diffusion-map

Files (43)

• .gitignore
• SKILL.md
• openai.yaml · agents/
• bun.lock
• evals.json · evals/
• capture.ts · evals/visual/
• fixture-kit.ts · evals/visual/
• fixtures-en.ts · evals/visual/
• fixtures.ts · evals/visual/
• readme-shots.ts · evals/visual/
• rubric.md · evals/visual/
• package.json
• cli.md · references/
• data-model.md · references/
• protocol.md · references/
• dm.ts · scripts/
• model.ts · scripts/lib/
• outline.ts · scripts/lib/
• server-info.ts · scripts/lib/
• session.ts · scripts/lib/
• store.test.ts · scripts/lib/
• store.ts · scripts/lib/
• transcripts.test.ts · scripts/lib/
• parse.ts · scripts/lib/transcripts/
• sync.ts · scripts/lib/transcripts/
• server.test.ts · scripts/
• server.ts · scripts/
• tsconfig.json
• index.html · web/
• api.js · web/js/
• format.js · web/js/
• home.js · web/js/
• i18n.js · web/js/
• icons.js · web/js/
• layout.js · web/js/
• main.js · web/js/
• map-view.js · web/js/
• markdown.js · web/js/
• palette.js · web/js/
• panel.js · web/js/
• renderer.js · web/js/
• shell.js · web/js/
• styles.css · web/

SKILL.md (first lines)

# 扩散图谱

进入这个模式后，你同时做两件事：

1. **和用户正常对话**：讲解、讨论、追问。这仍然是主要工作，质量不能因为维护图谱而打折。
2. **维护一张扩散图谱**：从几个支柱出发，随着对话把信息结构向外生长、重组。图谱是对话的副产品，由你主动判断何时增长、怎么调整，不需要等用户下指令。

图谱存放在 `~/.efficient-coding/diffusion/maps/<slug>/`，跨会话、跨 Agent 都能继续。用户在本地网页上看它实时生长，点开节点可以回看当时的对话。

## 准备

- 这个 skill 目录记为 `SKILL_DIR`。只需要 Bun：不用 `bun install`，也没有任何构建步骤。网页的界面库和字体由浏览器从 CDN 加载。
- 下文的 `dm` 都指 `bun "$SKILL_DIR/scripts/dm.ts"`。**不要 cd 到 skill 目录再执行**，保持在当前工作目录直接调用，这样会话的 cwd 才会记录正确。
- 当前会话（Claude Code 或 Codex）由 CLI 从环境变量中自动识别。所有改动图谱的命令都会自动把当前会话关联到受影响的节点，不需要你手动处理 session id。

## 开场

1. 执行 `dm maps`，看有没有与本次主题相符的图谱。
2. **继续已有图谱**：执行 `dm show -m <slug>` 读取大纲。用两三句话说明目前的进展（支柱有哪些、哪些已经稳定、frontier 还有哪些），给出 2–3 个可以继续的方向，然后顺着用户的选择往下聊。
3. **新建图谱**：
   - 弄清用户的意图。意图清楚就不要追问；不清楚最多问一个问题。
   - 设计这张图的 **lens**：支柱代表什么、有哪些节点类型、状态用哪些词、节点之间有哪几种关系。lens 没有固定模板，按这次的意图来定。设计方法和示例见 [references/protocol.md](references/protocol.md)。
   - 提议 3–7 个支柱，每个用一句话说明为什么它是支柱。和 lens 一起交给用户确认，按用户的调整修改。
   - 确认后执行 `dm new`，再用一次 `dm apply` 写入支柱。
4. 执行 `dm serve -m <slug>`，把网址告诉用户（本机地址，以及同一网络下其他设备可用的地址）。服务已经在运行时，这条命令只打印网址；服务连续 30 分钟没有被访问会自动退出，下次调用再启动即可。用户只想本机访问时，加 `--host 127.0.0.1`。

## 每一轮对话

先把这一轮的对话做好，然后问自己：**这一轮之后，信息结构应该变成什么样？**

- **生长**：某个点被实质性地讲清楚了，就作为节点挂到最合适的父节点下。只是提到、还没有展开的点，用 lens 里 `open` 语气的状态加进来，作为后续可以扩散的方向。
- **调整**：发现两个节点其实是同一件事，就合并；层级放错了，就移动；之前的理解有误，就修改摘要或状态；不同分支之间存在关系，就连一条边。
- **状态推进**：用户表现出已经理解、已经拍板，或者已经否决，就更新状态。
- **登记讨论**：这一轮讨论到了已有节点，但结构没有变化，就用 `touch` 记录，这样网页上能从这些节点找到这次对话。

一轮里的所有变化，用**一次** `dm apply` 提交，格式见 [references/cli.md](references/cli.md)。不需要每轮都改：纯闲聊，或者只是在复述已有内容时，什么都不做。

在对话里，图谱的更新最多用一句话带过，比如"图谱：新增『借用检查』，并入『生命周期』"。不要把记账过程展开给用户看。

## 什么时候先和用户确认

大多数调整直接做。下面这些影响大的改动，先说明再动手：

- 增加、删除或更换支柱；
- 删除一棵子树，或者删除已经关联了会话的节点（`remove --cascade`）；
- 修改 lens（`dm lens`），比如新增或删除节点类型、修改状态体系。

拿不准结构该怎么组织时，也可以直接问用户，比如"这个更像 A 的一部分，还是一个独立的支柱？"

## 用户主动要求时

用户说"展开这个""把 X 拆开""这两个合并""删掉这块"时，照做。展开节点就是围绕它讲解，然后把讲到的内容按上面的规则长进图谱。

## 删除图谱

用户可以自己在网页的图谱列表页删除（卡片上的删除按钮，带确认）。在对话里，只有用户明确要求时才删除整张图谱（例如快照占用空间太大，或者主题已经不需要了）：

1. 先执行 `dm delete -m <slug>` 预览，它会列出节点数、关联对话数和占用空间，但不会删除任何东西；
2. 把预览结果告诉用户，确认后再执行 `dm delete -m <slug> --yes`。

删除只会移除这张图谱的事件日志和会话快照；Claude Code、Codex 自己的原始会话记录不受影响。`dm maps` 会列出每张图谱占用的空间。

## 节点摘要怎么写

节点摘要会显示在网页的知识卡片上，用户以后会脱离当时的对话单独回看。所以：

- 写成能单独读懂的 1–4 句话（支持 Markdown），讲清这个节点**是什么**、**为什么重要**，或者**结论是什么**；
- 不要写"如上所述""我们刚才讨论的"这类依赖上下文的话；
- 理解加深或者结论变了，就更新摘要。

## 参考

- [references/protocol.md](references/protocol.md)：生长和重组怎么判断、lens 设计、示例（学习、项目构思、做决策）
- [references/cli.md](references/cli.md)：命令和 `apply` 操作格式
- [references/data-model.md](references/data-model.md)：数据存储、事件格式、会话快照

From jtsang4/efficient-coding, MIT.

More from jtsang4/efficient-coding