语义卡片绘图 QinLuza/dsh-aisketch

dsh-aisketch

给 DSH（DeepSeek Harness）加一条卡片通道：模型只给结构，客户端负责作图。

English TL;DR — dsh-aisketch 给 DSH 加了两个扩展点：show_card（原生表格 / SVG 流程图 / 手绘 draw / 语义教学图）和 sketch_function（六种交互绘图模式）。模型只提供结构，几何由确定性引擎负责。MIT 协议，零 base 改动。

| 工具 | 模型给什么 | 用户看到什么 |
| show_card | kind + 结构化 payload | 会话里的原生卡片：表格、SVG 流程图、手绘插画、教学示意图 |
| sketch_function | 一条函数表达式 + 参数范围（实测 4–45 token） | 可交互函数图像：六种模式、参数滑块、追踪读数 |

零 base 改动：全部走官方扩展点（tool 注册、tool.call.toolview、conversation.chat.node、conversation.chat.turnTail），没有一行改动 @deepseek-ai/dsh-。

手绘插画卡

一、它补的是哪一块

模型想把一件事讲清楚时，手上常常只有文字。于是它写 Markdown 表格、画 ASCII 图，或者更糟——生成一段 HTML/SVG 让你渲染。前两者难看且难读，后者是在执行模型生成的代码，还不可回放。

dsh-aisketch 换了一条路：模型只交结构，几何由确定性引擎算。

// show_card：模型只给节点和连线，位置/换行/箭头锚点由客户端算 { "kind": "flowchart",
"payload": {
"nodes": [
{ "id": "check", "label": "n 是偶数？", "shape": "decision" }, { "id": "even", "label": "输出 n/2", "shape": "process" } ],
"edges": [{ "from": "check", "to": "even", "label": "是" }]
}
}

同一份 payload 必然画出同一张图；回放一个旧会话，卡片一模一样，不需要 Host 再参与。

与 DSH 本体的关系

| | DSH 本体已有 | 本插件补的 |
| 卡片怎么来 | 每个内置工具自己的卡片模型（read / grep / diff / terminal / web / image …），渲染器写死在客户端 | 一条通用通道：模型自选内容，kind 决定用哪个渲染器；加一种卡片 = 注册一个组件 |
| 交付物 | present：把已有文件声明为最终交付物，只记路径不搬内容 | 把结构化内容本身交付到会话里，不需要先落盘 |
| 图表/流程图 | 官方工具目录里没有通用绘图、图表、流程图工具 | 表格、流程图、手绘、教学示意图、六种函数图 |
| 可见性 | 工具调用属于「回合过程」，会被工作步骤展示模式折叠 | 卡片同时挂 turnTail 产出物槽位（详见「已知限制」） |

二、现在能画什么

1. show_card → table

columns + rows，1..12 列、≤500 行；表头吸顶、数字右对齐等宽、null 显示 --、超宽横向滚动。

物理量表

2. show_card → flowchart

1..40 节点、≤80 连线，shape ∈ terminal / process / decision。分层布局、分支标签、回边绕右侧 gutter、共享端点自动扇开。点卡片右上角可放大显示。

奇偶判断流程图

3. show_card → draw

手绘卡：模型只写中心线、形状、文字、胶带或像素网格；钢笔出锋、书法笔角度、荧光笔半透明、铅笔颗粒、手绘抖动全部由引擎算。支持 draft: true 私有草稿与最终稿，用户只看到成品。

山湖小屋手绘插画

0.3 起：光与墨也是字段

| 字段 | 用在 | 解决什么 |
| background | 载荷级 | 画布底色（夜色、牛皮纸），不必拿一个整幅矩形元素伪造 |
| strokeOpacity | path / shape | 同一支笔的浓淡：远处更淡、压住的辅助线；不用换浅色，也不改笔型 |
| dash | path | 自由曲线画虚线（被挡的棱、轨迹）；此前只有 shape 有 |
| fill 渐变 | path / shape | linear / radial + 2..8 个色标（CSS 角度、from/to 简写）；一条字段替代 8–12 条色带 |
| blend | path / shape / pixels | normal / multiply / screen / overlay / soft-light：光叠在物体上 |
| blur | path / shape | 光柱、光晕、雾、景深；blur 是可见扩散半径，两端都按 σ = blur/2 计算 |

渐变和模糊都按元素自身的包围盒解析几何，模型不给坐标，所以「同一份载荷必然同一张图」对它们同样成立；光栅预览逐像素采样，模型看到的预览和卡片一致。

渲染是一次性的：卡片先离屏栅格化成位图再上屏，滚动与放大不再重栅格化。同一张 340 条 path 的卡实测：首次滚动从中位 41ms / 单帧 407ms 回到 17ms，放大从 539ms 卡顿降到约 97ms。

4. show_card → figure

教学示意图不塞进 draw：前者怕错，后者怕平庸。figure 只接受模板与语义参数，坐标、角度、锚点、标签位置全部由渲染器构造。

| 模板 | 模型填什么 | 渲染器保证什么 |
| incline_force | 角度、质量、摩擦系数、可选 g/分量/数值 | 物块置于斜面；G 竖直、N 垂直斜面、f 沿斜面向上；力的大小由 m/g/θ/μ 计算 |
| connected_bodies | 桌面质量、悬挂质量、摩擦系数、可选 g/数值 | 桌面块经定滑轮连悬挂块；T/N/G/f 锚在对应块面上；T 不伪造数值 |
| orbital_diagram | 元素符号（H–Zn） | 由参考表推导电子排布与各亚层电子数；按洪特规则画轨道框、↑↓ 与电子排布式 |
| atom_shell | 元素符号（H–Ca） | Z 和电子层数从内置参考表推导；电子均匀落位、核标 +Z、K/L/M… 图例 |

5. sketch_function → 六种模式

| 模式 | 画什么 |
| plain | 单曲线，y 轴按表达式自适应 |
| compare | 多曲线对比（共享窗口，各自独立采样） |
| tangent | 指定点的切线（数值微分） |
| riemann | n 个矩形逼近定积分 |
| taylor | 泰勒展开到 n 阶（展开点可选） |
| data | 折线 / 柱状 / 散点 / 饼图 |

带 params 时出参数滑块；拖拽期间 y 窗口冻结，另有追踪读数（悬停、点按钉住、键盘步进）。交互态全部在组件本地，不写回 spec、不发 Host 调用。

三、三条设计边界

1. 不执行模型生成的代码。 没有 eval、没有 new Function、不把生成的 HTML/SVG 字符串塞进 DOM。draw 的路径串只经过自己的迷你语法解析器；未知命令、空路径、指数记法一律拒绝，错误带 element N: 前缀，模型可以自己改。
2. 几何是载荷的纯函数。 流程图分层、换行、箭头锚点、扇开偏移，函数图采样、视窗、数值微分/积分，全部由确定性引擎算。同一 spec 必然同一张图，因此回放等价，也能在 vitest 里断言，不需要 DOM。
3. 校验在 Host 就做。 列数/行数、节点数/连线数、id 唯一、shape 取值、每条连线必须指向已声明节点；不做「画出来少一条边」这种事。报错让模型自己改。

四、安装

方式一：link 安装（推荐，当前已验证）

git clone https://github.com/QinLuza/dsh-aisketch.git
cd dsh-aisketch

构建两个浏览器半边（客户端模块系统读 lib/client.js 原样下发）bash
pnpm install
pnpm build:client

装进 profile（官方命令，实为 pnpm 包装器）

dsh plugin --profile <profile> add link:<repo>/packages/sketch-bundle
dsh --profile <profile> --dump-config # 应见 4 行 insert

桌面端（Electron）的 desktop profile 被应用独占，命令行装不进去；请用应用自己的插件面板，安装来源填 packages/sketch-bundle 的绝对路径。

方式二：从 Git 仓库安装

在插件面板里填本仓库地址，或使用插件市场支持的 Git 安装语法；包目录是 packages/sketch-bundle。本仓库没有发布 npm 包，@aisketch/ 只是公开作用域名，不依赖 npm 在线安装。

兼容性

packages/sketch-bundle/package.json 已声明： json { "engines": { "dsh": ">=0.1.7-rc.2 <0.2.0" } }

当前在 0.1.7-rc.2 的桌面端与插件系统上实测。dsh 升级到 0.2 之前，先看这个范围是否仍然匹配；不匹配时安装器会直接拒绝，而不是装作能跑。

改完 Host 半（cards-core / cards-tool / sketch-core / sketch-tool）必须重启应用；改完 client 半必须重新构建 lib/client.js 并重启。 运行中重建 client 产物会让整批插件加载失败。

五、架构

七个包，全部 @aisketch/*，base 仓一行未改：

| 包 | 职责 |
| packages/cards-core | 卡片契约内核：版本化 CardSpec、限额校验、table/flowchart/draw/figure 载荷解析、draw 几何引擎与自检。零依赖 |
| packages/cards-tool | Host 工具 show_card：schema、拒绝原因、摘要、draw 离屏预览与回读 |
| packages/client-ui-cards | 浏览器半边：card 聊天节点 + turnTail 产出物面；CardView 按 spec.kind 经 registry 派发 |
| packages/sketch-core | 纯函数内核：自写 Pratt 表达式解析器、参数摘要、几何采样。零依赖 |
| packages/sketch-tool | Host 工具 sketch_function：schema、校验、摘要、presentationMeta |
| packages/client-ui-sketch | 浏览器半边：tool.call.toolview 过程行 + turnTail 产出物卡，同一 SketchFigure |
| packages/sketch-bundle | 装配包：dsh.bundle.patch → cordis.patch.yml（4 行 insert） |

两张脸

| 面 | 槽位 | 何时可见 |
| 过程行 | tool.call.toolview（key = 工具名） | 回合进行中、折叠区打开时实时出图 |
| 产出物 | conversation.chat.turnTail | 回合结束后常驻；数据源是持久化事件，回放等价 |

只挂 toolview 的卡片会在回合结束后被「回合过程折叠」藏掉；turnTail 是 base 留给产出物的槽位。两条通道都同时挂两张脸。

六、质量与验收

- 539 例单元/集成测试（cards-core 194 / client-ui-cards 170 / sketch-core 58 / cards-tool 52 / client-ui-sketch 37 / sketch-tool 28），六个包 tsc --noEmit 全清。
- 真机验收不是「没报错」：函数图 canvas 像素回读（曲线/坐标轴非零）；流程图截图读到胶囊起点、菱形判断、是/否分支与汇合箭头；电子排布图逐项核对轨道数、电子数与洪特规则；渐变/模糊读渲染后的 DOM（linearGradient 停点、stroke-dasharray、filter）而不是只看截图。
- 回归钉：wiring 闸门（少注册一张脸即红）、turnTail 发布键必须等于 Definition 的 kind、draw 的 draft/final 过滤、虚线只能落在描边型笔上、渐变角度按 CSS 约定。
bash
pnpm test # 539 passed
pnpm typecheck # 六个包全清
pnpm build:client # 两个 lib/client.js

七、已知限制（照实说）

- 有些卡片会被 DSH 的展示逻辑「吞掉」。 工具调用按定义属于「回合过程」，而 dsh 的工作步骤展示有「简洁 / 标准 / 详细 / 完全展开」四档；在部分档位/版本下，过程区的卡片会被折叠或藏起来，只有把信息展示切到「完全展开（verbose）」或展开对应回合才能看到。这是 dsh 对回合过程的显示策略，不是卡片没渲染，也不是插件坏了。本插件已经把产出物同时挂到 turnTail，但宿主版本与展示设置仍会影响最终可见性；排查时先切「完全展开」，再看卡片是否在。table、flowchart、sketch_function、draw、figure 都走同一条通道，表格同样适用——表格在默认档位被折叠时，切到「完全展开」即可显示。
- 「完全展开」档下会看到同一张卡两次（过程行 + 产出物行），这是两张脸的副作用，目前未去重。
- 「轨迹」页看不到卡片：卡片的 view target 是 chat，轨迹页按设计只显示原始调用。
- figure 目前只有四个模板，不是通用约束求解器；标签位置固定，不做自动避让。
- orbital_diagram 支持 H–Zn，atom_shell 支持 H–Ca；超出范围会直接报错，不会猜。
- draw 是确定性矢量手绘，不是像素级绘画模型；draft 草稿默认不展示，模型最多提交一次 final。
- draw 卡片是一张位图快照：图里的文字不可选中；每张 1200×800 的卡约占 8.6MB 显存（缓存上限 6 张）；首次上屏有约 100–300ms 的占位。换来的是滚动与放大不再重栅格化。
- 模糊、混合模式、渐变都受绘制部件数量影响：三四百条 path 的卡仍会比几十条的慢一档，提示词里建议把大色块合并、少用重复罩染。
- Host 半与 client 半的改动都需要重启应用才生效（无 HMR）。运行中不要重建 client 产物。

八、参与贡献

- 注册你自己的卡片 kind：一个载荷解析器 + 一个渲染器 + 一组测试；
- 用出问题请带 show_card 的原始参数开 issue；
- 如果它帮你省掉了一坨 ASCII 图，欢迎 star。

License

MIT © 2026 QinLuza. 见 LICENSE。