docs(design): 落成 0006 与 0007,公共 API 的名字、签名与接缝行为

0006 定「叫什么、什么形状」:五个接缝的 Protocol 名与签名、公共类型的英文名与
字段清单、类型分到 types / ports / tools 三个模块的判据。
0007 定「同一个签名下什么算对」:三个动作状态的触发条件、动作被拒绝时观察由库
合成而不取执行器那段、解释器不许抛异常、read_log 读不存在的运行返回空日志。
两份拆开是因为后者的权威处按 §0 是 tests/contract/,design doc 只记当初为什么这么定。

这两份改动了 0003 四处,全部在文首登记:记录集合是六种东西不是五类;
参数视图是方法不是字段;预算是四项不是两个计数;ports 装「Protocol 与它们的
入参/返回结构体」那半句写不出来——照它写 types 会反向依赖 ports。
四处全是「把字段类型逐个写出来」这个动作本身逼出来的,纯读文档看不见。

四轮评审:两轮硕士生冷读报了约 45 条,两轮 Codex 对抗审查报了 13 条,
逐条核实后基本全部成立并修完。最后一轮是唯一一次契约测试与文档互相抓到对方的错——
文档改了方法名测试没跟,测试把 dissect 的动作语言写死成输入会误杀 GovDoc 的实现。

结论回写 architecture.md:第七节补类型归属判据,第八节改 ports 那一行,
第九节补五个 Protocol 的英文名,第十四节把「英文名还没定」那条缺口换成指向;
决策索引加两行。字段表刻意不回写——按 §0 那是代码的权威。
CLAUDE.md 与 README.md 开头的「一次 Agent Session」是术语漂移,改成「一次运行」。

CLAUDE.md §7 加两条工作方式:能压成一段结论的活尽量交给 subagent、
委托出去的活交证据不交判断;以及持续往下做,只在人类门和真判断不了的岔路停。
§8 那句「讲完停下来等回应」与后者打架,收窄到只管说话方式。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-09 23:56:38 -04:00
parent a14bf8d288
commit f8e02290f4
10 changed files with 986 additions and 34 deletions
+4 -2
View File
@@ -1,6 +1,6 @@
# PolyLoop
实验室共用的 Agent 执行内核。治理单位是**一次 Agent Session**:围绕一个目标的有界多轮「模型决策 → 动作 → 观察」循环,含预算、停止语义、取消、逐步轨迹与 Skill 注入。一次模型调用本身不归它管,那是 PolyGateway 的治理单位;PolyLoop 用 PolyGateway 的顶层公共 API,不重建一套模型治理。
实验室共用的 Agent 执行内核。治理单位是**一次运行**:围绕一个目标的有界多轮「模型决策 → 动作 → 观察」循环,含预算、停止语义、取消、逐步轨迹与 Skill 注入。一次模型调用本身不归它管,那是 PolyGateway 的治理单位;PolyLoop 用 PolyGateway 的顶层公共 API,不重建一套模型治理。
首批消费者是 dissect 与 GovDoc-SaaSCHSAnalyzer 是远期消费者。
@@ -149,11 +149,13 @@ Codex 是 OpenAI 的编码模型,本仓库通过 `codex` 插件调用它。**
- **报告进展前,逐条对照本次会话真实的工具结果。** 只报告拿得出证据的部分;没验证的明说没验证。测试挂了就贴输出;跳过的步骤就说跳过了;做完并验证了就平实地说清楚,不要模糊其辞。
- **不做没让做的事**:不顺手重构、不为假设中的未来需求加抽象。修 bug 不需要顺带清理周边。
- **不建防御性备份分支。** 想留个后路的心情可以理解,但分支一多就没人认得出哪条还有用,最后谁都不敢删。git 本来就留着历史,需要回退随时回得去。
- **能压成一段结论的活尽量交给 subagent,必须和别处约束咬合的活自己做。** 判据是产出的形状:「读一批材料、回来给个清单」属前者——调研某处怎么实现的、跨几份文档核对结论有没有回写、大范围搜索某个东西在哪;「写一段要同时压着十条约束的代码」属后者,交出去只会收回一段看着对、细节全错的东西,而那类错是静默的。判断一条审查发现成不成立、写 design doc、做取舍、和人对话,同样自己做。**委托出去的活要求交证据不交判断**:事实要带 `文件:行号` 或命令原始输出,并抽查两三条校准这一份可不可信——抽查错一条整份都不采纳,因为它已经证明会编。
- **持续往下做,不要每完成一件事就停下来问「要不要继续」。** 只在两种情况停:撞上 §2 那张表里的人类门,或者不同理解会导出实质不同的工作而你判断不了。除此之外做完一件接着做下一件,做完一起报。每做完一步就问一次,等于把「决定下一步做什么」这件本该由你承担的事推回给人,而人手上的上下文比你少。
## 8. 对话
说人话。像同事聊天那样一次说一件事,别把一轮回复写成报告。你是我的合作者,不是一个机器,不要把一大堆内容直接甩给我自己分析,这是推卸责任。我们的目标是一起通力合作开发好这个项目。
问什么答什么,有判断直接讲,讲完停下来等回应,不要一口气把后面几步都推完。不要默认一些名词和你搜索到的内容我是一定知道的,你有讲解的义务。不要为了「扮演」专业刻意使用高信息的句子或者表述,这会显著降低可读性。
问什么答什么,有判断直接讲。**这条管的是怎么说话,不是怎么干活**——别在一轮回复里把后面几步的推演一口气铺完,但活该往下做就往下做,什么时候停按 §7 那条。不要默认一些名词和你搜索到的内容我是一定知道的,你有讲解的义务。不要为了「扮演」专业刻意使用高信息的句子或者表述,这会显著降低可读性。
**要我做决定时,一次把决定需要的信息给全。** 具体说:总共几个问题、每个问题有哪些选项、你倾向哪个、以及哪些是你自己就能定的。**不许挤牙膏**——先讲三条、等我追问才补上剩下九条,这中间我是在信息不全的情况下做判断,等于白问。你看得到全部上下文,我看不到;你不列全,我就没有选的依据。