release-skill 0.1.5 → 0.1.7

package/README.zh-CN.md

@@ -2,15 +2,39 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.1.5 -->
+<!-- release-skill:release-version: 0.1.7 -->
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终
 发布的字节究竟是什么。它先冻结并供人工审阅，再从同一份冻结制品发布，不会在
 最后一步重新生成 README、重新打包活动工作区或覆盖人工内容。
 
+<!-- release-skill:managed:start id=latest-release -->
+**0.1.7** (2026-07-23)
+
+v0.1.7 是一个组织迁移版本。公开 GitHub 仓库从 `mzdbxqh/release-skill` 迁移至 `ifoohoo/release-skill`（仓库名不变，GitHub 对旧 URL 做重定向），项目新增明确的公司维护主体与版权持有人（广州市风荷科技有限公司），并将面向未来版本的仓库、维护主体、作者与版权元数据在 npm 包、插件市场清单、NOTICE、LICENSE 与发布配置中统一对齐到新组织。npm 包名（`release-skill`）与 npm 发布身份（`publisher: mzdbxqh`）保持不变，已发布的 v0.1.6 标签、GitHub Release 与 npm 版本不被改写。
+
+**变更**
+
+- **公开仓库迁移至 `ifoohoo` 组织**：公开 GitHub 仓库从
+  `mzdbxqh/release-skill` 转移到 `ifoohoo/release-skill`，仓库名不变。默认分支仍为
+  `main`，v0.1.6 标签、发行版与历史均被保留，旧 URL 以 HTTP 301 重定向到新位置。
+  发布配置（`publicRepo` 与绑定的 `previousPublicBaseline`）现在指向
+  `ifoohoo/release-skill`，并以公开 v0.1.6 提交
+  `48fb2a258a2786c2e32136ad67bd51f3a280b3b8` 作为上一公开基线。
+- **公司维护主体与版权**：MIT LICENSE（根目录与公开包）现在携带 release-skill
+  贡献者与广州市风荷科技有限公司的双行版权声明；NOTICE 明确项目由广州市风荷科技
+  有限公司维护，并说明 GitHub 仓库转移属于托管位置与维护身份的行政变更，本身不构成
+  著作权转让。
+- **面向未来版本的元数据与组织对齐**：npm `package.json` 的仓库、主页与问题
+  跟踪地址指向 `ifoohoo/release-skill`，并在保留 release-skill 贡献者的同时新增公司
+  作者。Claude Code 插件市场所有者现在标识 `ifoohoo` 组织。npm 包名
+  （`release-skill`）与 npm 发布身份（`publisher: mzdbxqh`）保持不变。
+<!-- release-skill:managed:end id=latest-release -->
+
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.1.5 是当前发布版本。v0.1.1 已完成 GitHub 与 npm 的
+> **当前边界：** v0.1.7 是当前发布版本（v0.1.6 完成真实生产验证后曾处于这一状态）。
+> v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；“当前发布版本”与“首次生产验证里程碑”
 > 是两个不同的事实，不得混写成同一含义。同一工作流还通过了本地
@@ -22,7 +46,7 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 > 远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.5 是当前发布版本。**
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.7 是当前发布版本。**
 > npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
@@ -61,6 +85,10 @@ release-skill 不重新生成、也不回写项目源文件。`prepare` 从当
 
 ## 快速开始
 
+下文每个只读步骤都把可能很大的报告保存在临时文件中，只展示确定性的
+`compactSummary`（紧凑摘要）审阅视图；紧凑摘要只是审阅辅助，不能替代绑定摘要
+授权。
+
 ### 安装 / 前置条件
 
 - Node.js 22+
@@ -456,8 +484,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 +514,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 +547,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 +643,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 +660,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 +696,7 @@ releaseUnits:
     source: packages/plugin
     publicRepo: owner/my-plugin
     version:
-      source: packages/plugin/package.json
+      source: package.json
       tagTemplate: my-plugin-v{version}
     distributions:
       # 只有当单元确实发布插件时才声明插件消费者。
@@ -692,6 +815,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

@@ -2,14 +2,14 @@
   "name": "release-skill",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "owner": {
-    "name": "mzdbxqh",
-    "url": "https://github.com/mzdbxqh"
+    "name": "ifoohoo",
+    "url": "https://github.com/ifoohoo"
   },
   "plugins": [
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.5",
+      "version": "0.1.7",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

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

@@ -1,9 +1,9 @@
 {
   "name": "release-skill",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
-    "name": "release-skill contributors"
+    "name": "广州市风荷科技有限公司"
   },
   "license": "MIT",
   "skills": "./skills/"