dsh-rich-response
把 DeepSeek Harness 的回复从一大坨纯文本，变成可扫读、有语义色块的卡片。
中文
这是什么
所有 AI 聊天界面都长一个样：黑字白底，层级只靠加粗和缩进撑着。这个插件给 DSH 的回复加上语义化色块 —— 顶部一张结论卡，要点排成卡片组，对比变成表格，步骤变成编号流。
安装
dsh plugin --profile web add github:xiangxueyujiandelin/dsh-rich-response
装完需要重启 DSH（bundle 层在启动时组装）。
桌面版：也可以手动挂载 —— 不需要 CLI，不需要 pnpm。逐步骤见 docs/desktop-install.md。
本地开发：
git clone https://github.com/xiangxueyujiandelin/dsh-rich-response
cd dsh-rich-response
dsh plugin --profile web add .
工作方式
插件教模型一套小型输出协议，再把返回的内容渲染成卡片：
:::summary{title="结论"}
丢失的是**可定位坐标**，不是数据本身。
:::
:::points{cols="3"}
- **数据在** — ref 会读写，ttl>0 即会话存活
- **入口没了** — 页面方式取不回
- **uuid 不可转** — 无法塞进另一条对循环
:::
渲染成带底色和左边框的卡片，而不是一堆 > 引用符号。
两个块族：
| 族 | 语法 | 用途 |
|---|---|---|
| 语义块 | GitHub Alerts（> [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT]） |
带色提示块。模型零学习成本 —— 这个语法在训练数据里到处都是 |
| 结构块 | ::: 围栏 —— summary / points / table / steps / columns |
卡片、对比表、编号流、分栏 |
设计原则：颜色 = 语义
插件刻意不给所有东西上色。只有模型明确标记的块才染色，正文保持干净。
- 只用语义色 —— 蓝块是补充，琥珀是警告，绿是结论
- 底色极低饱和，边框承担识别职责
- 着色面积约 11%，对比"全面染色"的 38%（后者读起来是噪音）
优雅降级
模型不配合是常态，不是异常。五级降级，全程不给用户看任何错误提示：
L0 解析成功 → 完整卡片
L1 可选字段缺失 → 用默认值补齐
L2 结构非法 → 静默退回普通 markdown
L3 围栏未闭合 → 按引用块渲染
L4 完全没有标记 → 普通 markdown（宿主默认）
parseRich 永不抛异常，3000 组 fuzz 用例强制保证这一点。
流式兼容
回复是逐 token 吐出来的，::: 围栏经常有一段时间没闭合。实测行为：
- 闭合前 → 0 个块，文本按普通 markdown 渲染
- 闭合后 → 1 个块，切换成卡片
不闪烁、不跳动。渲染层只需要一条规则：markdown 照常渲染，遇到 level 0 的块才切卡片。
开发
npm run test:all
三套测试共 92 项断言，无需安装任何依赖（Node 22 即可）：
| 套件 | 断言数 | 防什么 |
|---|---|---|
parser-test.mjs |
24 | 协议解析与降级矩阵 |
verify-build.mjs |
13 | 构建产物与源码漂移 |
check-seam.mjs |
55 | 宿主 API 契约跑偏（见下） |
check-seam.mjs 的存在是因为第一版把三个宿主 API 猜错了，插件装上完全不会渲染；
第二版又因为用错了模块格式，DSH 直接启动失败。本项目用到的每个宿主 API 都已对照 DSH 源码确认，记录在 docs/host-seam-reference.md。
其中一项断言会在 Node 的 vm 沙箱里按 classic script 语义执行产物 ——
和宿主加载插件的方式一致。这是「产物能不能被宿主执行」的回归防线。
怎么挂进 DSH
DSH 里一切皆插件，UI 也是插件。本插件替换一个 keyed 渲染器：
ctx.slots.register(
{ name: 'conversation.chat.node', key: 'assistant-step', priority: -10 },
RichAssistantNodeView,
)
priority: -10 遮蔽内置渲染器（内置用默认 0）。其余部分 —— 推理折叠、工具调用分组、图片画廊、文件提及、turn-process 联动 —— 全部原样透传。
目录结构
├── src/
│ ├── client.js 渲染器（浏览器半区）
│ ├── index.js 宿主半区（空实现，满足 bundle 契约）
│ ├── parser.js 协议解析器
│ ├── parser-reference.ts 协议解析器（TS 参考实现）
│ └── rich-response.css 样式
├── protocol/ 协议规范（中文）
├── docs/ 技术方案 + 已验证的宿主契约（中文）
├── skills/rich-response/ 内容层 skill
├── scripts/build.mjs 零依赖构建
└── tests/ 三套测试
当前状态
协议与渲染器已实现并通过测试，但尚未在真实运行的 DSH 上验证 —— 宿主契约是靠读源码确认的，不是靠跑出来的。
许可
MIT © lin（xiangxueyujiandelin）
English
What it does
Every AI chat UI looks the same: black text on white, hierarchy carried by bold and indentation alone. This plugin gives DSH replies semantic color blocks — a conclusion card up top, key points as a card row, comparisons as a table, procedures as a numbered flow.
Install
dsh plugin --profile web add github:xiangxueyujiandelin/dsh-rich-response
Then restart DSH (bundle layers are assembled at startup).
Desktop app: the plugin can also be mounted manually — no CLI, no pnpm needed.
See docs/desktop-install.md (Chinese) for the step-by-step.
For local development:
git clone https://github.com/xiangxueyujiandelin/dsh-rich-response
cd dsh-rich-response
dsh plugin --profile web add .
How it works
The plugin teaches the model a small output protocol, then renders what comes back:
:::summary{title="Conclusion"}
What was lost is the **locatable coordinate**, not the data itself.
:::
:::points{cols="3"}
- **Data is there** — the ref reads and writes; `ttl>0` means the session is alive
- **Entry point is gone** — it cannot be retrieved the page way anymore
- **uuid is not portable** — it cannot be embedded in another loop's id
:::
renders as a tinted conclusion card plus a three-card row, instead of a pile of > quote markers.
Two block families:
| Family | Syntax | Purpose |
|---|---|---|
| Semantic | GitHub Alerts (> [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT]) |
Tinted callouts. Zero learning cost for the model — this syntax is everywhere in training data. |
| Structural | ::: fences — summary, points, table, steps, columns |
Cards, comparison tables, numbered flows, two-column layouts. |
Design principle: color means meaning
The plugin deliberately does not tint everything. Only blocks the model explicitly marks get color; body text stays clean.
- Semantic colors only — a blue block means "supplementary", amber means "warning", green means "conclusion"
- Low-saturation backgrounds, saturated left borders
- ~11% colored area, versus ~38% for a "tint everything" approach that reads as noise
Graceful degradation
The model not cooperating is the normal case, not an error. Five fallback levels, none of which ever shows the user an error:
L0 parsed cleanly → full card
L1 optional field missing → filled with default
L2 structure invalid → rendered as plain markdown, silently
L3 fence not closed yet → rendered as a quote block
L4 no markers at all → plain markdown (host default)
parseRich never throws. A 3000-case fuzz test enforces this.
Works with streaming
Assistant replies arrive token by token, so a ::: fence is usually half-open for a while. Measured behaviour:
- before the closing fence → 0 blocks, the text renders as ordinary markdown
- after it closes → 1 block, switches to a card
No flicker, no layout jump. The renderer only needs one rule: render markdown as usual, switch to a card when a level-0 block appears.
Development
npm run test:all
Three suites, 92 assertions, no dependencies to install (Node 22 is enough):
| Suite | Assertions | Guards against |
|---|---|---|
parser-test.mjs |
24 | protocol parsing and the degradation matrix |
verify-build.mjs |
13 | build output drifting from source |
check-seam.mjs |
55 | host API contract drift — see below |
check-seam.mjs exists because the first implementation guessed three host APIs wrong and the plugin would not have rendered at all; the second one used the wrong module format and DSH failed to boot. Every host API used here was confirmed against the DSH source; docs/host-seam-reference.md (Chinese) records the findings.
One assertion executes the built artifact in a Node vm sandbox under classic script semantics — exactly how the host loads a plugin. That is the regression guard for "can the host even execute this artifact".
How it hooks into DSH
DSH treats everything as a plugin, including the UI. The plugin replaces one keyed renderer:
ctx.slots.register(
{ name: 'conversation.chat.node', key: 'assistant-step', priority: -10 },
RichAssistantNodeView,
)
priority: -10 shadows the built-in renderer (which uses the default 0). Everything else — reasoning collapse, tool-call grouping, image galleries, file mentions, turn-process linkage — is passed through untouched.
Project layout
├── src/
│ ├── client.js renderer (browser half)
│ ├── index.js host half (empty, satisfies the bundle contract)
│ ├── parser.js protocol parser
│ ├── parser-reference.ts protocol parser (TS reference implementation)
│ └── rich-response.css styles
├── protocol/ protocol spec (Chinese)
├── docs/ research + verified host contract (Chinese)
├── skills/rich-response/ the content-layer skill
├── scripts/build.mjs zero-dependency build
└── tests/ three suites
Status
Protocol and renderer are implemented and tested. Not yet verified against a running DSH instance — the host contract was confirmed by reading source, not by running it.
License
MIT © lin (xiangxueyujiandelin)
No comments yet. Be the first to write one.