Completion Audit This file records the current completion evidence for doc/01 through doc/22. It is intentionally evidence-oriented: each row points to implementation areas, tests, and final valid...

Codegen Plan 本文档是根据前面各章节生成 soong-agent 项目代码的执行计划。目标是让 Codex 或其他代码生成器可以按阶段实现完整项目, 并用测试用例逐步验收。 目标 Python distribution name: soong-agent. Python import package: agent_core. CLI 命令: soong-age...

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

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...