flow-comet 1.6.3 → 1.6.5
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/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +21 -3
- package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
- package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +8 -2
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +180 -6
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +69 -18878
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +29 -5
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1053 -0
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
- package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
- package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
- package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +817 -0
- package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
- package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
- package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +618 -0
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +756 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1235 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +384 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +714 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +204 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +179 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +714 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +123 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +249 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1505 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1248 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2493 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +214 -2
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +976 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1398 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1367 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1492 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +59 -7559
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +223 -2476
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
- package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
- package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
- package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
- package/README.md +52 -69
- package/package.json +3 -2
- package/scripts/dsh-bridge.mjs +2 -2
- package/scripts/lib/installer-cleanup.mjs +152 -0
- package/scripts/lib/installer-flowkit.mjs +159 -0
- package/scripts/lib/installer-hooks.mjs +363 -0
- package/scripts/lib/installer-loader.mjs +220 -0
- package/scripts/lib/installer-migrate.mjs +236 -0
- package/scripts/lib/installer-platforms.mjs +314 -0
- package/scripts/prepare-env.mjs +21 -1313
|
@@ -29,7 +29,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
29
29
|
|---|---|---|
|
|
30
30
|
| 段在场,段内出现**结构形态**的「不适用」标记 | 非前端 change | **显式跳过**:不加载、不产出;design 出口打印 `UI-DESIGN: skipped(非前端)` 与命中片段后放行 |
|
|
31
31
|
| 段在场,无**结构形态**的「不适用」标记 | 前端 change | 必须加载本技能并产出 `.specs/<change-id>/UI-DESIGN.md` |
|
|
32
|
-
| 段缺席 |
|
|
32
|
+
| 段缺席 | **新 change:拦**(条件段标题必须在场——缺席即 BLOCKED,须显式标注「不适用」或填写调性)· **旧 change:兼容**(沿用旧口径判非前端,出口打印 `UI-DESIGN: skipped(旧 change 兼容)`) | 新 change 先回 open 补段;旧 change 保持原行为,不追溯 |
|
|
33
33
|
|
|
34
34
|
**「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、行尾,或下列标点之一:`,。;、,;.::!!??…—()()【】「」『』“”"'`——**只有这一组**,组外的标点如 `/`、`-` 不算边界),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
|
|
35
35
|
|
|
@@ -42,7 +42,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
42
42
|
`design` 节点对本技能的绑定等级 = **guarded**(见 `../flow-comet/reference/workflow-protocol.json` 的 `requiredSkillCalls`)。前端 change 的完整动作是**先加载、再声明、后干活**:
|
|
43
43
|
|
|
44
44
|
1. 用 Skill 工具加载本技能(只读取 SKILL.md 文件不叫加载);
|
|
45
|
-
2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md
|
|
45
|
+
2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md --templates DESIGN.md`(`--templates` 声明 design 节点的产出物模板;前端要一并声明 UI-DESIGN 时写 `--templates DESIGN.md,UI-DESIGN.md`);
|
|
46
46
|
3. 把 `required-skill:design.flow-comet-ui-design` 记进 design 节点的 evidence(`record` / handoff 载荷)。
|
|
47
47
|
|
|
48
48
|
design 出口的核对口径:
|
|
@@ -17,16 +17,18 @@ This node performs the final integration verification: running all automated tes
|
|
|
17
17
|
|
|
18
18
|
### 必填段清单(结构+存在级)
|
|
19
19
|
|
|
20
|
-
|
|
|
21
|
-
|
|
22
|
-
| TEST.md | `##
|
|
23
|
-
| UAT.md | `## 验收结果`
|
|
20
|
+
| 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
|
|
21
|
+
|------|------|------|
|
|
22
|
+
| `TEST.md` | `## 验证命令`(本仓登记的**增量段**,必填,位置不限但标题后必须紧跟代码块)——exit verify 真实执行其中的命令并计数失败 | `TEST.md` 的 5 轮 H2 与结构子段**在本出口**按登记表骨架校验(`flowkit.verify.v1` 的 artifacts 含 TEST.md;UAT 未登记 → 跳过)。verify 的**模板声明**为空集,但结构校验来自节点 `outputSchemas`,不来自模板声明 |
|
|
23
|
+
| `UAT.md` | **仅存在性**——guard 只查 `.specs/<change-id>/UAT.md` 在场(UAT 无上游模板,不校验段名与段序) | `## 验收结果` 等段:格式与内容由 UAT 执行与 review 把关,guard 不判段名 |
|
|
24
24
|
|
|
25
|
-
> **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet
|
|
25
|
+
> **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet 登记的增量段(exit verify 会真实执行其中的命令并计数失败)。使用 `flow-kit/templates/TEST.md` 填写后,**必须按上方右栏补写 `## 验证命令` 段**,否则 exit verify 会被 BLOCKED。**排版约束**:`## 验证命令` 标题后必须**紧跟**代码块(` ``` `),标题与代码块之间**不得插入任何说明行**(如 blockquote 说明——guard 正则要求标题后直接是代码块);段名可带括号后缀。UAT.md 同理:flow-kit 无独立 UAT 模板(UAT 脚本格式见 5-test.md 1.2 节),本出口只查文件在场——`## 验收结果` 段按惯例填写,格式由 UAT 执行与 review 把关。
|
|
26
26
|
|
|
27
|
-
guard 校验见 workflow-guard.mjs
|
|
27
|
+
guard 校验见 workflow-guard.mjs 的 verify 出口门禁(`## 验证命令` 增量段真实执行 + 失败计数 + LESSONS 条目形态与条目区);UAT.md 只查存在性,「填得好不好」由 review 与 UAT 执行把关。
|
|
28
28
|
|
|
29
|
-
>
|
|
29
|
+
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
30
|
+
|
|
31
|
+
本节点零模板:只有 `READ PROMPT:`(`7-integration`),没有 `READ TEMPLATE:`。
|
|
30
32
|
|
|
31
33
|
### Prerequisites
|
|
32
34
|
|
|
@@ -120,6 +122,8 @@ Load `flow-comet-integration` during this Node and record completed check `requi
|
|
|
120
122
|
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load verify flow-comet-integration --prompt flow-kit/prompts/7-integration.md
|
|
121
123
|
```
|
|
122
124
|
|
|
125
|
+
> **零模板节点省略 `--templates`**:verify 的产出物模板映射为空(UAT.md 无上游模板;TEST.md 的结构校验在 verify 出口(本节点),review 只做 5 轮完整性过程检查),命令**不带** `--templates`——省略即视为空集,与节点映射一致并通过;不要「为保险」补一个模板名(多写会与映射不一致而被拦)。
|
|
126
|
+
|
|
123
127
|
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做。
|
|
124
128
|
|
|
125
129
|
## Augmentations
|
|
@@ -151,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record verify '{"summa
|
|
|
151
155
|
| `verify-evidence` | UAT.md exists | artifact-exists |
|
|
152
156
|
| `automation-passed` | All automated checks pass (real output) | 执行纪律(review 把关),guard 不校验 |
|
|
153
157
|
| `retry-limit` | No more than 3 auto-retries(机器计数 verifyFailures,第 4 次 BLOCKED) | process-check |
|
|
154
|
-
| `lessons-nominated` | LESSONS.md
|
|
158
|
+
| `lessons-nominated` | LESSONS.md 条目形态与条目区合规(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 结构级(guard 强制:本出口校验 `.specs/LESSONS.md` 的条目写 `### L-NNN`、位于条目区、编号升序——新 change 违反即 BLOCKED,旧 change WARN);「是否有合格条目」由执行者把关,归档时另以 `evidence.lessonsNomination` 核对 |
|
|
155
159
|
|
|
156
160
|
## Exit Check
|
|
157
161
|
|
package/README.md
CHANGED
|
@@ -4,17 +4,15 @@
|
|
|
4
4
|
|
|
5
5
|
</div>
|
|
6
6
|
|
|
7
|
-
<h1 align="center">flow-comet</h1>
|
|
8
|
-
|
|
9
7
|
<p align="center">
|
|
10
|
-
<
|
|
11
|
-
<br />
|
|
12
|
-
<em>For AI coding workflows — deterministic state machine · protocol-driven · guard-validated · subagent-isolated</em>
|
|
8
|
+
<img src="assets/readme/hero.svg" width="100%" alt="flow-comet — the project mark beside the name, and the engine's eight nodes drawn as a rail in which every transition carries a gate" />
|
|
13
9
|
</p>
|
|
14
10
|
|
|
15
11
|
<p align="center">
|
|
16
|
-
<a href="
|
|
17
|
-
<a href="
|
|
12
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat" alt="License: MIT" /></a>
|
|
13
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
14
|
+
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI status" /></a>
|
|
15
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.5-blue.svg" alt="Version 1.6.5" /></a>
|
|
18
16
|
</p>
|
|
19
17
|
|
|
20
18
|
<p align="center">
|
|
@@ -22,13 +20,6 @@
|
|
|
22
20
|
<a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-10A37F?style=flat&logoColor=white" alt="Codex" /></a>
|
|
23
21
|
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-4D6BFE?style=flat&logoColor=white" alt="DeepSeek Harness" /></a>
|
|
24
22
|
<a href="https://github.com/rihebty/flow-kit"><img src="https://img.shields.io/badge/flow--kit-4CAF50?style=flat" alt="flow-kit" /></a>
|
|
25
|
-
<a href="https://github.com/rpamis/comet"><img src="https://img.shields.io/badge/comet-4CAF50?style=flat" alt="comet" /></a>
|
|
26
|
-
</p>
|
|
27
|
-
|
|
28
|
-
<p align="center">
|
|
29
|
-
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
30
|
-
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
|
|
31
|
-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.3-blue.svg" alt="Version" /></a>
|
|
32
23
|
</p>
|
|
33
24
|
|
|
34
25
|
---
|
|
@@ -48,7 +39,7 @@ cd <your project>
|
|
|
48
39
|
fcomet init
|
|
49
40
|
```
|
|
50
41
|
|
|
51
|
-
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal
|
|
42
|
+
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal, a run without `--platform` asks which platform to set up — the arrow-key selector pre-selects the platforms it detects, and the fallback prompt takes the detected platform as its default (Claude Code when several traces are present); for a non-interactive pick use `--platform claude-code`, `--platform codex`, `--platform dsh`, a comma-separated combination such as `--platform claude-code,dsh`, or `--platform all`. Re-running the same command updates an existing install and is idempotent. Upgrading the global package only replaces the CLI — run `fcomet init` in a project again to refresh that project's copy.
|
|
52
43
|
|
|
53
44
|
**Verify**:
|
|
54
45
|
|
|
@@ -71,84 +62,76 @@ The first call confirms scope, then creates the branch for the change, initializ
|
|
|
71
62
|
|
|
72
63
|
To see where it is, just ask it — or inspect it from the command line with `status` and `next` in the project (the per-platform paths are in [Installation](docs/INSTALLATION.md)).
|
|
73
64
|
|
|
74
|
-
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is
|
|
65
|
+
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is appended at the top of `.specs/CHANGELOG.md`. The node-by-node walkthrough — including what the workflow runs underneath, and how to drive a node by hand when you need to — is in [Usage](docs/USAGE.md).
|
|
75
66
|
|
|
76
67
|
## Pick a platform
|
|
77
68
|
|
|
78
69
|
| Platform | Skills install to | Hook / bridge | First use |
|
|
79
70
|
|---|---|---|---|
|
|
80
71
|
| Claude Code (default) | `.claude/skills/` | `settings.local.json` → `hooks.PreToolUse` | the workspace must be trusted; headless sessions need that trust pre-accepted |
|
|
81
|
-
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs
|
|
72
|
+
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs |
|
|
82
73
|
| DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
|
|
83
74
|
|
|
84
75
|
Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
|
|
85
76
|
|
|
86
|
-
##
|
|
77
|
+
## Real-run artifacts
|
|
87
78
|
|
|
88
|
-
|
|
79
|
+
A complete 8-node run leaves the artifact trail below — [a real archived change](docs/examples/processor-pipeline/) from the end-to-end test project (2026-08-13), kept in this repository as the quality reference: CHANGE / REQUIREMENT / DESIGN / TASK / six-section summaries / REVIEW with disposition markers / TEST / UAT / KNOWN-ISSUES / skill-load declaration markers.
|
|
89
80
|
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
81
|
+
```
|
|
82
|
+
processor-pipeline/ (archived change, full artifact set)
|
|
83
|
+
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
84
|
+
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
85
|
+
├── REVIEW.md (findings with disposition markers)
|
|
86
|
+
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
87
|
+
├── KNOWN-ISSUES.md
|
|
88
|
+
└── .skill-loads/ (11 skill-load declaration markers)
|
|
89
|
+
```
|
|
95
90
|
|
|
96
|
-
|
|
91
|
+
Two captures from real sessions of this project, unedited: a workflow skill loading normally more than four hours in, and the end of a five-hour run whose verify exit had already executed the test commands.
|
|
97
92
|
|
|
98
|
-
|
|
93
|
+
<p align="center">
|
|
94
|
+
<img src="assets/readme/proof-board.png" width="100%" alt="Two terminal captures: a workflow skill loading four hours into a session, and the end of a five-hour run after verification" />
|
|
95
|
+
</p>
|
|
99
96
|
|
|
100
|
-
|
|
101
|
-
|---------|-------------|-----------|---------------------------|
|
|
102
|
-
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process + `.specs/` templates + R1-R8 rules, zero runtime | Humans load prompt files stage by stage; state flows through `.md` artifacts | **Dependency / base** — flow-comet is its automation layer; artifacts and rules fully inherited |
|
|
103
|
-
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding | `openspec/` directory, one proposal/specs/design/tasks per change, propose→apply→verify→archive | **Idea source + lighter alternative** — spec-first thinking fused into flow-kit; standalone use is lighter (no state machine, no stage gates) |
|
|
104
|
-
| **Superpowers** (obra) | Claude Code skill set + full dev methodology | Composable skills (brainstorm/plan/TDD/debug/review), triggered by context, enforced by instructions | **Idea source + partial overlap** — skill-based discipline relies on model compliance; flow-comet scripts and machine-verifies the same discipline |
|
|
105
|
-
| **comet** (rpamis) | Resumable long-task workflows + skill platform: protocol state machine, guard gates, hook interception | `/comet` routes by config; Classic = OpenSpec + Superpowers 5-stage state machine | **Mechanism source** — flow-comet borrows its mechanism shapes (protocol-as-truth, script-owned state, guard gates, hook whitelist) and drops its platform facilities (eval/publish); state does not interoperate with Comet Classic |
|
|
106
|
-
| **GSD** | Spec-driven development meta-prompt / context-engineering workflow | Milestones → slices → tasks; fresh context per stage with pre-inlined context; worktree isolation + UAT | **Idea source (same lane)** — fresh-context execution and stage gates align; no script state-machine routing, relies on prompt discipline |
|
|
107
|
-
| **spec-kit** (GitHub) | SDD toolkit: Spec → Plan → Tasks → Implement | Each stage feeds markdown artifacts to the next; task format with order IDs, parallel `[P]` markers, file paths | **Idea source (same lane)** — task-with-file-paths/parallel-marker shape is same-origin with flow-kit TASK; no stage-transition enforcement |
|
|
108
|
-
| **claude-task-master** | AI-driven task management (MCP + CLI) | PRD parsing → task decomposition → dependency graph → next-task orchestration | **Complement** — manages the task layer only (decomposition/ordering/dependencies), not stage gates, artifact validation, or write permissions |
|
|
97
|
+
## How it works
|
|
109
98
|
|
|
110
|
-
|
|
99
|
+
The process is flow-kit's nine stages; the engine runs them as eight nodes. CHANGE and REQUIREMENT are covered by `open`, TEST and REVIEW by `review`, and DEV runs as `execute` or `subagent-execute` depending on the execution mode. Every node's exit is validated before the next one opens — the `verify` exit really executes the commands in `TEST.md` — and each node's artifacts land under `.specs/<change-id>/`.
|
|
111
100
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| Validation | Humans eyeball artifacts against the rules; TEST.md commands "should" run | Guards enforce required artifacts/sections at every node entry/exit; verify actually executes the TEST.md commands and counts failures |
|
|
116
|
-
| Discipline enforcement | Rules are markdown text the model may ignore | Three defense layers: write whitelist physically blocks out-of-scope writes / coordinator prohibition / exit takeover detection |
|
|
117
|
-
| Recovery | Depends on conversation memory; progress is lost across sessions | File-as-truth: re-derive the node from `.specs/` and auto-correct state; any session resumes correctly |
|
|
118
|
-
| Parallel implementation | Humans coordinate multiple windows, easy to overstep | One delegation contract on every supported platform — write permission, commit isolation, verification isolation and integration discipline. The guard decides by the caller's identity, an isolated worktree is one implementation of write permission rather than a requirement, and the only platform difference is who builds the tree (per-platform channels and what is not yet covered: [Parallel delegation](docs/MECHANISM.md#parallel-delegation)). Subagents return a verified contract (commit hash + evidence) and the coordinator cannot write source |
|
|
119
|
-
| Decision burden | A confirmation point at every stage, humans answer everything | Decisions are classified (user-decided / auto-handled / stop conditions / manual handover); humans only intervene at key points (scope, tech stack, breaking changes, review findings, archive) |
|
|
101
|
+
<p align="center">
|
|
102
|
+
<img src="assets/readme/workflow.gif" width="100%" alt="An animated diagram mapping the nine flow-kit stages onto the engine's eight nodes: CHANGE and REQUIREMENT merge into open, TEST and REVIEW into review, DEV runs as execute or subagent-execute, and every transition carries a gate" />
|
|
103
|
+
</p>
|
|
120
104
|
|
|
121
|
-
|
|
105
|
+
Driving a node by hand, the artifacts each node produces, and the two command surfaces are documented in [Usage](docs/USAGE.md); what the engine guarantees and how a node's exit is validated are in [Core Mechanisms](docs/MECHANISM.md).
|
|
106
|
+
|
|
107
|
+
## Why flow-comet
|
|
122
108
|
|
|
123
109
|
1. **Discipline goes from "self-discipline" to "machine-checked"** — every stage entry/exit has script validation: artifacts complete, sections filled, verify commands actually run, tasks stay in bounds.
|
|
124
110
|
2. **No lost progress across sessions** — where you are is always derived from `.specs/` artifacts, never from conversation memory; reopen and continue from the right node.
|
|
125
|
-
3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement
|
|
126
|
-
4. **The native automation layer for flow-kit** — not a re-invention: artifact formats, rules, and stages are identical to flow-kit; a flow-kit project upgrades to a machine-driven flow by installing flow-comet, no migration needed.
|
|
127
|
-
5. **Protocol-driven, minimal dependency, install-and-run** — the built-in 8-node flow works out of the box; any installed skill can be composed into a custom protocol on the same engine; Node.js 18+; the only third-party dependency is `@clack/prompts`, used exclusively by the installer's TTY multi-select (with an automatic readline fallback otherwise); one command installs it.
|
|
111
|
+
3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement. The coordinator is banned from writing source, and writes outside the current node's scope are refused by the hook. The layers themselves are described in [Core Mechanisms](docs/MECHANISM.md).
|
|
128
112
|
|
|
129
|
-
|
|
113
|
+
### Related projects
|
|
130
114
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
processor-pipeline/ (archived change, full artifact set)
|
|
137
|
-
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
138
|
-
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
139
|
-
├── REVIEW.md (findings with disposition markers)
|
|
140
|
-
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
141
|
-
├── KNOWN-ISSUES.md
|
|
142
|
-
└── .skill-loads/ (11 skill-load declaration markers)
|
|
143
|
-
```
|
|
115
|
+
<p align="center">
|
|
116
|
+
<img src="assets/readme/related-projects.svg" width="100%" alt="How flow-comet relates to the projects it is compared with: five sources aggregated through flow-kit, comet as an early mechanism reference that is now decoupled, and brooks-lint as an optional integration" />
|
|
117
|
+
</p>
|
|
144
118
|
|
|
145
|
-
|
|
119
|
+
| Project | What it is, and how it works | Relationship to flow-comet |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer: templates, rules and artifact shapes are inherited from upstream, and this repository only adds the increment sections upstream does not define; the template is the sole authority on shape, and documents without an upstream template (`UAT`, the archive's leftovers list) are checked for existence only. The projects below reached flow-comet through it. |
|
|
122
|
+
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding. One `proposal` / `specs` / `design` / `tasks` set per change under `openspec/`; the default profile runs propose → apply → sync → archive. | **Aggregated through flow-kit** (idea source). Standalone it stays lighter: no state machine, no gates. |
|
|
123
|
+
| **Superpowers** (obra) | Agentic skills framework plus a full development methodology, installed per harness across Claude Code, Codex, Cursor, Gemini CLI and more. Skills trigger by context and are enforced by instructions. | **Aggregated through flow-kit** (idea source, partial overlap). Discipline lives in skill text and relies on model compliance; flow-comet machine-checks the same discipline. |
|
|
124
|
+
| **comet** (rpamis) | Resumable long-running task workflow and skill platform: a five-stage state machine, stage guards, hook write-interception. `/comet` routes from config and defaults to its Native branch. | **Early mechanism reference, now decoupled.** The hook-injection shape and script-owned state came from here; the naming was decoupled and state does not interoperate. Only its Classic branch carries the OpenSpec + Superpowers lineage. |
|
|
125
|
+
| **GSD** | Spec-driven development meta-prompt and context-engineering workflow: milestones → phases → plans, a fresh context window per agent with scoped payloads, worktree isolation and a UAT gate. | **Aggregated through flow-kit** (idea source, same lane). Fresh-context execution and stage gates align; routing stays prompt-driven. |
|
|
126
|
+
| **spec-kit** (GitHub) | SDD toolkit: Specify → Plan → Tasks → Implement → Converge. Each stage feeds markdown artifacts to the next, with order ids, `[P]` parallel markers and file paths in the task block. | **Aggregated through flow-kit** (idea source, same lane). That task-block shape is what flow-kit's TASK template inherited; stage transitions are not enforced. |
|
|
127
|
+
| **claude-task-master** | AI-driven task management over MCP and a CLI: PRD parsing → task breakdown → dependency graph → next-task orchestration. Distributed under MIT with Commons Clause. | **Aggregated through flow-kit** (complement). Covers the task layer only: no stage gates, no artifact validation, no write permissions. |
|
|
128
|
+
| **brooks-lint** (hyhmrright) | Third-party review engine grounded in twelve classic engineering books: 6 production and 6 test decay risks, findings cited as Symptom → Source → Consequence → Remedy, a 0–100 health score and six modes. | **Optional integration (MIT, not a dependency).** Where installed, five of its six commands back the self-check and review rounds; absent, the workflow degrades along a declared fallback chain. |
|
|
146
129
|
|
|
147
|
-
|
|
130
|
+
**Fit**: flow-comet is built for long-running, multi-session development changes. The contract is the same on all three platforms — write permission, commit isolation, verification isolation and integration discipline — while the depth of testing differs per platform, and the per-platform coverage is stated in [Core Mechanisms](docs/MECHANISM.md#parallel-delegation). It is not a general CI/CD or project-management tool; other platforms (Gemini / Cursor) are not guaranteed.
|
|
148
131
|
|
|
149
|
-
|
|
132
|
+
## Recommended: brooks-lint
|
|
150
133
|
|
|
151
|
-
|
|
134
|
+
The quality checks are grounded in the decay-risk framework of [brooks-lint](https://github.com/hyhmrright/brooks-lint), a third-party (MIT) review engine that diagnoses code against twelve classic engineering books. Where it is installed, the per-task self-check, the review node's code-quality round and the test-quality check run through it, and the `health` side command folds its result into its report; where it is not, the workflow still completes along a declared fallback chain and says so. It is not a dependency and nothing needs configuring on the flow-comet side; its installer covers more platforms than this project does, with a different depth of verification per platform — the details are in [Installation](docs/INSTALLATION.md).
|
|
152
135
|
|
|
153
136
|
## Relationship to the upstream project
|
|
154
137
|
|
|
@@ -173,13 +156,13 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
173
156
|
|
|
174
157
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
175
158
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
176
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
159
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 350 SCENARIOS PASSED`
|
|
177
160
|
4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
|
|
178
161
|
|
|
179
|
-
CI enforces the repository conventions automatically on every PR and push
|
|
162
|
+
CI enforces the repository conventions automatically on every PR and push: regression, installer reproducibility, workflow and bilingual-mirror quality, PR discipline, version consistency, and dead links. Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
|
|
180
163
|
|
|
181
164
|
## License
|
|
182
165
|
|
|
183
166
|
[MIT](LICENSE) © 2026 baobaolaodie
|
|
184
167
|
|
|
185
|
-
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT)
|
|
168
|
+
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT). Its mechanism shapes were borrowed from [Comet](https://github.com/rpamis/comet) (MIT), which it does not depend on.
|
package/package.json
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-comet",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.5",
|
|
4
4
|
"description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
7
7
|
".flow-comet/skills",
|
|
8
8
|
".flow-comet/rules",
|
|
9
9
|
"scripts/prepare-env.mjs",
|
|
10
|
-
"scripts/dsh-bridge.mjs"
|
|
10
|
+
"scripts/dsh-bridge.mjs",
|
|
11
|
+
"scripts/lib"
|
|
11
12
|
],
|
|
12
13
|
"bin": {
|
|
13
14
|
"fcomet": "scripts/prepare-env.mjs",
|
package/scripts/dsh-bridge.mjs
CHANGED
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
// 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
|
|
39
39
|
// ESM 模块导出 { name, apply },ctx 由 dsh 注入。
|
|
40
40
|
//
|
|
41
|
-
// BRIDGE_VERSION: 1.6.
|
|
41
|
+
// BRIDGE_VERSION: 1.6.5
|
|
42
42
|
|
|
43
43
|
import { spawn } from 'node:child_process';
|
|
44
44
|
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
@@ -50,7 +50,7 @@ import path from 'node:path';
|
|
|
50
50
|
// 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
|
|
51
51
|
// bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
|
|
52
52
|
export const name = 'dsh-flow-comet-bridge';
|
|
53
|
-
export const version = '1.6.
|
|
53
|
+
export const version = '1.6.5';
|
|
54
54
|
|
|
55
55
|
// guard 在项目内的相对路径常量(随 skill 包分发)。
|
|
56
56
|
const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* installer-cleanup.mjs — 生成物镜像目录的定向清理(升级路径残留)
|
|
3
|
+
*
|
|
4
|
+
* 为什么清理独立成模块:判据只有一条——「权威源同一相对路径上不存在同类型条目」,而删除面
|
|
5
|
+
* 必须与本次整树复制的目标根严格对应。每一条 fail-closed(镜像根是链接不跟随 / 真实路径越出
|
|
6
|
+
* 项目根不删 / 符号链接不跟随 / 类型冲突不删 / 清理后仍非空不删)都是**不可放宽**的安全边界:
|
|
7
|
+
* 放宽任何一条,删除动作就可能落到项目之外、或落到用户自有文件上。把它与入口的 CLI / 编排
|
|
8
|
+
* 分开,是为了让「哪些路径允许删」只有一处、可单独审查与测试。
|
|
9
|
+
*
|
|
10
|
+
* 依赖方向:本模块依赖 installer-migrate 的探测原语(lstatIfExists / readdirIfExists——
|
|
11
|
+
* 「该路径确实不存在」的单一判定);反向依赖不存在。
|
|
12
|
+
*/
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
|
|
16
|
+
import { lstatIfExists, readdirIfExists } from './installer-migrate.mjs';
|
|
17
|
+
|
|
18
|
+
// ---------- 生成物镜像目录的定向清理(升级路径残留) ----------
|
|
19
|
+
//
|
|
20
|
+
// 缺陷形态(实测):copyTree 只覆盖、不删除 ⇒ 权威源里已删除或改名的文件在已有副本里永久残留。
|
|
21
|
+
// 一次改名 + 一次移出即可在三平台副本各留 8 条残留,且残留会让安装副本跑自身回归套件报
|
|
22
|
+
// 308/309(失败项的失败信息逐条指向残留文件),而权威源同一命令 309/309——落差纯由残留造成。
|
|
23
|
+
//
|
|
24
|
+
// 镜像白名单(唯一允许删除的路径集合,逐条由本次生成动作定义):本次真实 copyTree 的目标根
|
|
25
|
+
// `<skillRoot>/<name>`,其中 <name> ∈ 权威源 `skills/` 下的 `flow-comet*` 目录清单。
|
|
26
|
+
// 命名空间(flow-comet* 前缀)与安装位置(平台技能根)共同构成归属判据;白名单之外的一切路径
|
|
27
|
+
// **永不触碰**。两条 fail-closed 边界(不删,但必须可见):
|
|
28
|
+
// · 整个技能目录不在权威源清单里(`<skillRoot>/flow-comet-fork` 一类):安装器没有生成清单,
|
|
29
|
+
// 用户自建的同命名空间目录与「权威源已移除的技能」在结构上不可区分 ⇒ 归属不可判定,保留;
|
|
30
|
+
// 该形态由显式 `--purge` 处置。
|
|
31
|
+
// · `.claude/rules`(同为 copyTree 目标):路径不含命名空间,无法与用户自有规则文件区分 ⇒
|
|
32
|
+
// 不纳入删除面(同上,`--purge` 处置)。
|
|
33
|
+
//
|
|
34
|
+
// 删除判据只有一条:**权威源同一相对路径上不存在同类型条目**。fail-closed 情形逐条打印、绝不静默:
|
|
35
|
+
// · **镜像根自身**是符号链接/junction(不跟随、不删除——条目层检查拦不住根级穿越:根为链接时
|
|
36
|
+
// `readdirSync` 会跟随进链接目标,删除动作落在**项目之外**,而播报打印的是项目内的表象路径);
|
|
37
|
+
// · **镜像根的真实路径越出目标项目根**(realpath 包含性判据——根或其任一祖先段为链接时,
|
|
38
|
+
// 词法路径仍显示在项目内,只有解析后才能证否;无法证明「在项目内」一律不删);
|
|
39
|
+
// · 条目是符号链接(不跟随、不删除——防穿越到目标项目之外);
|
|
40
|
+
// · 权威源同路径在场但类型不同(文件 ↔ 目录):归属不可判定,留给复制阶段的既有语义;
|
|
41
|
+
// · 目录清理后仍非空(其中含非残留内容 = 用户文件)→ 只删残留子孙,目录本身保留。
|
|
42
|
+
// 幂等:重复运行零残留可删 ⇒ 零输出、零报错;删除动作逐条打印(输出可核对)。
|
|
43
|
+
/**
|
|
44
|
+
* realpath 解析:返回真实路径,**解析不出即 null**(路径不存在 / 悬空链接 / 权限或 IO 故障一视同仁)。
|
|
45
|
+
* 与 lstatIfExists「访问类故障原样抛出」的取舍不同——本函数只服务**删除前的包含性判据**,
|
|
46
|
+
* 调用方约定为 fail-closed(null ⇒ 不删并打印原因):解析不出就**证明不了**在项目内,
|
|
47
|
+
* 此时中止安装比静默放行危险,而静默放行又比不删危险。
|
|
48
|
+
* 优先 `realpathSync.native`:Windows 上 libuv 实现不展开 8.3 短名(实测 `LONGYI~1` 形态),
|
|
49
|
+
* 而词法形态不同的两侧直接比较会把项目内路径误判为越界——本仓既有同判据(dsh-bridge 的
|
|
50
|
+
* 包含性检查)已登记该平台事实,此处沿用同一取值口径(失败方向仍是 fail-closed:误判 = 不删)。
|
|
51
|
+
*/
|
|
52
|
+
function realpathOrNull(target) {
|
|
53
|
+
try {
|
|
54
|
+
return fs.realpathSync.native(target);
|
|
55
|
+
} catch {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* 真实路径包含性:`target` 解析后的真实路径是否仍在 `root` 解析后的真实路径之内。
|
|
62
|
+
* 两侧都先 realpath——根或祖先段是链接时词法路径会骗人(Windows 8.3 短名 / 平台临时目录链接同理)。
|
|
63
|
+
* 任一解析失败 ⇒ false(fail-closed);`path.relative` 的 `..` 前缀与绝对路径都判越界。
|
|
64
|
+
*/
|
|
65
|
+
function isRealPathInside(target, root) {
|
|
66
|
+
const targetReal = realpathOrNull(target);
|
|
67
|
+
const rootReal = realpathOrNull(root);
|
|
68
|
+
if (targetReal === null || rootReal === null) return false;
|
|
69
|
+
const rel = path.relative(rootReal, targetReal);
|
|
70
|
+
return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function pruneMirrorEntries(srcRoot, dstRoot, report, projectRoot) {
|
|
74
|
+
// 根级 fail-closed(**进入递归/枚举之前**):镜像根自身是链接 ⇒ 不跟随;真实路径越出目标项目根
|
|
75
|
+
// ⇒ 不删。条目层的 entry.isSymbolicLink() 只覆盖根以下的条目,拦不住根级的符号链接/junction。
|
|
76
|
+
const rootStat = lstatIfExists(dstRoot);
|
|
77
|
+
if (rootStat === null) return; // 镜像根不在场(首次安装)——无残留可清
|
|
78
|
+
if (rootStat.isSymbolicLink()) {
|
|
79
|
+
report.skipped.push(`${dstRoot}(镜像根是符号链接/junction——不跟随、不删除,防穿越到目标项目之外)`);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
if (!isRealPathInside(dstRoot, projectRoot)) {
|
|
83
|
+
report.skipped.push(`${dstRoot}(真实路径 ${realpathOrNull(dstRoot) || '无法解析'} 越出目标项目根 ${realpathOrNull(projectRoot) || '无法解析'}——归属不可判定,不删)`);
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const entries = readdirIfExists(dstRoot);
|
|
87
|
+
if (entries === null) return; // TOCTOU:lstat 后、枚举前被移走——无残留可清(判定同 lstatIfExists 口径)
|
|
88
|
+
for (const entry of entries) {
|
|
89
|
+
const srcPath = path.join(srcRoot, entry.name);
|
|
90
|
+
const dstPath = path.join(dstRoot, entry.name);
|
|
91
|
+
if (entry.isSymbolicLink()) {
|
|
92
|
+
report.skipped.push(`${dstPath}(符号链接——不跟随、不删除)`);
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
const srcStat = lstatIfExists(srcPath);
|
|
96
|
+
const isDir = entry.isDirectory();
|
|
97
|
+
if (srcStat && isDir === srcStat.isDirectory()) {
|
|
98
|
+
// 权威源在场且同类型:目录递归下探,文件保留(内容由 copyTree 覆盖)
|
|
99
|
+
if (isDir) pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
if (srcStat) {
|
|
103
|
+
report.skipped.push(`${dstPath}(权威源同路径类型不同——归属不可判定,不删)`);
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
if (isDir) {
|
|
107
|
+
// 权威源无该目录 ⇒ 其中全部条目都属残留:先递归清空,再连同目录本身移除
|
|
108
|
+
pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
|
|
109
|
+
const left = readdirIfExists(dstPath);
|
|
110
|
+
if (left === null) continue; // 递归中已被移除(与其祖先同批)
|
|
111
|
+
if (left.length > 0) {
|
|
112
|
+
report.skipped.push(`${dstPath}(清理后仍非空——保留其中非残留内容)`);
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
fs.rmdirSync(dstPath);
|
|
116
|
+
report.removed.push(dstPath);
|
|
117
|
+
continue;
|
|
118
|
+
}
|
|
119
|
+
if (entry.isFile()) {
|
|
120
|
+
fs.rmSync(dstPath, { force: true });
|
|
121
|
+
report.removed.push(dstPath);
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
report.skipped.push(`${dstPath}(既非普通文件也非目录——不删)`);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* 平台镜像清理总入口:对本次安装的每个技能镜像根(`<skillRoot>/<name>` ← `skills/<name>`)
|
|
130
|
+
* 做定向清理,逐条打印结果。无残留时零输出(幂等可核对:重复运行不再打印清理项);
|
|
131
|
+
* fail-closed 保留项以警告逐条打印——保留是**可见的决定**,不是静默跳过。
|
|
132
|
+
* `projectRoot` = 本次安装的目标项目根:**删除面的包含性上界**(镜像根 realpath 必须落在其内,
|
|
133
|
+
* 见 pruneMirrorEntries 的根级判据)。
|
|
134
|
+
*/
|
|
135
|
+
export function cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, projectRoot) {
|
|
136
|
+
const report = { removed: [], skipped: [] };
|
|
137
|
+
for (const name of skillNames) {
|
|
138
|
+
pruneMirrorEntries(path.join(skillsSrc, name), path.join(skillRoot, name), report, projectRoot);
|
|
139
|
+
}
|
|
140
|
+
if (report.removed.length > 0) {
|
|
141
|
+
console.log(`[flow-comet] 镜像清理: 已删除 ${report.removed.length} 项(权威源已不存在的生成物)`);
|
|
142
|
+
for (const p of report.removed) {
|
|
143
|
+
console.log(` - 已删除: ${p}`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
if (report.skipped.length > 0) {
|
|
147
|
+
console.warn(`[flow-comet] 警告: 镜像清理保留 ${report.skipped.length} 项(fail-closed——无法判定归属即不删):`);
|
|
148
|
+
for (const p of report.skipped) {
|
|
149
|
+
console.warn(` - 保留: ${p}`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|