前言¶

DeepSeek Harness（DSH）的智能體在開發過程中經常修改代碼，但容易遺漏同步更新相關文檔。dsh-doc-impact 插件通過確定性執行機制，將代碼變更與文檔更新綁定，建立聲明式的影響圖，確保文檔與代碼保持一致。

核心功能¶

該插件通過以下機制解決文檔與代碼脫節的問題：
* 影響分析：將代碼和文檔鏈接到聲明式影響圖。
* 變更檢測：將工作區與基準（Git 或文件系統）進行對比。
* 規則匹配：將增量變更與項目規則進行匹配。
* 智能引導：在智能體關閉回合前，引導其審查或更新受影響的文檔。
* 標準擴展：作爲標準 Cordis 擴展實現，無需修改 DSH 核心。

安裝與啓用¶

在 Harness 中安裝插件，需要使用 profile 參數。安裝完成後需重啓 Harness 以加載插件。

# 從本地路徑安裝
dsh plugin --profile web add link:/path/to/dsh-doc-impact

# 或安裝已發佈的版本
dsh plugin --profile web add dsh-doc-impact

配置¶

在工作區根目錄創建配置文件 .dsh/doc-impact.yml。

version: 1

defaults:
  mode: remind
  scope: turn
  changeDetection: auto

rules:
  - id: auth-docs
    description: Authentication behavior documentation
    code:
      include:
        - packages/auth/**
        - packages/server/src/auth/**
      exclude:
        - "**/*.test.ts"
    docs:
      - docs/authentication.md
    direction: code-to-docs
    relation: documents
    mode: require-resolution

配置文件定義了代碼與文檔的映射關係。例如，packages/auth/src/session.ts 變更會觸發 docs/authentication.md 的更新檢查。

工作流程¶

插件在智能體的運行流程中執行以下步驟：
1. 記錄基準：在回合開始時，記錄 HEAD 和所有已髒文件的哈希值（Git 模式）或匹配選擇器的文件（文件系統模式）。
2. 停止檢查：在回合結束時，對比工作區與基準，匹配增量變更。
3. 自動解析：自動解析目標文件已被更新的影響。
4. 引導與解決：對於未解決的影響，插件會提醒智能體。在嚴格模式下，智能體需調用 doc_impact_resolve 命令進行確認。

命令與工具¶

插件提供了一系列命令用於查詢和解決文檔影響問題。

插件配置 UI¶

插件提供瀏覽器端的配置界面。在 Harness 的 Settings → Plugins → Plugin Configuration 中，可以找到 “Doc Impact” 卡片。
* 階段編輯：修改不會立即保存，需點擊 Save。
* 狀態反饋：標題欄在存在草稿時會顯示 unsaved 徽章。
* 重置功能：每個字段下方提供 Reset 按鈕，可恢復到配置層設置。

重要說明¶

• 倉庫狀態：原倉庫已存檔並設爲只讀。開發已遷移至 xarleyn/dsh-plugins 單體倉庫。
• 新包名稱：舊包 dsh-doc-impact 已被 @yadsh/dsh-doc-impact 取代。
• 依賴要求：需要 Node.js 版本 >= 20。
• 許可證：MIT 許可證。

結語¶

dsh-doc-impact 通過將文檔影響納入 DSH 的自動化流程，爲開發者提供了確定性更強的代碼與文檔同步保障。