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.
Files changed (106) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +21 -3
  3. package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
  4. package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
  5. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +8 -2
  6. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  7. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +180 -6
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +69 -18878
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +29 -5
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1053 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
  15. package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
  16. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
  17. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
  18. package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
  19. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +817 -0
  20. package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
  21. package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
  22. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
  23. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
  24. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +618 -0
  25. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  26. package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +756 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1235 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +384 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +714 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +204 -0
  35. package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
  36. package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +179 -0
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +714 -0
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +123 -0
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
  46. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
  47. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +249 -0
  48. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1505 -0
  49. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
  51. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1248 -0
  52. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
  53. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2493 -0
  54. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +214 -2
  55. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +976 -0
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1398 -0
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1367 -0
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1492 -0
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
  69. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  70. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
  71. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +59 -7559
  72. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
  73. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +223 -2476
  74. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
  75. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
  76. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  77. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  78. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  79. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  80. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  81. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  82. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  83. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  84. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  85. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  86. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  87. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  88. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  89. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  90. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  91. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  92. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  93. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  94. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  95. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  96. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  97. package/README.md +52 -69
  98. package/package.json +3 -2
  99. package/scripts/dsh-bridge.mjs +2 -2
  100. package/scripts/lib/installer-cleanup.mjs +152 -0
  101. package/scripts/lib/installer-flowkit.mjs +159 -0
  102. package/scripts/lib/installer-hooks.mjs +363 -0
  103. package/scripts/lib/installer-loader.mjs +220 -0
  104. package/scripts/lib/installer-migrate.mjs +236 -0
  105. package/scripts/lib/installer-platforms.mjs +314 -0
  106. package/scripts/prepare-env.mjs +21 -1313
@@ -7,6 +7,14 @@
7
7
  * 这是 flow-comet 的**安装器**:适用于新项目安装 flow-comet、e2e 验证载体准备、
8
8
  * 源仓库自我改进 worktree 环境准备。
9
9
  *
10
+ * 模块边界(本文件 = 入口薄壳:只做 CLI 解析、命令编排与输出收口;判据与实现落在 scripts/lib/):
11
+ * installer-platforms 平台描述符表 / 仓库根与权威源常量 / 整树复制与平台路径替换
12
+ * installer-migrate 运行时文件位置迁移 + 路径存在性探测原语(三处调用方共用)
13
+ * installer-hooks 配置注入(settings.local.json / .codex / AGENTS.md 托管区)+ .gitignore 纳管
14
+ * installer-loader 桥接 loader 版本比对 / cordis.patch.yml 托管块 / 托管块移除边界
15
+ * installer-cleanup 生成物镜像目录的定向清理(fail-closed 删除判据)
16
+ * installer-flowkit flow-kit 上游快照获取链路(非破坏)
17
+ *
10
18
  * 多平台(1.4.0 / dsh 扩展):平台描述符表 PLATFORMS 驱动——claude-code(默认,现状语义)
11
19
  * + codex + dsh(新增)。平台差异全部封装在描述符条目内:技能安装位置 skillRoot /
12
20
  * SKILL 命令路径替换 pathReplacements / hook 注入 installHooks
@@ -54,8 +62,8 @@
54
62
  * .gitignore 纳管取保守策略:既有条目一律保留,仅缺失时追加 `.flow-comet/` 条目。
55
63
  *
56
64
  * 用法:node scripts/prepare-env.mjs [--target <dir>] [--platform <claude-code|codex|dsh|claude-code,dsh|all>] [--purge --yes]
57
- * --target 缺省 = 当前工作目录(cwd)。脚本自身定位:__dirname 上一级 = 仓库根
58
- * (scripts/ 与 .flow-comet/ 同级),据此解析权威源。
65
+ * --target 缺省 = 当前工作目录(cwd)。仓库根与权威源路径由 scripts/lib/installer-platforms.mjs
66
+ * 解析(仓库根 / 权威源 / 平台表三者的单一来源——本文件不自行推导)。
59
67
  * --platform 显式指定平台:单平台 / 逗号分隔多平台(claude-code,codex,dsh)/
60
68
  * all(全部平台,安装顺序 = PLATFORMS 表顺序);未知平台报错(旧 both 语义已移除——
61
69
  * 多平台用逗号列表或 all);缺省走选择链:
@@ -71,289 +79,20 @@
71
79
  */
72
80
  import fs from 'node:fs';
73
81
  import path from 'node:path';
74
- import os from 'node:os';
75
82
  import { execFileSync } from 'node:child_process';
76
83
  import { createInterface } from 'node:readline/promises';
77
- import { fileURLToPath, pathToFileURL } from 'node:url';
78
-
79
- const __dirname = path.dirname(fileURLToPath(import.meta.url));
80
- const REPO_ROOT = path.resolve(__dirname, '..');
81
- // 权威源根(含 skills/ 与 rules/——目录结构与安装副本 .claude/ 对称:<根>/skills/flow-comet/)
82
- const BUNDLE_DRAFTS = path.join(REPO_ROOT, '.flow-comet');
83
-
84
- // ---------- 运行时文件位置迁移(旧命名空间 → 新命名空间) ----------
85
- //
86
- // 【过渡性模块——有明确退役条件,不是永久耦合】
87
- // 本模块存在的唯一理由:让已安装项目把状态文件从旧命名空间搬到新命名空间,避免破坏性变更
88
- // 导致用户进行中的流程状态丢失。它**只在安装/升级时执行一次**,从不进入任何日常运行路径
89
- // (写入守卫、工作流脚本、协议解析均已完全不含对旧命名空间的感知)。
90
- //
91
- // 因此这里的 `.comet` 字面量是**迁移源**,不是 flow-comet 的命名归属——它标记的是"要从哪里
92
- // 搬走",而非"我们是谁"。这是任何破坏性变更都需要的过渡桥(同"改名迁移脚本必须知道旧表名")。
93
- //
94
- // **退役条件**(满足任一即可整体删除本模块及其常量):
95
- // ① 下一个破坏性版本发布时——迁移公告期结束(建议至少覆盖一个完整的 minor 周期,让下游
96
- // 项目有时间升级);
97
- // ② 或:连续多次安装运行中迁移报告**全部为「已跳过」**(说明已知项目均已迁移完毕)。
98
- // 判据取证:每次安装都会打印迁移明细(已迁移 / 已跳过);长期全为「已跳过」即为退役信号。
99
- //
100
- // 位置迁移白名单(单一来源):目标项目的 `.comet/` 是三方共占目录——flow-comet 运行时文件
101
- // + Comet 资产(`runs/`、`config.yaml` 等)+ 用户自有文件(`*.bak-*` 等)。只有下表列出的
102
- // 文件属 flow-comet 运行时域,其余一律原位不动(不搬迁、不删除、不改写)——整目录搬迁或
103
- // 前缀正则匹配都会越界处置非 flow-comet 资产。新增运行时文件时必须同步本表。
104
- const LEGACY_RUNTIME_DIR = '.comet';
105
- const RUNTIME_DIR = '.flow-comet';
106
- const RUNTIME_FILE_MIGRATIONS = [
107
- { name: 'flow-comet-state.json', validateJson: true },
108
- ];
109
-
110
- // comet-hook-guard 的 command 特征(用于识别"已管理的 hook 命令",注入时替换避免重复)
111
- const MANAGED_HOOK_COMMAND_MARKER = 'comet-hook-guard.mjs';
112
-
113
- // ---------- hook 命令项目根锚定(单一事实来源) ----------
114
- // Claude Code 运行 hook 时注入 CLAUDE_PROJECT_DIR 环境变量(值 = 项目根绝对路径,官方 hooks
115
- // 文档契约)。变量名是唯一事实来源;命令形态**全平台统一**为 POSIX/bash 词形
116
- // (`${VAR}` + 正斜杠——CC 在所有平台含 Windows 都以 /bin/bash -c 执行 hook 命令),
117
- // 由 projectRootGuardScriptRef 派生,不按宿主 OS 分叉。
118
- const PROJECT_ROOT_ENV_VAR = 'CLAUDE_PROJECT_DIR';
119
84
 
120
- // hook 命令加整体外层引号(2026-09-10 演进——原「不加引号」取舍的前提是识别函数按空白分词
121
- // 判等、外层引号会并入 token 使 basename 失配;识别函数已演进为容忍引号,故放开):未加
122
- // 引号时,含空格的项目根路径在变量展开后会被词法分词切断(静默失效,与反斜杠转义同类)。
123
- function projectRootGuardScriptRef(rootDirName) {
124
- // CC 全平台以 /bin/bash -c 执行 hook 命令(含 Windows——Git Bash 语义),并注入
125
- // CLAUDE_PROJECT_DIR 环境变量;故统一 POSIX 形态:${VAR} 花括号词形(CC 自身亦做该词形
126
- // 插值——字符串替换,双保险)+ 正斜杠路径(反斜杠在 bash 词法里会被当转义吞掉,如 \. \f)。
127
- // 整体加引号:含空格的项目根路径不因词法分词断裂;识别层容忍引号(isManagedHookCommand
128
- // 去引号后取 basename 判等),幂等升级不受影响。
129
- const segments = [rootDirName, 'skills', 'flow-comet', 'scripts', MANAGED_HOOK_COMMAND_MARKER];
130
- return `"\${${PROJECT_ROOT_ENV_VAR}}/${segments.join('/')}"`;
131
- }
132
-
133
- // AGENTS.md 托管区标记(Codex/dsh 平台 rules 注入共用——幂等替换边界,任一平台卸载可清)
134
- const MANAGED_AGENTS_START = '<!-- Managed by flow-comet prepare-env -->';
135
- const MANAGED_AGENTS_END = '<!-- /Managed by flow-comet prepare-env -->';
136
-
137
- // $DSH_HOME/cordis.patch.yml 托管块标记(dsh 平台 home patch 注入——幂等替换边界;
138
- // 参照本机既有惯例:# --- dsh-skin managed --- ... # --- end dsh-skin managed ---)
139
- const MANAGED_CORDIS_START = '# --- flow-comet managed ---';
140
- const MANAGED_CORDIS_END = '# --- end flow-comet managed ---';
141
-
142
- // ---------- 平台描述符表(单一来源——新增平台 = 描述符条目 + 安装/清理函数,main 零改动) ----------
143
- // D6:flow-kit 永不纳入清理域——下述各平台 purge 清单均不含 <target>/flow-kit/(含 --purge --yes);
144
- // 它不是本安装器的生成物域(ADR-008),由安装器首次创建的 flow-kit 残留属预期。
145
-
146
- const PLATFORMS = {
147
- 'claude-code': {
148
- label: 'Claude Code',
149
- // 技能安装根(相对 target;与权威源 .claude 形态一致——零路径替换)
150
- skillRoot: (target) => path.join(target, '.claude', 'skills'),
151
- // 平台路径替换表(from 正则 → to):claude-code 为空 = 权威源即目标形态
152
- pathReplacements: [],
153
- // hook 注入:settings.local.json 读-合并-写(保留既有字段;matcher Write|Edit)
154
- installHooks(target, stats) {
155
- const claudeDir = path.join(target, '.claude');
156
- fs.mkdirSync(claudeDir, { recursive: true });
157
- stats.dirs++;
158
- const settings = injectSettingsHook(claudeDir);
159
- const injected = !!(settings.hooks && settings.hooks.PreToolUse);
160
- stats.files++;
161
- console.log(`[flow-comet] settings.local.json ${injected ? '注入完成(保留既有字段)' : '已生成'}`);
162
- },
163
- // rules 注入:.claude/rules/ 整树复制(自动加载 markdown 指令)
164
- installRules(target, stats) {
165
- const rulesSrc = path.join(BUNDLE_DRAFTS, 'rules');
166
- if (fs.existsSync(rulesSrc)) {
167
- copyTree(rulesSrc, path.join(target, '.claude', 'rules'), stats);
168
- }
169
- },
170
- // purge 清理:整删 .claude/(CC 的 .claude 即 flow-comet 生成物域);返回删除清单供打印
171
- purge(target) {
172
- const claudeDir = path.join(target, '.claude');
173
- const removed = [];
174
- if (fs.existsSync(claudeDir)) {
175
- for (const entry of fs.readdirSync(claudeDir)) {
176
- removed.push(path.join(claudeDir, entry));
177
- }
178
- fs.rmSync(claudeDir, { recursive: true, force: true });
179
- }
180
- return removed;
181
- },
182
- // 覆盖清单描述(默认非破坏:只覆盖生成物)
183
- overwriteDescription(target) {
184
- return [
185
- path.join(target, '.claude', 'rules'),
186
- path.join(target, '.claude', 'settings.local.json') + '(注入方式:保留既有字段,仅更新 hooks.PreToolUse)',
187
- ];
188
- },
189
- },
190
- 'codex': {
191
- label: 'Codex',
192
- // 技能安装根:Codex 自动发现位置($CWD/.agents/skills/ 最高优先)
193
- skillRoot: (target) => path.join(target, '.agents', 'skills'),
194
- // SKILL/GUIDANCE 命令路径平台化替换(权威源保持 .claude 形态,安装时替换)
195
- pathReplacements: [
196
- { from: /\.claude\/skills\/flow-comet\/scripts\//g, to: '.agents/skills/flow-comet/scripts/' },
197
- ],
198
- // hook 注入:.codex/hooks.json(顶层 hooks 包裹层 + matcher *)+ config.toml features 启用
199
- installHooks(target, stats) {
200
- const codexDir = path.join(target, '.codex');
201
- injectCodexHook(codexDir, target);
202
- injectCodexConfig(codexDir);
203
- stats.files += 2;
204
- console.log('[flow-comet] .codex/hooks.json + config.toml 注入完成(hooks 启用,保留既有字段)');
205
- },
206
- // rules 注入:AGENTS.md 托管区内联(Codex 指令唯一自动加载路径;.codex/rules/ 是命令批准规则目录,不混用;
207
- // 注入函数与托管区标记 codex/dsh 共用——任一平台卸载可清,另一平台重装恢复)
208
- installRules(target, stats) {
209
- if (injectManagedRules(target, stats)) {
210
- console.log('[flow-comet] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
211
- }
212
- },
213
- // purge 清理:只清 flow-comet 技能(.agents/ 为多工具共享位置——非 flow-comet 条目保留)
214
- // + .codex/hooks.json 托管条目(保留用户条目)+ AGENTS.md 托管区(保留文件本身)
215
- purge(target) {
216
- const removed = [];
217
- const agentsSkillsDir = path.join(target, '.agents', 'skills');
218
- if (fs.existsSync(agentsSkillsDir)) {
219
- for (const entry of fs.readdirSync(agentsSkillsDir)) {
220
- if (!/^flow-comet/.test(entry)) continue;
221
- const managed = path.join(agentsSkillsDir, entry);
222
- removed.push(managed);
223
- fs.rmSync(managed, { recursive: true, force: true });
224
- }
225
- }
226
- const hooksPath = path.join(target, '.codex', 'hooks.json');
227
- if (fs.existsSync(hooksPath)) {
228
- removed.push(hooksPath + '(移除托管 hook 条目,保留用户条目)');
229
- // 移除托管条目(重建流程随后重新注入新托管条目——purge = 移除旧生成物后重建)
230
- removeManagedCodexHooks(path.join(target, '.codex'));
231
- }
232
- const agentsPath = path.join(target, 'AGENTS.md');
233
- if (fs.existsSync(agentsPath)) {
234
- const content = fs.readFileSync(agentsPath, 'utf8');
235
- if (content.includes(MANAGED_AGENTS_START)) {
236
- removed.push(agentsPath + '(托管区)');
237
- const stripped = stripManagedBlock(content, MANAGED_AGENTS_START, MANAGED_AGENTS_END);
238
- fs.writeFileSync(agentsPath, stripped.trim() + '\n', 'utf8');
239
- }
240
- }
241
- return removed;
242
- },
243
- // 覆盖清单描述(默认非破坏:只覆盖生成物)
244
- overwriteDescription(target) {
245
- return [
246
- path.join(target, 'AGENTS.md') + '(托管区注入:保留托管区外用户内容)',
247
- path.join(target, '.codex', 'hooks.json') + '(注入方式:保留既有字段,仅更新托管 hook 条目)',
248
- path.join(target, '.codex', 'config.toml') + '(注入方式:补 [features] hooks 启用键)',
249
- ];
250
- },
251
- },
252
- 'dsh': {
253
- label: 'DeepSeek Harness',
254
- // 技能安装根:dsh 项目级 skill 发现(rank 100 自动发现,免重启;未安装该目录的项目不可见该 skill)
255
- skillRoot: (target) => path.join(target, '.dsh', 'skills'),
256
- // SKILL/GUIDANCE 命令路径平台化替换(权威源保持 .claude 形态,安装时替换)
257
- pathReplacements: [
258
- { from: /\.claude\/skills\/flow-comet\/scripts\//g, to: '.dsh/skills/flow-comet/scripts/' },
259
- ],
260
- // hook 注入:全局挂载桥接 loader($DSH_HOME/plugins/ 复制 + cordis.patch.yml 托管块——
261
- // 所有 profile 生效;$DSH_HOME 解析 = 显式 DSH_HOME > ~/.dsh)
262
- installHooks(target, stats) {
263
- const dshHome = resolveDshHome();
264
- const pluginsDir = path.join(dshHome, 'plugins');
265
- const loaderSrc = path.join(REPO_ROOT, 'scripts', 'dsh-bridge.mjs');
266
- const loaderDst = path.join(pluginsDir, 'dsh-flow-comet-bridge.mjs');
267
- if (fs.existsSync(loaderSrc)) {
268
- fs.mkdirSync(pluginsDir, { recursive: true });
269
- // 覆盖前版本比对明示(版本戳标记契约):输出首次安装/升级/降级/版本一致之一;
270
- // 任一侧提取失败只告警不中断——覆盖照常执行(幂等语义不变)
271
- reportLoaderVersionTransition(loaderSrc, loaderDst);
272
- fs.copyFileSync(loaderSrc, loaderDst);
273
- stats.files++;
274
- console.log('[flow-comet] 桥接 loader 已复制到 $DSH_HOME/plugins/dsh-flow-comet-bridge.mjs');
275
- injectDshCordisPatch(dshHome, loaderDst);
276
- stats.files++;
277
- console.log('[flow-comet] $DSH_HOME/cordis.patch.yml 托管块注入完成(读-合并-写,保留既有块)');
278
- } else {
279
- // 容错:scripts/dsh-bridge.mjs 由并行任务新建——源缺失时 WARN 跳过 loader 复制
280
- // **并跳过 cordis.patch.yml 托管块注入**(避免注入指向不存在文件的 file:// 引用,
281
- // 导致 dsh 每次启动尝试加载不存在的插件);仍完成其余安装
282
- // (AGENTS.md 托管区 / skills 复制照常)
283
- console.warn(
284
- '[flow-comet] 警告: scripts/dsh-bridge.mjs 不存在——跳过 loader 复制与 cordis.patch.yml 托管块注入' +
285
- '(dsh 桥接拦截暂不生效,待源文件就位后重跑 prepare-env)'
286
- );
287
- }
288
- },
289
- // rules 注入:AGENTS.md 托管区(与 codex 共用注入函数与托管区标记——任一平台卸载可清)
290
- installRules(target, stats) {
291
- if (injectManagedRules(target, stats)) {
292
- console.log('[flow-comet] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
293
- }
294
- },
295
- // purge 清理:项目级 .dsh/skills 下全部 flow-comet* 技能(.dsh/skills 为 dsh 技能位置——
296
- // 非 flow-comet 条目保留,与 codex purge 同语义)+ 空 .dsh 目录 + AGENTS.md 托管区
297
- // (保留文件与用户内容)+ $DSH_HOME/cordis.patch.yml 托管块 + plugins/ loader
298
- // (写 home 的敏感面——purge 需 --yes 显式确认)
299
- purge(target) {
300
- const removed = [];
301
- const dshSkillsDir = path.join(target, '.dsh', 'skills');
302
- if (fs.existsSync(dshSkillsDir)) {
303
- for (const entry of fs.readdirSync(dshSkillsDir)) {
304
- if (!/^flow-comet/.test(entry)) continue;
305
- const managed = path.join(dshSkillsDir, entry);
306
- removed.push(managed);
307
- fs.rmSync(managed, { recursive: true, force: true });
308
- }
309
- }
310
- // 空目录清理:仅删空目录(skills 下无剩余条目 / .dsh 下无其它内容时)——有内容则保留
311
- if (fs.existsSync(dshSkillsDir) && fs.readdirSync(dshSkillsDir).length === 0) {
312
- fs.rmdirSync(dshSkillsDir);
313
- removed.push(dshSkillsDir);
314
- }
315
- const dshDir = path.join(target, '.dsh');
316
- if (fs.existsSync(dshDir) && fs.readdirSync(dshDir).length === 0) {
317
- fs.rmdirSync(dshDir);
318
- removed.push(dshDir);
319
- }
320
- const agentsPath = path.join(target, 'AGENTS.md');
321
- if (fs.existsSync(agentsPath)) {
322
- const content = fs.readFileSync(agentsPath, 'utf8');
323
- if (content.includes(MANAGED_AGENTS_START)) {
324
- removed.push(agentsPath + '(托管区)');
325
- const stripped = stripManagedBlock(content, MANAGED_AGENTS_START, MANAGED_AGENTS_END);
326
- fs.writeFileSync(agentsPath, stripped.trim() + '\n', 'utf8');
327
- }
328
- }
329
- // home patch 托管块移除 + loader 删除($DSH_HOME——写 home 的敏感面)
330
- const dshHome = resolveDshHome();
331
- for (const entry of removeDshCordisPatch(dshHome)) {
332
- removed.push(entry);
333
- }
334
- const loaderPath = path.join(dshHome, 'plugins', 'dsh-flow-comet-bridge.mjs');
335
- if (fs.existsSync(loaderPath)) {
336
- removed.push(loaderPath + '($DSH_HOME/plugins/ loader)');
337
- fs.rmSync(loaderPath, { force: true });
338
- // 全局挂载语义警示:loader 位于 $DSH_HOME(所有 profile / 所有项目共享)——
339
- // 任一项目 purge 都会连带移除,其它已安装 flow-comet 的项目将静默失去拦截
340
- console.warn(
341
- '[flow-comet] 全局桥接 loader 被移除,其它已安装 flow-comet 的项目将停止拦截' +
342
- '($DSH_HOME 全局挂载——如需恢复请重跑 prepare-env --platform dsh)'
343
- );
344
- }
345
- return removed;
346
- },
347
- // 覆盖清单描述(默认非破坏:只覆盖生成物;声明写 home 的敏感面)
348
- overwriteDescription(target) {
349
- return [
350
- path.join(target, 'AGENTS.md') + '(托管区注入:保留托管区外用户内容)',
351
- path.join(resolveDshHome(), 'cordis.patch.yml') + '(托管块注入:保留 dsh-skin 等既有块)',
352
- path.join(resolveDshHome(), 'plugins', 'dsh-flow-comet-bridge.mjs') + '($DSH_HOME 全局挂载——安装器写 home 目录的敏感面)',
353
- ];
354
- },
355
- },
356
- };
85
+ import { cleanStaleMirrorEntries } from './lib/installer-cleanup.mjs';
86
+ import { ensureFlowKit } from './lib/installer-flowkit.mjs';
87
+ import { manageGitignore } from './lib/installer-hooks.mjs';
88
+ import { migrateRuntimeFiles } from './lib/installer-migrate.mjs';
89
+ import {
90
+ BUNDLE_DRAFTS,
91
+ PLATFORMS,
92
+ REPO_ROOT,
93
+ applyPathReplacements,
94
+ copyTree,
95
+ } from './lib/installer-platforms.mjs';
357
96
 
358
97
  // ---------- 平台选择 ----------
359
98
 
@@ -570,930 +309,6 @@ async function resolvePlatform(target, platformArg) {
570
309
  return [PLATFORMS[probe ?? 'claude-code']];
571
310
  }
572
311
 
573
- // ---------- 文件工具 ----------
574
-
575
- /** 递归收集 srcDir 下所有目录与文件的绝对路径 */
576
- function collect(srcDir) {
577
- const dirs = [];
578
- const files = [];
579
- (function walk(dir) {
580
- for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
581
- const abs = path.join(dir, entry.name);
582
- if (entry.isDirectory()) {
583
- dirs.push(abs);
584
- walk(abs);
585
- } else if (entry.isFile()) {
586
- files.push(abs);
587
- }
588
- }
589
- })(srcDir);
590
- return { dirs, files };
591
- }
592
-
593
- /** 整树复制 srcDir → dstRoot(保持相对结构),计数写入 stats */
594
- function copyTree(srcDir, dstRoot, stats) {
595
- fs.mkdirSync(dstRoot, { recursive: true });
596
- stats.dirs++;
597
- const { dirs, files } = collect(srcDir);
598
- for (const d of dirs) {
599
- fs.mkdirSync(path.join(dstRoot, path.relative(srcDir, d)), { recursive: true });
600
- stats.dirs++;
601
- }
602
- for (const f of files) {
603
- fs.copyFileSync(f, path.join(dstRoot, path.relative(srcDir, f)));
604
- stats.files++;
605
- }
606
- }
607
-
608
- /**
609
- * 平台路径替换:对复制后的技能包内全部 .md 文件(SKILL/GUIDANCE/reference)做命令路径替换。
610
- * 权威源保持 .claude 形态;claude-code 平台替换表为空(零改动,可复现性 diff 不变)。
611
- * 幂等:同平台重复安装替换结果一致。
612
- */
613
- function applyPathReplacements(root, replacements) {
614
- if (!replacements || replacements.length === 0) return 0;
615
- let replaced = 0;
616
- const { files } = collect(root);
617
- for (const f of files) {
618
- if (!f.endsWith('.md')) continue;
619
- let content = fs.readFileSync(f, 'utf8');
620
- const original = content;
621
- for (const { from, to } of replacements) {
622
- content = content.replace(from, to);
623
- }
624
- if (content !== original) {
625
- fs.writeFileSync(f, content, 'utf8');
626
- replaced++;
627
- }
628
- }
629
- return replaced;
630
- }
631
-
632
- /**
633
- * readdir(withFileTypes):仅「该路径确实不存在」返回 null——判定与 lstatIfExists 同口径
634
- * (见 isMissingPathError:只有 ENOENT / ENOTDIR 算不存在,访问类故障原样抛出)。
635
- * 供镜像清理复用:把「目录不可枚举」与「目录为空」两个分支分开,避免清理判定深嵌 try/catch。
636
- */
637
- function readdirIfExists(dir) {
638
- try {
639
- return fs.readdirSync(dir, { withFileTypes: true });
640
- } catch (err) {
641
- if (isMissingPathError(err)) return null;
642
- throw err;
643
- }
644
- }
645
-
646
- // ---------- 生成物镜像目录的定向清理(升级路径残留) ----------
647
- //
648
- // 缺陷形态(实测):copyTree 只覆盖、不删除 ⇒ 权威源里已删除或改名的文件在已有副本里永久残留。
649
- // 一次改名 + 一次移出即可在三平台副本各留 8 条残留,且残留会让安装副本跑自身回归套件报
650
- // 308/309(失败项的失败信息逐条指向残留文件),而权威源同一命令 309/309——落差纯由残留造成。
651
- //
652
- // 镜像白名单(唯一允许删除的路径集合,逐条由本次生成动作定义):本次真实 copyTree 的目标根
653
- // `<skillRoot>/<name>`,其中 <name> ∈ 权威源 `skills/` 下的 `flow-comet*` 目录清单。
654
- // 命名空间(flow-comet* 前缀)与安装位置(平台技能根)共同构成归属判据;白名单之外的一切路径
655
- // **永不触碰**。两条 fail-closed 边界(不删,但必须可见):
656
- // · 整个技能目录不在权威源清单里(`<skillRoot>/flow-comet-fork` 一类):安装器没有生成清单,
657
- // 用户自建的同命名空间目录与「权威源已移除的技能」在结构上不可区分 ⇒ 归属不可判定,保留;
658
- // 该形态由显式 `--purge` 处置。
659
- // · `.claude/rules`(同为 copyTree 目标):路径不含命名空间,无法与用户自有规则文件区分 ⇒
660
- // 不纳入删除面(同上,`--purge` 处置)。
661
- //
662
- // 删除判据只有一条:**权威源同一相对路径上不存在同类型条目**。fail-closed 情形逐条打印、绝不静默:
663
- // · **镜像根自身**是符号链接/junction(不跟随、不删除——条目层检查拦不住根级穿越:根为链接时
664
- // `readdirSync` 会跟随进链接目标,删除动作落在**项目之外**,而播报打印的是项目内的表象路径);
665
- // · **镜像根的真实路径越出目标项目根**(realpath 包含性判据——根或其任一祖先段为链接时,
666
- // 词法路径仍显示在项目内,只有解析后才能证否;无法证明「在项目内」一律不删);
667
- // · 条目是符号链接(不跟随、不删除——防穿越到目标项目之外);
668
- // · 权威源同路径在场但类型不同(文件 ↔ 目录):归属不可判定,留给复制阶段的既有语义;
669
- // · 目录清理后仍非空(其中含非残留内容 = 用户文件)→ 只删残留子孙,目录本身保留。
670
- // 幂等:重复运行零残留可删 ⇒ 零输出、零报错;删除动作逐条打印(输出可核对)。
671
- /**
672
- * realpath 解析:返回真实路径,**解析不出即 null**(路径不存在 / 悬空链接 / 权限或 IO 故障一视同仁)。
673
- * 与 lstatIfExists「访问类故障原样抛出」的取舍不同——本函数只服务**删除前的包含性判据**,
674
- * 调用方约定为 fail-closed(null ⇒ 不删并打印原因):解析不出就**证明不了**在项目内,
675
- * 此时中止安装比静默放行危险,而静默放行又比不删危险。
676
- * 优先 `realpathSync.native`:Windows 上 libuv 实现不展开 8.3 短名(实测 `LONGYI~1` 形态),
677
- * 而词法形态不同的两侧直接比较会把项目内路径误判为越界——本仓既有同判据(dsh-bridge 的
678
- * 包含性检查)已登记该平台事实,此处沿用同一取值口径(失败方向仍是 fail-closed:误判 = 不删)。
679
- */
680
- function realpathOrNull(target) {
681
- try {
682
- return fs.realpathSync.native(target);
683
- } catch {
684
- return null;
685
- }
686
- }
687
-
688
- /**
689
- * 真实路径包含性:`target` 解析后的真实路径是否仍在 `root` 解析后的真实路径之内。
690
- * 两侧都先 realpath——根或祖先段是链接时词法路径会骗人(Windows 8.3 短名 / 平台临时目录链接同理)。
691
- * 任一解析失败 ⇒ false(fail-closed);`path.relative` 的 `..` 前缀与绝对路径都判越界。
692
- */
693
- function isRealPathInside(target, root) {
694
- const targetReal = realpathOrNull(target);
695
- const rootReal = realpathOrNull(root);
696
- if (targetReal === null || rootReal === null) return false;
697
- const rel = path.relative(rootReal, targetReal);
698
- return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
699
- }
700
-
701
- function pruneMirrorEntries(srcRoot, dstRoot, report, projectRoot) {
702
- // 根级 fail-closed(**进入递归/枚举之前**):镜像根自身是链接 ⇒ 不跟随;真实路径越出目标项目根
703
- // ⇒ 不删。条目层的 entry.isSymbolicLink() 只覆盖根以下的条目,拦不住根级的符号链接/junction。
704
- const rootStat = lstatIfExists(dstRoot);
705
- if (rootStat === null) return; // 镜像根不在场(首次安装)——无残留可清
706
- if (rootStat.isSymbolicLink()) {
707
- report.skipped.push(`${dstRoot}(镜像根是符号链接/junction——不跟随、不删除,防穿越到目标项目之外)`);
708
- return;
709
- }
710
- if (!isRealPathInside(dstRoot, projectRoot)) {
711
- report.skipped.push(`${dstRoot}(真实路径 ${realpathOrNull(dstRoot) || '无法解析'} 越出目标项目根 ${realpathOrNull(projectRoot) || '无法解析'}——归属不可判定,不删)`);
712
- return;
713
- }
714
- const entries = readdirIfExists(dstRoot);
715
- if (entries === null) return; // TOCTOU:lstat 后、枚举前被移走——无残留可清(判定同 lstatIfExists 口径)
716
- for (const entry of entries) {
717
- const srcPath = path.join(srcRoot, entry.name);
718
- const dstPath = path.join(dstRoot, entry.name);
719
- if (entry.isSymbolicLink()) {
720
- report.skipped.push(`${dstPath}(符号链接——不跟随、不删除)`);
721
- continue;
722
- }
723
- const srcStat = lstatIfExists(srcPath);
724
- const isDir = entry.isDirectory();
725
- if (srcStat && isDir === srcStat.isDirectory()) {
726
- // 权威源在场且同类型:目录递归下探,文件保留(内容由 copyTree 覆盖)
727
- if (isDir) pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
728
- continue;
729
- }
730
- if (srcStat) {
731
- report.skipped.push(`${dstPath}(权威源同路径类型不同——归属不可判定,不删)`);
732
- continue;
733
- }
734
- if (isDir) {
735
- // 权威源无该目录 ⇒ 其中全部条目都属残留:先递归清空,再连同目录本身移除
736
- pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
737
- const left = readdirIfExists(dstPath);
738
- if (left === null) continue; // 递归中已被移除(与其祖先同批)
739
- if (left.length > 0) {
740
- report.skipped.push(`${dstPath}(清理后仍非空——保留其中非残留内容)`);
741
- continue;
742
- }
743
- fs.rmdirSync(dstPath);
744
- report.removed.push(dstPath);
745
- continue;
746
- }
747
- if (entry.isFile()) {
748
- fs.rmSync(dstPath, { force: true });
749
- report.removed.push(dstPath);
750
- continue;
751
- }
752
- report.skipped.push(`${dstPath}(既非普通文件也非目录——不删)`);
753
- }
754
- }
755
-
756
- /**
757
- * 平台镜像清理总入口:对本次安装的每个技能镜像根(`<skillRoot>/<name>` ← `skills/<name>`)
758
- * 做定向清理,逐条打印结果。无残留时零输出(幂等可核对:重复运行不再打印清理项);
759
- * fail-closed 保留项以警告逐条打印——保留是**可见的决定**,不是静默跳过。
760
- * `projectRoot` = 本次安装的目标项目根:**删除面的包含性上界**(镜像根 realpath 必须落在其内,
761
- * 见 pruneMirrorEntries 的根级判据)。
762
- */
763
- function cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, projectRoot) {
764
- const report = { removed: [], skipped: [] };
765
- for (const name of skillNames) {
766
- pruneMirrorEntries(path.join(skillsSrc, name), path.join(skillRoot, name), report, projectRoot);
767
- }
768
- if (report.removed.length > 0) {
769
- console.log(`[flow-comet] 镜像清理: 已删除 ${report.removed.length} 项(权威源已不存在的生成物)`);
770
- for (const p of report.removed) {
771
- console.log(` - 已删除: ${p}`);
772
- }
773
- }
774
- if (report.skipped.length > 0) {
775
- console.warn(`[flow-comet] 警告: 镜像清理保留 ${report.skipped.length} 项(fail-closed——无法判定归属即不删):`);
776
- for (const p of report.skipped) {
777
- console.warn(` - 保留: ${p}`);
778
- }
779
- }
780
- }
781
-
782
- // ---------- 运行时文件位置迁移(旧命名空间 .comet/ → 新命名空间 .flow-comet/) ----------
783
-
784
- /**
785
- * 「该路径确实不存在」一类错误的单一判定(迁移探测与 gitignore 纳管共用同一判据——
786
- * 同一语义只有一处实现,改一处即全改,不会分叉):
787
- * - ENOENT:路径缺失;
788
- * - ENOTDIR:路径中某一段不是目录——该路径不可能存在为文件(跨平台等价于「不存在」:
789
- * 同一形态在 Windows 报 ENOENT、在 POSIX 报 ENOTDIR)。
790
- * 其余错误(EACCES / EPERM / EIO 等访问类故障)**不算**「不存在」——把访问故障当成
791
- * 「文件不存在」会让调用方按空内容继续(迁移静默跳过 / gitignore 被截断覆盖),
792
- * 都是静默的数据丢失风险,必须原样抛出并中止。
793
- */
794
- function isMissingPathError(err) {
795
- return Boolean(err) && typeof err === 'object' && (err.code === 'ENOENT' || err.code === 'ENOTDIR');
796
- }
797
-
798
- /**
799
- * lstat 探测:返回 stat 或 null(**不跟随符号链接**——isSymbolicLink() 判定依赖 lstat)。
800
- * 只有「该路径确实不存在」一类错误返回 null(判定见 isMissingPathError);其余错误原样抛出——
801
- * 迁移静默跳过会让安装照常继续并报告「已跳过:旧位置不存在」,用户的旧状态却永远留在旧位置
802
- * (用户以为已迁移)。
803
- */
804
- function lstatIfExists(target) {
805
- try {
806
- return fs.lstatSync(target);
807
- } catch (err) {
808
- if (isMissingPathError(err)) {
809
- return null;
810
- }
811
- throw err;
812
- }
813
- }
814
-
815
- /** 迁移备份文件名时间戳(ISO 串里的 `:` 与 `.` 在 Windows 文件名中非法——统一替换为 `-`)。 */
816
- function migrationTimestamp() {
817
- return new Date().toISOString().replace(/[:.]/g, '-');
818
- }
819
-
820
- /** 逐字节读回并比较;读取失败一律视为不一致(调用方按校验失败处置)。 */
821
- function fileEqualsBytes(filePath, bytes) {
822
- try {
823
- return fs.readFileSync(filePath).equals(bytes);
824
- } catch {
825
- return false;
826
- }
827
- }
828
-
829
- /**
830
- * 迁移前置校验:旧件不存在 → 返回 null(无需迁移);命中边界情形 → 抛错中止(不返回字节)。
831
- * 三种边界一律不静默覆盖或丢弃:
832
- * - 旧件是符号链接 → 不跟随(防穿越到项目外),报错并给人工处置指引
833
- * - 新旧位置并存 → 不覆盖任何一方,报错并列出两处路径供人工判断
834
- * - 内容损坏(validateJson 条目)→ 保留原件未改动,报错并给修复指引
835
- */
836
- function readMigratableRuntimeFile(oldPath, newPath, entry) {
837
- const oldStat = lstatIfExists(oldPath);
838
- if (!oldStat) return null;
839
- if (oldStat.isSymbolicLink()) {
840
- let linkTarget = '(读取失败)';
841
- try {
842
- linkTarget = fs.readlinkSync(oldPath);
843
- } catch {
844
- /* 链接目标读取失败不改变处置(同样中止) */
845
- }
846
- throw new Error(
847
- `${oldPath} 是符号链接(指向 ${linkTarget})——不跟随链接搬移(避免穿越到项目外)。` +
848
- `请人工确认后处理:把真实文件复制到 ${newPath}(保留本链接),或删除该链接后重跑安装器。`
849
- );
850
- }
851
- if (lstatIfExists(newPath)) {
852
- throw new Error(
853
- `新旧位置同时存在该运行时文件,不覆盖任何一方:\n - 旧位置: ${oldPath}\n - 新位置: ${newPath}\n` +
854
- `请人工比对两处内容,保留正确的一份(删除或改名另一份)后重跑安装器。`
855
- );
856
- }
857
- let bytes;
858
- try {
859
- bytes = fs.readFileSync(oldPath);
860
- } catch (err) {
861
- throw new Error(`${oldPath} 读取失败(${err.message})——未做任何改动,中止迁移。请检查文件权限后重跑安装器。`);
862
- }
863
- if (entry.validateJson) {
864
- let parsed = null;
865
- try {
866
- // 校验容忍 UTF-8 BOM(与运行时判定一致:workflow-state.mjs 的 readJson 明确容忍 BOM,
867
- // 外部写入如会话 Write 可能带 BOM)——否则运行时读得动的状态文件会被迁移判为损坏而
868
- // 中止安装(同一份数据两处判定不一致)。strip 只作用于校验:备份与落盘始终写原始字节
869
- // bytes,绝不改写用户数据(BOM strip 用字面形态——与 workflow-state.mjs 的 readJson 同形,
870
- // 行为由场景 234 端到端锚定:若该字符被剥离会立即变红)。
871
- parsed = JSON.parse(bytes.toString('utf8').replace(/^/, ''));
872
- } catch (err) {
873
- throw new Error(
874
- `${oldPath} 内容不是合法 JSON(${err.message})——保留原件未改动,中止迁移。` +
875
- `请修复该文件(或从备份恢复)后重跑安装器。`
876
- );
877
- }
878
- if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
879
- throw new Error(`${oldPath} 顶层不是 JSON 对象——保留原件未改动,中止迁移。请修复该文件后重跑安装器。`);
880
- }
881
- }
882
- return bytes;
883
- }
884
-
885
- /**
886
- * 搬移落盘(写成功才删旧件):建目标目录 → 复制备份 → 逐字节校验备份 → 写新位置 →
887
- * 回读校验新位置 → 删旧件。任一环节失败都抛错,且**旧件与备份至少保留一份**(不丢数据)。
888
- */
889
- function writeRuntimeFileWithBackup(oldPath, newPath, backupPath, bytes) {
890
- const targetDir = path.dirname(newPath);
891
- const keepNote = `旧文件完整保留于 ${oldPath}`;
892
- try {
893
- fs.mkdirSync(targetDir, { recursive: true });
894
- } catch (err) {
895
- throw new Error(
896
- `无法建立迁移目标目录 ${targetDir}(${err.message})——${keepNote},未做任何改动。` +
897
- `请确认该路径未被普通文件占用且可写后重跑安装器。`
898
- );
899
- }
900
- try {
901
- fs.copyFileSync(oldPath, backupPath);
902
- } catch (err) {
903
- throw new Error(
904
- `生成迁移前备份失败(${backupPath}:${err.message})——${keepNote},未做任何改动。` +
905
- `请解除目标目录的写入限制后重跑安装器。`
906
- );
907
- }
908
- if (!fileEqualsBytes(backupPath, bytes)) {
909
- throw new Error(`备份逐字节校验失败(${backupPath} 与源文件不一致)——${keepNote},中止迁移。请重跑安装器。`);
910
- }
911
- try {
912
- fs.writeFileSync(newPath, bytes);
913
- } catch (err) {
914
- throw new Error(
915
- `写入新位置失败(${newPath}:${err.message})——${keepNote},备份保留于 ${backupPath}。` +
916
- `请解除该路径的写入限制后重跑安装器。`
917
- );
918
- }
919
- if (!fileEqualsBytes(newPath, bytes)) {
920
- throw new Error(
921
- `新位置回读校验失败(${newPath} 与源文件不一致)——${keepNote},备份保留于 ${backupPath},中止迁移。请人工检查后重跑安装器。`
922
- );
923
- }
924
- fs.rmSync(oldPath, { force: true });
925
- }
926
-
927
- /**
928
- * 编排单个白名单文件的位置迁移(前置校验 → 备份 → 写 → 回读校验 → 删旧件);
929
- * 无需迁移时把跳过说明记入 report(调用方统一打印)。
930
- */
931
- function migrateRuntimeFile(target, entry, report) {
932
- const oldRel = path.join(LEGACY_RUNTIME_DIR, entry.name);
933
- const newRel = path.join(RUNTIME_DIR, entry.name);
934
- const oldPath = path.join(target, oldRel);
935
- const newPath = path.join(target, newRel);
936
- const bytes = readMigratableRuntimeFile(oldPath, newPath, entry);
937
- if (!bytes) {
938
- report.skipped.push(`${oldRel} 不存在——无需迁移`);
939
- return;
940
- }
941
- const backupRel = path.join(RUNTIME_DIR, `${entry.name}.bak-${migrationTimestamp()}`);
942
- writeRuntimeFileWithBackup(oldPath, newPath, path.join(target, backupRel), bytes);
943
- report.migrated.push(`${oldRel} → ${newRel}(迁移前备份: ${backupRel})`);
944
- }
945
-
946
- /**
947
- * 运行时文件位置迁移总入口:按 RUNTIME_FILE_MIGRATIONS 白名单逐个执行(白名单之外的内容
948
- * 一律原位不动——目标项目 `.comet/` 三方共占),打印迁移/跳过报告;任一文件失败即抛错中止
949
- * (旧件与备份保留,可重跑自愈)。
950
- */
951
- function migrateRuntimeFiles(target) {
952
- const report = { migrated: [], skipped: [] };
953
- for (const entry of RUNTIME_FILE_MIGRATIONS) {
954
- migrateRuntimeFile(target, entry, report);
955
- }
956
- console.log(`[flow-comet] 运行时文件迁移(${LEGACY_RUNTIME_DIR}/ → ${RUNTIME_DIR}/;白名单 ${RUNTIME_FILE_MIGRATIONS.length} 项):`);
957
- for (const line of report.migrated) {
958
- console.log(` - 已迁移: ${line}`);
959
- }
960
- for (const line of report.skipped) {
961
- console.log(` - 已跳过: ${line}`);
962
- }
963
- if (report.migrated.length > 0) {
964
- console.log(' (迁移前备份保留在新位置,确认无误后可自行清理)');
965
- } else {
966
- console.log(' (全部跳过 = 本项目的状态已在当前命名空间,安装器不再需要触碰旧目录)');
967
- }
968
- }
969
-
970
- // ---------- .gitignore 保守纳管(目标项目;读-合并-写幂等,参照 injectSettingsHook 模式) ----------
971
-
972
- /** 判断一行是否为 `.flow-comet/` 忽略条目(容忍首尾空白与可选的首尾斜杠变体)。 */
973
- function isRuntimeDirIgnoreLine(line) {
974
- return String(line).trim().replace(/^\/+/, '').replace(/\/+$/, '') === RUNTIME_DIR;
975
- }
976
-
977
- /**
978
- * gitignore 保守纳管(读-合并-写幂等):既有条目一律保留原样——安装器无法可靠推断用户
979
- * 写下 `.comet/` 条目的原始意图(实测载体用整目录形态,该目录中仍有 Comet 资产),
980
- * 故只做「缺失时追加」,不改写用户其他内容(无关行/注释/既有行尾风格)。
981
- * 源仓库自身跳过:`.flow-comet/` 在源仓库是权威源(需被版本控制跟踪),
982
- * 整目录忽略会把权威源新增文件静默排除出版本控制。
983
- */
984
- function manageGitignore(target) {
985
- if (fs.existsSync(path.join(target, RUNTIME_DIR, 'skills', 'flow-comet', 'SKILL.md'))) {
986
- console.log(`[flow-comet] .gitignore 纳管跳过: 当前目录是 flow-comet 源仓库(${RUNTIME_DIR}/ 为权威源,需保持被版本控制跟踪)`);
987
- return;
988
- }
989
- const gitignorePath = path.join(target, '.gitignore');
990
- let existing = '';
991
- let fileExists = false;
992
- try {
993
- existing = fs.readFileSync(gitignorePath, 'utf8');
994
- fileExists = true;
995
- } catch (err) {
996
- // 只有「确实不存在」才是首次纳管;访问类故障(EACCES/EPERM/EIO…)必须原样抛出中止——
997
- // 按空内容继续会让下面的写回把用户既有 .gitignore **截断**为仅含受管条目
998
- // (判定语义见 isMissingPathError;调用点契约即「失败即中止,可重跑自愈」)。
999
- if (!isMissingPathError(err)) {
1000
- throw err;
1001
- }
1002
- }
1003
- if (existing.split(/\r?\n/).some(isRuntimeDirIgnoreLine)) {
1004
- console.log(`[flow-comet] .gitignore 已含 ${RUNTIME_DIR}/ 条目——保持原样(幂等)`);
1005
- return;
1006
- }
1007
- const eol = existing.includes('\r\n') ? '\r\n' : '\n';
1008
- const appended = ['# flow-comet 运行时文件(不随仓库分发)', `${RUNTIME_DIR}/`].join(eol);
1009
- const separator = !fileExists || existing === '' || existing.endsWith('\n') ? '' : eol;
1010
- fs.writeFileSync(gitignorePath, existing + separator + appended + eol, 'utf8');
1011
- console.log(`[flow-comet] .gitignore 追加 ${RUNTIME_DIR}/ 条目(既有内容原样保留): ${gitignorePath}`);
1012
- }
1013
-
1014
- // ---------- settings.local.json 注入(Claude Code 平台;参考 comet installClaudeCodeHooks) ----------
1015
-
1016
- /** 判断 hook 命令是否为"已管理的 comet hook"(注入时替换,保证幂等)。
1017
- * 精确匹配:归一化命令(去前缀、统一分隔符)后必须包含
1018
- * 'comet-hook-guard.mjs' 作为脚本路径(而非任意位置子串),防误伤用户自定义 hook。
1019
- */
1020
- function isManagedHookCommand(command) {
1021
- if (typeof command !== 'string' || command.trim() === '') {
1022
- return false;
1023
- }
1024
- const normalized = command.replace(/\\/g, '/').trim();
1025
- // 提取命令中的脚本路径(node <path> 或直接 <path>)——容忍外层引号(含空格路径防护形态):
1026
- // 引号由可选的 ["']? 吸收、不并入捕获组,basename 判等保持形态无关(旧相对形态 / 变量引用
1027
- // 形态 / 绝对路径形态 / 带引号形态均识别)。
1028
- const pathMatch = normalized.match(/(?:^|\s)["']?([^\s"']+\.mjs)["']?(?:\s|$)/);
1029
- if (!pathMatch) {
1030
- return false;
1031
- }
1032
- const scriptPath = pathMatch[1].split('/').pop();
1033
- return scriptPath === MANAGED_HOOK_COMMAND_MARKER;
1034
- }
1035
-
1036
- /**
1037
- * 合并 hook 组:已有组中过滤掉已管理的 comet hook 命令;新组按 matcher 合并进
1038
- * 同 matcher 的既有组(或新建组)。参考 comet mergeHookGroups。
1039
- */
1040
- function mergeHookGroups(existingGroups, newGroups) {
1041
- const mergedGroups = (Array.isArray(existingGroups) ? existingGroups : []).map((group) => {
1042
- if (!group || typeof group !== 'object' || Array.isArray(group) || !Array.isArray(group.hooks)) {
1043
- return group;
1044
- }
1045
- const hadManagedHook = group.hooks.some((hook) => isManagedHookCommand(hook && hook.command));
1046
- const filtered = group.hooks.filter((hook) => !isManagedHookCommand(hook && hook.command));
1047
- // 只删除「含托管 hook 且过滤后为空」的组:matcher 演进(如 Write|Edit → Write|Edit|Bash)
1048
- // 会使旧托管组过滤为空,此时删除防配置污染(与 Codex purge 路径一致);
1049
- // 用户空组/纯用户组保留(不动用户配置——2026-08-16 修复:此前统一删空组会误删用户空 matcher 组)
1050
- if (hadManagedHook && filtered.length === 0) return null;
1051
- return { ...group, hooks: filtered };
1052
- }).filter(Boolean);
1053
- for (const newGroup of newGroups) {
1054
- const existingIndex = mergedGroups.findIndex(
1055
- (group) =>
1056
- group &&
1057
- typeof group === 'object' &&
1058
- !Array.isArray(group) &&
1059
- group.matcher === newGroup.matcher &&
1060
- Array.isArray(group.hooks)
1061
- );
1062
- if (existingIndex >= 0) {
1063
- const existing = mergedGroups[existingIndex];
1064
- mergedGroups[existingIndex] = { ...existing, hooks: [...existing.hooks, ...newGroup.hooks] };
1065
- } else {
1066
- mergedGroups.push(newGroup);
1067
- }
1068
- }
1069
- return mergedGroups;
1070
- }
1071
-
1072
- /**
1073
- * 注入 comet hook 到 settings.local.json(Claude Code 平台):
1074
- * 读现有 settings(缺失 → {})→ 保留全部既有字段(permissions 等)→
1075
- * 只更新 hooks.PreToolUse(过滤已管理 comet hook + 合并新 hook)→ 写回。
1076
- *
1077
- * fail-safe(T-FIX-13 审查修复):
1078
- * - settings 文件存在但 JSON 非法 → 抛错退出(不静默覆盖,避免用户内容丢失)
1079
- * - hooks.PreToolUse 非数组(手写变体/对象形式)→ 保留原值 + 警告(不注入,
1080
- * 避免破坏用户结构;提示手动配置)
1081
- */
1082
- function injectSettingsHook(claudeDir) {
1083
- const settingsPath = path.join(claudeDir, 'settings.local.json');
1084
- let settings = {};
1085
- let fileExists = false;
1086
- try {
1087
- const raw = fs.readFileSync(settingsPath, 'utf8');
1088
- fileExists = true;
1089
- const parsed = JSON.parse(raw);
1090
- if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
1091
- settings = parsed;
1092
- } else {
1093
- throw new Error('settings 顶层必须是 JSON 对象');
1094
- }
1095
- } catch (err) {
1096
- if (fileExists) {
1097
- // 文件存在但非法:fail-safe——不覆盖用户内容,报错退出
1098
- throw new Error(
1099
- `settings.local.json 已存在但内容非法(${err.message})——为保护用户配置,中止注入。` +
1100
- `请修复该文件后重试,或手动添加 hook 配置(见 README 方案 B)。`
1101
- );
1102
- }
1103
- // 文件缺失:视为空对象(首次安装)
1104
- settings = {};
1105
- }
1106
- const existingHooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
1107
- ? settings.hooks
1108
- : {};
1109
- const newGroup = {
1110
- // R5: matcher 含 Bash——协调者禁令物理化(Bash 写源码命令同样被 hook 检测拦截;
1111
- // hook 对无写路径的 Bash 命令(如 git/查询)放行)
1112
- matcher: 'Write|Edit|Bash',
1113
- hooks: [
1114
- {
1115
- type: 'command',
1116
- // 项目根锚定(全平台统一形态):node ${CLAUDE_PROJECT_DIR}/.claude/skills/.../comet-hook-guard.mjs
1117
- // —— CC 以 /bin/bash -c 执行 hook 命令(含 Windows),POSIX 词形 + 正斜杠为唯一可用形态。
1118
- // 运行期由 CC 注入的变量展开;单一事实来源 = PROJECT_ROOT_ENV_VAR + projectRootGuardScriptRef。
1119
- command: `node ${projectRootGuardScriptRef('.claude')}`,
1120
- },
1121
- ],
1122
- };
1123
- if (existingHooks.PreToolUse !== undefined && !Array.isArray(existingHooks.PreToolUse)) {
1124
- // PreToolUse 非数组(手写变体):保留原值 + 警告,不注入(避免破坏用户结构)
1125
- console.error(
1126
- '[flow-comet] 警告: settings.local.json 的 hooks.PreToolUse 不是数组(可能是手写变体)——' +
1127
- '为保护用户配置,未注入 comet hook。请手动添加(见 README 方案 B)。'
1128
- );
1129
- return settings;
1130
- }
1131
- const merged = mergeHookGroups(existingHooks.PreToolUse, [newGroup]);
1132
- settings.hooks = { ...existingHooks, PreToolUse: merged };
1133
- fs.mkdirSync(claudeDir, { recursive: true });
1134
- fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
1135
- return settings;
1136
- }
1137
-
1138
- // ---------- Codex 平台注入 + AGENTS.md 托管区(codex/dsh 共用) ----------
1139
-
1140
- /**
1141
- * 注入 comet hook 到 .codex/hooks.json(Codex 平台):
1142
- * 读现有 hooks(缺失 → {})→ 过滤已管理 comet hook(命令含 comet-hook-guard.mjs)→
1143
- * 合并新组(matcher "*"——Codex PreToolUse 只拦截 Bash 工具,写路径经 PowerShell/Bash 命令,
1144
- * 必须匹配所有 Bash 调用;命令带 --platform codex 平台标记)→ 写回。
1145
- * 结构:顶层 "hooks" 包裹层(Codex 与 Claude Code 同构——{"hooks":{"PreToolUse":[...]}};
1146
- * 实测缺包裹层 hook 不加载)。
1147
- * fail-safe:文件存在但 JSON 非法 → 抛错退出(保护用户配置)。
1148
- */
1149
- function injectCodexHook(codexDir, target) {
1150
- const hooksPath = path.join(codexDir, 'hooks.json');
1151
- let hooks = {};
1152
- let fileExists = false;
1153
- try {
1154
- const raw = fs.readFileSync(hooksPath, 'utf8');
1155
- fileExists = true;
1156
- const parsed = JSON.parse(raw);
1157
- if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
1158
- hooks = parsed;
1159
- } else {
1160
- throw new Error('hooks.json 顶层必须是 JSON 对象');
1161
- }
1162
- } catch (err) {
1163
- if (fileExists) {
1164
- throw new Error(
1165
- `.codex/hooks.json 已存在但内容非法(${err.message})——为保护用户配置,中止注入。请修复该文件后重试。`
1166
- );
1167
- }
1168
- hooks = {};
1169
- }
1170
- const existingHooks = hooks.hooks && typeof hooks.hooks === 'object' && !Array.isArray(hooks.hooks)
1171
- ? hooks.hooks
1172
- : {};
1173
- const existingGroups = Array.isArray(existingHooks.PreToolUse) ? existingHooks.PreToolUse : [];
1174
- // D6 查证结论(2026-08,openai/codex 官方仓库 main 分支):
1175
- // - hooks.json 的 command 经 shell 执行:Windows = %COMSPEC% 回退 cmd.exe /C;POSIX = $SHELL
1176
- // 回退 /bin/sh -lc(codex-rs/hooks/src/engine/command_runner.rs 的 build_command /
1177
- // default_shell_command);子进程环境 = 会话环境快照 + 条目级 env 映射,current_dir = 会话工作目录。
1178
- // - 无等价项目根变量:全仓 Rust 检索 CODEX_PROJECT_DIR / CLAUDE_PROJECT_DIR / project_dir
1179
- // 均 0 命中(GitHub code search,openai/codex);$PWD/%CD% 展开的是"会话启动目录"而非
1180
- // 项目根契约,子目录启动即漂移——不构成 CLAUDE_PROJECT_DIR 的等价锚点。
1181
- // → 按 D6 预授权退化分支:安装期把 target 绝对路径字面注入(path.join)。
1182
- // ⚠️ 迁移目录需重跑安装器:绝对路径随安装位置固化,项目移动/换 checkout 后必须重新运行
1183
- // 本安装器刷新 hooks.json(旧条目按脚本 basename 仍被 isManagedHookCommand 识别并在
1184
- // 重跑时被过滤替换为新位置——幂等自愈,不会产生重复条目)。
1185
- // 注:上游 HookHandlerConfig::Command 另有 command_windows 平台分字段(declarations.rs);
1186
- // 本安装器逐机注入,写入路径与宿主 OS 天然一致,无需分字段双写。
1187
- const guardAbsolutePath = path.join(target, '.agents', 'skills', 'flow-comet', 'scripts', MANAGED_HOOK_COMMAND_MARKER);
1188
- const newGroup = {
1189
- matcher: '*',
1190
- hooks: [
1191
- {
1192
- type: 'command',
1193
- command: `node ${guardAbsolutePath} before_tool --platform codex`,
1194
- },
1195
- ],
1196
- };
1197
- const merged = mergeHookGroups(existingGroups, [newGroup]);
1198
- hooks.hooks = { ...existingHooks, PreToolUse: merged };
1199
- fs.mkdirSync(codexDir, { recursive: true });
1200
- fs.writeFileSync(hooksPath, JSON.stringify(hooks, null, 2) + '\n', 'utf8');
1201
- return hooks;
1202
- }
1203
-
1204
- /**
1205
- * 注入 Codex hook 启用配置到 .codex/config.toml(Codex 平台):
1206
- * hooks 默认关闭——需 [features] hooks = true(部分版本 codex_hooks = true;双写兼容)。
1207
- * 幂等:已有 [features] 段时合并缺失键,不覆盖用户其他配置。
1208
- */
1209
- function injectCodexConfig(codexDir) {
1210
- const configPath = path.join(codexDir, 'config.toml');
1211
- let content = '';
1212
- try {
1213
- content = fs.readFileSync(configPath, 'utf8');
1214
- } catch { /* 文件缺失 = 首次安装 */ }
1215
- if (content.includes('[features]')) {
1216
- // 已有 [features] 段:一次性补齐全部缺失键(分次 replace 会因插入点被前次消耗而失配;
1217
- // CRLF 行尾与文件尾无换行均须匹配——(\[features\])(?:\r?\n|$) 覆盖)
1218
- const missing = [];
1219
- if (!/^hooks\s*=/m.test(content)) missing.push('hooks = true');
1220
- if (!/^codex_hooks\s*=/m.test(content)) missing.push('codex_hooks = true');
1221
- if (missing.length > 0) {
1222
- content = content.replace(/(\[features\])(?:\r?\n|$)/, '$1\r\n' + missing.join('\r\n') + '\r\n');
1223
- }
1224
- } else {
1225
- const trimmed = content.trim();
1226
- content = (trimmed ? trimmed + '\n\n' : '') + '[features]\nhooks = true\ncodex_hooks = true\n';
1227
- }
1228
- fs.mkdirSync(codexDir, { recursive: true });
1229
- fs.writeFileSync(configPath, content, 'utf8');
1230
- }
1231
-
1232
- /**
1233
- * 注入 rules 到 AGENTS.md 托管区(Codex/dsh 平台共用——AGENTS.md 是两平台指令
1234
- * 唯一自动加载路径;.codex/rules/ 是命令批准规则目录,不混用)。
1235
- * 读现有 AGENTS.md(缺失 → 空)→ 移除旧托管区(幂等)→ 托管区内联 orchestration 全文
1236
- * → 保留托管区外用户内容 → 写回。托管区标记不变(任一平台卸载可清,另一平台重装恢复)。
1237
- */
1238
- function injectManagedRules(target, stats) {
1239
- const rulesSrc = path.join(BUNDLE_DRAFTS, 'rules');
1240
- if (!fs.existsSync(rulesSrc)) return false;
1241
- const rulesFile = path.join(rulesSrc, 'flow-comet-orchestration.md');
1242
- if (!fs.existsSync(rulesFile)) return false;
1243
- const rulesText = fs.readFileSync(rulesFile, 'utf8');
1244
- const agentsPath = path.join(target, 'AGENTS.md');
1245
- let existing = '';
1246
- try {
1247
- existing = fs.readFileSync(agentsPath, 'utf8');
1248
- } catch { /* 文件缺失 = 首次安装 */ }
1249
- const stripped = stripManagedBlock(existing, MANAGED_AGENTS_START, MANAGED_AGENTS_END);
1250
- const managedBlock =
1251
- MANAGED_AGENTS_START + '\n' +
1252
- rulesText.trim() + '\n' +
1253
- MANAGED_AGENTS_END + '\n';
1254
- const merged = (stripped.trim() ? stripped.trim() + '\n\n' : '') + managedBlock;
1255
- fs.writeFileSync(agentsPath, merged, 'utf8');
1256
- stats.files++;
1257
- return true;
1258
- }
1259
-
1260
- /**
1261
- * 移除 .codex/hooks.json 中的托管 hook 条目(purge 语义:移除而非注入——保留用户条目;
1262
- * 重建流程会重新注入新托管条目)。文件非法 JSON 时不动(保护用户配置)。
1263
- */
1264
- function removeManagedCodexHooks(codexDir) {
1265
- const hooksPath = path.join(codexDir, 'hooks.json');
1266
- if (!fs.existsSync(hooksPath)) return;
1267
- let hooks;
1268
- try {
1269
- hooks = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
1270
- } catch { return; } // 非法 JSON 不触碰(保护用户配置)
1271
- const outer = hooks && typeof hooks === 'object' && !Array.isArray(hooks) ? hooks : {};
1272
- const inner = outer.hooks && typeof outer.hooks === 'object' && !Array.isArray(outer.hooks) ? outer.hooks : {};
1273
- if (!Array.isArray(inner.PreToolUse)) return;
1274
- inner.PreToolUse = inner.PreToolUse
1275
- .map((group) => (
1276
- group && typeof group === 'object' && !Array.isArray(group) && Array.isArray(group.hooks)
1277
- ? { ...group, hooks: group.hooks.filter((hook) => !isManagedHookCommand(hook && hook.command)) }
1278
- : group
1279
- ))
1280
- .filter((group) => group && typeof group === 'object' && Array.isArray(group.hooks) && group.hooks.length > 0);
1281
- outer.hooks = inner;
1282
- fs.writeFileSync(hooksPath, JSON.stringify(outer, null, 2) + '\n', 'utf8');
1283
- }
1284
-
1285
- // ---------- dsh 平台注入 ----------
1286
-
1287
- /**
1288
- * $DSH_HOME 解析(dsh 平台——与 dsh CLI 同款默认):显式 DSH_HOME 环境变量 > ~/.dsh。
1289
- */
1290
- function resolveDshHome() {
1291
- if (process.env.DSH_HOME) return path.resolve(process.env.DSH_HOME);
1292
- return path.join(os.homedir(), '.dsh');
1293
- }
1294
-
1295
- // ---------- loader 覆盖前版本比对(全局挂载的桥接 loader 生命周期治理) ----------
1296
-
1297
- // 版本戳锚点正则(标记行格式契约:独立整行、行首无缩进、冒号后恰一个空格、行尾无其它字符;
1298
- // 格式禁动——安装器与 bridge-check 双侧提取以此为准;技能包自包含,语义同值复刻不跨模块 import)。
1299
- const BRIDGE_VERSION_RE = /^\/\/ BRIDGE_VERSION: ([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$/m;
1300
-
1301
- /**
1302
- * 从 loader 文件提取版本戳(同一锚点正则)。返回 { ok:true, version };
1303
- * 文件缺失/读取失败/无标记行 → { ok:false, reason }(调用方告警兜底,不抛错)。
1304
- */
1305
- function extractBridgeVersion(loaderPath) {
1306
- let text;
1307
- try {
1308
- text = fs.readFileSync(loaderPath, 'utf8');
1309
- } catch {
1310
- return { ok: false, reason: '文件读取失败' };
1311
- }
1312
- const match = BRIDGE_VERSION_RE.exec(text);
1313
- if (match) return { ok: true, version: match[1] };
1314
- // 标记行存在但形态非法(区别于「无标记行」)——仍走既有警告路径,原因精确可诊断
1315
- const loose = /^\/\/ BRIDGE_VERSION: (.*)$/m.exec(text);
1316
- return loose
1317
- ? { ok: false, reason: '版本戳形态非法(非语义化版本: ' + loose[1] + ')' }
1318
- : { ok: false, reason: '未提取到版本戳标记行' };
1319
- }
1320
-
1321
- /**
1322
- * 语义化版本数值序比较(覆盖前判定方向):major.minor.patch 逐段按数值比较
1323
- * (如 1.10.0 > 1.6.0——非字典序);核心版本相等时按语义化版本规则处理预发布后缀
1324
- * (如 1.6.0-alpha.1 < 1.6.0)。返回 -1 / 0 / 1。
1325
- */
1326
- function compareBridgeVersions(a, b) {
1327
- const parse = (v) => {
1328
- const text = String(v);
1329
- const dash = text.indexOf('-');
1330
- const core = (dash === -1 ? text : text.slice(0, dash)).split('.').map((seg) => parseInt(seg, 10));
1331
- return { core, pre: dash === -1 ? null : text.slice(dash + 1) };
1332
- };
1333
- const av = parse(a);
1334
- const bv = parse(b);
1335
- const coreLen = Math.max(av.core.length, bv.core.length);
1336
- for (let i = 0; i < coreLen; i++) {
1337
- const x = av.core[i] ?? 0;
1338
- const y = bv.core[i] ?? 0;
1339
- if (x !== y) return x < y ? -1 : 1;
1340
- }
1341
- const ap = av.pre !== null;
1342
- const bp = bv.pre !== null;
1343
- if (ap !== bp) return ap ? -1 : 1; // 预发布 < 正式版
1344
- if (!ap) return 0;
1345
- const ai = av.pre.split('.');
1346
- const bi = bv.pre.split('.');
1347
- const preLen = Math.max(ai.length, bi.length);
1348
- for (let i = 0; i < preLen; i++) {
1349
- if (i >= ai.length) return -1; // 更短标识符列表是更长列表的前缀 → 更小
1350
- if (i >= bi.length) return 1;
1351
- const x = ai[i];
1352
- const y = bi[i];
1353
- if (x === y) continue;
1354
- const xn = /^\d+$/.test(x) ? parseInt(x, 10) : null;
1355
- const yn = /^\d+$/.test(y) ? parseInt(y, 10) : null;
1356
- if (xn !== null && yn !== null) return xn < yn ? -1 : 1;
1357
- if (xn !== null) return -1; // 数字标识符 < 字母标识符(语义化版本规则)
1358
- if (yn !== null) return 1;
1359
- return x < y ? -1 : 1;
1360
- }
1361
- return 0;
1362
- }
1363
-
1364
- /**
1365
- * 覆盖前版本比对明示:从权威源 loader 与已装 loader 各提取版本戳,按数值序输出
1366
- * 首次安装 / 升级 A→B / 降级 A→B / 版本一致 四类结论之一(人读、带 [flow-comet] 前缀)。
1367
- * 任一侧提取失败(文件缺失/无标记行)→ 告警并跳过比对——不抛错、不中断安装;
1368
- * 覆盖动作(copyFileSync)由调用方照常执行,幂等语义不变。
1369
- */
1370
- function reportLoaderVersionTransition(loaderSrc, loaderDst) {
1371
- if (!fs.existsSync(loaderDst)) {
1372
- console.log('[flow-comet] 桥接 loader 首次安装($DSH_HOME/plugins 无已装 loader)');
1373
- return;
1374
- }
1375
- const src = extractBridgeVersion(loaderSrc);
1376
- const installed = extractBridgeVersion(loaderDst);
1377
- if (!src.ok || !installed.ok) {
1378
- const failedSide = !src.ok ? '权威源 loader' : '已装 loader';
1379
- const reason = !src.ok ? src.reason : installed.reason;
1380
- console.warn(
1381
- `[flow-comet] 警告: ${failedSide} 版本戳提取失败(${reason})——跳过版本比对,继续覆盖安装`
1382
- );
1383
- return;
1384
- }
1385
- const a = installed.version;
1386
- const b = src.version;
1387
- const cmp = compareBridgeVersions(a, b);
1388
- if (cmp < 0) {
1389
- console.log(`[flow-comet] 桥接 loader 升级 ${a} → ${b}`);
1390
- } else if (cmp > 0) {
1391
- console.log(`[flow-comet] 桥接 loader 降级 ${a} → ${b}`);
1392
- } else {
1393
- console.log(`[flow-comet] 桥接 loader 版本一致(${a})`);
1394
- }
1395
- }
1396
-
1397
- /**
1398
- * 极简 YAML 形状校验(零依赖——用于 cordis.patch.yml 的 fail-safe 判定):
1399
- * 文件须为顶层 YAML 列表形态(行形态:注释 / 空行 / 顶层 `- 条目` / 条目下缩进内容 / 文档分隔符),
1400
- * 无法识别(二进制、顶层 map 形态等)→ 返回 false——调用方据此 fail-safe 不覆盖(保护用户配置)。
1401
- */
1402
- function isSimpleYamlText(text) {
1403
- return text.split(/\r?\n/).every((line) => {
1404
- const t = line.trimEnd();
1405
- if (t.trim() === '') return true; // 空行
1406
- if (/^\s*#/.test(t)) return true; // 注释
1407
- if (/^\s*---\s*$/.test(t)) return true; // 文档分隔符
1408
- if (/^\s*-\s+\S/.test(t)) return true; // 顶层列表条目
1409
- if (/^\s+\S/.test(t)) return true; // 条目下缩进内容(键值/嵌套列表;YAML 允许 1 空格缩进)
1410
- return false;
1411
- });
1412
- }
1413
-
1414
- /**
1415
- * 注入桥接 loader 托管块到 $DSH_HOME/cordis.patch.yml(dsh 平台 home patch——
1416
- * 读-合并-写,L-008 非破坏):
1417
- * 读现有 cordis.patch.yml(缺失 → 空)→ 移除旧托管块(幂等)→ 托管块内联 loader 的
1418
- * file:// 引用(**insert 形态**:无 id 的顶层 `- insert:` 条目内嵌插件行
1419
- * `- id: dsh-flow-comet-bridge` + `name: 'file:///<abs 路径>'`——dsh-app-boot 的
1420
- * applyEntryPatches 语义是 id-targeted patch(id 必须已存在于配置树);无 id 的
1421
- * `insert:` 顶层条目才执行 data.push 追加新插件行,是 home patch 新增插件的唯一正确形态;
1422
- * 旧的 `- id: ... + name:` patch 形态对不存在的 id 报 entry not found 并跳过——
1423
- * loader 从不加载 → 拦截整链静默失效)
1424
- * → 保留托管块外既有块(dsh-skin 等)→ 写回。
1425
- * fail-safe:文件存在但内容无法识别为 YAML → 抛错退出不覆盖(参照 injectSettingsHook 模式)。
1426
- */
1427
- function injectDshCordisPatch(dshHome, loaderPath) {
1428
- const patchPath = path.join(dshHome, 'cordis.patch.yml');
1429
- let existing = '';
1430
- let fileExists = false;
1431
- try {
1432
- existing = fs.readFileSync(patchPath, 'utf8');
1433
- fileExists = true;
1434
- } catch { /* 文件缺失 = 首次安装 */ }
1435
- if (fileExists && !isSimpleYamlText(existing)) {
1436
- throw new Error(
1437
- `cordis.patch.yml 已存在但内容无法解析为 YAML(${patchPath})——为保护用户配置,中止注入。` +
1438
- `请修复该文件(顶层 YAML 列表形态)后重试,或手动添加桥接 loader 引用。`
1439
- );
1440
- }
1441
- const stripped = stripManagedBlock(existing, MANAGED_CORDIS_START, MANAGED_CORDIS_END);
1442
- const fileUrl = pathToFileURL(loaderPath).href;
1443
- const managedBlock =
1444
- MANAGED_CORDIS_START + '\n' +
1445
- '- insert:\n' +
1446
- ' - id: dsh-flow-comet-bridge\n' +
1447
- ` name: '${fileUrl.replace(/'/g, "''")}'\n` +
1448
- MANAGED_CORDIS_END + '\n';
1449
- const merged = (stripped.trim() ? stripped.trim() + '\n\n' : '') + managedBlock;
1450
- fs.mkdirSync(dshHome, { recursive: true });
1451
- fs.writeFileSync(patchPath, merged, 'utf8');
1452
- return merged;
1453
- }
1454
-
1455
- /**
1456
- * 移除 $DSH_HOME/cordis.patch.yml 中的托管块(purge 语义:移除而非注入——保留 dsh-skin
1457
- * 等既有块与用户内容)。文件缺失 → 跳过;内容无法识别为 YAML → 不动(fail-safe 保护
1458
- * 用户配置)。移除后文件为空 → 删除文件本身。返回删除清单条目(供 purge 打印)。
1459
- */
1460
- function removeDshCordisPatch(dshHome) {
1461
- const patchPath = path.join(dshHome, 'cordis.patch.yml');
1462
- const removed = [];
1463
- if (!fs.existsSync(patchPath)) return removed;
1464
- let content;
1465
- try {
1466
- content = fs.readFileSync(patchPath, 'utf8');
1467
- } catch { return removed; }
1468
- if (!content.includes(MANAGED_CORDIS_START)) return removed;
1469
- if (!isSimpleYamlText(content)) {
1470
- // 无法识别 → 不触碰(fail-safe 语义与注入一致——保护用户配置)
1471
- return removed;
1472
- }
1473
- const stripped = stripManagedBlock(content, MANAGED_CORDIS_START, MANAGED_CORDIS_END);
1474
- const trimmed = stripped.trim();
1475
- if (trimmed) {
1476
- fs.writeFileSync(patchPath, trimmed + '\n', 'utf8');
1477
- } else {
1478
- fs.rmSync(patchPath, { force: true });
1479
- }
1480
- removed.push(patchPath + '(托管块)');
1481
- return removed;
1482
- }
1483
-
1484
- function escapeRegExp(value) {
1485
- return String(value).replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
1486
- }
1487
-
1488
- // 移除托管块(幂等替换边界):start 标记到 end 标记(含尾随换行)之间的全部内容。
1489
- // 注入与清理共用——AGENTS.md 托管区 / cordis.patch.yml 托管块(L-008 读-合并-写)。
1490
- function stripManagedBlock(content, startMarker, endMarker) {
1491
- return content.replace(
1492
- new RegExp(escapeRegExp(startMarker) + '[\\s\\S]*?' + escapeRegExp(endMarker) + '\\n?'),
1493
- ''
1494
- );
1495
- }
1496
-
1497
312
  // ---------- 版本标识(全部平台共用) ----------
1498
313
 
1499
314
  /**
@@ -1544,113 +359,6 @@ function resolveInstalledVersion() {
1544
359
  }
1545
360
  return installedVersion;
1546
361
  }
1547
-
1548
- // ---------- flow-kit 获取链路(ADR-008 / DESIGN D1~D6——平台无关,main 平台循环前调用一次) ----------
1549
-
1550
- // 锁定点常量(D2):上游 github.com/rihebty/flow-kit 实测无 tag,commit 是唯一精确锚;
1551
- // 升级锁定点 = 显式修改此常量并记 CHANGELOG,不做自动跟随(2026-08-23 ls-remote 实测 == 上游 HEAD)。
1552
- const FLOW_KIT_UPSTREAM_URL = 'https://github.com/rihebty/flow-kit.git';
1553
- const FLOW_KIT_LOCKED_COMMIT = '9b5dda7206ae841230f118348d660ad8d0ae2830';
1554
- // git 网络调用统一超时(D5——沿用 resolveInstalledVersion 的 execFileSync timeout 先例风格)
1555
- const FLOW_KIT_GIT_TIMEOUT_MS = 60000;
1556
- // 摘要展示用短 sha 长度(git 短哈希惯例——单一来源,clone 成功/已有/指引三处引用)
1557
- const FLOW_KIT_SHORT_SHA_LEN = 7;
1558
-
1559
- /** 提取 git 调用失败信息首行(execFileSync 错误消息含多行 stderr——警告只留首行) */
1560
- function gitErrorFirstLine(err) {
1561
- return String(err && err.message ? err.message : err).split('\n')[0].trim();
1562
- }
1563
-
1564
- /** 手动获取指引(clone/checkout 失败或目录非上游克隆时打印——含上游 URL 与目标路径;不抛错) */
1565
- function printFlowKitManualGuide(target) {
1566
- const flowKitDir = path.join(target, 'flow-kit');
1567
- console.warn(`[flow-comet] 手动获取指引: git clone ${FLOW_KIT_UPSTREAM_URL} "${flowKitDir}"`);
1568
- console.warn(`[flow-comet] 然后锁定快照: git -C "${flowKitDir}" checkout --detach ${FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN)}`);
1569
- console.warn('[flow-comet] 未获取 flow-kit 时技能协议引用悬空、guard 段名基准退化为内置 fallback——其余安装职责不受影响。');
1570
- }
1571
-
1572
- /**
1573
- * 归属判定(D3):origin remote URL 匹配上游——本地 config 读取,无网络。
1574
- * 兼容 https / ssh 形态与可选 .git 后缀;读取失败视为不匹配(保守落入"非上游克隆"分支,
1575
- * 绝不改动用户目录)。返回 'match' | 'mismatch' | 'unreadable'。
1576
- */
1577
- function flowKitOriginStatus(flowKitDir) {
1578
- try {
1579
- const url = execFileSync(
1580
- 'git',
1581
- ['-C', flowKitDir, 'config', '--get', 'remote.origin.url'],
1582
- { encoding: 'utf8', timeout: FLOW_KIT_GIT_TIMEOUT_MS }
1583
- ).trim().replace(/\.git$/i, '').replace(/\/+$/, '');
1584
- return /github\.com[:/]rihebty\/flow-kit$/i.test(url) ? 'match' : 'mismatch';
1585
- } catch {
1586
- return 'unreadable';
1587
- }
1588
- }
1589
-
1590
- /**
1591
- * 确保 <target>/flow-kit/ 就位(ADR-008 / DESIGN D1~D6——L-008 非破坏哲学:已存在路径一律只读不动):
1592
- * 路径 1 目标不存在 → execFileSync('git',…) 数组参数形态 clone 上游后 detached checkout 到锁定 commit;
1593
- * 路径 2 已存在且 .git 存在且 origin 匹配上游 → 只读 rev-parse HEAD 并输出与锁定点差异影响,绝不改动;
1594
- * 路径 3 已存在但不满足归属判定 → 摘要"非上游克隆,已跳过"+ 手动指引,不改动;
1595
- * 路径 4 clone/checkout 任一失败 → 警告 + 手动获取指引,**不抛错**(D5——外网故障不得绑架安装器
1596
- * 其余职责,进程照常 exit 0);各平台 purge 清单永不包含 flow-kit(D6,见 PLATFORMS 表头注释)。
1597
- */
1598
- function ensureFlowKit(target) {
1599
- const flowKitDir = path.join(target, 'flow-kit');
1600
- const shortLock = FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN);
1601
- if (!fs.existsSync(flowKitDir)) {
1602
- // 路径 1:目标缺失 → clone + detached checkout 到锁定 commit(D1/D2)
1603
- try {
1604
- execFileSync('git', ['clone', FLOW_KIT_UPSTREAM_URL, flowKitDir], {
1605
- encoding: 'utf8',
1606
- timeout: FLOW_KIT_GIT_TIMEOUT_MS,
1607
- });
1608
- execFileSync('git', ['-C', flowKitDir, 'checkout', '--detach', FLOW_KIT_LOCKED_COMMIT], {
1609
- encoding: 'utf8',
1610
- timeout: FLOW_KIT_GIT_TIMEOUT_MS,
1611
- });
1612
- console.log(`[flow-comet] 已获取 flow-kit(锁定 ${shortLock})`);
1613
- } catch (err) {
1614
- // 路径 4:clone/checkout 任一失败 → WARN + 手动指引,不抛错
1615
- console.warn(`[flow-comet] 警告: flow-kit 自动获取失败(${gitErrorFirstLine(err)})`);
1616
- printFlowKitManualGuide(target);
1617
- }
1618
- return;
1619
- }
1620
- // 目录已存在 → 归属判定(D3:.git 存在 且 origin remote 匹配上游)
1621
- const hasDotGit = fs.existsSync(path.join(flowKitDir, '.git'));
1622
- const originStatus = hasDotGit ? flowKitOriginStatus(flowKitDir) : 'mismatch';
1623
- if (originStatus !== 'match') {
1624
- // 路径 3:同名非克隆目录(或 remote 无法确认归属)→ 跳过 + 指引,绝不改动
1625
- if (originStatus === 'unreadable') {
1626
- console.warn('[flow-comet] 警告: flow-kit 目录存在且含 .git,但 origin remote 读取失败——无法确认归属');
1627
- }
1628
- console.log('[flow-comet] 目录存在但非上游克隆,已跳过');
1629
- printFlowKitManualGuide(target);
1630
- return;
1631
- }
1632
- // 路径 2:上游克隆 → 只读检测并输出差异影响(D4——绝不 fetch/checkout 改动用户克隆)
1633
- try {
1634
- const head = execFileSync('git', ['-C', flowKitDir, 'rev-parse', 'HEAD'], {
1635
- encoding: 'utf8',
1636
- timeout: FLOW_KIT_GIT_TIMEOUT_MS,
1637
- }).trim();
1638
- const shortHead = head.slice(0, FLOW_KIT_SHORT_SHA_LEN);
1639
- console.log(`[flow-comet] 已有 flow-kit(HEAD=${shortHead},推荐锁定点=${shortLock})`);
1640
- if (head === FLOW_KIT_LOCKED_COMMIT) {
1641
- console.log('[flow-comet] 当前 HEAD 与推荐锁定点一致。');
1642
- } else {
1643
- console.warn(
1644
- `[flow-comet] 差异影响: 当前 HEAD 与推荐锁定点不一致——guard 段名基准与协议引用可能偏离安装器锁定内容` +
1645
- `(安装器绝不改动已有克隆;如需对齐请手动执行 git -C "${flowKitDir}" fetch 后 checkout --detach ${shortLock})`
1646
- );
1647
- }
1648
- } catch (err) {
1649
- // HEAD 只读失败同样不改动、不中断安装(保守降级为警告)
1650
- console.warn(`[flow-comet] 警告: flow-kit HEAD 读取失败(${gitErrorFirstLine(err)}),已跳过比对`);
1651
- }
1652
- }
1653
-
1654
362
  // ---------- 主流程 ----------
1655
363
 
1656
364
  async function main() {