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:
@@ -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] ⑥ 验收 —— 两件事都做完了。**一是自己造负载压**:照三个消费者将来的用法造负载,用真实
|
||||
数据真的打模型跑完,看这个内核在这个量级上扛不扛得住。**这一步之所以必须自己做,是因为
|
||||
三个消费者一个都还没到能用它的时候**,而「从没被任何人用过」是它当时最大的未验证项,
|
||||
|
||||
Reference in New Issue
Block a user