前言¶
在 DeepSeek Harness (DSH) 的插件化生態中，讓 AI 編碼代理精準理解一個陌生的代碼庫，並在審閱變更時保持嚴格的邊界控制，是開發過程中的常見需求。dsh-repo-atlas 是爲此設計的插件，它幫助代理基於證據分析倉庫，並在有界生命週期內審閱變更提案。
這是什麼¶
dsh-repo-atlas 是一個 DeepSeek Harness 插件，由 zhenkun26 維護。它旨在解決代碼庫理解缺乏結構化證據、變更審閱缺乏生命週期管理的問題。該插件通過提供證據優先的結論和有界的操作策略，讓 AI 能夠安全地進行倉庫接手和變更審閱。
核心功能¶
倉庫分析¶
插件掃描已確認的 workspace，遵循路徑、內容、敏感文件和預算限制。它生成結構化證據、Markdown 報告、架構觀察和推薦閱讀順序。具體包括：
* Onboarding 分析：識別技術棧、入口點、重要目錄、測試、配置，並提供推薦閱讀順序。
* 證據優先的結論：將文件支持的觀察與文本推斷區分開，明確保留部分或未知狀態。
* 有界語法確認：確認選定的 import、聲明和關係，不執行倉庫代碼。
* Session 增量複用：僅在當前 Harness session 內複用兼容證據。
變更提案與生命週期¶
插件追蹤僅限當前 session 的變更流程，包括：
* 定義明確的目標和意圖。
* 審閱、導出和驗證有界補丁。
* 檢查 live worktree 狀態、commit 就緒情況、landing 關係、recovery guidance 和 release readiness。
* 管理隔離 commit、landing preflight、recovery guidance 和 release preflight。
安全邊界¶
爲了確保安全，插件默認以只讀模式運行，並嚴格限制操作範圍：
* 默認只讀：默認路徑爲只讀，不靜默生成或應用補丁、commit、merge、land、push、publish、安裝依賴、訪問網絡或上傳代碼。
* 受控動作：受控動作默認禁用。啓用時需要固定 recipe、顯式審批、sandbox 強制和有界脫敏輸出。
* Session 狀態：證據緩存、提案註冊表、事件歷史和 preflight 評估僅限當前 session，並以 detached 觀察返回。
* Git 生命週期：隔離本地操作是有界的，不提供自動衝突解決、遠程訪問、rollback 或 push。
安裝與啓用¶
加載此插件需要兼容的 DeepSeek Harness checkout。安裝步驟如下：
- 構建插件源碼。
- 將插件路徑添加到 Harness profile。
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm run build
cd /absolute/path/to/deepseek-harness
pnpm install
pnpm dsh plugin --profile web add /absolute/path/to/dsh-repo-atlas
pnpm dsh web
在 Harness Web UI 的插件列表中查找 dsh-repo-atlas/harness。
本地檢查¶
本地開發和檢查需要 Node.js 22 或更高版本。開發者可以運行以下命令驗證代碼質量：
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm test
npm run typecheck
npm run lint
npm run build
維護者可以運行完整倉庫門禁：
npm run validate:openspec
npm run verify:release-preflight
git diff --check
適用場景與注意¶
該插件適合需要在 AI 代理環境中進行結構化倉庫接手和受控變更審閱的場景。使用時需注意：
* 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證（MIT）。
* 默認禁用受控動作，如需啓用，必須配置固定 recipe、顯式審批和 sandbox 檢查。
* 插件僅提供狀態觀察和建議，不執行代碼生成、提交或發佈操作。
