README Copy Section

产品需求文档反推总览

目标：基于现有源码结构，反推出这套 AI 编程产品的核心需求与产品设计，而不是复述实现细节。

文档原则 Copy Chapter

- 只写需求、目标、交互、约束、边界条件
- 不直接泄露原始源码实现
- 如需描述机制，只用自然语言或 Python 风格伪代码
- 文档站在产品经理 / 系统设计者视角，回答“为什么需要这个能力”

文档结构 Copy Chapter

1. 00-product-overview.md
- 产品定位
- 核心用户
- 核心问题
- 顶层系统能力

2. 01-system-prompt-and-orchestration.md
- 系统提示词层的需求
- 为什么要做动态拼装
- 为什么要做角色化 agent orchestration

3. 02-tools-permissions-and-execution.md
- 工具系统需求
- 权限系统需求
- Hook / 执行链路 / 安全要求

4. 03-skills-plugins-mcp.md
- Skills 需求
- Plugins 需求
- MCP 集成需求

5. 04-memory-and-session.md
- 记忆系统需求
- Session 管理需求
- 压缩、归档、恢复、摘要需求

6. 05-commands-ui-and-operator-experience.md
- 命令系统需求
- TUI / 状态栏 / 任务可视化需求
- 操作者体验

7. 06-verification-and-quality.md
- 验证 agent 需求
- 质量保证需求
- 失败报告与可追溯性需求

8. 07-architecture-map.md
- 按模块汇总产品能力地图
- 用于快速定位需求归属

9. 08-agent-runtime-loop.md
- 主循环规格
- 多轮执行与终止条件

10. 09-message-model-and-state.md
- 消息模型
- 会话与状态对象

11. 10-context-management.md
- 上下文预算
- 压缩与恢复

12. 11-task-model.md
- 任务模型
- 后台执行与通知

13. 12-workspace-and-isolation.md
- 工作区隔离策略
- 角色与写权限边界

14. 13-failure-recovery.md
- 失败处理
- 恢复机制

15. 14-configuration-system.md
- 配置来源与优先级
- Agent / Session 配置项

16. 15-mvp-scope.md
- Python MVP 范围
- 哪些先做，哪些后置

17. 16-python-implementation-notes.md
- Python 版实现建议
- 模块划分与里程碑

阅读建议 Copy Chapter

如果你想快速理解这套产品：

1. 先看 00-product-overview.md
2. 再看 04-memory-and-session.md
3. 再看 02-tools-permissions-and-execution.md
4. 最后看 03-skills-plugins-mcp.md 和 06-verification-and-quality.md

---

00 Product Overview Copy Section

00. 产品总览需求文档

1. 产品定义 Copy Chapter

这是一款面向软件工程任务的交互式 AI 执行系统。它不是单纯的聊天机器人，也不是只会调用几个工具的脚本外壳，而是一套把推理、工具、权限、任务拆解、记忆、扩展机制与用户交互统一起来的产品系统。

2. 产品目标 Copy Chapter

产品需要满足以下目标：

1. 帮助用户完成真实的软件工程任务，而不只是提供建议
2. 在执行过程中保持安全、可控、可恢复
3. 让复杂任务可以分解、委派、验证、追踪
4. 让系统可以扩展新的技能、插件与外部工具能力
5. 让长期使用形成可积累的记忆和工作习惯

3. 核心用户 Copy Chapter

3.1 主要用户 Copy Section

3.2 用户的核心诉求 Copy Section

4. 产品要解决的核心问题 Copy Chapter

4.1 普通聊天模型的问题 Copy Section

4.2 简单 Agent 的问题 Copy Section

因此，本产品的需求本质上是在解决：

如何把“模型 + 工具”升级成一个可用、可控、可扩展、可产品化的软件工程执行系统。

5. 顶层产品能力 Copy Chapter

根据源码结构反推，这套产品至少需要以下一级能力：

1. 系统提示词编排能力
2. 工具发现、执行与治理能力
3. 多 Agent 调度能力
4. Skills / Plugins / MCP 扩展能力
5. Memory / Session 管理能力
6. 命令系统与交互界面能力
7. 任务与后台执行能力
8. 验证与质量保证能力
9. Telemetry / Transcript / 可追溯能力

6. 顶层非功能需求 Copy Chapter

6.1 安全性 Copy Section

6.2 可恢复性 Copy Section

6.3 可扩展性 Copy Section

6.4 成本控制 Copy Section

7. 产品价值主张 Copy Chapter

如果从需求层面概括，这套产品的价值主张不是“回答更聪明”，而是：

- 更稳定地执行任务
- 更安全地调用能力
- 更可控地使用 AI
- 更容易把 AI 接入真实工程工作流

8. 一个产品经理视角下的总需求句 Copy Chapter

可以用一句话总结：

用户需要的不是一个会聊天的模型，而是一个能够在真实工程环境中持续推进任务、遵守约束、调用工具、拆分工作、保留上下文并可被验证的 AI 软件工程操作系统。

---

01 System Prompt And Orchestration Copy Section

01. 系统提示词与 Agent 编排需求文档

1. 系统提示词为什么不是一段固定文案 Copy Chapter

从源码结构可以反推，这个产品要求系统提示词具备“动态拼装”能力，而不是固定模板。

需求原因 Copy Section

2. 系统提示词层的核心需求 Copy Chapter

2.1 基础身份定义 Copy Section

2.2 做任务规范 Copy Section

这不是“风格偏好”，而是稳定性需求。

2.3 风险动作规范 Copy Section

2.4 工具使用语法 Copy Section

3. 动态区块需求 Copy Chapter

系统提示词至少需要支持以下动态区块：

1. 环境信息
2. 当前语言偏好
3. 输出风格
4. 会话局部规则
5. 记忆内容
6. MCP 指令
7. scratchpad / 临时工作区规则
8. token budget 提示

4. 为什么要有 Prompt cache boundary Copy Chapter

如果每次请求都完全重造提示词，会带来两个问题：
- 成本上升
- 缓存命中下降

因此产品需要把系统提示词分成：
- 稳定前缀
- 动态后缀

这样才能兼顾灵活性与成本控制。

5. Agent 编排的需求本质 Copy Chapter

系统需要支持把复杂任务拆给不同角色，而不是只依赖一个万能主 agent。

必须支持的角色至少包括 Copy Section

需求原因 Copy Section

如果用一个 agent 混合承担所有角色，稳定性会下降。

6. 子 Agent 设计需求 Copy Chapter

6.1 fork 子任务 Copy Section

6.2 background 子任务 Copy Section

6.3 isolation 子任务 Copy Section

7. Prompt 写给子 Agent 的需求 Copy Chapter

主 agent 必须能够给子 agent 交接充分背景，不能只丢一个模糊命令。产品层面要明确要求：
- 写清任务目标
- 写清已知背景
- 写清约束
- 写清期望输出

8. 伪代码表达 Copy Chapter

class SystemPromptBuilder:
    def build(self, env, tools, memory, output_style, language, mcp_info):
        static_sections = [
            intro(),
            system_rules(),
            task_rules(),
            action_safety(),
            tool_usage_rules(),
        ]
        dynamic_sections = [
            env_section(env),
            language_section(language),
            output_style_section(output_style),
            memory_section(memory),
            mcp_section(mcp_info),
        ]
        return static_sections + dynamic_sections

9. 产品经理视角下的总需求句 Copy Chapter

系统提示词层的核心需求，是把产品规则、工具语法、会话状态和环境约束组装成一套可动态生成、可缓存优化、可支持多角色协作的运行时控制平面。

---

02 Tools Permissions And Execution Copy Section

02. 工具、权限与执行链需求文档

1. 为什么工具系统是产品核心 Copy Chapter

如果模型不能操作环境，它只是建议生成器。这个产品的目标是帮助用户推进真实工程任务，因此必须具备正式的工具系统。

2. 工具系统需求 Copy Chapter

2.1 基础工具能力 Copy Section

2.2 工具使用规范 Copy Section

3. 权限系统需求 Copy Chapter

3.1 用户控制边界 Copy Section

3.2 权限决策来源 Copy Section

3.3 被拒后的行为要求 Copy Section

4. 执行链路需求 Copy Chapter

工具执行不能是“模型决定 -> 直接运行”。产品需要一条正式执行链：

1. 找到工具
2. 校验输入结构
3. 做额外 validateInput
4. 执行 PreToolUse hooks
5. 做权限决策
6. 真正执行工具
7. 记录 telemetry
8. 执行 PostToolUse hooks
9. 格式化结果回流给模型

5. 为什么需要 Hook Copy Chapter

Hook 的需求本质是：
- 让组织规则进入运行时
- 让系统可以插入额外检查
- 让工具调用具备动态治理能力

Hook 至少要支持的行为 Copy Section

6. 为什么输入校验是必需的 Copy Chapter

模型本身会生成错误参数，因此产品必须在执行层拦住：
- schema 不合法
- 参数越界
- 缺字段
- 类型错误

7. shell 类工具的特殊需求 Copy Chapter

shell 工具的风险高于读写文件类工具，因此需要：
- 更严格的权限策略
- 可能的前置分类器检查
- 更强的审计能力

8. 工具执行结果的产品要求 Copy Chapter

工具执行结果不仅要“返回成功/失败”，还要满足：
- 可读
- 可追踪
- 能被后续 Hook 处理
- 能成为 transcript 的一部分

9. 伪代码表达 Copy Chapter

def execute_tool(tool_name, raw_input, context):
    tool = find_tool(tool_name)
    validated = schema_validate(tool, raw_input)
    validated = run_custom_validation(tool, validated)
    hook_result = run_pre_hooks(tool, validated, context)
    decision = resolve_permission(hook_result, context)
    if decision == 'deny':
        return denied_result()
    final_input = maybe_update_input(validated, hook_result)
    output = tool.call(final_input)
    run_post_hooks(tool, final_input, output, context)
    return output

10. 产品经理视角下的总需求句 Copy Chapter

工具系统必须从“可调用”升级到“可治理”：既要让模型拥有执行能力，也要在执行前后经过校验、权限、Hook、审计与结果回流，确保整个过程安全、稳定、可追踪。

---

03 Skills Plugins Mcp Copy Section

03. Skills、Plugins 与 MCP 需求文档

1. 为什么产品不能只靠内置能力 Copy Chapter

如果产品所有能力都硬编码在主程序里，会遇到几个问题：
- 难以扩展
- 难以适配不同团队
- 难以承载领域知识
- 难以形成生态

因此，这套产品必须支持可扩展能力面。

2. Skills 的需求本质 Copy Chapter

Skill 不是普通帮助文档，而是一种可复用的工作流能力包。

2.1 Skill 需要承载什么 Copy Section

2.2 为什么 Skill 必须是 first-class primitive Copy Section

3. Skill 的产品需求 Copy Chapter

1. 系统要能列出当前可用技能
2. 模型要能在合适时调用技能
3. skill 内容要能注入会话
4. skill 要能带 frontmatter 元信息
5. skill 可以约束 allowed-tools
6. skill 需要避免重复加载

4. Plugin 的需求本质 Copy Chapter

Plugin 的角色不是给程序员加脚本，而是为模型注入新的行为表面。

Plugin 至少要支持 Copy Section

5. 为什么要有 MCP Copy Chapter

MCP 的需求本质是：
- 用统一协议接入外部工具
- 让产品获得更多外部能力
- 让工具与说明一起进入运行时

MCP 需要满足 Copy Section

6. 为什么模型需要“知道扩展能力存在” Copy Chapter

很多系统扩展做不起来，不是因为没有插件，而是模型根本不知道：
- 有哪些技能
- 什么时候该用
- 扩展工具怎么使用

因此产品必须把这些扩展能力转化成模型可感知的提示信息。

7. Plugin / Skill / MCP 三者关系 Copy Chapter

Skill Copy Section

Plugin Copy Section

MCP Copy Section

三者叠加后，产品才能具备生态能力。

8. 伪代码表达 Copy Chapter

class ExtensionRuntime:
    def load_skills(self, cwd):
        return discover_skill_packages(cwd)
    def load_plugins(self):
        return discover_plugins()
    def connect_mcp_servers(self, configs):
        return [connect(server) for server in configs]
    def expose_capabilities_to_model(self, skills, plugins, mcp_servers):
        return build_runtime_capability_listing(skills, plugins, mcp_servers)

9. 产品经理视角下的总需求句 Copy Chapter

产品必须提供一套可扩展运行时：Skill 负责封装工作流知识，Plugin 负责扩展命令与能力表面，MCP 负责接入外部工具与说明，三者共同让系统具备持续生长的能力。

---

04 Memory And Session Copy Section

04. 记忆与会话系统需求文档

1. 为什么需要记忆系统 Copy Chapter

如果产品只靠当前窗口上下文工作，会出现几个问题：

- 用户长期偏好无法沉淀
- 项目背景每次都要重新解释
- 复杂任务容易因上下文压缩而丢失关键事实
- 系统无法逐步形成“协作连续性”

因此，这个产品需要一个多层级记忆系统。

2. 记忆系统的产品目标 Copy Chapter

1. 保存长期有效的用户偏好和协作约束
2. 保存项目级背景信息
3. 在上下文压缩后仍能恢复关键事实
4. 支持会话恢复与后续继续执行
5. 为子任务和后台任务提供必要的上下文继承

3. 记忆层级反推 Copy Chapter

从目录结构与调用链可以推断，产品至少需要以下记忆层级：

3.1 用户级记忆 Copy Section

3.2 项目级记忆 Copy Section

3.3 会话级记忆 Copy Section

3.4 子任务级记忆 Copy Section

4. 记忆系统的核心需求 Copy Chapter

4.1 持久化需求 Copy Section

4.2 注入需求 Copy Section

4.3 压缩需求 Copy Section

4.4 恢复需求 Copy Section

5. Session 管理需求 Copy Chapter

5.1 会话身份 Copy Section

5.2 会话摘要 Copy Section

5.3 会话转录 Copy Section

6. 为什么记忆不能等于“把所有历史都塞进去” Copy Chapter

产品层面必须避免一种错误思路：把完整历史无脑拼进上下文。

这样会导致：
- 成本上升
- 注意力稀释
- 有效信息被噪声淹没
- 子任务污染主线程

更合理的需求是：

记忆应该是可选择地提取、压缩、恢复和注入，而不是无节制堆积。

7. fork 与记忆的需求关系 Copy Chapter

从多 agent 设计看，fork 子任务有两个特殊需求：

1. 继承足够的上下文来完成任务
2. 又不能把中间噪声带回主线程

因此系统需要：
- 支持父子上下文有边界地继承
- 支持子任务输出被总结，而不是原样回灌
- 支持 prompt cache 友好的上下文复用

8. 记忆系统的伪代码表达 Copy Chapter

class MemorySystem:
    def load_user_memory(self, user_id):
        ...
    def load_project_memory(self, project_root):
        ...
    def load_session_summary(self, session_id):
        ...
    def build_runtime_context(self, user_memory, project_memory, session_summary):
        return merge_relevant_context(user_memory, project_memory, session_summary)
    def compact_if_needed(self, messages):
        if context_budget_low(messages):
            return summarize(messages)
        return messages

9. 产品经理视角下的总需求句 Copy Chapter

这套产品必须拥有一个分层记忆系统：它既能保存长期偏好与项目背景，又能在上下文预算受限时压缩历史，并在任务恢复、子任务继承和长期协作中重新注入关键事实。

---

05 Commands Ui And Operator Experience Copy Section

05. 命令系统、界面与操作者体验需求文档

1. 为什么命令系统是一级产品能力 Copy Chapter

这类产品不是单轮对话工具，而是一个长期运行的操作者界面。因此，命令系统不是附属功能，而是操作面板。

2. 命令系统需求 Copy Chapter

产品需要支持用户快速控制以下对象：
- memory
- permissions
- hooks
- mcp
- skills
- tasks
- review / plan / status
- 输出风格
- model
- sandbox
- 插件管理

3. 命令系统的产品目标 Copy Chapter

1. 降低复杂能力的学习成本
2. 提供清晰的系统控制入口
3. 把高级功能从自然语言里解耦出来
4. 为插件和技能提供统一入口面

4. UI / TUI 的核心需求 Copy Chapter

4.1 任务可见性 Copy Section

4.2 状态反馈 Copy Section

4.3 结构化展示 Copy Section

5. 为什么操作者体验是核心需求 Copy Chapter

如果系统很强，但用户看不懂当前状态，就会产生：
- 不信任
- 不敢授权
- 不知道何时干预
- 不知道下一步怎么控制

因此产品必须让操作者感觉：
- 任务是透明的
- 系统是可控的
- 能力是可发现的

6. 后台任务与通知需求 Copy Chapter

一旦支持 background agents，系统就必须支持：
- 后台任务注册
- 进度更新
- 完成通知
- 输出文件查看
- 必要时 kill / cancel

7. 命令系统的扩展需求 Copy Chapter

命令系统还必须允许：
- 内建命令
- 插件命令
- skill 入口
- 条件启用的功能命令

8. 产品经理视角下的总需求句 Copy Chapter

这套产品不仅要有能力，还要有可操作性。命令系统与界面层的目标，是把复杂的 AI 运行时变成用户可发现、可控制、可追踪的操作者体验。

---

06 Verification And Quality Copy Section

06. 验证与质量保证需求文档

1. 为什么“做完”不等于“完成” Copy Chapter

在 AI 编程产品里，最大的风险之一是：模型会把“代码改了”误当成“任务完成了”。

因此，这个产品必须把“验证”设计成一个独立能力，而不是可有可无的附属步骤。

2. 验证系统的产品目标 Copy Chapter

1. 独立检查实现是否真的可用
2. 防止只读代码就宣称完成
3. 防止 happy path 偏见
4. 让验证结果带证据而不是口头判断

3. 验证 Agent 的需求 Copy Chapter

3.1 独立角色 Copy Section

3.2 默认心智模型 Copy Section

3.3 必须禁止的行为 Copy Section

3.4 必须支持的检查类型 Copy Section

4. 输出格式需求 Copy Chapter

验证结果必须满足：
- 有检查项标题
- 有实际执行命令
- 有真实输出
- 有 PASS / FAIL / PARTIAL 结果
- 最后有统一 verdict

5. 为什么需要 adversarial probe Copy Chapter

只验证 happy path 会导致大量问题漏检。因此系统要要求验证阶段主动尝试：
- 边界输入
- 并发场景
- 空输入 / 非法输入
- 重复请求
- 不存在资源引用

6. 为什么验证必须可追溯 Copy Chapter

如果验证没有命令和输出，用户无法判断：
- 到底测没测
- 测了什么
- 失败在哪

因此，质量系统必须要求“证据化验证”。

7. 质量保证不只是测试 Copy Chapter

这套产品的质量保证包括：
- 提示词中对诚实汇报的要求
- 验证角色的独立存在
- 执行链的日志与 transcript
- 失败可追踪
- 结果可复盘

8. 伪代码表达 Copy Chapter

class VerificationRunner:
    def verify(self, task, changed_files, context):
        checks = build_verification_plan(task, changed_files)
        results = []
        for check in checks:
            cmd = check.command
            output = run(cmd)
            results.append(evaluate(output, check.expectation))
        return summarize_verdict(results)

9. 产品经理视角下的总需求句 Copy Chapter

产品必须把验证设计成独立、对抗性、证据化的质量系统：它不依赖实施者自我声明，而是通过命令、输出与统一 verdict 来证明任务是否真正完成。

---

07 Architecture Map Copy Section

07. 架构能力地图

1. 顶层能力区 Copy Chapter

A. 入口层 Copy Section

B. Prompt 编排层 Copy Section

C. 工具执行层 Copy Section

D. Agent 调度层 Copy Section

E. 扩展生态层 Copy Section

F. Memory / Session 层 Copy Section

G. 任务与后台层 Copy Section

H. 质量保证层 Copy Section

I. 界面与操作者体验层 Copy Section

2. 跨层系统性要求 Copy Chapter

2.1 安全要求跨层存在 Copy Section

2.2 上下文管理跨层存在 Copy Section

2.3 产品化要求跨层存在 Copy Section

3. 反推出来的组织设计 Copy Chapter

从架构地图可以反推出，这不是一个“以模型为中心”的产品，而是一个“以运行时操作系统为中心”的产品。

模型只是其中一个核心部件，真正的产品能力来自这些部分的组合：

- prompt assembly
- tool execution pipeline
- permission governance
- agent orchestration
- extension surface
- memory/session management
- verification and traceability

4. 产品经理视角下的总需求句 Copy Chapter

该产品的架构应被理解为一张能力地图：每一层都不是独立存在的功能点，而是在共同支撑一个目标——让 AI 在真实工程环境中成为一个可控、可扩展、可追踪的执行系统。

---

08 Agent Runtime Loop Copy Section

08. Agent 运行时主循环规格

目标：定义 Python 版本实现时最核心的运行时循环。该文档不是源码解释，而是实现规格。

1. 设计目标 Copy Chapter

主循环必须满足以下目标：

1. 能持续推进任务，而不是只做一次回答
2. 能在每轮后根据工具结果重新决策
3. 能在权限阻断、上下文压缩、工具失败时继续可控运行
4. 能触发子 agent、后台任务、验证任务
5. 能生成可追踪的消息流与 transcript

2. 主循环的输入 Copy Chapter

一次主循环至少需要以下输入：

- messages: 当前消息序列
- system_prompt: 已组装完成的系统提示词
- tool_registry: 当前可用工具集合
- tool_use_context: 执行上下文（cwd、权限、session、任务状态）
- memory_context: 注入后的记忆内容
- user_context: 用户态上下文
- system_context: 系统态上下文
- can_use_tool: 权限判断函数
- max_turns: 最大回合数
- task_budget: 本轮任务预算（可选）

3. 主循环的输出 Copy Chapter

主循环每轮可能产出：

- 普通 assistant 消息
- tool_use 请求
- tool_result 回写
- progress 消息
- compact / summary 边界消息
- 子任务启动事件
- terminal state（完成 / 失败 / 中断）

4. 循环状态 Copy Chapter

实现时必须维护显式状态，而不是散落在局部变量中。

建议状态字段：

class QueryState:
    messages: list
    turn_count: int
    auto_compact_tracking: dict | None
    pending_tool_summary: object | None
    stop_hook_active: bool
    max_output_recovery_count: int
    has_attempted_reactive_compact: bool
    transition_reason: str | None

5. 标准单轮流程 Copy Chapter

每轮执行顺序建议固定为：

1. 预处理当前消息
2. 计算 token / budget 状态
3. 调用模型
4. 解析返回内容
5. 如有工具调用，进入工具执行链
6. 将工具结果追加回消息
7. 如需压缩，执行 compact
8. 决定是否继续下一轮
9. 达到终止条件则返回 terminal state

6. 终止条件 Copy Chapter

至少支持以下终止条件：

- 模型明确结束任务
- 达到 max_turns
- 用户中断
- 权限阻断且无可行替代方案
- 发生不可恢复异常
- 任务被后台化或移交

7. 工具调用处理要求 Copy Chapter

如果模型返回一个或多个工具调用：

- 必须按顺序或编排策略执行
- 必须将每个 tool_result 写回消息流
- 如果工具失败，失败信息也必须结构化回写
- 严禁只在 UI 层显示，不回写到模型上下文

8. 压缩与恢复点 Copy Chapter

主循环必须内建以下钩子点：

- 调用模型前检查是否需要压缩
- 工具结果过长时应用 result budget
- prompt 过长时触发 compact / reactive compact
- resume 时从 compact boundary 后恢复有效消息

9. 子 agent 与后台任务接入点 Copy Chapter

主循环必须允许以下事件打断常规路径：

- 启动 foreground subagent
- 启动 background subagent
- 接收 task notification
- 继续 resume 某个已有 agent

10. Python 版推荐伪代码 Copy Chapter

def query_loop(params):
    state = init_state(params)
    while True:
        if should_stop(state, params):
            return terminal_result(state)
        state = maybe_compact(state, params)
        request = build_model_request(state, params)
        response = call_model(request)
        state.messages.append(response.assistant_message)
        if response.tool_calls:
            tool_events = run_tools(response.tool_calls, params)
            state.messages.extend(tool_events)
            state.transition_reason = 'tool_round'
            continue
        if response.should_launch_subagent:
            launch_subagent(response, params)
            state.transition_reason = 'subagent'
            continue
        if response.is_terminal:
            return terminal_result(state)
        state.turn_count += 1

11. 实现边界 Copy Chapter

Python 第一版务必保证：
- 单主循环是清晰、可测试的
- 每轮状态可序列化
- 每轮输出可回放
- 每轮失败可定位

不要把主循环写成大量隐式副作用的脚本式逻辑。

12. 验收标准 Copy Chapter

程序员实现完成后，应满足：

1. 可以连续多轮处理任务
2. 工具结果能回流并影响下一轮
3. 超长上下文会压缩而不是直接崩溃
4. 子任务可以插入主流程
5. transcript 可完整记录轮次

---

09 Message Model And State Copy Section

09. 消息模型与状态规格

1. 为什么消息模型必须先定义 Copy Chapter

这类 Agent 系统的核心不是“函数调用”，而是“结构化消息驱动状态变化”。如果消息模型不稳定，后面的 memory、resume、工具执行、agent 任务都会混乱。

2. 顶层消息类型 Copy Chapter

Python 版本建议至少定义以下消息类型：

- system
- user
- assistant
- tool_use
- tool_result
- progress
- attachment
- summary
- compact_boundary
- notification
- tombstone（可选，用于删除/隐藏历史消息后的链修复）

3. 核心消息字段 Copy Chapter

所有消息建议共享：

class BaseMessage:
    id: str
    type: str
    created_at: float
    parent_id: str | None
    session_id: str

assistant 消息 Copy Section

class AssistantMessage(BaseMessage):
    content_blocks: list
    usage: dict | None
    stop_reason: str | None

user 消息 Copy Section

class UserMessage(BaseMessage):
    content_blocks: list
    source: str | None

tool_use 消息块 Copy Section

class ToolUseBlock:
    id: str
    name: str
    input: dict

tool_result 消息块 Copy Section

class ToolResultBlock:
    tool_use_id: str
    content: str | list
    is_error: bool = False

4. 为什么 parent_id 很重要 Copy Chapter

消息链必须可追踪。这样才能支持：
- transcript 回放
- resume
- 历史修复
- compact boundary 后的有效链重建

5. progress 消息的处理原则 Copy Chapter

高频 progress 消息通常是 UI 态，而不是核心 transcript。实现时建议：

- 可以显示在界面中
- 但默认不参与核心 parent chain
- 不应污染 resume 后的模型上下文

6. attachment / notification 的用途 Copy Chapter

这类消息用于携带结构化系统事件，例如：
- hook 阻断
- task notification
- permission 说明
- MCP 附加上下文

不要把所有系统事件都挤进普通文本消息中。

7. 状态对象要求 Copy Chapter

除消息外，还要有显式状态对象：

class SessionState:
    session_id: str
    cwd: str
    current_task_id: str | None
    memory_summary: str | None
    active_agent_ids: list[str]
    current_permission_mode: str
    token_budget_state: dict | None

8. compact boundary 的需求 Copy Chapter

压缩前后必须有清晰边界，方便：
- 知道哪些历史被总结了
- resume 时只加载必要部分
- 保持消息链清晰

9. transcript 存储要求 Copy Chapter

transcript 至少要支持：
- 顺序追加
- 按 session 加载
- 按 agent 侧链加载
- 读取尾部摘要
- 限制超大文件读取风险

10. 验收标准 Copy Chapter

1. 任一轮对话都能序列化为结构化消息
2. tool_use 和 tool_result 可一一对应
3. progress 不污染核心历史链
4. 会话可按消息链恢复
5. 子 agent transcript 能独立存储

---

10 Context Management Copy Section

10. 上下文管理与压缩规格

1. 目标 Copy Chapter

上下文管理的目标不是“保留一切”，而是让模型在有限预算内持续拿到最关键的信息。

2. 必须保留的信息 Copy Chapter

优先级最高的信息包括：

1. 当前用户任务目标
2. 系统硬规则与安全约束
3. 用户明确偏好
4. 最近关键工具结果
5. 当前活跃子任务状态
6. 记忆摘要
7. 最近 compact 后的摘要

3. 可压缩的信息 Copy Chapter

以下信息应优先被压缩或裁剪：

- 旧的长日志
- 重复解释
- 已完成步骤的冗余细节
- 大量相似 read/search 结果
- 旧的 progress 消息

4. 上下文预算机制 Copy Chapter

Python 版建议同时维护：
- 粗略 token 估计
- 工具结果字符预算
- 每轮输出预算
- 全任务预算（可选）

5. 压缩触发条件 Copy Chapter

建议在以下情况触发：

- 请求前 token 估计超过阈值
- 工具结果总量过大
- 模型返回 prompt too long
- resume 重建会话时

6. 压缩策略层级 Copy Chapter

6.1 轻量裁剪 Copy Section

6.2 摘要压缩 Copy Section

6.3 边界标记 Copy Section

7. 子任务上下文要求 Copy Chapter

fork 子任务 Copy Section

verification 子任务 Copy Section

8. 工具结果预算 Copy Chapter

工具结果必须经过 budget 控制。否则：
- 长 grep
- 长 read
- 长 shell 输出
会迅速污染上下文。

9. Python 版伪代码 Copy Chapter

def manage_context(messages, budget):
    messages = drop_ephemeral_progress(messages)
    messages = trim_large_tool_results(messages, budget.tool_result_chars)
    if estimate_tokens(messages) > budget.max_input_tokens:
        summary = summarize_old_messages(messages)
        messages = build_post_compact_messages(summary, messages)
    return messages

10. 验收标准 Copy Chapter

1. 长任务不会因上下文无限增长而崩溃
2. resume 后仍可恢复关键事实
3. 子任务不会把噪声大规模回灌主线程
4. 工具长输出会被预算裁剪

---

11 Task Model Copy Section

11. 任务模型与后台执行规格

1. 目标 Copy Chapter

任务系统负责把“一个 agent 在做什么”变成可追踪对象，而不是只存在于对话文本里。

2. 任务类型 Copy Chapter

Python 版建议至少支持：

- main_session_task
- local_agent_task
- background_agent_task
- shell_task
- verification_task
- remote_task（可后置）

3. 核心任务字段 Copy Chapter

class TaskRecord:
    task_id: str
    type: str
    session_id: str
    parent_task_id: str | None
    agent_id: str | None
    description: str
    status: str
    created_at: float
    started_at: float | None
    finished_at: float | None
    output_path: str | None
    error: str | None
    result_summary: str | None
    progress: dict | None

4. 状态机 Copy Chapter

建议统一状态：
- pending
- running
- waiting_permission
- backgrounded
- completed
- failed
- cancelled
- killed

5. 背景任务需求 Copy Chapter

background agent 至少要支持：
- 注册
- 更新进度
- 存储输出文件路径
- 完成时通知主线程
- 失败时通知主线程
- 支持 kill / cancel

6. 进度跟踪需求 Copy Chapter

任务进度至少记录：
- 工具调用次数
- token 使用量
- 最近活动
- 最近摘要

7. 输出文件需求 Copy Chapter

后台任务建议将结果落盘到 output file，用于：
- 主线程查看
- resume 后读取
- 审计

8. 通知机制需求 Copy Chapter

任务结束时，系统必须向主线程注入结构化 notification，而不是只静默完成。

9. 验收标准 Copy Chapter

1. 每个子 agent 都能注册为任务
2. 背景任务可查询状态
3. 任务可输出结果文件
4. 任务完成/失败会通知主线程
5. 任务可被停止

---

12 Workspace And Isolation Copy Section

12. 工作区与隔离策略规格

1. 目标 Copy Chapter

不同 agent 不能默认拥有相同的文件系统权限。产品必须允许根据角色与场景控制工作区隔离。

2. 隔离模式 Copy Chapter

Python 版建议至少定义：

2.1 shared workspace Copy Section

2.2 read-only workspace Copy Section

2.3 temp workspace Copy Section

2.4 worktree workspace Copy Section

2.5 remote workspace Copy Section

3. 为什么隔离必须存在 Copy Chapter

没有隔离会导致：
- 子任务互相污染
- 验证角色破坏项目
- fork 实验影响主线程
- 风险动作边界模糊

4. 角色与隔离建议 Copy Chapter

- Explore Agent -> read-only
- Plan Agent -> read-only
- Verification Agent -> read-only + temp writable
- General Agent -> shared 或 worktree
- 高风险实现任务 -> worktree

5. 路径翻译需求 Copy Chapter

如果子任务运行在 worktree 中，而继承的上下文引用的是父工作区路径，系统需要能做路径翻译或重新读取。

6. 清理需求 Copy Chapter

隔离工作区结束后必须支持：
- 清理临时文件
- 清理临时目录
- 清理 worktree（如适用）
- 清理孤儿进程

7. 验收标准 Copy Chapter

1. 只读角色不能修改项目文件
2. 验证角色只能在 temp 目录写测试脚本
3. worktree 任务不污染主项目目录
4. 任务结束后能清理隔离资源

---

13 Failure Recovery Copy Section

13. 失败处理与恢复规格

1. 目标 Copy Chapter

Agent 系统不能把失败当成异常边缘情况。失败是常态，系统必须有明确恢复策略。

2. 失败类型 Copy Chapter

建议至少区分：

- tool_input_error
- permission_denied
- hook_blocked
- shell_runtime_error
- model_api_error
- prompt_too_long
- mcp_connect_error
- task_killed
- resume_load_error
- session_storage_error

3. 各类失败处理原则 Copy Chapter

tool_input_error Copy Section

permission_denied Copy Section

hook_blocked Copy Section

prompt_too_long Copy Section

model_api_error Copy Section

4. resume 恢复需求 Copy Chapter

系统必须支持：
- 读取 transcript
- 找到 compact boundary 后有效历史
- 恢复 session_id 与 project dir
- 恢复活跃任务或至少恢复摘要

5. 子任务失败需求 Copy Chapter

子任务失败后不能静默消失，必须：
- 写入任务状态
- 通知主线程
- 保留错误摘要

6. 恢复策略级别 Copy Chapter

轻恢复 Copy Section

中恢复 Copy Section

重恢复 Copy Section

7. 验收标准 Copy Chapter

1. 常见失败都有明确处理路径
2. 子任务失败不会丢失
3. prompt too long 可进入压缩恢复
4. 会话中断后可恢复

---

14 Configuration System Copy Section

14. 配置系统规格

1. 目标 Copy Chapter

配置系统负责把产品的默认行为、用户偏好、项目约束和扩展能力统一管理，而不是散落在代码里。

2. 配置来源 Copy Chapter

Python 版建议支持以下来源：

1. 全局用户配置
2. 项目级配置
3. session 级配置
4. plugin / skill frontmatter 配置
5. 环境变量
6. CLI 参数覆盖

3. 配置优先级 Copy Chapter

建议优先级从高到低：

1. runtime override / CLI 参数
2. session 配置
3. 项目配置
4. 用户全局配置
5. 默认配置

4. 必须可配置的项目 Copy Chapter

- 默认模型
- 语言
- 输出风格
- permission mode
- hook 开关与 hook 配置
- MCP server 配置
- plugin 路径
- skill 路径
- token / task budget
- 自动 compact 开关
- transcript 持久化开关

5. Agent 级配置需求 Copy Chapter

每个 agent 定义建议支持：
- agent_type
- when_to_use
- allowed_tools / disallowed_tools
- model
- memory scope
- mcp_servers
- background capability
- isolation mode

6. 配置系统验收标准 Copy Chapter

1. 用户可在不改代码的情况下调整运行行为
2. 项目可定义局部约束
3. session 可临时覆盖配置
4. plugin / skill 可附带配置元信息

---

15 Mvp Scope Copy Section

15. Python 版本 MVP 范围

1. 目标 Copy Chapter

避免 Python 版本一开始就无限扩张。MVP 只做能跑通核心闭环的最小系统。

2. MVP 必须包含 Copy Chapter

2.1 主循环 Copy Section

2.2 基础工具 Copy Section

2.3 基础权限系统 Copy Section

2.4 基础 transcript / session Copy Section

2.5 基础 memory Copy Section

2.6 基础 agent orchestration Copy Section

2.7 基础 compact Copy Section

3. MVP 可以后置的能力 Copy Chapter

- 完整 TUI
- remote execution
- 多人 teammate / swarm
- 高级 telemetry
- 高级 tracing
- 复杂 MCP delta 更新
- 高级 proactive / coordinator 模式
- 完整插件生态

4. 推荐实现顺序 Copy Chapter

1. 消息模型
2. 主循环
3. 工具执行链
4. transcript / resume
5. memory
6. verification agent
7. skills / plugin / MCP 里的最小一项

5. 成功标准 Copy Chapter

MVP 成功不等于“功能很多”，而是下面闭环能跑通：

用户给任务 -> 系统多轮推进 -> 调用工具 -> 保留上下文 -> 必要时压缩 -> 完成后给结果 -> 可恢复会话 -> 可做基本验证

6. 不建议在 MVP 阶段做的错误方向 Copy Chapter

- 先做复杂 UI
- 先做很多 agent 类型
- 先做大而全插件系统
- 没有 transcript / resume 就上 background task
- 没有权限系统就直接开放 bash

---

16 Python Implementation Notes Copy Section

16. Python 实现注意事项

1. 实现原则 Copy Chapter

目标不是逐字复刻原实现，而是用 Python 重建同样的产品能力结构。

2. 模块建议 Copy Chapter

建议 Python 项目按以下模块拆：

- runtime/：query loop, orchestration
- messages/：message schemas
- tools/：tool registry and execution
- permissions/：permission engine
- memory/：memory loading and retrieval
- tasks/：background task model
- storage/：transcript and session persistence
- agents/：agent definitions
- extensions/：skills/plugins/mcp
- verification/：verification runner

3. 推荐先用的数据模型 Copy Chapter

优先用：
- pydantic / dataclasses 定义消息与状态
- sqlite 或 JSONL 先做 transcript
- 明确的 service 层代替隐式全局状态

4. 不要过早做的事 Copy Chapter

- 不要先优化 UI
- 不要先做复杂并发
- 不要先支持十几种 agent
- 不要把 memory 做成向量库重系统

5. 第一阶段的最佳目标 Copy Chapter

先做出一个：
- 结构清晰
- transcript 可回放
- message 模型稳定
- verification 能跑
- compact 能工作

的 Python core runtime。

6. 推荐里程碑 Copy Chapter

Milestone 1 Copy Section

Milestone 2 Copy Section

Milestone 3 Copy Section

Milestone 4 Copy Section

---

README Copy Section

AI Agent Deep Dive

<a href="https://www.star-history.com/?repos=tvytlx%2Fai-agent-deep-dive&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tvytlx/ai-agent-deep-dive&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=tvytlx/ai-agent-deep-dive&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=tvytlx/ai-agent-deep-dive&type=date&legend=top-left" />
</picture>
</a>

Quick Links Copy Chapter

PDF 下载 / PDF Report:
- 新增《Hermes Agent 源码深度解析》，在我的知识星球 矩阵之外
- ClaudeCode ai-agent-deep-dive-v2.1.pdf 新增第八章：记忆系统
- ClaudeCode ai-agent-deep-dive-v2.pdf

Notes Copy Chapter

- 本仓库仅保留面向学习与评论的分析材料，不提供源码目录。
- 第二版 PDF 已完成。

Teaching Agent Code Copy Chapter

这个仓库现在还包含一个教学用的最小 Python Agent 项目，用于演示一个 AI Agent 的核心结构应该怎么组织。

核心代码位置 Copy Section

- Agent 核心代码：src/agt/agent.py
- CLI 入口：src/agt/cli.py
- 教学文档：docs/

这个教学项目的定位 Copy Section

这个最小 Agent 项目是为了教学而设计的，特点是：

- 尽量保持结构清晰
- 尽量减少不必要的工程复杂度
- 所有核心代码集中在一个很小的范围内，方便学习
- 当前重点放在：Agent 主循环、Fake LLM 接口、Skills 发现、CLI 骨架

如何运行最小 Agent Copy Section

本项目使用 Poetry 管理依赖。

#### 1. 安装依赖

poetry install

#### 2. 运行最小 Agent CLI

poetry run agt "你好"

#### 3. 查看 Skills

poetry run agt --skills-dir ./skills --list-skills

当前实现说明 Copy Section

当前版本是一个教学型最小实现，还没有接入真实远程模型 API。

目前内置的是一个可替换的 Fake LLM：
- 用户输入什么
- 它就会用流式文本块的方式返回一个测试响应

这样做的目的，是为了让后续接入真实模型时，只需要替换 LLM 调用层，而不需要重写整个 Agent 主体。

---