peaks-loop 4.1.5 → 4.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +36 -0
- package/README-en.md +47 -183
- package/README.md +24 -188
- package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
- package/dist/cli/commands/best-practice-scan-command.js +35 -20
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
- package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
- package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
- package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
- package/dist/cli/commands/dispatch-command-spec.js +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
- package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
- package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
- package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
- package/dist/cli/commands/openspec-command-shared.js +2 -2
- package/dist/cli/commands/request-transition-failures.js +31 -4
- package/dist/cli/commands/request-transition-preflight.js +1 -1
- package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
- package/dist/cli/commands/verdict-aggregate-command.js +2 -1
- package/dist/cli/commands/workflow-gate-commands.js +4 -4
- package/dist/cli/program.js +0 -2
- package/dist/services/artifacts/artifact-contract-block.js +21 -2
- package/dist/services/artifacts/artifact-prerequisites.js +7 -7
- package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
- package/dist/services/artifacts/rd-transition-gates.js +71 -0
- package/dist/services/artifacts/request-artifact-service.js +22 -20
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
- package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
- package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
- package/dist/services/audit-independent/judged-declaration-check.js +62 -1
- package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
- package/dist/services/context/build-dispatch-system-prompt.js +11 -11
- package/dist/services/context/post-compact-reinjection.js +1 -1
- package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
- package/dist/services/dispatch/test-tool-detection.js +12 -1
- package/dist/services/evidence/evidence-generator.js +8 -4
- package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
- package/dist/services/openspec/coverage-evidence-reader.js +8 -8
- package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
- package/dist/services/openspec/openspec-archive-service.js +6 -6
- package/dist/services/scan/file-size-baseline.d.ts +13 -6
- package/dist/services/scan/file-size-baseline.js +54 -31
- package/dist/services/scan/file-size-scan.d.ts +7 -14
- package/dist/services/scan/file-size-scan.js +6 -1
- package/dist/services/scan/type-corroboration.d.ts +32 -0
- package/dist/services/scan/type-corroboration.js +51 -0
- package/dist/services/scan/type-sanity-service.d.ts +14 -0
- package/dist/services/scan/type-sanity-service.js +10 -19
- package/dist/services/security/safe-settings-path.d.ts +5 -0
- package/dist/services/security/safe-settings-path.js +64 -8
- package/dist/services/skill/resume-detector.js +8 -8
- package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +32 -38
- package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
- package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
- package/dist/services/workflow/pipeline-verify-service.js +26 -27
- package/dist/services/workflow/request-type-resolution.d.ts +99 -0
- package/dist/services/workflow/request-type-resolution.js +130 -0
- package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
- package/dist/services/workflow/workflow-skip-service.js +19 -21
- package/dist/services/workflow/workflow-state-store.d.ts +9 -0
- package/dist/services/workflow/workflow-state-store.js +26 -1
- package/dist/shared/incrementing-number.d.ts +23 -2
- package/dist/shared/incrementing-number.js +57 -15
- package/package.json +5 -7
- package/skills/bee/peaks-prd/SKILL.md +3 -2
- package/skills/peaks-code/SKILL.md +32 -15
- package/dist/cli/commands/vm-command-shared.d.ts +0 -23
- package/dist/cli/commands/vm-command-shared.js +0 -23
- package/dist/cli/commands/vm-commands.d.ts +0 -3
- package/dist/cli/commands/vm-commands.js +0 -45
- package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
- package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
- package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
- package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
- package/dist/cli/commands/vm-release-command.d.ts +0 -5
- package/dist/cli/commands/vm-release-command.js +0 -101
- package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
- package/dist/cli/commands/vm-spawn-command.js +0 -177
- package/dist/cli/commands/vm-status-command.d.ts +0 -3
- package/dist/cli/commands/vm-status-command.js +0 -50
- package/dist/services/vm/vm-lease.d.ts +0 -40
- package/dist/services/vm/vm-lease.js +0 -160
package/README.md
CHANGED
|
@@ -9,7 +9,6 @@
|
|
|
9
9
|
[](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
|
|
10
10
|
[](./LICENSE)
|
|
11
11
|
[](https://www.npmjs.com/package/peaks-loop)
|
|
12
|
-
[](#status)
|
|
13
12
|
[](https://github.com/SquabbyZ/peaks-loop/stargazers)
|
|
14
13
|
|
|
15
14
|
[English](./README-en.md) · **简体中文**
|
|
@@ -24,22 +23,13 @@
|
|
|
24
23
|
|
|
25
24
|
## 它是什么
|
|
26
25
|
|
|
27
|
-
peaks-loop
|
|
26
|
+
peaks-loop 是装在你已经在用的 AI 编程工具(**Claude Code** / **Z Code**)上的一个编排层。你在对话框里发一条斜杠命令,它把整条工序替你跑完:拆工序 → 一道门一道门跑 → **坏在哪道停在哪道**。
|
|
28
27
|
|
|
29
|
-
|
|
30
|
-
| --- | --- | --- |
|
|
31
|
-
| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
|
|
32
|
-
| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
|
|
33
|
-
| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
|
|
34
|
-
| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
|
|
28
|
+
你只要做两件事:**说一句话**,或者**在一个选项里挑一个**。
|
|
35
29
|
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
<p align="center">
|
|
41
|
-
<img src="./assets/readme/architecture.svg" alt="peaks-loop 四层资产 / 七道闸门 / 一条工程脊柱" width="92%"/>
|
|
42
|
-
</p>
|
|
30
|
+
- **它不是新的 AI CLI。** 不抢你的 shell、不抢你的 prompt、不抢你的 IDE,也不替换 IDE 里任何一个原生入口。
|
|
31
|
+
- **你不用背 CLI、不用手写 manifest、不用手填表单。** 所有 CLI 命令对外隐藏、对 LLM 开放;命令由它替你跑,你只说话。
|
|
32
|
+
- **它不替你拍板。** 影响你资产的决策会拿来问你;其余的它自己跑。
|
|
43
33
|
|
|
44
34
|
---
|
|
45
35
|
|
|
@@ -79,7 +69,6 @@ npm i -g peaks-loop
|
|
|
79
69
|
/peaks-issue-fix-orchestrator 帮我把 upstream 的 30 个 open issue 修一批
|
|
80
70
|
/peaks-sop 帮我把团队的发布流程沉淀成 SOP
|
|
81
71
|
/peaks-solo 这套打法以后还会用,沉淀成本地战术
|
|
82
|
-
/peaks-solo 按上次那样再跑一次
|
|
83
72
|
```
|
|
84
73
|
|
|
85
74
|
<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
|
|
@@ -90,19 +79,18 @@ npm i -g peaks-loop
|
|
|
90
79
|
|
|
91
80
|
## 装上以后,文件放在哪
|
|
92
81
|
|
|
93
|
-
`npm i -g`
|
|
94
|
-
`~/.peaks/{skills,agents,output-styles}
|
|
95
|
-
|
|
96
|
-
包路径(里面嵌着 node 版本号)变化而静默断裂。
|
|
82
|
+
`npm i -g` 之后,三类资产(**skills / agents / output-styles**)的**实体只存一份**,放在你自己 home 下的
|
|
83
|
+
`~/.peaks/{skills,agents,output-styles}`;每个 IDE 目录里(`~/.claude/…`、`~/.trae/…` 等)的条目都是**指向它的链接**
|
|
84
|
+
(目录用 junction,单个 `.md` 文件用符号链接)。所以升级 `peaks-loop` 时链接目标不变、不需要重建。
|
|
97
85
|
|
|
98
|
-
|
|
86
|
+
两件会直接影响你的事:
|
|
99
87
|
|
|
100
|
-
- **受管入口会在升级时被覆盖。** 由 peaks-loop
|
|
101
|
-
`.peaks-managed`
|
|
102
|
-
|
|
103
|
-
- **有些 Windows 机器上会退化成实体副本。**
|
|
104
|
-
|
|
105
|
-
|
|
88
|
+
- **受管入口会在升级时被覆盖。** 由 peaks-loop 装进去的入口(比如 `~/.claude/agents/karpathy-reviewer.md`)旁边有一份
|
|
89
|
+
`.peaks-managed` 边车标记归属,升级时内容会被更新。**想换成你自己的版本,删掉那份额边车即可** —— 没有标记的入口
|
|
90
|
+
一律视为你自己建的,**永不被替换、也永不被删除**。
|
|
91
|
+
- **有些 Windows 机器上会退化成实体副本。** 没有开发者模式、也不是管理员时,建不出**文件**符号链接(目录用的 junction
|
|
92
|
+
不受影响),安装器会写实体副本并在 stderr 明说 `installed as REAL COPIES because this host refused a symlink`。
|
|
93
|
+
内容照样跟着升级走。
|
|
106
94
|
|
|
107
95
|
真源根可用环境变量 `PEAKS_HOME` 重定向。完整的模型、从 4.1.1 升级时会发生什么、怎么验证与回退 →
|
|
108
96
|
[`.peaks/docs/canonical-store.md`](./.peaks/docs/canonical-store.md)。
|
|
@@ -111,11 +99,8 @@ npm i -g peaks-loop
|
|
|
111
99
|
|
|
112
100
|
## 它能为你做什么
|
|
113
101
|
|
|
114
|
-
代码、内容、项目健康、issue 修复、自定义工作流 ——
|
|
115
|
-
|
|
116
|
-
<p align="center">
|
|
117
|
-
<img src="./assets/readme/command-palette.svg" alt="peaks-loop 13 slash commands — command palette" width="92%"/>
|
|
118
|
-
</p>
|
|
102
|
+
代码、内容、项目健康、issue 修复、自定义工作流 —— **每条域都有专门编排器**,按"门禁不通过就停"的纪律一条一条跑。
|
|
103
|
+
你要做的只是挑一条命令发出去:
|
|
119
104
|
|
|
120
105
|
| 域 | 你发这条命令 | 它会做什么 |
|
|
121
106
|
| --- | --- | --- |
|
|
@@ -141,113 +126,25 @@ npm i -g peaks-loop
|
|
|
141
126
|
## 为什么大家会选它
|
|
142
127
|
|
|
143
128
|
- **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
|
|
144
|
-
- **门禁真挡事,不是装饰** ——
|
|
145
|
-
- **跑过的事会变成本地战术(bee)** ——
|
|
129
|
+
- **门禁真挡事,不是装饰** —— 代码审计、安全扫描、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
|
|
130
|
+
- **跑过的事会变成本地战术(bee)** —— 沉淀下来的东西落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
|
|
146
131
|
- **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
|
|
147
132
|
- **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
|
|
148
133
|
|
|
149
134
|
---
|
|
150
135
|
|
|
151
|
-
## 装上以后的几道闸门
|
|
152
|
-
|
|
153
|
-
| 闸门 | 默认状态 | 用来挡什么 |
|
|
154
|
-
| --- | --- | --- |
|
|
155
|
-
| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
|
|
156
|
-
| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
|
|
157
|
-
| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
|
|
158
|
-
| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
|
|
159
|
-
| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
|
|
160
|
-
| 反漂移评估 (Evolution Evaluation) | ✅ 开 | 改进必须过独立评估者 + 反方怀疑者,过不了就回滚 |
|
|
161
|
-
|
|
162
|
-
**所有闸门默认开,你想关哪一道才需要单独说。**
|
|
163
|
-
|
|
164
|
-
---
|
|
165
|
-
|
|
166
|
-
## 当前状态 · 4.0.32
|
|
167
|
-
|
|
168
|
-
<p align="center">
|
|
169
|
-
<img src="./assets/readme/pulse.svg" alt="peaks-loop live metrics — 4 tiles + sparkline + pipeline progress" width="92%"/>
|
|
170
|
-
</p>
|
|
171
|
-
|
|
172
|
-
<p align="center">
|
|
173
|
-
<img src="./assets/readme/trace-stream.svg" alt="peaks-loop 实时 diff & log stream — code diff + 滚动日志 + 7-gate 链路" width="92%"/>
|
|
174
|
-
</p>
|
|
175
|
-
|
|
176
|
-
| | |
|
|
177
|
-
| --- | --- |
|
|
178
|
-
| **最新版本** | [](https://www.npmjs.com/package/peaks-loop) — 4.1.5(2026-10-14) |
|
|
179
|
-
| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
|
|
180
|
-
| **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
|
|
181
|
-
| **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |
|
|
182
|
-
| **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
|
|
183
|
-
| **依赖运行时** | Node ≥ 20 |
|
|
184
|
-
| **License** | MIT |
|
|
185
|
-
|
|
186
|
-
### 近期演进(4.0.18 → 4.0.32)
|
|
187
|
-
|
|
188
|
-
| 版本 | 解决的事 | 怎么验 |
|
|
189
|
-
| --- | --- | --- |
|
|
190
|
-
| **4.0.32** | **CI 首次全绿** —— ci.yml 此前死在第一个门(`pnpm/action-setup@v4` 在 Node 24 runner 上 self-installer 必挂),后面所有步骤从未被验证。修 5 层:corepack 替 pnpm action、删 pre-Build 的 `tsc`(结构性过不了:subpath 指向未生成的 dist)、移除 node 20 矩阵、CI 固定 `PEAKS_CALLER_ID`、3 类 Linux-only 测试 bug(`setImmediate` 闭包竞态 / 平台写死断言 / 墙钟 flake)。 | CI run 全 3 job success;双平台独立复跑 119 files / 0 failed |
|
|
191
|
-
| **4.0.31** | **codegraph 自动刷新失效修复** —— `.peaks-loop-marker` 被下游误判为"已初始化",悬空 `.codegraph/` 永远建不出 `codegraph.db`。改为按 `codegraph.db` 判真实初始化 + 源头真 `init` + 悬空态自愈。 | 现场从悬空态成功建出 24.71 MB 索引 |
|
|
192
|
-
| **4.0.30** | **搜索优先 preflight**(编排层"先搜再答":Context7/WebSearch → ≤5 条绑定指令注入 RD 派发)+ **9 个超行文件拆分**(`src/` 全量 ≤800 行)+ CLI 漂移修复。 | scoped + full suite |
|
|
193
|
-
| **4.0.29** | **codegraph 生命周期闭环** —— RD 规划前 pre-dispatch preflight 自动 init/index 并注入结构;slice 完成边界自动 refresh(CLI-internal,不可绕过)。 | 29 单测 |
|
|
194
|
-
| **4.0.28** | **codegraph 数据目录回根** + **env-first 1M 窗口识别**(修 1M 模型被误判 200K 导致 false soft-warn)。 | `context-now` 修复前 200K/0.884 → 修复后 1M/0.187 |
|
|
195
|
-
| **4.0.24** | zod v4 + Context7 接入 + **Step 2.5 best-practice scan**(业务感知的最佳实践扫描)。 | — |
|
|
196
|
-
| **4.0.21** | vendor-detect recovery + codegraph 集成 + anti-fake-green gate。 | — |
|
|
197
|
-
| **4.0.19 / 4.0.20** | **detached sub-agent**(真 OS 进程 + G8 无限上下文自压缩);`peaks-loop-internal-runtime` 作为公开 lockstep 包发布。 | — |
|
|
198
|
-
| **4.0.18** | statusline 24h overlay。 | — |
|
|
199
|
-
|
|
200
|
-
---
|
|
201
|
-
|
|
202
136
|
## 强烈推荐 · 三个项目组合起来用
|
|
203
137
|
|
|
204
|
-
> **0 学习成本。**
|
|
205
|
-
|
|
206
|
-
<p align="center">
|
|
207
|
-
<img src="./assets/readme/footer.svg" alt="peaks-loop 推荐组合" width="92%"/>
|
|
208
|
-
</p>
|
|
138
|
+
> **0 学习成本。** 让这几个项目一起用最大的好处,是它们的接口都对齐到"自然语言 + 一个选项":你说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
|
|
209
139
|
|
|
210
140
|
| 角色 | 项目 | 一句话 |
|
|
211
141
|
| --- | --- | --- |
|
|
212
|
-
| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 |
|
|
142
|
+
| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 | 装上就有 PRD/RD/QA/UI/SC/TXT 一整条工程链 + 沉淀 |
|
|
213
143
|
| **战术手册** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | Claude Code 上能拿到的最好用的战术、技能、SOP 集合 |
|
|
214
144
|
| **流程与纪律** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review 等流程纪律,每条都自带硬退出条件 |
|
|
215
145
|
|
|
216
146
|
**用起来就一句话**:把上面两个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
|
|
217
147
|
|
|
218
|
-
### 致敬
|
|
219
|
-
|
|
220
|
-
peaks-loop 的两条工程脊柱直接来自这两个项目:
|
|
221
|
-
|
|
222
|
-
- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
|
|
223
|
-
- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
|
|
224
|
-
|
|
225
|
-
---
|
|
226
|
-
|
|
227
|
-
## 开发者 · 24h 模式 / 批量工具
|
|
228
|
-
|
|
229
|
-
> **给 peaks-loop 项目维护者与「24h 模式」使用者** —— end-user 跳过这一段,继续看 FAQ 就够。
|
|
230
|
-
|
|
231
|
-
如果你的工作流跑到了 **24h 模式**(`peaks session 24h-mode` + `24H_ACTIVE`)、**批量 closure pass**、或任何需要从 LLM 主线程派生出一堆 `peaks request transition` 之类的子命令,**先装一份 Python 3.10+**:
|
|
232
|
-
|
|
233
|
-
```bash
|
|
234
|
-
# macOS / Linux
|
|
235
|
-
brew install python@3.12 # 或: pyenv install 3.12
|
|
236
|
-
|
|
237
|
-
# Windows
|
|
238
|
-
winget install Python.Python.3.12
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
**为什么不是 Node.js?peaks-loop 本身就是 Node/pnpm 的呀。** —— peaks-loop 自身的 hard dep 是 Node.js,**没变**。但批量工具脚本的"外部 subprocess 编排"这一层,Python 的 `subprocess.run(capture_output=True, env=...)` 比 Node 的 `child_process.spawn` 在 Windows + UTF-8 + 跨平台 3 件事上少踩坑(LANG/LC_ALL/PYTHONIOENCODING 一行 env 就能修好;Node 的 child_process 需要单独设 `windowsHide` + 改 `console.log` 编码)。代码量也短得多。
|
|
242
|
-
|
|
243
|
-
**规则**(`.peaks/memory/2026-08-01-24h-mode-59-rid-closure-pass.md` 沉淀):
|
|
244
|
-
|
|
245
|
-
1. **探测 → 选语言**:`python3 --version`(Windows 是 `py -3`)若有,优先 Python;否则降级到 `node`;都没有就报错,不要静默 fallback。
|
|
246
|
-
2. **路径**:放 **`.peaks/_tools/<name>.py`**(或 `.mjs`),**不**放 `bin/` —— `bin/` 是 peaks-loop 自己源码分发的目录,临时 helper 会污染它。下划线开头的 `.peaks/_tools/` 跟 `.peaks/_runtime/`、`.peaks/_sub_agents/`、`.peaks/_dogfood/` 一样,gitignored。
|
|
247
|
-
3. **活干完就删**。临时脚本不是 deliverable,留在这里会让别人好奇"这是什么"。
|
|
248
|
-
|
|
249
|
-
这条提示对**普通 end-user 没用** —— 你只要 `npm i -g peaks-loop` 然后发斜杠命令就行,Python 是给"想自己写批处理"那一层人用的。
|
|
250
|
-
|
|
251
148
|
---
|
|
252
149
|
|
|
253
150
|
## FAQ
|
|
@@ -255,14 +152,7 @@ winget install Python.Python.3.12
|
|
|
255
152
|
<details>
|
|
256
153
|
<summary><b>它跟 Claude Code / Z Code 是什么关系?</b></summary>
|
|
257
154
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
</details>
|
|
261
|
-
|
|
262
|
-
<details>
|
|
263
|
-
<summary><b>我需要记 CLI 命令吗?</b></summary>
|
|
264
|
-
|
|
265
|
-
不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
|
|
155
|
+
它是**搭在上面**,不是替换。它不抢你的 shell、不抢你的 prompt、不抢你的 IDE,你照常用。**其他 AI 编程工具适配中,欢迎共建** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)。
|
|
266
156
|
|
|
267
157
|
</details>
|
|
268
158
|
|
|
@@ -283,77 +173,23 @@ winget install Python.Python.3.12
|
|
|
283
173
|
<details>
|
|
284
174
|
<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
|
|
285
175
|
|
|
286
|
-
|
|
176
|
+
**从"代码专用"扩成"多域编排":** 新增 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
|
|
287
177
|
|
|
288
178
|
</details>
|
|
289
179
|
|
|
290
180
|
---
|
|
291
181
|
|
|
292
|
-
## 全量 skill 索引
|
|
293
|
-
|
|
294
|
-
13 个 user skill · 全部入口都在 `skills/<name>/SKILL.md`:
|
|
295
|
-
|
|
296
|
-
<p align="center">
|
|
297
|
-
<img src="./assets/readme/skill-index.svg" alt="peaks-loop 13 user skills 索引卡" width="92%"/>
|
|
298
|
-
</p>
|
|
299
|
-
|
|
300
|
-
---
|
|
301
|
-
|
|
302
|
-
## Ship 摘要(4.x · 19 rid)
|
|
303
|
-
|
|
304
|
-
`009 · 010 · 011 · 014 · 015 · 016 · 017 · 020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034` — 涵盖 CLI surface 收敛(73→5 byte-identical)、Trusted Publishing + OIDC、24h-mode、context spillover、DAG wave+barrier、dashboard aggregation、test-rebuild epic、karpathy-cost self-review、compact visibility、retire-auto-compact-hook 等。
|
|
305
|
-
|
|
306
|
-
<p align="center">
|
|
307
|
-
<img src="./assets/readme/ship-summary.svg" alt="peaks-loop 4.x 19 rid 历程表" width="92%"/>
|
|
308
|
-
</p>
|
|
309
|
-
|
|
310
|
-
---
|
|
311
|
-
|
|
312
|
-
## 下游消费者须知 (Downstream consumer notes)
|
|
313
|
-
|
|
314
|
-
如果你的项目依赖 `peaks-loop`(或者把 `npm install peaks-loop` 写进 CI / 协作者 onboarding),有三件事需要先记清:
|
|
315
|
-
|
|
316
|
-
- **`codegraph` 是传递依赖。** `peaks-loop` 在 `dependencies` 里硬钉 `@colbymchenry/codegraph@1.6.2`,所以 `npm install` / `pnpm install` 会自动拉取。CLI 命令组 `peaks codegraph …`(status / init / index / query / files / context / affected)打包在 `dist/services/codegraph/`,无需额外安装步骤。
|
|
317
|
-
- **`.codegraph/` 目录归属是共享的。** aider / cody 等类似工具也会在项目根创建 `.codegraph/`。`peaks codegraph init` 拒绝覆盖外源 schema,以 exit code 73 + `CODEGRAPH_INIT_CONFLICT` 凭据退出。如果你的项目里已经有其他工具建的 `.codegraph/`,跑 `peaks codegraph init` 之前先移走 / 改名(或确认不再需要后删除)。
|
|
318
|
-
- **session 绑定落在 `.peaks/_runtime/<sessionId>/`。** codegraph 编排上下文(以及其他 session 级证据)由 RD / QA 切片写入。把 `.peaks/_runtime/` 加进项目的 `.gitignore`,避免误提交本地 session 状态。session 缺失 / 未绑定时优雅降级为「跳过 + 警告」,绝不 crash。
|
|
319
|
-
- **yarn-pnp / pnpm-strict 的 doctor 兜底。** `peaks doctor` 在 `require.resolve('@colbymchenry/codegraph/package.json')` 抛错时回退到文件系统遍历,因此严格解析模式下的下游安装也能拿到绿色 check(若版本偏离钉死的 `1.6.2` 则降级为 `severity: 'warning'`)。
|
|
320
|
-
- **tarball 大小 / 自检。** 每次发布都把 codegraph service 打进 `dist/services/codegraph/`。逐版本自检脚本见 `scripts/verify-codegraph-tarball.mjs`(发布前本地跑 `node scripts/verify-codegraph-tarball.mjs`)。exit 0 表示 whitelist 完好,exit 1 表示 tarball 漏了 codegraph service 文件。
|
|
321
|
-
|
|
322
|
-
典型下游安装片段:
|
|
323
|
-
|
|
324
|
-
```bash
|
|
325
|
-
# 把 peaks-loop 加进项目
|
|
326
|
-
npm install peaks-loop
|
|
327
|
-
|
|
328
|
-
# 首次引导 codegraph(若项目已有外源 .codegraph/ 会以 exit 73 + 凭据拒绝)
|
|
329
|
-
npx peaks codegraph init --project .
|
|
330
|
-
|
|
331
|
-
# 校验 doctor 在下游解析模式下仍是绿色
|
|
332
|
-
npx peaks doctor --project .
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
三个常见坑:
|
|
336
|
-
|
|
337
|
-
1. **`peaks codegraph init` 退出码 73** —— 项目里已有外源 `.codegraph/`(aider / cody 等)。把它挪开(或删掉)再重跑。
|
|
338
|
-
2. **`peaks doctor` 报 codegraph 版本漂移** —— 你的 lockfile 解到了一个跟钉死 `1.6.2` 不同的版本。在 lockfile 里钉到 `1.6.2`;这条 warning 不会让 doctor 退出码翻红。
|
|
339
|
-
3. **`.peaks/_runtime/` 下的 session 产物在 `git status` 里嘈杂** —— 把这条路径加进项目的 `.gitignore`。`peaks-loop` 仓库已经这样做;下游消费者应当镜像这条规则。
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
182
|
## 链接
|
|
344
183
|
|
|
345
184
|
- 全部技能清单 → [`skills/`](./skills/)
|
|
346
185
|
- 更新日志 → [`CHANGELOG.md`](./CHANGELOG.md)
|
|
347
186
|
- 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
|
|
348
|
-
- 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
|
|
349
187
|
- 组合推荐: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [obra/superpowers](https://github.com/obra/superpowers)
|
|
350
188
|
|
|
351
189
|
---
|
|
352
190
|
|
|
353
|
-
---
|
|
354
|
-
|
|
355
191
|
<div align="center">
|
|
356
192
|
|
|
357
193
|
MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
|
|
358
194
|
|
|
359
|
-
</div>
|
|
195
|
+
</div>
|
|
@@ -17,12 +17,17 @@
|
|
|
17
17
|
* the defect this command was fixed for (a `.`-titled "best-practice scan").
|
|
18
18
|
* Omitting `--intent` fails with `BEST_PRACTICE_SCAN_INTENT_REQUIRED`.
|
|
19
19
|
*
|
|
20
|
-
* Honesty gate:
|
|
21
|
-
*
|
|
22
|
-
* NOT a scan result — the command then prints a refusal (no
|
|
23
|
-
* recommendation, no ⚠️ catch gate), records the skip, and exits
|
|
24
|
-
* with `BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP` so no automated caller can
|
|
25
|
-
* treat Step 2.5 as satisfied.
|
|
20
|
+
* Honesty gate: the built-in Context7 / WebSearch lookups are stubs, so an
|
|
21
|
+
* uninjected scan comes back `synthetic: true` (see scan-orchestrator). A
|
|
22
|
+
* synthetic result is NOT a scan result — the command then prints a refusal (no
|
|
23
|
+
* table, no recommendation, no ⚠️ catch gate), records the skip, and exits
|
|
24
|
+
* non-zero with `BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP` so no automated caller can
|
|
25
|
+
* treat Step 2.5 as satisfied. Two further outcomes also refuse non-zero, both
|
|
26
|
+
* without rendering: a `--lookup-results` document that breaks the injection
|
|
27
|
+
* contract (`BEST_PRACTICE_SCAN_INVALID_RESULTS`) and a scan that resolved
|
|
28
|
+
* against caller-supplied lookups and found nothing
|
|
29
|
+
* (`BEST_PRACTICE_SCAN_NO_FRAGMENTS` — see `emitNoFragmentsRefusal`, which is
|
|
30
|
+
* the guard against a `★` recommendation built from zero fragments).
|
|
26
31
|
*
|
|
27
32
|
* Catch-gate (spec §7): the command emits a 3-line prompt asking the
|
|
28
33
|
* user to ack / pick alt / reject + reason. The gate is read from
|
|
@@ -1,16 +1,10 @@
|
|
|
1
|
-
import { mkdirSync, writeFileSync } from 'node:fs';
|
|
2
|
-
import { join } from 'node:path';
|
|
3
1
|
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
4
2
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
5
3
|
import { detectLanguage } from '../../services/best-practice/language-detector.js';
|
|
6
4
|
import { scanBestPractice } from '../../services/best-practice/scan-orchestrator.js';
|
|
7
5
|
import { findForbiddenTokens, formatOutputTable } from '../../services/best-practice/output-formatter.js';
|
|
8
|
-
import {
|
|
9
|
-
|
|
10
|
-
const dateStr = new Date().toISOString().slice(0, 10);
|
|
11
|
-
const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, 32) || 'intent';
|
|
12
|
-
return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
|
|
13
|
-
}
|
|
6
|
+
import { CATCH_GATE_PROMPT, emitNoFragmentsRefusal, INTENT_REQUIRED_MESSAGE, renderSyntheticRefusal, scanArtifactPath, SYNTHETIC_SOURCE_MESSAGE, writeRefusal, writeRenderedArtifact } from './best-practice-scan-helpers.js';
|
|
7
|
+
import { readLookupResultsOrFail } from './best-practice-scan-lookup-results.js';
|
|
14
8
|
async function readUserInput() {
|
|
15
9
|
const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
|
|
16
10
|
if (override !== undefined)
|
|
@@ -67,6 +61,8 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
67
61
|
.option('--intent <text>', 'business goal the scan is for (required)')
|
|
68
62
|
.option('--project <path>', 'project root (default cwd)', process.cwd())
|
|
69
63
|
.option('--lang <lang>', 'language override (skip auto-detect)')
|
|
64
|
+
.option('--lookup-results <file>', 'JSON file of real Context7 / WebSearch results the caller performed; ' +
|
|
65
|
+
'keys are `context7` / `websearch`, values are { ok, results:[{title,url,snippet}] }')
|
|
70
66
|
.option('--commit', 'reserved flag — opts the artifact into git tracking (future slice)')).action(async (opts) => {
|
|
71
67
|
try {
|
|
72
68
|
const intent = (opts.intent ?? '').trim();
|
|
@@ -75,6 +71,13 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
75
71
|
process.exitCode = 1;
|
|
76
72
|
return;
|
|
77
73
|
}
|
|
74
|
+
const injection = opts.lookupResults === undefined
|
|
75
|
+
? {}
|
|
76
|
+
: readLookupResultsOrFail(opts.lookupResults, intent, io, opts.json === true);
|
|
77
|
+
if (injection === null) {
|
|
78
|
+
process.exitCode = 1;
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
78
81
|
const detection = opts.lang === undefined ? detectLanguage(opts.project) : null;
|
|
79
82
|
const language = opts.lang ?? detection?.language ?? 'unknown';
|
|
80
83
|
io.stdout(`[best-practice-scan] project=${opts.project} intent=${intent} language=${language}`);
|
|
@@ -82,14 +85,13 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
82
85
|
intent,
|
|
83
86
|
language,
|
|
84
87
|
projectRoot: opts.project,
|
|
85
|
-
io
|
|
88
|
+
io,
|
|
89
|
+
...injection
|
|
86
90
|
});
|
|
87
91
|
if (scan.synthetic) {
|
|
88
92
|
const refusal = renderSyntheticRefusal({ intent, language, source: scan.source });
|
|
89
93
|
io.stdout(refusal);
|
|
90
|
-
const refusedPath =
|
|
91
|
-
mkdirSync(bestPracticeDir(opts.project), { recursive: true });
|
|
92
|
-
writeFileSync(refusedPath, refusal + '\n', 'utf8');
|
|
94
|
+
const refusedPath = writeRefusal(opts.project, intent, refusal);
|
|
93
95
|
printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_SYNTHETIC_LOOKUP', SYNTHETIC_SOURCE_MESSAGE, {
|
|
94
96
|
project: opts.project,
|
|
95
97
|
intent,
|
|
@@ -99,14 +101,25 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
99
101
|
step25: 'skipped-synthetic-lookup',
|
|
100
102
|
artifactPath: refusedPath
|
|
101
103
|
}, [
|
|
102
|
-
'Re-run
|
|
104
|
+
'Re-run with --lookup-results <file> carrying the Context7 / WebSearch results you fetched',
|
|
103
105
|
`Skip record written to ${refusedPath}`
|
|
104
106
|
]), opts.json === true);
|
|
105
107
|
process.exitCode = 1;
|
|
106
108
|
return;
|
|
107
109
|
}
|
|
110
|
+
if (scan.results.length === 0) {
|
|
111
|
+
emitNoFragmentsRefusal(io, opts.json === true, {
|
|
112
|
+
project: opts.project,
|
|
113
|
+
intent,
|
|
114
|
+
language,
|
|
115
|
+
source: scan.source
|
|
116
|
+
});
|
|
117
|
+
process.exitCode = 1;
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
108
120
|
const recommendation = scan.results.length > 0 ? 'A' : 'B';
|
|
109
|
-
const reasoning =
|
|
121
|
+
const reasoning = `基于调用方提供的 ${scan.fragments.length} 个 ${scan.source} 文档片段` +
|
|
122
|
+
`(URL 由调用方构造,Context7 响应不含 URL);` +
|
|
110
123
|
`语言=${language};LLM 推断方案 ${recommendation} 与项目阶段最匹配。`;
|
|
111
124
|
const table = formatOutputTable({
|
|
112
125
|
intent,
|
|
@@ -124,10 +137,8 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
124
137
|
io.stdout(CATCH_GATE_PROMPT);
|
|
125
138
|
const userInput = await readUserInput();
|
|
126
139
|
const outcome = parseCatchGateReply(userInput, recommendation);
|
|
127
|
-
const artifactPath =
|
|
128
|
-
|
|
129
|
-
writeFileSync(artifactPath, table + '\n', 'utf8');
|
|
130
|
-
printResult(io, ok('best-practice.scan', {
|
|
140
|
+
const artifactPath = scanArtifactPath(opts.project, intent);
|
|
141
|
+
const payload = {
|
|
131
142
|
project: opts.project,
|
|
132
143
|
intent,
|
|
133
144
|
language,
|
|
@@ -138,10 +149,14 @@ export function registerBestPracticeScanCommand(program, io) {
|
|
|
138
149
|
artifactPath,
|
|
139
150
|
commitFlag: opts.commit === true,
|
|
140
151
|
forbiddenHits
|
|
141
|
-
}
|
|
152
|
+
};
|
|
153
|
+
writeRenderedArtifact(artifactPath, table, payload);
|
|
154
|
+
printResult(io, ok('best-practice.scan', payload, forbiddenHits.length > 0 ? [`forbidden tokens present: ${forbiddenHits.join(', ')}`] : [], [`Artifact written to ${artifactPath}`, `catch-gate outcome: ${outcome.kind}`]), opts.json === true);
|
|
142
155
|
}
|
|
143
156
|
catch (err) {
|
|
144
|
-
|
|
157
|
+
// No `data.stack`: the caller asked for a scan, not a diagnosis, and the
|
|
158
|
+
// failure here is usually a path it chose (EISDIR names it in the message).
|
|
159
|
+
printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_FAILED', getErrorMessage(err), { project: opts.project, intent: opts.intent ?? null }, ['Rerun with --json for machine-readable envelope']), opts.json === true);
|
|
145
160
|
process.exitCode = 1;
|
|
146
161
|
}
|
|
147
162
|
});
|
|
@@ -1,7 +1,12 @@
|
|
|
1
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
1
2
|
export declare const CATCH_GATE_PROMPT: string;
|
|
2
3
|
export declare const INTENT_REQUIRED_MESSAGE: string;
|
|
3
4
|
export declare const SYNTHETIC_SOURCE_MESSAGE: string;
|
|
4
5
|
export declare function bestPracticeDir(projectRoot: string): string;
|
|
6
|
+
/** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
|
|
7
|
+
* every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
|
|
8
|
+
* truncated to 32, so no intent can introduce a path separator. */
|
|
9
|
+
export declare function scanArtifactPath(projectRoot: string, slugSource: string): string;
|
|
5
10
|
/** Refusal body for a synthetic scan. It is written to the artifact path so
|
|
6
11
|
* the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
|
|
7
12
|
* spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
|
|
@@ -10,3 +15,45 @@ export declare function renderSyntheticRefusal(opts: {
|
|
|
10
15
|
readonly language: string;
|
|
11
16
|
readonly source: string;
|
|
12
17
|
}): string;
|
|
18
|
+
/**
|
|
19
|
+
* A refusal must never overwrite anything.
|
|
20
|
+
*
|
|
21
|
+
* The rendered table and the refusal are keyed on the same `(date, intent)`, and
|
|
22
|
+
* an auto-triggered scan runs with the same intent as the injected one, so a
|
|
23
|
+
* refusal landing second used to destroy a real recommendation. The rule is now
|
|
24
|
+
* unconditional — *any* existing file at the primary path wins — because the
|
|
25
|
+
* only way to tell a refusal from a recommendation without a forgeable content
|
|
26
|
+
* test is to not need the test at all. Refusals for an occupied path go to
|
|
27
|
+
* `best-practice/skipped/`, a directory no primary path can reach: the slug
|
|
28
|
+
* collapses every character outside `[A-Za-z0-9_-]`, so no intent can produce a
|
|
29
|
+
* separator. A fresh project still records its refusal at the primary path,
|
|
30
|
+
* which `tests/unit/cli/commands/best-practice-scan-command.test.ts` pins.
|
|
31
|
+
*
|
|
32
|
+
* Returns where the refusal landed.
|
|
33
|
+
*/
|
|
34
|
+
export declare function writeRefusal(projectRoot: string, intent: string, refusal: string): string;
|
|
35
|
+
/**
|
|
36
|
+
* Write the rendered table to `artifactPath` and return nothing.
|
|
37
|
+
*
|
|
38
|
+
* The artifact is the durable side effect and the envelope is not, so the
|
|
39
|
+
* payload is proved to serialise *before* anything is written: a payload the
|
|
40
|
+
* printer cannot render must not leave behind an artifact claiming a scan that
|
|
41
|
+
* never reported.
|
|
42
|
+
*/
|
|
43
|
+
export declare function writeRenderedArtifact(artifactPath: string, table: string, payload: unknown): void;
|
|
44
|
+
export declare const NO_FRAGMENTS_MESSAGE: string;
|
|
45
|
+
/**
|
|
46
|
+
* Refuse a scan that resolved against real lookups and still found nothing.
|
|
47
|
+
*
|
|
48
|
+
* This is not the synthetic path: no stub took part, so `scan.synthetic` is
|
|
49
|
+
* false, and the orchestrator is right to say so — it answers "was anything
|
|
50
|
+
* fabricated?", not "was anything found?". Without this refusal the empty
|
|
51
|
+
* fallback renders a full table with a `★` on it, from zero fragments, and exits
|
|
52
|
+
* 0. Writes nothing: an absent artifact is the honest record of an empty scan.
|
|
53
|
+
*/
|
|
54
|
+
export declare function emitNoFragmentsRefusal(io: ProgramIO, asJson: boolean, scope: {
|
|
55
|
+
readonly project: string;
|
|
56
|
+
readonly intent: string;
|
|
57
|
+
readonly language: string;
|
|
58
|
+
readonly source: string;
|
|
59
|
+
}): void;
|
|
@@ -1,9 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* extracted from `best-practice-scan-command.ts` (file-size cap campaign).
|
|
3
|
-
*
|
|
4
|
-
* helper, and the synthetic-lookup refusal renderer.
|
|
3
|
+
* Partly a mechanical move: help-text constants, the artifact directory path
|
|
4
|
+
* helper, and the synthetic-lookup refusal renderer. Later additions (the
|
|
5
|
+
* refusal write-path rule, the fragments-free refusal) live here for the same
|
|
6
|
+
* file-size reason.
|
|
5
7
|
*/
|
|
6
|
-
import {
|
|
8
|
+
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
|
9
|
+
import { dirname, join, parse } from 'node:path';
|
|
10
|
+
import { fail } from 'peaks-loop-shared/result';
|
|
11
|
+
import { printResult } from '../cli-helpers.js';
|
|
7
12
|
export const CATCH_GATE_PROMPT = [
|
|
8
13
|
'⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
|
|
9
14
|
'回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
|
|
@@ -17,6 +22,18 @@ export const SYNTHETIC_SOURCE_MESSAGE = 'best-practice-scan: SKIPPED — the Con
|
|
|
17
22
|
export function bestPracticeDir(projectRoot) {
|
|
18
23
|
return join(projectRoot, 'best-practice');
|
|
19
24
|
}
|
|
25
|
+
/** `YYYY-MM-DD` is 10 characters, and the slug is capped at 32 so the filename
|
|
26
|
+
* stays a filename. Both are part of the pinned artifact path. */
|
|
27
|
+
const ISO_DATE_LENGTH = 10;
|
|
28
|
+
const SLUG_MAX_LENGTH = 32;
|
|
29
|
+
/** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
|
|
30
|
+
* every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
|
|
31
|
+
* truncated to 32, so no intent can introduce a path separator. */
|
|
32
|
+
export function scanArtifactPath(projectRoot, slugSource) {
|
|
33
|
+
const dateStr = new Date().toISOString().slice(0, ISO_DATE_LENGTH);
|
|
34
|
+
const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, SLUG_MAX_LENGTH) || 'intent';
|
|
35
|
+
return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
|
|
36
|
+
}
|
|
20
37
|
/** Refusal body for a synthetic scan. It is written to the artifact path so
|
|
21
38
|
* the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
|
|
22
39
|
* spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
|
|
@@ -30,7 +47,73 @@ export function renderSyntheticRefusal(opts) {
|
|
|
30
47
|
'',
|
|
31
48
|
`- language: ${opts.language}`,
|
|
32
49
|
`- transport that answered: ${opts.source} (stub)`,
|
|
33
|
-
'- Step 2.5: recorded as skipped, reason "synthetic-lookup". Re-run this step
|
|
34
|
-
' lookup
|
|
50
|
+
'- Step 2.5: recorded as skipped, reason "synthetic-lookup". Re-run this step with',
|
|
51
|
+
' --lookup-results <file> once real lookup results are available; a gate cannot be',
|
|
52
|
+
' satisfied from a fabricated scan.'
|
|
35
53
|
].join('\n');
|
|
36
54
|
}
|
|
55
|
+
/**
|
|
56
|
+
* A refusal must never overwrite anything.
|
|
57
|
+
*
|
|
58
|
+
* The rendered table and the refusal are keyed on the same `(date, intent)`, and
|
|
59
|
+
* an auto-triggered scan runs with the same intent as the injected one, so a
|
|
60
|
+
* refusal landing second used to destroy a real recommendation. The rule is now
|
|
61
|
+
* unconditional — *any* existing file at the primary path wins — because the
|
|
62
|
+
* only way to tell a refusal from a recommendation without a forgeable content
|
|
63
|
+
* test is to not need the test at all. Refusals for an occupied path go to
|
|
64
|
+
* `best-practice/skipped/`, a directory no primary path can reach: the slug
|
|
65
|
+
* collapses every character outside `[A-Za-z0-9_-]`, so no intent can produce a
|
|
66
|
+
* separator. A fresh project still records its refusal at the primary path,
|
|
67
|
+
* which `tests/unit/cli/commands/best-practice-scan-command.test.ts` pins.
|
|
68
|
+
*
|
|
69
|
+
* Returns where the refusal landed.
|
|
70
|
+
*/
|
|
71
|
+
export function writeRefusal(projectRoot, intent, refusal) {
|
|
72
|
+
const primary = scanArtifactPath(projectRoot, intent);
|
|
73
|
+
const target = existsSync(primary)
|
|
74
|
+
? join(dirname(primary), 'skipped', parse(primary).base)
|
|
75
|
+
: primary;
|
|
76
|
+
mkdirSync(dirname(target), { recursive: true });
|
|
77
|
+
writeFileSync(target, refusal + '\n', 'utf8');
|
|
78
|
+
return target;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Write the rendered table to `artifactPath` and return nothing.
|
|
82
|
+
*
|
|
83
|
+
* The artifact is the durable side effect and the envelope is not, so the
|
|
84
|
+
* payload is proved to serialise *before* anything is written: a payload the
|
|
85
|
+
* printer cannot render must not leave behind an artifact claiming a scan that
|
|
86
|
+
* never reported.
|
|
87
|
+
*/
|
|
88
|
+
export function writeRenderedArtifact(artifactPath, table, payload) {
|
|
89
|
+
JSON.stringify(payload);
|
|
90
|
+
mkdirSync(dirname(artifactPath), { recursive: true });
|
|
91
|
+
writeFileSync(artifactPath, table + '\n', 'utf8');
|
|
92
|
+
}
|
|
93
|
+
export const NO_FRAGMENTS_MESSAGE = 'best-practice-scan: NO FRAGMENTS — the lookups this scan resolved against returned no ' +
|
|
94
|
+
'documentation at all, so there is nothing to compare and no recommendation to make. ' +
|
|
95
|
+
'No comparison table, no ★ and no ⚠️ catch gate were produced, and no artifact was written.';
|
|
96
|
+
/**
|
|
97
|
+
* Refuse a scan that resolved against real lookups and still found nothing.
|
|
98
|
+
*
|
|
99
|
+
* This is not the synthetic path: no stub took part, so `scan.synthetic` is
|
|
100
|
+
* false, and the orchestrator is right to say so — it answers "was anything
|
|
101
|
+
* fabricated?", not "was anything found?". Without this refusal the empty
|
|
102
|
+
* fallback renders a full table with a `★` on it, from zero fragments, and exits
|
|
103
|
+
* 0. Writes nothing: an absent artifact is the honest record of an empty scan.
|
|
104
|
+
*/
|
|
105
|
+
export function emitNoFragmentsRefusal(io, asJson, scope) {
|
|
106
|
+
printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_NO_FRAGMENTS', NO_FRAGMENTS_MESSAGE, {
|
|
107
|
+
project: scope.project,
|
|
108
|
+
intent: scope.intent,
|
|
109
|
+
language: scope.language,
|
|
110
|
+
scanSource: scope.source,
|
|
111
|
+
fragments: 0,
|
|
112
|
+
synthetic: false,
|
|
113
|
+
step25: 'skipped-no-fragments',
|
|
114
|
+
artifactPath: null
|
|
115
|
+
}, [
|
|
116
|
+
'Supply a results file whose context7 or websearch entry declares ok: true with at least one fragment',
|
|
117
|
+
'Or rerun without --lookup-results to record the honest no-injection skip instead'
|
|
118
|
+
]), asJson);
|
|
119
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { LookupFn } from '../../services/best-practice/scan-orchestrator.js';
|
|
2
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
3
|
+
/** The scan seam's two optional lookups, ready to spread into `ScanOptions`. */
|
|
4
|
+
export type InjectedLookups = {
|
|
5
|
+
context7Lookup?: LookupFn;
|
|
6
|
+
webSearchLookup?: LookupFn;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* Rule 1 plus the refusal. Returns the injected seam lookups, or `null` after
|
|
10
|
+
* emitting `BEST_PRACTICE_SCAN_INVALID_RESULTS` — in which case the caller must
|
|
11
|
+
* set a non-zero exit code and scan nothing.
|
|
12
|
+
*/
|
|
13
|
+
export declare function readLookupResultsOrFail(file: string, intent: string, io: ProgramIO, asJson: boolean): InjectedLookups | null;
|