更新日志 — PactKit Docs

4.1.0 — 2026-10-02

增强旧项目兼容诊断与安全迁移能力。 策略有歧义的项目会被要求裁定—— 而不是被替你裁定。

这一版不承诺所有老项目自动迁移，也不承诺行为完全不变。它承诺的是：支持范围内有证据、范围外有明确提示、任何情况下不静默改变项目策略。

四包共享 major.minor，lockstep 发布。 每个 adapter 钉 pactkit>=4.1.0,<4.2.0，且 doctor.check_adapter_compat 要求 adapter 的 major.minor 等于 core 的。core 4.1.0 与 4.0.0 的 adapter 是明确不允许的组合 ——部署会被 skew guard 拒绝。

升级 CLI 会立即改变旧 hook 的行为，但不会迁移项目。 旧 Git wrapper 执行的是 PATH 上的 pactkit，所以 pip/pipx 升级后下一次 git push 就跑新版本；而项目的配置形态、hook 链、.gitignore 都不会被改写。要在项目里换链，跑 pactkit commit-gate --install --migrate。

升级前核对三样，不能只看版本号：版本（pactkit version）、安装来源（pip show / direct_url.json）、产物完整 sha256。本机历史上存在多个不同构建都报同一个版本号的情况。

新增

项目形态盘点。 init / update / upgrade 与 commit-gate --install 会先打印一张逐入口表——同一形态在不同宿主信号下各读到什么——并明确说明 不会替你改配置。只读、只报、不阻断。
配置三层事实（发现 / 选择 / 解析）。doctor --json 给出候选、选定层、解析状态与比较完整性。"多份副本且无共享层"与"没有配置"现在是两个不同的状态。

修复

Copilot 适配器不认 -C。 pactkit -C <别的项目> update --format copilot 会把 44 个生成物写进调用方 cwd：分派器对「签名里没有 project_root」的 deployer 静默丢弃该参数，而 copilot 的部署根是项目相对的 .github/，于是退回 Path.cwd()。现在明确拒绝而不是丢弃；三个 adapter 都接收并使用项目根。
doctor 把同一批分歧打印两遍。 逐键详情现在文本里只留一次摘要，完整内容在 doctor --json 的 config_source.divergence 里——而那份 JSON 此前一条都没有。

说明

支持范围——哪些可兼容读取、副本如何选择、update 保护什么、以及未覆盖什么 ——见 migration-support-scope-4.1.md。一句话版本：无宿主信号的进程会兼容读取 恰好一份宿主副本（至 5.0.0 到期）；两份以上且无共享层则一份都不选，有效值全部来自默认。

4.0.0 — 2026-09-26

Kernelization + Repository Coherence。 宿主归属彻底移出 core；生成的配置写到哪里，不再靠猜。

自 3.1.0 起全部是契约边界变更——这是 major 而不是 minor 的原因。即使不拆任何包，4.0 仍改变 spec lifecycle / story 状态机 / evidence contract / prompt 生成模型 / truth hierarchy / 迁移行为 / artifact 元数据 / garden 语义。

升级编排（必读）

四包共享 major.minor，lockstep 发布。 两条独立的锁表达同一件事：每个 adapter 钉 pactkit>=4.0.0,<4.1.0，且 doctor.check_adapter_compat 要求 adapter 的 major.minor 与 core 相同。

core 4.0.0 与 3.x 的 adapter 是明确不允许的组合——部署会被 skew guard 拒绝：

✗ Adapter pactkit-codex 3.1.0 incompatible with core 4.0.0 (major/minor mismatch)

这是刻意选择的更轻失败模式：import 正常、注册正常，只有部署被拦下，可用 --allow-adapter-skew 显式放行。请四包一起装：

pip install -U "pactkit==4.0.0" "pactkit-opencode==4.0.0" \
              "pactkit-codex==4.0.0" "pactkit-copilot==4.0.0"

移除

core 不再为任何外部宿主声明任何东西（SPEC-4.0-22 Step 7）。profile、能力、 pre-tool 面、部署声明、安全事实、线格式，全部由各自 adapter 自带并经 entry-point discovery 注册。core 只保留它自己随包发布的 classic。
resolve_pactkit_yaml_dir 的目录存在性回退（Step 8）。写入目标不再由「哪个目录碰巧存在」决定——实测 mkdir .opencode && pactkit init --format classic 会把 classic 的配置写进 .opencode/pactkit.yaml。规则改为： 读取可以发现已有层；写入必须知道自己正在为哪个 format 写。
adapter 的内联 pactkit.yaml 模板（Step 8 R-②-1）。它们写出的 stack: unknown 不在 core 的 VALID_STACKS 里，且没有 schema_version—— adapter 在写 core 校验器会拒绝的值，而没有人读回来看。

变更

所有宿主的 pactkit.yaml 由同一个 canonical format-aware generator 产生。 adapter 只声明位置（profile.pactkit_yaml_path）与是否需要，不再发明格式。
opencode 现在真的生成 .opencode/pactkit.yaml。 此前它被声明、被搜索、从不被生产者创建——却能被别的宿主创建。「声明 + 搜索 + 不生产」会让后续判断把一个不存在的状态当成正常候选。
register_adapter 的重注册保留 input_translation。 它是第五个声明成员，此前漏了 carry-forward：重注册会静默撤回线格式声明，translate_host_payload 随即认不出该宿主，整条通道 fail-open。

说明

四宿主在 fresh init 下生成的配置逐字节相同。已存在任意 pactkit.yaml 的项目不自动增殖宿主副本——它继续复用现有层（已知行为，非缺陷）。
本段在 v4.0.0 tag 之后补写，因此不包含在 tag 指向的那棵树里。

3.1.0 — 2026-09-25

宿主归属移出 core。这是契约边界变更，不是内部重构——所以是 minor 而不是 patch。

移除

core 不再为 opencode / codex / copilot 声明任何东西；过渡期的 API 与状态整体删除。

变更

宿主从「core 预置」变成「adapter 装上才出现」。未安装的宿主无法注册，所以 format: all 不会为一个从未部署过的宿主安装通道。

说明

升级顺序有讲究。 core 与 adapter 必须共享 major.minor。本版要求 adapter 先升；把新 adapter 装到旧 core 上会让 pip 为满足钉版而静默降级 core。

3.0.4 — 2026-09-24

为 adapter 解锁的 core 依赖发布。宿主描述数据从 core 的硬编码表迁进可注册的 AdapterRegistration，并落地三个 adapter 自带声明所需的类型与 API。

这不是 PactKit 4.0 的最终发布——4.0 的 lifecycle closure 还在后面。本版的定位是让 adapter 能站起来，不是宣布内核化完成。

升级

新 adapter + 旧 core 是不兼容组合，不是运行时回归。 三个 adapter 钉 pactkit>=3.0.1,<3.1.0，所以升级到新 adapter 时 pip 会同时把 core 升到本版； 只升 core 不升 adapter 是安全的。反过来，手工把新 adapter 装到 core 3.0.3 上会得到 ModuleNotFoundError: No module named 'pactkit.capability'，注册表退化成只剩 classic——这是安装组合的问题，不是缺陷，重装 core 即可恢复。