release-skill 0.1.4 → 0.1.6

package/README.zh-CN.md

@@ -2,15 +2,66 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.1.4 -->
+<!-- release-skill:release-version: 0.1.6 -->
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终
 发布的字节究竟是什么。它先冻结并供人工审阅，再从同一份冻结制品发布，不会在
 最后一步重新生成 README、重新打包活动工作区或覆盖人工内容。
 
+<!-- release-skill:managed:start id=latest-release -->
+**0.1.6** (2026-07-22)
+
+v0.1.6 是一个发布准备版本，收口了 release-docs 自动化闭环。单一结构化发布说明源通过两阶段、摘要绑定的写入协议与 prepare 文档新鲜度门禁，确定性地驱动多语 CHANGELOG 与 README 刷新；同时终态事务收据被有界化，CLI 生命周期、路径安全与错误输出脱敏均得到加固。
+
+**新增**
+
+- **结构化发布说明驱动的文档刷新（`docs refresh`）**：单一结构化发布说明源
+  （`release-notes/0.1.6.yaml`）现在确定性地驱动受管 CHANGELOG 与 README 区域的
+  多语刷新。刷新以两阶段协议运行：只读计划阶段渲染每个候选并冻结一个
+  `inputDigest`（绑定规范化说明与说明源字节）以及一个 `refreshDigest`（绑定协议
+  版本、unit、version、配置投影与逐文件新旧摘要），写入阶段则仅在三项授权齐备
+  （`--write`、精确匹配的 `--confirm-refresh <refreshDigest>` 与
+  `--ack-local-document-write`）时才提交变更目标。写入阶段在独占锁下重新计划；
+  摘要分歧时收敛为 `RELEASE_DOCS_REFRESH_STALE` 且零写入，干净计划则是零写入的
+  空操作。prepare 文档新鲜度门禁使包版本与公开文档之间的版本漂移在发布计划冻结
+  之前失败关闭。
+- **有界化的终态事务收据与恢复安全**：终态（已提交 / 已回滚）事务现在持久化
+  仅含摘要的收据而非完整载荷，单个收据上限 256 KB（`TERMINAL_RECEIPT_SIZE_CAP`），
+  并受 50 条终态记录的保留上限约束（`DEFAULT_TRANSACTION_RETENTION_MAX`）。保留
+  裁剪只移除终态记录，永不裁剪 `RECOVERY_CONFLICT` 记录或任何非终态（与恢复相关）
+  的记录，因此即便达到数量上限也保留恢复证据；保留失败永不中止进行中的提交。
+- **严格的 `docs refresh` 参数验证（失败关闭）**：`docs` 命令在调用刷新服务
+  之前验证每个参数，因此即便没有项目配置或 safe-fs 后端，也能给出精确的稳定参数
+  错误。`--flag=value` 等号形式与空格分隔形式走完全相同的验证；重复参数在任何
+  服务调用、配置读取、加锁或事务之前即以 `DUPLICATE_PARAMETER` 失败关闭；裸位置
+  参数与单短横参数（如 `-w`）被识别为未识别而拒绝。未带 `--write` 的写入授权参数，
+  或授权不全的 `--write`，都以精确原因失败关闭，而非静默继续。
+
+**修复**
+
+- **bundle 入口生命周期以真实退出码收敛**：自包含 bundle 现在拥有命令生命
+  周期。其入口等待命令完成，并针对成功、业务错误、已处理的异步拒绝与未知命令以
+  真实业务退出码退出，使启动器不再遗留未结算的顶层 await（Node 退出码 13）。当
+  bundle 缺失或无法求值时，启动器仅以静态文本失败关闭，绝不插值机器相关路径、
+  用户名或主机布局，因为模块加载失败信息携带绝对路径。
+- **失败关闭的路径规范化与稳定诊断**：artifact 路径规范化要求 POSIX 分隔符，
+  并拒绝 POSIX（`/`）、Windows 盘符与 UNC 拼写的绝对路径，连同穿越、Windows 保留
+  设备名与冒号，以 `PATH_UNSAFE` 失败关闭，而不是把不安全拼写规范化为另一个公开
+  路径。错误输出脱敏现在区分真实文件系统路径与严格的 RFC 6901 JSON Pointer 诊断
+  坐标（如 `/units/0/version`）：绝对 POSIX/Windows/UNC 路径收敛为稳定的
+  `<redacted-path>` 占位符，而诊断指针按原样保留，使失败可诊断且不泄露主机路径。
+- **self 公开边界脱敏**：集中式脱敏权威（`core/redact.mjs`）现在闭合 self
+  公开边界，使运行时错误输出与 detail 结构绝不携带 release-skill 工作区自身的绝对
+  路径，也不携带 macOS `Users`、Linux home、macOS `private`/`var` 别名、temp 或 CI
+  检出等域。脱敏经由 `ReleaseError` 收口点失败关闭：任何两段及以上、以 `/` 开头且
+  非严格诊断 JSON Pointer 的 token 都被替换为 `<redacted-path>`，因此自我发布绝不
+  向公开输出泄露私有文件系统布局。
+<!-- release-skill:managed:end id=latest-release -->
+
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.1.4 是当前发布版本。v0.1.1 已完成 GitHub 与 npm 的
+> **当前边界：** v0.1.6 是当前发布版本（v0.1.5 完成真实生产验证后曾处于这一状态）。
+> v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；“当前发布版本”与“首次生产验证里程碑”
 > 是两个不同的事实，不得混写成同一含义。同一工作流还通过了本地
@@ -22,7 +73,7 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 > 远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.4 是当前发布版本。**
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.6 是当前发布版本。**
 > npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
@@ -61,6 +112,10 @@ release-skill 不重新生成、也不回写项目源文件。`prepare` 从当
 
 ## 快速开始
 
+下文每个只读步骤都把可能很大的报告保存在临时文件中，只展示确定性的
+`compactSummary`（紧凑摘要）审阅视图；紧凑摘要只是审阅辅助，不能替代绑定摘要
+授权。
+
 ### 安装 / 前置条件
 
 - Node.js 22+
@@ -456,8 +511,9 @@ v0.1.1 生产发布验证完成后，npm 安装的 CLI 是受支持的用户入
 5. **人工审阅：** 检查返回的 `planPath`、`externalActions`、
    `units[].targetVersion` 和 `planDigest`。每个发布单元的快照位于
    `<evidenceDir>/snapshots/<unit-id>/`。release-skill 自身只把数据写入
-   `.release-skill/`；获得授权的项目 hook/gate 是无沙箱进程，可能写入其他位置或
-   访问网络。
+   `.release-skill/`；获得授权的项目 hook/gate 是没有操作系统沙箱的任意项目
+   进程，可能写入其他位置、访问网络，并读取当前账号可访问的凭据、令牌、密钥和
+   环境变量。
 6. **生产计划冻结：**
    ```bash
    PRODUCTION_JSON=$("${CLI[@]}" prepare --root "$PROJECT" --online --production \
@@ -485,7 +541,9 @@ v0.1.1 生产发布验证完成后，npm 安装的 CLI 是受支持的用户入
    `latestApprovalPath` 指向 `.release-skill/approval-record.json`，它只是可变便利
    副本，不得传给生产 publish/reconcile。批准 24 小时失效；PARTIAL 恢复可为同一
    plan 重新批准，同时逐字节保留全部旧批准。后续必须使用返回的 immutable
-   `approvalPath` 和 `expiresAt`。
+   `approvalPath` 和 `expiresAt`。`--actor` 只是未经认证的本地审计标签：
+   release-skill 不执行身份认证、不提供数字签名，因此无法证明真人已经批准——
+   它只记录操作者自报的身份。
 8. **发布（从此开始写远端）：**
    ```bash
    PUBLISH_JSON=$("${CLI[@]}" publish --root "$PROJECT" \
@@ -516,6 +574,94 @@ GitHub Release → Claude/Codex 插件市场（marketplace）安装”执行并
 默认分支名为 `release/<tag>`，可由每个 unit 的 `production.branchTemplate` 配置；
 同名远端对象存在时停止，交由人工判断。
 
+### 发布文档刷新（可选）
+
+发布单元可以声明 `releaseDocuments`，用一份结构化双语说明源确定性刷新 README
+受管区域和 CHANGELOG 当前版本条目。核心 CLI 完全离线运行：不联网、不调用大模型、
+不自动翻译；只改写声明过的受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本
+受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+
+```yaml
+# .release-skill/project.yaml（发布单元片段）
+releaseUnits:
+  - id: my-project
+    source: .
+    releaseDocuments:
+      notesSource: release-notes/{version}.yaml
+      locales: [en, zh-CN]
+      changelogs:
+        - path: CHANGELOG.md
+          locale: en
+      readmes:
+        - path: README.md
+          locale: en
+          regions: [latest-release]
+          versionMarkers:
+            - id: current-version
+              pattern: '<!-- release-skill:version -->v{version}<!-- /release-skill:version -->'
+        - path: README.zh-CN.md
+          locale: zh-CN
+          regions: [latest-release]
+```
+
+`notesSource` 和所有目标路径均相对发布单元根。`versionMarkers[].pattern` 必须与
+README 现有唯一版本标记精确匹配，`{version}` 代表机器版本值；刷新只替换该值
+（零次或多次匹配失败关闭）。
+
+```yaml
+# release-notes/0.1.6.yaml（结构化说明源）
+version: 0.1.6
+date: 2026-07-21
+locales:
+  en:
+    summary: Deterministic multilingual release-document refresh.
+    changes:
+      added:
+        - Refresh managed README regions and changelogs from one source.
+    upgradeNotes: Review and commit refreshed documents before prepare.
+  zh-CN:
+    summary: 从同一说明源确定性刷新多语种发布文档。
+    changes:
+      added:
+        - 自动刷新 README 受管区域和 CHANGELOG。
+    upgradeNotes: prepare 前审阅并提交刷新结果。
+```
+
+`version` 必须与解析出的单元版本精确一致；每个配置语种恰好出现一次，`summary`
+与变更项非空，且 `security`、`breaking`、`added`、`changed`、`deprecated`、
+`removed`、`fixed` 中至少一个类别含条目。YAML alias、重复键、未知字段和语种回退
+均失败关闭。
+
+1. **只读演练：**
+   ```bash
+   "${CLI[@]}" docs refresh --root "$PROJECT" --unit my-project --json
+   ```
+   输出 `status`（`changes` 或 `clean`）、逐文件相对 `path`、`locale`、`kind`、
+   新旧摘要、单元 `version`、`locales`、`inputDigest` 和 `refreshDigest`。
+   `refreshDigest` 绑定协议版本、发布单元、规范说明对象、配置投影和按路径排序的
+   逐文件新旧摘要，不绑定时间、绝对路径或展示文本；`nextCommand.argv` 给出精确
+   写入命令。
+2. **摘要确认的本地写入（仅在用户明确授权“本地发布文档写入”后执行）：**
+   ```bash
+   "${CLI[@]}" docs refresh --root "$PROJECT" --unit my-project \
+     --write --confirm-refresh <refreshDigest> \
+     --ack-local-document-write --json
+   ```
+   三项绑定缺一不可；摘要不匹配以 `RELEASE_DOCS_REFRESH_STALE` 失败关闭且零写入。
+   候选无变化时演练返回 `clean`，写入同样零写入。全部目标作为一个事务提交；
+   写入成功后立即复演，必须返回 `clean`。
+
+该授权只覆盖声明的本地发布文档目标，不是 hook、Git 提交、push、publish 或安装的
+授权：维护者必须审阅刷新结果并提交，然后重新 `prepare`——新字节会改变快照、
+workspace digest 和 plan digest，旧批准不能授权刷新后的计划。
+
+配置了 `releaseDocuments` 的文档发生漂移时，`prepare` 在 hook、基线、快照、
+远端检查和计划冻结前以 `RELEASE_DOCS_STALE` 失败关闭。恢复路径：运行演练，审阅
+展示的文件/语种/版本/摘要，授权并执行本地写入，审阅提交后重新 `prepare`。
+`RELEASE_DOCS_INVALID`（配置或说明数据非法）、`RELEASE_DOCS_TRANSLATION_MISSING`
+（配置语种缺失）和 `RELEASE_DOCS_CONFLICT`（非受管同版本内容或标记损坏）都需要
+先修复源或目标，不得扩大写入范围解决。
+
 ### 父工作空间 + npm 子单元 + 插件子单元
 
 当 monorepo 从不同目录同时产出 npm 包和 Claude/Codex 插件时，应定义独立的
@@ -524,6 +670,10 @@ GitHub Release → Claude/Codex 插件市场（marketplace）安装”执行并
 
 本例中的 `project` 是父工作空间的编排容器，本身不是公开发布单元；如果工作空间
 根目录也要发布独立仓库或 package，应再增加一个 `source: .` 的 release unit。
+`version.source` 相对于该发布单元的 `source` 目录解析
+（`version.source` is resolved relative to that release unit's `source` directory）：
+`source: packages/app` 的单元应直接写 `package.json`，而不是
+`packages/app/package.json`。
 
 ```yaml
 apiVersion: release-skill/v1
@@ -537,7 +687,7 @@ releaseUnits:
     source: packages/app
     publicRepo: owner/my-app
     version:
-      source: packages/app/package.json
+      source: package.json
       tagTemplate: my-app-v{version}
     distributions:
       - type: npm
@@ -573,7 +723,7 @@ releaseUnits:
     source: packages/plugin
     publicRepo: owner/my-plugin
     version:
-      source: packages/plugin/package.json
+      source: package.json
       tagTemplate: my-plugin-v{version}
     distributions:
       # 只有当单元确实发布插件时才声明插件消费者。
@@ -582,10 +732,12 @@ releaseUnits:
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # 可选；范围 30000–900000；默认 300000
       - type: codex-plugin
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # 可选；范围 30000–900000；默认 300000
     publicFiles:
       - from: packages/plugin/.claude-plugin/plugin.json
         to: .claude-plugin/plugin.json
@@ -631,6 +783,12 @@ releaseUnits:
 入口 Skill 和全部 required public files。CLI 冒烟（`smokeBin`）对插件单元
 是可选项，仅当发布包同时暴露 CLI 二进制时才适用。
 
+插件分发可声明 `timeoutMs`（范围 30,000–900,000 毫秒；默认 300,000 毫秒），
+用于设置 marketplace add、plugin install 和 plugin list 三条命令的子进程超时。
+真实网络下这些命令可能需要 40–105 秒；默认 300 秒超时避免误报 `PARTIAL`。
+解析后的值冻结到计划中，与其他动作参数一起接受批准。无 `timeoutMs` 的旧计划
+在执行时默认回退到 300,000 毫秒以保证向后兼容。
+
 ### PARTIAL 恢复与 reconcile
 
 当 `publish` 在部分检查点成功但在其他检查点失败时，运行进入 `PARTIAL`
@@ -684,6 +842,28 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 父工作区的步骤。它们可能修改项目或访问网络，prepare 必须显式传入
 `--acknowledge-hook-side-effects`。
 
+每个 hook 都是一个对象，绝不是裸命令列表。
+`command` 是可执行文件/参数数组，不是 shell 字符串
+（`command` is an executable/argument array, not a shell string）。每个 hook 还声明
+`cwd`、`timeoutMs` 和 `envAllowlist`：
+
+```yaml
+hooks:
+  build:
+    command: [node, scripts/build.mjs]
+    cwd: .
+    timeoutMs: 120000
+    envAllowlist: [CI]
+  test:
+    command: [node, --test, test/]
+    cwd: .
+    timeoutMs: 300000
+    envAllowlist: []
+```
+
+hook 同样必须先逐项审阅配置的可执行文件、参数、工作目录和副作用，
+并经 `prepare --acknowledge-hook-side-effects` 明确授权才会运行。
+
 `verificationGates` 是更适合发布校准的受控扩展点：
 
 ```yaml

package/adapters/claude/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/adapters/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"