前言¶
在 DeepSeek Harness（DSH）裏做智能體或插件開發，常見做法是每一輪對話都讓模型重新讀大量源碼，上下文很快被佔滿，模塊邊界、對外契約和已知風險也難以在會話之間保持一致。手寫一份項目說明又容易和代碼脫節，維護成本高。
dsh-ai-indexer（維護者 cute-gugu，社區分類：記憶）面向上述問題：從源碼註釋派生索引，把全量信息留在磁盤，只把壓縮後的快照按硬 token 上限注入對話；支持增量掃描與交付後復盤。索引事實來源是源碼裏的 @ai: 標記，插件不修改任何源碼。
這是什麼¶
一句話定位：給 AI 一份受 token 預算約束的項目索引，而不是每個會話重新讀完整個代碼庫。
倉庫：cute-gugu/dsh-ai-indexer
目錄頁：skillhub.cn 插件頁
核心功能¶
下面按 README 歸納的四塊能力說明（版本 0.1.0，MIT 許可證）。
增量掃描¶
只看改動過的文件，把項目摺疊成「模塊 + 契約 + 風險」三張表。沒有 @ai: 標記的文件會按目錄自動歸組成模塊，仍能得到結構圖。
受控注入¶
全量索引寫在 .ai-index/index.json 等文件，不佔對話上下文。插件生成 .ai-index/snapshot.md，按 meta.json 裏的 snapshotBudgetTokens（默認 1200）等配置裁剪後，可選前置進模型提示詞。
交付後復盤¶
本輪改動完成後，通過工具 ai_index_review 或命令 /ai-index review 觸發；走宿主原生問答卡片提問，結論追加到 .ai-index/decisions.json，可查、可審計。復盤由工具觸發，而非交付鉤子，避免每輪交付強制多跑一輪模型。
避免重複造輪子¶
動手實現通用設施（配置、事件總線、序列化、UI 基類等）之前，可用 ai_index_wheel 做輪子檢索，並可回寫檢索結論做緩存。
標記規範¶
在任意語言的源碼註釋中寫入下列標記（插件按註釋語法抓取）：
| 標記 | 作用 |
|---|---|
@ai:module <名字> |
文件歸屬模塊；省略時按目錄自動歸組 |
@ai:status done\|wip\|planned\|blocked\|deprecated\|frozen |
模塊狀態，進進度看板 |
@ai:contract <說明或 函數名()> |
對外承諾；函數名會與源碼符號覈對，不一致則報風險 |
@ai:risk <一句話> |
已知風險，進風險面板 |
@ai:note <一句話> |
給下一位讀者的說明 |
@ai:deps <名字或相對路徑> |
依賴項；相對路徑在磁盤上不存在時會告警 |
@ai:ref <項目或鏈接> |
同類實現或參考來源 |
@ai:ecosystem <標籤> |
生態標籤，用作輪子檢索關鍵詞 |
@ai:owner <子系統或人> |
歸屬 |
示例（Lua）：
--[[
@ai:module OptionsPanel
@ai:status wip
@ai:contract 輸出:RegisterOption() 入參:table
@ai:risk 界面縮放未兼容多分辨率
@ai:ref PigOptions
]]
示例（JavaScript）：
/**
* @ai:module auth/token
* @ai:status done
* @ai:contract 輸出:issueToken(userId) verify(token)
* @ai:deps ./storage
*/
安裝與啓用¶
官方 README 給出的安裝方式如下（請將路徑換成本地 clone 或解壓後的目錄絕對路徑）：
dsh plugin --profile <profile> add link:<本目錄絕對路徑>
也可在本倉庫工作區裏用 harness 的 plugin_manager 安裝 install_bundle，目標填本目錄。
安裝後重啓或熱載一次宿主。左側欄會出現「項目索引」入口，設置 → 插件裏也會多一頁。
典型用法¶
模型可調用的工具¶
| 工具 | 用途 |
|---|---|
ai_index_scan |
掃描或增量更新索引；改模塊接口、狀態或依賴後應調用 |
ai_index_query |
按模塊名或關鍵詞查模塊、符號、契約、風險、依賴 |
ai_index_review |
交付後復盤，走原生問答卡片 |
ai_index_wheel |
通用設施動手前的輪子檢索；可回寫檢索結論做緩存 |
人工命令¶
/ai-index scan # 掃描
/ai-index status # 看狀態
/ai-index review # 復盤說明
設置 → 插件 → 項目索引，或左側欄圖標，可打開完整面板：指紋、模塊表、風險面板、變更切片、快照預覽、復盤結論。
產生的文件¶
| 文件 | 誰寫 | 會不會進對話 |
|---|---|---|
.ai-index/meta.json |
只有你 | 否 |
.ai-index/index.json |
插件 | 否 |
.ai-index/snapshot.md |
插件 | 是（只有穩定段） |
.ai-index/master.md |
插件 | 需要時讀 |
.ai-index/cache.json |
插件 | 否 |
.ai-index/decisions.json |
插件（追加） | 否 |
README.md 裏的 <!-- ai-index:sync --> 區塊 |
插件 | 否 |
第一次掃描時創建 meta.json，之後永不覆蓋；你對它的修改是權威的。常用開關示例：
{
"enabled": true,
"injectSnapshot": true,
"snapshotBudgetTokens": 1200,
"snapshotTemplate": "general",
"injectOrder": 60,
"watch": false,
"advisor": { "enabled": true, "maxQuestions": 4, "timeoutMs": 180000 },
"wheel": { "enabled": true, "cacheDays": 7 }
}
snapshotTemplate 可選 general、minimal、deep。
適用場景與注意¶
適合需要在 DSH 中長期維護同一倉庫、希望模型先看到結構化模塊與契約摘要、又嚴格控制上下文 token 的開發者。也適合在改接口或依賴後，用增量掃描刷新風險面板，並在交付後用問答卡片把結論落盤。
使用前請注意：
- 插件以當前 DSH 進程權限運行；安裝前應自行閱讀倉庫源碼與 MIT 許可證，確認可接受其行爲（掃描工作區、寫入
.ai-index/、可選注入快照等）。 - 插件不 import 任何
@deepseek-ai/*包，依賴 node 內置模塊與瀏覽器react；安裝 bundle 不需要聯網取包。 - 社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本文介紹的是社區插件，而非官方應用商店條目。
設計取捨上，索引 100% 派生自源碼，改標記後重掃即可；快照是注入用的唯一形態，裝不下就裁剪段落，不無限增長；復盤結論進 decisions.json，需要落到源碼的 @ai: 標記由模型通過普通編輯路徑修改，你可審查與回滾。
結尾¶
dsh-ai-indexer 把「模塊、契約、風險」從註釋裏抽出來，用增量掃描和 token 預算快照減輕每會話通讀倉庫的負擔，並用交付後復盤把關鍵確認留在磁盤。若要安裝或查標記細節，以 GitHub README 爲準：
- 目錄頁：https://www.skillhub.cn/plugins/cute-gugu/dsh-ai-indexer
- 源碼與文檔：https://github.com/cute-gugu/dsh-ai-indexer
