peaks-loop 4.0.0-beta.3 → 4.0.0-beta.31

package/README.md

@@ -1,102 +1,260 @@
-# Peaks Loop
+<div align="center">
 
-[English](./README-en.md) | **简体中文**
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### 你说话,它替你跑完一整条工程流水线 —— 不止写代码,跑两次就沉淀成本地战术。
+
+[![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop)
+[![publish](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/publish.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=publish)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/publish.yml)
+[![ci](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=ci)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&github=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+
+[English](./README-en.md) · **简体中文**
+
+</div>
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">
-    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/zh-closing-960.png" alt="peaks-loop demo (点击播放)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
-  </a>
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.gif"
+    alt="peaks-loop 30 秒演示(前 18 秒 · install + 斜杠命令 + 5 域 + 沉淀成 bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
   <br>
-  <sub>👆 点击图片播放 60s 演示</sub>
+  <sub>👆 18s 循环 GIF(完整 30s mp4 不再随 npm 包发布,见 <a href="https://github.com/SquabbyZ/peaks-loop/releases">GitHub Release</a> · 13MB · 480p)</sub>
 </p>
 
+---
+
 ## 它是什么
 
-### loop engineering 的工程实现
+peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。**Loop engineering 结晶系统** 的工程实现见 [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)。
 
-**peaks-loop 是你的 Loop Engineering 结晶系统 —— 不是工作流工具。** 它从真实完成的工作里把 loop engineering 资产结晶出来,只通过被验证的改进让它们进化。你只用自然语言和选择操作系统,所有结构化操作由 LLM 代办。
+| 资产层 | 角色 | 一句话 |
+| --- | --- | --- |
+| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
+| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
+| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
+| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
 
-产品遵循四层资产模型与 karpathy × darwin 双层纪律,两者缺一不可:
+- **工程化每条规则 = karpathy 风格 · 验证每次改进 = darwin 风格** —— 两条缺一不可。砍掉 karpathy,原则没人写清;砍掉 darwin,改得对不对没人验。这一对是 co-equal 的双层结构,不是先后两步。
+- `/peaks-code` 是 **code-domain** 长任务 Loop Engineering 编排器,不是通用编排器;非代码域(`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`)都是独立的 `peaks-*` 蜂,不是 `peaks-code` 的子类。
+- 跑两次稳定就沉淀成本地战术(bee);跑翻车的会让你重定义。bee 跟着你的口味长。
 
-- **四层资产模型**:Loop Engineering 资产(方法体系,一等公民)+ Bee 资产(可执行体,一等公民)+ Workflow Trace(执行轨迹,只作证据,不作资产)+ Evolution Evaluation(反漂移闸门,变更必经)。
-- **karpathy × darwin 双层纪律**:karpathy 工程化每一条规则(failure modes + imperative→declarative rewrite + self-check + out-of-scope);darwin 校验每一次改进(单对象 + 单维度 + 独立上下文评估 + ratchet 防回退)。两层是平行的伙伴,谁都不是谁的子集 —— 详见 `.peaks/standards/loop-engineering-guidelines.md` 与上游参考 `multica-ai/andrej-karpathy-skills`、`alchaincyf/darwin-skill`。
-- **post-run crystallization**:`loop_release` 与 `bee_release` 只在一次真实任务跑完后才写入;pre-run 永远是 scratch。沉淀触发支持四种,user explicit 优先级最高。
-- **Human-NL-Choice-Only**:你只说话或选择,LLM 替你跑 CLI;禁止手写 JSON / manifest / form field。
+---
 
-### peaks-code 是 code-domain 唯一的入口
+## 30 秒上手
 
-`peaks-code` 是 loop engineering 在 **代码域** 的长任务编排器,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。它**不是通用编排器** —— 研究 / 内容 / 产品等其他域各自是独立的 `peaks-*` 技能,复用同一份 Loop Engineering 准则。详见 Loop Engineering 设计 `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8,以及 sediment 设计 `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`。
+```bash
+npm i -g peaks-loop
+```
 
-召之即来,事完收队,**不跳步,不半截扔给你**。它不是新发明一个 AI CLI,而是架在你已有的 Claude Code / Codex / Copilot 之上,把它们都调成同一支团队,只对你这一个开发者的口味。
+装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
-**每一步都有强退出条件**:审计不通过就停,QA 没过就停,任何一道门失败 = 全流程停。你不必追着它催、也不必替它补,它跑完一道再交你拍板,拍完再走下一道。
+```
+/peaks-code 帮我熟悉下当前的项目
+```
 
-#### 门禁不是装饰 —— 5439 tests passed · 19 skipped · 0 failed
+剩下的就交给 peaks-loop —— 它会按这条命令的语义判断该走哪一域,用对应的编排器拆工序,一道门一道门跑,**坏在哪道停在哪道**,中间不会扔半截给你。
 
-每一行代码都过自己的门:测试套件 5,420 个用例真挡得住事,不是装饰。门禁不是写给用户看的,是写给自己看的。
+其他常用的显式命令:
 
-#### 做这个项目的只有一个人,工程师口味:
+```
+/peaks-content                 帮我把今天这篇推文写完发出
+/peaks-doctor                  帮我体检一下这个仓库
+/peaks-issue-fix-orchestrator  帮我把 upstream 的 30 个 open issue 修一批
+/peaks-sop                     帮我把团队的发布流程沉淀成 SOP
+/peaks-solo                    这套打法以后还会用,沉淀成本地战术
+/peaks-solo                    按上次那样再跑一次
+```
 
-- **极客精神。**
-- **你跟 AI 之间只该用自然语言讲话,没有 CLI 表面给你。**
-- **单测覆盖率和门禁审计真挡得住事,不是装饰。**
-- **严于律己,宽以待人 —— 自己写的代码过自己的门,使用者随便怎么说都能跑通。**
-- **AI 使用水平的下限平权:你不需要懂 prompt engineering,就跟说话一样用。**
+<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
 
-这套项目级硬规则也写进了 `~/.peaks/memory/`,不是口号,是被工具链守住的红线。
+不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
 
-## 装了你有什么战术角色
+---
 
-先给你上的是 `peaks-code`,主官。它是 peaks-loop 默认入口,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。
+## 它能为你做什么
 
-它能做的:
-- 写长任务代码(端到端需求 → PRD → 实现 → QA),一道门一道门跑,坏在哪道停在哪道
-- 修 bug 当天发,改完顺手过审 + 测试,不是改完就完
-- 帮你做 / 接 / 拆长跑的需求,把一个模糊需求一路剥到能落地的实现
+代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
-它一句话能扛完的活,你都不必开第二个终端。它对测试覆盖率、审计门、卡点阻断一视同仁:跑不到位的活不交付,跑歪的活直接退回重跑。
+| 域 | 你发这条命令 | 它会做什么 |
+| --- | --- | --- |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 帮我实现这个功能` | PRD → RD → 实现 → QA → UI → 切片,跑完交你拍板 |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 这个 bug 帮我修一下` | 复现 → 改 → review → 测试,同日 ship |
+| 📝 **内容** | `/peaks-content 帮我把这篇推文写出来再发` | 草稿 → 编辑 → 调性检查 → 发布 → 归档,中间不跳步 |
+| 🩺 **项目健康** | `/peaks-doctor 帮我体检一下这个仓库` | 红线审计 + L3 doctor 检查 + 转 OpenSpec,坏在哪道停在哪道 |
+| 🐛 **批量修 issue** | `/peaks-issue-fix-orchestrator 帮我把 upstream 的 30 个 open issue 修一批` | 调研 → 分类 → 参考 PR → 逐个修复 + commit + PR 草稿 |
+| 📋 **自定义工作流** | `/peaks-sop 帮我把团队的发布流程沉淀成 SOP` | 自然语言描述 → 自动生成 + 校验 + 注册成可执行的 SOP |
+| 🔁 **跑过一次再来** | `/peaks-solo 按上次那样再跑一次` | 调出你已经沉淀好的战术,自动复跑 |
+| 🆕 **接手陌生仓库** | `/peaks-code 这是新仓库,先带我过一遍` | 摸清结构、识别风险点、给一个上手顺序 |
+| 🧠 **沉淀自己的打法** | `/peaks-solo 这套打法以后还会用,沉淀一下` | 变成你本地常驻的战术,下次说"跑那只"就行 |
 
-它既是装好就立刻能用的那个入口,也是后面要长出来的内建角色的调度口;它内部有一套连续审计、QA 闸口、review 验收,默认打开,你想关哪一道才需要单独说。
+每一条路,**一条斜杠命令**就能开跑。
 
-其他内置 loop engineering,敬请期待。
+---
 
-## 你也能沉淀自己的 loop engineering
+## 为什么大家会选它
 
-跑过一次还想跑,说一句话让它永久驻场。
+- **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
+- **门禁真挡事,不是装饰** —— 5,439 个测试用例、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
+- **跑过的事会变成本地战术(bee)** —— 沉淀下来的 loop engineering 落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
+- **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
+- **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
 
-你沉淀的是 loop engineering(战术套路),不是简单的 skill(动作招式)。下次说"跑那只",整套流程自动就位。
+---
 
-它落到你本地的一个池子里,只对你生效。命名、复用、迭代都是你说了算:跑过两遍稳定的会被抬高,跑翻车的会让你重新定。决策影响资产的,你拍板。
+## 装上以后的几道闸门
 
-这套机制关键不是"工具给你造了多少只 bee",而是你那几只 bee 一直在跟着你的口味长 —— 你提一句,它长一点。
+| 闸门 | 默认状态 | 用来挡什么 |
+| --- | --- | --- |
+| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
+| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
+| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
+| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
+| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
 
-## 上号
+**所有闸门默认开,你想关哪一道才需要单独说。**
 
-```bash
-npm i -g peaks-loop
-```
+---
+
+## 当前状态 · 4.x 正式版
+
+| | |
+| --- | --- |
+| **最新版本** | [`4.0.0-beta.31`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x 正式版筹备中 |
+| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测) |
+| **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
+| **测试套件** | 5,439 passed · 19 skipped · 0 failed |
+| **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
+| **依赖运行时** | Node ≥ 20 |
+| **License** | MIT |
+
+---
+
+## 强烈推荐 · 四个项目组合起来用
+
+> **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
+
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC">
+    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/Egonex-AI/Understand-Anything">
+    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/obra/superpowers">
+    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
+  </a>
+</p>
 
-装完一句话接活。
+| 角色 | 项目 | 一句话 |
+| --- | --- | --- |
+| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 | loop engineering 结晶系统,装上就有 PRD/RD/QA/UI/SC/TXT 一整条工程链 + 沉淀 |
+| **战术手册** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code:Claude Code 上能拿到的最好用的战术、技能、SOP 集合 |
+| **代码理解** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | 任意仓库,一句话读懂 —— 让 LLM 真正"理解"项目,而不是猜 |
+| **流程与纪律** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review 等流程纪律,每条都自带硬退出条件 |
 
-## 顺便说一句
+**用起来就一句话**:把上面三个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
 
-这个仓库以前叫 [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli),现在叫 `peaks-loop`。
+### 致敬
 
-里面的技能从 `peaks-code`(单角色)演化到 `peaks-code`(带门禁的代码域).两边都还在,只是分工不同:`peaks-code` 如今是给单任务跑流程用的那个老入口,`peaks-code` 接管了端到端的主路径。
+peaks-loop 的两条工程脊柱直接来自这两个项目:
 
-事情一直没换过:你说话,它替你排工程门禁,坏哪道停哪道,你来拍板。
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
 
-你只需要把这一个仓库装好,后面每次跑新需求,都有现成的战术角色等你点。
+---
+
+## FAQ
+
+<details>
+<summary><b>它跟 Claude Code / Z Code 是什么关系?</b></summary>
+
+它是**搭在上面**,不是替换。peaks-loop 不抢你的 shell、不抢你的 prompt、不抢你的 IDE。它在 Claude Code / Z Code 这两个一等公民适配里跑,你照常用。**其他 AI 编程工具适配中,欢迎共建** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)。
+
+</details>
+
+<details>
+<summary><b>我需要记 CLI 命令吗?</b></summary>
+
+不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
+
+</details>
+
+<details>
+<summary><b>沉淀下来的战术会一直留在本地吗?</b></summary>
+
+会。沉淀落在你本地的池子里,只对你生效。命名、复用、迭代都是你说了算;跑翻车的会让你重新定义。
+
+</details>
+
+<details>
+<summary><b>它会自己改我的代码吗?</b></summary>
+
+改,但过门禁。**审计不通过 = 不出门**,**QA 没过 = 不出门**,**review 不通过 = 不出门**。它替你跑,但每道门都给你审。
+
+</details>
+
+<details>
+<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
+
+**最大的不同:从"代码专用"扩成"多域编排系统"。** 4.x 不再只是写代码 —— 新增了 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。再加 9 个 IDE 适配、结晶系统重命名、post-run crystallization 机制、5,439 tests 通过。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
+
+</details>
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## 链接
 
 - 全部技能清单 → [`skills/`](./skills/)
-- 设计文档 → [`docs/`](./docs/)
 - 更新日志 → [`CHANGELOG.md`](./CHANGELOG.md)
 - 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- 组合推荐: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
+- 沉淀设计 → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
+- Loop Engineering 结晶设计 → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
+
+---
+
+## 发布(Trusted Publishing · OIDC)
+
+本仓库发布链路**不**使用 npm token,改用 **Trusted Publishing + OIDC**:
+
+- 维护者**不需要**也不会持有 `NPM_TOKEN` —— `~/.npmrc` 已被清理,npmjs.com 已把 Publishing access 切到 disallow tokens。
+- 触发方式 1:`git tag vX.Y.Z && git push --tags`(走 `.github/workflows/publish.yml` 的 `push: tags: v*.*.*` 触发器)。
+- 触发方式 2:GitHub UI → Actions → publish → Run workflow(手动兜底,可用于 dry-run / 补发)。
+- 每次发布跑完整链路:`install → typecheck → build → vitest → changesets version → changesets publish`,全部通过才会真正落到 npm。
+- 维护者的本地动作只有两步:`pnpm changeset` 写变更说明 + 合并 PR(剩下的 CI 自动跑)。
+
+**npmjs 侧一次性配置**(本 slice 完成后由人工做一次):
+
+1. 登录 https://www.npmjs.com → Settings → Trusted Publishers → Add GitHub Action。
+2. Owner / Org:`SquabbyZ` · Repository:`peaks-loop` · Workflow filename:`publish.yml` · Environment name:留空。
+3. 保存。
+
+**撤销** = npmjs 端删 trusted publisher,**无需** rotate token。
+
+**常见故障**:
+
+| 现象 | 原因 | 修法 |
+|------|------|------|
+| publish 步骤报 `Cannot get JWT` | 缺 `id-token: write` | 检查 `.github/workflows/publish.yml#permissions` |
+| publish 步骤报 `ENEEDAUTH` 或 `404 from registry.npmjs.org` | npmjs 端没配 trusted publisher | 走上面的 3 步配置 |
+| `changeset version` 把 `package.json` 改了我没想要 | 漏掉了手动 version | 提交前先本地 `pnpm changeset version`,CI 端为 no-op |
+| tag 推了但 CI 没跑 | tag 格式不符 `v*.*.*` | 检查 `git tag` 输出 |
+
+详细 RD 文档见 [`docs/superpowers/slices/slice-s1-trusted-publish.md`](./docs/superpowers/slices/slice-s1-trusted-publish.md)。
+
+---
+
+<div align="center">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
+
+</div>

package/bin/peaks.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/src/cli/index.js';
+import '../dist/cli/index.js';

package/dist/cli/cli-helpers.d.ts

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from 'peaks-loop-shared/result';
+import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
+import type { ConfigLayer } from '../services/config/config-service.js';
+import type { RecommendationWorkflow } from '../services/recommendations/recommendation-service.js';
+export type ProgramIO = {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function printResult<T>(io: ProgramIO, result: ResultEnvelope<T>, asJson?: boolean): void;
+export declare function addJsonOption(command: Command): Command;
+export declare function failUnsupportedNonDryRun(io: ProgramIO, command: string, asJson?: boolean): void;
+/** CLI shim helper: render a `{ ok: boolean, error?, data? }` envelope
+ *  and set `process.exitCode = 1` on failure.
+ *
+ *  Library functions MUST return envelopes like `{ ok, error?, data? }`
+ *  and MUST NOT mutate `process.exitCode` themselves. The shim (the
+ *  Commander `.action()` callback in `register*Commands`) owns the
+ *  process-exit side-effect so the library can be re-used from non-CLI
+ *  contexts (vitest, programmatic dispatch, plugin loading).
+ *
+ *  Output format mirrors the existing `registerSedimentCommands` shim:
+ *  a JSON envelope on stdout (one line, parseable), nothing else.
+ */
+export interface CliEnvelope {
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+export declare function printCliEnvelope(io: ProgramIO, r: CliEnvelope): void;
+export declare function isRecommendationWorkflow(value: string): value is RecommendationWorkflow;
+export declare function isArtifactProvider(value: string): value is ArtifactProvider;
+export declare function isArtifactSetupStep(value: string): value is GuidedArtifactSetup['step'];
+export declare function isArtifactRepoSegment(value: string): boolean;
+export declare function parseConfigLayer(value: string | undefined): ConfigLayer | undefined | null;
+export declare function printInvalidConfigLayer(io: ProgramIO, command: string, asJson?: boolean): void;
+export declare function multipleOption(value: string, previous: string[]): string[];
+export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/cli-helpers.js

@@ -0,0 +1,62 @@
+import { fail, getErrorMessage, ok, redactSensitiveErrorMessage } from 'peaks-loop-shared/result';
+export function printResult(io, result, asJson = false) {
+    if (asJson) {
+        io.stdout(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.ok) {
+        io.stderr(`${result.code}: ${result.message}`);
+        for (const action of result.nextActions) {
+            io.stderr(`- ${action}`);
+        }
+        return;
+    }
+    io.stdout(JSON.stringify(result.data, null, 2));
+    for (const warning of result.warnings) {
+        io.stderr(`warning: ${warning}`);
+    }
+    for (const action of result.nextActions) {
+        io.stdout(`next: ${action}`);
+    }
+}
+export function addJsonOption(command) {
+    return command.option('--json', 'print machine-readable JSON envelope');
+}
+export function failUnsupportedNonDryRun(io, command, asJson) {
+    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), asJson);
+    process.exitCode = 1;
+}
+export function printCliEnvelope(io, r) {
+    if (r.ok) {
+        io.stdout(JSON.stringify({ ok: true, data: r.data ?? null }));
+        return;
+    }
+    io.stdout(JSON.stringify({ ok: false, error: r.error }));
+    process.exitCode = 1;
+}
+export function isRecommendationWorkflow(value) {
+    return value === 'code-refactor' || value === 'product-refactor' || value === 'frontend-design';
+}
+export function isArtifactProvider(value) {
+    return value === 'github' || value === 'gitlab';
+}
+export function isArtifactSetupStep(value) {
+    return value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete';
+}
+export function isArtifactRepoSegment(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
+}
+export function parseConfigLayer(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value === 'user' || value === 'project' ? value : null;
+}
+export function printInvalidConfigLayer(io, command, asJson) {
+    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, ['Use --layer user or --layer project']), asJson);
+    process.exitCode = 1;
+}
+export function multipleOption(value, previous) {
+    return [...(previous || []), value];
+}
+export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/commands/_cli-error-envelope.d.ts

@@ -0,0 +1,19 @@
+export type EnvelopeMapping = {
+    code: 'INVALID_GOAL';
+    nextActions: readonly string[];
+} | {
+    code: 'INVALID_PROVIDERS';
+    nextActions: readonly string[];
+} | {
+    code: 'INTERNAL_ERROR';
+    nextActions: readonly string[];
+};
+/**
+ * Map a thrown error into an envelope code + nextActions hint. Pure
+ * function — no IO, no state. Safe to call from any CLI handler.
+ *
+ * @param error - any value that may have been thrown (we only inspect
+ *                `.message` for goal-validation; everything else is
+ *                routed by class).
+ */
+export declare function mapServiceError(error: unknown): EnvelopeMapping;

package/dist/cli/commands/_cli-error-envelope.js

@@ -0,0 +1,50 @@
+// Slice 015 — single source of truth for translating a thrown error from
+// the service layer (createRdSwarmPlan, createTechPlan, etc.) into a CLI
+// envelope code + user-facing nextActions.
+//
+// Lives under src/cli/commands/ (private to the CLI surface; underscore
+// prefix marks it as not-an-exported-CLI-subcommand per the project
+// convention). Used by every CLI handler that wraps a service call in a
+// try/catch — currently the four catches in workflow-commands.ts.
+//
+// Pre-slice behavior: all four catches emitted a fixed `INVALID_GOAL`
+// envelope code, regardless of the actual error class. Provider-config
+// failures (`ProviderNotConfiguredError`) were silently re-labelled as
+// "invalid goal", hiding real config issues behind a misleading hint.
+//
+// Post-slice behavior: the helper routes errors into one of three envelope
+// codes based on the runtime error class/message. The CLI catch sites
+// become data-only — they call the helper, then format the envelope.
+import { ProviderNotConfiguredError } from '../../services/config/model-routing.js';
+// Slice 015 risk A: goal-validation uses a substring match on the error
+// message thrown by `validatePlanningInput`. If validatePlanningInput's
+// message wording changes in a future slice, this branch silently
+// degrades into INTERNAL_ERROR. Mitigated by the helper's unit test
+// pinning the literal substring.
+// Slice 015 — match the goal-validation throw message. The current
+// `validatePlanningInput` literal is `"Goal must be non-empty"` (capital
+// G, "non-empty" with hyphen). The regex tolerates common wording
+// variations (`must be non-empty`, `must not be empty`, case-insensitive)
+// so a future message tweak still routes correctly; the unit test below
+// pins the *current* literal substring so any wording change fails loudly.
+const GOAL_VALIDATION_MESSAGE_RE = /goal.{0,4}(must be non-empty|must not be empty)/i;
+/**
+ * Map a thrown error into an envelope code + nextActions hint. Pure
+ * function — no IO, no state. Safe to call from any CLI handler.
+ *
+ * @param error - any value that may have been thrown (we only inspect
+ *                `.message` for goal-validation; everything else is
+ *                routed by class).
+ */
+export function mapServiceError(error) {
+    if (error instanceof ProviderNotConfiguredError) {
+        return {
+            code: 'INVALID_PROVIDERS',
+            nextActions: ['Configure provider model: peaks config provider <id> set --model <id>'],
+        };
+    }
+    if (error instanceof Error && GOAL_VALIDATION_MESSAGE_RE.test(error.message)) {
+        return { code: 'INVALID_GOAL', nextActions: ['Use a non-empty goal'] };
+    }
+    return { code: 'INTERNAL_ERROR', nextActions: ['See errorId for trace'] };
+}

package/dist/cli/commands/adapter-commands-s2a.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `peaks adapter *` — vendor adapter registry CLI surface.
+ *
+ * Slice S2-a of RD-2 (2026-07-08 session). Two subcommands:
+ *
+ *   list     — list registered user adapters (persisted at
+ *              `.peaks/runtime/adapters.json`).
+ *   register — register a new adapter. Vendor verb strings live in
+ *              the binary the user picks, NOT in peaks-loop source.
+ *
+ * This file coexists with the older `adapter-commands.ts` (slice
+ * 2026-07-04-cli-15a) which exposes `peaks skill adapter <verb>` —
+ * a different surface for skill materialization (resolveScratchDir /
+ * materialize / publish). The two surfaces do NOT collide because
+ * one is `peaks skill adapter` and the other is `peaks adapter`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface AdapterListOptions {
+    json?: boolean;
+    project?: string;
+}
+export interface AdapterRegisterOptions {
+    json?: boolean;
+    id?: string;
+    /** Display name override (defaults to the id). */
+    name?: string;
+    binary?: string;
+    /** Repeated --arg values. */
+    arg?: string[];
+    force?: boolean;
+    project?: string;
+}
+export declare function registerAdapterS2ACommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/adapter-commands-s2a.js

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+import { registryFileFor } from './runtime-commands.js';
+function resolveProjectRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerAdapterS2ACommands(program, io) {
+    const adapter = program
+        .command('adapter')
+        .description('Vendor adapter registry (user-registered, persisted to .peaks/runtime/adapters.json)');
+    // -----------------------------------------------------------------
+    // 1. peaks adapter list [--json] [--project <root>]
+    // -----------------------------------------------------------------
+    addJsonOption(adapter
+        .command('list')
+        .description('List user-registered vendor adapters')
+        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const file = registryFileFor(projectRoot);
+            const reg = new AdapterRegistry();
+            if (existsSync(file))
+                reg.load(file);
+            const records = reg.list();
+            printResult(io, ok('adapter.list', { projectRoot, file, records, count: records.length }, [], [
+                records.length === 0
+                    ? 'No adapters registered yet. Run `peaks adapter register --id <vendor> --binary <cmd>` to add one.'
+                    : `Run \`peaks runtime compact --via <id>\` to invoke a registered adapter.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('adapter.list', 'ADAPTER_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks adapter register --id <id> --binary <cmd> [--arg <a>]... [--force]
+    // -----------------------------------------------------------------
+    addJsonOption(adapter
+        .command('register')
+        .description('Register a new vendor adapter; persists to .peaks/runtime/adapters.json')
+        .requiredOption('--id <id>', 'vendor adapter id (lowercase, e.g. my-cli)')
+        .option('--name <name>', 'human-readable display name (defaults to <id>)')
+        .requiredOption('--binary <cmd>', 'binary name to invoke for compact (e.g. my-cli)')
+        .option('--arg <value>', 'extra arg appended before --force (repeatable)', (value, previous = []) => [...previous, value])
+        .option('--force', 'overwrite an existing adapter with the same id')
+        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const file = registryFileFor(projectRoot);
+            const reg = new AdapterRegistry();
+            if (existsSync(file))
+                reg.load(file);
+            const id = options.id ?? '';
+            const record = options.arg !== undefined
+                ? { id, displayName: options.name ?? id, binary: options.binary ?? '', args: options.arg }
+                : { id, displayName: options.name ?? id, binary: options.binary ?? '' };
+            let result;
+            try {
+                result = reg.register(record, { force: options.force === true });
+            }
+            catch (validationError) {
+                printResult(io, fail('adapter.register', 'INVALID_ADAPTER_RECORD', getErrorMessage(validationError), { id }, [
+                    'Use --id with /^[a-z0-9][a-z0-9._-]*$/, --binary as a binary name (no path separators).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            reg.persist(file);
+            const warnings = [];
+            if (!result.created && options.force !== true) {
+                warnings.push(`adapter "${id}" already registered; pass --force to overwrite`);
+            }
+            printResult(io, ok('adapter.register', {
+                projectRoot,
+                file,
+                adapter: result.record,
+                created: result.created
+            }, warnings, [
+                `Run \`peaks runtime compact --via ${id}\` to invoke it.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('adapter.register', 'ADAPTER_REGISTER_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}