dsh-workspace-snapshot：DeepSeek Harness 的只讀 Git 工作區探針

在 DeepSeek Harness (DSH) 的開發實踐中，讓 AI Agent 在修改代碼前檢查當前 Git 狀態是一個常見需求。現有的 Git 工具往往功能過於複雜，或者不僅限於“檢查”功能，容易導致 Agent 誤執行提交或切換分支等破壞性操作。dsh-workspace-snapshot 提供了一個受控的、只讀的解決方案。

功能定位¶

dsh-workspace-snapshot 是 DeepSeek Harness 的一個客戶端插件，由 txy-ucas 維護。它通過向模型暴露一個 workspace_snapshot 工具，將 Git 工作區的狀態（如分支、跟蹤狀態、文件變更分類）報告爲經過驗證的結構化數據。這是一個“探針”而非完整的工作流，其核心價值在於安全地讀取狀態。

核心能力¶

該插件主要提供以下能力：

• 只讀狀態報告：通過 ctx.subprocess 運行 Git 命令，報告當前分支、跟蹤分支、ahead/behind 數量、detached HEAD 狀態以及工作區是否乾淨。
• 路徑分類：明確區分路徑的類型，包括：
  • changed：有變更的文件，細分爲 indexStatus（暫存區狀態）和 worktreeStatus（工作區狀態）。
  • conflict：存在合併衝突的文件。
  • untracked：未被跟蹤的新文件。
• 嚴格的操作限制：插件聲明瞭只讀權限，實際上：
  • 永遠不會暫存文件。
  • 永遠不會切換分支。
  • 永遠不會寫入 Git 配置。
  • 永遠不會創建提交或推送。
  • 默認禁用了 Git 的鎖、FSMonitor 和 untracked cache，以確保查詢結果不受環境干擾。
• 結構化輸出：返回的 JSON 對象包含完整的統計信息（stagedCount, unstagedCount, untrackedCount 等）以及路徑條目，且路徑均爲相對於倉庫根目錄的，不暴露絕對路徑。

安裝與啓用¶

安裝前請確保環境滿足依賴要求：Node.js ^22.19.0 || >=24.0.0 和 DeepSeek Harness 0.1.0-rc.6。

使用官方預構建包安裝：

dsh plugin --profile web add https://github.com/txy-ucas/dsh-workspace-snapshot/releases/download/v0.1.0/dsh-workspace-snapshot-0.1.0.tgz

安裝後，可以通過以下命令驗證插件是否正確加載：

dsh --profile web --dump-config

輸出中應包含 workspace-snapshot 配置行。

典型用法¶

Agent 在收到指令後，可以調用 workspace_snapshot 工具。例如，Agent 收到的指令如下：

Inspect the Git workspace before making changes.

工具返回的 canonical 對象示例如下：

{
  "status": "ok",
  "repositoryRoot": ".",
  "branch": "feature/status-tool",
  "detached": false,
  "upstream": "origin/feature/status-tool",
  "ahead": 2,
  "behind": 0,
  "clean": false,
  "entries": [
    {
      "kind": "changed",
      "path": "src/index.ts",
      "indexStatus": "M",
      "worktreeStatus": "M"
    },
    {
      "kind": "changed",
      "path": "README.md",
      "indexStatus": ".",
      "worktreeStatus": "M"
    },
    {
      "kind": "untracked",
      "path": "notes.txt"
    }
  ],
  "totalPaths": 3,
  "conflictCount": 0,
  "stagedCount": 1,
  "unstagedCount": 1,
  "untrackedCount": 1,
  "omittedPaths": 0,
  "truncated": false
}

配置項¶

插件安裝後使用默認配置。如果需要調整，可以在 --profile web 的配置文件中覆蓋：

- id: workspace-snapshot
  config:
    timeoutMs: 5000
    maxGitStdoutBytes: 262144
    maxPathRecords: 500
    maxResultBytes: 131072

配置項說明如下：

注意：配置是扁平的，且如果設置無效的限制，插件將無法加載。

適用場景與注意事項¶

• 適用場景：適合需要 Agent 評估當前代碼庫狀態（如是否有衝突、未提交更改）的場景，特別是在只讀部署環境中。
• 使用限制：這是一個探針工具，不是完整的工作流。如果 Agent 需要檢查具體變更的行內容、創建提交或管理分支，應使用專門的 Git 工作流或審查插件。
• 安全性：插件通過 inject = ['tools', 'subprocess'] 聲明依賴，僅當 Cordis 的這兩個服務同時可用時纔會激活。子進程環境清除了所有 GIT_* 環境變量，確保查詢結果不受用戶或模型控制的環境變量影響。
• 來源覈查：安裝前建議查看源碼與許可證。該插件使用 MIT 許可證，並在 GitHub 上提供維護。

dsh-workspace-snapshot 提供了一種安全、受控的方式來讓 Agent 獲取 Git 工作區的只讀快照，是構建健壯智能體工作流的有力補充。