dsh-context-map

dsh plugin --profile web add dsh-context-map

🗺️ dsh-context-map

中文 · [English](README.en.md)

<p align="center">

<b>把一段对话的上下文，画成一张能贴进文档的信息架构图。</b><br>

_{目标 · 背景 · 决策 · 动作 · 产物 · 风险 · 待确认 —— 分层成图，一次输出 SVG / 交互式 HTML / Mermaid。}

</p>

<p align="center">

<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.3.0-0891b2?style=flat-square" alt="Version 0.3.0"></a>

<a href="https://www.npmjs.com/package/dsh-context-map"><img src="https://img.shields.io/npm/v/dsh-context-map?style=flat-square&color=CB3837" alt="npm"></a>

<a href="https://www.dsh.so/artifact/dsh-context-map-2/"><img src="https://cdn.dsh.so/badge/install/dsh-context-map-2@0.2.1-rc.5.svg" alt="dsh.so install: runtime verified (L5) on dsh 0.2.1-rc.5"></a>

<a href="https://www.dsh.so/artifact/dsh-context-map-2/"><img src="https://cdn.dsh.so/badge/dsh-context-map-2.svg" alt="dsh.so risk: low"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-16a34a?style=flat-square" alt="License"></a>

<a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square" alt="Node"></a>

<a href="package.json"><img src="https://img.shields.io/badge/runtime%20deps-0-blue?style=flat-square" alt="Zero dependencies"></a>

<a href="package.json"><img src="https://img.shields.io/badge/dsh-%3E%3D0.2.0--rc.1-4D6BFE?style=flat-square" alt="DSH"></a>

<a href="https://github.com/gavinff1990/dsh-context-map/stargazers"><img src="https://img.shields.io/github/stars/gavinff1990/dsh-context-map?style=flat-square&color=4D6BFE" alt="Stars"></a>

</p>

<p align="center">

<a href="#什么场景用">场景</a> ·

<a href="#快速开始">快速开始</a> ·

<a href="#示例">示例</a> ·

<a href="#能力">能力</a> ·

<a href="#参数">参数</a> ·

<a href="#安装详解与排错">安装排错</a> ·

<a href="#和其它工具的区别">区别</a> ·

<a href="#常见问题">常见问题</a>

</p>

<p align="center">

<img src="docs/context-map-example.svg" alt="一张由 dsh-context-map 生成的示例图：左侧是目标，右侧分为渠道调研、产品设计、交付计划、风险与待办四个分支" width="900">

</p>

<p align="center">

_{这张图由插件自己生成：<code>examples/spec.json</code> → <code>docs/context-map-example.svg</code>（23.9 KB），没有用任何设计工具。}

</p>

---

为 DeepSeek Harness 补齐「把对话变成结构」这一步。

一次长会话结束时，真正值钱的东西散落在上下文里：为什么改了方向、哪个文件才是产物、还有哪些没定。翻聊天记录找不回来，截图又不带结构。

dsh-context-map 给 agent 一个工具 context_map：agent 把对话蒸馏成节点，插件负责校验 → 布局 → 渲染。你得到的是左→右推进的分层结构，不是放射状的思维导图 —— 父子关系一眼可读。

• 零运行时依赖，不带 API key，不联网，不读会话日志
• 确定性布局：同一份输入永远得到同一张图，同一天重建字节一致，可以提交进 git
• 四种产物：矢量 SVG、可缩放可搜索的 HTML、可进 PR 的 Mermaid Markdown，以及一份可再渲染、可 diff 的 JSON

懒得自己装？ 把这句话发给你的 agent：

```text

帮我安装 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
.dsh-context-map/context-map.json    # 数据层，下次 update 用它

建议让 agent 传绝对路径的 outDir：插件进程的工作目录不一定等于会话工作区，绝对路径最稳。

示例

仓库里三份真实产物，都由 examples/spec.json 生成：

文件 · 大小 · 里面有什么

[context-map-example.svg](docs/context-map-example.svg) · 23.9 KB · 单文件矢量图；明暗两套主题内联，prefers-color-scheme 直接生效

[context-map-example.html](docs/context-map-example.html) · 39.4 KB · 同一张图 + 工具栏 + 大纲栏；离线可用，无 CDN

[context-map-example.md](docs/context-map-example.md) · 5.6 KB · Mermaid flowchart + 嵌套大纲 + 类型统计 + 节点清单

context-map-example.json · ~4 KB · 图的数据层：节点与关联的原始结构、修订号与历史；下次 update 就读它

能力

入口 · 适合 · 你得到什么

🖼️ SVG · 贴进文档、README、幻灯片 · 矢量不失真，深浅色自动适配

🖱️ HTML · 自己看、发给别人看 · 缩放、适配、搜索、按类型筛选、大纲跳转、A3 打印

🧾 Markdown · 进 PR、进 wiki、让 review 看见结构 · Mermaid 源码 + 大纲 + 清单，diff 可审阅

🗃️ JSON · 下次还要改这张图 · 可再渲染的 sidecar：修订号、历史、原始节点

⌨️ CLI · 进 CI、批量重建、手工校样 · 同一套渲染器，--json 还能吐布局几何

🔎 session_facts · 想让节点引用真实路径 · 本会话写/读过的文件、跑过的命令、失败记录

🧭 分层布局，不是雷达图

深度就是一列：列宽取该层最宽卡片，父节点对齐子节点子树带，同级按序堆叠且不重叠。跨分支关联（如「风险 X 阻塞动作 Y」）走虚线，绕右缘出画面，不穿过卡片。算法与不变量写在 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

🎨 语义着色，跨图一致

八种节点各有固定色与色条：目标蓝、背景灰、决策紫、动作绿、产物琥珀、风险玫红、待确认青、备注石板灰。状态（done / active / planned / blocked）画成节点左侧的小圆点。

🖱️ HTML 里能做什么

• / 聚焦搜索，+ / - 缩放，0 还原，f 适配，Esc 清空
• 点图例里的某一类，隐藏/显示该类节点
• 点左侧大纲的任意一行，跳到对应节点并高亮
• 右上角 ◐ 在 auto / light / dark 之间切换；⎙ 直接打印

🔎 会话事实：让节点有据可查

模型凭记忆写节点，容易把"好像改过"写成"改过"。插件同时监听本会话的 tools/result，记录真实发生的事：哪些文件被写、哪些被读、跑过什么命令、哪些调用失败 —— 只存在进程内存里，不读会话日志、不落盘。

需要引用真实路径时，先调 session_facts，再拿它的 path 去写 artifact / action 节点：

session_facts()                       → 本会话的文件与命令清单
session_facts({ scope: "files" })     → 只看文件
session_facts({ clear: true })        → 读完后清空，开启新阶段

🔁 修订：图是可维护的资产

第一次画完会落一个 .json。下次要改，不必重新口述整张图 —— 把它的路径传给 update：

context_map({ tit

…(truncated)