Codegen Plan 本文档定义 soong-agent 的代码生成执行计划。Codex 或其他代码生成器按阶段实现项目, 并用测试用例逐步验收。 目标 Python distribution name: soong-agent. Python import package: agent_core. CLI 命令: agentcli. 第一版必须覆盖文档中定义的 ...

Codegen Contract 本章固定实现时容易分叉的接口、schema、内置工具和模板资源。 其他章节描述产品语义和行为；本章定义第一版代码生成必须落地的稳定契约。实现可以在内部增加字段或 helper, 但对外 API、持久化字段、tool canonical name 和错误码需要保持稳定。 Public SDK Shape Python distribution n...

Error Handling Provider 错误可重试, 见 Provider Adapter retry 策略. Tool 错误返回给模型处理. Hook 错误默认记录但不中断, 明确 deny 除外. Storage 写入失败通常不能继续, loop 标记 failed. Prompt 太长时尝试 compact; compact 后仍过长则 prompt_t...

Testing 第一版使用 pytest. 核心模块必须有单元测试. 重点覆盖: provider fake stream helper. runtime.start 支持 mode=”normal” / mode=”orchestrator”; orchestrator mode 的主 agent 是 Orchestrator, 不创建两层...

Config & File Layout Soong Agent 只使用 .soong-agent/ 目录名. 用户级根目录默认是 ~/.soong-agent. 可以通过环境变量 SOONG_AGENT_HOME 覆盖用户级根目录, 主要用于测试隔离. 正常运行未设置 SOONG_AGENT_HOME 时固定使用 ~/.soong-agent. 第一版只有用...

Task Board Task 是 orchestrator 模式下 Orchestrator 维护的内部执行 DAG. Task 是内部对象, 默认不展示给用户. Task 不使用 Markdown 文件. Task 不写项目级 task md 文件, 不扫描 .soong-agent/tasks/*.md, 不解析 Task frontmatter. Task 不...

Plan & Todo Plan / Task / Todo 的自然语言内容都主要由模型生成. core 通过 system prompt、tool instruction、tool schema 和内置模板工具引导模型产出内容形态. 三者的区别不在内容是否由模型生成, 而在持久化位置、可见性、机器字段、调度语义和上下文进入方式. Todo Todo 只通过...

Multi Agent 采用父子 agent 树. 同一个 session 内, main agent、Orchestrator、sub agent、fork agent 使用同一个 session_id. 不同 agent / run 必须用不同 agent_id / run_id 区分. sub agent 的完整过程必须持久化到同一个 session 的 nodes...

Hooks Hook 配置参考 Claude Code / Trae 风格, 使用用户级 JSON: ${SOONG_AGENT_HOME}/hooks.json 默认正常运行时等价于 ~/.soong-agent/hooks.json. 不存在项目级 hooks. runtime 不读取 <project>/.s...

MCP MCP 配置只放用户级: ${SOONG_AGENT_HOME}/mcp.json MCP server 属于用户信任的外部能力, 项目不直接声明 MCP server. 用户级 config 可以启用/禁用某些已存在的 MCP tools. MCP server 加载采用 lazy connect: - SDK ...