FDE Copilot

把 Palantir 式 FDE（前向部署工程师）的交付动作，固化成一套 AI 能照着走的插件。

它以**本体（Ontology）**当业务规则的唯一权威，用 15 个交付阶段驱动 AI 从「接入客户」一路走到「移交 / 退出」：每走到一个阶段，就按那个阶段该有的条件校验业务规则；改本体只能走唯一入口，改完还要过「规则可信度」校验。 门禁与审计是保证 AI 不跑偏的实现机制，不是产品本身。

这是什么

一句话：它让 AI 扮演一名 FDE —— 按「干系人对齐 → Bootcamp → Demo → 本体定义 → AIP 叠加 → 部署 → 变更管理 → 评估飞轮 → 产品化 → 移交」的节奏做交付，而不是拿到一句需求就直接去改代码。

15 个交付阶段（4 个区）

区	阶段
A 切入	`0.1` Connect ｜ `0.2` Site Survey ｜ `0.3` Stakeholder Map ｜ `0.4` Success Criteria
B 共建	`1` Bootcamp + 场景发现｜ `2` Demo 深化 + 数据接入｜ `3` Ontology 完整定义｜ `4` AIP 叠加
C 落地	`5` 交付与移交准备｜ `6` Deploy ｜ `7` Change Management ｜ `8` Eval Flywheel ｜ `9` Productize
D 收尾	`10` Handoff ｜ `11` Disengage

三条硬规则（由插件强制，不靠嘱咐）：

阶段只能一格一格推进（current → next）—— 跳过「Ontology 完整定义」就等于跳过 D1 门禁；
每次改本体都要定级：L0 / L1 / L2，看语义载荷而不是看 diff 形状；
本体节点有成熟度：draft → verified → locked，只能升不能降。

靠什么实现：四个互相协作的插件

跑在 DeepSeek Harness（DSH） 上：

插件	管什么
`dsh-fde-ontology-gate`	谁能在什么条件下改本体（业务规则）+ 变更定级
`dsh-fde-dsl`	改出来的规则能不能信（D1 护栏 + D3 反例）
`dsh-fde-phase`	现在处在哪个阶段、能不能推进
`dsh-fde-memory`	决策、清单、干系人、实验沙箱、本体成熟度，以及审计采集

共注册 20 个工具，全部通过 ctx.tools.guard 挂在宿主的工具调用链上。

为什么「门禁」必须做在机制层，而不是写在提示词里

「在提示词里提醒 AI 注意安全」是没用的——AI 可以不听。

方式	能拦住吗
提示词提醒 AI	❌ AI 可以不听
守卫（`ctx.tools.guard`）	✅ 同步、单调、只能否决——返回拒绝后无人能翻盘

这套系统提供的是机制，不是建议：

fail-closed：判定不了「安全」时，一律判「不放行」；
哈希链审计：改任何一条记录都会导致后续全部哈希不符；
结论绑定内容哈希：改了文件 ⇒ 旧结论自动失效，杜绝「拿改动之前的结论蒙混过关」。

快速开始

环境要求

项	要求
操作系统	Windows（本项目在 Windows 11 上开发与验证）
Node.js	插件运行：与 DSH 宿主一致（四个插件的 `lib/` 不用 `node:zlib`，没有额外版本要求）跑回归：Node ≥ 22.15（`package.json` 的 `engines`；实测依据见下节）
DeepSeek Harness	桌面应用形态（`DeepSeek Harness.exe`）已安装

⚠️ DSH 不是命令行服务，是 Electron 桌面应用 ⇒ 「启动/停止」= 打开/关闭应用，没有 systemd 概念。

跑一遍回归（不需要 DSH）

bash tests/_run_all_tests.sh
#   期望最后两行（本机**没有**部署 DSH 时）：
#   共 41 个套件；已跑 37；跳过 4（白名单内，需本机部署的 DSH）；失败 0；疑似空程序 0
#   ALL-TESTS-GREEN
#   ⚠️ 「跳过 4」= 这 4 套要读你**本机已部署**的插件副本，没有那份部署就跑不了 —— 见下节。
#      本机**有**那份部署时是「已跑 41；跳过 0」。
#   退出码：0 = 通过；1 = 有失败（判定行与退出码同源，不会一个说绿一个说红）

部署插件

# 1. 复制 4 个插件目录到 DSH 的插件位置
cp -r dsh-fde-*  <DSH_HOME>/profiles/web/node_modules/

# 2. 编辑配置（这是配置的唯一权威）
#    <DSH_HOME>/profiles/web/cordis.patch.yml

# 3. 对拍源 ↔ 副本
node tests/_deploy_diff.mjs      # 期望：ALL_MATCH

# 4. ⚠️ 重启 DSH —— 改了 lib/*.js 不重启等于没改

完整步骤见 → docs/03-usage/deployment.md

零运行时依赖

"dependencies": {}

四个插件的 dependencies 全部为空。

意味着
✅ 不向宿主引入任何依赖面	✅ 不联网、不上云、数据 100% 留本机
✅ 不打包任何第三方代码	✅ 无第三方许可证义务

peer 依赖（由宿主 DSH 提供，本项目不打包）：

@deepseek-ai/dsh-tools    0.1.2-rc.1
@deepseek-ai/schemastery  3.18.2

连 YAML 解析都是自研的受限子集（yamlsubset.js）——代价是行内集合必须写合法 JSON（双引号）。

仓库结构

.
├── README.md                    ← 本文件
├── LICENSE                      ← 规范 MIT 正文（GitHub 可自动识别）
├── DISCLOSURE.md                ← 四项如实披露（AI 生成 / 领域敏感 / 第三方宿主 / 非专业意见）
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md                  ← 报漏洞的私密渠道 + 已知安全边界
├── CODE_OF_CONDUCT.md
├── package.json                 ← `npm test` 入口（= bash tests/_run_all_tests.sh）
├── .gitignore                   ← ⚠️ node_modules 有反常规处理，改前先读
├── .gitattributes               ← ⚠️ 强制 LF；删了会让 .sh 在 Windows 上坏掉
├── .github/
│   ├── workflows/test.yml       ← CI：每次推送自动跑那 41 套
│   ├── ISSUE_TEMPLATE/bug_report.md
│   ├── ISSUE_TEMPLATE/feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
│
├── docs/                        ← 📚 18 份交付文档（从这里开始读）
│   ├── README.md                  导航中枢
│   ├── 01-overview/               项目说明书 · 功能对照表 · 技术架构
│   ├── 02-development/            开发日志 · 变更台账 · Bug台账 · 版本记录
│   ├── 03-usage/                  用户手册 · 部署运维 · FAQ
│   ├── 04-retrospective/          总结报告 · 成本统计 · 迭代规划
│   └── 05-ai-development/         AI工具清单 · Prompt库 · 代码风险 · 数据版权
│
├── dsh-fde-ontology-gate/       ← 插件 1（20 文件 / 7,042 行）
├── dsh-fde-dsl/                 ← 插件 2（17 文件 / 2,728 行）
├── dsh-fde-phase/               ← 插件 3（25 文件 / 6,625 行）
├── dsh-fde-memory/              ← 插件 4（26 文件 / 5,055 行）
│
├── tests/                       ← 41 套离线回归（+ 7 个它们真正 import/spawn 的脚本，必须同目录）
│   ├── README.md                  这个文件夹里有什么、怎么跑
│   ├── _run_all_tests.sh          全量回归入口（**从任意目录调用都行**，脚本会自定位）
│   ├── _*_test.mjs                41 套套件
│   └── _fixtures/                 回归夹具
├── tools/                       ← 111 个独立工具脚本（活验 / 勘察 / 一次性，**不进回归**）
│   └── README.md
├── evidence/                    ← 历史测试产物归档（⚠️ 已在 .gitignore，不进仓库）
└── node_modules/@deepseek-ai/   ← ⚠️ 测试桩，【必须保留】，见 .gitignore

✅ 本结构已被验证：从本仓库克隆到干净目录后 bash tests/_run_all_tests.sh → ALL-TESTS-GREEN。这证明 .gitignore 里的 node_modules 例外有效、LF 归一化不破坏夹具、脚本的子目录自定位有效。（本机有部署时 41/41；干净机器上是 37 跑 + 4 跳过，见下节。）

📌 关于「脚本放进子目录」这件事，之前写在 README 里的理由是错的 （原文：「它们用 ./dsh-fde-phase/lib/state.js 相对导入，移动会直接破坏 41 套回归，是不可移动的硬约束」）。 2026-09-29 实测证伪：移动确实要顺手改两类路径——① 相对导入 ./dsh-fde-* → ../dsh-fde-*； ② 少数按「我所在目录 = 仓库根」拼的运行时路径。改完 41/41 全绿、0 失败。 ⇒ 它不是「不可移动」，是「移动时要顺手改路径」。仓库根的条目数从 182 降到 19 （= 10 个文件 + 9 个目录；用 git ls-tree --name-only HEAD | wc -l 与 git ls-files | awk -F/ 'NF==1' | wc -l + 首层目录数对拍得出）。（仍在根目录出现的只有 _*_out.txt 这类产物，已 gitignore、不进仓库。）

⚠️ 哪些脚本你能跑，哪些跑不了

请先读这段，否则会在不该失败的地方失败。

类别	能否直接跑	说明
`__test.mjs`（41 套*）	✅ 能 —— 限 Windows + Node ≥ 22.15	路径从脚本自身位置推导，不含作者本机绝对路径。 2026-09-29 实测：换目录也能跑，且改坏插件会让对应套件变红（变异验证过）。
↳ 其中 4 套	⚠️ 要本机已部署 DSH，否则明确跳过	`tests/_fde_e1_wiring_test.mjs`、`tests/_fde_e2_test.mjs`、`tests/_fde_e5_test.mjs`、`tests/_fde_phase_wiring_test.mjs`。它们要读你本机已部署的插件副本 / 部署配置 ⇒ 不是纯离线套件。没有那份部署时它们 `exit 77`（跳过），汇总行会报出「跳过 4」。设 `FDE_DSH_HOME=<你的 dsh-home>` 即可让它们真跑。
`tests/_deploy_diff.mjs`	✅ 能（限 Windows，且需本机有部署）	不传参数 = 对拍全部 4 个插件（就是下面部署步骤里那条命令）。本机没有那份部署时它会明确报 `SKIP` 并 `exit 77`，不会报 `ALL_MATCH`；设 `FDE_DSH_HOME=<你的 dsh-home>` 即可真跑。也支持原用法 `node tests/_deploy_diff.mjs <源目录> <副本目录>` 只对拍一对。退出码：`0` 全一致 / `1` 有差异 / `77` 无部署可测（不是一致）。
`tools/_token_usage_report.mjs`	✅ 能（跨平台）	纯统计工具，路径由命令行参数给。
`__live.mjs`、`_cc_.mjs`、`_dsh_.mjs` 等（36 个）	❌ 不能开箱即跑	它们是活验仪器：① 需要 DSH 正在运行；② 里面写死了作者本机路径（`C:/Users/DELL/...`）与 launch-token 文件位置。（口径：`grep -rl "Users/DELL"` 命中的根目录脚本共 36 个；
另命中 4 份文档，逐一列出以免读者数不出来 —— `README.md`、`CHANGELOG.md`、
`dsh-fde-ontology-gate/README.md`、`dsh-fde-ontology-gate/HANDOFF.md`。）

🔴 两条边界 —— 都是 CI 实测出来的，不是猜的

① 平台：这 41 套回归是 Windows 专用的。

平台（同一次提交）结果

Windows 11（开发机） ✅ 41 套全绿

windows-latest（GitHub 托管） ✅ 全绿（修好下面②之后）

ubuntu-latest ❌ 41 套挂 9 套

从失败断言能看出两处根因方向：tests/_gate_mode_test.mjs 的断言原文是「enforce 下路径命中应拒」⇒ 路径语义不同；tests/_shelltok_test.mjs ⇒ shell 分词语义不同；其余若干在导入期直接崩溃。

② Node 版本：不能低于 22.15。

Node 结果

20.20.2 ❌ 挂 2 套：zlib 没有 zstdDecompressSync 这个导出

22.15.0 ✅ 有该导出（实测 typeof === 'function'）

24.15.0 ✅ 全绿

用到 zstd 的是读 DSH 会话记录的那几个脚本（tests/_tool_surface_check.mjs 等）—— 插件 lib/ 本身不用 zstd，所以「跑插件」没有这个版本要求。下界已写进 package.json 的 engines。

⇒ 所以 CI 固定在 windows-latest，Node 取 22.15.0 与 24 各跑一遍。没有把它改成"Linux 上失败也算通过"、也没有把 Node 钉在 20 再放宽判据 —— 那都是假绿。 CI 的判定步还额外核一件事：跳过数必须正好是 4（白名单一变就红），这样「跳过」不会变成一个能吞掉红灯的出口。

🔴 关于那 36 个活验脚本 —— 一个必须说清的事实：它们含作者本机路径这一点已知未修。原因不是没发现，而是修不了：它们的行为必须连着运行中的 DSH 才能验证，而合并前无法验证的改动不允许进主干 —— 这正是本项目自己的纪律（"判据必须可复算"）。 ⇒ 要复用它们，请先按你的环境改路径，并自己验一遍。

文档导航

第一次接触这个项目？ 按这个顺序读：

顺序	文档	读它能知道
1	项目说明书	这是什么、为谁做、核心价值
2	功能清单与对照表	19 项功能的真实完成度（含 4 项缺口）
3	技术架构说明	架构、数据、20 个工具接口、技术债
4	用户操作手册	不需要懂编程——跟 AI 说一句话就行
5	常见问题 FAQ	20+ 个真实踩过的坑

要接手维护？ 另加：

文档	为什么必读
部署运维手册	环境、部署、配置全表、排障
问题与 Bug 台账	47 条已记录缺陷 + 6 条固定动作
AI 代码风险说明	🔴 风险没有被消除，只是被压制
版本管理记录	⚠️ 本项目没有用 git，看它实际用了什么

🔴 AI 生成声明

本仓库的源码、测试与文档全部由 AI 工具生成，人类负责需求、决策与验收。

角色	承担者
需求 / 决策 / 验收	HarryKong824（人类）
主要实现	Claude Code
早期并行实现	WorkBuddy（2026-09-28 退出）
阶段性接力	Trae

这带来一个无法消除的风险：AI 既是实现者，也是验证者。

一个 AI 如果对某个机制有错误理解，它会同时把这个错误写进实现和测试里—— 两边一致 ⇒ 测试全绿 ⇒ 错误被牢牢锁住。

⇒ 本项目的代码质量不能只用「41 套回归全绿」来论证。那 41 套也是 AI 写的。

压制手段（不是消除）：判据必须落到磁盘事实（哈希 / seq / 退出码 / 字节数），核证方独立重算，不看实现方的说明。

完整说明 → docs/05-ai-development/ai-code-risks.md

项目状态

维度	状态
版本	0.0.1（PoC 阶段）
开发周期	2026-09-23 — 2026-09-29（7 天）
功能完成度	19 项中 15 项活验完整、4 项部分完成、0 项未实现
回归	41 套全绿
运行时依赖	零
界面	❌ 没有界面 —— 它就长在 AI 助手的对话里，能力的形状是 20 个工具 + 每阶段的门禁
多租户	❌ 不支持——设计场景是单机单用户

四个尚未验完的功能（不是没做，是没在真环境验完）→ 功能对照表 §4

三条最重要的使用纪律

1. 被拒绝是设计行为，不是故障。 fail-closed 意味着它宁可拦住正确的操作，也不放过错误的操作。被拦时先读拒绝理由——里面通常已经写了「怎么补」。

2. 理由要写真的。 这套系统存在的意义就是「说的话都能被追溯」。 不要为了「测试一下」而推进阶段或编造理由——业务状态会被真实推进，且链上永久留一条测试记录。

3. 看到异常先怀疑自己的判据。 本项目至少 3 次发生「先怀疑实现有缺陷，查下去发现是判据/观测方法错了」。如果当时直接动手「修」，会把一个本来正确的实现改坏。

许可证

MIT —— 见 LICENSE。

✅ 已确认的两个前提（由版权持有人 HarryKong824 于 2026-09-29 确认）：

E:\ontologyRoot\ 里的医疗领域示例为通用示例，不来自真实客户业务、不含真实患者信息；

本项目以 MIT 公开。

📌 另见 DISCLOSURE.md —— 四项如实披露（AI 生成 / 领域敏感内容 / 第三方宿主 / 不构成专业意见）。它不修改 MIT 条款，只是披露事实。

⚠️ 为什么披露要单独放：原先这四项是附在 LICENSE 正文后面的，实测导致 GitHub 的许可证识别器匹配不上，仓库页面显示为 "Other" 而非 MIT。现在 LICENSE 只保留规范 MIT 正文，许可证能被正确识别，事实也照旧告知。

如需改用其它许可证（Apache-2.0 / AGPL-3.0 / 专有），整体替换 LICENSE 即可。

相关的深度分析 → docs/05-ai-development/data-licensing.md

贡献

见 CONTRIBUTING.md。

最重要的一条：本项目的方法论核心是 「判据必须可复算」—— 提交前请确认你的每条结论都指着一个可以被别人独立复算的磁盘事实。

致谢

DeepSeek Harness —— 宿主平台
本项目 7 天里的 123 份交接文档、41 套回归、47 条被记录下来的缺陷 —— 它们不是项目的污点，它们正是这套系统想证明的东西。

FDE Copilot

把 Palantir 式 FDE（前向部署工程师）的交付动作，固化成一套 AI 能照着走的插件。

它以**本体（Ontology）**当业务规则的唯一权威，用 15 个交付阶段驱动 AI 从「接入客户」一路走到「移交 / 退出」：每走到一个阶段，就按那个阶段该有的条件校验业务规则；改本体只能走唯一入口，改完还要过「规则可信度」校验。 门禁与审计是保证 AI 不跑偏的实现机制，不是产品本身。

这是什么

15 个交付阶段（4 个区）

区	阶段
A 切入	`0.1` Connect ｜ `0.2` Site Survey ｜ `0.3` Stakeholder Map ｜ `0.4` Success Criteria
B 共建	`1` Bootcamp + 场景发现｜ `2` Demo 深化 + 数据接入｜ `3` Ontology 完整定义｜ `4` AIP 叠加
C 落地	`5` 交付与移交准备｜ `6` Deploy ｜ `7` Change Management ｜ `8` Eval Flywheel ｜ `9` Productize
D 收尾	`10` Handoff ｜ `11` Disengage

三条硬规则（由插件强制，不靠嘱咐）：

阶段只能一格一格推进（current → next）—— 跳过「Ontology 完整定义」就等于跳过 D1 门禁；
每次改本体都要定级：L0 / L1 / L2，看语义载荷而不是看 diff 形状；
本体节点有成熟度：draft → verified → locked，只能升不能降。

靠什么实现：四个互相协作的插件

跑在 DeepSeek Harness（DSH） 上：

插件	管什么
`dsh-fde-ontology-gate`	谁能在什么条件下改本体（业务规则）+ 变更定级
`dsh-fde-dsl`	改出来的规则能不能信（D1 护栏 + D3 反例）
`dsh-fde-phase`	现在处在哪个阶段、能不能推进
`dsh-fde-memory`	决策、清单、干系人、实验沙箱、本体成熟度，以及审计采集

共注册 20 个工具，全部通过 ctx.tools.guard 挂在宿主的工具调用链上。

为什么「门禁」必须做在机制层，而不是写在提示词里

「在提示词里提醒 AI 注意安全」是没用的——AI 可以不听。

方式	能拦住吗
提示词提醒 AI	❌ AI 可以不听
守卫（`ctx.tools.guard`）	✅ 同步、单调、只能否决——返回拒绝后无人能翻盘

这套系统提供的是机制，不是建议：

fail-closed：判定不了「安全」时，一律判「不放行」；
哈希链审计：改任何一条记录都会导致后续全部哈希不符；
结论绑定内容哈希：改了文件 ⇒ 旧结论自动失效，杜绝「拿改动之前的结论蒙混过关」。

快速开始

环境要求

项	要求
操作系统	Windows（本项目在 Windows 11 上开发与验证）
Node.js	插件运行：与 DSH 宿主一致（四个插件的 `lib/` 不用 `node:zlib`，没有额外版本要求）跑回归：Node ≥ 22.15（`package.json` 的 `engines`；实测依据见下节）
DeepSeek Harness	桌面应用形态（`DeepSeek Harness.exe`）已安装

⚠️ DSH 不是命令行服务，是 Electron 桌面应用 ⇒ 「启动/停止」= 打开/关闭应用，没有 systemd 概念。

跑一遍回归（不需要 DSH）

bash tests/_run_all_tests.sh
#   期望最后两行（本机**没有**部署 DSH 时）：
#   共 41 个套件；已跑 37；跳过 4（白名单内，需本机部署的 DSH）；失败 0；疑似空程序 0
#   ALL-TESTS-GREEN
#   ⚠️ 「跳过 4」= 这 4 套要读你**本机已部署**的插件副本，没有那份部署就跑不了 —— 见下节。
#      本机**有**那份部署时是「已跑 41；跳过 0」。
#   退出码：0 = 通过；1 = 有失败（判定行与退出码同源，不会一个说绿一个说红）

部署插件

# 1. 复制 4 个插件目录到 DSH 的插件位置
cp -r dsh-fde-*  <DSH_HOME>/profiles/web/node_modules/

# 2. 编辑配置（这是配置的唯一权威）
#    <DSH_HOME>/profiles/web/cordis.patch.yml

# 3. 对拍源 ↔ 副本
node tests/_deploy_diff.mjs      # 期望：ALL_MATCH

# 4. ⚠️ 重启 DSH —— 改了 lib/*.js 不重启等于没改

完整步骤见 → docs/03-usage/deployment.md

零运行时依赖

"dependencies": {}

四个插件的 dependencies 全部为空。

意味着
✅ 不向宿主引入任何依赖面	✅ 不联网、不上云、数据 100% 留本机
✅ 不打包任何第三方代码	✅ 无第三方许可证义务

peer 依赖（由宿主 DSH 提供，本项目不打包）：

@deepseek-ai/dsh-tools    0.1.2-rc.1
@deepseek-ai/schemastery  3.18.2

连 YAML 解析都是自研的受限子集（yamlsubset.js）——代价是行内集合必须写合法 JSON（双引号）。

仓库结构

.
├── README.md                    ← 本文件
├── LICENSE                      ← 规范 MIT 正文（GitHub 可自动识别）
├── DISCLOSURE.md                ← 四项如实披露（AI 生成 / 领域敏感 / 第三方宿主 / 非专业意见）
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md                  ← 报漏洞的私密渠道 + 已知安全边界
├── CODE_OF_CONDUCT.md
├── package.json                 ← `npm test` 入口（= bash tests/_run_all_tests.sh）
├── .gitignore                   ← ⚠️ node_modules 有反常规处理，改前先读
├── .gitattributes               ← ⚠️ 强制 LF；删了会让 .sh 在 Windows 上坏掉
├── .github/
│   ├── workflows/test.yml       ← CI：每次推送自动跑那 41 套
│   ├── ISSUE_TEMPLATE/bug_report.md
│   ├── ISSUE_TEMPLATE/feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
│
├── docs/                        ← 📚 18 份交付文档（从这里开始读）
│   ├── README.md                  导航中枢
│   ├── 01-overview/               项目说明书 · 功能对照表 · 技术架构
│   ├── 02-development/            开发日志 · 变更台账 · Bug台账 · 版本记录
│   ├── 03-usage/                  用户手册 · 部署运维 · FAQ
│   ├── 04-retrospective/          总结报告 · 成本统计 · 迭代规划
│   └── 05-ai-development/         AI工具清单 · Prompt库 · 代码风险 · 数据版权
│
├── dsh-fde-ontology-gate/       ← 插件 1（20 文件 / 7,042 行）
├── dsh-fde-dsl/                 ← 插件 2（17 文件 / 2,728 行）
├── dsh-fde-phase/               ← 插件 3（25 文件 / 6,625 行）
├── dsh-fde-memory/              ← 插件 4（26 文件 / 5,055 行）
│
├── tests/                       ← 41 套离线回归（+ 7 个它们真正 import/spawn 的脚本，必须同目录）
│   ├── README.md                  这个文件夹里有什么、怎么跑
│   ├── _run_all_tests.sh          全量回归入口（**从任意目录调用都行**，脚本会自定位）
│   ├── _*_test.mjs                41 套套件
│   └── _fixtures/                 回归夹具
├── tools/                       ← 111 个独立工具脚本（活验 / 勘察 / 一次性，**不进回归**）
│   └── README.md
├── evidence/                    ← 历史测试产物归档（⚠️ 已在 .gitignore，不进仓库）
└── node_modules/@deepseek-ai/   ← ⚠️ 测试桩，【必须保留】，见 .gitignore

✅ 本结构已被验证：从本仓库克隆到干净目录后 bash tests/_run_all_tests.sh → ALL-TESTS-GREEN。这证明 .gitignore 里的 node_modules 例外有效、LF 归一化不破坏夹具、脚本的子目录自定位有效。（本机有部署时 41/41；干净机器上是 37 跑 + 4 跳过，见下节。）

📌 关于「脚本放进子目录」这件事，之前写在 README 里的理由是错的 （原文：「它们用 ./dsh-fde-phase/lib/state.js 相对导入，移动会直接破坏 41 套回归，是不可移动的硬约束」）。 2026-09-29 实测证伪：移动确实要顺手改两类路径——① 相对导入 ./dsh-fde-* → ../dsh-fde-*； ② 少数按「我所在目录 = 仓库根」拼的运行时路径。改完 41/41 全绿、0 失败。 ⇒ 它不是「不可移动」，是「移动时要顺手改路径」。仓库根的条目数从 182 降到 19 （= 10 个文件 + 9 个目录；用 git ls-tree --name-only HEAD | wc -l 与 git ls-files | awk -F/ 'NF==1' | wc -l + 首层目录数对拍得出）。（仍在根目录出现的只有 _*_out.txt 这类产物，已 gitignore、不进仓库。）

⚠️ 哪些脚本你能跑，哪些跑不了

请先读这段，否则会在不该失败的地方失败。

类别	能否直接跑	说明
`__test.mjs`（41 套*）	✅ 能 —— 限 Windows + Node ≥ 22.15	路径从脚本自身位置推导，不含作者本机绝对路径。 2026-09-29 实测：换目录也能跑，且改坏插件会让对应套件变红（变异验证过）。
↳ 其中 4 套	⚠️ 要本机已部署 DSH，否则明确跳过	`tests/_fde_e1_wiring_test.mjs`、`tests/_fde_e2_test.mjs`、`tests/_fde_e5_test.mjs`、`tests/_fde_phase_wiring_test.mjs`。它们要读你本机已部署的插件副本 / 部署配置 ⇒ 不是纯离线套件。没有那份部署时它们 `exit 77`（跳过），汇总行会报出「跳过 4」。设 `FDE_DSH_HOME=<你的 dsh-home>` 即可让它们真跑。
`tests/_deploy_diff.mjs`	✅ 能（限 Windows，且需本机有部署）	不传参数 = 对拍全部 4 个插件（就是下面部署步骤里那条命令）。本机没有那份部署时它会明确报 `SKIP` 并 `exit 77`，不会报 `ALL_MATCH`；设 `FDE_DSH_HOME=<你的 dsh-home>` 即可真跑。也支持原用法 `node tests/_deploy_diff.mjs <源目录> <副本目录>` 只对拍一对。退出码：`0` 全一致 / `1` 有差异 / `77` 无部署可测（不是一致）。
`tools/_token_usage_report.mjs`	✅ 能（跨平台）	纯统计工具，路径由命令行参数给。
`__live.mjs`、`_cc_.mjs`、`_dsh_.mjs` 等（36 个）	❌ 不能开箱即跑	它们是活验仪器：① 需要 DSH 正在运行；② 里面写死了作者本机路径（`C:/Users/DELL/...`）与 launch-token 文件位置。（口径：`grep -rl "Users/DELL"` 命中的根目录脚本共 36 个；
另命中 4 份文档，逐一列出以免读者数不出来 —— `README.md`、`CHANGELOG.md`、
`dsh-fde-ontology-gate/README.md`、`dsh-fde-ontology-gate/HANDOFF.md`。）

🔴 两条边界 —— 都是 CI 实测出来的，不是猜的

① 平台：这 41 套回归是 Windows 专用的。

平台（同一次提交）结果

Windows 11（开发机） ✅ 41 套全绿

windows-latest（GitHub 托管） ✅ 全绿（修好下面②之后）

ubuntu-latest ❌ 41 套挂 9 套

从失败断言能看出两处根因方向：tests/_gate_mode_test.mjs 的断言原文是「enforce 下路径命中应拒」⇒ 路径语义不同；tests/_shelltok_test.mjs ⇒ shell 分词语义不同；其余若干在导入期直接崩溃。

② Node 版本：不能低于 22.15。

Node 结果

20.20.2 ❌ 挂 2 套：zlib 没有 zstdDecompressSync 这个导出

22.15.0 ✅ 有该导出（实测 typeof === 'function'）

24.15.0 ✅ 全绿

用到 zstd 的是读 DSH 会话记录的那几个脚本（tests/_tool_surface_check.mjs 等）—— 插件 lib/ 本身不用 zstd，所以「跑插件」没有这个版本要求。下界已写进 package.json 的 engines。

⇒ 所以 CI 固定在 windows-latest，Node 取 22.15.0 与 24 各跑一遍。没有把它改成"Linux 上失败也算通过"、也没有把 Node 钉在 20 再放宽判据 —— 那都是假绿。 CI 的判定步还额外核一件事：跳过数必须正好是 4（白名单一变就红），这样「跳过」不会变成一个能吞掉红灯的出口。

🔴 关于那 36 个活验脚本 —— 一个必须说清的事实：它们含作者本机路径这一点已知未修。原因不是没发现，而是修不了：它们的行为必须连着运行中的 DSH 才能验证，而合并前无法验证的改动不允许进主干 —— 这正是本项目自己的纪律（"判据必须可复算"）。 ⇒ 要复用它们，请先按你的环境改路径，并自己验一遍。

文档导航

第一次接触这个项目？ 按这个顺序读：

顺序	文档	读它能知道
1	项目说明书	这是什么、为谁做、核心价值
2	功能清单与对照表	19 项功能的真实完成度（含 4 项缺口）
3	技术架构说明	架构、数据、20 个工具接口、技术债
4	用户操作手册	不需要懂编程——跟 AI 说一句话就行
5	常见问题 FAQ	20+ 个真实踩过的坑

要接手维护？ 另加：

文档	为什么必读
部署运维手册	环境、部署、配置全表、排障
问题与 Bug 台账	47 条已记录缺陷 + 6 条固定动作
AI 代码风险说明	🔴 风险没有被消除，只是被压制
版本管理记录	⚠️ 本项目没有用 git，看它实际用了什么

🔴 AI 生成声明

本仓库的源码、测试与文档全部由 AI 工具生成，人类负责需求、决策与验收。

角色	承担者
需求 / 决策 / 验收	HarryKong824（人类）
主要实现	Claude Code
早期并行实现	WorkBuddy（2026-09-28 退出）
阶段性接力	Trae

这带来一个无法消除的风险：AI 既是实现者，也是验证者。

一个 AI 如果对某个机制有错误理解，它会同时把这个错误写进实现和测试里—— 两边一致 ⇒ 测试全绿 ⇒ 错误被牢牢锁住。

⇒ 本项目的代码质量不能只用「41 套回归全绿」来论证。那 41 套也是 AI 写的。

压制手段（不是消除）：判据必须落到磁盘事实（哈希 / seq / 退出码 / 字节数），核证方独立重算，不看实现方的说明。

完整说明 → docs/05-ai-development/ai-code-risks.md

项目状态

维度	状态
版本	0.0.1（PoC 阶段）
开发周期	2026-09-23 — 2026-09-29（7 天）
功能完成度	19 项中 15 项活验完整、4 项部分完成、0 项未实现
回归	41 套全绿
运行时依赖	零
界面	❌ 没有界面 —— 它就长在 AI 助手的对话里，能力的形状是 20 个工具 + 每阶段的门禁
多租户	❌ 不支持——设计场景是单机单用户

四个尚未验完的功能（不是没做，是没在真环境验完）→ 功能对照表 §4

三条最重要的使用纪律

1. 被拒绝是设计行为，不是故障。 fail-closed 意味着它宁可拦住正确的操作，也不放过错误的操作。被拦时先读拒绝理由——里面通常已经写了「怎么补」。

2. 理由要写真的。 这套系统存在的意义就是「说的话都能被追溯」。 不要为了「测试一下」而推进阶段或编造理由——业务状态会被真实推进，且链上永久留一条测试记录。

3. 看到异常先怀疑自己的判据。 本项目至少 3 次发生「先怀疑实现有缺陷，查下去发现是判据/观测方法错了」。如果当时直接动手「修」，会把一个本来正确的实现改坏。

许可证

MIT —— 见 LICENSE。

✅ 已确认的两个前提（由版权持有人 HarryKong824 于 2026-09-29 确认）：

E:\ontologyRoot\ 里的医疗领域示例为通用示例，不来自真实客户业务、不含真实患者信息；

本项目以 MIT 公开。

📌 另见 DISCLOSURE.md —— 四项如实披露（AI 生成 / 领域敏感内容 / 第三方宿主 / 不构成专业意见）。它不修改 MIT 条款，只是披露事实。

⚠️ 为什么披露要单独放：原先这四项是附在 LICENSE 正文后面的，实测导致 GitHub 的许可证识别器匹配不上，仓库页面显示为 "Other" 而非 MIT。现在 LICENSE 只保留规范 MIT 正文，许可证能被正确识别，事实也照旧告知。

如需改用其它许可证（Apache-2.0 / AGPL-3.0 / 专有），整体替换 LICENSE 即可。

相关的深度分析 → docs/05-ai-development/data-licensing.md

贡献

见 CONTRIBUTING.md。

最重要的一条：本项目的方法论核心是 「判据必须可复算」—— 提交前请确认你的每条结论都指着一个可以被别人独立复算的磁盘事实。

致谢

DeepSeek Harness —— 宿主平台
本项目 7 天里的 123 份交接文档、41 套回归、47 条被记录下来的缺陷 —— 它们不是项目的污点，它们正是这套系统想证明的东西。

平台（同一次提交）	结果
Windows 11（开发机）	✅ 41 套全绿
`windows-latest`（GitHub 托管）	✅ 全绿（修好下面②之后）
`ubuntu-latest`	❌ 41 套挂 9 套

Node	结果
20.20.2	❌ 挂 2 套：`zlib` 没有 `zstdDecompressSync` 这个导出
22.15.0	✅ 有该导出（实测 `typeof === 'function'`）
24.15.0	✅ 全绿

HarryKong824/fde-copilot

FDE Copilot

这是什么

15 个交付阶段（4 个区）

靠什么实现：四个互相协作的插件

为什么「门禁」必须做在机制层，而不是写在提示词里

快速开始

环境要求

跑一遍回归（不需要 DSH）

部署插件

零运行时依赖

仓库结构

⚠️ 哪些脚本你能跑，哪些跑不了

文档导航

🔴 AI 生成声明

项目状态

三条最重要的使用纪律

许可证

贡献

致谢

Community comments

HarryKong824/fde-copilot

FDE Copilot

这是什么

15 个交付阶段（4 个区）

靠什么实现：四个互相协作的插件

为什么「门禁」必须做在机制层，而不是写在提示词里

快速开始

环境要求

跑一遍回归（不需要 DSH）

部署插件

零运行时依赖

仓库结构

⚠️ 哪些脚本你能跑，哪些跑不了

文档导航

🔴 AI 生成声明

项目状态

三条最重要的使用纪律

许可证

贡献

致谢

Community comments