SmileBuild/dsh-planchart

dsh-planchart

中文

一个 DeepSeek Harness（dsh）插件，为智能体提供用于项目规划的展示界面。模型通过一次工具调用传入整个计划；浏览器会在两个位置渲染它：

- 步骤 —— 停靠在框架右边缘的面板，包含阶段、状态标记和每步详情；
- 框架 —— Chat 和 Trajectory 旁边的 "PlanChart" 标签页，其中包含自动排版的架构图，可下载为 SVG 或 PNG。

再次与智能体对话会同时更新两者：每次 planchart_set 调用都会替换整张图表，因此“将第 3 步标记为完成”或“添加缓存层”只是普通的后续消息。

PlanChart 标签页：中央是框架图，右侧是步骤面板

使用 PNG 按钮导出的框架图

安装

dsh plugin --profile web add ./dsh-PlanChart

然后重启该 profile（dsh web）并强制重新加载浏览器标签页。该插件声明了 dsh.bundle.patch，因此安装程序会自动将其加入 profile 的 bundle 栈；其浏览器端部分通过 dsh.client 被发现，并在 /plugins/dsh-planchart/client.js 提供。

重新加载不是可选项。客户端插件表以 window.__DSH_BOOT__ 的形式到达，它是在页面加载时注入到 index.html 中的。如果你重启时标签页已经打开，它会保留旧清单，并且永远不会获取新的 bundle —— 工具会运行，图表会被存储，但浏览器什么都不显示。这对每个 dsh 客户端插件都成立，不只是这个插件。

要移除它：dsh plugin --profile web remove dsh-planchart。

工具

| 工具 | 作用 |
|---|---|
| planchart_set | 发布整张图表：title、可选的 summary、steps[] 以及 framework 图。会整体替换之前的图表。 |
| planchart_get | 以文本形式读回当前显示的图表 —— 用于修改模型上下文中已不存在的图表。 |

还有一个 /planchart 斜杠命令，用于打印当前图表。

步骤结构

{ "id": "…",            // 可选；省略时根据标题派生
"title": "Build recipe CRUD",
"status": "pending",  // pending | active | done | blocked
"detail": "create, edit, publish",   // 可选
"phase": "Build" }                   // 可选；连续的步骤会归入其下

框架结构

{ "direction": "TB",                       // TB（默认）或 LR
"groups": [{ "id": "…", "label": "Client" }],
"nodes":  [{ "id": "…", "label": "Web app", "kind": "entry",
"note": "React + Vite", "group": "client" }],
"edges":  [{ "from": "web-app", "to": "api-gateway",
"label": "HTTPS", "dashed": false }] }

kind 决定方框如何绘制，而不是它意味着什么。各处都可以省略 id —— 会根据标签派生一个（CJK 标签会保留其字符），随后边会引用它。

视觉语言
该图是单色结构，恰好只有一处强调色，因此九宫格图不会变成九个相互争抢的填充：

| kind | 绘制为 | 原因 |
|---|---|---|
| core | 着色填充、强调色边框 | 画布上唯一的颜色——承担主要工作的部分，也是视线应首先落到的位置 |
| entry、output | 实线边框、无填充 | 系统的边界 |
| store | 浅淡填充、极细线 | 承载某些内容 |
| external | 虚线极细线、弱化文字 | 不属于你 |
| default | 极细线 | 配角 |

带状区域为 2% 着色且无轮廓，边标签置于无边框的底板上，并在其穿过的线上留出一个缺口，而步骤面板将其唯一的强调色用在单个 active 步骤上。已完成的步骤保留其标题并丢弃其细节：对于一眼扫读的面板而言，已经完成的工作的说明是最先值得移除的内容。

布局

两种模式，由数据选择：

- 带状区域——当每个节点都指明了一个已声明的分组时，这些分组成为行（或在 LR 下成为列），每个分组绘制为带标签的带状区域。这是对分层架构的自然解读。
- 分层 DAG——否则由边决定层级（最长路径），并通过一次重心扫描排序。

随后两者都运行相同的优先级放置，使子节点位于其父节点之下，而不是位于其所在行的中间之下，并且同一层级中兄弟节点之间的边会从下方预留的通道中穿过，而不是横切方框。

图表如何到达浏览器

图表搭载于 tool/result.meta——文档化的工具私有、可重放的载荷通道——而 planchart 会话投影将其重新折叠出来：

planchart_set.execute → output.presentationMeta → tool/result.meta (durable log)
↓
projection planchart (apply/view)
↓
session/projection push frame → useProjection

为什么不用它自己的会话事件。 仓库外的事件类型不存在于此构建的 KNOWN_SESSION_EVENT_TYPES 中，而 Session.append 没有提供将事件标记为 ignorable 的方式。因此，写入 planchart/write 会使每个使用该插件的会话在重启后永久无法加载——持久化读取路径会拒绝包含未知、不可忽略类型的日志。在普通的 tool/result 上搭载 meta 完全不增加任何词汇，并且重放结果完全相同。

值得了解的后果：

- 图表在重启、恢复和分叉后依然存在，因为它派生自日志。
- 与待办列表不同，它不会在下一轮被清除：已发布的图表是项目的常驻形态。
- presentationMeta 仅为顶层调用计算，因此从子代理内部发布的图表不会到达面板。

两半

- 宿主（lib/index.js）——两个工具、投影单元、系统
在提示词部分，/planchart 命令。可选接缝（sessionProjections、
systemPrompt、commands）通过 ctx.inject 获取，因此即使没有它们，无头
组合仍然能获得这些工具。
- 浏览器（lib/client.js）—— 以客户端模块加载器所期望的惰性 CJS bundle 形式
手工编写（window.__ModuleLoader__.load({ id, factory })），
因此没有构建步骤。它注册到 conversation.view（标签页）
和 shell.overlay（步骤面板）。

该图使用表现属性和字面颜色绘制——没有 CSS
类，没有 var(--dsw-*)——因此序列化实时的  会生成一个文件，下载后可独立渲染。
它通过监听  上的 data-ds-dark-theme 来跟随应用的浅色/深色主题。

为什么步骤面板会浮动

ui-layout 提供四个根席位：sidebar、conversation、details 和
shell.overlay。右侧的 details 列是一个单一槽位，已被 ui-conversation 的 DetailsPanel 占用，注册到那里会替换它，
并连带夺走工具详情席位。shell.overlay 是文档中记载的
用于框架级界面的附加席位，因此步骤面板位于那里：停靠在
右侧，可折叠为边缘标签页，并记住在 localStorage 中。由于是
根作用域，它不会获得 useProjection，因此它通过
ctx.sessions.binding(id).session.projections.faceOf('planchart') 读取相同的按 key 可观察对象。

配置

- insert:
- id: planchart
name: dsh-planchart
config:
promptSection: true   # false 保留工具但停止宣传它们

测试

npm test                     # 宿主部分：注册、持久往返、验证
node test/render-preview.mjs # 使用真实 React 渲染浏览器部分 → test/preview.{html,svg}

render-preview.mjs 通过客户端模块加载器的桩加载 lib/client.js，
并对两个席位进行服务端渲染，断言每个节点和边都被绘制，
且没有任何框超出画布。

限制

- 图表按会话划分；没有跨会话库。
- 步骤面板浮动在对话之上，而不是缩小对话（见
上文）；当它挡路时，将其折叠到边缘标签页。
- 图表布局是确定性的，但不是最优的——繁重的图（数十个
节点且有许多跨层级边）仍会交叉。
- 上限：60 个步骤、80 个节点、200 条边、12 个组。超大输入会被
大声拒绝，而不是截断。

中文说明

dsh-planchart 给 agent 增加一块项目规划的展示面板。模型用一个工具发送完整的
规划，浏览器分两处渲染：

- 步骤 —— 停靠在窗口右侧的面板，带阶段分组、状态标记和每步说明；
- 框架 —— Chat / Trajectory 旁边的 "PlanChart" 标签页，自动排版的架构图，可以
下载 SVG 或 PNG。

继续对话即可修改：每次 planchart_set 都整体替换当前的图，所以"把第三步标记完成"
或"加一层缓存"就是一句普通的后续消息。

安装

dsh plugin --profile web add ./dsh-PlanChart

然后重启 profile（dsh web），并且硬刷新浏览器页面。插件声明了
dsh.bundle.patch，安装器会自动把它加入 profile 的 bundle 列表；浏览器半边通过
dsh.client 被发现，served 在 /plugins/dsh-planchart/client.js。
刷新这一步不能省。客户端插件表是 window.__DSH_BOOT__，在页面加载时注入
index.html。重启前就开着的标签页会一直用旧的清单，永远不会去取新 bundle ——
结果是工具照常执行、图也存下来了，但界面上什么都不显示。这对所有 dsh 客户端
插件都成立，不只是这个插件。

卸载：dsh plugin --profile web remove dsh-planchart。

工具

- planchart_set —— 发布整张图：title、可选 summary、steps[]、framework 图。
- planchart_get —— 把当前显示的图读回成文本，供模型在上下文丢失后再修改。
- /planchart —— 斜杠命令，打印当前的图。

节点和步骤的 id 都可以省略，会从标题/标签推导（中文标签保留原字符），边再引用它。

视觉语言

整张图是单色结构 + 一处强调色，避免九个方框变成九种互相争抢的填充：core 是画布上
唯一有颜色的东西（做实事的部分，视线首先落在这里）；entry/output 用较实的描边表示
系统边界；store 是极淡的填充；external 用虚线描边加灰字，表示“不属于你”；
其余是发丝线。分带只有 2% 的色调、没有描边，边上的文字压在一块无边框的底板上，把它
穿过的那条线截断。

右侧面板同理：唯一的强调色给“进行中”那一步。已完成的步骤保留标题、去掉说明——一个
用来扫一眼的面板里，最该先删掉的就是已完成工作的解释。

数据怎么到浏览器

图挂在 tool/result.meta（工具私有、可重放的载荷通道）上，由 planchart
session projection 折叠出来，再通过 session/projection 推给浏览器。

为什么不自定义 session 事件类型：本次构建的 KNOWN_SESSION_EVENT_TYPES 不包含
仓库外的事件类型，而 Session.append 没有提供把事件标记为 ignorable 的入口。写入
planchart/write 会让用过该插件的每个 session 在重启后永久无法加载——持久化读取
路径会拒绝含有未知且非 ignorable 类型的日志。挂在普通 tool/result 的 meta 上不
新增任何事件词汇，重放结果完全一致。

因此：图能跨重启、resume 和 fork 保留；与 todo 列表不同，它不会在下一轮被清空；
presentationMeta 只对顶层调用计算，所以子 agent 里发布的图不会出现在面板上。

已知限制

- 图按 session 保存，没有跨 session 的图库。
- 步骤面板浮在对话之上，不会挤压中间栏；挡路时可以折叠成右侧边缘的小标签。
- 排版是确定性的但不是最优的，节点很多且跨层边很密时仍会有交叉。
- 上限：60 步、80 节点、200 条边、12 个分组，超出会直接报错而不是截断。