纸墨锦鲤 cngtn/dsh-cngtn-pond

Dsh-Pond-Koi — 给 DeepSeek Harness 的纸墨主题

一套给 DSH Web GUI 用的主题包：暖纸、暖墨、细线描边、近直角，整个外壳背后还有一池活的 ASCII 锦鲤。视觉语言来自一个单屏作品集站点，产出这套设计的分析放在 cngtn-analysis。

外壳背后的池塘，浅色

外壳背后的池塘，深色

量取配色时对照的参考截图：浅色 / 深色。主题下的对话记录和任务看板：对话记录、任务看板。

这是什么

三层结构，通过官方认可的第三方主题扩展点（ctx.theme.overrideTokens）注册，外加一份样式表和一块画布：

| 层 | 做什么 |
| Token（230+ 组） | 纸与墨的表面、细线描边、更紧的圆角阶梯、真正的直角（不是 squircle）、磨砂菜单取代亚克力、锦鲤朱红作为唯一强调色。不指定字体族：由设置 → 外观 → 字体决定，没选时用系统默认字体栈。 |
| 样式表 | 画布层及其绘制顺序、让水透过外壳边框的透明链路、磨砂面板和 Trajectory 卡片，以及站点那种只留下划线的链接样式。 |
| 画布 | 池塘：锦鲤有 20 节脊椎、爆发-滑行的摆尾节奏、对指针的好奇、点击投食、快速划动受惊、深度下潜，还有一套 ASCII 光栅，把每条鱼刻进和界面同一套字形网格。 |

停用插件，三层全部移除，GUI 回到原生设计。

为什么长这样

设计系统就四种颜色、一种字体、几乎没有装饰：

paper #f5f4f1 ink #262523 (light)
ink #1a1917 cream #fff7f0 (dark)

其余全是推导出来的：描边和弱化文字用墨混纸的 color-mix，一种字体，卡片 8px、媒体 6px，唯一的柔和阴影留给唯一一个抬升表面。

唯一的高饱和色是锦鲤。它的朱红取自池塘自身高光阶梯的第 3 级（纸上 #cc3e1c，墨上 #e86038），用作强调色、主按钮和业务状态——但刻意不用作错误色，因为「错误」和「品牌」绝不能混淆。

池塘

引擎忠实移植自参考站点的 koi-pond/ 组件，拆分方式也一致：

| 文件 | 移植自 | 行数 |
| src/world.js | world.ts | 440 |
| src/shape.js | shape.ts | 79 |
| src/renderer.js | renderer.ts | 672 |
| src/engine.js | koi-pond.tsx | 205 |

没有做任何简化：七种转向力、爆发-滑行的摆尾节奏、选食迟滞、受惊阈值、深度模型，五点采样子覆盖测试、锚定主体的字形哈希、流动光泽、尾迹扩散，以及两套配色，都沿用原版。把最深的体色与参考做像素比对，每个通道的误差不超过一个单位。

有三处确实改了，因为外壳不是落地页：

1. 数量。 站点在全屏画布上播下 3–6 条成鱼，外加两条小锦鲤。主题要求 budget: 0.55，所以典型的 1440×900 窗口会得到三条鱼——足够读作一池水，又少到不碍事。
2. 避让目标。 站点给自己的正文打上 data-koi-avoid 标记。主题改不了外壳的标记，于是改为指名外壳公开的钩子（[data-slot="sidebar"]、[data-composer-card]……）。自己铺纸的面板只让鱼避让；不铺纸的面板还会把鱼淡成水印，跟站点淡化正文的做法一模一样。
3. 尺寸变化时重新播种。 站点只播种一次，因为它的画布在第一次测量时尺寸总是对的。在外壳里，画布在样式表加载之前就插入了，所以第一次拿到的矩形可能是 300×150 的默认值——鱼就会永远困在那个角落。因此只要盒子变化超过四分之一，世界就重新播种。

七个品种

鱼群的配置跟真实池塘一样：大多是白底红斑，少数带花纹，再有一两条金属色或蓝色的鱼增加层次。

| 品种 | 外观 |
| kohaku | 白色，头部有强调色，背上有两到三块鞍斑 |
| sanke | kohaku 加小黑点 |
| tancho | 白色，头顶一块强调色圆斑 |
| showa | 黑色背部，强调色与白色斑块 |
| ogon | 单一金属色，腹部偏浅 |
| asagi | 石板灰背部，腹部带强调色 |
| bekko | 白色，只有黑点 |

每条鱼自带色素，渲染器据此推导出六段色阶——体侧偏暗，背部受光——所以金色锦鲤和红色锦鲤用同一套逻辑着色，而不是换色的复制品。

布局

侧边栏是浮起的。 框架是三列网格，侧边栏保留 280px 的轨道；单元格加 8px 内边距，让卡片画在单元格内部（宽 264px），而不是压缩轨道——调整大小的手柄和中间列都留在外壳放的位置上。卡片四角都是 14px 圆角，一圈细描边，填充与其他面板相同的磨砂质感，外加渐进阴影：七层叠加，模糊半径按几何级数增长（1、2、4、8、16、28、44px），透明度很低，再加一圈 0.5px 的接触环。单层宽阴影只有一条边，看起来像一条带子；叠层则像真实遮挡物那样渐次衰减。纸与墨用不同的透明度，因为深色页面上黑色阴影几乎看不见。

这层阴影需要让列停止裁剪：它原本是 overflow: hidden，把阴影在列边缘切成了 12px 的带子。现在这一列 overflow: visible，行改由内层根节点裁剪，而内层根节点的盒子正好就是卡片的盒子。

折叠后，这一列变成 18px 宽的轨道，只放一个按钮，所以卡片样式被去掉，轨道保持裸露。

右侧面板与它保持一致。 它的列同样是网格轨道，但面板是绝对定位的占据者，正常情况下贴着窗口右边缘。面板被内缩到与侧边栏相同的 10/12/20/18px 盒子，圆角同样是 14px，同样有细线和渐进阴影，而轨道和调整大小的手柄仍留在外壳放置它们的位置。展开时，它就是同一张卡片铺在对话之上，在聊天界面上做磨砂而不是透明：薄片是 58% 的纸色底，叠加 blur(26px)，并且这一列被抬到中间列之上，所以不会有东西盖住卡片。关闭时，卡片、薄片和抬高的层叠一起消失。

标题栏是透明的，原生按钮也一样。 无填充、无模糊：池塘一直延伸到窗口上边缘，标题按钮浮在水面之上。三个标题按钮之所以跟随，是因为桌面端预加载读取 --dsw-specific-sidebar-fill，把它转成 rgba()，再通过 IPC 交给 setTitleBarOverlay —— 所以透明的 token 就得到透明的按钮区。这就是为什么这里的 token 是透明的，而侧边栏自身的表面却由 --dsw-alias-bg-base 绘制：一个值同时驱动面板和原生窗口装饰。

主题唯一够不到的地方，是 Electron 在按下按钮背后绘制的悬停填充。

安装

dsh plugin --profile desktop add github:cngtn/dsh-cngtn-pond

命令形式与其他 DSH 插件相同：dsh plugin 在配置档内转发给 pnpm，于是包被安装，它的 dsh.bundle 补丁被读取，bundle 自动追加到 dsh.profile.bundles。

包发布到 npm 之后，带版本号的形式也能用：

dsh plugin --profile desktop add @cngtn/dsh-cngtn-pond@latest

要锁定仓库的某个确切修订：

dsh plugin --profile desktop add github:cngtn/dsh-cngtn-pond#<commit>

移除也用同样的方式：

dsh plugin --profile desktop remove @cngtn/dsh-cngtn-pond

然后重启 DeepSeek Harness。同一时间只能启用一个主题：token 层会叠加，每个 token 以最后注册的为准，所以先禁用其他主题 bundle。

插件页上的设置

池塘的三项设置在 Host 部分声明（index.js，一个 schemastery Config），正因如此插件页才能描述它们；Client 部分则在 bundle 的包名之下，为 plugins.bundle.config 槽位注册表单。打开 Plugins → Dsh-Pond-Koi，表单就在描述和组件行之间：

| 字段 | 范围 | 含义 |
| Fish | 3–12 | 鱼群总数，包含幼鲤 |
| Colour | mixed / warm / cool / mono | 鱼取用哪些色素 |
| 幼鲤 | 开 / 关 | 两条小鱼，始终待在深水区 |

保存会写入 Host 配置文档；运行中的池塘遵循同一作用域，所以改动立即生效，无需重启。同样的值也可以从浮动的 Pond 面板或控制台设置：

cngtnPond.open()
cngtnPond.set({ fish: 9, palette: 'warm' })
cngtnPond.get()
cngtnPond.list()
cngtnPond.diag() // what the settings wiring reached

配置档也可以在 cordis.patch.yml 里设置该行的 config，随附一套默认风格；Host 配置一旦保存，优先级高于它。

手动安装

cd $env:USERPROFILE\.dsh\profiles\desktop
dsh plugin --profile desktop add "file:C:/path/to/dsh-cngtn-pond"

构建与测试

外壳通过 window.__ModuleLoader__ 求值 client.js，自身无法编译任何东西，所以客户端那一半以单个生成文件的形式发布。先改 src/，然后：

npm run build # inlines src/ + the vendored fonts into client.js
npm test # boot contract + a ten-minute headless simulation
npm run verify http://127.0.0.1:9333 # read the live page over CDP

npm test 运行 test/ 里的两项检查。npm run verify 连接运行中的 DSH（桌面应用需要 --remote-debugging-port=9333；web 配置档本身就是一个 HTTP 页面），打印下面的状态表，这样关于主题的任何说法都能重新核对，而不必从截图里取信。

npm test 运行两项语法检查覆盖不到的检查：

- boot.mjs —— 工厂完成注册，模块导出 apply + inject，每个 token 都是 { light, dark } 字符串对（主题运行时强制执行这条规则，违反即抛错），每个 effect 都返回一个清理函数。
- smoke.mjs —— 36 000 个固定步长，指针持续移动，反复投喂与滑动，断言没有任何脊线节点变成 NaN、被投喂的锦鲤会吃到饲料、饲料与涟漪数量始终有上限、大幅缩放会重新播种而小幅缩放不会。

Trajectory 标签页

Trajectory 与对话记录是两种不同的界面：一张 列出每一步，外面套一层铺满页面底色的遮罩。放任不管的话，这是唯一一个池塘消失、列表读起来像一整块长条纹的视图。

主题把这个标签页变成一叠玻璃卡片：

| 层 | 变成什么 |
| [data-conversation-composer-overlay] | 透明 —— 这个钩子只存在于 Trajectory，所以规则碰不到 Chat |
| 吸顶筛选栏 | 58 % 色调叠加 blur(16px)，账本从下面滚过时 Duration / Turns / Calls / Search 依然可读 |
| [data-trajectory-scroll] | 18 % 薄片叠加 blur(14px) |
| 每个 tr[data-trajectory-row-key] | 一张卡片：30 % 色调、blur(14px)、10px 圆角、细线描边、与下一张卡片间隔 6px |

无法带圆角，所以卡片通过它的两个单元格画出来 —— 第一个单元格取左侧圆角，最后一个单元格取右侧圆角，两者共用同一层色调再加一条过滤规则。border-spacing: 0 6px 负责留出间隙。表格保留 table-layout: fixed，虚拟化器照常测量行高；现在一行高 36px，不再是 30px，虚拟化器会像对待其他尺寸变化一样感知到它。

刻意不照搬的部分

| 站点里的做法 | 为什么不照搬 |
| 单屏布局，overflow: hidden | 外壳是多面板应用，锁死滚动会破坏它 |
| px-[20vw] 留白 | 外壳带侧边栏，留白要跟随容器，而不是视口 |
| pond / projects / gallery / blog 导航 | 导航归外壳自己管 |
| 引用悬停卡片 | 外壳里没有可引用的源数据 |
| 硬编码 defaultTheme="dark" | 浅色/深色偏好由用户自己定 |
| Playfair 14vw 移动端菜单 | 外壳没有全屏移动端菜单 |

原则：照搬视觉语言，不照搬信息架构。

许可

主题不设置任何字体族，因此没有再分发任何东西：排版来自 DSH 自带的字体栈和用户在设置里的选择。fonts/ 目录只作为原始参考来源保留，不再内联进 client.js。这个包里的其余内容都是原创。

本机验证结果

记录环境：DSH 桌面应用（0.2.1-rc.3，Windows 11）和 web 配置档，执行 dsh plugin --profile … install 并重启之后。

| 检查项 | 结果 |
| 包激活 | @cngtn/dsh-cngtn-pond 进入 active；启动审计无记录 |
| 画布挂载 | #cngtn-pond-canvas 存在，应用内 1280×820，浏览器内 1440×900 |
| 池塘绘制 | 23k–66k 个非透明像素，帧与帧之间在变化 |
| token（浅色） | --dsw-alias-bg-base #f5f4f1，--dsw-alias-label-primary #262523，品牌色 #cc3e1c |
| token（深色） | --dsw-alias-bg-base #1a1917，--dsw-alias-label-primary #fff7f0，品牌色 #e86038 |
| 形状 | --dsw-radius-md 8px，--dsw-corner-shape round |
| 材质 | 菜单和面板为磨砂效果：--dsw-menu-backdrop-filter blur(26px) saturate(160%)，填充 color-mix(… 55%, transparent) |
| 字体 | 主题不设置字体：--dsh-font-family-text-default 保留外壳的字体栈（本机为 Segoe UI），在设置里选中的字体会生效 |
| 框架透明度 | 框架和中间列计算为 rgba(0, 0, 0, 0)；每个面板都是磨砂薄片 |
| 标题栏 | 40 px 的 Windows 标题条计算为 blur(22px) 上叠加 58 % 着色，所以 Application / Edit 和面板浮在同一层玻璃上 |
| 聊天玻璃 | 只有两块是磨砂的：已发送气泡（46 % 着色 + blur(14px)）和代码/命令卡片（30 % + blur(14px)）。对话列本身计算为 backdrop-filter: none，所以回复正文保持清晰 |
| 轨迹玻璃 | 标签页的覆盖层透明，账本在 18 % 的薄片上滚动，每一行都是卡片：30 % 着色、blur(14px)、四角 10px 圆角、行间 6px 间隙 |
| Koi steering | 锦鲤在玻璃面板下方游动，而不是绕开它们 |
| Text legibility | 回复正文落在开阔水面上；两块磨砂玻璃块自带色调 |
| Frame budget | 180 帧：p50 16.7 ms，p95 16.8 ms，最大 16.9 ms（60 Hz，无掉帧） |
| Other plugins | Task Board 在该主题下正常渲染和滚动 |
| Fidelity | 锦鲤身体最暗像素 rgb(114,28,14)，线上站点为 rgb(113,26,14) |

有两件事这台机器无法验证，需要你自行确认：

- 主观感受。 池塘里放多少条鱼属于主观判断（1280–1440 px 宽度下三条成年锦鲤加两条幼鱼）；要改的只有一个数字，即 src/apply.js 里的 budget。
- 真实的 prefers-reduced-transparency 开关。 代码路径已实现，引擎也会在开启时清空画布，但 Windows 通过「设置 → 辅助功能 → 视觉效果」暴露该开关，这里没有切换过。