dsh-kit：填补 DeepSeek Harness 插件生态空白的实用工具

前言¶

DeepSeek Harness (DSH) 采用了插件化架构，拥有庞大的生态系统（超过 13,000 个相关仓库）。dsh-kit 提供了 8 个插件，旨在解决智能体在无人检查时产生的“安静失败”。其中 4 个功能填补了现有插件生态的空白，另外 4 个则提供了现有替代方案的更优实现。

安装与运行环境¶

插件为纯 ESM JavaScript，无构建步骤，因此无需 prepare 脚本或 allowBuilds 权限。唯一运行时依赖是 @deepseek-ai/schemastery。

安装命令如下：

dsh plugin --profile web add github:FoyonaCZY/dsh-kit
dsh --profile web

如需锁定版本以确保供应链安全，可指定 commit hash：

dsh plugin --profile web add github:FoyonaCZY/dsh-kit#<sha>

Node 引擎要求：>= 22。

插件列表¶

该包包含以下 8 个独立插件：

autoformat：在 agent 写入的文件上运行项目格式化器。
artifact-guard：阻止 agent 手动编辑锁文件、构建输出、生成代码。
env-drift：报告 agent 添加但未记录的环境变量。
verify：在报告完成前运行项目检查（如 typecheck）。
checkpoint：回滚工作区。
secret-guard：从工具输出中删除凭据。
git-context：在提示中提供分支、工作树、提交信息。
notify：桌面通知。

核心功能详解¶

autoformat¶

在文件上运行项目格式化器。为了避免干扰，格式化器仅在项目已配置时运行。插件会检测 .prettierrc、node_modules/.bin/prettier 等配置文件，支持 Prettier、gofmt、rustfmt、ruff、black 等工具。如果格式化器拒绝文件，该错误会附加到工具结果中。

artifact-guard¶

防止 agent 手动编辑机器生成的文件（如 pnpm-lock.yaml、dist/ 下的文件、生成的 protobuf 绑定）。它通过两种信号识别文件：
1. 路径规则：识别 lockfiles、构建输出、vendored 树。
2. 内容标记：识别 @generated、DO NOT EDIT 等标记（仅检查文件前 20 行）。拒绝编辑时，系统会提示 agent 修改配置文件而非直接编辑。

env-drift¶

捕获 agent 添加但从未记录在模板中的环境变量。插件会在成功写入文件后读取模板文件（默认为 .env.example、.env.sample、.env.template），提取访问到的变量，并将缺失项报告给 agent。系统会自动过滤 NODE_ENV、CI、PATH 等运行时变量。

verify¶

在回合结束前运行项目检查，确保 agent 报告“完成”时代码确实可用。默认自动检测 typecheck 命令（优先查找 package.json 中的脚本，否则执行 tsc --noEmit）。如果检查失败，回合不会结束，agent 会继续工作。该功能有 maxRounds 限制，防止无限循环。

配置示例¶

禁用插件¶

在 cordis.patch.yml 中设置 disabled: true。

- id: dsh-kit-notify
  disabled: true

autoformat 配置¶

指定要格式化的文件扩展名、命令和检测规则。

- id: dsh-kit-autoformat
  config:
    formatters:
      - extensions: ['.ts', '.tsx']
        command: npx --no-install prettier --write {file}
        detect: ['.prettierrc', 'node_modules/.bin/prettier']
      - extensions: ['.sql']
        command: sqlfluff fix --force {file}
        detect: []
    timeoutMs: 15000
    reportFailures: true

artifact-guard 配置¶

设置拒绝行为和检测标记。

- id: dsh-kit-artifact-guard
  config:
    onArtifact: ask
    detectMarkers: true
    allowPaths: []

env-drift 配置¶

指定模板文件路径和忽略变量。

- id: dsh-kit-env-drift
  config:
    templates: ['.env.example', '.env.sample', '.env.template']
    ignore: ['NODE_ENV', 'CI', 'PATH']

verify 配置¶

自定义检查命令。

- id: dsh-kit-verify
  config:
    checks:
      - name: typecheck
        command: pnpm typecheck
      - name: unit tests
        command: pnpm test -- --run
    autoDetect: ...

注意事项¶

无构建步骤，纯 ESM JavaScript。
唯一运行时依赖是 @deepseek-ai/schemastery。
格式化器仅在项目已配置时运行。
环境变量仅在项目有模板时报告。
Node 引擎要求：>= 22。