flow-comet 1.6.1 → 1.6.3
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 +94 -46
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
- package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +22 -30
- package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
- package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +260 -17
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
- package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5432 -194
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +51 -4
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +68 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1479 -11
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +197 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +115 -6
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +261 -29
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
- package/.flow-comet/skills/flow-comet-change/SKILL.md +10 -1
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +8 -6
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
- package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
- package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
- package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
- package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +29 -4
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
- package/README.md +5 -5
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +59 -26
- package/scripts/prepare-env.mjs +165 -1
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
package/scripts/prepare-env.mjs
CHANGED
|
@@ -26,12 +26,20 @@
|
|
|
26
26
|
* 非破坏设计(T-FIX-13,2026-08-08 用户裁决):
|
|
27
27
|
* - 默认(无 --purge):**不删除整个 .claude/(或 .agents/ / .dsh/)**——只精确覆盖生成物
|
|
28
28
|
* (rules/ + skills/ 等),保留其他一切内容(commands/、自定义 hook、自定义 skill)。
|
|
29
|
+
* - **镜像面定向清理(2026-10-09 增补:升级路径缺陷修复)**:默认模式额外删除**生成物镜像
|
|
30
|
+
* 目录内**「权威源已不存在」的条目(改名 / 移出的文件,以及随之清空的目录)——只覆盖不删除
|
|
31
|
+
* 会让它们在副本里永久残留(实测后果:安装副本跑自身回归套件报 308/309,失败信息逐条指向
|
|
32
|
+
* 残留文件,而权威源同一命令 309/309)。删除面逐条限定在本次 copyTree 的目标根
|
|
33
|
+
* (`<skillRoot>/flow-comet*`),唯一判据 = 「权威源同一相对路径上不存在同类型条目」;
|
|
34
|
+
* 白名单之外(用户自有 skill、自定义文件、无命名空间的生成面)一律不触碰;fail-closed
|
|
35
|
+
* 情形(符号链接 / 类型冲突 / 清理后仍非空 / 归属不可判定)逐条打印保留原因,绝不静默。
|
|
29
36
|
* - settings.local.json / .codex/hooks.json 采用**注入**方式:读现有配置 → 保留已有
|
|
30
37
|
* 字段 → 过滤已管理的 comet hook → 合并新 hook → 写回。不覆盖用户已有配置。
|
|
31
38
|
* - 显式 `--purge` 参数才允许删除生成物(打印删除清单 + 警告 + 需 --yes 二次确认)。
|
|
32
39
|
* - 覆盖前打印将覆盖的生成物清单。
|
|
33
40
|
*
|
|
34
|
-
* 幂等:默认模式重复运行——rules/skills
|
|
41
|
+
* 幂等:默认模式重复运行——rules/skills 覆盖一致;镜像面定向清理零残留(第二次运行零删除项、
|
|
42
|
+
* 零报错);settings/hooks 注入幂等
|
|
35
43
|
* (已管理的 comet-hook-guard 命令被过滤后重新合并,不产生重复条目);
|
|
36
44
|
* AGENTS.md 托管区幂等替换(移除旧托管区后重新生成);
|
|
37
45
|
* 运行时位置迁移幂等(旧件已搬走 → 跳过);.gitignore 纳管幂等(已有条目 → 保持原样)。
|
|
@@ -621,6 +629,156 @@ function applyPathReplacements(root, replacements) {
|
|
|
621
629
|
return replaced;
|
|
622
630
|
}
|
|
623
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
|
+
|
|
624
782
|
// ---------- 运行时文件位置迁移(旧命名空间 .comet/ → 新命名空间 .flow-comet/) ----------
|
|
625
783
|
|
|
626
784
|
/**
|
|
@@ -1555,6 +1713,12 @@ async function main() {
|
|
|
1555
1713
|
if (skillNames.length === 0) {
|
|
1556
1714
|
throw new Error(`权威源中未找到任何 flow-comet* skill 目录: ${skillsSrc}`);
|
|
1557
1715
|
}
|
|
1716
|
+
// 3.1 定向清理**先于复制**:镜像目录内「权威源已不存在」的条目(升级路径残留——见
|
|
1717
|
+
// cleanStaleMirrorEntries 的白名单与 fail-closed 说明;只覆盖不删除会让改名/移出的文件在
|
|
1718
|
+
// 副本里永久残留)。清理抛 EACCES / EPERM / EBUSY 时安装中止(错误 fatal,不吞)——此时
|
|
1719
|
+
// 尚未复制任何技能树,副本里不会留下「已复制但平台路径未替换、版本标识未写」的半成品树;
|
|
1720
|
+
// 清理判据只比对权威源与镜像现状,与复制是否已发生无关,故前置不改变删除面。
|
|
1721
|
+
cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, target);
|
|
1558
1722
|
for (const name of skillNames) {
|
|
1559
1723
|
copyTree(path.join(skillsSrc, name), path.join(skillRoot, name), stats);
|
|
1560
1724
|
stats.skills.push(name);
|
|
@@ -1,116 +0,0 @@
|
|
|
1
|
-
# flow-comet 系统测试矩阵(TEST-MATRIX)
|
|
2
|
-
|
|
3
|
-
> 定位:系统测试集(`system-test.mjs`)的设计文档——说明测试覆盖的机制面、测试载体与判定规则。
|
|
4
|
-
> 运行:`node .flow-comet/skills/flow-comet/scripts/system-test.mjs`(权威源直接跑;安装副本路径同理)。
|
|
5
|
-
|
|
6
|
-
## 一、测试载体说明
|
|
7
|
-
|
|
8
|
-
- **载体**:每个测试项 = 一个独立临时目录(`fs.mkdtemp`)+ 内置协议副本复制到 `<tmp>/reference/`(受保护路径要求协议文件位于 runRoot 内)+ **真实命令序列**(`init → record → guard entry/exit → handoff → hook` 的 `spawnSync` 调用)+ 断言退出码与输出关键词;测试项跑完 `rmSync` 清理。
|
|
9
|
-
- **与引擎回归的关系**:`guard-self-test.mjs` 是引擎脚本的单元/场景级回归(fixture 构造为主,**场景数以套件自身输出为准**);本系统测试集是**系统级**(**A~L 共十二组,项数以套件自身输出为准**)——每个测试项走真实命令链路,验证机制在真实调用序列下生效(行为锚定归场景回归,集成正确性归系统测试)。
|
|
10
|
-
- **归档源受控重入的锚登记**:引擎回归按四类锚覆盖——正例(授权全链路:备份 + 转移 + 审计事件 + 授权留痕)、负例(未授权 / 授权形态非法 fail-closed)、越界(目标白名单 / 协议 enabled / 源非 archive / 归档移动已发生 / 轮次上限)、恢复(拒绝 → 补全授权放行 → 重复同目标空操作);系统测试集由 H5~H8 覆盖真实命令链路(见 H 组)。两层锚均走 `reenter <target> --authorized-by <source> --reason <text>` 真实命令通道,判定逻辑单一权威。
|
|
11
|
-
|
|
12
|
-
> **本文件刻意不记录具体计数**:计数随场景/测试项增减而变化,而本文件不在计数一致性自检的覆盖范围内——写死数字会静默过期(本项目已因此复发多次)。以两套件的实际输出为准(`ALL n SCENARIOS PASSED` 与系统测试的汇总行)。
|
|
13
|
-
- **运行环境**:仅 node 内置模块(child_process/fs/os/path),无网络、无第三方依赖。
|
|
14
|
-
- **输出纪律**:逐项 PASS/FAIL + 汇总(`SYSTEM TEST: N/M passed`);全过 exit 0,有 FAIL exit 1。测试项命名为公开面——零过程代号。
|
|
15
|
-
|
|
16
|
-
## 二、判定规则
|
|
17
|
-
|
|
18
|
-
- **全部 PASS = 系统测试集完整通过**:与引擎回归套件(guard-self-test 全绿)构成统一测试集两级基线,方可进入下一级验证(CLI 冒烟)。
|
|
19
|
-
- **任一 FAIL**:修复后重跑(修复只改权威源一处,重跑至全绿)。
|
|
20
|
-
- **误通过 = 测试无效,必须修**:该拦截未拦截 / 该放行未放行,说明测试自身没守住机制边界——测试先于功能守边界,不许自欺("当时能过"不等于"现在正确")。
|
|
21
|
-
|
|
22
|
-
## 三、机制面覆盖矩阵(A~L 十二类)
|
|
23
|
-
|
|
24
|
-
### A. 状态机与路由
|
|
25
|
-
|
|
26
|
-
覆盖:init 全分支(状态写入/工件目录/同 id 重跑防护/分支模式)、status 节点推导与无活跃兜底、next 推进与状态漂移校正、next 未出口节点严格拦截、select 切换、advance 推进、record 基础证据、execution-mode 切换与记录、config 设置与非法值拒绝、多趟路由真实链路(并→串→交替与多波依赖)、plan 出口依赖环负例与恢复、多趟路由时序收敛、plan 出口文件依赖检出、修复回路闭环(review/verify 源受控归位 execute → 四类出口 → 回源节点出口;回程审计行按证据分为真实修复锚、正常多趟中性回程、旧态证据不足未分类三态;越界拦截与旧 change 渐进)。
|
|
27
|
-
|
|
28
|
-
测试项:A1 init 状态写入与工件目录创建 / A2 init 分支模式与非法前缀拒绝 / A3 init 同 id 重跑防护 / A4 status 节点推导与无活跃兜底 / A5 next 推进与状态漂移校正(进行中节点保护由引擎回归覆盖)/ A6 next 未出口节点严格拦截 / A7 select 切换与缺失拒绝 / A8 advance 节点推进 / A9 record 基础证据记录 / A10 execution-mode 切换与记录 / A11 config 配置与非法值拒绝 / A12 验证失败计数按 change 隔离(切换 change 后计数独立)/ A13 多趟路由真实链路(并→串→交替与多波依赖,NODE 行多次交替直至全部 done;正常多趟收尾输出中性回程行且不出现修复回程锚)/ A14 plan 出口依赖环负例(BLOCK 含 depends_on 恢复指引,按指引调环后恢复通过)/ A15 多趟路由时序收敛(逐节点 exit 后 next NODE 与 guard 出口 NODE 一致)/ A16 plan 出口文件依赖检出(写写重叠 BLOCK 与恢复 + 读写弱判 WARN)/ A17 多趟平行转换后 next 可达(各转换点 next NODE 与 guard 出口 NODE 一致)/ A18 漂移容忍 exit(execute 欠账经容错路径补齐)/ A19 路由诊断静默扩展(P→S 收尾无噪音 / 畸形块仍报)/ A20 directOverride 授权约束(自切 direct 无授权 BLOCK / 协调者授权通过) / A21 review 源 Fix 闭环:next 归位 execute → 出口回源 review → 审查出口真实执行;真实修复保留可检索回程锚(真实命令) / A22 verify 源 Fix 回程:回 verify 而非跳过 archive + verify 出口真实执行(真实命令) / A23 Fix 越界拦截与旧 change 渐进:源节点直接 exit BLOCK(新)/WARN(旧)不卡死;多波次修复、源节点未进入、旧态证据不足输出中性未分类回程的归因子场景(真实命令)。
|
|
29
|
-
|
|
30
|
-
### B. 声明机制
|
|
31
|
-
|
|
32
|
-
覆盖:skill-load 声明标记写入(协议归属)、非法参数拒绝不落标记、record 缺声明标记拦截、声明后记录通过、声明时间序自洽、损坏声明标记 fail-closed、委托范围条目豁免(有委托通过/无委托拦截)、exit 协议声明标记校验(真实链路通过/无标记·空协议·损坏拦截)、旧项目兼容(未激活声明机制照常通过)。
|
|
33
|
-
|
|
34
|
-
测试项:B1 声明标记写入 / B2 非法参数拒绝 / B3 缺声明标记拦截 / B4 声明后记录通过 / B5 声明时间序自洽 / B6 损坏标记 fail-closed / B7 委托范围条目豁免 / B8 exit 协议声明标记校验 / B9 旧项目兼容。
|
|
35
|
-
|
|
36
|
-
### C. 委托链路
|
|
37
|
-
|
|
38
|
-
覆盖:handoff 请求/结果/状态全链路(含提交校验与零提交资格——输出为空或全部可证明被 gitignore 可合法闭环;glob / 越界 / 非 git / tracked 的零提交声明一律拒绝,不得绕过提交子集校验、拦截时 state 字节零改写)、红绿证据时间序(先红后绿通过/补录拦截)、委托后 exit 证据键名契约与契约校验(通过/空交接拦截)。
|
|
39
|
-
|
|
40
|
-
测试项:C1 handoff 全链路(含零提交资格正例与越权负例)/ C2 红绿证据时间序 / C3 委托后 exit 契约校验。
|
|
41
|
-
|
|
42
|
-
### D. hook 写白名单
|
|
43
|
-
|
|
44
|
-
覆盖:open 阶段工件放行与源码拦截、execute 按执行模式收窄(subagent 只写 .specs/,direct 放宽)、归档阶段白名单与完成态放行。
|
|
45
|
-
|
|
46
|
-
测试项:D1 open 阶段白名单 / D2 execute 执行模式收窄 / D3 归档阶段白名单与完成态放行。
|
|
47
|
-
|
|
48
|
-
### E. 自定义协议
|
|
49
|
-
|
|
50
|
-
覆盖:自定义协议加载路由与节点推导(`--protocol`/env 加载)、自定义节点声明机制与出口全链路(含技能绑定)、内置特化校验对自定义协议不误触发。
|
|
51
|
-
|
|
52
|
-
测试项:E1 加载路由与节点推导 / E2 声明机制与出口全链路。
|
|
53
|
-
|
|
54
|
-
### F. 自动初始化
|
|
55
|
-
|
|
56
|
-
覆盖:上下文缺失提示且不自动生成、跳过记忆、新鲜上下文静默、生成协作全链路(7 段校验 + 扫描时间记录)。
|
|
57
|
-
|
|
58
|
-
测试项:F1 上下文缺失提示 / F2 跳过记忆 / F3 新鲜上下文静默 / F4 生成协作全链路。
|
|
59
|
-
|
|
60
|
-
### G. 分支模式
|
|
61
|
-
|
|
62
|
-
覆盖:init 建分支与一致性、归档入口分支校验、分支一致性失配警告。
|
|
63
|
-
|
|
64
|
-
测试项:G1 init 建分支与一致性 / G2 归档入口分支校验 / G3 一致性失配警告。
|
|
65
|
-
|
|
66
|
-
### H. verify 与归档
|
|
67
|
-
|
|
68
|
-
覆盖:验证命令真实执行与超时配置、归档完整流程(遗留清单 + 目录移动 + 完成态)、归档路径声明标记查找(先移目录后 exit 顺序下标记只存归档路径)、归档源受控重入真实命令链路(未授权 / 授权形态非法 fail-closed 且状态字节零改写;完整授权转移 + 嵌套证据 + 审计事件 + 备份指纹;幂等重放零改写与按备份手工回滚;轮次上限后 BLOCK 与人工裁决指引)、受控计划重校(replan)真实命令链路(任务集修订后出口被签名门禁 BLOCK 且零改写 → 授权 replan 重签 → 出口放行并正常路由;未授权 / 轮次不足 fail-closed 且零改写、上限后 BLOCK 与显式续轮放行)、强制推进留痕(advance 写 advance-forced 事件 + `status.forcedNodes` 派生可见)。
|
|
69
|
-
|
|
70
|
-
测试项:H1 验证命令真实执行与超时 / H2 归档完整流程 / H3 归档路径声明标记查找 / H4 归档后自动补声明标记写归档路径(不重建活动目录) / H5 受控重入:未授权调用 fail-closed 且状态字节零改写 / H6 受控重入:完整授权链路(转移 + 嵌套证据 + 审计事件 + 备份指纹 + 审计行) / H7 受控重入:幂等重放零改写与按备份手工回滚可执行 / H8 受控重入:上限 BLOCK、显式授权续轮与重入后闭环组合链路(真实命令) / H9 replan 解死锁:execute 相位修订任务集(含并行就绪任务)→ 重签 → 出口放行 → next 正常路由 / H10 replan 授权 fail-closed 与轮次上限:未授权零改写 · 第 4 次 BLOCK · 显式续轮放行(真实命令) / H11 advance 留痕:advance-forced 事件 + status.forcedNodes 派生可见(真实命令)。
|
|
71
|
-
|
|
72
|
-
### I. 异常路径
|
|
73
|
-
|
|
74
|
-
覆盖:损坏状态文件 fail-closed、缺工件出口拦截、非法参数拒绝、状态字段类型非法拦截。
|
|
75
|
-
|
|
76
|
-
测试项:I1 损坏状态文件 fail-closed / I2 缺工件出口拦截 / I3 非法参数拒绝 / I4 状态字段类型非法拦截。
|
|
77
|
-
|
|
78
|
-
### J. 文档一致性
|
|
79
|
-
|
|
80
|
-
覆盖:双语健康检查(英文文档零中文/中文文档零英文长句/双语镜像对称/版本场景数)、公开产物零代号检查(调用仓库本地工具;安装副本无仓库文档跳过)。注:本地工具为发布快照——开发窗口期场景数一致性子检查按结构检查放行,权威判定在引擎自测。
|
|
81
|
-
|
|
82
|
-
测试项:J1 双语健康检查 / J2 公开产物零代号检查。
|
|
83
|
-
|
|
84
|
-
### K. 安装器(版本标识 + 多平台)
|
|
85
|
-
|
|
86
|
-
覆盖:prepare-env 生成的版本标识(优先源仓库 git describe:发布版 = 精确 tag、开发态 = `<tag>-N-g<hash>`;无 git 时回退权威源随技能包分发的 INSTALLED_VERSION)精确反映源仓库状态;权威源文件与 CHANGELOG 首个版本段一致(CI release-consistency 同规则);多平台安装(平台描述符驱动:claude-code 默认零变化 / codex——技能落 `.agents/skills/`、SKILL 命令路径平台化替换、`.codex/hooks.json`(顶层 hooks 包裹层 + matcher `*`)注入、`config.toml [features] hooks` 启用、AGENTS.md 托管区、纯 codex 不生成 `.claude/`);hook 平台分支输出契约(codex = `{"decision":"block"}` deny 通道 + Bash 命令写入检测(PowerShell cmdlet / .NET File API / 重定向)、放行 `{}`;claude-code 文本输出不变);平台选择链(`--platform` 显式 / TTY 交互 / 无 TTY 探测 `.codex/`·`.claude/` / 默认 claude-code);purge 语义(缺 `--yes` 拒绝 / 重建 / 用户内容保留);平台描述符驱动防回归(main 统一调度——源码无平台分支标识,安装/清理逻辑全部封装在描述符条目;从源码提取平台逐一安装冒烟,未来新增平台自动纳入测试);dsh 平台面(三平台桥接——技能落 `.dsh/skills/`、路径替换/版本标识/AGENTS.md 托管区/purge 清理/桥接 loader 纯函数与流程态门/版本戳重装断言;分发面环境判据:权威源形态真跑完整断言,安装副本形态显式「不适用」并按结果标记计通过,不静默跳过)。
|
|
87
|
-
|
|
88
|
-
测试项:K1 安装器版本标识 / K2 codex 平台安装冒烟(技能/路径替换/hooks.json/AGENTS 托管区 + 非法 hooks.json fail-safe)/ K3 hook 平台分支 JSON 契约 + CC 分支不变 / K4 平台选择链(显式/无 TTY 探测/默认/未知平台拒绝)/ K5 purge 语义(缺 --yes 拒绝/重建/用户内容保留)/ K6 平台描述符驱动(全平台安装冒烟 + main 统一调度断言)/ K7 dsh 平台安装(技能/pathReplacements/版本标识/树一致)/ K8 dsh AGENTS.md 托管区(用户内容保留 + 幂等重装)/ K9 桥接 loader 源文件/语法/复制与托管块注入(读-合并-写)/ K10 dsh purge 清理恢复(缺 --yes 拒绝/删除后重建/用户内容保留/空目录清理)/ K11 桥接 loader 纯函数与 apply 分派断言(映射/包含性/退出映射/身份分派)/ K12 桥接 loader 流程态门断言(无 state/无 activeChange/completed 放行 · 非法 JSON/未知 status deny)/ K13 hook 注入形态无关断言(basename+项目根引用)+ 旧条目幂等升级 / K14 桥接 loader 版本戳重装断言(升级/降级方向与覆盖后新戳)+ dev 态载体 bridge-check 基础版本比较(剥离开发态后缀后同基础健康 / 基础版本失配仍 FAIL);分发面环境判据:权威源形态真跑,安装副本形态显式「不适用」并按结果标记计通过(不静默跳过)/ K15 桥接 loader 同源重装断言(首次安装后版本一致)/ K16 桥接 loader purge 后重建路径回归(loader 恢复与再装收敛)/ K17 状态迁移(旧布局项目安装后状态可读且流程可继续)/ K18 分发面(环境判据与包体边界 + bin 双入口——权威源真跑/副本显式不适用 + init 词元红线)。
|
|
89
|
-
|
|
90
|
-
### L. 执行遗漏防护(真实链路)
|
|
91
|
-
|
|
92
|
-
覆盖:进入证据(entry 记录 enteredNodes、正常流程 exit 无误报——真实链路中节点顺序检查先于进入警告,未 entry 场景由引擎回归覆盖)、空退出豁免(显式 emptyExitApproved 通过 / 无豁免仍拦截)、空仓库提示(init 在无提交仓库输出 EMPTY-REPO)。
|
|
93
|
-
|
|
94
|
-
测试项:L1 进入证据 / L2 空退出豁免 / L3 空仓库。
|
|
95
|
-
|
|
96
|
-
## 四、附:design 节点 required 自指核验结论
|
|
97
|
-
|
|
98
|
-
**核验对象**:`workflow-protocol.json` 的 design 节点——`requiredSkillCalls` 含与 `implementation` 相同的技能(自指),对照 open / review 两模式核验(遗留核验项)。
|
|
99
|
-
|
|
100
|
-
**三模式对照**:
|
|
101
|
-
|
|
102
|
-
| 节点 | implementation | requiredSkillCalls | 含自身? |
|
|
103
|
-
|---|---|---|---|
|
|
104
|
-
| open | flow-comet-open | flow-comet-change, flow-comet-requirement | 否 |
|
|
105
|
-
| design | flow-comet-design | flow-comet-design, flow-comet-ui-design | 是 |
|
|
106
|
-
| review | flow-comet-review | flow-comet-review, flow-comet-test | 是 |
|
|
107
|
-
|
|
108
|
-
**结论:设计如此,非缺陷。** 理由:
|
|
109
|
-
|
|
110
|
-
1. **协议承载型入口 vs 纯壳编排**:design 与 review 的入口技能即协议本体(flow-comet-design 承载 DESIGN 阶段协议,flow-comet-review 承载 REVIEW 阶段协议),其 `required` 列表 = 执行者必须加载并声明的协议技能集合,含自身是「入口即协议承载」的自然形态。open 是纯壳编排者(flow-comet-open 自身无协议文件,协议由 flow-comet-change / flow-comet-requirement 两个独立技能承载),故 required 不含自身——open 若含自身反而无法声明(没有对应协议文件可声明)。
|
|
111
|
-
2. **required 自条目是加载声明的载体**:执行者加载 flow-comet-design 后运行 `skill-load design flow-comet-design --prompt flow-kit/prompts/2-design.md` 写入声明标记——该标记同时满足记录校验(required-skill 条目须有对应标记)与节点 exit 的协议声明校验(design 节点要求 2-design.md 标记),两处复用同一文件,机械上自洽。
|
|
112
|
-
3. **review 同构佐证**:review 的 required(flow-comet-review + flow-comet-test)与其节点协议文件集(6-review.md + 5-test.md)一一对应——两个节点同构,是设计而非偶发。
|
|
113
|
-
4. **与 plan 节点修正不同类**:plan 节点那次修正的缺陷在 `implementation` 字段指向错误(指向协议技能而非节点入口技能),修正后确立「implementation = 节点入口、required = 需加载声明的协议技能」语义——design 的 implementation 指向正确,required 含自身不违反该语义。
|
|
114
|
-
5. **机械上无害**:required 条目在节点 exit 时自动补全,不产生额外拦截;删除反而破坏上述声明载体对应关系。
|
|
115
|
-
|
|
116
|
-
**边界**:若未来把 design 重构为「壳 + 独立协议技能」双层结构(同 open),required 自条目随结构自然去除;当前形态保持,无需修复。
|
|
@@ -1,65 +0,0 @@
|
|
|
1
|
-
# Composition Report
|
|
2
|
-
|
|
3
|
-
## Workflow Contract
|
|
4
|
-
|
|
5
|
-
- Kind: workflow-kernel
|
|
6
|
-
- Nodes: 8
|
|
7
|
-
- Required Skill Calls: 11
|
|
8
|
-
- Output Schemas: flowkit.intake.v1, flowkit.design.v1, flowkit.plan.v1, flowkit.execution.v1, flowkit.handoff.v1, flowkit.review.v1, flowkit.verify.v1, flowkit.archive.v1
|
|
9
|
-
- Wrapper classification: kernel-authored
|
|
10
|
-
|
|
11
|
-
## Source Skills
|
|
12
|
-
|
|
13
|
-
- flow-comet-open
|
|
14
|
-
- flow-comet-change
|
|
15
|
-
- flow-comet-requirement
|
|
16
|
-
- flow-comet-design
|
|
17
|
-
- flow-comet-ui-design
|
|
18
|
-
- flow-comet-task
|
|
19
|
-
- flow-comet-execute
|
|
20
|
-
- flow-comet-dev
|
|
21
|
-
- flow-comet-subagent-execute
|
|
22
|
-
- flow-comet-review
|
|
23
|
-
- flow-comet-test
|
|
24
|
-
- flow-comet-verify
|
|
25
|
-
- flow-comet-integration
|
|
26
|
-
- flow-comet-archive
|
|
27
|
-
|
|
28
|
-
## Composition Steps
|
|
29
|
-
|
|
30
|
-
- step-1: flow-comet-open (atomic)
|
|
31
|
-
- step-2: flow-comet-change (atomic)
|
|
32
|
-
- step-3: flow-comet-requirement (atomic)
|
|
33
|
-
- step-4: flow-comet-design (atomic)
|
|
34
|
-
- step-5: flow-comet-ui-design (atomic)
|
|
35
|
-
- step-6: flow-comet-task (atomic)
|
|
36
|
-
- step-7: flow-comet-execute (atomic)
|
|
37
|
-
- step-8: flow-comet-dev (atomic)
|
|
38
|
-
- step-9: flow-comet-subagent-execute (atomic)
|
|
39
|
-
- step-10: flow-comet-review (atomic)
|
|
40
|
-
- step-11: flow-comet-test (atomic)
|
|
41
|
-
- step-12: flow-comet-verify (atomic)
|
|
42
|
-
- step-13: flow-comet-integration (atomic)
|
|
43
|
-
- step-14: flow-comet-archive (atomic)
|
|
44
|
-
|
|
45
|
-
## Resolved Skills
|
|
46
|
-
|
|
47
|
-
- flow-comet-open: available
|
|
48
|
-
- flow-comet-change: available
|
|
49
|
-
- flow-comet-requirement: available
|
|
50
|
-
- flow-comet-design: available
|
|
51
|
-
- flow-comet-ui-design: available
|
|
52
|
-
- flow-comet-task: available
|
|
53
|
-
- flow-comet-execute: available
|
|
54
|
-
- flow-comet-dev: available
|
|
55
|
-
- flow-comet-subagent-execute: available
|
|
56
|
-
- flow-comet-review: available
|
|
57
|
-
- flow-comet-test: available
|
|
58
|
-
- flow-comet-verify: available
|
|
59
|
-
- flow-comet-integration: available
|
|
60
|
-
- flow-comet-archive: available
|
|
61
|
-
|
|
62
|
-
## Preferences
|
|
63
|
-
|
|
64
|
-
- Preference mode: not configured
|
|
65
|
-
- Preference hash: none
|
|
@@ -1,184 +0,0 @@
|
|
|
1
|
-
# dsh 平台锚定参考(dsh-platform)
|
|
2
|
-
|
|
3
|
-
> 维护者参考文档:dsh 平台适配的版本锚定、安装形态、API 签名、桥接 loader 契约与验证记录模板。
|
|
4
|
-
> 权威依据:`@.specs/archive/2026-08-18-deepseek-harness-platform/DESIGN.md`(D1~D10 / 7.1 / 7.2 / 7.3)、`@.specs/archive/2026-08-18-deepseek-harness-platform/REQUIREMENT.md`(AC-1~AC-7)、`@.specs/adr/ADR-005-dsh-install-via-installer.md`。
|
|
5
|
-
> dsh 为 dev-preview:本文件锚定认证版本(0.1.7-rc.2,2026-09-27 全接缝重认证;历史锚 0.1.0-rc.6 → 0.1.1-rc.2 → 0.1.5-rc.1);破坏性变更风险显式声明。
|
|
6
|
-
|
|
7
|
-
## 1. 版本锚定
|
|
8
|
-
|
|
9
|
-
| 项 | 值 |
|
|
10
|
-
|---|---|
|
|
11
|
-
| 认证 dsh 版本 | `0.1.7-rc.2`(2026-09-27 全接缝重认证;历史锚 `0.1.0-rc.6` → `0.1.1-rc.2` → `0.1.5-rc.1`) |
|
|
12
|
-
| 安装入口 | `node scripts/prepare-env.mjs --target <项目> --platform dsh`(或交互终端多选勾选 dsh)——唯一入口(D1) |
|
|
13
|
-
| 重置/重新生成(purge——删除后重建到完整安装态,**不是卸载**) | `node scripts/prepare-env.mjs --target <项目> --purge --platform dsh --yes` |
|
|
14
|
-
| npm 包 | **自 `1.5.0-rc.3` 起已发布**(`npm i -g flow-comet` → `fcomet init`,dist-tag `latest`)——分发的为**安装器**,非 dsh 插件包;旧 npm 插件包安装形态已废弃(verify 阶段推翻,见 ADR-005) |
|
|
15
|
-
| 破坏性变更 | dev-preview 中 `tools/pre-execute` 签名 / skill 发现 rank / `DSH_HOME` 语义可能变化;低于锚定版本时拦截/发现可能失效 |
|
|
16
|
-
|
|
17
|
-
> 版本不匹配时拦截可能失效——必须文档警示 + 真实平台会话实测兜底(D9)。
|
|
18
|
-
|
|
19
|
-
**bridge-check 版本比较语义(基础版本比较)**:桥接健康检查比较 loader 的 `// BRIDGE_VERSION:` 发布戳与技能包 `INSTALLED_VERSION` 时,两侧先剥离 git-describe 开发态后缀 `-<领先提交数>-g<hash>`、再按基础版本比较:
|
|
20
|
-
|
|
21
|
-
- 开发态载体的 `INSTALLED_VERSION = <发布版本>-<N>-g<hash>` 是预期形态、不构成版本偏斜——与同基础版本的 loader 判健康(exit 0)。
|
|
22
|
-
- 语义化预发布标识(如 `1.5.0-rc.3`)不是开发态后缀、不剥离——预发布与基础版本不可互相放行。
|
|
23
|
-
- 归一后基础版本不同(含发布版对发布版)仍报「版本偏斜」并 exit 1;失配报告同时打印原始值与归一值,便于识别 dev 态后缀。
|
|
24
|
-
- loader 戳生成与发布同步纪律不变(发布戳仍取当前发布版本,随发布同步更新)。
|
|
25
|
-
|
|
26
|
-
## 2. tools/pre-execute 签名
|
|
27
|
-
|
|
28
|
-
```js
|
|
29
|
-
ctx.on('tools/pre-execute', async (exec, next) => {
|
|
30
|
-
// exec: ToolExecution
|
|
31
|
-
// { callId, name, arguments, signal, agent?, parent? }
|
|
32
|
-
// 放行: return next();
|
|
33
|
-
// 拒绝: return { kind: 'deny', reason: '…' };
|
|
34
|
-
// 询问: return { kind: 'ask', reason? };
|
|
35
|
-
});
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
- PreToolDecision 形状:`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`;deny 必须带 `kind` 字段。
|
|
39
|
-
- 不调 `next()` 即否决(waterfall 事件——监听方不续传则工具被短路)。
|
|
40
|
-
- 会话 cwd 锚定:`exec.agent.session.header.cwd`(逐会话;缺失时逐级回退 exec 上下文其它路径字段——见桥接 loader sessionCwd;Web UI 切换 workspace 时按会话判定,非进程 cwd)。
|
|
41
|
-
|
|
42
|
-
## 3. skill 发现(文件系统级——取代 provider 注册模型)
|
|
43
|
-
|
|
44
|
-
- dsh skill 发现 rank 区间 100~500;**rank 100(最高)= `<项目根>/.dsh/skills`**(0.1.0-rc.6 源码核实)——目录存在于项目根下即自动发现(chokidar 热发现,免重启);未安装该目录的项目不可见该 skill → **天然项目级**(无运行时痕迹判定、无 chicken-and-egg)。
|
|
45
|
-
- 项目根 = 会话 cwd 的最近 `.git` 祖先(`.git` 可为目录或文件——worktree/submodule 形态)。
|
|
46
|
-
- 旧 provider 注册模型(`ctx.skills.registerProvider`)已废弃——skill 不再运行时注册,由文件系统发现 + 安装器物理安装(D3/D6)。
|
|
47
|
-
|
|
48
|
-
## 4. DSH_HOME 与 home patch
|
|
49
|
-
|
|
50
|
-
- `DSH_HOME` 解析(与 dsh CLI 同款默认,**两态**):`$DSH_HOME` 环境变量 > `~/.dsh`。dsh-home-paths 库 API 支持显式配置参数(configured),但 dsh CLI 0.1.0-rc.6 实际无参调用(profile-boot 调 `resolveDshHome()` 不传 configured),该层不生效;prepare-env 安装器与 dsh CLI 行为一致(两态)。
|
|
51
|
-
- **`DSH_` 前缀 bootstrap-only**:项目 `.env` 中设置 `DSH_HOME` 被直接拒绝——`.env` 方案不可行,文档明确不推荐(ADR-005 源码实证)。
|
|
52
|
-
- `$DSH_HOME/cordis.patch.yml` 为 home 级 patch,对所有 profile 生效——dsh 加载链 `bundles → profile → home → overlays`(ADR-005 源码核实)。
|
|
53
|
-
- flow-comet 托管块:`# --- flow-comet managed ---` … `# --- end flow-comet managed ---`,内容为 **insert 形态**(无 id 顶层 `- insert:` 条目内嵌插件行——追加到条目列表,而非覆盖既有条目):
|
|
54
|
-
|
|
55
|
-
```yaml
|
|
56
|
-
# --- flow-comet managed ---
|
|
57
|
-
- insert:
|
|
58
|
-
- id: dsh-flow-comet-bridge
|
|
59
|
-
name: 'file:///<loader 绝对路径>'
|
|
60
|
-
# --- end flow-comet managed ---
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
- **机制事实(为何必须 insert 形态)**:cordis.patch.yml 是 **id-targeted patch 层**——dsh-app-boot 的 `applyEntryPatches` 对 `{id, ...overrides}` 仅能覆盖已存在条目,id 不存在报 `entry not found` 跳过(旧 `- id: … + name:` patch 形态对不存在的 id 即跳过,loader 从不加载——拦截整链静默失效);**新增插件必须用无 id 顶层 `- insert:` 条目**。读-合并-写保留既有块;文件存在但内容无法识别为 YAML → fail-safe 报错退出不覆盖。
|
|
64
|
-
|
|
65
|
-
## 5. fs/write-intent(single-slot 守卫瀑布)
|
|
66
|
-
|
|
67
|
-
```ts
|
|
68
|
-
(target: FsTarget, actor: object | undefined, next) => FsWriteIntent | undefined
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
- 决策形状:`{kind:'createIfAbsent'}` | `{kind:'replaceIfVersion', version}`——守卫,**无 deny 决策面**。
|
|
72
|
-
- single-slot:first-wins by registration order。
|
|
73
|
-
- **flow-comet 不注册该槽位**(避免 shadow 官方 `dsh-fs-observation-policy` 的 freshness 检查);拦截能力由 `tools/pre-execute` 全覆盖(D6)。
|
|
74
|
-
- `fs/observed` 审计通道设计上不采用(v1 桥接 loader 极薄——D6;v2 可按需加)。
|
|
75
|
-
|
|
76
|
-
## 6. 安装 / 激活 / 重置(prepare-env 平台描述符——唯一入口)
|
|
77
|
-
|
|
78
|
-
### 安装
|
|
79
|
-
|
|
80
|
-
- 正式:`node scripts/prepare-env.mjs --target <项目> --platform dsh`。
|
|
81
|
-
- 多平台:`--platform claude-code,dsh`(逗号分隔,按参数顺序安装)/ `--platform all`(全部平台,按 PLATFORMS 表顺序:claude-code → codex → dsh);旧 `both` 已移除——`--platform both` 报错并提示用逗号列表或 all;未知平台报错(含逗号列表中的未知项——不得部分安装)。
|
|
82
|
-
- 交互(缺省选择链):显式 `--platform` > TTY 交互多选 > 探测 > 默认 claude-code。TTY 多选 = @clack/prompts 方向键多选(可选依赖,未安装自动回退 readline 数字/逗号多选),按目标项目痕迹 `.claude/`/`.codex/`/`.dsh/` 预勾选,回车默认 = 探测推荐;无 TTY 探测:仅 `.codex/` → codex、仅 `.dsh/` → dsh、含 `.claude/` → claude-code、皆无 → 默认 claude-code;多痕迹(≥2 并存)不武断二选一——默认主平台 claude-code 并输出提示。
|
|
83
|
-
- 安装动作(dsh 描述符):
|
|
84
|
-
1. `installHooks`:复制 `scripts/dsh-bridge.mjs` → `$DSH_HOME/plugins/dsh-flow-comet-bridge.mjs`(全局挂载——home patch 对所有 profile 生效)+ `$DSH_HOME/cordis.patch.yml` 托管块注入(读-合并-写,保留既有块;源文件缺失时 WARN 同时跳过 loader 复制与托管块注入(避免注入指向不存在文件的 file:// 引用),其余安装照常
|
|
85
|
-
2. `installRules`:AGENTS.md 托管区注入(`<!-- Managed by flow-comet prepare-env -->` … `<!-- /Managed by flow-comet prepare-env -->` 包裹编排规则全文;非破坏合并,保留托管区外用户内容;codex/dsh 共用标记——任一平台的移除流程均可清理该区)。
|
|
86
|
-
3. skills:复制权威源 `skills/flow-comet/**` → `<项目>/.dsh/skills/flow-comet/` + pathReplacements(包内命令路径 `.claude/skills/flow-comet/scripts/` → `.dsh/skills/flow-comet/scripts/`,仅 .md,幂等)+ INSTALLED_VERSION 版本标识。
|
|
87
|
-
|
|
88
|
-
### 激活(天然项目级)
|
|
89
|
-
|
|
90
|
-
- 目录物理存在即激活——dsh 启动自动发现 `/flow-comet`(rank 100,chokidar 热发现免重启);未安装该目录的项目不可见(无痕迹判定、无 chicken-and-egg)。
|
|
91
|
-
- dsh 对项目 AGENTS.md 的注入行为**已认证**(0.1.7-rc.2 headless 会话:项目根 AGENTS.md 作为上下文注入,托管区内容被会话逐字引用——见下方认证记录);**边界**:认证面向 headless profile,dsh-tui / web 运行时未验。
|
|
92
|
-
|
|
93
|
-
### 重置/重新生成(prepare-env --purge --yes——删除后重建,**不是卸载**)
|
|
94
|
-
|
|
95
|
-
- `node scripts/prepare-env.mjs --target <项目> --purge --platform dsh --yes`:**先删除生成物、随后重新生成**(与 claude-code/codex 平台同一 main 模式):
|
|
96
|
-
1. 删 `<项目>/.dsh/skills/` 下全部 `flow-comet*` 条目(非 flow-comet 条目保留)+ 空 `.dsh` 目录(有内容保留)。
|
|
97
|
-
2. AGENTS.md 托管区移除(保留文件与用户内容)——重建流程随后重新注入新托管区(purge = 移除旧生成物后重建)。
|
|
98
|
-
3. `$DSH_HOME/cordis.patch.yml` 托管块移除(保留 dsh-skin 等既有块;移除后文件为空 → 删除文件本身)+ `$DSH_HOME/plugins/dsh-flow-comet-bridge.mjs` 删除——重建流程随后重新挂载 loader。
|
|
99
|
-
- **重置 ≠ 卸载(安全面警示)**:purge 后 flow-comet **仍完整安装**——skill 重新生成、AGENTS.md 托管区重新注入、全局 loader 继续挂载(所有 profile 拦截恢复)。用户想「卸载」而执行 purge 会得到完整安装态,不是移除。
|
|
100
|
-
- **真实卸载需手动**(purge 不是卸载途径):删 `<项目>/.dsh/skills/flow-comet*` + AGENTS.md 托管区(`<!-- Managed by flow-comet prepare-env -->` … `<!-- /Managed by flow-comet prepare-env -->`)+ `$DSH_HOME/cordis.patch.yml` 托管块 + `$DSH_HOME/plugins/dsh-flow-comet-bridge.mjs`;AGENTS.md 与 cordis.patch.yml 的托管区/托管块之外的用户内容保留。
|
|
101
|
-
- 多项目语义:每项目独立安装 skill(未安装项目不可见);loader 全局一份(按会话项目判定——与 claude-code 项目级 hook 等价);同一 loader 服务多个 flow-comet 项目。
|
|
102
|
-
|
|
103
|
-
## 7. 桥接 loader 契约($DSH_HOME/plugins/dsh-flow-comet-bridge.mjs)
|
|
104
|
-
|
|
105
|
-
- 形态:dsh 官方插件形态——ESM 模块导出 `{ name: 'dsh-flow-comet-bridge', apply(ctx) }`,ctx 由 dsh 注入;纯 ESM 零第三方依赖;模块级幂等(同进程重复 apply 跳过已注册监听)。
|
|
106
|
-
- 职责链:`tools/pre-execute` 监听 → 会话项目判定 → 参数映射 → 流程态门 → 包含性校验 → 子进程调项目本地 guard → 决策映射。
|
|
107
|
-
1. **窄监听(硬性契约)**:工具名归一化(非 Write/Edit/Bash 直接 `next()`);会话 cwd(`exec.agent.session.header.cwd` 锚定,缺失回退)的最近 `.git` 项目根下**存在 `.dsh/skills/flow-comet` 才处理**,否则直接 `next()`——非 flow-comet 项目零拦截零开销(D6/R7)。
|
|
108
|
-
2. **参数映射(fail-closed)**:dsh 工具名归一化到 guard CLI 契约名(Write/Edit/Bash;别名:write/writefile/file-write、edit/editfile/file-edit、bash/shell/powershell/pwsh/run_command/run-command);Write/Edit → `file_path`、Bash → `command`;形状不符/缺关键字段 → WARN + fail-closed deny(不静默放行)。
|
|
109
|
-
3. **流程态门(B 方案——包含性仅运行中生效)**:读项目根 `.flow-comet/flow-comet-state.json`(UTF-8 BOM 容错;判定规则锚定 guard `comet-hook-guard.mjs` 的空闲态门——grep 锚点:`grep -n "if (!state.activeChange)"`):空闲(无 state / 无 `activeChange` / `status==='completed'`)→ 直接 `next()` 放行——跳过包含性校验与 guard 白名单(与 Claude Code / Codex 的 active-change 门语义对齐);解析失败 / 未知 status → WARN + fail-closed deny(不视为空闲放行);`activeChange` 存在且 `status==='running'` 或缺失(undefined)→ 继续下方包含性校验与 guard(现状不变)。
|
|
110
|
-
- **空闲边界(refined)**:空闲 = 无 state / 无 activeChange / status==='completed' → 项目外写 next() 放行;解析失败 / 未知 status 保持 fail-closed deny(不视为空闲),与 Claude Code / Codex 的 guard 语义一致。
|
|
111
|
-
4. **包含性校验**:Write/Edit 的 `file_path` 必须解析后位于项目根内——`realpathSync.native` 展开 Windows 8.3 短路径(词法 path.relative 会把项目内短路径误判为越界);**运行中**越界直接 deny(不进 guard——guard 侧 target=null 会跳过白名单判定 = fail-open);通过后传规范化长路径。
|
|
112
|
-
5. **代理身份分派(B1——dsh 子代理=执行者)**:读 `exec.agent.session.header.delegationDepth`(`agentDepth(exec)` 纯函数)——**>0 = 子代理(执行者)→ 跳过 guard 白名单判定直接 `next()` 放行**(子代理写源码是执行者职责,对应 Claude Code worktree 子代理物理自由写;形状 fail-closed 与项目根包含性校验已在上方对子代理同样执行,不因身份放宽);**0/缺失 = 协调者 → 走 guard 白名单判定**(协调者禁令物理拦截保留)。dsh 子代理系统在 dsh-base 自带(`tool-subagent`/`subagent-spawn-in-process` 等,headless/web/tui 全 profile 激活),`childSessionMeta` 写入 delegationDepth=parentDepth+1(dsh-subagent 源码锚定 rc.6);不识别此字段会导致 subagent 执行模式下子代理写源码被 guard 白名单(execute → `.specs/`)误拦(B1,项目内验证记录实证)。真实平台会话实测(2026-08-18):真实模型调 subagent → 子代理(delegationDepth:1)写 `scripts/` 放行、协调者(delegationDepth:0)写同路径被 deny 保留。
|
|
113
|
-
6. **判定调用**:`spawn node <项目根>/.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs before_tool`,stdin JSON `{tool_name, tool_input}`;**spawn cwd 必须 = 会话项目根的长形态规范化(硬性)**(相对 file_path 按 cwd 解析,cwd≠项目根 = fail-open;8.3 短形态项目根若原样传入、而 file_path 已归一化为长形态时,guard 词法 path.relative 得 target=null → 白名单跳过 = fail-open——桥接修复已关闭,系统测试 K11 断言锁定;不得以设 env 替代 cwd);guard 文件缺失(安装未完成/被删除)→ WARN + `next()` 放行(不阻断非 flow-comet 语义);spawn 异常 → fail-closed deny + WARN。
|
|
114
|
-
7. **决策映射**:exit 0 → `next()` 放行;exit 2 → `{kind:'deny', reason}`(BLOCK 消息 + 恢复指引透传);其它/异常 → fail-closed deny + WARN。
|
|
115
|
-
- 协议文件:天然在项目内(skill 包 `reference/` 随树复制)——受保护读取满足,**无 FLOW_COMET_PROTOCOL 机制**。
|
|
116
|
-
- 明确不做(D6——旧完整插件功能废弃):不注册 `fs/write-intent` 槽位;不做 `fs/observed` 审计;不做技能注册/AGENTS.md 运行时注入(安装器职责)。
|
|
117
|
-
|
|
118
|
-
## 8. 验证记录模板
|
|
119
|
-
|
|
120
|
-
> 实测执行后按此模板回填;发布前逐项闭环(DESIGN 7.3)。
|
|
121
|
-
|
|
122
|
-
### 环境
|
|
123
|
-
|
|
124
|
-
- 日期:
|
|
125
|
-
- dsh 版本:
|
|
126
|
-
- prepare-env / 仓库版本:
|
|
127
|
-
- profile:
|
|
128
|
-
- 临时项目路径:
|
|
129
|
-
|
|
130
|
-
### 检查项(新形态命令——非旧插件冒烟形态)
|
|
131
|
-
|
|
132
|
-
| # | 检查 | 结果 | 证据(命令/输出摘要) |
|
|
133
|
-
|---|---|---|---|
|
|
134
|
-
| 1 | `prepare-env --platform dsh` 安装成功(skill 落 `.dsh/skills/flow-comet` + INSTALLED_VERSION + pathReplacements 生效) | | |
|
|
135
|
-
| 2 | 平台选择链:`--platform dsh` / `claude-code,dsh` / `all` / TTY 多选预勾选 / 未知平台报错 / `both` 已移除 | | |
|
|
136
|
-
| 3 | skill 可见断言:项目内 dsh 会话查询 `/flow-comet`(未安装项目不可见负向) | | |
|
|
137
|
-
| 4 | AGENTS.md 托管区注入 + 用户内容保留 + dsh 实际注入行为(R2 必测) | | |
|
|
138
|
-
| 5 | 桥接 loader 就位:`$DSH_HOME/plugins/` 文件 + `cordis.patch.yml` 托管块读-合并-写(dsh-skin 块保留断言) | | |
|
|
139
|
-
| 6 | 运行中越权 Write deny(PreToolDecision `{kind:'deny', reason}`)+ BLOCK 消息 + 恢复指引 | | |
|
|
140
|
-
| 7 | 合法写放行 | | |
|
|
141
|
-
| 8 | 非 flow-comet 项目 `next()` 负向(窄监听零拦截) | | |
|
|
142
|
-
| 9 | 参数形状不符 → fail-closed deny + WARN | | |
|
|
143
|
-
| 10 | 8.3 短路径包含性(realpath 展开——迁移复测) | | |
|
|
144
|
-
| 11 | spawn cwd = 会话项目根(负向:cwd≠项目根不可接受) | | |
|
|
145
|
-
| 12 | 协议文件随 skill 树(无 FLOW_COMET_PROTOCOL 机制) | | |
|
|
146
|
-
| 13 | purge 重置:删除后重新生成到完整安装态(skill 重新可见 / 托管区重新注入 / loader 重新挂载)/ 用户内容与 dsh-skin 块保留 | | |
|
|
147
|
-
| 14 | 多项目切换:A 项目装 B 项目不装——A 拦截 B 放行 | | |
|
|
148
|
-
| 15 | 幂等重装:重复安装结果一致(托管区/托管块读-合并-写幂等) | | |
|
|
149
|
-
|
|
150
|
-
### 结论
|
|
151
|
-
|
|
152
|
-
- 通过 / 不通过:
|
|
153
|
-
- 失败项与修复记录:
|
|
154
|
-
- 遗留风险:
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
### rc.8 三态冒烟(2026-08-20)(历史)
|
|
158
|
-
|
|
159
|
-
- 环境:dsh CLI 0.1.0-rc.8 / Harness 核心 rc.8 / dsh-tui 0.8.5
|
|
160
|
-
- 结果:运行中协调者项目外 Write → deny;运行中子代理项目内 Write → next();空闲态(无 state)项目外 Write → next();解析失败/未知 status → fail-closed deny(当轮 system-test ALL PASSED,K11/K12 断言覆盖;当轮基线 82 项(历史))。**记录口径**:历史实测基线保留原始数字并在行内标注(历史)——历史数字是证据,删除不是修法(带标记即被计数过期判据豁免);指针语(「以套件自身输出为准」)只用于当前值。
|
|
161
|
-
- 载体:prepare-env --platform dsh 经临时项目重推真实 ~/.dsh 桥接 loader,loader 与权威源 SHA-256 一致;真实交互式 TUI/Web 冒烟留待开放项
|
|
162
|
-
|
|
163
|
-
### 0.1.5-rc.1 全接缝认证(2026-09-10)(历史)
|
|
164
|
-
|
|
165
|
-
- 环境:dsh CLI 0.1.5-rc.1 / Node v24.14.1 / dsh-tui 0.10.0;headless profile;真实 `~/.dsh`(loader 与权威源逐字节一致)
|
|
166
|
-
- 方式:真实 headless 会话逐接缝运行时检测——每场景独立运行,证据取会话日志(`session.v3.jsonl` 解压)与文件系统双重判定;配套无 skill 目录负向载体
|
|
167
|
-
- 结果(全部通过):
|
|
168
|
-
- 运行中协调者写项目内白名单外 Write → deny(桥接消息 + guard 的 `BLOCKED: phase ... 允许范围: .specs/` 详情透传);写白名单内 → 放行
|
|
169
|
-
- 空闲态(无 state)项目内 Write → 放行;state 解析失败 → fail-closed deny(不视为空闲)
|
|
170
|
-
- 真实子代理(child session header `delegationDepth: 1`、`origin: subagent`)写源码 → 放行;子代理越界写 → 桥接包含性 deny(bridge 消息而非 sandbox 消息——证明子代理判定全程经过桥接,非未触发)
|
|
171
|
-
- `pwsh` 命令级写入 → deny(命令写入检测:`命令写入 ... 不在当前节点允许范围`)
|
|
172
|
-
- 窄监听负向(运行态 state 但无 `.dsh/skills/flow-comet` 的项目)→ 零拦截;项目级 skill 发现正常(flow-comet 全系可见)
|
|
173
|
-
- AGENTS.md 注入实证:dsh 将项目根 AGENTS.md 作为上下文注入(`Instructions from: AGENTS.md`),托管区内容被会话逐字引用
|
|
174
|
-
- 安装链:bridge-check 四项全绿(loader 存在 / 托管块 insert 形态 / `file://` 目标可达 / 无重复注册)
|
|
175
|
-
- 边界:认证面向 headless profile(自动化通道);dsh-tui / web 为静态证据(组合树含桥接行),交互式运行时留待日常使用或手动步骤清单;`str_replace_editor` 自 0.1.5-alpha.2 起为 opt-in(默认不挂载)
|
|
176
|
-
- 结论:桥接与 workflow-kernel 均无需修改(完整认证记录见维护者归档)
|
|
177
|
-
|
|
178
|
-
### 0.1.7-rc.2 全接缝重认证(2026-09-27)
|
|
179
|
-
|
|
180
|
-
- 版本线(历史锚):`0.1.0-rc.6` → `0.1.1-rc.2` → `0.1.5-rc.1` → `0.1.7-rc.2`(当前认证锚)
|
|
181
|
-
- 环境:dsh CLI `0.1.7-rc.2`;headless profile;真实 `~/.dsh`
|
|
182
|
-
- 结果:各接缝重认证通过
|
|
183
|
-
- 结论:桥接与 workflow-kernel 均无需修改
|
|
184
|
-
- 持续锚:`system-test` K9~K13 覆盖核心行为(loader 源文件与托管块注入 / 纯函数与身份分派 / 流程态门 / hook 注入形态与幂等升级)——后续版本升级以该套件持续回归为准
|