dsh-plugin-ml-phase-gate
给 DeepSeek Harness 使用的机器学习阶段闸门插件：让“做到哪一步”不只靠模型自述，而是由检查、工件和项目状态共同证明。
这个插件解决什么问题
机器学习项目很容易出现一种情况：对话里说“已经完成数据处理”，但数据集切分、泄漏检查、指标文件或验证脚本并没有真正留下证据。
这个插件把 ML 项目拆成 M0–M8 阶段，并做三件事：
- 读取项目当前声明的阶段；
- 执行项目自己的验证脚本和检查；
- 根据证据计算真实阶段、差距和下一出口。
结果会显示在 DSH 界面里：
M0 ✓ M1 ✓ M2 ⚠ M3 ··· M8
声明 M2 证据 M1 差距 1 下一步 M2
插件不会替你编写 ML 项目代码，也不会凭空判断阶段完成。真正的判断依据来自：
.dsh-ml-phase/phases.yml
.dsh-ml-phase/state.json
work/verify.cmd / verify.ps1 / verify.mjs / verify.sh
work/checks/*
outputs/*
你需要准备什么
- Node.js 20 或更高版本
- 可以运行的 DSH profile，下面以
web 为例
- 一个想要接入阶段流程的 ML 项目目录
- 项目自己的验证脚本和检查脚本
Windows、macOS 和 Linux 都可以使用。
下载与安装
方式一：从 GitHub 源码安装（推荐用于当前阶段）
先下载源码：
git clone https://github.com/lerqian883-alt/dsh-plugin-ml-phase-gate.git
cd dsh-plugin-ml-phase-gate
然后把它链接到 DSH：
dsh plugin --profile web add link:"$PWD"
如果 PowerShell 对 $PWD 处理不符合预期，可以显式取当前目录：
$pluginPath = (Get-Location).Path
dsh plugin --profile web add link:"$pluginPath"
macOS 或 Linux 可以直接使用：
dsh plugin --profile web add link:"$PWD"
安装后确认 DSH 能看到插件：
dsh --profile web --dump-config
预期看到类似内容：
- id: ml-phase-gate
name: dsh-plugin-ml-phase-gate
config:
activationMode: auto
方式二：从 GitHub Release 安装
项目发布 Release 后，可以下载：
dsh-plugin-ml-phase-gate-<version>.tgz
dsh-plugin-ml-phase-gate-<version>.tgz.sha256
先校验文件：
Get-FileHash .\dsh-plugin-ml-phase-gate-0.1.0.tgz -Algorithm SHA256
Get-Content .\dsh-plugin-ml-phase-gate-0.1.0.tgz.sha256
再确认当前 DSH 支持的安装规格：
dsh plugin --help
如果你的 DSH 版本支持 file/npm 包规格，就使用对应命令安装 tarball。不同 DSH 版本的安装语法可能不同，不要直接照搬其他版本的参数。
方式三：以后发布到 npm 后安装
如果未来发布到 npm，用户应优先使用：
dsh plugin --profile web add dsh-plugin-ml-phase-gate
在此之前，以 GitHub 源码安装和 Release tarball 安装为准。
卸载
dsh plugin --profile web remove dsh-plugin-ml-phase-gate
初始化一个 ML 项目
插件安装成功后，还需要给 ML 项目创建阶段文件和验证入口。
推荐方式：使用 bootstrap
在插件仓库中执行：
$projectRoot = "D:\ML\my-project"
node scripts/bootstrap-project.mjs `
--root $projectRoot `
--template standard
也可以先进入目标项目，再省略 --root：
cd D:\ML\my-project
node C:\path\to\dsh-plugin-ml-phase-gate\scripts\bootstrap-project.mjs `
--template standard
bootstrap 会在目标项目根目录下创建：
.dsh-ml-phase/
phases.yml
state.json
work/
verify.*
checks/
outputs/
可用参数：
--root <project> 指定 ML 项目根目录
--platform auto|windows|posix
--template standard|node
--force 覆盖管理路径中的冲突文件
--dry-run 只显示计划，不写文件
生成的检查脚本是占位检查，默认不会伪造通过。你需要把它们替换成真正能证明阶段完成的检查。
手动创建最小结构
如果你不想使用 bootstrap，可以手动创建：
my-ml-project/
.dsh-ml-phase/
phases.yml
state.json
work/
verify.cmd
checks/
010-problem.ps1
011-data.ps1
outputs/
最小 state.json：
{
"version": 1,
"declared": "M0",
"history": []
}
验证入口如何选择
插件支持以下入口，未显式配置时按顺序自动发现：
work/verify.cmd
work/verify.ps1
work/verify.mjs
work/verify.sh
检查前缀通过参数传入：
verify.* -Only 010-
退出码约定：
0 = pass
1 = fail
2 = skip
其他 = error
Node 项目的验证入口可以写成：
const prefix = process.argv[process.argv.indexOf('-Only') + 1];
if (prefix !== '010-') process.exit(1);
// 在这里执行真实检查
process.exit(0);
启动 DSH
进入已经初始化过的 ML 项目：
cd D:\ML\my-project
启动 DSH：
dsh --profile web
或者只启动服务，不自动打开浏览器：
dsh --profile web --no-open --port 10045
插件会根据当前 session 的 cwd 向上寻找项目根，并读取：
.dsh-ml-phase/state.json
如果找不到项目状态，activationMode=auto 下不会显示阶段 Dock。
你会看到什么
输入框上方的阶段轨道
M0 ✓ M1 ✓ M2 ⚠ M3 ○ M4 ○ ...
轨道会显示：
- 当前声明阶段
- 已经由证据证明的阶段
- 两者之间的差距
- 下一步应该进入哪个阶段
- 数据是否可能过期
点击“展开阶段详情”可以看到下一阶段的检查、工件和常见坑。
右栏审计页
点击“打开审计”后，可以看到完整的：
- 当前状态摘要
- 下一出口
- M0–M8 阶段清单
- 历史迁移记录
常用工具
在 DSH 中可以让 Agent 使用：
ml_phase_status
查看当前声明、证据、差距和下一阶段。
ml_phase_phases
查看阶段定义和证据判定结果。
ml_phase_advance
在目标阶段检查和工件通过后推进阶段。
ml_phase_defer
记录人工覆盖原因，例如：
ml_phase_defer reason="等待外部数据确认"
配置
默认配置：
- id: ml-phase-gate
name: dsh-plugin-ml-phase-gate
config:
activationMode: auto
watchAutoRun: false
activationMode
| 模式 | 行为 |
|---|
auto | 有阶段快照时显示；非 ML 项目安静降级 |
always | 没有阶段快照时也显示“未开始” |
off | Host 不注册能力，Dock/Audit 不显示 ML 内容 |
watchAutoRun
默认：
watchAutoRun: false
含义是文件变化只标记数据可能过期，不会自动执行项目验证脚本。
只有显式打开后，才会在文件变化时自动运行检查：
watchAutoRun: true
这会启动真实子进程。除非你明确知道项目脚本的行为，否则建议保持关闭。
项目结构说明
.dsh-ml-phase/
phases.yml 阶段定义和退出条件
state.json 当前声明阶段和迁移历史
work/
verify.* 项目统一的验证入口
checks/ 阶段检查脚本
outputs/ 阶段产物，例如报告、指标和数据摘要
phases.yml
phases.yml 定义阶段名称、检查前缀、工件和常见坑。
项目可以覆盖默认阶段，也可以追加自己的阶段。
state.json
state.json 保存声明阶段和历史记录。
不要在状态文件里写入：
evidenced
gap
next
这些字段由插件根据证据实时计算。
示例项目
仓库自带两个示例：
examples/minimal-ml-project/ Windows cmd/ps1 示例
examples/node-ml-project/ 跨平台 Node 示例
Node 示例可以直接验证：
cd examples\node-ml-project
node work\verify.mjs -Only 010-
常见问题
安装了插件，但看不到 ML 阶段 Dock
按顺序检查：
- 当前 DSH session 是否在 ML 项目目录下启动。
- 项目是否有
.dsh-ml-phase/state.json。
- 当前配置是否为
activationMode: auto，并且已经有阶段快照。
- 如果是空项目，可以先用
activationMode: always 观察“未开始”轨道。
提示找不到 verify command
插件会尝试：
work/verify.cmd
work/verify.ps1
work/verify.mjs
work/verify.sh
至少创建其中一个，或者显式配置：
verifyCommand: work/verify.mjs
阶段检查一直失败
检查脚本需要返回正确退出码：
0 = pass
1 = fail
2 = skip
其他 = error
也可以先运行：
ml_phase_status
查看具体 blocker 和原始输出。
不想自动执行项目脚本
保持默认：
watchAutoRun: false
需要完全停用运行时能力时，使用：
activationMode: off
需要彻底移除静态浏览器 bundle 时，在 DSH 插件管理器中禁用插件。
开发与验证
npm test
npm run pack:check
node scripts/smoke-install.mjs
npm run release:pack
npm run smoke:package
打包发布
npm run release:pack
会生成：
dsh-plugin-ml-phase-gate-<version>.tgz
dsh-plugin-ml-phase-gate-<version>.tgz.sha256
文档
