Aafff623/dsh-callout

dsh-callout

为 DeepSeek Harness (DSH) 助手 Markdown 提供 GitHub 风格提示卡片。它把符合条件的 > [!NOTE] 引用块渲染为带稳定类型、图标和语义色的紧凑卡片，不修改存储的会话内容或 DSH 核心渲染器。

先看效果

> [!WARNING]
> This operation may overwrite existing configuration.

安装插件并刷新 DSH Web 后，发送这段助手 Markdown。符合条件的首标记会成为警告卡片；畸形或未知标记仍按普通文本保留。

为什么需要这个插件

警告应该看起来像警告，而不必等到读者读到命令才意识到。关键结论应该容易定位，而不必把整段回答都套进彩色框里。

dsh-callout 让源格式保持可读的 Markdown，只在展示阶段做升级：

助手 Markdown → DSH MarkdownText → 普通引用块 → 提示卡片

它不修改存储的会话内容、provider、权限、工具或 DSH 核心渲染器。

支持的类型

类型	用途	语义色
NOTE	前提、环境事实与边界	蓝
TIP	更优或不太明显的做法	绿
IMPORTANT	决策或关键结论	紫
WARNING	潜在损失或破坏性操作	琥珀
CAUTION	高影响或难以回退的操作	红

视觉与机制图

下面两张图把证据贴近实现：类型图展示支持的语义卡片，流程图展示带守卫的 DOM 展示层升级路径。

安装

没有设置项。装上之后，宿主半会把写法说明注入系统提示词，浏览器半会升级合格的助手 Markdown。

从 GitHub

dsh plugin --profile web add github:Aafff623/dsh-callout

然后硬刷新 Web UI（Ctrl+Shift+R）。dsh.bundle.patch 会把插件插入 profile bundle。

lib/ 已提交入库，git 安装无需本地构建。

npm

尚未发布。只有包进入你使用的注册表后，dsh plugin --profile web add dsh-callout 才可用。

规范语法

使用以下两种形式之一：

> [!NOTE]
> 正文写在下一行。

> [!NOTE] 正文写在同一行。

标记必须是引用块的第一段内容。多行 callout 的每一物理行都以 > 开头。

以下不是规范 callout：

[!NOTE] 没有 `>` 标记的正文。

普通文字 > [!NOTE] > 被压到同一行的正文。

畸形或未知标记会 fail-open，作为普通文本保留。插件不会把每一处出现的 [!NOTE] 都强行变成卡片。

保证的行为

• 五种固定类型，大小写不敏感。
• 代码、行内代码、强调、链接、列表、嵌套引用和后续段落不会触发引用块升级。
• 标记只从符合条件的首段文本节点移除，正文节点保留。
• observer 回声路径是幂等的：插件自身的文本变更不会被误判为编辑。
• 真实编辑可以移除插件拥有的卡片样式，并在安全时还原源标记。
• 深浅色板规则跟随 DSH 的 body[data-ds-dark-theme] 开关。

不做的事

• 用户（Human）消息由 DSH 以纯文本渲染，刻意不在本插件作用域内。
• 它不是 Markdown 解析器替代品，也不新增 Markdown AST 节点类型。
• 不保证解析后能区分真实标记与被反斜杠转义的标记。
• 依赖当前 DSH Web DOM 约定；未来渲染器变化应通过回归套件和浏览器冒烟测试复核。

架构

层	文件	职责
宿主	src/index.ts	向系统提示词注入简洁的输出契约
Bundle	cordis.patch.yml	在 DSH bundle 中注册插件入口
浏览器	src/client/index.ts	匹配渲染后的 DOM、应用卡片属性/CSS、观察流式更新、负责卸载
验证	test/callout.test.mjs	测试 GFM 形状、负例与 observer 状态机

两半都由 esbuild 构建到 lib/。浏览器部分刻意保持纯展示层：使用插件自有 data-md-alert-* 属性与 --dsh-callout-* 变量，并通过 Cordis ctx.effect() 注册清理。

开发

npm install
npm run typecheck   # tsc --noEmit
npm run build       # esbuild → lib/index.js + lib/client.js（ModuleLoader 包装）
npm test            # node:test，在 vm 沙箱中跑构建产物

lib/ 是刻意提交入库的：git 安装无需构建步骤。改动 src/ 后要执行 npm run build 并把刷新后的 lib/ 一起提交——CI 会检查漂移。

测试套件目前覆盖 30 个用例，包括：

• 标准单行与多行形式；
• 五种类型、小写类型、CRLF 与 CJK 文本；
• 未知/粘连标记、代码、强调、链接、列表、嵌套引用与缩进/围栏代码；
• 裸助手 Markdown 段落回退；
• 首次升级、observer 回声、真实编辑清理与节点移除释放；
• 增量脏根命中、无关 mutation 不得清卡片、以及父段落被重建后仍能剥标记。

需要快速目视时，打开 demo-before-after.html。本 README 中的图是确定性的实现示意，不是运行中会话的截图。

兼容性与维护

插件	DSH 基线	状态
0.2.x	0.1.2-rc.1	已测试

DSH 升级后，先运行 npm test，再冒烟测试一条标准 callout、一段代码示例、一次主题切换和一次会话切换。若渲染器、Markdown 根 class、客户端加载器或 chat-flow 属性发生变化，先复核 src/client/index.ts 再升级插件版本。

许可

MIT——见 LICENSE。