前言¶
在 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
