引言

前面10篇文章，我们一块一块地拆解了 Agent 的每个核心机制。每篇聚焦一个点：循环、工具、规划、技能、上下文、任务、团队、协议、自治、隔离。

现在是时候把这些散落的拼图拼回去了。

项目里的 s_full.py 就是这个"毕业作品"——它把 s01 到 s11 的所有机制整合进一个文件，形成一个完整的、可运行的 Agent 系统。这篇文章不会再引入新概念，而是做一件事：俯瞰全景，看清全貌。

完整架构：一张图看完

先看结构，再说细节。

flowchart TB
    subgraph AgentLoop["Agent Loop（while 循环）"]
        direction TB
        subgraph L1["第一层：系统提示"]
            S1["技能菜单描述"]
            S2["任务优先指令"]
            S3["TODO 未完成提醒"]
        end
        subgraph L2["第二层：LLM 调用前预处理"]
            P1["微压缩 micro_compact"]
            P2["排空后台通知"]
            P3["检查收件箱"]
        end
        subgraph L3["第三层：工具调度面板"]
            T1["23 个工具"]
        end
        L1 --> L2 --> L3
        L3 -->|"模型选择工具并执行"| L2
    end

    AgentLoop -->|"spawn subagent"| Sub["子代理：执行后返回摘要即销毁"]
    AgentLoop -->|"spawn teammate"| Team["队友：后台持续运行，idle 时自动领任务"]

    style L1 fill:#e3f2fd,stroke:#1565c0
    style L2 fill:#fff3e0,stroke:#e65100
    style L3 fill:#e8f5e9,stroke:#2e7d32
    style Sub fill:#fff9c4,stroke:#f9a825
    style Team fill:#e0f7fa,stroke:#00838f

第一层：系统提示

每次对话开始前，Harness 构建系统提示。这不是写死的一段话，而是动态拼接的：

基础角色定义
 + 可加载的技能列表（来自 skills/ 目录下的 SKILL.md）
 + "先拆任务再动手"的工作指令
 + 如果有未完成的 TODO，追加提醒（"你还有 N 个待办没做完"）

这里体现了一个重要设计：系统提示是 Harness 对模型施加影响的第一道关卡。模型的行为很大程度上被系统提示塑造。你想让它先做计划？写进系统提示。你想让它优先处理任务？也写进系统提示。

第二层：每次 LLM 调用前的预处理

Agent Loop 每一轮都会调用 LLM。但在发请求之前，Harness 会做三件事：

1. 微压缩（Microcompact）

检查对话历史里的工具返回结果，只保留最近3条，更早的用 [cleared] 替换掉。这是一种"精打细算"的方式，在不丢失近期上下文的前提下节省 token。

2. 自动压缩（Auto-compact）

如果总 token 数超过阈值（默认10万），触发一次完整压缩：把当前对话存档到 .transcripts/ 目录，然后用 LLM 生成一份摘要，替换掉整个对话历史。代价是丢失细节，好处是能继续工作而不会撑爆上下文窗口。

压缩后，Harness 会把最新的消息（用户的最后一句话和最后一批工具结果中未清除的内容）保留在新的对话历史里，确保模型不会丢失"刚才在干什么"。

3. 排空后台通知 + 检查收件箱

后台任务（BackgroundManager）跑完了会往通知队列里丢结果。每轮循环开始时，Harness 把这些通知取出来，注入到对话历史里。同理，如果有队友发来的消息，也在这个时机注入。

这三步加在一起，保证模型每次"醒来"看到的上下文是干净的、可控的、不会太长的。

第三层：工具调度面板

s_full.py 一共注册了多少个工具？数一下：

类别	工具	来源
基础操作	bash, read_file, write_file, edit_file	s01/s02
计划管理	TodoWrite	s03
子代理	subagent	s04
技能加载	load_skill	s05
上下文压缩	compress	s06
任务管理	task_create, task_get, task_update, task_list	s07
后台执行	bg_run, bg_check	s08
团队通信	spawn_teammate, list_teammates, send_message, read_inbox, broadcast	s09
协议	shutdown_request, plan_approval	s10
自治	idle, claim_task	s11

总计 23 个工具。这是模型的"操作面板"——模型在每一轮 Agent Loop 里，从这23个工具中选择要用哪个（或者不用任何工具，直接回复文字）。

flowchart LR
    subgraph Basic["基础操作"]
        B1["bash"]
        B2["read_file"]
        B3["write_file"]
        B4["edit_file"]
    end
    subgraph Plan["计划"]
        P1["TodoWrite"]
    end
    subgraph SubA["子代理"]
        SA1["subagent"]
    end
    subgraph Skill["技能"]
        SK1["load_skill"]
    end
    subgraph Compact["压缩"]
        C1["compress"]
    end
    subgraph Task["任务管理"]
        T1["task_create"]
        T2["task_get"]
        T3["task_update"]
        T4["task_list"]
    end
    subgraph BG["后台"]
        BG1["bg_run"]
        BG2["bg_check"]
    end
    subgraph Team["团队通信"]
        TM1["spawn_teammate"]
        TM2["list_teammates"]
        TM3["send_message"]
        TM4["read_inbox"]
        TM5["broadcast"]
    end
    subgraph Proto["协议"]
        PR1["shutdown_request"]
        PR2["plan_approval"]
    end
    subgraph Auto["自治"]
        A1["idle"]
        A2["claim_task"]
    end

    style Basic fill:#bbdefb,stroke:#1565c0
    style Plan fill:#c8e6c9,stroke:#2e7d32
    style SubA fill:#fff9c4,stroke:#f9a825
    style Skill fill:#ffe0b2,stroke:#e65100
    style Compact fill:#e0e0e0,stroke:#616161
    style Task fill:#e1bee7,stroke:#7b1fa2
    style BG fill:#ffcdd2,stroke:#c62828
    style Team fill:#b2ebf2,stroke:#00838f
    style Proto fill:#f8bbd0,stroke:#c2185b
    style Auto fill:#d7ccc8,stroke:#4e342e

子代理与队友

这两个概念容易混淆，值得再澄清一次：

子代理（Subagent）：临时工。Lead 发起一个子任务，子代理独立完成后返回摘要，然后就没了。它有自己的 Agent Loop，但生命周期很短——用完即弃。适合"帮我调研一下这个 API 怎么用"这类一次性任务。

队友（Teammate）：长期工。被 spawn 出来后，在后台线程里持续运行。做完手头的事会进入 idle 状态，自动扫描任务板找新活。可以和 Lead 通信，可以提交计划等审批，可以被要求关闭。适合"负责前端开发"这类持续性角色。

子代理：  spawn → work → return summary → 消失
队友：    spawn → work → idle → auto-claim → work → idle → ... → shutdown

设计取舍：为什么这样而不是那样

技术方案没有完美的，只有适合的。s_full.py 做了几个很有意思的取舍。

为什么选"信任模型"而不是"控制模型"？

有些 Agent 框架会严格约束模型的行为：规定好执行顺序、限定工具调用的组合、人工审批每一步操作。这叫"控制模型"——你不信任模型的判断力，所以替它做决策。

Claude Code 走的是另一条路。它给模型一个丰富的工具面板，告诉它目标是什么，然后让模型自己决定怎么做。模型可能先读文件、再写测试、再跑测试、再改代码——也可能反过来。Harness 不规定顺序。

为什么？因为现代大语言模型的规划和推理能力已经足够强了。过度控制反而会限制模型发挥。就像你雇了一个高级工程师，但每写一行代码都要你审批——那还不如你自己写。

当然，"信任"不等于"放任"。Harness 仍然划定了边界：危险命令会被拦截，文件路径不能逃出工作目录，关键操作要走审批协议。信任模型的判断力，但约束它的行为边界。

为什么用文件而不是数据库？

任务用 JSON 文件（.tasks/task_1.json），消息用 JSONL 文件（.team/inbox/coder.jsonl），配置也是 JSON 文件。为什么不用 SQLite？不用 Redis？

三个理由：

可读。打开文件就能看状态，不需要任何客户端工具
可调试。出了问题，cat 一下就知道哪里不对
零依赖。不需要装数据库，不需要启动服务，pip install 完就能跑

对于教学项目来说，这是最优选择。对于生产环境，换成数据库是很自然的演进——接口不变，只改存储层。

为什么不用消息队列？

RabbitMQ、Kafka、Redis Pub/Sub——这些都是成熟的消息中间件。为什么不用？

同样是可理解性优先。一个 JSONL 文件 + 读后清空的语义，任何人都能看懂。引入 Kafka 之后，你还得解释 partition、offset、consumer group……这些和 Agent 本身没关系，只会增加认知负担。

生产环境需要消息队列吗？看规模。几个 Agent 协作，文件就够了。几百个 Agent 跨机器协作，那确实需要换。但核心模式（收件箱 + 发送 + 读取 + 清空）不变，只是底层换了个存储。

五条核心设计哲学

回顾整个系列，有五条原则贯穿始终。它们不是空洞的口号，而是每一个设计决策背后的理由。

1. 循环不变，机制叠加

从 s01 到 s_full，Agent Loop 的核心结构一直没变过：

while True:
    response = llm.call(messages)
    if response.stop_reason != "tool_use":
        return
    results = execute_tools(response)
    messages.append(results)

变的是什么？是循环体内的工具越来越多，循环前的预处理越来越丰富。但骨架没动。

这就像手机的操作系统内核十年没换，但 App 从几个变成了几百万个。

2. 模型决策，代码执行

模型决定"做什么"——用哪个工具、传什么参数、什么时候停下来。代码决定"怎么做"——执行命令、读写文件、发送消息。

两者的边界非常清晰。模型不直接操作文件系统，代码不替模型做判断。

3. 按需加载，不预先堆料

技能文件不是一开始就塞进系统提示的，而是模型觉得需要时才调用 load_skill 加载。工具的描述是精简的，详细文档按需获取。

原因很实际：上下文窗口有限，每一个 token 都有成本。把不相关的信息堆进去，既浪费钱，又稀释了重要信息的权重。

4. 文件持久化，上下文是临时的

任务状态、团队配置、消息历史——这些都持久化在文件里。但对话上下文（messages 数组）是内存里的临时数据，随时可能被压缩、被截断、被丢弃。

这个区分很关键。如果你把重要状态只放在 messages 里，一次压缩就丢了。所以凡是需要"记住"的东西，必须写到文件里。

5. 信任模型，约束边界

给模型足够的自由度，但用工具设计、系统提示和协议来划定边界。不替模型做决策，但确保它的行为不会越线。

这五条原则不只适用于 Claude Code 的这个教学项目，它们适用于所有 Agent 系统的设计。

一张全景表

最后，用一张表把 s01 到 s_full 的演进串起来：

阶段	新增机制	解决的问题
s01	Agent Loop + bash	Agent 能执行命令了
s02	read/write/edit 工具	Agent 能读写文件了
s03	TodoWrite	Agent 会做计划了
s04	Subagent	Agent 能拆子任务了
s05	Skill Loading	Agent 能按需学习了
s06	Context Compact	Agent 能持续工作了（不会撑爆上下文）
s07	Task System	Agent 能管理多任务了
s08	Background Tasks	Agent 能并行跑任务了
s09	Team Messaging	多个 Agent 能通信了
s10	Protocols	通信有序了（请求-响应配对）
s11	Autonomous Agents	队友自己找活干了
s12	Worktree Isolation	并行改代码不冲突了
s_full	全部整合	完整的 Agent 系统

flowchart LR
    S01["s01\nAgent Loop\n+ bash"] --> S02["s02\n文件\n读写"]
    S02 --> S03["s03\nTodo\n计划"]
    S03 --> S04["s04\n子代理\n拆任务"]
    S04 --> S05["s05\nSkill\n按需学习"]
    S05 --> S06["s06\n上下文\n压缩"]
    S06 --> S07["s07\n任务\n管理"]
    S07 --> S08["s08\n后台\n并行"]
    S08 --> S09["s09\n团队\n通信"]
    S09 --> S10["s10\n协议\n审批"]
    S10 --> S11["s11\n自治\nAgent"]
    S11 --> S12["s12\nWorktree\n隔离"]
    S12 --> SF["s_full\n完整平台"]

    style S01 fill:#e3f2fd,stroke:#1565c0
    style S02 fill:#e3f2fd,stroke:#1565c0
    style S03 fill:#e8f5e9,stroke:#2e7d32
    style S04 fill:#fff9c4,stroke:#f9a825
    style S05 fill:#ffe0b2,stroke:#e65100
    style S06 fill:#e0e0e0,stroke:#616161
    style S07 fill:#e1bee7,stroke:#7b1fa2
    style S08 fill:#ffcdd2,stroke:#c62828
    style S09 fill:#b2ebf2,stroke:#00838f
    style S10 fill:#f8bbd0,stroke:#c2185b
    style S11 fill:#d7ccc8,stroke:#4e342e
    style S12 fill:#dcedc8,stroke:#558b2f
    style SF fill:#ffab40,stroke:#e65100,stroke-width:3px

小结

s_full.py 只有大约500行代码。用500行代码搭出一个拥有23个工具、支持子代理和团队协作、有计划管理和上下文压缩、带通信协议和任务隔离的完整 Agent 系统——这说明 Agent 框架本身并不复杂，复杂的是对每个机制的理解和取舍。

到这里，原理层面的内容全部结束了。

下一篇，我们换个角色——从"理解别人造的东西"变成"自己动手造"。

全景拆解 —— Claude Code 的完整架构一览

评论区

需要帮助？