前言¶
DeepSeek Harness (DSH) 插件生態旨在通過模塊化擴展智能體能力。在長期項目協作中，智能體會話往往面臨上下文窗口限制與認知碎片化的問題，即“任務做完即忘，新會話從頭學起”。爲了解決這一痛點，project-ai-docs 提供了一套通用協議，旨在將項目認知沉澱在文檔而非會話記憶中。
插件簡介¶
project-ai-docs 是一個通用項目 AI 文檔協議 skill。其核心邏輯是爲每個項目維護一份獨立的 docs/.ai/ 認知庫。智能體在執行任務前，會先讀取該庫的索引，再針對性讀取相關文檔；任務完成後，改動會自動回寫到文檔中。這種方式旨在防止上下文渙散，並保持項目認知的精細度。
核心功能¶
該插件通過以下協議與機制保證文檔體系的有效性：
- 地圖先行：
index.md作爲唯一入口，構建全文檔的路由表。 - 分層預算：將文檔劃分爲 core/modules/config/best-practices 四層，顯式控制 token 開銷。
- 紅線前置：硬約束（禁止項）置於
index.md頂部，優先於技術細節。 - 點讀代替全讀：按任務需求只讀取相關切片，避免冗餘信息干擾。
- 寫回閉環：任務結束即視爲文檔更新，知識沉澱在文檔系統。
- 增量感知：通過
changelog臺賬記錄變更，新會話讀取尾部即可掌握項目現狀。 - 人機分離：
README.md面向用戶，docs/.ai面向智能體。 - 事實可驗：文檔內容僅包含實測路徑、版本與命令，杜絕猜測。
安裝與啓用¶
DSH 官方安裝（推薦）¶
使用插件命令安裝，隨 profile 管理：
dsh plugin --profile web add project-ai-docs
安裝完成後重啓 DSH 進程即可生效。
本地驗證安裝¶
若需在未發佈到 npm 的本地代碼上測試：
dsh plugin --profile web add file:D:\Desktop\project-ai-docs
工作原理¶
B 路安裝利用包內的 dsh.bundle.patch 配置，將其指向 cordis.patch.yml，進而加載 extensions/dsh/index.js。該適配器會將 skills/ 目錄下的內容註冊爲 DSH 的技術源。
其他宿主¶
對於 Claude Code、Codex 等非 DSH 宿主，直接複製 skills/project-ai-docs/ 目錄至其對應的 skills 路徑即可使用。
使用方式¶
插件定義了三個標準階段，按順序執行：
1. 新會話開始¶
智能體啓動時，先讀取 index.md 和 changelog，根據任務需求點讀相關分層文檔，建立上下文。
2. 初始化項目文檔¶
觸發命令爲 /init。執行 Init 協議：
* 掃描項目結構
* 建立文檔骨架
* 實測填充內容
3. 任務完成後¶
執行清理與回寫流程：
* 清理冗餘信息
* 回寫對應文檔
* 在 changelog 中記賬
生態與依賴¶
- 依賴：該插件依賴
@deepseek-ai/dsh-skill-filesystem作爲 peer dependency（可選）。 - 許可證：MIT。
- 目錄結構：
skills/project-ai-docs/：運行時技能單元。extensions/dsh/index.js：DSH bundle 適配器。cordis.patch.yml：bundle 註冊配置。
結語¶
project-ai-docs 提供了一套結構化的文檔管理方案，幫助開發者與智能體在 DSH 環境下建立持久、可驗證的項目認知體系。更多細節與源碼，請參考其 GitHub 倉庫。
