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)。
This commit is contained in:
2026-08-27 03:59:39 -04:00
parent 1fac387e75
commit c4e5732587
12 changed files with 246 additions and 80 deletions
+19 -5
View File
@@ -25,6 +25,18 @@ pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/py
"polyloop[gateway]==1.0.*"
```
契约套件随包发布,它要的 pytest 也是一个单独的 extra
```bash
pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
"polyloop[testing]==1.0.*"
```
**只有自己实现了某个接缝、要拿库这边的契约套件验它的时候才装这个。** 存储、模型调用、决策
解释、动作执行、事件出口五处允许换实现,谁换了谁就得证明自己那份还满足接缝的行为契约,而
证明的方式就是继承 `polyloop.testing` 里对应的基类跑一遍。只调 `run` / `resume`、五个接缝
全用库自带或别人写好的实现的项目,不需要它。
写进 `requirements.txt` 的话,那一行 `--extra-index-url` 必须排在 `polyloop` 之前。
**这台开发机上的注意事项**:它设了 `http_proxy` 指向一个到不了外面的本地代理,走代理会失败,
@@ -32,7 +44,7 @@ pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/py
## 现状
十个模块全部落地,四层测试都在跑。**还没有任何下游项目真的用过它**——这是它现在最大的未验证项,
个模块全部落地,四层测试都在跑。**还没有任何下游项目真的用过它**——这是它现在最大的未验证项,
下面的阶段清单是唯一的进度权威。
## 消费者与验收标准
@@ -61,10 +73,12 @@ pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/py
架构文档先于代码存在,此期间它是一份规格而不是描述,文档开头须写明这一点
- [x] ④ 测试框架 —— 四层都在跑(划分判据是「依赖什么」,见 [CLAUDE.md](CLAUDE.md) §1.9)。
e2e 打真实模型网关、会产生真实费用,所以默认不跑:要 `POLYLOOP_E2E=1` 加显式
`pytest -m e2e`,配置见 [.env.example](.env.example)。`tests/contract/` 那套公共行为
一致性用例接上了自带的存储实现,解释器与执行器那几条仍等下游把实现接进来
- [x] ⑤ 实现 —— 十个模块全部落地,五个接缝都有调用点。**一处已知欠账**:`stores` 只有逐行
追加那一种形态,关系数据库那种由下游自己实现,契约套件是它的准入标准
`pytest -m e2e`,配置见 [.env.example](.env.example)。那套公共行为一致性用例住在
`polyloop.testing` 里随包发出去,五个接缝在本仓库都接上了实现跑起来,接点是
`tests/contract/``tests/integration/` 下那几个继承契约基类的子类
- [x] ⑤ 实现 —— 十一个模块全部落地,五个接缝都有调用点。`stores` 有两种形态:逐行追加进
本地文件的那个,和只留在进程内存里、进程一退就没了的那个。关系数据库那种仍然由下游
自己实现,契约套件是它的准入标准,而套件随包发布在 `polyloop.testing`
- [x] ⑥ 验收 —— 两件事都做完了。**一是自己造负载压**:照三个消费者将来的用法造负载,用真实
数据真的打模型跑完,看这个内核在这个量级上扛不扛得住。**这一步之所以必须自己做,是因为
三个消费者一个都还没到能用它的时候**,而「从没被任何人用过」是它当时最大的未验证项,