Kimi Code CLI 后台任务枚举指南TaskList 工具的原理、参数与实战【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读本文聚焦 Kimi Code CLIkimi-cli中负责枚举后台任务的TaskList工具完整解读其官方描述文档 list.md 中的设计意图与使用准则并结合 工具实现源码、后台任务管理器 与 测试用例 剖析其底层原理。读完本文你将掌握 TaskList 的参数语义active_only、limit、输出格式、与TaskOutput/TaskStop的协作流程以及如何在上下文压缩context compaction后可靠地重建后台任务视图。一、TaskList 在后台任务体系中的位置1.1 后台任务从哪里来Kimi Code CLI 的通用后台任务系统支持两类任务见 models.py 中的TaskKindbash 任务通过Shell工具以run_in_backgroundtrue启动的长时命令构建、测试、watcher、服务器等调用链为Shell._run_in_background→BackgroundTaskManager.create_bash_task见 shell 工具实现agent 任务通过Agent工具以run_in_backgroundtrue委派给子代理执行的独立子任务调用链为Agent._run_in_background→BackgroundTaskManager.create_agent_task见 agent 工具实现。TaskList正是这套体系的枚举入口——它负责回答当前会话里还有哪些后台任务存活这一基础问题。1.2 任务状态的持久化模型每个后台任务在会话上下文目录下的tasks/task_id/中持久化四类 JSON 文件加一个日志文件见 store.py文件内容spec.json任务规格id、kind、session_id、description、command、timeout_s、kind_payload 等runtime.json运行时状态status、worker_pid、exit_code、heartbeat_at、timed_out、failure_reason 等control.json控制信息kill_requested_at、kill_reason、forceconsumer.json消费进度last_seen_output_size、last_viewed_atoutput.log任务完整输出日志TaskList读取的是这些持久化文件合并后的TaskViewspec runtime control consumer因此即使 Agent 进程自身经历过上下文压缩或会话恢复只要任务文件仍在枚举结果依然可靠。二、TaskList 的设计意图何时使用list.md开篇明确了工具职责List background tasks from the current session.即枚举当前会话的后台任务。文档进一步给出了典型触发场景Use this when you need to re-enumerate which background tasks still exist, especially after context compaction or when you are no longer confident which task IDs are still active.也就是说当发生以下情况时应当调用 TaskList 重新清点任务上下文压缩context compaction之后——历史对话被压缩任务 ID 等细节可能从上下文中丢失对哪些任务 ID 仍处于活跃状态失去把握时——例如会话被恢复、子代理切换或长时间对话后。这一设计与 Agent 系统提示词中的指引完全一致src/kimi_cli/agents/default/system.md中明确要求 root 代理在需要时使用TaskList重新枚举活跃任务尤其是在上下文压缩之后。2.1 四条使用准则原文完整继承list.md给出了四条必须遵守的准则它们是本文档的核心约束优先使用默认的active_onlytrue除非你确实需要查看已完成completed或已失败failed的任务在确定正确的任务 ID 之后使用TaskOutput深入检查单个任务——TaskList 只负责列出不负责细查不要猜测哪些任务仍在运行——当你可以直接调用本工具时猜测是毫无必要的本工具是只读的在 plan mode计划模式下使用是安全的——它不会修改任何任务状态。第 3 条尤为重要它把枚举任务从记忆任务中解放出来Agent 永远不需要依赖不完整的上下文去猜任务 ID。三、TaskList 参数详解TaskList的参数定义在 工具实现 的TaskListParams中共两个字段class TaskListParams(BaseModel): active_only: bool Field( defaultTrue, descriptionWhether to list only non-terminal background tasks., ) limit: int Field( default20, ge1, le100, descriptionMaximum number of tasks to return., )参数类型默认值取值范围语义active_onlybooltrue—仅列出非终止状态non-terminal的任务设为false时连同已完成/已失败/已杀死/已丢失的任务一并列出limitint201 ~ 100ge1, le100最多返回的任务条数从源码可以看出active_onlytrue是经过深思熟虑的默认值。日常场景中 Agent 关心的几乎总是还在跑的任务把已完成任务混入只会增加噪声、浪费 tokenlimit被 pydantic 硬约束在 1~100 之间。传 0 或负数会被参数校验直接拒绝传超过 100 的值会被钳制——这保证了枚举结果始终可控传入非法参数时工具会在参数校验阶段即返回错误不会触达任务存储层。此外TaskList与TaskOutput/TaskStop一样通过_ensure_root()检查调用者角色见 工具实现def _ensure_root(runtime: Runtime) - ToolError | None: if runtime.role ! root: return ToolError( messageBackground tasks can only be managed by the root agent., briefBackground task unavailable, ) return None只有 root 代理可以枚举后台任务。子代理subagent调用 TaskList 会得到明确的错误提示Background tasks can only be managed by the root agent.。这同样适用于TaskOutput与TaskStop是后台任务系统root 专属权限模型的一部分。四、内部实现原理从参数到结果4.1 调用链一次TaskList调用的完整链路为TaskList.__call__ └─ _ensure_root(runtime) # 角色校验 └─ list_task_views(manager, active_only, limit) # src/kimi_cli/background/summary.py └─ manager.list_tasks(limitNone) # src/kimi_cli/background/manager.py └─ store.list_views() # 读取全部任务并合并视图、按更新时间倒序 ├─ 过滤非终止状态active_onlytrue 时 └─ views[:limit] # 截断 └─ format_task_list(views, active_only) # 生成文本输出 └─ BackgroundTaskDisplayBlock(...) # 生成 UI 展示块其中 list_task_views 的实现为def list_task_views(manager, *, active_onlyTrue, limit20): views manager.list_tasks(limitNone) if active_only: views [view for view in views if not is_terminal_status(view.runtime.status)] return views[:limit]注意这里的一个细节manager.list_tasks(limitNone)先取回全部任务再在 Python 层按状态过滤、最后截断。任务列表的排序发生在 store.list_views 中——按runtime.updated_at兜底用spec.created_at倒序排列即最近有动静的任务排在最前这恰好符合 Agent 排查时的直觉先看到最可能仍在运行/刚结束的任务。4.2 何为活跃状态机视角models.py 定义了完整的任务状态机type TaskStatus Literal[ created, starting, running, awaiting_approval, completed, failed, killed, lost, ] TERMINAL_TASK_STATUSES (completed, failed, killed, lost)非终止活跃状态created、starting、running、awaiting_approval——其中awaiting_approval表示任务正在等待批准例如后台 agent 需要审批时它虽未在执行但仍属于活跃终止状态completed、failed、killed、lost——其中lost用于 worker 心跳过期或进程丢失的异常情况见 manager.recover。active_onlytrue即过滤掉所有终止状态任务active_onlyfalse则全部返回。4.3 返回格式工具返回的文本由 format_task_list 生成头部会根据active_only区分active_background_tasks: 2 # active_onlytrue 时 [1] task_id: b4444444 kind: bash status: running description: build the project command: make build exit_code: null [2] task_id: b5555555 kind: agent status: awaiting_approval description: review PR #12 agent_id: a-xxxx subagent_type: default或active_onlyfalse时的background_tasks: N头部。每条任务条目包含的字段来自 format_task字段说明task_id任务唯一 IDbash-xxx/agent-xxx前缀kindbash或agentstatus当前状态见 4.2 状态机description创建任务时提供的简短描述agent_id/subagent_type仅 agent 任务出现来自kind_payloadcommand仅 bash 任务且include_commandtrue时出现exit_code已结束时出现reason失败/被杀死等原因failure_reason同时工具还会返回BackgroundTaskDisplayBlock展示块task_id、kind、status、description用于在终端 UI 中渲染任务卡片。五、与 TaskOutput / TaskStop 的协作流程TaskList 是后台任务管理工具链的第一环文档明确要求它与另外两个工具配合TaskList枚举 → 拿到 task_id → TaskOutput深查 / TaskStop取消5.1 TaskOutput单任务深查output.md 明确了其定位在Shell(run_in_backgroundtrue)之后当需要检查进度或显式等待完成时使用。它支持默认非阻塞返回当前状态与输出快照retrieval_status: not_ready表示任务仍在运行blocktrue时最多等待timeout默认 30s范围 0~3600直到任务结束或超时返回结构化元数据 固定大小输出预览32 KiB见常量TASK_OUTPUT_PREVIEW_BYTESoutput_path完整日志路径预览被截断时output_truncated: true使用ReadFile按output_path分页读取完整日志。因此官方建议的读取路径是TaskList 先定位任务 → TaskOutput 拿快照 → ReadFile 分页读全量日志。5.2 TaskStop任务取消stop.md 强调仅当必须取消任务时才使用。取消是破坏性操作可能留下部分副作用若任务已自然结束TaskStop 只会返回其当前状态。并且 TaskStop 在 plan mode 下被显式禁用返回Blocked in plan mode而 TaskList 不受此限制——这正是文档强调 TaskList 只读且 plan mode 安全的原因。5.3 用户侧的分工对交互式 shell 中的人类用户后台任务统一通过/task斜杠命令管理见 bash.mdAgent 不应虚构/task list之类的子命令而TaskList/TaskOutput/TaskStop是供给 Agent 自身的工具调用。六、自动化完成通知与 TaskList 的关系一个常见的疑问是既然任务完成时会自动推送通知为何还需要 TaskList答案在于两者的触发时机不同。系统在任务到达终止状态时会由 publish_terminal_notifications 生成task.completed/task.timed_out/task.failed/task.killed/task.lost等事件通知带dedupe_key去重。但上下文压缩后历史通知可能已从上下文中移除多个任务并行时Agent 可能只记得部分任务的 ID通知去重后重复事件不会再次推送见completion_event的注释语义。在这些场景下TaskList 提供的是按需、实时、确定性的枚举能力而不是依赖记忆中的通知。二者是互补关系通知是主动推送TaskList 是被动查询。七、源码与测试佐证7.1 实现文件索引关注点文件工具类与参数定义src/kimi_cli/tools/background/init.py工具描述文档list.md、output.md、stop.md任务视图格式化src/kimi_cli/background/summary.py任务状态与模型src/kimi_cli/background/models.py任务持久化存储src/kimi_cli/background/store.py任务生命周期管理src/kimi_cli/background/manager.pyShell 后台启动入口src/kimi_cli/tools/shell/init.py7.2 测试用例印证tests/tools/test_background_tools.py#L130-L149 的test_task_list_returns_active_tasks验证了核心语义同时存在一个running任务与一个completed任务时active_onlytrue只返回 1 个活跃任务且输出头部为active_background_tasks: 1同文件L302附近的用例以active_onlyFalse, limit1验证全量列举与 limit 截断tests/tools/test_tool_schemas.py#L202-L206 校验了TaskList的 JSON Schema 中active_only默认值为truetests/tools/test_tool_descriptions.py#L200-L209 断言工具描述逐字包含list.md中的准则原文如 Prefer the defaultactive_onlytrue...确保运行时加载的描述与文档一致。这些测试直接证明了TaskList 的默认只列活跃任务行为是被测试锁定的契约而非实现细节的偶然产物。八、实战场景上下文压缩后重建任务视图综合以上分析一个典型的实战流程如下压缩前通过Shell(run_in_backgroundtrue, descriptionrun integration tests)启动了测试任务随后进入长时间多轮对话触发压缩上下文被压缩之前的任务 ID 与通知细节从上下文中消失重新枚举调用TaskList(active_onlytrue, limit20)得到当前会话所有非终止任务及其task_id、status、description定向深查对仍处于running的任务调用TaskOutput(task_id..., blockfalse)获取输出快照若需要完整日志再按返回的output_path用ReadFile分页读取必要时取消若确认某个任务不再需要再调用TaskStop(task_id..., reason...)注意其 plan mode 禁用限制与破坏性。整个过程只读查询TaskList TaskOutput 的默认路径不改变任何任务状态即使处于 plan mode 也可安全执行只有显式调用 TaskStop 才会产生副作用。结语TaskList虽是一个小工具却承担着后台任务体系的关键职责它把任务存续状态从易失的对话上下文中剥离出来变成可随时确定性查询的事实来源。理解它的参数语义active_only默认过滤终止状态、limit1~100 硬约束、输出格式active_background_tasks头部 结构化字段、权限模型仅 root 代理可用以及与TaskOutput/TaskStop的分工是正确使用 Kimi Code CLI 后台任务能力、在长会话与上下文压缩场景下保持任务可控的前提。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考