xuxucodepractice-code/dsh-claim-guard

dsh-claim-guard

中文 · English

dsh-claim-guard 是一个确定性的写入前声明守卫，适用于受支持的
DeepSeek Harness 文件工具。它是一个非官方社区项目，
由 xuxucodepractice-code 独立开发和维护；它并非由 DeepSeek
发布、认证、维护或背书。

合成终端演示

English

它的作用

在已验证的 DSH 文件工具写入文本之前，该插件会读取用户维护的
JSON 规则文件并检查新文本。一个 blocked 短语或一个无界的
bounded 短语会返回 DSH 原生的 ask 决策。DSH 现有的审批
服务决定该次执行是否继续。

已检入的源代码并不声称未来的某个版本或 CI 运行已经通过。
项目状态用词以证据为界：参见状态与兼容性
以及发布后的、与提交绑定的 CI/Release 证据。

状态与兼容性

| 组件 | 确切候选版本 | 证据规则 |
| --- | --- | --- |
| DeepSeek Harness | 0.1.1-rc.2，标签 dsh-v0.1.1-rc.2，提交 b150a551b8d465e31e418e1b2eaf5e79bbb7d28e | 仅当该确切发布提交通过必需的 CI 和制品门禁后才为 verified |
| Node | 22.19.0、24.15.0 | 每个版本都必须通过相同的必需 CI 矩阵 |
| pnpm | 11.7.0 | 确切的安装/配置命令基线 |
| npm | 11.12.1 | 确切的发布打包基线 |
| 平台 | macOS、Linux CI | 其他平台未经测试 |

implemented、integrated、release-candidate、released-github 和
shared-dsh-community 描述不同的证据级别；一个绝不意味着
下一个。不可变的 API 和依赖证据见 RECON.md。

从 GitHub Release tarball 安装

首个分发计划仅限 GitHub。没有 npm 安装声明。
在 v0.1.0 发布后，从
GitHub Release
下载 dsh-claim-guard-0.1.0.tgz 及其 .sha256 文件，
然后在安装前验证：

shasum -a 256 -c dsh-claim-guard-0.1.0.tgz.sha256
mkdir -p claim-guard-workspace
cp claims.example.json claim-guard-workspace/claims.json
dsh plugin --profile claim-guard-smoke add ./dsh-claim-guard-0.1.0.tgz
cd claim-guard-workspace
dsh --profile claim-guard-smoke --dump-config
dsh --profile claim-guard-smoke

首先使用专用 profile。必需的顺序是：准备有效的规则
文件，安装/启用插件，然后运行合成的被阻止写入和干净写入。
如果规则文件缺失或无效，受覆盖的写入会失败关闭。唯一的
自我修复例外是写入解析后的规则文件本身，插件始终将其
排除在外。

配置

该 bundle 插入以下默认行：

- insert:
- id: dsh-claim-guard
name: dsh-claim-guard
config:
rulesPath: claims.json
include: ["/.md", "/.mdx", "*/.txt"]
exclude: []
rulesPath 可以相对于 exec.agent.session.header.cwd，也可以是显式配置在工作区之外的绝对路径。目标路径仍会相对于会话工作区进行分类。exclude 优先于 include；include: [] 包含所有工作区目标。未知配置字段、显式 null、空值和错误类型都会被拒绝。

规则是严格的 UTF-8 JSON，不是 YAML，也不是带注释的 JSON：

{
"version": 1,
"options": { "window": 60, "caseSensitive": false },
"blocked": [
{
"id": "manuscript-status",
"match": "submitted",
"message": "The synthetic demo manuscript is only in preparation."
}
],
"bounded": [
{
"id": "demo-composite-score",
"match": "42.5%",
"mustAccompany": ["synthetic benchmark", "合成示例"],
"message": "This invented demo value must be labelled as synthetic."
}
]
}

规则文件限制为 262,144 字节，规则总数为 1–256 条。输入文本限制为 1,000,000 个 JavaScript UTF-16 代码单元。匹配是字面子字符串匹配；不区分大小写模式使用 ECMAScript toLowerCase()，不会添加规范化、分词、模糊匹配或同义词。

涵盖的工具与审批行为

| 工具 | 操作 | 覆盖范围 |
| --- | --- | --- |
| write | 所有写入 | 完整新文本；blocked 和 bounded |
| edit | 替换/删除 | 仅新片段；仅 blocked |
| str_replace_editor | create | 完整新文本；blocked 和 bounded |
| str_replace_editor | str_replace、insert | 仅新片段；仅 blocked |
| str_replace_editor | view | 不适用；原样委托 |

干净的完整写入以及未命中 blocked 的片段会委托给下一个策略。命中会请求审批；只有 DSH 的 allowed-once 结果才会执行工具主体。被拒绝、被取消、不可用/无响应者、缺少审批以及 never 策略结果都不会执行它。每次命中都会再次询问；先前的一次性授权不会被缓存。下游策略仍可拒绝干净的写入。

规则/配置/工作区/已知适配器故障会返回有界的 deny 原因；它们不能作为普通内容被批准。报告最多显示 20 个完整命中项和 6,000 个 UTF-16 代码单元，并使用简短的转义摘录，而不是整个文档。

数据流与权限

- 插件读取配置的规则文件，通常位于会话工作区内；显式的绝对 rulesPath 可以指向其外部。
- 预执行钩子会看到受支持文件工具的新文本参数。
- 匹配的摘录和原因可以进入 DSH 审批 UI 和会话审计。
- 插件本身不发起网络请求，不提供遥测，也不直接写入目标文件。
- DSH 仍可根据其自身配置访问模型、网络、文件和日志。
- 社区插件与 DSH 在同一进程中运行。仅本地执行
不是安全保证。请审查源代码并固定发布版本/校验和。
- 切勿将秘密规则或文本放入公开 issue、截图或 CI 中。避免让大型秘密值本身成为规则匹配项，因为摘录可能会留存。

它不做什么

这不是事实核查器、内容改写器、DLP 系统、恶意软件检测器、沙箱或恶意主机边界。它无法推断真实性或语义等价性。Bash、PowerShell、Python、Node 脚本、MCP 工具、第三方或未知写入工具、主机内部写入、二进制内容以及会话工作区之外的路径都可以绕过它。增量编辑不会被重建，因此一次删除可能造成 v1 无法检测到的整文件违规。

为什么复用 DSH 审批

该插件返回文档化的原生 ask 决策，而不是创建第二套提示、策略或审计机制。这保持了单一权威审批结果，并保留了 DSH 的取消、无响应者和会话审计行为。这不会使该插件成为官方 DSH 组件。

升级、禁用、卸载和故障排查

将升级后的带校验和 tarball 安装到一次性配置文件中，并在更改重要配置文件之前重复合成冒烟测试。配置文件本地补丁可以在不改变同一行身份的情况下禁用它：

- id: dsh-claim-guard
disabled: true

使用以下命令移除包和 bundle 层：

dsh plugin --profile claim-guard-smoke remove dsh-claim-guard

常见故障：

- RULE_FILE_UNREADABLE 或规则无效：恢复有效的 claims.json；规则文件本身保持可写以便恢复。
- 某次写入未被检查：确认确切的 DSH/工具版本、工具名称、工作区边界、包含/排除模式，以及插件行已启用。未知工具和工作区外路径有意不在覆盖范围内。
- 某片段在没有有界短语的情况下通过：有界检查需要完整文本，并且在 v1 中有意不对增量编辑运行。
- 没有审批 UI：当没有响应者可用时，DSH 会将 ask 失败关闭。

有关私下报告，请参阅 SECURITY.md；有关合成复现，请参阅 CONTRIBUTING.md。移除私有数据后，请通过 issue 跟踪器报告普通 bug。

路线图

- 研究针对增量编辑的精确整文件重建。
- 仅在源代码和集成重新验证后添加兼容性基线。
- 在自动 hook 仍完全受门控后，考虑可选只读 claim_check 便利工具。
- 单独评估 npm 分发；GitHub Release 仍是 v0.1.0 计划。

许可证

MIT。请参阅 LICENSE。

中文

作用与身份

dsh-claim-guard 是一个面向已验证 DeepSeek Harness 文件工具的确定性写前
声明检查插件。它是由 xuxucodepractice-code 独立开发维护的非官方社区项目，
并非 DeepSeek 发布、认证、维护或背书的官方组件。

在受支持工具写入之前，插件读取用户维护的 JSON 规则，检查即将写入的新文本。
命中 blocked，或完整文本中的 bounded 表述缺少邻近限定词时，插件返回 DSH
原生 ask，由宿主已有审批流决定这一次是否执行。源码不提前声称未来 Release
或 CI 已成功；兼容性只有在同一 commit 的两档 CI 与制品门禁完成后才是
verified。

安装与启用顺序

首发采用 github-only，不宣称 npm 已发布。v0.1.0 发布后，从
GitHub Release
下载 .tgz 与 .sha256，先校验，再安装到专用 profile：

shasum -a 256 -c dsh-claim-guard-0.1.0.tgz.sha256
mkdir -p claim-guard-workspace
cp claims.example.json claim-guard-workspace/claims.json
dsh plugin --profile claim-guard-smoke add ./dsh-claim-guard-0.1.0.tgz
cd claim-guard-workspace
dsh --profile claim-guard-smoke --dump-config
dsh --profile claim-guard-smoke

固定顺序是：准备并校验规则 → 安装/启用 → 用合成内容 smoke test。
缺失、不可读、损坏或 schema 非法的规则会让纳入范围的写入失败关闭。唯一恢复
例外是规则文件自身始终排除，所以可以先创建或修复它。

配置与规则

默认 rulesPath 是相对 session workspace 的 claims.json，也可显式配置仓库外
绝对路径；目标文件仍按 session workspace 分类。exclude 优先于 include，
include: [] 表示 workspace 内所有目标。配置不接受未知字段、null、空白值
或错误类型。

规则必须是 UTF-8 严格 JSON，只包含 version、options、blocked、
bounded 规定字段。规则文件不超过 262,144 bytes，总规则 1–256 条，单次文本
不超过 1,000,000 个 UTF-16 code units。匹配是确定性的字面子串，不是事实判断、
正则、分词、模糊匹配或语义推理。完整合成示例见
claims.example.json。

覆盖、审批与失败关闭

- write：检查完整新文本的 blocked 与 bounded。
- edit：只检查 new_string 片段内的 blocked。
- str_replace_editor/create：检查完整新文本的两类规则。
- str_replace_editor/str_replace 与 insert：只检查新片段内的 blocked。
- view、排除路径调用后续策略；未知工具和 workspace 外路径同样继续，但属于
未覆盖，不能称为 pass。

命中后每次都重新请求审批；只有 allowed-once 执行。拒绝、取消、无 responder、
approval 不可用或 never policy 都不会执行。干净调用仍保留下游策略的决定。
规则、配置、可信 workspace 或已知 adapter 出错时直接 deny，不会“警告后放行”。

数据流、权限与边界

插件读取规则文件，并能看到受支持工具的新文本参数。命中 excerpt/reason 可能进入
DSH 审批 UI 与 session audit。插件自身不联网、无遥测、不直接写目标文件；但
DSH 仍可按自身配置访问模型、网络、文件和日志。第三方插件与 DSH 同进程运行，
“本地运行”不等于安全保证，应审阅源码并固定 Release 与 checksum。

它不是事实核查器、自动改写器、DLP、安全沙箱或恶意宿主隔离层。Shell/Python/
Node、MCP、第三方/未知工具、宿主内部写入、workspace 外路径和二进制内容都可
绕过。增量编辑不重建全文，因此删除旧限定词造成的新全文违规可能无法发现。

升级、禁用、卸载与故障排查

升级前先在一次性 profile 中安装新的 checksummed tarball 并重复合成 smoke。
用同一 row id 加 disabled: true 可禁用；卸载命令是：

dsh plugin --profile claim-guard-smoke remove dsh-claim-guard

若规则错误，先修复 claims.json；若写入未被检查，核对冻结 DSH 版本、工具名、
workspace、include/exclude 与 row enabled 状态；若片段中仅有 bounded 风险却未审批，
这是 v1 的明确边界；若没有 approval responder，DSH 会失败关闭。

安全问题请按 SECURITY.md 私下报告；普通 bug 使用脱敏、完全合成的
复现。Roadmap 包括精确重建增量编辑全文、经证据扩展兼容版本、可选只读
claim_check，以及未来单独评估 npm 分发。

许可证：MIT。