iomgaa
c4e5732587
docs: 回写全仓库对契约套件的指向，以及 README、架构与 CHANGELOG
...
套件从 tests/contract/ 搬进 polyloop.testing 之后，全仓库 28 处引用要重新指过。修了 12 处，
其余在 design/（只增不改）与 scratch/（由人清理）里。
**CLAUDE.md 改了四处事实**：§0 权威表里行为契约的权威、§0 那句依赖规则的条数、§5 目录树与
模块数、§1.8 那句「谁断言公共 Protocol 的签名」。§1 的其余硬约束与 §2 的人类门一条没动。
**architecture.md**：分层图第 4 层加一格，装配层从三个变四个；代码地图加一行；第十节按代码
逐项重写——那笔「工具段渲染样式」的欠账**没有被数字对上盖掉**，加了 fingerprints 之后请求
的字段数恰好还是十一，而组成已经换过，所以那一节正面写着它仍然欠着；新增第十条依赖规则
（pytest 只在 testing 那个 extra 里，别处 import 它会让下游的生产环境一 import 本库就
ModuleNotFoundError），带静态与运行时两半；删掉「src/ 下一行代码都没有」那段过期状态说明；
决策索引补齐 0008 到 0016，其中四行原描述说的不是那份文档真正定的东西。
**migrations/dissect.md** 那笔「内存实现不存在」的欠账还掉了。
**压测那边**三条测试守的是一条已经撤销的公共契约，改名并写清它们现在守的是场景自己的选择。
AppWorld 那处刻意的偏离（不补三个反引号）留着不恢复——那条路径要模型输出被 stop 序列截断才
触发，而压测不配 stop 序列，恢复的收益不抵重跑一次压测的成本。但注释的理由改对了：它现在是
一笔有出处的欠账，不是一个决定。
CHANGELOG 攒在「未发布」段，版本号不提前写（§1.10）。
2026-08-27 03:59:39 -04:00
iomgaa
e10f024c9b
docs: 撤掉阶段清单的自毁条款
...
原话是「开发结束后把本节删掉即可」。六个阶段现在都走完了，而这份清单没有变成过期条文——
它记的是每个阶段各自的验收标准与结论，那是「当初凭什么算完成」的答案，删掉就没有别处
记着了。留着它不需要维护：勾完就不再动。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 12:31:49 -04:00
iomgaa
1b8e8367f9
docs: ⑥ 验收完成，两半都交付了
...
压测那一半的结果写进阶段清单：193 次运行、1743 次真实调用、十一条不变量全过，九类故障
注入 58 条判据零击穿。库本身没有被压出 bug——压出来的四个问题全在压测这一侧，各自的
commit 里写了是怎么发现的。
AppWorld 那一路的步数分布与 dissect 已有的 937 条真实轨迹基本重合，那是「同一个 benchmark
换个内核驱动、轨迹形状没变」的证据。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:57:06 -04:00
iomgaa
aa2cc46ef8
docs: ⑥ 的验收标准换成自造负载 + 迁移方案交付
...
原来写的是「真的把 dissect 迁过来、以它原有测试全绿为准」，两个前提都不成立了：
GovDoc-SaaS 的实现已经整体清空，没有东西可迁；dissect 正在 Phase-1 中间，而且它的方案
该由那边自己排期，不该由本库直接改它的代码。
换成两件：自己照三个消费者将来的用法造约一百个任务的真实负载压一遍——这一步必须自己做，
因为三个消费者一个都还没到能用它的时候，而「从没被任何人用过」是它现在最大的未验证项；
以及把 dissect 的迁移方案写成一份提到它 issue 上的东西。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:32:51 -04:00
iomgaa
303e4ebc1c
chore(release): 打包元数据补齐，版本定到 1.0.1
...
发布前置：readme 与 project.urls 从第一版就写全——缺 readme 的话 registry 包页面正文一片
空白，而 twine 只警告不阻塞上传，三步全绿产物却是坏的（PolyGateway 1.1.2 的教训）。
build 与 twine 钉进 dev extra 而不是靠人手装，PolyGateway 那边它们不在任何 extra 里，
于是发布指南得多写一条「记得先装」，那种步骤迟早有人漏。
README 里那条「项目还没有可用的功能、十个模块是空骨架」的横幅早就过期了，而打包会把当时的
README 固化进 sdist、发布后再改无效，所以在构建之前换成安装说明与现状。顺带修两处与事实
不符的：GovDoc-SaaS 的实现已经在 8 月 3 日整体清空，⑥ 对它的验收标准改成设计级验收。
新建 CHANGELOG.md，写清楚首个版本为什么是 1.0.1 而不是 0.x——「公共类型的字段只增不删不
改名」那条承诺从第一个下游装上它那天起就生效，而 0.x 意味着随时可以破坏兼容。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:11:04 -04:00
iomgaa
d4aa5e117e
test(e2e): 补上打真实网关的那一层，四层测试到齐
...
两个用例：一次运行走通「模型→解释→工具→观察回填→再问模型→收尾」，以及取消能穿过真实的
HTTP 请求并留下已取消的结束记录。测试自带解释器、工具注册表与事件出口——库故意不带它们，
带了就等于替某一家定了动作语言。
断言只绑结构不变量，一条都不绑模型输出的文字：停止原因落在两个正常终态里、至少两步且至少
一步真的执行过动作、每步 call_id 非空（网关那边生成的，替身给不出来）、日志读回来与返回值
逐字段相等、事件条数等于步数。绑内容的测试会随机红，而随机红的测试很快没人看。
两道跳过闸：网关装没装，以及 POLYLOOP_E2E 是不是 1。分开是因为填好密钥不等于同意花钱。
实测跑一次三次真实模型调用、约 12 秒；开关关着时整层跳过；make ci 283 passed / 16 skipped。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 23:49:11 -04:00
iomgaa
95898bccf3
docs: 事件集落地后回写 GovDoc 缺口清单与阶段清单
...
「审计出口与事件流的关系」那条缺口转到已回答：审计由意图日志承担，出口要包在存储接缝上
而不是接在事件出口上；三类事件里 phase_recovery 那一类在界外。新登记一条缺口：工具单独的
耗时拿不到，本库只有整步墙钟，迁过去口径会变。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 22:57:09 -04:00
iomgaa
183113f624
docs: 0011 与 0012 转已接受，README 阶段清单勾到 ⑤
...
④ 与 ⑤ 都勾上但各自注明了欠账：e2e 那一层还是空的（它要打真实模型网关）；事件出口没有调用
点（Event 还没有字段）；stores 只有逐行追加那一种形态。勾上是因为骨架与十个模块确实都落地
了，注明欠账是因为清单是进度的权威处，含糊会让人以为这两件事已经做完。
2026-08-10 04:24:01 -04:00
iomgaa
f8e02290f4
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 >
2026-08-09 23:56:38 -04:00
iomgaa
e017160c45
build(repo): 落成工具链、依赖契约与十个模块的空骨架
...
第 ③ 阶段剩下的那半：架构文档之外，import-linter 契约也落地了。
pyproject.toml 把九条依赖规则里的七条写成五条 import-linter 契约。
分层用一条 layers 契约表达规则 1、2、3、8，`|` 表示同层互不 import；
另外四条 forbidden 分别管下游反向 import、polygateway 的唯一入口、
以及三个纯逻辑模块不碰 asyncio 与 pathlib。
契约不是平凡的绿：故意注入两处违规验证过，都被点名到行号。
先建十个模块的空包，是为了避开 PolyGateway bootstrap 期那段 Makefile 门控——
它当时没有包，lint-imports 报 module not found 而红，只好加一段跳过逻辑。
空包让契约从第一天就真的在跑。
剩下两条规则落不进契约，写成了 tests/unit 下的测试：
规则 6「types 与 ports 不许 import 任何第三方」判据要反过来写（只许标准库和自己），
规则 9「import polyloop 之后 sys.modules 里没有 polygateway」是运行时事实。
另加硬约束 §1.1 零业务假设的黑名单扫描——它第一次跑就抓到 _assembly 的 docstring
里写了 dissect 的业务词，已改。三个扫描类测试都带 fail-closed 守卫，
防止目录搬走之后扫到空列表安静地绿。
工程约定取自实验室已有项目：setuptools + src layout、ruff 十一项 select、
line-length 100 来自 PolyGateway；dev 工具链版本钉死、--strict-markers 与
--import-mode=importlib 来自 CHSAnalyzer 与 dissect 踩过的坑，各自的理由写在配置注释里。
e2e 默认不跑，它打真实网关要花钱。
CLAUDE.md §0 那句「契约还没写，要等 src/ 落地」已过期，改掉；
README 勾掉第 ②③ 阶段，补上本地检查命令与 GovDoc-Editor 那一行。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-09 21:28:59 -04:00
iomgaa
a2e94318b9
chore(repo): 建仓，落成协作规范与文档骨架
...
协作方式以 CHSAnalyzer 为蓝本，按「库」这个身份改写：
- CLAUDE.md §0 的权威表换成公共 API 契约、公共类型、下游迁移三条主线，
数据库 schema / HTTP 契约 / alembic 迁移在本项目不存在，整体删去。
- §1 新增四条库特有的硬约束：字段只增不删不改名、持久化 schema 走显式版本、
不反向 import 下游、发布必须走完整流程（PolyGateway 有两个版本只 bump
没上传，registry 长期停在旧版且无人发现）。
- §3 的四类 Codex 对抗审查按同一判据重定：公共签名、停止判定与预算结算、
取消传播与 Session 隔离、schema 演进。共同点是错了不会当场炸。
- research-wiki 在常青层加第四类 migrations/，因为本项目的核心验收标准就是
能否搬回 dissect、能否替代 GovDoc-SaaS 的 docagent-core/，塞进 guides/
会让它看起来像可选工序。
reference/ 不入库：五个仓库各带一个 .git、合计约 96MB，提交进来会变成一堆
不可用的嵌套仓库。它也不是任何事实的权威，agent-core.md 同理。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-07 07:02:09 -04:00
iomgaa