🗺️ dsh-context-map
中文 · English
把一段对话的上下文,画成一张能贴进文档的信息架构图。
目标 · 背景 · 决策 · 动作 · 产物 · 风险 · 待确认 —— 分层成图,一次输出 SVG / 交互式 HTML / Mermaid。
场景 · 快速开始 · 示例 · 能力 · 参数 · 安装排错 · 区别 · 常见问题
这张图由插件自己生成:examples/spec.json → docs/context-map-example.svg(23.9 KB),没有用任何设计工具。
为 DeepSeek Harness 补齐「把对话变成结构」这一步。
一次长会话结束时,真正值钱的东西散落在上下文里:为什么改了方向、哪个文件才是产物、还有哪些没定。翻聊天记录找不回来,截图又不带结构。
dsh-context-map 给 agent 一个工具 context_map:agent 把对话蒸馏成节点,插件负责校验 → 布局 → 渲染。你得到的是左→右推进的分层结构,不是放射状的思维导图 —— 父子关系一眼可读。
- 零运行时依赖,不带 API key,不联网,不读会话日志
- 确定性布局:同一份输入永远得到同一张图,同一天重建字节一致,可以提交进 git
- 三种产物:矢量 SVG、可缩放可搜索的 HTML、可进 PR 的 Mermaid Markdown
懒得自己装? 把这句话发给你的 agent:
帮我安装 dsh-context-map 插件:dsh plugin --profile web add dsh-context-map, 装完跑 dsh --profile web --dump-config 确认有 context-map 这一行。
什么场景用
| 场景 | 你问 agent 的话 | 图上会出现什么 |
|---|---|---|
| 🧭 项目复盘 | 「把这次讨论画成上下文架构图」 | 目标、走过的弯路、最终拍板、待办 |
| 🧩 技术选型 | 「把我们比较过的方案画成图,标出为什么选 B」 | 候选方案、淘汰理由、决策、风险 |
| 📝 PR 说明 | 「把这次改动的来龙去脉画成图,放进 docs/」 |
动机、改动点、影响面、遗留问题 |
| 📋 需求拆解 | 「把这段需求整理成信息架构图」 | 目标、约束、拆分出的动作、未定项 |
| 🔥 事故复盘 | 「把这次故障的上下文画成图」 | 现象、根因、处置、后续预防 |
同一个工具也能反过来用:图是先写给你自己看的 —— 把模糊的讨论压成 8–20 个节点,哪块没想清楚会立刻暴露(那些节点只能写成 question)。
快速开始
1. 安装
环境要求:DeepSeek Harness(带 dsh plugin 命令)+ Node.js ≥ 20 + pnpm 在 DSH 进程的 PATH 上。
# 没装 pnpm 的话先装(DSH 的插件安装由 pnpm 执行)
npm install -g pnpm
# 安装插件
dsh plugin --profile web add dsh-context-map
其它装法:
| 方式 | 命令 |
|---|---|
| 从 GitHub 指定 tag | dsh plugin --profile web add github:gavinff1990/dsh-context-map#v0.1.0 |
| 从 git 仓库 | dsh plugin --profile web add git+https://github.com/gavinff1990/dsh-context-map.git |
| 本地源码(开发用) | dsh plugin --profile web add /absolute/path/to/dsh-context-map |
装完确认挂载点进了合成配置:
dsh --profile web --dump-config | grep -A1 context-map
# - id: context-map
# name: dsh-context-map
2. 说一句话
在会话里直接说(中英文都行):
把这次讨论画成上下文架构图。 给我一张这个项目的信息架构图,标出风险和还没定的事。
agent 会调用 context_map,把对话整理成节点并渲染。想指定位置就说"放到 docs/ 下"。
3. 打开产物
.dsh-context-map/context-map.svg # 贴文档
.dsh-context-map/context-map.html # 浏览器打开,可缩放/搜索/筛选
.dsh-context-map/context-map.md # 进 PR / wiki
建议让 agent 传绝对路径的 outDir:插件进程的工作目录不一定等于会话工作区,绝对路径最稳。
示例
仓库里三份真实产物,都由 examples/spec.json 生成:
| 文件 | 大小 | 里面有什么 |
|---|---|---|
context-map-example.svg |
23.9 KB | 单文件矢量图;明暗两套主题内联,prefers-color-scheme 直接生效 |
context-map-example.html |
39.4 KB | 同一张图 + 工具栏 + 大纲栏;离线可用,无 CDN |
context-map-example.md |
5.6 KB | Mermaid flowchart + 嵌套大纲 + 类型统计 + 节点清单 |
能力
| 入口 | 适合 | 你得到什么 |
|---|---|---|
| 🖼️ SVG | 贴进文档、README、幻灯片 | 矢量不失真,深浅色自动适配 |
| 🖱️ HTML | 自己看、发给别人看 | 缩放、适配、搜索、按类型筛选、大纲跳转、A3 打印 |
| 🧾 Markdown | 进 PR、进 wiki、让 review 看见结构 | Mermaid 源码 + 大纲 + 清单,diff 可审阅 |
| ⌨️ CLI | 进 CI、批量重建、手工校样 | 同一套渲染器,--json 还能吐布局几何 |
🧭 分层布局,不是雷达图
深度就是一列:列宽取该层最宽卡片,父节点对齐子节点子树带,同级按序堆叠且不重叠。跨分支关联(如「风险 X 阻塞动作 Y」)走虚线,绕右缘出画面,不穿过卡片。算法与不变量写在 docs/ARCHITECTURE.md。
🎨 语义着色,跨图一致
八种节点各有固定色与色条:目标蓝、背景灰、决策紫、动作绿、产物琥珀、风险玫红、待确认青、备注石板灰。状态(done / active / planned / blocked)画成节点左侧的小圆点。
🖱️ HTML 里能做什么
/聚焦搜索,+/-缩放,0还原,f适配,Esc清空- 点图例里的某一类,隐藏/显示该类节点
- 点左侧大纲的任意一行,跳到对应节点并高亮
- 右上角
◐在 auto / light / dark 之间切换;⎙直接打印
🔒 零网络、零依赖、零配置
没有 fetch、没有 socket、没有遥测,不 spawn 子进程,不 eval。它只写 outDir 下的三个文件,并显式拒绝文件系统根目录、~/.dsh、~/.ssh、~/.aws 等位置。
参数
工具参数
| 参数 | 必填 | 说明 |
|---|---|---|
title |
✅ | 图标题,一行 |
nodes |
✅ | 节点数组,上限 300 |
subtitle |
副标题:这张图回答的问题 | |
links |
树表达不了的跨分支依赖,上限 150 | |
outDir |
输出目录,默认 .dsh-context-map;推荐绝对路径 |
|
slug |
文件基名,默认由标题推导为 [a-z0-9-] |
|
formats |
svg / html / md 子集,默认全出 |
|
theme |
light / dark / auto(默认跟随系统) |
|
locale |
zh / en,默认 zh |
节点字段
| 字段 | 必填 | 说明 |
|---|---|---|
label |
✅ | 短标签,建议 ≤ 40 字,一行能扫完 |
kind |
见下表,默认 context |
|
detail |
一句补充:理由、证据、确切路径 | |
parent |
父节点 id;不填即为根(多根会自动加合成根) | |
id |
稳定 id,供 parent / links 引用;默认 n1…nN |
|
status |
done / active / planned / blocked |
八种节点类型
| kind | 含义 | 典型内容 |
|---|---|---|
goal |
目标 | 用户到底要什么 |
context |
背景 / 约束 | 环境限制、已确认的事实、外部规则 |
decision |
已做的决策 | 选型、取舍、拍板结论 |
action |
动作 | 正在做或要做的事 |
artifact |
产物 | 文件、仓库、文档、图表 |
risk |
风险 | 会翻车的地方 |
question |
待确认 | 还没定的问题 |
note |
备注 | 其他值得留下的信息 |
命令行
同一套渲染器也能脱网跑,方便进 CI 或手工校样:
node bin/cli.js examples/spec.json --out docs # 写三份文件
node bin/cli.js examples/spec.json --json # 只看布局几何(调试)
node bin/cli.js examples/spec.json --stdout > m.svg # SVG 到标准输出
echo '{"title":"t","nodes":[{"label":"root"}]}' | node bin/cli.js - # 从标准输入读
--help 有完整参数表(--formats / --theme / --locale / --slug / --quiet)。
安装详解与排错
桌面版怎么装
Desktop profile 由 Electron 应用独占管理,dsh plugin --profile desktop add 会被拒绝。请在应用内的插件市场安装;市场尚未收录时,把下面这行加到 ~/.dsh/profiles/desktop/cordis.patch.yml 的数组里,并确保该包已在 profile 的 node_modules 中:
- id: context-map
name: dsh-context-map
pnpm: command not found
DSH 的插件安装由 pnpm 执行,而它要求 pnpm 在 DSH 进程的 PATH 上(不是只在某个终端里)。
npm install -g pnpm
pnpm --version # 确认能找到
装完重启 DSH,让新 PATH 生效。
装完看不到 context_map 工具
dsh --profile web --dump-config | grep -A1 context-map—— 没有这一行说明包没装上;- 有这一行但工具没出现:确认 profile 里
@deepseek-ai/dsh-tools正常加载(inject: ['tools']会等它); - 重启 DSH 会话(工具列表在会话开始时就固定了)。
更新与卸载
dsh plugin --profile web add dsh-context-map@latest # 更新
dsh plugin --profile web remove dsh-context-map # 卸载
隐私与数据
| 项目 | 情况 |
|---|---|
| 网络请求 | 无。没有 fetch / socket / 遥测 |
| 会话日志 | 不读。不碰 ~/.dsh/sessions,只处理本次调用传入的节点 |
| 写入范围 | 仅 outDir 下 <slug>.svg / <slug>.html / <slug>.md 三个文件 |
| 进程 / 代码执行 | 不 spawn、不 eval、不加载远程代码、无安装钩子 |
| 密钥 | 不需要任何 API key |
这些约束写在 lib/files.js 的 resolveOutDir 里,并由测试守着。
兼容性
- DSH
>=0.2.0-rc.1 <0.3.0-0。在 0.2.1-rc.2 上验证过:临时 profile 跑--dump-config能合成出context-map这一行。 - Node
>=20(用到node:test、String.replaceAll)。 - macOS / Linux / Windows。
和其它工具的区别
市面上的「画图」工具很多,输入不同:
| 工具类型 | 输入 | 产出 | 适合 |
|---|---|---|---|
| 思维导图(XMind / 幕布) | 你手打的提纲 | 放射状导图 | 头脑风暴;不擅长表达层级与跨支依赖 |
| 从仓库生成架构图 | 代码仓库 | 系统 / 模块结构 | 读懂一个 codebase;不记录「为什么这么定」 |
| 通用 diagram 工具(Mermaid / draw.io) | 你写的 DSL 或手工摆放 | 图 | 精确控制;但排版和配色要自己调 |
| dsh-context-map | 一段对话 | 分层信息架构图 + 三种格式 | 复盘、交接、PR 说明;不读代码,不调模型 |
它不替代前三种,补的是它们的空白:代码里没有的东西 —— 决策、风险、待确认 —— 只存在于对话里。
更新
0.1.0 — 2026-11-02
首个版本:context_map 工具、确定性树布局、SVG / 交互式 HTML / Mermaid 三格式、CLI、55 个测试。完整记录见 CHANGELOG。
限制
- 一张图 = 一棵树。多个根会自动加一个合成根。
- 单图上限 300 节点 / 150 条跨分支关联。节点多时图会很高,先分组(3–5 个分支,每支 2–6 个子节点)—— 工具描述里就是这么要求模型的。
- 它不决定内容,只负责画对;要点该不该进图由 agent 判断。
- 不是设计工具:没有拖拽、没有手工调位、不导出 PNG/PDF(SVG 与浏览器打印够用)。
常见问题
为什么不让插件自己读聊天记录?
DSH 的会话是 session.v4.jsonl.zstd——多帧拼接的 zstd 内部格式,解析它会在版本升级时碎掉。而且模型本来就在上下文里,让它蒸馏比让插件猜更准。插件只做渲染,才换来「无网络、无密钥、可复现」。
图太宽/太高怎么办? 先分组。单层十几个兄弟节点会拉出一条很长的竖列;3–5 个分支、每支 2–6 个叶子读起来最舒服。已生成的图可以在 HTML 里缩放、搜索、按类型筛。
能改配色吗?
改 lib/theme.js 的 KIND_STYLES:每个 kind 一个 accent + 一个 tint,明暗两套一起生效。
每次生成的图会不一样吗? 坐标完全确定,时间戳只到日。同一天重建是字节一致的;跨天只有那一行日期会变。
能画代码结构吗? 不能,也不打算做:那是「从仓库生成架构图」这类工具的事。这里的输入是对话,产出是对话里那些不进代码的东西。
本地开发
npm test # 55 个用例 / 6 个套件
npm run demo # 用 examples/spec.json 生成到 examples/out
npm run check # node --check 入口
测试为什么不用 node --test:它会给每个文件 fork 子进程,在被限制的沙箱里会 EPERM。scripts/test.mjs 把 6 个套件 import 进同一进程,语义一致、退出码一样。
lib/ spec → layout → svg → html / markdown → files
bin/ CLI(与工具共用同一套渲染)
test/ 规格校验、布局不变量、渲染与转义、插件注册、打包元数据、schema 契约
docs/ 示例产物 + 架构说明
examples/ 可以直接改的输入样例
其中 test/package.test.js 把上架契约变成了断言:包名 slug 合法、dsh.bundle.patch 指向真实文件、LICENSE 是 SPDX 标识、README 含安装命令、运行时依赖为空。改坏了测试先红。
反馈
- 问题与建议:Issues
- 更新记录:CHANGELOG · 版本:Releases
- 参与开发:CONTRIBUTING · 安全策略:SECURITY
No comments yet. Be the first to write one.