knowledge-agent-execution-and-orchestration

## Module Structure 该域负责把一次用户意图推进为可持久恢复、可委派、可验证的 Agent 工作；会话状态和具体工具副作用由相邻领域提供，本域只编排它们。 ### Directory Layout - `packages/cli/src/agent/` — 无状态 Agent 外壳、决策循环、子代理和团队运行时 - `loop/` — Provider 回合、工具调度、完成门禁和持久化边界 - `subagents/` — 子代理配置、执行、恢复、结果采纳和 worktree 生命周期 - `teams/` — 团队成员、任务图、邮箱和状态投影 - `runtime/` — 本域使用的任务与定时调度器 - `packages/cli/src/goals/` — 持久 Goal 状态机、延续提示和完成验证记录 - `packages/cli/src/prompts/` — 系统提示组装与运行模式指令 - `packages/cli/src/services/CodeReviewService.ts` — 只读审查会话编排 - `packages/cli/src/services/SessionTaskService.ts` — 独立任务 Session 与隔离 worktree 创建 ### Key Entry Points - `Agent.chatStream()` in `packages/cli/src/agent/Agent.ts` — 各运行表面的统一 Agent 事件流入口 - `executeLoopGenerator()` in `packages/cli/src/agent/loop/executeLoopGenerator.ts` — Provider、工具和完成门禁的核心循环 - `createTaskTool()` in `packages/cli/src/tools/builtin/task/task.ts` — 子代理前台、后台与恢复入口 - `TeamRuntime.create()` in `packages/cli/src/agent/teams/TeamRuntime.ts` — 团队和成员启动入口 - `GoalStore` in `packages/cli/src/goals/GoalStore.ts` — Goal 持久状态机 - `SessionTaskService.createSessionTask()` in `packages/cli/src/services/SessionTaskService.ts` — 顶层任务 Session 创建入口 ## Gotchas - “Task”在本域有三套不同身份：`Task` 工具启动子代理，`TaskListManager` 保存 Agent 内检查清单，`SessionTaskService` 创建可在看板和调度器中运行的顶层 Session；三者不能共用 ID 或生命周期假设 (`packages/cli/src/tools/builtin/task/task.ts`, `packages/cli/src/tools/builtin/task/TaskListManager.ts`, `packages/cli/src/services/SessionTaskService.ts`) - Goal、任务列表和团队工具被声明为 `ToolKind.ReadOnly` 只表示工具权限分类，不表示无副作用；它们会写 sidecar、启动子代理或改变 durable 状态 (`packages/cli/src/tools/builtin/goal/goalTools.ts`, `packages/cli/src/tools/builtin/task/taskListTools.ts`, `packages/cli/src/tools/builtin/team/teamTools.ts`) - `Agent.executeTask()` 只是一次直接模型调用，不经过工具循环、完成门禁或 durable turn 协议；需要完整编排行为的调用方必须走 `chatStream()`/`chat()` (`packages/cli/src/agent/Agent.ts`, `packages/cli/src/agent/ExecutionEngine.ts`) - 子代理、团队成员和定时任务最终都复用 Session Runtime，但各自另有 sidecar；只修复主 Session transcript 不会自动修复这些编排状态 (`packages/cli/src/agent/subagents/AgentSessionStore.ts`, `packages/cli/src/agent/teams/TeamStore.ts`, `packages/cli/src/services/ScheduleStore.ts`) ## Architecture - `Agent` 保存模型与工具依赖，不保存 session ID 或消息历史；每次调用从 `ChatContext` 取状态，存在 Session 时再由 `SessionRuntime` 提供资源快照、持久化和活动轮次所有权 (`packages/cli/src/agent/Agent.ts`) - Goal 完成不是独立于 Agent loop 的按钮操作：`UpdateGoal complete` 只生成候选，loop 强制启动保留的 `goal-verification` 子代理，PASS 后才由宿主最终提交 (`packages/cli/src/agent/loop/goalCompletionVerification.ts`, `packages/cli/src/goals/GoalStore.ts`, `git:0eff1b2a`) - Agent Teams 是子代理运行时和共享任务列表之上的组合层，而不是另一套 Agent 实现；成员由 `BackgroundAgentManager` 执行，依赖图复用 `TaskListManager` (`packages/cli/src/agent/teams/TeamRuntime.ts`, `packages/cli/src/agent/teams/TeamTaskGraph.ts`) - 定时任务不直接执行模型请求；`TaskScheduler` 调用与 Web/CLI 任务相同的 `dispatchTask` 路径，因此继承顶层任务的准入、隔离、恢复和事件投影 (`packages/cli/src/agent/runtime/TaskScheduler.ts`, `packages/cli/src/services/SessionTaskService.ts`, `git:675b11bc`) - 子代理生命周期、团队事件、Goal 更新和任务列表更新最终汇入统一 Loop/Bus 事件，再由 TUI、Web、Headless 与 ACP 投影；新增状态不能只更新某一个界面 (`packages/cli/src/agent/loop/types.ts`, `packages/cli/src/agent/loop/toolDomainPolicy.ts`, `packages/cli/src/agent/teams/TeamEvents.ts`) ## Decisions - 编排状态按恢复边界拆成独立存储：对话走 Session JSONL，子代理走 agent sidecar，Goal、团队、任务列表和 schedule 各自原子写入；这样各状态机可以独立校验和恢复，代价是跨文件完成必须携带可核对 receipt (`packages/cli/src/agent/loop/conversationPersistence.ts`, `packages/cli/src/agent/subagents/AgentSessionStore.ts`, `packages/cli/src/goals/GoalStore.ts`) - 文件系统隔离由任务或子代理启动层创建并交给子 Session，Agent loop 只观察 workspace 转换和完成证据；不要在 loop 内另建 worktree 生命周期 (`packages/cli/src/services/SessionTaskService.ts`, `packages/cli/src/agent/subagents/SubagentWorktreeLifecycle.ts`, `packages/cli/src/agent/loop/toolDomainPolicy.ts`) ## Patterns - 所有可恢复的委派都先生成稳定 child Session ID，再把 lineage、owner 和配置快照持久化；完成结果通过同一身份回接父会话，避免按显示名称猜测归属 (`packages/cli/src/agent/loop/durableToolIdentity.ts`, `packages/cli/src/agent/subagents/AgentSessionStore.ts`) - 对外表面只消费事件和快照，不直接拥有编排状态；状态刷新或重启后的投影应重新读取 durable source，而不是缓存 UI 组件内部状态 (`packages/cli/src/agent/loop/types.ts`, `packages/cli/src/agent/teams/TeamRuntime.ts`, `packages/cli/src/services/ScheduleStore.ts`) ## Child Knowledge Nodes - `./decision-loop-and-completion/SKILL.md` — 进入时机：修改流式决策循环、工具回合、持久提交顺序、完成门禁、系统提示或结构化输出 - `./subagent-runtime/SKILL.md` — 进入时机：修改子代理发现、前后台执行、resume lineage、结果采纳、只读验证代理或隔离 worktree - `./agent-teams/SKILL.md` — 进入时机：修改团队创建、成员状态、共享任务图、邮箱通信、认领/完成流程或多端投影 - `./goals-tasks-and-scheduling/SKILL.md` — 进入时机：修改 Goal 状态机、Agent 任务列表、顶层任务 Session、定时触发或任务交付