附录
核心代码导览 —— 十个检查点
各章的「Python 实验」告诉你要运行什么;这一页把十个机制的关键片段摘出来,逐段讲设计意图。读完它,你就有了打开任何 Agent 框架源码时的"路标"——知道该先找哪几处、每处在回答什么问题。
全部片段取自
learn_pi_lab/labs/(约两千多行,只依赖标准库、完全离线)。它们是教学模型,不是 Pi 的生产实现;每一节末尾会给出 Pi 里对应的位置,方便你去核对设计而不是抄代码。
01 · 循环骨架:谁决定下一步
agent_loop.py 的 run_scripted_loop 把循环压成"问 → 判 → 执行 → 回填"四步:
for turn in range(1, max_turns + 1):
step = model.next_step(prompt)
if step is None:
errors.append(RunError(code="script_exhausted", ...))
return _trace(prompt, None, tool_names, turn - 1, errors)
if isinstance(step, str) or isinstance(step, FinalText):
return _trace(prompt, step, tool_names, turn, errors) # 终止
# ToolRequest:执行并把结果回填,进入下一轮
三个设计点:
- 轮数上限先于一切校验:防失控是循环的第一道参数检查。参数不合法就返回一份运行记录,而不是抛异常——循环的产物是数据,测试才能断言它。
- "脚本耗尽"也是错误:模型停在没有给出最终答复的地方,循环不能装作正常结束。让这个状态显式可见,比悄悄返回空字符串诚实。
- 字符串和最终文本都算终止:这就是"停止原因"最朴素的模拟——工具请求之外的任何一步,都走向终止。
想对照更完整的版本,看 mini_agent.py 的 run_agent_loop:它真的调模型、真的执行工具。机制详解见 02 章。
02 · 拦截:先检查,后执行
tool_permissions.py 有一百多行,把"拦截"写成纯函数:
def dispatch_if_allowed(request, policy, executor):
decision = evaluate_request(request, policy)
if not decision.allowed:
return DispatchResult(decision=decision, result=None, executed=False)
return DispatchResult(decision=decision, result=executor(decision.request), executed=True)
evaluate_request 内部是三道依次的检查:
token, problem = _command_token(request.command) # ① 拆出裸命令令牌
if token not in policy.allowed_commands: # ② 白名单
return Decision(False, "command_not_allowed", ...)
for requested_path in request.paths: # ③ 路径归一化 + 包含检查
normalized_path, path_problem = _normalized_path(requested_path, policy.root)
关键取舍藏在细节里:
- 拒绝一切 shell 语法:出现管道、重定向、变量替换就直接拒绝。命令必须是单个裸词——不做字符串解析,就没有注入面。
- 路径检查两步走:先拒绝父目录分量拦住明显穿越,再解析真实路径验证仍在边界内,兜底符号链接与绝对路径。两步缺一不可。
executed=False是结构化事实:被拒的请求零副作用,调用方不需要"事后撤销"。
要强调:这个闸门是你写的,不是 Pi 内置的。Pi 提供"拦下某次调用"的钩子和操作系统隔离,策略留给你。机制详解见 03 章。
03 · 会话树:只记父节点
session_tree.py 用不到一百行实现"只追加 + 父指针"。校验做三件事:
for entry in self._entries:
if entry.id in entries_by_id: # ① 编号不能重复
raise MalformedTranscript(...)
for entry in self._entries:
if entry.parent_id == entry.id: # ② 不能自己当自己的父
raise MalformedTranscript(...)
if entry.parent_id is not None and entry.parent_id not in entries_by_id:
raise MalformedTranscript(...) # ③ 父节点必须存在
而"重建一条分支"只有一层循环:
def path_to(self, leaf_id):
current = self._entries_by_id[leaf_id]
branch = []
while True:
branch.append(current)
if current.parent_id is None:
break
current = self._entries_by_id[current.parent_id]
return tuple(reversed(branch))
设计点:分支不是数据结构,是查询结果。从任意末尾沿父指针走到底,就是一条分支。没有"分支列表"要维护,自然也没有分支不一致的 bug。校验放在构造时,损坏的快照根本进不来。
机制详解见 05 章。
04 · 压缩:宁可多留,不拆一对
compaction.py 的 choose_cut 回答一个具体问题:保留最新 N 条时,如果第 N 条正好切在一对"调用 + 结果"中间怎么办?
start = max(0, len(units) - keep_units)
while True:
expanded_start = start
for indices in pair_indices.values():
includes_pair_unit = any(index >= start for index in indices)
excludes_pair_unit = any(index < start for index in indices)
if includes_pair_unit and excludes_pair_unit: # 这一对被切开了
expanded_start = min(expanded_start, min(indices))
if expanded_start == start:
break
start = expanded_start
边界往更旧的方向扩张,直到不再切开任何一对。 扩张的是"保留区"——多留几条,而不是把半个对丢进摘要。多留的代价是多占一点预算,拆对的代价是下一次请求直接非法。
_pair_indices 还在入口处断言每个配对编号恰好两个单元,把"配对完整"从口头约定升级成构造时校验。
零预算的语义也值得看:保留量为零时什么都不留,包括完整的对——摘要替换全部历史,这是合法的极端情况。
机制详解见 07 章。
05 · 事件总线:异常变成数据
extension_events.py 的 emit 只有二十几行,却包含事件系统的全部纪律:
snapshot = _freeze_value(payload) # ① 先冻结再广播
handlers = tuple(self._handlers.get(event, ()))
for handler_index, (_rid, callback) in enumerate(handlers):
try:
outcomes.append(EventOutcome(status="ok", value=callback(snapshot)))
except Exception as error: # ② 异常隔离
outcomes.append(EventOutcome(status="error", error=f"{type(error).__name__}: {error}"))
- 先冻结再广播:处理函数拿到不可变快照,谁也没法通过改负载影响后面的处理函数。
- 捕获普通异常,放行系统退出:用户按 Ctrl+C 必须能立刻停,事件系统无权吞掉它。
- 异常是结果,不是中断:一个处理函数崩了,后面的照常跑,调用方拿到完整结果列表自行决定怎么呈现。
机制详解见 06 章。
06 · 分帧:按行,不按块
rpc_jsonl.py 的 feed 展示粘包与半包的标准解法:
candidate = self._buffer + chunk
records = candidate.split("\n")
self._buffer = records.pop() # 最后一段(可能不完整)留回缓冲
for record in records:
if not record.strip():
continue # 空行跳过
decoded = json.loads(record) # 逐行解析,坏行报错但不连累后续
messages.append(_validate_record(decoded))
三个决定:
- 缓冲以行为单位:切完把最后一段放回缓冲,半包自动等下一次,粘包自动拆开。不数长度、不猜对齐。
- 坏帧是协议错误,不是流终止:报给调用方,缓冲状态由调用方决定要不要重置。
- 无界缓冲有上限:一行恶意超长输入不能吃光内存;超限就清空并报错。
机制详解见 10 章。
07 · 重试:退避可注入,才可测试
reliability.py 的 retry 不到三十行,暴露了重试的两个本质:
for current_attempt in range(1, attempts + 1):
try:
return RetryResult(operation(), current_attempt, tuple(delays))
except Exception as error:
if current_attempt == attempts:
raise RetryExhausted(current_attempt, type(error).__name__) from error
delay = float(base_delay) * (2 ** (current_attempt - 1)) # 1, 2, 4, ...
delays.append(delay)
if sleep is not None:
sleep(delay) # ① sleep 是参数,不是 import
- 等待函数由调用方注入:测试传一个"记录等待时长"的假函数,生产传真 sleep。测试零等待、确定性、可断言。
- 异常只带类型名:最后一次失败的错误文本不进入新异常,避免敏感内容泄漏到上层日志。
- 分类不在这里:这个函数对一切异常一视同仁地退避。调用方要先按 09 章 的矩阵过滤——认证失败之类的根本不该进来。
机制详解见 09 章。
08 · 系统提示词:两条路径的分歧点
system_prompt.py 复现 Pi 的分段拼装,分歧点只有一处:
if options.custom_prompt:
prompt = options.custom_prompt # ① 跳过工具清单、规则、文档指针
prompt += append_section
prompt += _project_context_section(options.context_files)
...
return prompt
# 默认路径:人设 + 工具清单 + 规则 + 文档指针
guidelines = _guidelines_block(tools, options.prompt_guidelines)
_guidelines_block 里最有意思的是规则的动态生成与去重:
if (has_bash or has_powershell) and not has_grep and not has_find and not has_ls:
add("Use bash for file operations like ls, rg, find") # 或 PowerShell 变体
for guideline in extra:
add(guideline)
for guideline in ALWAYS_GUIDELINES: # 无条件两条
add(guideline)
规则不是写死的文本,是根据工具集算出来的:有专职搜索工具就不教"用命令找文件",有 Windows 命令工具就换措辞。去重让调用方重复传入也不产生重复行。技能段的条件同理——读不了技能文件就不注入。
同一个模块还提供 build_system_prompt_sections,返回"段名 → 内容"的映射,和 Pi 的分段视图一致;build_system_prompt 只是把它连起来、加上便于阅读的标签。
机制详解见 04b 章。
09 · 服务商注册表:元数据与执行分离
provider_registry.py 用八十行演示"换模型不换代码":注册表只保存元数据(标识、显示名、窗口),执行经由统一接口注入。
它做了三件容易被省略的事:标识校验(用正则约束,防止拿不可靠字符串当键)、重复检测(同一服务 + 模型注册两次直接报错)、稳定排序(清单可复现,测试才能断言)。
这三件事和 Pi 的模型清单职责同构:注册表不是"存一堆字符串",而是"提供一份可校验、可复现、可查询的目录"。目录本身不稳定,后面所有"选哪个模型"的推理都不成立。
机制详解见 08 章。
10 · 两条扩展通道:脚本化调用与可替换点
这两段来自新增的两章,共同点是"不掉进循环里"。
scripted_calls.py 的运行时,把"调了很多工具"压缩成"上下文里只多一条结果":
output = runtime.run((
CallStep("read", {"path": "a.py"}),
CallStep("read", {"path": "b.py"}),
CallStep("read", {"path": "c.py"}),
TextStep("3 files; only the long one matters"),
))
output.calls, output.context_messages # 三次调用,一条消息
设计点:调用次数与上下文条目数解耦。同时它把两个预算(调用次数、输出长度)做成了参数。注意:教学模型用"计数",真实沙箱用"超时"加输出上限——没有预算,一次脚本就可能耗尽这一轮。
storage_and_routing.py 把"换后端不改调用方"钉成一条可测试的性质:
def replay(store):
return "\n".join(f"{record.role}: {record.content}" for record in store.load())
assert {replay(s) for s in (memory, file_store, read_only)} == {"user: hi"}
路由那半段则把"没命中"做成了返回值的一部分(matched=False),因为路由最危险的失败是"看起来正常"——用户以为在用强模型,其实一直在用兜底模型。
怎么把这套路标用到别的框架
十个片段对应十个"检查点"。打开任何一个 Agent 框架的源码,都可以按同样的问题去定位:
| 检查点 | 问的问题 |
|---|---|
| 循环 | 终止由哪几个信号合流决定?轮数之外还有取消吗? |
| 拦截 | 检查发生在执行之前还是之后?拒绝时有没有副作用? |
| 会话存储 | 崩溃在任意一行会损坏多少历史? |
| 压缩 | 切割点怎么保证调用与结果不被拆开? |
| 事件 | 一个订阅者崩了会影响别的订阅者吗? |
| 分帧 | 解析按块还是按帧?无界输入有上限吗? |
| 重试 | 等待函数可注入吗?错误文本会不会泄漏到上层? |
| 系统提示词 | 换人设会不会连带丢掉工具说明?哪些段关不掉? |
| 服务商 | 协议差异写在循环里,还是收敛在适配层? |
| 扩展通道 | 新能力是改了循环,还是只换了一个实现? |
返回 课程地图。