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。