# 开发文档 · dsh-liuyao 面向要改这个插件的人。用户安装与使用说明见 [../README.md](../README.md)。 --- ## 1. 架构总览 一个包同时交付 DSH 的**两个半边**：Host（Node 侧）与 Client（浏览器侧）。 两半边由同一行 patch 挂载——包名解析到 Host 的 `main`，浏览器半边则由 `package.json` 的 `dsh.client` 声明自动发现。 ``` package.json name / dsh.bundle.patch / dsh.client / exports / files cordis.patch.yml insert 一行 { id: liuyao, name: dsh-liuyao } locale/ zh.json 插件页显示的「名字 + 介绍」（中文） en.json 同上（英文；它也是 DSH 读取语言文件的锚点，不能少） lib/ index.js Host 插件：注册工具、技能、卦例只读路由 tools.js 两个工具的定义与执行（手写 JSON Schema） archive.js 卦例库（原子写 + 写链串行化 + 损坏自愈 + 上限淘汰） doctrine.js 解卦体例：完整版读 doctrine.md，精简版内嵌工具描述 doctrine.md 完整《六爻断卦体例》（模型按需经技能加载） client.js 浏览器半边（手写惰性 CJS bundle，无打包器） engine/ tables.js 八卦 / 六十四卦名 / 纳甲 / 六神 / 地支五行 / 冲合刑 / 旬空 hexagram.js 爻值 ↔ 阴阳爻 ↔ 上下卦 ↔ 卦名 ↔ 变卦 palace.js 京房八宫卦序（算法生成）+ 世应 + 宫五行 najia.js 纳甲、六亲、六神、旬空、月破、旺衰、伏神 calendar.js 儒略日 / 日干支 / 节气 / 月建 / 四柱 cast.js 三钱法取爻（随机源可注入） chart.js 装卦组装（含变爻、格局） format.js 卦盘 → 模型可读 Markdown test/ 92 个单测 dsw-theme-tokens.json DSH 主题 token 快照（供样式契约测试） tools/ check-client.mjs 离线加载并校验客户端 bundle run-tests.mjs 同进程跑全部测试（绕开沙箱禁止 spawn 管道） snapshot-theme-tokens.mjs 重新枚举主题 token 刷新快照 ``` --- ## 2. Host 半边 ### 2.1 零 DSH import（重要约束） `lib/index.js`、`lib/tools.js`、`lib/archive.js`、`lib/doctrine.js` 与 `lib/engine/*` **只 import `node:*` 内建模块**，不 import 任何 `@deepseek-ai/*` 包。 原因：`@deepseek-ai/*` 只在 DSH 进程内可解析（启动器装了进程内解析表）。 第三方插件一旦 import 它们，就多了一个"解析不到就整个插件不 apply"的失败面。 而 `defineTool` 实际只做两件事——把参数 DSL 编译成 JSON Schema、包一层参数校验—— 它返回的就是普通对象。所以 `lib/tools.js` 直接手写标准 JSON Schema。 代价与对策：自己保证 schema 落在 DSH 支持的子集内 （`type/oneOf/properties/required/additionalProperties/items/enum/const` + 注解）。 `test/tools.test.js` 里的 `assertSupportedSubset()` 逐条复刻了 DSH 的 `checkSchemaNode` / `checkObjectSchemaTail` 规则，schema 写歪了测试直接红。 同理，**不 import `@deepseek-ai/dsh-storage-domain` 与 `zod`**：卦例库改用 `$DSH_HOME/liuyao/cases.json`（`lib/archive.js`），把原子写、写链串行化、 损坏备份自愈、上限淘汰都自己做掉。 ### 2.2 插件契约 ```js export const name = 'liuyao'; export const inject = ['tools', 'skills']; // 必需服务 export function apply(ctx) { /* ... */ } ``` - **不导出 `Config`**：本插件没有配置项，导出空 Config 反而容易在 patch 的 "整体替换 config" 语义下踩坑。 - **`webServer` 绝不进模块级 `inject`**：headless profile 没有该服务， 写进 `inject` 会让整个插件永远不 apply。改用 `ctx.inject(['webServer'], scope => ...)` 局部等待；服务缺席时工具照常工作，只有卦例面板降级。 - 工具注册用 `ctx.tools.register(definition)`，技能用 `ctx.skills.register({ name, description, content, source })`； 两者内部都以 `layers.effect(this.ctx, ...)` 绑定本 fiber，卸载自动撤销。 ### 2.3 工具 | 工具 | 用途 | | --- | --- | | `liuyao_cast` | 起卦 + 装卦。`method='coins'` 由 Host 一键起卦；`method='lines'` 用调用方给的六个爻值装卦 | | `liuyao_cases` | 卦例库 `list` / `get` / `delete` / `clear` | `output.render` 返回**两个** content part： 1. 卦盘 Markdown —— 给模型读的正文； 2. `JSON.stringify({ __liuyao: 'chart', ... })` —— 给卡片用的结构化信封。 前端卡片靠第二段渲染六爻盘。这是刻意设计的稳定契约：Host 的 `presentCall` / `presentResult` **不会**传到浏览器（DSH 的 Web 客户端不消费它们）， 自定义卡片必须由客户端 `tool.call.toolview` 按工具名注册。 ### 2.4 插件展示元数据（插件页显示的「名字 + 介绍」） **改这里，不要只改 `package.json` 的 `description`。** 插件页读的是 `dsh-app-boot` 的 `readPluginMeta()`，顺序是： 1. 解析 `<包名>/locale/en.json` —— **它是锚点**，解析不到就完全不看任何语言文件； 2. 以该文件所在目录为准，枚举同目录所有 `*.json`； 3. 每个文件读 `meta.title` / `meta.description`（必须是非空字符串）； 4. `package.json` 的 `name` / `description` 只作 `en` 兜底。 ```json { "meta": { "title": "六爻起卦 · AI 解卦", "description": "……" } } ``` 两个**静默失败**的坑（都有测试守着，见 `test/plugin-meta.test.js`）： - `package.json` 的 `exports` 必须声明 `"./locale/*.json"`。缺了它， 解析 `<包名>/locale/en.json` 会抛 `ERR_PACKAGE_PATH_NOT_EXPORTED`， 被 `optionalResourcePath` 吞掉，插件页**悄悄退回** `package.json` 的 `description`。 - 展示文案必须写在 `meta` 里。写在文件顶层读不到，同样静默无效。 语言文件名必须是合法语言 id（小写、不可重复）。`readPluginMeta` 是**每次调用都重读文件、 没有缓存**的自由函数，所以改完只要**刷新插件页**即可，不需要重启 DSH。 另：`readPluginMeta` 还支持 manifest 的 `icon` 字段（SVG/PNG/JPEG/WebP，≤256 KiB， 相对 manifest 目录）——本插件暂未提供图标。 ### 2.5 卦例路由 `ctx.webServer.register({ kind: 'prefix', path: '/dsh-liuyao', handler })`， handler 是标准 `(req, res)`： ``` GET /dsh-liuyao/status 插件与卦例库状态 GET /dsh-liuyao/cases?limit=50 卦例列表（不含完整卦盘） GET /dsh-liuyao/cases/ 单条卦例（含完整卦盘） DELETE /dsh-liuyao/cases/ 删除一条 ``` 之所以走 HTTP 而不是自定义 Remote：`dsh-api-remotes` 的能力集是**构建期固定**的， 第三方插件无法在运行期新增 remote 命名空间（见其 README 的 Known Limitations）。 前端面板通过同源 `fetch` 读这些接口。 --- ## 3. Client 半边 ### 3.1 bundle 契约 DSH **不做运行时打包**。客户端半边必须是预编译产物：一个只做注册的惰性 CJS 包装。 ```js window.__ModuleLoader__.load({ id: 'dsh-liuyao', // 必须等于包名 factory(require) { const React = require('react'); // …… 组件 …… return { inject: ['slots', 'locale'], apply(ctx) { /* 注册 */ }, __internals: { /* 供单测 */ } }; }, }); ``` - `factory` 的**返回值**就是模块导出；`apply` 是 cordis 插件体。 - `require()` 只能解析 DSH 的 seed 模块。0.2.0-rc.2 是 9 个（`react`、 `react/jsx-runtime`、`react-dom`、`react-dom/client`、`@deepseek-ai/cordis`、 `dsh-client-store`、`dsh-client-ui-slots`、`dsh-client-ui-primitives`、 `dsh-client-ui-dockkit`）；0.2.1-rc.2 追加 `zod`、`@tanstack/react-virtual`， 原 9 项 specifier 一字未改。权威列表见 `tools/check-client.mjs` 的 `SEED_SPECIFIERS`。此外还能 require 已在 boot 图中的插件包（需写进 `dsh.client.external`）。 - 所以本文件**不能 import 引擎**（`lib/engine/*` 是 ESM，浏览器半边拿不到）。 客户端需要的常量表（六十四卦名、八卦三爻）在 `lib/client.js` 里各存一份， 由 `test/client.test.js` **逐项断言**两边一致，表一漂就红。 - JSX 不可用，统一 `const h = React.createElement`。 ### 3.2 注册的三个扩展点 | 扩展点 | 用途 | | --- | --- | | `conversation.input.dock`（list/session，`id: 'liuyao'`, `order: 30`） | 起卦面板：输入问题 → 一键起卦 → 请教解卦；内含「卦例」标签页 | | `tool.call.toolview`（keyed/session，`key: 'liuyao_cast'`） | 卦盘卡片 | | `ctx.locale.register('liuyao', { zh, en })` | 中英文案 | 面板的"请教解卦"经 slot 的 `inject(sessionId)` 拿到动词， 内部走 client Session 的 `prompt(content, 'queue')`；会话服务缺席时降级为 把文本写进 composer 草稿。**`sessions` 刻意不写进 `inject`**——写成静态依赖后 一旦该服务缺席，整个插件不 apply，面板会彻底不出现；改成运行时 `ctx.get('sessions')` 最坏只是"发送"降级。 ### 3.3 样式纪律 - **只用 DSH 真实存在的 `--dsw-*` token**（快照见 `test/dsw-theme-tokens.json`）。 - **凡是设成实心填充的地方，必须配成对的前景色 token。** 第 2 条是踩过的坑：曾经把 `--dsw-alias-brand-primary`（一个前景/强调色 token） 当成按钮背景，文字用 `color: inherit`（= `label-primary`），于是浅色模式黑底黑字、 深色模式白底白字，按钮完全看不见。正确做法是用成对的按钮 token： | 用途 | 填充 | 前景 | | --- | --- | --- | | 主按钮 | `--dsw-alias-button-primary-fill` | `--dsw-alias-label-primary-foreground` | | 次级按钮 / 选中标签 | `--dsw-alias-interactive-bg-active` | `--dsw-alias-label-primary` | | 卡片 / 面板 | `--dsw-alias-bg-layer-1` / `-layer-2` | `--dsw-alias-label-primary` | | 描边 | `--dsw-alias-border-l1` / `-l2` / `-l3` | — | 次级按钮刻意与"选中标签"取同一填充 token；hover 不改底色，只把描边强化到 `l3`， 避免 hover 时又压深。`test/client-ui.test.js` 把这几条都锁成了断言。 样式用单个 `