前言¶
DeepSeek Harness（DSH）的插件体系允许开发者把特定工作流封装成 Agent 工具。在估值模块 M1 中，需要同时保证「目标设计/模板」自身完整，以及「实例底稿」与模板结构一致。手工核对容易漏检严重项和版本漂移，而直接修改底稿又带来风险。本插件提供一个只读的门禁审核工具 workpaper_gate，把 M1 的两层完整性检查（目标层 + 实例层）变成可配置、可复现的流程。
是什么¶
zirscard/dsh-workpaper-gate 是一个 DeepSeek Harness 工作流插件，提供 Agent 工具 workpaper_gate，对估值底稿集合做完整性门禁审核。它接收只读的底稿路径，输出 blocker、warning、info 三级 issues，并生成 markdown 与 JSON 报告。插件由 zirscard 维护，当前版本为 0.2.0，已归类为工作流。插件的核心职责是执行规则与模板的比对，不修改底稿文件。
核心功能¶
插件通过 core/audit.py 执行审核，规则与配置集中在 spec/checks.json。审核分为两层：
- 目标（设计层/模板）自身完整性
- 底稿实例与模板（G14）的结构一致性
审核结果按严重度分级返回，便于在 CI 或 Agent 工作流中做门禁阻断。
严重度分级¶
| 级别 | 触发示例 |
|---|---|
blocker |
模板缺核心表、实例缺必填 Sheet/字段、表头与模板不一致、预测闭环断裂、审计严重项未登记、design_version 不一致、文件无法解析 |
warning |
C10 严重项已登记待用户确认（c10-pending）、孤儿模板/规则、设计层无版本 |
info |
核心表仅有表头无数据（empty-sheet） |
配置化¶
规则、模板、核心表、门禁与严重度都在 spec/checks.json 中：
goal.rules— 7 份规则文件清单goal.templates— 每份模板的file / core / any_of / exactinstance.core_sheets— 实例核心表清单gates— C2–C10 的阶段门控、必填表、必填字段、最小行数severity— 每个 check_id 的级别
新增或调整规则只需修改 spec/checks.json，core/audit.py 无需改动。
版本三件套¶
每次输出的 JSON 顶层包含三个版本字段：
| 字段 | 含义 |
|---|---|
plugin_version |
插件版本（package.json / audit.py） |
spec_version + spec_hash |
规则版本号 + spec 文件内容 SHA256 前 16 位（改 spec 即变） |
design_version |
被审核数据底表的 _design/version.json.design_version |
接口¶
Agent 工具 workpaper_gate¶
workpaper_gate(
path: "...", # 数据底表根 / 单项目目录 / _design 目录；默认 <data-root>
scope: "both", # both | goal | instance
project: "<项目C>", # 可选，只审单项目
detail: false, # true 时 issues 含 info 级（空表等）
outputDir: "..." # 报告目录，默认 <root>/.workpaper-gate
)
返回 summary + issues[]，每条包含 check_id / severity / project / path / sheet / item / hint。
CLI（CI / 自测）¶
NODE="$HOME/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/node/bin/node"
cd "/path/to/plugins/dsh-workpaper-gate"
"$NODE" cli.js --scope both --fail-on blocker # blocker>0 退出 1，否则 0；引擎错误退出 2
"$NODE" cli.js --scope both --detail --json
"$NODE" cli.js --project <项目C> --scope instance
--fail-on blocker 只在 blocker 时退出 1；--fail-on warning 在 blocker 或 warning 时退出 1；info 永不触发失败。退出码：0 通过 / 1 门禁失败 / 2 引擎或参数错误。
安装与启用¶
在终端执行以下命令（请将路径替换为插件实际位置）：
CLI="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$CLI" plugin --profile desktop add \
link:/path/to/plugins/dsh-workpaper-gate
安装完成后重启 DeepSeek Harness，在 GUI 工具列表中会出现 workpaper_gate。安装前后可分别运行 CLI 与 GUI 工具进行比对验证。
典型用法¶
- 在数据底表根目录下调用
workpaper_gate，同时审核目标与实例：
workpaper_gate(scope: "both")
- 若只需审核某个项目，可指定
project：
workpaper_gate(project: "项目C", scope: "both")
- 在 CI 中以 blocker 为门禁，失败时中断流水线：
workpaper_gate(scope: "both", detail: false)
- 生成包含 info 级别的详细报告：
workpaper_gate(scope: "both", detail: true)
适用场景与注意¶
本插件适合需要在 DSH Agent 工作流中做底稿完整性门禁的场景，例如：
- 估值 M1 的模板与实例一致性检查
- 门禁规则集中管理，避免硬编码在 Agent 代码中
- CI/CD 中阻断不合规的底稿提交
插件以当前 dsh 进程权限运行，安装前建议检查源码与许可证。由于是只读审核，底稿文件不会被修改。
结尾¶
dsh-workpaper-gate 把 M1 的目标与底稿完整性审核变成可配置、可复现的流程，输出三级 issues 与结构化报告，适合集成到 DSH 的工作流中。更多细节与源码请访问：GitHub。
