dsh-git-ai：DeepSeek Harness 插件，將智能體編輯記錄歸因給 git-ai

DeepSeek Harness（DSH）採用插件化架構，旨在通過模塊化擴展能力。在使用智能體進行代碼開發時，開發者需要清晰地掌握具體由哪個模型、在哪個會話中對哪些文件進行了修改。dsh-git-ai 插件解決了這一歸因需求，它將智能體的操作記錄轉化爲 git-ai 可識別的數據，從而實現代碼變更的自動追溯。

插件定位¶

dsh-git-ai 是 DeepSeek Harness 的一個插件，由開發者 NiuZhuang 維護。它位於「記憶」分類，採用 MIT 許可證。其核心功能是攔截 DSH 的工具執行鉤子，將文件編輯、使用的模型以及會話信息轉換爲 git-ai 的 agent-v1 檢查點 payload，並調用 git-ai 的 checkpoint 命令進行記錄。

核心功能¶

該插件主要通過攔截和轉換數據實現歸因：

攔截點監聽：攔截 DeepSeek Harness 的 tools/pre-execute 和 tools/post-execute 兩個攔截點。
數據記錄：記錄文件編輯操作、使用的模型名稱以及會話信息。
協議轉換：將捕獲的工具調用轉換爲 git-ai 通用接口 agent-v1 的 payload 格式。
Shell 支持：支持對 bash 和 pwsh 命令的 pre/post shell 檢查點記錄。
可配置項：提供豐富的配置選項，包括指定 git-ai 可執行文件路徑、設置 agent 名稱、指定模型、檢查點預設、調用超時時間以及是否追蹤 bash 命令。

安裝與啓用¶

安裝該插件可以通過以下命令完成：

dsh plugin --profile web add dsh-git-ai

如果使用 pnpm 版本大於等於 10，安裝命令需要加上 -w 參數以避免工作區根目錄衝突：

dsh plugin --profile web add -w dsh-git-ai

該包聲明瞭 dsh.bundle，在執行上述命令時會自動激活配置。如果需要手動加載或在自定義 profile 中配置，需在 cordis.patch.yml 中添加如下塊：

- dsh-git-ai:
    gitAiPath: git-ai
    agentName: deepseek-harness

典型用法¶

完成安裝與配置後，可以通過以下步驟驗證功能：

安裝插件：執行安裝命令。
配置插件：在 cordis.patch.yml 中添加上述配置塊。
啓動 Harness：運行 dsh web 啓動服務。
編輯文件：讓智能體編輯 git 倉庫中的文件。
檢查狀態：運行 git-ai status --，查看 git-ai 是否接收到了檢查點數據。
提交與驗證：執行 git add -A && git commit -m "test" 提交，隨後運行 git-ai stats HEAD --json 檢查歸因統計。

配置項說明¶

插件支持通過配置對象進行細粒度控制，配置項包括：

import type { Config } from 'dsh-git-ai'

const config: Config = {
  gitAiPath: 'git-ai',                  // 可選：git-ai 可執行文件路徑（省略時通過 PATH 解析）
  agentName: 'deepseek-harness',        // 可選：標記在所有檢查點上的 agent_name
  model: '',                            // 可選：顯式指定的模型，空則回退到 agent.options.model
  checkpointPreset: 'agent-v1',         // 可選：git-ai 的通用集成預設
  timeoutMs: 10_000,                    // 可選：git-ai 調用超時時間（毫秒）
  trackBash: true,                      // 可選：是否爲 bash/pwsh 發送 pre/post shell 檢查點
}

適用場景與注意事項¶

依賴關係：git-ai 是可選依賴。如果 git-ai 未安裝、調用失敗或超時，插件僅記錄警告而不會中斷工具調用。
編輯歸因限制：文件編輯工具目前僅發送 post-edit 檢查點。這意味着如果用戶在智能體編輯前對同一文件進行了未提交的修改，這些修改可能會被誤歸因給智能體。
Bash 輸出限制：Bash 輸出的歸因基於快照，僅限倉庫樹內的文件修改會被歸因，倉庫外的文件修改無法被追蹤。
同步延遲：每個被追蹤的工具調用都會等待 git-ai 檢查點完成（受 timeoutMs 限制）後再返回結果，這會增加工具調用的同步延遲。

總結¶

dsh-git-ai 爲 DeepSeek Harness 用戶提供了一種標準化的方式，將智能體的操作行爲與 git-ai 的歸因系統打通。通過攔截工具執行鉤子並生成符合 agent-v1 規範的 payload，它幫助開發者實現了代碼來源的可追溯性。更多細節與源碼可參考其 GitHub 倉庫或社區目錄頁面。