Harness on 男娘教主

W7-Day6：把所有零件装成一台机器——完整调用链

Mon, 21 Sep 2026 14:41:20 +0800

W7-Day6：把所有零件装成一台机器——完整调用链

前两篇已经把 W7 的知识点拆开了。

这一篇只做一件事情：

顺着代码真正走一遍。

因为我发现自己阅读复杂代码时，最大的困难不是看不懂某个函数，而是：

不知道这个函数为什么在这里，它是谁调用的，调用完又把结果交给谁。

所以这一次不从文件开始，而是从一次真实运行开始。

一、先看一次完整运行

用户输入：

1

写一篇 300 字介绍 Agent 记忆系统的文章，要有事实依据

整个系统大致这样跑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


main()
 ↓
创建 LLM
 ↓
build_harness()
 ↓
创建五模块
 ↓
build_supervisor()
 ↓
创建 supervisor + workers
 ↓
build_graph()
 ↓
graph.stream()
 ↓
START
 ↓
supervisor
 ↓
researcher
 ↓
supervisor
 ↓
writer
 ↓
Reflection
 ↓
critic
 ↓
reviser
 ↓
critic
 ↓
返回 ReflectionResult
 ↓
writer 交活
 ↓
supervisor
 ↓
reviewer
 ↓
supervisor
 ↓
FINISH

这张图是 Day6 最应该掌握的东西。

二、入口：`main()`

最终整合程序的入口是：

1

def main():

先做：

1

llm = ChatOpenAI(...)

这里创建的是整个系统共用的 LLM。

然后：

1

h = build_harness(llm)

注意这个调用。

它意味着：

1
2
3
4
5


main
 ↓
build_harness
 ↓
Harness

三、`build_harness()` 到底做了什么？

这里不是业务流程。

它做的是：

装配基础设施。

大概：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


build_harness
 │
 ├── ToolRegistry
 │
 ├── PermissionGate
 │
 ├── SessionStore
 │
 ├── ContextCompactor
 │
 ├── Tracer
 │
 └── Harness

所以：

1

h = build_harness(llm)

得到的：

1

h

不是一个 Agent。

而是：

Agent 的运行环境。

四、Registry 在这里注册了什么？

示例里注册两个工具：

1
2


search_web
publish_article

其中：

1
2
3
4
5


search_web
 level = safe

publish_article
 level = dangerous

于是：

1
2
3
4
5


Registry
 │
 ├── search_web
 │
 └── publish_article

接着：

1

PermissionGate(reg, audit_path=...)

建立：

1
2
3


Registry
 ↓
Gate

五、Session / Compactor / Tracer 在这里被装配

1
2
3


SessionStore(...)
ContextCompactor(...)
Tracer(...)

最终：

1
2
3
4
5
6
7
8


Harness(
 registry=reg,
 gate=gate,
 session=session,
 compactor=compactor,
 tracer=tracer,
 llm=llm
)

这就是整个 Harness 的装配点。

以后业务代码拿：

1

h

就能访问：

1
2
3
4
5
6


h.registry
h.gate
h.session
h.compactor
h.tracer
h.llm

六、然后进入 `build_supervisor()`

这里开始真正创建 Agent 流程。

首先：

1

Route

定义 Supervisor 可以输出：

1
2
3
4
5


planner
researcher
writer
reviewer
FINISH

然后：

1

router = llm.with_structured_output(...)

于是：

1
2
3


LLM
 ↓
Route

七、`build_supervisor()` 又创建了几个节点？

可以先不看函数细节。

直接看返回值：

1
2
3
4
5


supervisor
planner
researcher
writer
reviewer

所以这里实际上完成：

1
2
3


节点工厂
 ↓
节点集合

然后 build_graph() 再把这些节点连起来。

八、为什么 `make_simple()` 是一个函数工厂？

例如：

1

def make_simple(name, prompt):

它返回：

1

def node(state):

所以：

1

make_simple("planner", prompt)

得到：

1

planner node

而：

1

make_simple("researcher", prompt)

得到：

1

researcher node

本质上：

1
2
3


输入角色配置
 ↓
生成对应节点函数

所以这不是多了一层“炫技”。

而是在消除重复代码。

九、真正特殊的是 `writer_node`

因为：

1
2
3


planner
researcher
reviewer

都是普通 worker。

但：

1

writer

里面又嵌套了一套 Reflection。

也就是说：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Supervisor 图
 │
 └── writer
 │
 ▼
 Reflection 图
 │
 generator
 ↓
 critic
 ↓
 reviser
 ↓
 critic

这就是 Day6 最复杂的一层嵌套。

十、为什么这里不能直接把 Reflection 的 State 暴露出来？

Reflection 有：

1
2
3
4
5
6
7
8
9


topic
draft
score
issues
fatal_issues
revise_count
trajectory
best_draft
best_score

而 Supervisor 有：

1
2
3


messages
next
rounds

如果直接把两套 State 合起来：

1

SuperState + RState

马上就会产生耦合。

于是 Day6 引入：

1

reflection_api.py

十一、`ReflectionResult` 就是两个系统之间的“接口”

它只有：

1
2
3
4
5
6
7


@dataclass
class ReflectionResult:
 draft: str
 score: int
 rounds: int
 passed: bool
 notes: list

也就是说：

1
2
3
4
5
6
7
8


Reflection 内部
 8 个字段
 ↓
Reflection API
 ↓
5 个字段
 ↓
Supervisor

这就是：

窄接口。

十二、窄接口到底解决什么？

假设未来 Reflection 内部：

1

revise_count

改成：

1

revision_count

如果 Supervisor 直接访问：

1

state["revise_count"]

那么 Supervisor 也要改。

但现在：

1
2
3
4
5


Supervisor
 ↓
write_with_reflection()
 ↓
Reflection 内部

Supervisor 根本不知道内部字段叫什么。

所以：

内部实现可以变化，外部调用契约不变。

这就是封装真正有价值的地方。

十三、`write_with_reflection()` 内部到底发生什么？

调用：

1

write_with_reflection(topic)

进入：

1
2
3


build / 注入 Reflection Graph
 ↓
graph.invoke(...)

传进去的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "topic": topic,
 "draft": "",
 "score": 0,
 "issues": [],
 "revise_count": 0,
 "trajectory": [],
 "best_draft": "",
 "best_score": 0
}

也就是说：

Supervisor 不需要知道这些字段。

这些字段全部属于 Reflection 内部。

十四、Reflection Graph 内部再次运行

1
2
3
4
5
6
7


START
 ↓
generator
 ↓
critic
 ↓
route_after_critic

如果不达标：

1
2
3


reviser
 ↓
critic

继续循环。

最终：

1
2
3


Reflection Graph
 ↓
最终 State

十五、然后 API 做一件很重要的事情：重新判定

这里特别值得注意。

它没有直接：

1

passed = out["passed"]

而是自己计算：

1
2
3


fatal issue?
score >= pass_score?
revise_count >= max_revise?

然后：

1
2
3


程序
 ↓
ReflectionResult

所以：

模型负责评价，程序负责最终判定。

十六、为什么返回 `best_draft` 而不是最后一稿？

例如：

1
2
3


第一稿 6 分
第二稿 8 分
第三稿 7 分

最终：

1
2


draft = 第三稿
best_draft = 第二稿

因此 API 返回：

1
2
3


best_draft
+
best_score

而不是：

1
2
3


最后一次 draft
+
最后一次 score

否则会出现：

1
2


稿子是第二稿
分数却是第三稿

这种状态不一致。

所以这里其实还有一个重要工程原则：

相关字段必须保持一致的语义。

十七、回到 `writer_node`

Reflection 返回：

1

ReflectionResult

然后 writer 把它重新变成 Supervisor 世界里的消息：

1
2
3


[writer 交活]
终稿内容
[内部: 2轮/8分/pass=True]

然后：

1
2
3


return {
 "messages": [...]
}

注意这里发生了一次非常重要的转换：

1
2
3
4
5


Reflection State
 ↓
ReflectionResult
 ↓
Supervisor Message

这就是系统之间的边界。

十八、第二条边界：消息格式

还有一个更隐蔽的问题。

Supervisor / LangGraph 使用：

1
2
3
4


HumanMessage
AIMessage
SystemMessage
ToolMessage

但是 Harness 的：

1
2


Session
Compactor

使用的是：

1
2
3
4


{
 "role": "user",
 "content": "..."
}

所以出现：

1
2
3
4
5


LangChain Message Object
 ↓
 ❌
 ↓
dict

如果直接：

1

m.get("role")

而：

1

m

其实是：

1

HumanMessage

就会报：

1

AttributeError

十九、于是 Day6 又增加了 `msg_adapter.py`

它做的事情非常简单：

1
2
3
4
5


LangChain Message
 ↓
 normalize
 ↓
内部统一 dict

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


HumanMessage
 ↓
{"role": "user", ...}

AIMessage
 ↓
{"role": "assistant", ...}

ToolMessage
 ↓
{"role": "tool", ...}

于是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


外部世界
LangChain Message

 ↓

 Adapter

 ↓

内部世界
dict

二十、为什么不让 Harness 直接支持所有 Message 类型？

当然可以。

但是那样会导致：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Session
 认识 HumanMessage
 认识 AIMessage
 认识 ToolMessage

Compactor
 也认识 HumanMessage
 也认识 AIMessage
 ...

Tracer
 ...

最终：

每个模块都知道 LangChain。

耦合就越来越高。

而 Adapter 的方案：

1
2
3
4
5
6
7


LangChain
 ↓
Adapter
 ↓
内部统一格式
 ↓
Harness 五模块

所以 Harness 不需要知道外面的消息框架。

这就是 Day6 的第二条重要边界。

二十一、现在整个调用链可以完整画出来了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


用户输入
 │
 ▼
graph.stream()
 │
 ▼
supervisor
 │
 ├── 读取 messages
 │
 ├── LLM 判断 next
 │
 └── Route
 │
 ▼
 conditional edge
 │
 ├──────── researcher
 │ │
 │ └── search_web
 │
 ├──────── writer
 │ │
 │ ▼
 │ write_with_reflection()
 │ │
 │ ▼
 │ Reflection Graph
 │ │
 │ ┌──────┴──────┐
 │ ↓ ↓
 │ generator critic
 │ │
 │ ↓
 │ reviser
 │ │
 │ └──→ critic
 │
 └──────── reviewer
 │
 ▼
 supervisor
 │
 FINISH / 再循环

而旁边始终有：

1
2
3
4
5
6
7
8
9


 Harness
 │
 ┌──────────┼──────────┐
 ↓ ↓ ↓
 Registry Gate Session
 │ │
 Executor Compactor
 
 Tracer

二十二、Tracer 是怎么插进调用链的？

Day6 使用：

1
2


@h.tracer.trace("supervisor")
def supervisor_node(...):

于是：

1
2
3
4
5
6
7
8
9


进入 supervisor
 ↓
Tracer 创建 span
 ↓
执行 supervisor
 ↓
记录耗时
 ↓
返回原结果

最关键的是：

装饰器必须把原函数返回值继续返回。

否则：

1

supervisor_node()

原本应该：

1

return {"next": ...}

结果装饰器返回：

1

None

LangGraph 就炸了。

所以 Tracer 不是业务逻辑。

它是：

包在业务逻辑外面的观察层。

二十三、为什么 Day5 的 Tracer Bug 很重要？

之前出现过：

1
2


父 span 一个 ID
子 span 指向另一个 ID

最终：

1

trace tree

为空。

这个 bug 很危险，因为：

1

程序不一定报错

但是：

1

观测数据已经失真

所以：

可观测性系统自己也必须被测试。

不能因为：

1

Tracer 是测试工具

就不测试 Tracer。

二十四、Session 又在哪里真正生效？

理论上：

1

SessionStore

存在还不够。

必须真的：

1
2
3


append
 ↓
writer_sessions.jsonl

所以 Day6 验收强调：

1

文件真的长出来

这就是：

“接入”和“生效”的区别。

二十五、Compactor 怎么证明自己真的工作？

不能只写：

1

ContextCompactor(...)

而应该看到：

1

compactions > 0

甚至：

1
2
3
4
5


原始：
81 条

压缩后：
9 条

而且：

1
2


Session 中原始 81 条
仍然存在

所以：

1
2
3
4
5


存储层
81 条

模型视图
9 条

这是最完整的证明。

二十六、Gate 怎么证明真的生效？

例如：

1

publish_article

是危险工具。

正常路径：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


调用
 ↓
Gate
 ↓
NEED_APPROVAL
 ↓
人工批准
 ↓
Executor
 ↓
真正执行

拒绝路径：

1
2
3
4
5
6
7
8
9


调用
 ↓
Gate
 ↓
NEED_APPROVAL
 ↓
人工拒绝
 ↓
Executor 不执行

最终应该同时看到：

1

audit.log

以及真实副作用：

1
2


批准 → 文件出现
拒绝 → 文件没有出现

所以：

安全机制必须验证“阻止了什么”，而不仅仅是“返回了什么”。

二十七、Day6 最重要的测试思想：故障注入

正常运行：

1
2
3
4
5


reviewer
 ↓
“可以定稿”
 ↓
FINISH

这个证明不了 Reflection 一定有效。

因为：

可能只是这次恰好没触发修改。

所以故意加入：

1

fault-reviewer

让 reviewer：

1
2


永远说：
“不达标，第2段缺案例”

这样才能强制系统进入：

1
2
3
4
5
6
7
8
9


reviewer
 ↓
reviser
 ↓
reviewer
 ↓
reviser
 ↓
...

然后验证：

1

真的修改了

以及：

1

没有超过 MAX_REVISE

这就是：

故障注入测试。

二十八、为什么“绿色测试”还不够？

Day5 有：

1

21 个测试

但最有价值的是后来做的：

自杀测试 / Mutation Test。

故意把 bug 种回去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


删掉 safe_cut
 ↓
对应测试必须红

span_id 分配两次
 ↓
嵌套测试必须红

坏行修复删掉
 ↓
Session 测试必须红

装饰器不 return
 ↓
return-value 测试必须红

于是得到：

1
2
3
4
5


4 个 bug
 ↓
4 个对应测试
 ↓
4/4 全部抓住

这才证明：

测试不是“跑起来是绿的”，而是“真的有牙”。

二十九、这也是我这一周对“验证设计”的最大理解

以前可能会这样写测试：

1

assert result == expected

现在开始发现：

测试首先要证明自己的前提成立。

例如：

1

assert delivered

为什么？

因为如果：

1

delivered = []

后面的：

1

for m in delivered:

一句都不会执行。

测试可能莫名其妙通过。

所以：

空集合测试是非常危险的。

应该先：

1
2
3


证明数据存在
 ↓
再证明数据满足条件

这就是这周不断出现的：

“先证明测试有牙。”

三十、最后重新看 W7，发现它其实是在训练四层能力

第一层：编排

1
2
3


Supervisor
Conditional Edge
Worker

解决：

Agent 怎么协作？

第二层：反馈

1
2
3


Critic
Reviser
Reflection

解决：

Agent 怎么自我检查？

第三层：运行时基础设施

1
2
3
4
5


Registry
Gate
Session
Compactor
Tracer

解决：

Agent 怎么真正运行？

第四层：工程验证

1
2
3
4
5


Unit Test
Integration Test
Fault Injection
Mutation Test
Evidence

解决：

我怎么知道它真的工作？

三十一、所以 W7 真正的闭环是

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


 ┌───────────────┐
 │ Agent 决策 │
 └───────┬───────┘
 ↓
 多 Agent 协作
 ↓
 Reflection
 ↓
 产生更好结果
 ↓
 Harness 执行
 ↓
 ┌───────────┼───────────┐
 ↓ ↓ ↓
 Tools State Trace
 ↓ ↓ ↓
 Gate Session Audit
 │ │
 └──────┬────┘
 ↓
 最终结果
 ↓
 Tests
 ↓
 证明它真的工作

三十二、如果让我用一句话总结 W7

以前我可能会说：

W7 学了 Supervisor、Reflection 和 Harness。

现在我会说：

W7 是第一次把“Agent 的思考逻辑”和“Agent 的运行基础设施”放到同一个系统里考虑。

其中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


Supervisor
解决“谁来做”

Reflection
解决“做得够不够好”

Registry
解决“有什么能力”

Gate
解决“能不能使用能力”

Executor
解决“到底有没有执行”

Session
解决“过去发生了什么”

Compactor
解决“现在需要看到什么”

Tracer
解决“刚才是怎么运行的”

Facade
解决“这些零件怎么装起来”

而 Day6 真正解决的是：

1
2
3
4


这些东西之间
怎么连接
怎么转换
怎么验证

所以我现在再看一个复杂 Agent 项目，应该不再只是找：

1
2
3


Agent
Tool
LLM

而应该主动寻找：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


入口
 ↓
State
 ↓
Control Flow
 ↓
Data Flow
 ↓
模块边界
 ↓
调用契约
 ↓
执行入口
 ↓
持久化
 ↓
上下文
 ↓
观测
 ↓
测试证据

这才是这一周真正想让我学会的东西。

W7 核心机制：Supervisor、Reflection 与 Harness

Mon, 21 Sep 2026 14:40:28 +0800

W7 核心机制：Supervisor、Reflection 与 Harness

第一篇把 W7 串成了一条主线。

这一篇不再按 Day1、Day2、Day3 去记，而是把整个系统拆成三个核心问题：

1
2
3


① 谁决定下一步？
② 谁负责把结果变好？
③ Agent 运行时需要哪些基础设施？

对应：

1
2
3


① Supervisor
② Reflection
③ Harness

一、先看完整系统

先不看代码。

只看这张图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


 用户任务
 │
 ▼
 ┌─────────────┐
 │ Supervisor │
 └──────┬──────┘
 │
 决定下一步是谁
 │
 ┌──────────────┼──────────────┐
 ↓ ↓ ↓
 Researcher Writer Reviewer
 │ │
 │ │
 └──────┬───────┘
 ↓
 Reflection
 │
 ┌────────┴────────┐
 ↓ ↓
 Critic Reviser
 │ │
 └──────→ Critic ←─┘
 │
 ↓
 END


 下面所有节点都运行在
 Harness
 │
 ┌─────────────────┼─────────────────┐
 ↓ ↓ ↓
 Registry Gate Session
 │ │
 ↓ ↓
 Executor Compactor
 
 
 Tracer

这时候要特别注意：

Supervisor、Reflection、Harness 不是三个平级功能。

它们解决的是三个不同层次的问题。

二、Supervisor：解决“下一步干什么”

Supervisor 的输入是：

1

当前 State

输出是：

1

next

例如：

1
2
3
4


{
 "next": "researcher",
 "reason": "目前还没有资料"
}

然后 LangGraph：

1
2
3
4
5


supervisor
 ↓
conditional edge
 ↓
researcher

所以 Supervisor 本身不负责：

1
2
3


查资料
写文章
审稿

它只负责：

选择下一个执行者。

三、Supervisor 为什么需要 State？

因为它不能凭空判断。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


第一次：
没有 researcher 资料
→ researcher

第二次：
有资料，没有文章
→ writer

第三次：
有文章，没有审核
→ reviewer

第四次：
审核通过
→ FINISH

因此 Supervisor 实际上是在：

1
2
3
4
5


读取 State
 ↓
理解当前进度
 ↓
做下一步决策

这就是：

State → Decision → Control Flow

四、Supervisor 的代码怎么读？

先找到：

1

def supervisor_node(state):

不要一行一行读。

先画：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


state
 ↓
rounds + 1
 ↓
是否超限？
 ├─ 是 → FINISH
 └─ 否
 ↓
System Prompt + messages
 ↓
router.invoke()
 ↓
Route
 ↓
next

然后再看：

1
2
3
4


router = router_llm.with_structured_output(
 Route,
 method="json_mode"
)

这句话真正的作用是：

1
2
3
4
5
6
7


LLM
 ↓
JSON
 ↓
Pydantic Route
 ↓
decision.next

所以它不是为了“写 JSON 好看”。

它是为了：

把模型的自然语言决策变成程序可以消费的控制数据。

五、为什么 `Literal` 很重要？

1
2
3
4
5
6
7


class Route(BaseModel):
 next: Literal[
 "researcher",
 "writer",
 "reviewer",
 "FINISH"
 ]

这里实际上是在告诉程序：

1

允许的控制流只有这几个

如果模型输出：

1

"next": "delete_database"

理论上就不应该进入合法流程。

所以：

1
2
3


Literal
=
控制流白名单

六、Reflection：解决“结果够不够好”

Supervisor 解决：

1

谁干活

Reflection 解决：

1

干出来的东西怎么样

它的流程：

1
2
3
4
5
6
7
8
9


generator
 ↓
critic
 ↓
route
 ├── end
 └── reviser
 ↓
 critic

七、Reflection 的 State 为什么这么多？

Day3 的 State：

1
2
3
4
5
6
7
8
9


topic
draft
score
issues
fatal_issues
revise_count
trajectory
best_draft
best_score

刚开始看会觉得：

为什么要这么多字段？

其实可以分成四组。

第一组：当前任务

1
2


topic
draft

第二组：当前评估

1
2
3


score
issues
fatal_issues

第三组：循环控制

1

revise_count

第四组：历史信息

1
2
3


trajectory
best_draft
best_score

这样一下就清楚了。

八、`trajectory` 为什么要用 Reducer？

1

trajectory: Annotated[list, operator.add]

普通字段：

1
2
3


新值
 ↓
覆盖旧值

Reducer：

1
2
3
4
5


旧值
+
新值
 ↓
合并

所以：

1
2
3


第1轮 → 7分
第2轮 → 8分
第3轮 → 8分

最终：

1
2
3
4
5


trajectory = [
 {"round": 0, "score": 7},
 {"round": 1, "score": 8},
 {"round": 2, "score": 8}
]

这时候它就不只是：

当前分数。

而是：

整个 Reflection 的历史轨迹。

九、为什么要保存 `best_draft`？

因为：

1

修改

不一定：

1

越改越好

可能：

1
2
3


v1 = 7分
v2 = 8分
v3 = 6分

如果最终直接拿：

1

v3

就把好结果改坏了。

所以保存：

1
2


best_draft = v2
best_score = 8

最后：

1

终稿 = best_draft

这个设计特别重要。

因为它承认一个事实：

LLM 的修改不是单调优化过程。

十、Reflection 的条件边怎么理解？

1

def route_after_critic(state):

不要先看代码。

先画决策树：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


critic
 │
 ├── 修改次数 >= MAX_REVISE
 │ ↓
 │ END
 │
 ├── 有 fatal issue
 │ ↓
 │ reviser
 │
 ├── score >= PASS_SCORE
 │ ↓
 │ END
 │
 ├── 分数下降
 │ ↓
 │ END
 │
 └── 其他
 ↓
 reviser

所以 Reflection 的本质就是：

一个有边界的反馈控制回路。

十一、Harness 五模块应该怎么理解？

现在进入另一条线。

不要死记五个名字。

按照 Agent 生命周期记：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


Agent 想做什么？
 ↓
Registry
 ↓
允许不允许？
 ↓
Gate
 ↓
真的执行
 ↓
Executor

执行过程中
 ↓
Session 保存状态
 ↓
Compactor 控制上下文
 ↓
Tracer 记录过程

这样五个模块就不会混。

十二、Registry：工具“有什么”

Registry 的职责：

1
2
3
4


注册
查询
搜索
执行入口

但它最重要的一条边界是：

Registry 不决定权限。

例如：

1

registry.is_dangerous("delete_file")

只是回答：

1

它危险吗？

不是：

1

现在允许执行吗？

后者是 Gate。

十三、为什么 Registry 要提供 `invoke()`？

代码里有：

1

registry.invoke(name, args)

而不是让外面：

1

spec.fn(...)

这是一个非常典型的封装边界。

如果以后：

1

ToolSpec.fn

改成：

1

ToolSpec.func

如果所有调用方都直接访问：

1

spec.fn

整个项目都要改。

但如果统一：

1

registry.invoke()

调用方不知道内部到底叫什么。

所以：

1
2
3
4
5
6
7


内部实现
 ↓
Registry
 ↓
统一接口
 ↓
外部调用方

这就是：

封装。

十四、Gate：工具“能不能用”

Gate 的判断：

1
2
3
4
5
6
7
8
9


工具存在？
 ↓
黑名单？
 ↓
危险工具？
 ↓
白名单？
 ↓
是否需要审批？

因此：

1
2
3


Registry = capability

Gate = authorization

这两个概念以后做 Agent 很容易混淆。

十五、Executor：工具“真的执行了吗”

Executor 是：

1
2
3


Gate
 ↓
真正执行

它特别强调：

1
2
3
4
5


{
 "ok": True,
 "executed": True,
 "result": ...
}

为什么要有：

1

executed

而不仅仅是：

1

ok

因为：

1

ok=False

可能有很多原因：

1
2
3


权限拒绝
人工拒绝
工具异常

所以：

1

ok

和：

1

executed

是两个不同维度。

十六、Session：Agent“经历过什么”

Session 保存：

1
2
3
4
5


thread_id
messages
meta
seq
timestamp

它回答：

这个 Agent 之前发生过什么？

注意：

1

Session

不是：

1

Memory

至少在这一周的实现里，它首先解决的是：

运行状态持久化。

比如：

1

thread_id = user-001

第一次：

1

你好

程序重启。

第二次：

1

继续刚才的事情

Session 可以恢复之前的状态。

十七、Compactor：Agent“现在需要看到什么”

Session 是：

1

全部历史

Compactor 是：

1

当前给 LLM 看的历史

所以：

1
2
3
4
5
6
7
8
9


Session
 ↓
全量历史
 ↓
Compactor
 ↓
当前上下文
 ↓
LLM

这就是为什么：

Session 和 Compactor 不能合并成一个东西。

因为：

1

事实存储

和：

1

视图生成

是两个不同职责。

十八、Tracer：Agent“刚才是怎么跑的”

Tracer 记录：

1
2
3
4
5


谁
什么时候
耗时
成功还是失败
父节点是谁

例如：

1
2
3


supervisor 300ms
 writer 200ms
 critic 150ms

于是可以定位：

1
2
3


哪里慢？
哪里炸？
谁调用谁？

十九、Audit 和 Trace 再区分一次

这是以后非常容易被问到的问题。

1
2
3


Audit
 ↓
“谁做了什么？”

1
2
3


Trace
 ↓
“系统是怎么跑的？”

例如：

1
2
3
4
5
6
7


Audit:
agent → delete_file → approval_granted

Trace:
supervisor 100ms
 writer 500ms
 critic 200ms

所以：

1
2
3


Audit = 安全 / 合规

Trace = 性能 / 排障

二十、Facade：为什么又套一个 Harness？

如果直接让业务代码：

1
2
3
4
5


registry = ...
gate = ...
session = ...
compactor = ...
tracer = ...

每个地方都自己组装。

以后会变成：

1
2


业务代码
到处 new 五个模块

所以：

1

Harness(...)

统一装配。

它不是：

第六个功能模块。

而是：

五个模块的装配入口。

这就是 Facade。

二十一、Facade 最重要的两个设计

第一：模块之间不要互相乱 import

理想结构：

1
2
3
4
5
6
7


Registry
Gate
Session
Compactor
Tracer
 ↓
 Harness

而不是：

1
2
3
4


Registry → Gate
Gate → Session
Session → Tracer
Tracer → Registry

否则容易循环依赖。

第二：LLM 从外面注入

不要：

1
2
3


class Harness:
 def __init__():
 self.llm = ChatOpenAI(...)

而是：

1

Harness(llm=llm)

这样：

1
2
3


DeepSeek
 ↓
换模型

只需要改装配层。

这就是依赖注入。

二十二、把三条线合在一起

现在可以画出 W7 真正的系统：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


 用户
 │
 ▼
 ┌─────────────┐
 │ Supervisor │
 └──────┬──────┘
 │
 ┌────────────┼────────────┐
 ↓ ↓ ↓
 Researcher Writer Reviewer
 │
 ↓
 Reflection
 │
 ┌──────────┴──────────┐
 ↓ ↓
 Critic Reviser
 │ │
 └──────────→──────────┘


 所有运行都依赖 Harness

 ┌─────────────────────────────────────────┐
 │ Harness │
 │ │
 │ Registry → Gate → Executor │
 │ │
 │ Session → Compactor │
 │ │
 │ Tracer │
 └─────────────────────────────────────────┘

这时候 W7 的架构就真正清楚了。

二十三、这也是为什么 Day6 才真正困难

因为 Day2：

1

Supervisor 自己能跑

Day3：

1

Reflection 自己能跑

Day4：

1

Registry/Gate 自己能跑

Day5：

1

Session/Compactor/Tracer 自己能跑

但是：

1
2
3
4
5


Supervisor
+
Reflection
+
Harness

真正接起来的时候，突然出现：

1
2
3
4


消息格式不同
State 不同
调用接口不同
依赖不同

这就是 Day6。

所以：

“单独能跑”不代表“系统能组合”。

这其实是 W7 最工程化的一课。

W7 总览：从多 Agent 流程到 Agent Harness

Mon, 21 Sep 2026 14:36:46 +0800

W7 总览：从多 Agent 流程到 Agent Harness

这一周的学习内容很多。

刚开始看，每天似乎都是一个新的知识点：

Supervisor
多 Agent
Structured Output
Reflection
Critic / Reviser
Tool Registry
Permission Gate
Session Store
Context Compaction
Tracer
Facade
测试
故障注入
最后还有一个 writer_pipeline.py

如果把这些东西一个个记，很容易变成：

“这些我都见过，但是如果让我从头解释整个 W7，我不知道它们为什么会出现在一起。”

所以 Day6 做的事情，其实就是让我重新回答一个问题：

这一周到底在造什么？

我现在对 W7 的理解是：

W7 不是单纯学习 Multi-Agent，而是在尝试把一个“会自己决定下一步的 Agent 系统”，逐渐变成一个具有路由、反思、工具权限、持久化、上下文管理和可观测能力的 Agent 应用。

也就是说，这一周其实有两条线。

W7 一页脑图版

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


 W7
 │
 ┌───────────────┴────────────────┐
 │ │
 Agent 大脑 Agent 身体
 │ │
 ▼ ▼
 Supervisor Harness
 │ │
 决定下一步 ┌─────┼─────┐
 │ ↓ ↓ ↓
 ┌──────┼──────┐ Registry Gate Session
 ↓ ↓ ↓ │ │ │
Research Writer Reviewer │ │ ↓
 │ │ │ Compactor
 ↓ │ │ │
 Reflection │ │ ↓
 │ │ │ LLM
 ┌────┴────┐ │ │
 ↓ ↓ │ ↓
 Critic Reviser │ Executor
 ↑ │ │
 └─────────┘ │
 ↓
 Tracer

 ↓
 Day6 Integration
 ↓
 ┌─────────────┼─────────────┐
 ↓ ↓ ↓
 消息适配 窄接口 五模块实际生效
 ↓ ↓ ↓
 LangChain msg ReflectionResult 文件/日志/trace
 │ │ │
 └─────────────┼─────────────┘
 ↓
 端到端
 ↓
 故障注入
 ↓
 测试证据

一、第一条线：Agent 的“脑子”越来越复杂

这一条线是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Supervisor
 ↓
多个 Worker
 ↓
Reflection
 ↓
Critic
 ↓
Reviser
 ↓
重新评审

它解决的是：

一个 LLM 不够用了，如何让多个角色协作，并且让结果能够自我检查和修改？

二、第二条线：Agent 的“身体”越来越完整

另一条线是 Harness：

1
2
3
4
5
6
7
8
9


Tool Registry
 ↓
Permission Gate
 ↓
Executor

Session Store
Context Compactor
Tracer

它解决的是另外一类问题：

Agent 会思考还不够，它真正运行的时候，工具怎么管理？危险操作怎么办？上下文太长怎么办？重启之后怎么办？出了问题怎么查？

所以我现在可以把 W7 看成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 ┌──────────────────────┐
 │ Agent 大脑 │
 │ │
用户任务 → Supervisor → Worker → Reflection
 │ │
 └──────────┬───────────┘
 │
 ▼
 ┌──────────────────────┐
 │ Agent Harness │
 │ │
 │ Registry │
 │ Permission Gate │
 │ Session Store │
 │ Context Compactor │
 │ Tracer │
 └──────────────────────┘

前半部分解决：

怎么想、怎么分工、怎么反思。

后半部分解决：

怎么安全、稳定、可持续地运行。

而 Day6 的任务就是：

把这两个世界真正接起来。

二、Day1：先设计“机器长什么样”

W7 的第一天实际上更像架构设计，而不是继续学习某个 API。

这一阶段最重要的不是代码，而是先确定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


用户
 ↓
Supervisor
 ↓
Researcher
 ↓
Writer
 ↓
Reviewer
 ↓
是否需要修改？
 ├─ 是 → Writer
 └─ 否 → FINISH

同时开始考虑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Agent
 ↓
Tools
 ↓
权限
 ↓
状态
 ↓
上下文
 ↓
追踪

所以 Day1 给后面留下了两张图：

第一张图：Agent 编排图

1
2
3
4
5
6
7
8
9


Supervisor
 │
 ├── Researcher
 │
 ├── Writer
 │
 └── Reviewer
 │
 └── 需要修改 → Writer

第二张图：Harness 图

1
2
3
4
5
6
7


Agent
 │
 ├── Registry
 ├── Gate
 ├── Session
 ├── Compactor
 └── Tracer

后面所有代码其实都是在把这两张图变成真实程序。

所以我发现：

复杂项目不能一上来就读代码。

先画结构，才能知道代码里的函数到底属于哪一个盒子。

三、Day2：先解决“多个 Agent 怎么协作”

Day2 开始真正写 Supervisor。

核心文件是：

1

supervisor_demo.py

它解决的问题非常明确：

不是让三个 Agent 自己聊天，而是增加一个 Supervisor，决定下一步应该谁工作。

整体结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


START
 ↓
supervisor
 ↓
根据 next 决定
 ├── researcher
 ├── writer
 ├── reviewer
 └── FINISH
 ↑
 │
worker ─┘

这里有一个非常重要的理解：

Worker 不负责决定流程

Worker 只负责：

1
2
3
4
5


收到任务
 ↓
干自己的活
 ↓
交活

Supervisor 负责：

1
2
3
4
5


看当前状态
 ↓
判断缺什么
 ↓
决定下一步

所以：

1
2
3


Worker = 干活

Supervisor = 调度

这其实已经非常接近真实 Agent 系统里的：

1
2
3


执行者
vs
Orchestrator

四、为什么 Supervisor 需要 Structured Output？

Supervisor 的输出不能是：

1

“我觉得下一步应该让研究员继续。”

因为程序没法稳定解析。

所以 Day2 定义：

1
2
3
4
5
6
7
8


class Route(BaseModel):
 next: Literal[
 "researcher",
 "writer",
 "reviewer",
 "FINISH"
 ]
 reason: str

于是模型输出变成：

1
2
3
4


{
 "next": "researcher",
 "reason": "还没有资料"
}

这时候：

1
2
3
4
5
6
7
8
9


LLM
 ↓
Route
 ↓
state["next"]
 ↓
conditional edge
 ↓
worker

整个链条就变成程序可以控制的东西。

这也是我之前学习 Structured Output 时理解的东西，在 W7 真正落到了实际项目里：

LLM 可以负责做判断，但程序不能直接把自然语言判断当成控制流。

所以：

1
2
3
4
5


自然语言
 ↓
结构化结果
 ↓
程序控制流程

是 Agent 工程里非常重要的一层。

五、Day2 真正让我学到的不是 Supervisor，而是“控制流”

如果只记：

Supervisor 是一个调度 Agent。

其实还是浅。

真正应该记住的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


State
 ↓
Supervisor 判断
 ↓
next
 ↓
Conditional Edge
 ↓
Worker
 ↓
State 更新
 ↓
Supervisor 再判断

所以 Supervisor 本质上是在控制：

Control Flow

而 messages 等字段承载的是：

Data Flow

这两个东西必须分开看。

例如：

1

next = "writer"

是控制流。

而：

1

messages = [...]

是数据流。

这是 W7 开始变复杂以后，非常重要的一种阅读代码方式。

六、Day3：发现一个新问题——Agent 会一直改

Day2 解决：

多个 Agent 怎么协作？

Day3 开始解决：

一个 Agent 产出的结果，怎么知道够不够好？

于是出现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


generator
 ↓
critic
 ↓
reviser
 ↓
critic
 ↓
reviser
 ↓
...

也就是 Reflection。

核心文件：

1

reflection_graph.py

七、Reflection 本质上是一个反馈控制回路

如果把它抽象出来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


生成
 ↓
评价
 ↓
发现问题
 ↓
修改
 ↓
重新评价
 ↓
是否达标？
 ├── 是 → END
 └── 否 → 修改

这其实不是简单的：

“再调用一次 LLM。”

而是：

让一次 Agent 执行拥有反馈回路。

所以 Day3 的重点其实是：

1
2
3
4
5
6
7


生成器
+
评价器
+
修改器
+
停止条件

八、为什么 Reflection 必须有停止条件？

因为：

1

critic → reviser → critic → reviser

天然就是一个循环。

如果没有出口：

1
2
3


无限调用
无限 Token
无限成本

所以 Day3 设计了三个出口条件。

1. 分数达标

1
2


if score >= PASS_SCORE:
 return "end"

比如：

1

8 分以上 → 结束

2. 修改次数达到上限

1
2


if count >= MAX_REVISE:
 return "end"

例如：

1

最多修改 3 次

这解决的是：

即使永远达不到标准，也不能无限烧钱。

3. 停滞

例如：

1
2
3


第一次 7 分
第二次 7 分
第三次 6 分

说明继续改可能没有价值。

于是：

1
2
3
4
5


改了
 ↓
没有变好
 ↓
停止

九、Day3 又学到一个非常重要的东西：不要完全相信模型自己

Critic 有：

1

passed: bool

模型可以告诉程序：

1

passed = True

但代码没有直接相信它。

而是：

1

passed_by_code = score >= PASS_SCORE

也就是说：

1
2
3
4
5


模型负责提供：
score

程序负责决定：
passed

这和之前 Structured Output 的思想是一致的：

让模型提供信息，但关键控制权留在程序。

十、Day3 又增加了“硬伤”

这比普通评分更重要。

比如一篇文章：

1

评分：9 分

但是：

1

编造了一个数据

这时候不能说：

9 分，所以通过。

因此增加：

1

fatal_issues

形成：

1
2
3
4
5


score >= 8
 │
 ├── 没硬伤 → 可以通过
 │
 └── 有硬伤 → 不通过

所以：

分数是质量指标，fatal issue 是硬约束。

这已经开始接近真正的 Agent 评估系统：

1
2
3


软指标
+
硬约束

十一、Day4：Agent 不只是“会用工具”，还必须“受管控”

到了 Day4，问题又变化了。

前面我们讨论：

Agent 怎么思考？

现在开始讨论：

Agent 想调用工具的时候，真的可以随便调用吗？

答案当然不是。

例如：

1

search_web

和：

1
2
3


delete_file
publish_article
send_money

风险完全不同。

所以 Day4 开始建立 Harness 的前两块：

1
2
3
4
5


Tool Registry
 ↓
Permission Gate
 ↓
Executor

十二、Tool Registry 是什么？

我现在更倾向于把 Registry 理解成：

Agent 的工具通讯录。

里面记录：

1
2
3
4
5


工具名
工具函数
描述
权限等级
标签

例如：

1
2
3
4
5


search_web
level = safe

delete_file
level = dangerous

Registry 负责回答：

1
2
3
4


有什么工具？
这个工具存在吗？
这个工具是什么？
它危险吗？

但它不负责：

“这个 Agent 现在能不能用。”

这个事情交给 Gate。

所以：

1
2
3


Registry = 能力目录

Gate = 权限判断

这个边界非常重要。

十三、为什么需要 Permission Gate？

如果没有 Gate：

1
2
3


LLM
 ↓
工具

模型一旦输出：

1

delete_file(...)

程序就可能直接执行。

所以加：

1
2
3
4
5
6
7
8
9


LLM
 ↓
Tool Registry
 ↓
Permission Gate
 ↓
Executor
 ↓
真正工具

Gate 有三个结果：

1
2
3


ALLOW
DENY
NEED_APPROVAL

也就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


普通工具
 ↓
直接允许

危险工具
 ↓
需要人工确认

黑名单工具
 ↓
直接拒绝

十四、Day4 真正重要的是“拒绝以后真的不能执行”

测试不能只写：

1

assert result == "拒绝"

因为可能出现：

1
2


返回结果说拒绝
但是工具实际上已经执行

所以测试里专门准备：

1

CALLS = []

工具真正执行的时候：

1

CALLS.append("delete_file")

然后验证：

1
2
3


Gate 拒绝
 ↓
CALLS == []

这才证明：

拒绝不是嘴上拒绝，而是执行路径真的没有发生。

这是我这一周对“测试”的一个重要理解：

不要只测返回值，要测副作用。

十五、Day5：Harness 开始从“安全”变成“完整运行环境”

Day4 主要解决：

1
2
3
4


工具
权限
审批
审计

Day5 又增加：

1
2
3
4


Session Store
Context Compactor
Tracer
Harness Facade

于是五模块终于形成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


 Harness
 │
 ┌──────────────┼──────────────┐
 ↓ ↓ ↓
Registry Gate Session
 
 ↓
 Compactor
 
 ↓
 Tracer

这时候我才真正理解：

Harness 不是 Agent 的“大脑”。

它更像：

Agent 运行时的基础设施层。

十六、Session Store：让 Agent 能“记住运行状态”

Session Store 解决：

程序重启之后，之前的会话还在不在？

如果只有：

1

self._mem = {}

那么：

1
2
3
4
5


程序退出
 ↓
内存消失
 ↓
全部历史消失

所以 Day5 增加 JSONL：

1

writer_sessions.jsonl

存：

1
2
3
4
5


thread_id
seq
messages
meta
timestamp

于是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


第一次进程
 ↓
append
 ↓
JSONL

程序退出

第二次进程
 ↓
SessionStore(path)
 ↓
load
 ↓
恢复历史

十七、为什么 Session Store 存“全量”，而不是存压缩结果？

这是 Day5 一个非常值得记住的设计决策。

假设：

1
2


今天压缩策略：
max_messages = 20

明天发现：

1
2


20 太多了
改成 10

如果数据库里已经保存的是压缩结果：

1

早期消息已经永久丢失

但如果：

1
2
3
4
5
6
7


Session Store
 ↓
保存全量历史

Compactor
 ↓
读取时做投影

那么：

1
2
3
4
5


原始数据
 ↓
策略 A → 一个视图
 ↓
策略 B → 另一个视图

所以：

Session Store 是事实来源，Compactor 是视图。

这个思想其实非常像：

1
2
3


原始日志
+
按需投影

十八、Context Compactor：不是删除历史，而是改变给模型看的视图

假设有：

1

41 条消息

但模型只需要：

1
2
3


最近 6 条
+
早期内容摘要

于是：

1
2
3
4
5
6
7
8
9


41 条原始消息
 ↓
 Compactor
 ↓
┌───────────────┐
│ system │
│ 历史摘要 │
│ recent 6 条 │
└───────────────┘

关键点：

压缩不是销毁。

原始数据仍然在 Session Store。

十九、Context Compactor 最容易出现的坑：Tool Call 不能拆

比如：

1
2
3
4
5


assistant
 tool_calls = call_1

tool
 tool_call_id = call_1

这两个实际上是一对。

如果压缩的时候：

1
2


删掉 assistant
保留 tool

就变成：

1

tool(call_1)

但是找不到：

1

谁发起了 call_1？

于是就可能出现 API 错误。

所以 _safe_cut() 做的事情不是：

“随便从第 N 条切。”

而是：

如果切点正好落在 tool 结果上，就往前退，确保完整保留这一组。

这个地方让我开始真正意识到：

上下文压缩不是简单的 list[:N]。

它已经涉及消息协议的结构约束。

二十、Tracer：解决“为什么慢、为什么炸”

Tracer 和 Audit 很容易混。

但它们解决的问题完全不同。

Audit

回答：

谁做了什么决定？

例如：

1
2
3


agent
delete_file
approval_granted

主要用于：

1
2
3


安全
审计
追责

Trace

回答：

程序到底怎么跑的？哪一步慢？谁调用了谁？

例如：

1
2
3


supervisor 300ms
 writer 200ms
 critic 150ms

于是可以看到：

1
2
3


父节点
 └── 子节点
 └── 更深子节点

所以：

Audit 是安全视角。

Trace 是运行视角。

二十一、Tracer 为什么需要 contextvars？

因为嵌套调用的时候，需要知道：

1

当前是谁？

比如：

1
2
3


outer()
 ↓
inner()

Tracer 要记录：

1
2


outer
 └── inner

所以使用：

1

_current

保存当前 span。

进入：

1
2
3


outer
 ↓
_current = outer

再进入：

1
2
3


inner
 ↓
parent = outer

于是：

1

inner.parent_id = outer.span_id

最后就能恢复出树。

二十二、Day5 结束时，我实际上已经拥有了一套 Agent 基础设施

到这里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 Agent
 │
 ┌───────┴───────┐
 ↓ ↓
 Tools State
 │ │
 Registry Session
 │ │
 Gate Compactor
 │
 Executor
 
 + Tracer
 + Audit

但是：

这些东西还是零件。

它们之间还没有真正装起来。

这就是 Day6。

二十三、Day6：真正的任务不是“继续写功能”

Day6 的一句话我现在可以重新理解成：

Day1–Day5 造零件，Day6 装机器。

Day6 材料里明确把今天的交付定义成：

1
2
3
4
5
6


① 端到端跑通
② 拓扑图和设计一致
③ 五模块全部实际生效
④ 故障注入
⑤ README
⑥ 3 分钟讲法

而且特别强调：

“接了”不等于“有用”。

代码里：

1

import Tracer

只能证明：

1

Tracer 被导入了

不能证明：

1

Tracer 真正在记录

真正的验收应该是：

1
2
3


trace.jsonl
audit.log
writer_sessions.jsonl

这些东西真的产生了。

二十四、所以我现在可以把整个 W7 串成一条线

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


Day1
架构设计
 ↓
Day2
Supervisor
 ↓
解决“多人怎么协作”
 ↓
Day3
Reflection
 ↓
解决“结果怎么自我检查”
 ↓
Day4
Registry + Gate + Executor
 ↓
解决“Agent 怎么安全使用工具”
 ↓
Day5
Session + Compactor + Tracer + Facade
 ↓
解决“Agent 怎么长期、稳定、可观察地运行”
 ↓
Day6
Integration
 ↓
解决“这些零件怎么真正接在一起”

所以 W7 的真正主线不是：

1
2
3
4
5
6
7


Supervisor
Reflection
Registry
Gate
Session
Compactor
Tracer

这些知识点的简单堆积。

而是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


一个 Agent 系统
 ↓
会思考
 ↓
会协作
 ↓
会反思
 ↓
会使用工具
 ↓
不会随便使用危险工具
 ↓
能保存状态
 ↓
能控制上下文
 ↓
能追踪运行过程
 ↓
最后把这些东西组合成完整系统

这才是 W7。

二十五、我现在对 W7 最大的理解变化

以前我容易把 Agent 理解成：

1
2
3
4
5


LLM
 ↓
Tool
 ↓
Result

W7 之后，这个模型已经不够了。

现在更接近：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


 ┌───────────────┐
 │ Supervisor │
 └───────┬───────┘
 │
 ┌─────────────┼─────────────┐
 ↓ ↓ ↓
 Researcher Writer Reviewer
 │
 ↓
 Reflection
 │
 ┌──────┴──────┐
 ↓ ↓
 Critic Reviser
 
 │
 ↓
 ┌─────────────┐
 │ Harness │
 ├─────────────┤
 │ Registry │
 │ Gate │
 │ Session │
 │ Compactor │
 │ Tracer │
 └─────────────┘

也就是说：

LLM 只是系统中的一个决策组件。

真正的 Agent 应用，是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


LLM
+
Workflow
+
State
+
Tools
+
Permissions
+
Persistence
+
Context Management
+
Observability
+
Evaluation

这也是我觉得 W7 比前面的单个 LangGraph API 更重要的地方。

它开始从：

“我会不会写一个 Agent？”

进入：

“我能不能设计一个真正可以运行、可以验证、可以排错的 Agent 系统？”

二十六、W7 最后留下的一个工程思维

这周我越来越明显地感觉到：

真正复杂的不是代码本身，而是模块之间的边界。

Day6 就是最典型的例子。

每一个模块单独看都不复杂：

1
2
3
4
5
6
7


Supervisor
Reflection
Registry
Gate
Session
Compactor
Tracer

真正困难的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


A 输出什么？
 ↓
B 接受什么？
 ↓
两边的数据结构是不是一样？
 ↓
谁负责转换？
 ↓
谁负责判断？
 ↓
谁负责执行？
 ↓
谁负责记录？

所以以后再看到复杂代码，我不能只问：

“这个函数是干什么的？”

还应该问：

“它和前后模块的接缝是什么？”

这可能是 W7 最重要的一次学习升级。

W7-D4｜Tool Registry + Permission Gate：给 Agent 加上工具注册表和权限闸门

Thu, 17 Sep 2026 13:54:20 +0800

W7-D4｜Tool Registry + Permission Gate：给 Agent 加上工具注册表和权限闸门

今天第一次接触 Harness。

之前学 LangGraph 时，我一直在解决“Agent 怎么跑”的问题：

State 怎么流

节点怎么走

条件边怎么决定下一步

HITL 怎么暂停和恢复

今天开始换一个问题：

Agent 想调用工具的时候，谁来管理这些工具？谁决定这个工具能不能真的执行？

今天做的就是两层：

Tool Registry：工具登记处

Permission Gate：工具闸门

一、先看整体：今天到底给 Agent 加了什么

以前可能是这种结构：

1
2
3
4
5
6


Agent
 │
 ├── read_file()
 ├── search_web()
 ├── delete_file()
 └── send_email()

工具多起来以后，工具散落在代码各处。

Agent 知道某个函数存在，就直接调用：

1
2
3
4
5


Agent
 ↓
直接调用工具
 ↓
执行

问题就来了：

工具在哪里？
工具有哪些？
工具的名字是什么？
参数怎么传？
这个工具危险不危险？
危险工具能不能直接执行？
谁审批过？

所以今天加一层 Harness：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 ┌───────────────┐
 │ Agent │
 └───────┬───────┘
 │
 想调用某个工具
 ↓
 ┌──────────────────┐
 │ Tool Registry │
 │ 工具注册表 │
 └────────┬─────────┘
 │
 找到工具 + 元数据
 ↓
 ┌──────────────────┐
 │ Permission Gate │
 │ 权限闸门 │
 └────────┬─────────┘
 │
 ┌─────────────┼─────────────┐
 ↓ ↓ ↓
 allow deny need_approval
 │ │
 ↓ ↓
 执行工具 等待人工审批

所以今天新增的不是一种“新的 Agent”。

而是在：

Agent 和真正执行工具之间，加了一层统一管理和控制。

二、今天解决的其实是两个不同问题

这两个东西很容易混在一起。

1. Registry 解决“这个工具是什么”

Registry 更像工具目录。

它负责：

1
2
3
4
5


名字
 ↓
找到工具
 ↓
拿到工具信息

例如：

1
2
3
4
5


delete_file
 ↓
找到真正的 delete_file 函数
 ↓
知道它是 high risk

所以 Registry 的核心问题是：

“我有哪些工具，它们分别是什么？”

2. Permission Gate 解决“这个工具现在能不能执行”

Gate 不负责寻找工具。

它只判断：

1
2
3
4
5


这个工具
 ↓
当前条件
 ↓
允许吗？

例如：

1
2
3
4
5


read_file
 ↓
low risk
 ↓
allow

而：

1
2
3
4
5


delete_file
 ↓
high risk
 ↓
need_approval

所以可以简单记成：

模块	解决的问题
Tool Registry	工具是谁
Permission Gate	工具现在能不能执行

这两个问题一定要分开。

三、先看 Tool Registry 的核心结构

先不管装饰器。

假设最简单的工具注册表是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class ToolRegistry:
 def __init__(self):
 self._tools = {}

 def register(self, name, description, risk, func):
 self._tools[name] = {
 "name": name,
 "description": description,
 "risk": risk,
 "func": func,
 }

 def get(self, name):
 return self._tools[name]

这里其实没有什么神秘东西。

本质就是一个字典：

1
2
3


工具名
 ↓
工具信息

例如：

1
2
3
4
5
6
7
8


{
 "delete_file": {
 "name": "delete_file",
 "description": "删除文件",
 "risk": "high",
 "func": delete_file
 }
}

这样 Agent 以后就不需要到处找函数。

只需要：

1

registry.get("delete_file")

就能拿到整个工具描述。

四、为什么工具不直接放函数，还要包一层 ToolSpec？

实际代码里通常不会一直使用这种裸字典。

更适合定义一个工具描述对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from dataclasses import dataclass
from typing import Callable


@dataclass
class ToolSpec:
 name: str
 description: str
 risk: str
 func: Callable

然后 Registry：

1
2
3
4
5
6
7
8
9


class ToolRegistry:
 def __init__(self):
 self._tools = {}

 def register(self, spec: ToolSpec):
 self._tools[spec.name] = spec

 def get(self, name: str) -> ToolSpec:
 return self._tools[name]

现在注册表里面保存的就不是一堆散乱字段，而是完整的：

1
2
3
4
5


ToolSpec
├── name
├── description
├── risk
└── func

这其实是在做一件非常工程化的事情：

把“一个工具”和“这个工具的描述信息”绑在一起。

以后权限判断、日志、工具发现、参数校验都可以继续往 ToolSpec 上挂。

五、然后问题来了：工具一个个手动 register 很麻烦

如果每个工具都这样写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def read_file(path):
 ...


registry.register(
 ToolSpec(
 name="read_file",
 description="读取文件",
 risk="low",
 func=read_file,
 )
)

工具少的时候还能接受。

工具多以后就很烦。

而且：

1
2
3
4


def read_file(...):
 ...

registry.register(...)

工具代码和“注册动作”是分开的。

能不能写成：

1
2
3


@registry.register(...)
def read_file(...):
 ...

这就进入今天第一次真正遇到的东西：

装饰器

六、装饰器到底是什么

我以前看到：

1
2
3


@xxx
def foo():
 ...

容易把它理解成：

“这是某种特殊语法。”

实际上没有那么神秘。

装饰器最核心的思想只有一句：

把一个函数作为参数传进去，返回一个处理后的函数对象。

最简单的例子：

1
2
3
4
5
6
7


def decorator(func):
 def wrapper():
 print("调用前")
 func()
 print("调用后")

 return wrapper

然后：

1
2
3


@decorator
def hello():
 print("hello")

它其实等价于：

1
2
3
4


def hello():
 print("hello")

hello = decorator(hello)

这就是装饰器最关键的理解点。

七、所以 `@decorator` 到底做了什么？

假设：

1
2
3


@decorator
def hello():
 print("hello")

Python 不会把 @decorator 当成一个神秘标签。

它实际上是在做：

1
2
3
4
5
6
7


先创建 hello 函数
 ↓
把 hello 作为参数传给 decorator
 ↓
decorator 返回一个函数
 ↓
再把返回结果重新绑定给 hello

也就是：

1

hello = decorator(hello)

所以：

装饰器的本质，就是“函数加工”。

八、为什么今天的 Registry 特别适合用装饰器

回到今天。

我们希望：

1
2
3


@registry.register(...)
def read_file(path):
 ...

意思其实非常直白：

“定义这个函数的时候，顺手把它登记进 Registry。”

也就是说：

1
2
3


定义工具
 +
注册工具

合并成了一件事。

这不是为了炫技。

它解决的是：

避免“工具定义”和“工具注册”分离。

九、这里有一个比普通装饰器更重要的细节

你今天很可能会看到：

1
2
3
4
5
6
7


@registry.register(
 name="read_file",
 description="读取文件",
 risk="low",
)
def read_file(path):
 ...

你可能会疑惑：

register() 明明需要参数，为什么最后还能接收到 read_file？

这里是装饰器最容易卡住的地方。

因为这里其实有两层调用。

第一层：先执行 `register(...)`

1
2
3
4
5


registry.register(
 name="read_file",
 description="读取文件",
 risk="low",
)

这一步还没有拿到 read_file。

它的任务只是：

根据这些配置，创建一个真正的装饰器。

可以理解成：

1
2
3


register(...)
 ↓
得到 decorator

第二层：Python 再把函数交给这个 decorator

然后定义：

1
2


def read_file(path):
 ...

Python 再做：

1

decorator(read_file)

也就是说整个过程实际上类似：

1
2
3
4
5
6
7


decorator = registry.register(
 name="read_file",
 description="读取文件",
 risk="low",
)

read_file = decorator(read_file)

这才是：

1
2
3


@registry.register(...)
def read_file(...):
 ...

真正发生的事情。

十、所以 Tool Registry 的装饰器可以这样写

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


from dataclasses import dataclass
from typing import Callable


@dataclass
class ToolSpec:
 name: str
 description: str
 risk: str
 func: Callable


class ToolRegistry:
 def __init__(self):
 self._tools = {}

 def register(self, name, description, risk):
 def decorator(func):
 spec = ToolSpec(
 name=name,
 description=description,
 risk=risk,
 func=func,
 )

 self._tools[name] = spec

 return func

 return decorator

这里的结构值得认真看。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


register(...)
 ↓
返回 decorator
 ↓
decorator(func)
 ↓
创建 ToolSpec
 ↓
放进 self._tools
 ↓
返回原函数

这里出现了一个新的知识：

函数里面还定义函数。

这叫嵌套函数。

而 decorator() 能记住外面的：

1
2
3


name
description
risk

是因为它形成了闭包。

你今天不需要深入学闭包底层，但至少先知道：

decorator() 虽然执行时接收到的参数只有 func，但它还能使用外层 register() 的 name / description / risk。

这是装饰器里非常常见的写法。

十一、为什么最后要 `return func`？

这是今天一个非常值得注意的细节。

1
2
3


def decorator(func):
 ...
 return func

为什么注册完以后不返回 None？

因为：

1
2
3


@registry.register(...)
def read_file(...):
 ...

最终等价于：

1

read_file = decorator(read_file)

如果：

1

decorator(...)

返回 None：

1

read_file = None

那原本的：

1

read_file(...)

以后就不能调用了。

所以这里选择：

1

return func

意味着：

我完成了登记，但不改变这个函数本身。

因此：

1
2
3


Registry
 ├── 保存了一份工具信息
 └── 原函数依然还是原函数

这是今天这个装饰器实现和很多“包装型装饰器”很重要的区别。

十二、这和 LangChain 里的 `@tool` 不完全是一回事

这里很容易产生一个误解：

“装饰器不是就是 @tool 吗？”

不是。

@tool 只是使用了装饰器语法。

至于这个装饰器具体干什么，要看实现。

例如我们今天自己的：

1
2
3


@registry.register(...)
def read_file(...):
 ...

本质上只是：

1

把函数登记进 Registry

原函数仍然返回。

而某些框架里的：

1
2
3


@tool
def search(...):
 ...

可能会：

1
2
3
4
5
6
7
8
9


普通 Python 函数
 ↓
转换成 Tool 对象
 ↓
增加 schema
 ↓
增加描述
 ↓
变成框架可调用对象

所以以后看到：

1

@xxx

不要先问：

“这个装饰器是什么意思？”

应该先问：

“这个装饰器拿到原函数以后，对它做了什么？”

这个思维比死记 @tool 有用得多。

十三、Registry 解决了工具管理，但它仍然没有权限

现在假设：

1
2
3
4
5
6
7


@registry.register(
 name="read_file",
 description="读取文件",
 risk="low",
)
def read_file(path):
 return f"读取 {path}"

以及：

1
2
3
4
5
6
7


@registry.register(
 name="delete_file",
 description="删除文件",
 risk="high",
)
def delete_file(path):
 return f"删除 {path}"

Registry 可以知道：

1
2
3
4
5


read_file
 risk = low

delete_file
 risk = high

但是：

知道风险，不等于阻止执行。

这就是 Permission Gate 出场的原因。

十四、Permission Gate 是什么

Permission Gate 本质上就是一个决策函数。

输入：

1
2
3


工具信息
+
当前权限条件

输出：

1
2
3


allow
deny
need_approval

可以先写成最简单的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from typing import Literal

Decision = Literal["allow", "deny", "need_approval"]


class PermissionGate:

 def check(self, tool: ToolSpec) -> Decision:
 if tool.risk == "low":
 return "allow"

 if tool.risk == "high":
 return "need_approval"

 return "deny"

这里其实非常简单。

它不是执行器。

它只是：

判断能不能执行。

十五、为什么这里要把 Gate 和工具本身分开？

这是今天真正的工程设计。

错误的写法可能是：

1
2
3


def delete_file(path):
 if user_is_admin():
 ...

这样每个工具自己负责权限。

最后就会变成：

1
2
3
4
5


read_file 自己判断权限
delete_file 自己判断权限
send_email 自己判断权限
pay_money 自己判断权限
...

权限逻辑散落整个项目。

以后规则一改：

1

所有 high-risk 工具都需要审批

你就得改很多地方。

而现在：

1
2
3
4
5
6
7


Tool
 ↓
只负责“怎么做”

PermissionGate
 ↓
负责“允许不允许做”

职责就清楚了。

十六、所以今天真正形成了“能力”和“策略”的分离

这个可以作为今天最重要的一句话：

1
2
3
4
5


Tool
= 我能做什么

Permission Gate
= 我现在允不允许做

例如：

1

delete_file

本身具备：

删除文件的能力。

但：

1

PermissionGate

可以决定：

1
2


普通情况下 → deny
人工审批后 → allow

所以：

工具负责能力，Gate 负责策略。

这也是 Harness 开始有意义的地方。

十七、把 Registry + Gate 串起来

真正的工具调用入口可以设计成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


def call_tool(
 registry: ToolRegistry,
 gate: PermissionGate,
 tool_name: str,
 args: dict,
 approved: bool = False,
):
 tool = registry.get(tool_name)

 decision = gate.check(tool)

 if decision == "deny":
 return "permission denied"

 if decision == "need_approval" and not approved:
 return "approval required"

 return tool.func(**args)

这段代码非常重要。

因为它第一次把今天两个组件连接起来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


tool_name
 ↓
Registry
 ↓
找到 ToolSpec
 ↓
PermissionGate
 ↓
判断
 ↓
allow？
 ↓
真正执行 func

十八、这里要特别区分“逻辑流”和“数据流”

逻辑流

谁决定下一步？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


call_tool()
 ↓
Registry.get()
 ↓
拿到 ToolSpec
 ↓
Gate.check()
 ↓
decision
 ↓
allow / deny / need_approval
 ↓
决定是否进入 func()

真正决定流程走向的是：

1

decision

数据流

什么东西在流动？

最开始有：

1
2


tool_name = "delete_file"
args = {"path": "a.txt"}

先经过 Registry：

1
2
3


"delete_file"
 ↓
ToolSpec

然后 Gate 使用：

1
2
3


ToolSpec
 ↓
decision

最后真正执行：

1

tool.func(**args)

所以：

1
2
3
4
5
6
7
8
9


tool_name
 ↓
ToolSpec
 ↓
decision
 ↓
tool.func + args
 ↓
result

十九、一个完整调用到底发生了什么

假设 Agent 想做：

1
2
3
4
5
6


call_tool(
 registry,
 gate,
 "delete_file",
 {"path": "a.txt"},
)

完整执行链：

第一步：Agent 提出工具调用

1

delete_file

同时给参数：

1

path = a.txt

第二步：Registry 查询

1

registry.get("delete_file")

得到：

1
2
3
4
5
6


ToolSpec(
 name="delete_file",
 description="删除文件",
 risk="high",
 func=<真正的 delete_file 函数>
)

第三步：Gate 判断

1

gate.check(tool)

因为：

1

risk = high

所以：

1

need_approval

第四步：流程暂停

这时候不能直接执行：

1

tool.func(...)

而是应该进入人工审批流程。

这就连接到了你 W6 学过的：

1

HITL

逻辑变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Agent
 ↓
Tool Registry
 ↓
Permission Gate
 ↓
need_approval
 ↓
HITL
 ↓
人工决定
 ↓
allow / deny

所以今天没有凭空出现一个新概念。

而是：

W6 学过的 HITL，今天被重新利用到了工具权限控制上。

二十、审批以后发生什么

假设人工允许：

1

approved = True

再次进入：

1

call_tool(...)

或者把审批结果继续传回原流程。

最终：

1
2
3
4
5
6
7
8
9


PermissionGate
 ↓
allow
 ↓
tool.func(**args)
 ↓
delete_file("a.txt")
 ↓
result

所以完整链路就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


Agent
 ↓
选择工具
 ↓
Registry 找工具
 ↓
拿到 ToolSpec
 ↓
PermissionGate 判断
 ↓
┌───────────────┬──────────────┬─────────────────┐
│ allow │ deny │ need_approval │
│ ↓ │ ↓ │ ↓ │
│ 执行工具 │ 直接拒绝 │ HITL │
│ │ │ ↓ │
│ │ │ 人工审批 │
│ │ │ ↓ │
│ │ │ allow │
└───────────────┴──────────────┴────────┬────────┘
 ↓
 执行工具
 ↓
 result

这就是今天整个任务。

二十一、为什么今天的 Registry 不能顺便做权限判断？

当然可以。

从“能不能写出来”的角度：

1

registry.get(...)

里面也可以判断权限。

但这样会把两个完全不同的问题混在一起：

1
2
3


工具管理
+
权限管理

未来 Registry 还要负责：

工具发现
名称冲突
schema
描述
工具列表

Permission Gate 还要负责：

risk
allow
deny
approval
用户权限
环境限制

所以把它们拆开，是为了以后能够独立演化。

今天虽然代码不多，但已经开始进入真正的工程设计：

不是“能不能运行”，而是“职责是不是清楚”。

二十二、今天一个很重要的边界：Gate 不是安全魔法

这里也要保持一个工程上的清醒。

如果项目里同时存在：

1

call_tool(...)

和：

1

delete_file(...)

那么程序员完全可以绕过 Gate：

1

delete_file("a.txt")

所以今天这种 Permission Gate 的设计，更准确地说是：

统一的工具执行控制入口。

如果真正想做到严格权限控制，就必须让“工具执行”本身经过统一边界。

也就是说：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


不应该：

Agent → Tool
Agent → Tool
Agent → Tool

而应该：

Agent
 ↓
统一工具执行入口
 ↓
Registry
 ↓
Permission Gate
 ↓
Tool

否则 Gate 只是“建议”，不是唯一入口。

这个区别以后做真正 Agent 系统时非常重要。

二十三、今天的装饰器，最后再用一句话理解

看到：

1
2
3
4
5
6
7


@registry.register(
 name="delete_file",
 description="删除文件",
 risk="high",
)
def delete_file(path):
 ...

脑子里不要把它看成一条特殊语法。

直接展开成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def delete_file(path):
 ...

decorator = registry.register(
 name="delete_file",
 description="删除文件",
 risk="high",
)

delete_file = decorator(delete_file)

然后继续往里面展开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


register(...)
 ↓
返回 decorator
 ↓
decorator(delete_file)
 ↓
创建 ToolSpec
 ↓
ToolSpec 放入 Registry
 ↓
返回原来的 delete_file

这时候装饰器基本就不神秘了。

二十四、这次真正应该记住的不是几个 API

今天最值得留下来的其实是这几个关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Tool
= 能力

Tool Registry
= 工具目录 / 统一发现

Permission Gate
= 权限决策

HITL
= 人工介入决策

Harness
= 把这些控制能力放到 Agent 和执行环境之间

再压缩成一条：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Agent 想做事
 ↓
Registry：你想找哪个工具？
 ↓
拿到 ToolSpec
 ↓
Gate：这个工具现在允许做吗？
 ↓
allow / deny / need_approval
 ↓
必要时 HITL
 ↓
真正执行 Tool

所以今天的变化不是：

“我又学了两个类。”

而是：

Agent 从“能调用工具”，开始进入“工具调用受系统控制”的阶段。

二十五、关键坑 / 真正理解

1. Registry 不是执行器

1

registry.get("read_file")

只是找到工具。

真正执行的是：

1

tool.func(...)

2. Gate 不是工具

Gate 不负责：

1
2
3


删除文件
发邮件
查询数据库

它只负责：

1
2
3


允许
拒绝
审批

3. 装饰器不是“魔法标记”

1

@xxx

本质上要还原成：

1

func = xxx(func)

遇到陌生装饰器，先找：

xxx 到底返回了什么？

4. 带参数的装饰器有两层调用

看到：

1

@register(name="xxx")

不要直接理解成：

1

register(function)

它通常是：

1
2
3
4
5


register(name="xxx")
 ↓
 decorator
 ↓
decorator(function)

5. `return func` 有实际意义

如果装饰器最终：

1

return None

那么：

1
2
3


@decorator
def foo():
 ...

执行以后可能变成：

1

foo = None

原函数就没了。

所以我们的 Registry 装饰器返回原函数，是因为：

注册工具，但不改变原工具的调用方式。

二十六、完整 Demo

下面这个版本把今天的核心机制全部放在一起。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169


from dataclasses import dataclass
from typing import Callable, Literal


# =========================
# Tool 定义
# =========================

@dataclass
class ToolSpec:
 name: str
 description: str
 risk: str
 func: Callable


# =========================
# Tool Registry
# =========================

class ToolRegistry:

 def __init__(self):
 self._tools: dict[str, ToolSpec] = {}

 def register(self, name: str, description: str, risk: str):
 def decorator(func: Callable):
 if name in self._tools:
 raise ValueError(f"tool already exists: {name}")

 self._tools[name] = ToolSpec(
 name=name,
 description=description,
 risk=risk,
 func=func,
 )

 return func

 return decorator

 def get(self, name: str) -> ToolSpec:
 if name not in self._tools:
 raise KeyError(f"unknown tool: {name}")

 return self._tools[name]


# =========================
# Permission Gate
# =========================

Decision = Literal["allow", "deny", "need_approval"]


class PermissionGate:

 def check(self, tool: ToolSpec) -> Decision:

 if tool.risk == "low":
 return "allow"

 if tool.risk == "high":
 return "need_approval"

 return "deny"


# =========================
# 创建 Registry
# =========================

registry = ToolRegistry()


# =========================
# 注册工具
# =========================

@registry.register(
 name="read_file",
 description="读取文件",
 risk="low",
)
def read_file(path: str):
 return f"读取文件：{path}"


@registry.register(
 name="delete_file",
 description="删除文件",
 risk="high",
)
def delete_file(path: str):
 return f"删除文件：{path}"


# =========================
# 创建 Gate
# =========================

gate = PermissionGate()


# =========================
# 统一工具执行入口
# =========================

def call_tool(
 tool_name: str,
 args: dict,
 approved: bool = False,
):
 # 1. 从 Registry 找工具
 tool = registry.get(tool_name)

 # 2. 让 Permission Gate 判断
 decision = gate.check(tool)

 # 3. 拒绝
 if decision == "deny":
 return {
 "status": "denied",
 "reason": "permission denied",
 }

 # 4. 需要人工审批
 if decision == "need_approval" and not approved:
 return {
 "status": "need_approval",
 "tool": tool.name,
 }

 # 5. 允许执行
 result = tool.func(**args)

 return {
 "status": "success",
 "result": result,
 }


# =========================
# 调用
# =========================

print(
 call_tool(
 "read_file",
 {"path": "a.txt"},
 )
)


print(
 call_tool(
 "delete_file",
 {"path": "a.txt"},
 )
)


print(
 call_tool(
 "delete_file",
 {"path": "a.txt"},
 approved=True,
 )
)

这个 Demo 不复杂，但已经把今天的完整结构包含进去了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@registry.register
 ↓
Tool 注册
 ↓
ToolSpec
 ↓
Registry
 ↓
call_tool()
 ↓
PermissionGate
 ↓
allow / deny / need_approval
 ↓
Tool.func()

二十七、今天这一层放回整个 W7

到这里可以重新看整个 W7：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


多 Agent
 ↓
Supervisor / Worker
 ↓
反思与停止条件
 ↓
Tool Registry
 ↓
Permission Gate
 ↓
真正可控的 Agent 执行环境

前面的内容更多是在解决：

Agent 怎么思考、怎么协作、怎么控制流程。

今天开始增加：

Agent 想动手的时候，系统怎么控制它。

所以 Harness 开始有了非常具体的形状：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


能力
 ↓
工具

管理
 ↓
Registry

控制
 ↓
Permission Gate

人工决策
 ↓
HITL

这几个东西以后还会继续往下扩展成更完整的 Agent Runtime / Harness。

Harness on 男娘教主

W7-Day6：把所有零件装成一台机器——完整调用链

W7-Day6：把所有零件装成一台机器——完整调用链

一、先看一次完整运行

二、入口：main()

三、build_harness() 到底做了什么？

四、Registry 在这里注册了什么？

五、Session / Compactor / Tracer 在这里被装配

六、然后进入 build_supervisor()

七、build_supervisor() 又创建了几个节点？

八、为什么 make_simple() 是一个函数工厂？

九、真正特殊的是 writer_node

十、为什么这里不能直接把 Reflection 的 State 暴露出来？

十一、ReflectionResult 就是两个系统之间的“接口”

十二、窄接口到底解决什么？

十三、write_with_reflection() 内部到底发生什么？

十四、Reflection Graph 内部再次运行

十五、然后 API 做一件很重要的事情：重新判定

十六、为什么返回 best_draft 而不是最后一稿？

十七、回到 writer_node

十八、第二条边界：消息格式

十九、于是 Day6 又增加了 msg_adapter.py

二十、为什么不让 Harness 直接支持所有 Message 类型？

二十一、现在整个调用链可以完整画出来了

二十二、Tracer 是怎么插进调用链的？

二十三、为什么 Day5 的 Tracer Bug 很重要？

二十四、Session 又在哪里真正生效？

二十五、Compactor 怎么证明自己真的工作？

二十六、Gate 怎么证明真的生效？

二十七、Day6 最重要的测试思想：故障注入

二十八、为什么“绿色测试”还不够？

二十九、这也是我这一周对“验证设计”的最大理解

三十、最后重新看 W7，发现它其实是在训练四层能力

第一层：编排

第二层：反馈

第三层：运行时基础设施

第四层：工程验证

三十一、所以 W7 真正的闭环是

三十二、如果让我用一句话总结 W7

W7 核心机制：Supervisor、Reflection 与 Harness

W7 核心机制：Supervisor、Reflection 与 Harness

一、先看完整系统

二、Supervisor：解决“下一步干什么”

三、Supervisor 为什么需要 State？

四、Supervisor 的代码怎么读？

五、为什么 Literal 很重要？

六、Reflection：解决“结果够不够好”

七、Reflection 的 State 为什么这么多？

第一组：当前任务

第二组：当前评估

第三组：循环控制

第四组：历史信息

八、trajectory 为什么要用 Reducer？

九、为什么要保存 best_draft？

十、Reflection 的条件边怎么理解？

十一、Harness 五模块应该怎么理解？

十二、Registry：工具“有什么”

十三、为什么 Registry 要提供 invoke()？

十四、Gate：工具“能不能用”

十五、Executor：工具“真的执行了吗”

十六、Session：Agent“经历过什么”

十七、Compactor：Agent“现在需要看到什么”

十八、Tracer：Agent“刚才是怎么跑的”

十九、Audit 和 Trace 再区分一次

二十、Facade：为什么又套一个 Harness？

二十一、Facade 最重要的两个设计

第一：模块之间不要互相乱 import

第二：LLM 从外面注入

二十二、把三条线合在一起

二十三、这也是为什么 Day6 才真正困难

W7 总览：从多 Agent 流程到 Agent Harness

W7 总览：从多 Agent 流程到 Agent Harness

一、第一条线：Agent 的“脑子”越来越复杂

二、第二条线：Agent 的“身体”越来越完整

二、Day1：先设计“机器长什么样”

第一张图：Agent 编排图

第二张图：Harness 图

三、Day2：先解决“多个 Agent 怎么协作”

Worker 不负责决定流程

四、为什么 Supervisor 需要 Structured Output？

二、入口：`main()`

三、`build_harness()` 到底做了什么？

六、然后进入 `build_supervisor()`

七、`build_supervisor()` 又创建了几个节点？

八、为什么 `make_simple()` 是一个函数工厂？

九、真正特殊的是 `writer_node`

十一、`ReflectionResult` 就是两个系统之间的“接口”

十三、`write_with_reflection()` 内部到底发生什么？

十六、为什么返回 `best_draft` 而不是最后一稿？

十七、回到 `writer_node`

十九、于是 Day6 又增加了 `msg_adapter.py`

五、为什么 `Literal` 很重要？

八、`trajectory` 为什么要用 Reducer？

九、为什么要保存 `best_draft`？

十三、为什么 Registry 要提供 `invoke()`？

七、所以 `@decorator` 到底做了什么？

第一层：先执行 `register(...)`

十一、为什么最后要 `return func`？

十二、这和 LangChain 里的 `@tool` 不完全是一回事

5. `return func` 有实际意义