dsh-doc-kit

Readme

# dsh-doc-kit

> 不往 AI 的上下文里塞「记忆」，而是把事实留在文档里。
> 本插件只做两件事：给文档体系做体检（`doc_lint`），并附带一套文档治理规则（`doc-governance` 技能）。

## 为什么放弃记忆插件路线

记忆插件的出发点是「让 AI 记住」：把对话里的事实抽成条目，常驻注入 systemPrompt，从此每轮都带着。
它确实解决了「记不住」，但代价在入库之后才显现：

- **条目常驻，且只增不减**：每一条都永久占注入预算，模型每轮都要读一遍——记得越多，注意力越贵。
- **条目是二次加工的产物**：事实被抽离原文就开始失真；整理动作、审批回执也容易被写成「事实」，在注入层里长期占着预算。
- **它会长成一个需要维护的数据系统**：为了让条目不过期、不超预算、不写错，得再养一套治理层——预算看门狗、整理到期提醒、提案队列、审批界面、备份与断点续跑。这套治理层越做越完整，越说明记忆路线自身的维护成本下不来。
- **真源分裂**：同一个事实既在文档里、又被复制成一条记忆，两边各改各的，漂移无从对齐。

所以记忆插件最后的问题不是「记不住」，而是「记得太多、没人管」——这正是我们放弃它、转投文档路线的原因。

## 换成什么：文档管理路线

- **事实的唯一真源就是文档**：`docs/`、`CONTEXT.md`、项目 handoff。要改事实，改文档那一处。
- **注入层只放索引**：全局 / 工作区 `AGENTS.md` 里只有「哪里有什么、什么时候去读」，不放事实本身。
- **模型按需读，不靠「背」**：需要时 `grep` / `read` 当场取，读完即走。注入层因此恒定小，成本不随事实增长。
- **治理交给 git**：文档天然有 diff、回退与历史，不需要再自造备份、事件日志和审批机器。

代价要说清楚：模型不再「自动记得」，需要时得多一次查找。换来的是注入层稳定、真源单一、维护成本不随内容膨胀。

## 这条路线的失效模式，就是本插件要补的洞

文档路线不是没有风险，只是它的风险**看得见**：索引指向的文件改名/删掉了、注入层被人一点点塞胖、文档里混进决策史、新文档忘了进 git。
这些漂移不会报错，只会慢慢烂掉——而「文档体系自己会不会烂」通常没人查。

`doc_lint` 一次调用把它们变成报告：

- `quota`（FAIL）：L0 / L1 超出自律配额（默认 2 KB / 4 KB）——有人把事实写进了注入层。
- `banned`（FAIL）：注入层出现「曾用 / 已废弃 / 已被推翻 / 别再试」这类措辞——过程凭证混进来了。
- `index`（WARN）：索引点名的文档不存在——指向已经漂移。
- `git`（WARN）：治理文件未跟踪——没有历史，漂移无从发现。

再配一份随包分发的 `doc-governance` 技能，给「该写进哪一层、写前先查什么、多久体检查一次、对外发布前看什么」一套可执行规则。
**检查给事实，技能给规则**——两者加起来才是完整的文档治理。

## 为什么用轻量的 doc-kit，而不是再写一个记忆插件

| | 记忆插件路线 | 文档路线 + dsh-doc-kit |
|---|---|---|
| 事实放哪 | 抽成条目，常驻注入 | 文档本身，按需读取 |
| 常驻成本 | 每条记忆都占预算，随积累增长 | 只有索引，恒定小 |
| 真源 | 文档 + 条目两份，易漂移 | 单一（文档） |
| 版本与审计 | 要自造（备份 / 事件日志） | git 原生 |
| 维护对象 | 条目库 + 一整套治理 / 审批机器 | 文档本身 |
| 工具复杂度 | 存储 + 注入 + 循环 + UI | 只读、零依赖、无 UI、不调 LLM |
| 失效模式 | 条目过时、膨胀、退化成回执 | 索引漂移（`doc_lint` 直接查出） |

一句话：**doc-kit 不管理任何数据**。它没有存储、没有注入、没有定时器、没有模型调用，只是把「文档体系有没有烂」变成一次只读检查，外加一份写文档的规则。
所以它不会成为下一个需要维护的系统——这正是它在记忆插件之后被需要的原因。

## 用法

安装：插件面板（侧栏 **Plugins** → **Add plugin** 填 `github:rezon-aki/dsh-doc-kit`），或命令行 `dsh plugin --profile web add github:rezon-aki/dsh-doc-kit`；重启 `dsh web` 生效。

装好后让模型跑一次：

```
doc_lint
```

输出形如（本机实测）：

```
doc_lint：通过
  [PASS] quota：L0 599 B / 配额 2048；L1 652 B / 配额 4096
  [PASS] banned：无决策史措辞
  [PASS] index：6 条路径全部存在
  [PASS] git：已跟踪（3 个）
```

默认体检当前会话的工作区；在别处体检传 `workspaceRoot`。
四项检查的具体规则在 `lib/lint.js`，工具参数在 `lib/index.js`——README 只讲为什么，细节看代码与技能本身。

`doc_lint` 全程只读：它报告问题，不改任何文件。

卸载：`dsh plugin --profile web remove dsh-doc-kit`。技能库里的 `doc-governance` 是技能库自己的文件，不会被自动删除。

## 它明确不做什么

- 不注入任何 prompt（`AGENTS.md` 的分层 / 优先级 / 预算由平台原生机制负责）。
- 不自动改写任何文件；往注入层加内容仍需你同意。
- 不替你做判断：软检查只提示，处理与否由你决定。

## License

MIT