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
parent d4aa5e117e
commit 303e4ebc1c
4 changed files with 101 additions and 12 deletions
@@ -0,0 +1,51 @@
+# CHANGELOG
+
+**这份文件是「哪个版本改了什么」的唯一权威**（`CLAUDE.md` §0）。未发布的改动攒在「未发布」
+那一段，发布时改成 `## X.Y.Z（日期）`。发布的完整步骤在
+`research-wiki/guides/releasing.md`。
+
+版本号语义按 `CLAUDE.md` §1.3：公共类型的字段只增不删不改名，新增字段必带默认值；要删要改
+就发新 major 并写迁移指引。
+
+## 未发布
+
+## 1.0.1（2026-08-11）
+
+首个发布版本。十个模块全部落地，四层测试都在跑。
+
+**为什么首个版本是 1.0.1 而不是 0.x**：`CLAUDE.md` §1.3 那条「公共类型的字段只增不删不改名」
+从第一个下游装上它的那天起就生效，而 0.x 在语义化版本里意味着「随时可以破坏兼容」——两者
+对不上。用 1.x 开头是在声明那条承诺现在就算数。
+
+### 公共 API
+
+- **`polyloop.types`**：消息与内容块、上下文与注入、动作结果、预算、停止原因、逐步轨迹的
+  一行（`StepRecord`）、一次运行的结果（`RunResult`），以及五种持久化日志记录。持久化结构带
+  独立的 schema 版本，读到不认得的版本直接失败，不靠默认值补齐（`CLAUDE.md` §1.4）。
+- **`polyloop.ports`**：五个接缝的 Protocol——模型调用、决策解释、动作执行、存储、事件出口。
+  每个都带一个同步的 `parameters()`，装配时聚合成参数快照写进运行开始记录，续跑时逐字段比对。
+- **`polyloop.session`**：`run` 与 `resume` 两个入口，以及它们收的两个装配对象
+  （`AgentDefinition` 跨运行不变、`RunRequest` 每次运行一份）。
+- **`polyloop.tools`**：工具注册表。注册、模型可见的 schema 生成、存在性与参数校验、分发，
+  四件事由同一个注册表实例驱动，所以「模型看得见但调不到」这种状态构造不出来。
+- **`polyloop.serialization`**：持久化记录的编解码。读到没有版本字段的载荷直接失败。
+- **`polyloop.stores`**：逐行追加的 jsonl 存储。必须显式 import，不进顶层。
+- **`polyloop.adapters`**：PolyGateway 的模型调用适配器，装它要 `polyloop[gateway]`。
+  必须显式 import——顺手导出会让每个进程在 import 本库时把网关连同它的 provider 目录一起拉起来。
+
+### 这一版保证了什么
+
+- **一次运行是有界的**：步数、动作数、连续解析失败次数、提示词规模四个预算，停止判定的顺序
+  写死在主循环里，判定结果随每一步落盘——崩在中间也不会把「恰好用满预算完成」记成「预算耗尽」。
+- **崩溃之后能从断点续跑**：一步之内四次写，其中两次是耐久屏障；恢复读意图日志判断上一步
+  处在哪一档（还没开始 / 执行完了 / 状态未知 / 日志损坏），按工具声明的重放策略处置。
+  十个写入边界逐个崩过一遍，续跑结果与不中断跑完逐字段相等。
+- **取消能穿透**：`asyncio.CancelledError` 不被捕获吞没，取消进来之后在宽限期内写下结束记录
+  ——不写的话恢复会把一次被主动叫停的运行当成可以续跑。
+- **并发跑同一份定义互不干扰**：装配对象不持有任何一次运行的状态。
+
+### 已知欠账
+
+- `stores` 只有 jsonl 一种形态，关系数据库那种由下游自己实现，`tests/contract/` 是它的准入标准。
+- 契约套件里解释器、执行器、模型客户端那几条等下游把实现接进来才跑得到。
+- 原子写的「崩在中间时两者都不可见」与前缀持久性这两条承诺没有机器兜底，标成 `xfail`。
@@ -9,17 +9,38 @@

 ---

-## ⚠️ 项目还没有可用的功能（2026-08-07 起）
+## 安装

-`src/polyloop/` 下是十个模块的空骨架——目录和依赖契约先于代码存在，模块里一个类一个函数都
-还没有。下面的阶段清单是唯一的进度权威。
+发布在实验室自建的 Gitea PyPI registry 上，公网 PyPI 查它是 404，所以装它必须自己带索引地址：
+
+```bash
+pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
+    "polyloop==1.0.*"
+```
+
+模型调用要经 PolyGateway，那部分是一个单独的 extra——不用它的人不该被迫装上网关：
+
+```bash
+pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
+    "polyloop[gateway]==1.0.*"
+```
+
+写进 `requirements.txt` 的话，那一行 `--extra-index-url` 必须排在 `polyloop` 之前。
+
+**这台开发机上的注意事项**：它设了 `http_proxy` 指向一个到不了外面的本地代理，走代理会失败，
+装的时候加 `NO_PROXY=gitea.iomgaa.online`。
+
+## 现状
+
+十个模块全部落地，四层测试都在跑。**还没有任何下游项目真的用过它**——这是它现在最大的未验证项，
+下面的阶段清单是唯一的进度权威。

 ## 消费者与验收标准

 | 项目 | 现状 | 本库对它的验收标准 |
 |---|---|---|
 | dissect | 已有跑着的 `harness/agent/`（loop / context / memory / parser） | **能把那套循环搬到本库上，dissect 原有测试全绿。** 一手需求证据最强 |
-| GovDoc-SaaS | 已有 `packages/docagent-core/`（第一次抽库尝试，含 agent / workflow / retrieval / taskrun） | **能替代掉 `docagent-core/agent`，能替代更多更好。** 哪些子包能一并接管，在第 ② 阶段判断 |
+| GovDoc-SaaS | 仓库 2026-08-03 起整体重建，实现全部清空，自己的清单停在「构建文档框架」 | **不做迁移验收，做设计级验收**：它真实需要的东西逐条能不能被承载，见 `research-wiki/migrations/govdoc-saas.md`。它将来写 agent 层时是直接长在本库上，不是迁过来 |
 | CHSAnalyzer | 还没写到 agent 那一步，只有设计方案 | **远期可以兼容使用。** 它的 agent 需求要么本库能满足，要么明确写进「不属于本库」清单并说明为什么 |

 三者的证据强度不同，能进本库的语义也就分档：dissect 和 GovDoc-SaaS 的真实代码是一手证据，
@@ -45,7 +66,8 @@
      一致性用例接上了自带的存储实现，解释器与执行器那几条仍等下游把实现接进来
 - [x] ⑤ 实现 —— 十个模块全部落地，五个接缝都有调用点。**一处已知欠账**：`stores` 只有逐行
      追加那一种形态，关系数据库那种由下游自己实现，契约套件是它的准入标准
- [ ] ⑥ 迁移验收 —— 真的把 dissect 与 GovDoc-SaaS 迁过来，以两边测试全绿为准
+- [ ] ⑥ 迁移验收 —— 真的把 dissect 迁过来，以它原有测试全绿为准。GovDoc-SaaS 那半不是迁移
+      而是设计级验收（理由见上面那张表），口径在 `research-wiki/migrations/govdoc-saas.md`

 ## 本地检查

@@ -55,8 +77,8 @@ make test    # pytest（e2e 默认不跑，它打真实网关要花钱）
 make ci      # 上面两条
 ```

-仓库还没有 remote，所以没有 CI workflow。`make ci` 就是当前的全部机器闸，和 PolyGateway
-一样。等仓库推上去之后按 `research-wiki/guides/` 补 workflow（那份也还没写）。
+还没有 CI workflow，`make ci` 就是当前的全部机器闸，和 PolyGateway 一样。发布怎么做见
+[research-wiki/guides/releasing.md](research-wiki/guides/releasing.md)。

 文档质量不走机器检查，走 [CLAUDE.md](CLAUDE.md) §3 的「硕士生阅读」评审。

@@ -69,7 +91,7 @@ make ci      # 上面两条
 |---|---|
 | `reference/agent-core.md` | 别人为本项目写的一份架构提案。其中任何一条在被我们自己的 design doc 采纳前都不作数 |
 | `reference/dissect/` | 消费者，已有 ReAct 循环实现 |
-| `reference/GovDoc-SaaS/`（`background` 分支） | 消费者，已有第一次抽库尝试 `packages/docagent-core/` |
+| `reference/GovDoc-SaaS/`（`background` 分支） | 消费者的**旧代码**，第一次抽库尝试 `packages/docagent-core/`。它那边的活仓库已经把这份降级成「只作研究输入，不是当前事实来源」 |
 | `reference/GovDoc-Editor/` | GovDoc-SaaS 重构之前的那一版，今天跑在生产上。需求来源，不是迁移对象 |
 | `reference/CHSAnalyzer/` | 远期消费者；同时是本仓库协作规范的蓝本 |
 | `reference/PolyGateway/` | 本库的依赖，也是「实验室共用库该怎么做」的蓝本 |
@@ -4,8 +4,13 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "polyloop"
-version = "0.0.0"
+# 与 src/polyloop/__init__.py 的 __version__ 必须一致，由 tests/unit/test_package.py 断言。
+version = "1.0.1"
 description = "PolyLoop：实验室共用的 Agent 执行内核——一次运行的预算、停止语义、取消、逐步轨迹与 Skill 注入"
+# registry 的包页面正文只认这一项：缺了它页面就是一片空白，而 twine 只会警告
+# long_description missing，不阻塞上传——三步全绿、产物是坏的（PolyGateway 1.1.2 的教训）。
+# README 在打包时被固化进产物，发布之后再改无效，所以改 README 必须排在构建之前。
+readme = "README.md"
 requires-python = ">=3.11"
 # 3.11 是被下游钉死的：dissect 与 GovDoc-SaaS 都跑在 3.11，一个库不能要求比它的消费者更高的版本。
 dependencies = []
@@ -25,8 +30,19 @@ dev = [
    "pytest-asyncio==1.4.0",
    "ruff==0.16.2",
    "import-linter==2.13",
+    # 发布用的两个。**刻意放进 dev 而不是靠人手装**：PolyGateway 那边它们不在任何 extra 里，
+    # 于是发布指南必须多写一条「记得先装这两个」，而那种步骤迟早有人漏。
+    "build==1.5.0",
+    "twine==7.0.0",
 ]

+# 包页面上那几个链接。PyPI 的元数据里没有「仓库」这个字段，所以 registry 不会自动把包挂到
+# 仓库上——那一步只能在网页上手动做，这里这几条是包页面上唯一能自带的去处。
+[project.urls]
+Homepage = "https://gitea.iomgaa.online/iomgaa/PolyLoop"
+Changelog = "https://gitea.iomgaa.online/iomgaa/PolyLoop/src/branch/main/CHANGELOG.md"
+Issues = "https://gitea.iomgaa.online/iomgaa/PolyLoop/issues"
+
 [tool.setuptools.packages.find]
 where = ["src"]

@@ -8,11 +8,11 @@
 import 时把网关连同它的 provider 目录一起拉起来，而不传存储的人不会知道自己这次运行
 没有恢复能力。

-**当前是空骨架。** 目录与依赖契约先于代码存在，形状见
-`research-wiki/explanation/architecture.md`。
+分层与依赖方向见 `research-wiki/explanation/architecture.md`，一次运行到底保证什么见
+`tests/contract/`。
 """

 #: 与 `pyproject.toml` 的 `project.version` 必须一致，由 `tests/unit/test_package.py` 断言。
 #: 两处双写是因为运行时读不到构建元数据（未安装的源码树里 `importlib.metadata` 查不到），
 #: 而下游报 bug 时第一件事就是问版本号。
-__version__ = "0.0.0"
+__version__ = "1.0.1"