echovic 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()inpackages/cli/src/agent/Agent.ts— 各运行表面的统一 Agent 事件流入口executeLoopGenerator()inpackages/cli/src/agent/loop/executeLoopGenerator.ts— Provider、工具和完成门禁的核心循环createTaskTool()inpackages/cli/src/tools/builtin/task/task.ts— 子代理前台、后台与恢复入口TeamRuntime.create()inpackages/cli/src/agent/teams/TeamRuntime.ts— 团队和成员启动入口GoalStoreinpackages/cli/src/goals/GoalStore.ts— Goal 持久状态机SessionTaskService.createSessionTask()inpackages/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、定时触发或任务交付