peaks-loop 3.1.2 → 4.0.0-beta.10

package/README.md

@@ -1,365 +1,227 @@
 <div align="center">
 
-# ⛰️ Peaks
-
-<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=700&size=22&duration=3000&pause=800&color=6366F1&center=true&vCenter=true&multiline=true&width=720&height=110&lines=peaks-loop%3A%20跨%20AI%20IDE%20的工程门禁与编排;11%20个%E2%9A%99%EF%B8%8F%20工作流技能%20%2B%20%E2%9A%96%EF%B8%8F%20可执行门禁;%E2%9C%89%EF%B8%8F%20%E2%9A%96%EF%B8%8F%20%E2%9C%89%EF%B8%8F%20%E2%9A%91%EF%B8%8F%20%E2%9A%96%EF%B8%8F%20%E2%9C%89%EF%B8%8F%20%E2%9A%91%EF%B8%8F%20门禁%20%2B%20审计%20%2B%20跨%20IDE%20适配" alt="peaks-loop tagline typing animation" />
-
-[English](./README-en.md) | **简体中文**
-
-<table>
-<tr>
-<td align="center" width="180"><b>🔥 PROJECT</b></td>
-<td align="center" width="180"><b>⚡ BASED ON</b></td>
-<td align="center" width="180"><b>📚 SKILLS.SH</b></td>
-</tr>
-<tr>
-<td align="center"><a href="https://github.com/SquabbyZ/peaks-loop">peaks-loop / 首页</a></td>
-<td align="center">13 Skills + Cross-IDE</td>
-<td align="center"><a href="https://skills.sh/SquabbyZ/peaks-loop">在 skills.sh 收录</a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>⭐ STARS</b></td>
-<td align="center" width="180"><b>📦 VERSION</b></td>
-<td align="center" width="180"><b>📄 LICENSE</b></td>
-</tr>
-<tr>
-<td align="center"><a href="https://github.com/SquabbyZ/peaks-loop/stargazers"><img src="https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white" alt="stars" /></a></td>
-<td align="center"><a href="https://www.npmjs.com/package/peaks-loop"><img src="https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version" /></a></td>
-<td align="center"><a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="license" /></a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>🧪 TESTS</b></td>
-<td align="center" width="180"><b>🔧 LANG</b></td>
-<td align="center" width="180"><b>📥 DOWNLOADS</b></td>
-</tr>
-<tr>
-<td align="center"><b>2,800+</b></td>
-<td align="center"><b>TypeScript</b></td>
-<td align="center"><a href="https://www.npmjs.com/package/peaks-loop"><img src="https://img.shields.io/npm/dm/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="downloads" /></a></td>
-</tr>
-<tr><td colspan="3">&nbsp;</td></tr>
-<tr>
-<td align="center" width="180"><b>🌐 中文</b></td>
-<td align="center" width="180"><b>🚀 QUICK START</b></td>
-<td align="center" width="180"><b>👁️ VISITORS</b></td>
-</tr>
-<tr>
-<td align="center"><a href="./README.md">简体中文</a></td>
-<td align="center"><a href="#-30-秒跑起来">30 秒跑起来 →</a></td>
-<td align="center"><img src="https://komarev.com/ghpvc/?username=SquabbyZ&repo=peaks-loop&label=views&color=blue&style=for-the-badge" alt="visitors" /></td>
-</tr>
-</table>
-
-<img src="https://github-readme-streak-stats.herokuapp.com?user=SquabbyZ&repo=peaks-loop&theme=radical&hide_border=true&date_format=j%20M%5B%20Y%5D" alt="GitHub Streak Stats" />
-
-[安装](#-30-秒跑起来) · [5 分钟上手](#-5-分钟上手) · [技能家族](#-11-个技能家族) · [杀手锏：不可绕过的门禁](#-杀手锏不可绕过的门禁)
+# peaks-loop
 
-</div>
-
----
-
-## 🤔 为什么是 Peaks
+### 你说话,它替你跑完一整条工程流水线 —— 不止写代码,跑两次就沉淀成本地战术。
 
-> 你把 `git push --force`、`rm -rf`、`npm publish`、`DROP TABLE` 这类不可逆动作**写进 CLAUDE.md** 吗？
-> LLM 不会真听。它有 99% 的概率会"尊重你的偏好"，然后在下一次对话里忘掉。
-> **CI 只能在合并时拦；规则只能靠自觉；只有门禁（gates）能在 agent 拔刀的瞬间摁住它。**
+[![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)
+[![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&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
-Peaks 把 AI IDE 里的"工程团队"建模成 13 个工作流技能 + 一组**可执行的门禁**：
+[English](./README-en.md) · **简体中文**
 
-- 🧭 **技能（skills）**——`peaks-solo` 编排，`peaks-prd/rd/qa/ui/sc/txt/sop` 各管一段；LLM 按任务自动选对的人
-- 🚧 **门禁（gates）**——SOP 在每个 phase 上挂"可检查条件"（文件存在 / grep 命中 / 命令退出码），不满足就把 `git push` 在 agent 自己面前拦下——**连 `--dangerously-skip-permissions` 都绕不过**
-- 🧠 **项目记忆（memory）**——`.peaks/memory/` 把决策、踩坑、约定落盘到 git 一起被 commit；下个 session 接手不用问"为什么这么写"
-- 🌐 **跨 IDE**——一个 CLI 适配 Claude Code / Trae / Cursor / Codex / Qoder；技能注册到 IDE 原生格式
-- 📦 **生态可发现**——13 个技能同样发布到 [skills.sh](https://skills.sh)，按需 `npx skills add` 单点装
+</div>
 
-## 🚀 30 秒跑起来
+<p align="center">
+  <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>👆 18s 循环 GIF(<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">完整 30s mp4 下载</a> · 13MB · 480p)</sub>
+</p>
 
-```bash
-# 1. 装 CLI
-npm install -g peaks-loop
+---
 
-# 2. 在你的项目里打开 Claude Code
-cd /path/to/your-project && claude
-```
+## 它是什么
 
-> **v2.13.3 提示**：发布新版本时 `npm publish` 会在 publish 前自动跑 `pnpm run build`（`package.json` 的 `prepublishOnly` hook 走 `scripts/prepublish-build.mjs`），确保 `bin/peaks.js` 永远带最新 dist。**发布前不要手动跳过这一步**——2.13.2 dogfood 抓过 `bin/peaks.js` 指 Jun 13 旧 dist 的事故。
+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)。
 
-# 3. 让 AI 干活
-> peaks-solo 帮我给登录页加 OAuth 回调
-```
+| 资产层 | 角色 | 一句话 |
+| --- | --- | --- |
+| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
+| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
+| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
+| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
 
-完了。第一次跑 peaks 会自动建 `.peaks/` 工作区 + 扫一次项目原型 + 把任务分给对的技能（PRD → 工程切片 → UI → QA → 变更控制 → 知识压缩），中间产物全部落盘。**日常使用 1 个技能（`peaks-solo`）覆盖 ≥ 90% 的需求**。v2.13.1 起 5 套异质信号（security-audit / perf-audit / karpathy / mut / qa）会按 `block > return-to-rd > warn > pass` precedence 汇聚成单一 verdict，repair-loop 触发时打印 `re-run reason: { source, signal, file, line, hint }` 作为再决策依据。v2.13.2 起 `peaks verdict aggregate --from-rid <rid>` 把这套汇聚逻辑直接暴露为 CLI 子命令，并修复了 v2.13.1 跨 source dedup bug（之前 security + perf 报同处问题会被记为 2 条 reason，现在合并为 1 条且 sources 字段列出所有 source）。
+- **工程化每条规则 = 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 跟着你的口味长。
 
-## 🧠 peaks-context — 上下文构建模块 (v3.0)
+---
 
-peaks-context 是 CLI 强制执行的上下文采集器,**不再依赖 LLM 自主"读 package.json"**。
+## 30 秒上手
 
 ```bash
-peaks context build --goal "<你的需求>" --project . --audience peaks-rd --out context.json
-peaks context validate context.json
-peaks context inspect context.json
+npm i -g peaks-loop
 ```
 
-**承诺**:deps 锁版本 antd@5.21.0 → context.json 绝不返回 6.x API 文档。  
-详见 [design spec §4.1](../../docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md)。
-
-## 🧬 peaks-mut — 测试假绿拦截 (v3.0)
-
-peaks-mut 通过变异测试 + 断言有效性扫描拦截测试假绿:
+装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
-```bash
-peaks mut run --project . --test-files src/A.test.ts --input-sig <TACT.sig> --out mut-report.json
-peaks mut mutants --in mut-report.json
-peaks mut asserts --in mut-report.json
-peaks mut report --in mut-report.json
 ```
-
-**默认阈值**:变异杀灭率 ≥ 80%、弱断言比例 ≤ 5%。详见 [design spec §4.2](../../docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md)。
-
-## 🎯 peaks-rd 双阶段 (v3.0)
-
-peaks-rd 现在拆成两阶段:
-
-1. **战略审计**:写 `strategy.md` + `STRAT.sig`(根因分析 + 影响面)
-2. **战术审计**:写 `impl.json` + `TACT.sig`,**AST 硬门禁拦截版本错配的 API 调用**
-
-详见 [design spec §4.2](../../docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md)。
-
-## ⏱️ 5 分钟上手
-
-在 IDE 对话里直接对 AI 说：
-
-```text
-peaks-solo 帮我给登录页加 OAuth 回调      # 端到端编排（最常用）
-peaks-prd  为会员邀请功能整理产品目标、非目标和验收标准
-peaks-rd   分析这次重构的最小实现切片和风险
-peaks-qa   为这次改动设计测试和回归验证清单
-peaks-ui   设计登录页的交互和视觉方案
-peaks-sc   记录这次变更的影响范围、artifact 留存和 commit 边界
-peaks-txt  为当前模块生成上下文胶囊，保留关键决策
-peaks-sop  帮我把"内容发布"流程变成带门禁的 SOP
+/peaks-code 帮我熟悉下当前的项目
 ```
 
-**两种基本用法**：
-
-1. **让 `peaks-solo` 编排**（绝大多数情况）——告诉它做什么，剩下 PRD → RD → UI → QA → SC → TXT 的链路它自己协调
-2. **直接调单个角色技能**（进阶）——只想做工作流的某一段时，跳过整 pipeline
+剩下的就交给 peaks-loop —— 它会按这条命令的语义判断该走哪一域,用对应的编排器拆工序,一道门一道门跑,**坏在哪道停在哪道**,中间不会扔半截给你。
 
-随时确认状态？让 AI 跑一下：
+其他常用的显式命令:
 
-```bash
-peaks -V                       # 版本
-peaks doctor --json            # 环境/技能/配置一键体检
-peaks project dashboard --project . --json   # 当前项目一眼看完
 ```
-
-## 🧰 13 个技能家族
-
-| 技能 | 你用它做什么 | 典型场景 |
-|------|------------|----------|
-| `peaks-solo` | **端到端编排入口**，自动协调 prd/rd/ui/qa/sc/txt | 全流程开发、PRD-to-ship、跨子任务批量迭代 |
-| `peaks-prd` | 模糊意图 → **可验收 PRD**（目标/非目标/行为保留/验收） | 需求整理、PRD 撰写、重构目标 |
-| `peaks-rd` | 工程分析 + 切片规划 + 风险 + 执行契约 | 架构分析、最小切片、风险评估 |
-| `peaks-qa` | 测试设计 + 覆盖率 + 回归矩阵 + 验收证据 | 测试用例、回归、浏览器 E2E |
-| `peaks-ui` | 视觉方向 + 交互方案 + 设计系统约束 | 页面设计、交互、原型、UI 回归 |
-| `peaks-sc` | 变更追踪 + commit 边界 + 留存策略 + 回滚证据 | 影响范围、变更控制、审计 |
-| `peaks-txt` | 上下文胶囊 + 决策记录 + 知识压缩 | 模块理解、决策留存、复盘 |
-| `peaks-sop` | **把你的工作流变成带门禁的 SOP**（不只研发） | 内容发布、合规清单、数据 pipeline、运维 runbook |
-| `peaks-solo-resume` | 继续刚才没做完的切片 | 「继续完成刚才未完成的」 |
-| `peaks-solo-status` | 一眼看到现在到哪了 | 「现在到哪了」 |
-| `peaks-solo-test` | 跑项目测试（自动探测 vitest/jest/pytest/...） | 「跑测试」 |
-| `peaks-security-audit` | **独立安全审计**（OWASP Top-10 + 8-dim 威胁模型） | 新增鉴权/凭证/SQL 注入/外部 API 等安全面改动 |
-| `peaks-perf-audit` | **独立性能审计**（6-dim 性能影响） | 改热循环/I-O/并发/bundle/cold-start |
-
-**3 solo 包装 + 7 角色技能 + 2 独立审计 + 1 编排器 = 13 个。日常 1 个 `peaks-solo` 覆盖 ≥ 90%。**
-
-> **v2.13.0 新增**：zero-human-intervention **auto-compact**（`peaks solo context-now` + `peaks solo auto-compact`）——peaks-loop 自己探测 context %，≥85% 主动收敛（写 checkpoint + 收敛计划 + 触发 IDE compact），≥95% 强制同步压缩红线。LLM-runner 上下文始终 < 95% 自主运行，零介入。**v2.13.4 修复**：`auto-compact` 现在默认压缩**主会话**上下文（不是 sub-agent shell 自己的）。**3.0.3 新增 `ide-native` 通路**：在 `.claude/settings.local.json` 装 PreToolUse hook（`Bash|Task` matcher → `peaks session auto-compact-hook`），runner 下一次 Bash/Task tool call **in-band** 触发 `claude --compact`，不再依赖 LLM 自己 fire `/compact`。Hook ENOENT-safe（claude CLI 不在 PATH 时退出 0 + stderr 提示，runner 不会被中断）。
-
-## 🚧 杀手锏：不可绕过的门禁
-
-> CI 只能在**合并时**拦；`CLAUDE.md` 规则靠 agent **自觉**。**SOP 能做到 CI 和提示词都做不到的事——在 agent 拔刀的瞬间把它摁住。**
-
-```jsonc
-// sop.json
-"guards": [ { "phase": "publish", "bash": "git +push" } ]
+/peaks-content                 帮我把今天这篇推文写完发出
+/peaks-doctor                  帮我体检一下这个仓库
+/peaks-issue-fix-orchestrator  帮我把 upstream 的 30 个 open issue 修一批
+/peaks-sop                     帮我把团队的发布流程沉淀成 SOP
+/peaks-solo                    这套打法以后还会用,沉淀成本地战术
+/peaks-solo                    按上次那样再跑一次
 ```
 
-```bash
-peaks hooks install --project <repo>   # 显式 opt-in：装一条 PreToolUse 规则
-```
-
-之后 agent 在 `publish` 阶段的门禁没全过就想 `git push`，Claude Code 会收到 `permissionDecision: "deny"`，**在任何权限检查之前就被拦下——连 `--dangerously-skip-permissions` 都绕不过**。门禁三种类型：
-
-| 类型 | 含义 | 例子 |
-|------|------|------|
-| `file-exists` | 文件存在 → pass | `CHANGELOG.md` 存在 |
-| `grep`（含 `absent`） | 文件内正则匹配 → pass；`absent: true` 反转 | "正文里没有 `TODO`" |
-| `command` | 跑命令并按退出码判定（默认拒绝，需 `--allow-commands`） | 跑 `npm test` |
-
-定义层（`sop.json` + `SKILL.md`）可以放**全局** `~/.peaks/sops/`（个人跨项目）或**仓库** `<repo>/.peaks/sops/`（随 git 提交、团队共享，仓库层优先）。**紧急放行**用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"`（一次性、记原因、有上限）。
-
-## 🌍 真实场景
-
-**场景 1：临时决定重构鉴权模块**
-
-```text
-> peaks-rd 分析 src/auth/ 的现状，给我一份最小切片方案
-```
-`peaks-rd` 出：3 阶段切片、风险评估、回归点、可执行契约。**写不写代码你定**。
+<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
 
-**场景 2：把"内容发布"变成受控流程**
+不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
 
-```text
-> peaks-sop 帮我把"博客发布"做成带门禁的 SOP：草稿写完 → 自检（无 TODO/字数 ≥ 800） → 人工 review → 才允许发布
-```
-`peaks-sop` 生成 `sop.json` + `SKILL.md`，注册到全局，**从此 agent 跳过任何一步都发不出文章**。
-
-**场景 3：浏览器 E2E 回归**
-
-```text
-> peaks-qa 用浏览器跑一次完整注册 → 登录 → 看板的核心流，把卡点列出来
-```
-`peaks-qa` 出：测试矩阵、回归清单、`code-review.md` 风格的证据文档。
+---
 
-**场景 4：第二天回来继续昨天的切片**
+## 它能为你做什么
 
-```text
-> peaks-solo-resume
-```
-检测 in-flight slice 的最深已完成 gate，省 3-5k token 重新读 artifact。**会话断了不丢上下文**。
+代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
-## 📦 在 skills.sh 上发现 peaks 技能
+| 域 | 你发这条命令 | 它会做什么 |
+| --- | --- | --- |
+| 💻 **代码域 (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 这套打法以后还会用,沉淀一下` | 变成你本地常驻的战术,下次说"跑那只"就行 |
 
-peaks 的 13 个 `peaks-*` 技能自动收录到 [skills.sh](https://skills.sh) 注册表——**不需要单独去 skills.sh 网站注册**。收录靠仓库里**自带配置**：
+每一条路,**一条斜杠命令**就能开跑。
 
-- 13 个 `skills/<name>/SKILL.md`（每个都有 `name` + `description` YAML frontmatter）—— skills.sh 的标准发现约定
-- `.claude-plugin/marketplace.json` —— 显式列出 13 个公开技能（隐藏的内部 `peaks-doctor` / `peaks-ide` 通过 `metadata.internal: true` 屏蔽）
+---
 
-任何装了 `npx skills` 的环境（Claude Code、Cursor、Codex 等）都能直接拉取：
+## 为什么大家会选它
 
-```bash
-# 装全部 13 个：
-npx skills add SquabbyZ/peaks-loop
+- **自然语言即界面** —— 你不学 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 分钟上手。**
 
-# 或只装一个：
-npx skills add SquabbyZ/peaks-loop --skill peaks-solo
-npx skills add SquabbyZ/peaks-loop --skill peaks-rd
-npx skills add SquabbyZ/peaks-loop --skill peaks-sop
-```
+---
 
-浏览 [skills.sh/SquabbyZ/peaks-loop](https://skills.sh/SquabbyZ/peaks-loop) 看完整目录。技能和 `npm install -g peaks-loop` 是同一份内容——两条路径产物一致。
+## 装上以后的几道闸门
 
-## 🛠️ 怎么用：技能优先，CLI 是门禁
+| 闸门 | 默认状态 | 用来挡什么 |
+| --- | --- | --- |
+| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
+| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
+| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
+| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
+| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
 
-`peaks <cmd>` CLI **不是日常使用的主要入口**。它存在有三个理由，全是机器层保障：
+**所有闸门默认开,你想关哪一道才需要单独说。**
 
-1. **不可逆动作的显式 opt-in**（`peaks sop init --apply`、`peaks openspec archive --apply`）—— 不能靠 LLM"自觉"挥下
-2. **结构化 JSON 契约**（`peaks request show ... --json`、`peaks scan archetype ... --json`）—— 让技能读回可机读判决作为下游决策
-3. **hook / CI / 脚本场景下能被程序化调用**（`peaks hooks install`、`peaks gate enforce`）—— 把"必须满足门禁才能做 X"从纸面规则变成可执行规则
+---
 
-一句话：**技能 = 流程的大脑；CLI = 流程的骨节**。
+## 当前状态 · 4.x 正式版
 
-### 你**会**看到的 CLI 命令
+| | |
+| --- | --- |
+| **最新版本** | [`4.0.0-beta.7`](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 |
 
-```bash
-peaks workspace init / reconcile / scan archetype / scan libraries
-peaks request init / show / transition          # PRD/RD/QA/SC 请求状态机
-peaks session list / info / title / rotate
-peaks sop init / lint / check / advance / register
-peaks code-review detect-ocr / config-template / run-ocr   # 阿里 Open Code Review 第二意见
-peaks hooks install / gate enforce / gate bypass
-peaks project dashboard / memories
-```
+---
 
-完整列表跑 `peaks --help`。
+## 强烈推荐 · 四个项目组合起来用
 
-## 🌐 支持的 IDE
+> **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
 
-| IDE | 状态 |
-|---|---|
-| ✅ **Claude Code** | 13 技能 + PreToolUse hook，agent team dogfood 通过 |
-| ⚠️ **Trae** | slim `IdeAdapter` 已注册，真实 Trae 集成留到后续切片 |
-| 📋 **Codex / Cursor / Qoder / 通义灵码 等** | 路线图 |
+<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>
 
-## 🪝 Hooks
+| 角色 | 项目 | 一句话 |
+| --- | --- | --- |
+| **结晶与门禁** | [**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 等流程纪律,每条都自带硬退出条件 |
 
-peaks-loop 把自己注册为 Claude Code / Trae 的 PreToolUse hook，在**对话中途、面向 agent 本身**拦下不可逆动作——这是 CI 拦不住、CLAUDE.md 只能靠自觉的盲区。
+**用起来就一句话**:把上面三个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
 
-### 装 / 卸
+### 致敬
 
-```sh
-# 装到当前项目（写入 .claude/settings.json，幂等）
-peaks hooks install
+peaks-loop 的两条工程脊柱直接来自这两个项目:
 
-# 装到全局（写入 ~/.claude/settings.json）
-peaks hooks install --global
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
 
-# 查状态
-peaks hooks status
-peaks hooks status --global
+---
 
-# 卸（只卸 peaks 自己注册的；保留其他第三方 hook）
-peaks hooks uninstall
-```
+## FAQ
 
-装完之后**重启 IDE（或 reload workspace）**让 hook 生效。
+<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)。
 
-装的是 `peaks gate enforce` 这条 PreToolUse `Bash` 入口——每次 Bash 调用都会跑 SOP 门禁。命中失败 → 写 `permissionDecision: "deny"` 到 stdout + `process.exitCode = 2`，Claude Code 在权限检查**之前**就拦下来（连 `--dangerously-skip-permissions` 也拦得住）。完整审计表见 [`.claude/HOOKS.md`](./.claude/HOOKS.md)。
+</details>
 
-### 输出契约
+<details>
+<summary><b>我需要记 CLI 命令吗?</b></summary>
 
-| 信号          | 走哪                                    | 含义                       |
-|---------------|-----------------------------------------|----------------------------|
-| `stdout` JSON | `emitBlock` / `emitDecision`            | 给宿主读的 allow/deny 决策 |
-| `stderr` 文本 | `emitHint`                              | 给 LLM/操作者看的人话提示  |
-| 退出码 `0`    | 允许                                    | 宿主继续                   |
-| 退出码 `2`    | 阻塞（`emitBlock` 专用）                | 宿主必须停                 |
+不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
 
-所有 hook 走 `src/services/hooks/output.ts` 三个 helper：`emitHint` / `emitBlock` / `emitDecision`。跨平台契约测试（darwin / linux / win32）在 `tests/unit/hooks/contract.test.ts`。
+</details>
 
-### 一次性放行
+<details>
+<summary><b>沉淀下来的战术会一直留在本地吗?</b></summary>
 
-```sh
-peaks gate bypass --sop <id> --phase <phase> --reason "<why>"
-```
+会。沉淀落在你本地的池子里,只对你生效。命名、复用、迭代都是你说了算;跑翻车的会让你重新定义。
 
-下次匹配的 Bash 命令放行一次（每个 SOP 每项目上限 3 次）。完整文档：[`.claude/HOOKS.md`](./.claude/HOOKS.md)。
+</details>
 
-## 🏗️ 项目状态
+<details>
+<summary><b>它会自己改我的代码吗?</b></summary>
 
-- ✅ **13 技能** + 跨 IDE CLI + 2800+ 测试（v2.12.0 新增 `peaks-security-audit` + `peaks-perf-audit`）
-- ✅ **门禁机制** 已在真实项目 dogfood
-- ✅ **v2.12.0 RD fan-out 收缩**（3 路：code-reviewer + qa-test-cases-writer + karpathy-reviewer）2026-06-27 发布
-- ✅ **v2.13.0 零介入 auto-compact**（peaks-loop 自主压缩任意 AI CLI 的上下文，runner 始终 < 95%）2026-06-27 发布
-- ✅ **v2.13.4 4 个 solo bug 修复**：Step 1 AskUserQuestion 不再被跳过、verify-pipeline 走 canonical `.peaks/_runtime/<sessionId>/<role>/` 路径、`LegacyChangeIdSiblingError` 哨兵在 init 时容忍 misplaced 数据、auto-compact 真正压主会话上下文
-- 📋 路线图：Trae / Codex / Cursor 真实集成、`peaks-doc` / `peaks-i18n`、SOP 模板市场
+改,但过门禁。**审计不通过 = 不出门**,**QA 没过 = 不出门**,**review 不通过 = 不出门**。它替你跑,但每道门都给你审。
 
-详细看 [`CHANGELOG.md`](./CHANGELOG.md) 和 [`docs/`](./docs/)。
+</details>
 
-## 📄 许可
+<details>
+<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
 
-[MIT](LICENSE) — 商用、改、私有 fork 都欢迎，保留版权即可。
+**最大的不同:从"代码专用"扩成"多域编排系统"。** 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>
 
-遇到使用问题、功能建议、或者想和other peaks-loop users直接交流？扫码加入 **Peaks-Loop** 微信群：
+---
 
-<div align="center">
-  <img src="./docs/images/wechat-group-qr.png" alt="Peaks-Loop 微信群二维码" width="240" />
-</div>
+## 链接
 
-> 二维码图片过期后，欢迎在 GitHub Issues / Discussions 提反馈。
+- 全部技能清单 → [`skills/`](./skills/)
+- 更新日志 → [`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)
 
 ---
 
 <div align="center">
 
-**觉得有用？**
-
-⭐ [Star peaks-loop on GitHub](https://github.com/SquabbyZ/peaks-loop) · 🔍 [Browse on skills.sh](https://skills.sh/SquabbyZ/peaks-loop)
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
 
-</div>
+</div>

package/agents/karpathy-reviewer.md

@@ -9,7 +9,7 @@ model: sonnet
 
 > **Shipped source** (Slice 7/7): this file is the canonical source for the karpathy-reviewer sub-agent prompt. The `peaks-loop` postinstall (`scripts/install-skills.mjs#installBundledAgents`) copies this file to `~/.claude/agents/karpathy-reviewer.md` on every `npm i -g peaks-loop@latest` invocation, with content-hash drift detection (a `.peaks-managed` marker + SHA-256 compare). Edit here; do not edit the copy in `~/.claude/agents/` (it will be overwritten on the next upgrade).
 >
-> **Project-internal pointer**: `skills/peaks-rd/references/karpathy-reviewer-prompt.md` is a 2-line pointer to this file (peaks-loop 2.0 rules convention).
+> **Project-internal pointer**: `skills/bee/peaks-rd/references/karpathy-reviewer-prompt.md` is a 2-line pointer to this file (peaks-loop 2.0 rules convention).
 
 You are a **Karpathy-guidelines enforcement reviewer** for peaks-rd. You inspect a slice's RD outputs against the 4 Karpathy guidelines and emit a compact JSON envelope that blocks the `rd → qa-handoff` transition if any guideline fails. You do **not** review style, performance, security, or code quality — those are owned by the parallel 4 sub-agents.
 
@@ -223,7 +223,7 @@ karpathy-reviewer summary:
 ## 10. References
 
 - Canonical 4-guideline text: `andrej-karpathy-skills:karpathy-guidelines` skill id; full text in `skills/andrej-karpathy-src/skills/karpathy-guidelines/SKILL.md`.
-- Sub-agent dispatch contract: `skills/peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context".
-- 5-way fanout integration: `skills/peaks-rd/references/rd-fanout-contracts.md` §"karpathy-reviewer contract (Slice 5/6)".
+- Sub-agent dispatch contract: `skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context".
+- 5-way fanout integration: `skills/bee/peaks-rd/references/rd-fanout-contracts.md` §"karpathy-reviewer contract (Slice 5/6)".
 - CLI gate: `KARPATHY_REVIEW` prereq in `src/services/artifacts/artifact-prerequisites.ts` (title-case `mustContain`).
 - Structural scanner (companion): `peaks scan karpathy` reads `rd/karpathy-review.md` and emits a similar markdown report; the structural scanner is **not** a replacement for this reviewer — it covers regex / file-presence checks, not the semantic judgement this reviewer provides.

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,43 @@
+import { Command } from 'commander';
+import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from '../shared/result.js';
+import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
+import type { ConfigLayer } from '../services/config/config-service.js';
+import type { MiniMaxProviderSmokeResult } from '../services/providers/minimax-provider-service.js';
+import type { MiniMaxWorkerResult } from '../services/providers/minimax-worker-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 isMiniMaxHttpsUrl(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 declare function summarizeMiniMaxSmokeResult(result: MiniMaxProviderSmokeResult): MiniMaxProviderSmokeResult;
+export declare function summarizeMiniMaxWorkerResult(result: MiniMaxWorkerResult): MiniMaxWorkerResult;
+export { getErrorMessage, ok, redactSensitiveErrorMessage };