功能地图 megablue/dsh-feature-map

dsh-feature-map

一个 DeepSeek Harness 插件，让智能体先读项目文档，再读源码。

Listed on DSH Plugin Hub

想找到某个功能区的代码，通常得先 grep 整棵树，打开三个文件，再判断哪些部分才真正相关。功能地图把这一步换成每个功能一页文档——这个区域涉及的文件、类型、测试和坑——智能体就能直接要它需要的那一块。dsh-feature-map 把这张地图放进智能体的提示词，给它五个工具，按问题的大小读取地图，并且在有地图的项目里，拒绝会话中的第一次源码查找，只拒一次，同时给出原因和解决办法。

它还负责先把地图做出来：项目里什么都没有，用 feature_map_init；已经有文档，用 feature_map_adopt；地图已经长得不成样子，用 feature_map_regen。

你能得到什么

| 工具 | 作用 |
| feature_map | 读取地图：索引、某个主题的各节、某一页的结构、某一节、某个 ###，或者整页。 |
| feature_map_check | 报告漂移——没有索引行指向的页面、链接指向不存在位置的索引行——另外单独报告大到一次读不完的节。 |
| feature_map_init | 把工作流脚手架写进项目：AGENTS.md、HANDOFF.md、docs/SPEC.md 和地图索引。 |
| feature_map_adopt | 报告现有项目缺什么，只写不存在的文件。 |
| feature_map_regen | 重写已有地图，让它读起来通顺：补上缺失的标题和 Status: 行，把每个过大的章节拆成 ###，并核对索引。 |

另外还有一段提示词，说明阅读顺序；以及一个守卫，每个会话强制执行一次（见 你会注意到什么）。

安装

复制粘贴（已在 desktop 配置档上验证）：

dsh plugin --profile desktop add github:megablue/dsh-feature-map

或者从源码安装。这个插件是 DSH bundle，所以从当前目录安装，并在运行中的应用里生效：

- 在应用的插件设置里，把当前目录添加为 bundle。
- 或者，如果你从智能体会话里驱动 harness，就用插件管理器安装，指向这个 checkout 的绝对路径（…\projects\dsh-feature-map）。它会链接包，把 feature-map 行加到配置档，并实时激活。

插件本身的代码改动需要重启应用：配置档不会监听模块文件，切换插件行只会重新应用补丁，不会重新加载模块。编辑项目的文档则什么都不需要。

兼容性与权限：面向 DSH 0.2.0-rc.2、本地工作区。从宿主文件系统读取 docs/features/；写入走 harness 文件系统接缝，受配置档的沙箱策略约束。无依赖、无 peer 依赖、无网络调用。

开始一个新项目

两步：拿到文档，然后填写只有你能回答的部分。

1. 要脚手架。 说 「在这里搭好文档工作流」——或者直接点名工具 feature_map_init。它会返回为你的项目渲染好的四份文档，不写入任何内容：

| 文件 | 用途 |
| AGENTS.md | 流程与硬性规则：命令、工作流、适用于每次变更的约束。 |
| docs/features/README.md | 地图索引与页面模板——智能体最先读的入口。 |
| docs/SPEC.md | 用户可见的行为，不了解代码也能读懂。 |
| HANDOFF.md | 易变的会话状态：正在进行什么、下一步是什么。 |

2. 写它们。 要么调用 feature_map_init 并传 write: true——它通过 harness 文件系统接缝写入，所以配置档的沙箱策略仍然生效——要么自己写返回的文本。已有文件绝不会被替换；只有你确实想替换时才传 force。

3. 填写标记的位置。 文档会说明哪些地方还是占位符：AGENTS.md 里的布局、命令和硬性规则，以及地图索引的第一行。搭好脚手架却没填的文档，读起来像权威内容，实际什么都没说——占位符故意做得显眼。

4. 写你的第一个页面。 从 docs/features/README.md 里复制页面模板，给它一个功能：它做什么、里面有哪些名称、怎么工作、它的设置、固定它的测试，以及它和什么相关。然后调用 feature_map_adopt——它会根据页面自身的标题和 Read when: 行，这样你就不用手工维护表格了。

5. 确认。 feature_map_check 应该报告映射与自身一致。

从这时起，循环就是文档描述的工作流：先读映射，再看代码；改动和页面更新放在同一个提交里。

接入已有项目

feature_map_adopt 是只读的，除非你传 apply: true；而且它绝不修改已经存在的文件。它报告什么，取决于你手上有什么。

如果你已经有某种形式的特性映射

不带参数调用 feature_map_adopt。你会得到一行摘要和五个部分：

- 索引 —— 链接无法解析的行、没有任何行链接的页面、缺少 Read when: 触发的行，以及为未链接内容需要新增的行。
- 页面 —— 每个页面缺少六个规定标题中的哪几个、哪些页面没有 Status: … Read when: 行、哪些页面没有被链接。
- 章节 —— 每个超出大小限制的章节，以及它是已经在 ### 层级上分好了，还是确实需要拆分。已经分好的长章节不算工作量，报告会说明这一点。
- AGENTS.md —— 你的指令文件缺少模板中的哪些块，按名称列出。你自己的措辞绝不会被动到；你拿到的是缺失的块，直接粘贴即可。
- 映射之外 —— docs/ 下不属于映射页面的 markdown，附上大小和章节数。只报告，绝不移动：docs/GAME.md 该不该变成特性页面，由你决定，工具不插手。

然后是一份计划，其中每一项都标为 deterministic（由你文件中已有的内容推导而来 —— 索引行、缺失的块）或 judgment（Read when: 触发、某个标题的内容、长章节从哪里拆分）。apply: true 只写入不存在的文件；其余都是文本，由你或你的智能体来放置。

如果你的映射状态已经不错，这份报告会很短：它报告漂移、过大的章节和映射之外的文档，然后结束。

如果你的映射已经超出原有形态

在工作流出现之前写下的映射，读起来往往是一整段过大的章节，没法一次性交给别人。feature_map_regen 会重写它：补上缺失的 ## 标题和 Status: … Read when: 行，把每个过大的章节拆成适合一次阅读的 ### 块，并让索引与现有页面保持一致。它不改动任何正文 —— 唯一对句子的改动，是把简短的加粗引导语变成它上方的标题 —— 也不碰 docs/features/ 之外的任何东西。

它无法用你自己的话命名的块，会显式地留作未命名：

这样之后给它们命名，只需在回复里过一遍列表，而不用到处找。在你传 apply: true 之前它什么都不写，而且跑第二遍不会有任何变化。如果你想在写入前先看结果，用 show: true 调用它。

如果你还没有特性映射

三种情况，插件会告诉你自己属于哪一种：

- 有文档，但没有地图（比如 docs/ 里放着一份 spec 和一些笔记）。报告会把这些文档列为候选，并告诉你目前还没有页面。迁移分两趟：先在 docs/features/ 下写功能页面——一个功能一页，套用模板——然后再跑一次 feature_map_adopt，它会根据这些页面生成索引。feature_map_init 会把索引和页面模板交给你，作为起点。
- 有 AGENTS.md，但没有文档。 报告会列出你的 AGENTS.md 缺了哪些指令块，并指向 feature_map_init 去拿地图骨架。apply: true 会写入地图索引、HANDOFF.md 和 docs/SPEC.md，你的 AGENTS.md 原封不动。
- 什么都没有——没有文档，也没有 AGENTS.md。那就没有东西可采纳：回复会直接说明，并把你送到 feature_map_init，也就是上面「启动新项目」那条流程。

不管你属于哪种情况，插件都不会改写你的文字、不会凭空编一个 Read when: 触发条件、不会替你判定什么算一个功能、也不会移动文件。它只做测量、提建议，以及在你要它做的时候，把缺的东西建出来。

写页面

地图就是普通的 markdown，人可以自己写、自己审。一个功能一页，标题按这个顺序排：

<Feature> — <one-line summary> Status: shipped (vX.Y) · Read when: <the phrase someone would search for>

What it does what it is for, in a few bullets
Map the files, types, functions and test names — the payload How & why the mechanism, the invariants, the traps Config keys / UI a dense table: key, default, range, where it is set Tests that pin it the test names to run first Related links to the other pages

两条规则让地图值得一读：

- 写名字，绝不写行号。 行号会烂掉；符号名能扛过一次重构。
- 每节控制在两 KB 左右，更长的就用 ### 拆开。一节是后来的会话会单独读的东西，一节要是长到一次读不完，就得先拆开，才能整块交出去。feature_map_check 会点名哪些节超了。

你会注意到什么

在有地图的项目里，一个会话的第一次 read、grep 或 glob 会被拒一次：

Error: read "src/widgets.js" reads source in a project that keeps a feature
map. Call feature_map first … This is the only time this session will ask; call read again and it will proceed.

打断就这么多。一个会话里绝不会发生第二次，没有地图的项目里绝不会发生，智能体已经查过地图时也绝不会发生。读 docs/、AGENTS.md、HANDOFF.md 或 README.md 从不被当作查源码。

如果某个会话在做地图帮不上忙的事——比如一次大规模机械重构——把 mode 设成 prompt，只给指令、不加拦截；设成 off，两者都静音。

配置

在你的配置档里通过插件配置来设置。

| 键 | 默认值 | 作用 |
| mode | enforce | enforce 会拒绝第一次来源查找；prompt 保留指令、去掉守卫；off 两者都静默。未知值回退到 enforce。 |
| sourceTools | read、grep、glob | 哪些工具算作来源查找。 |
| exemptPaths | docs/、AGENTS.md、CLAUDE.md、HANDOFF.md、README.md | 相对项目的前缀，永远不算来源查找。 |
| maxBytes | 12000 | 单条回复的字节预算；被截断的回复会说明从哪里继续。 |
| sectionsPerTopic | 3 | 一个话题回复可以带多少节。 |
| maxSectionBytes | 2048 | 一节在多大以内可读；超过后，检查器会报告这一节。 |
| sectionOrder | read 工具的槽位 | 指令在提示词里的位置。 |

细节在哪里

这份 README 讲的是怎么用插件。其余内容都在仓库里：

- docs/SPEC.md —— 一个会话能看到什么，完整版。
- docs/features/ —— 插件自身的功能地图：地图工具、守卫、样板、采用、重新生成、打包。
- AGENTS.md —— 怎么开发这个插件。
- HANDOFF.md —— 目前进展到哪。
- templates/ —— 插件交给项目的样板。

请我喝杯咖啡

如果这个插件对你有用，可以通过 PayPal 请我喝杯咖啡。

许可证

MIT —— 见 LICENSE。