dsh-rich-msg 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyoukisu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# dsh-rich-msg
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness（DSH）的富内容消息渲染插件：把声明式 JSON 渲染成跟随宿主主题、可交互的消息内容。
+
+## 功能
+
+- **双输出通道**：Markdown fence（```rich-msg，兼容上游 `rich-ui`）与 Tool Bridge（`rich_msg_publish` 暂存 + 最终回答 `ref` 引用）；两条通道共用同一渲染器。
+- **只渲染最终回答**：推理过程、工具调用阶段、中间步骤中的内容不渲染；工具暂存内容只有被最终回答明确引用后才显示。
+- **组件**：布局（stack/row/grid/card/carousel/divider/meta）、文本与 callout/code、实体列表与详情、图库与图片灯箱、卡片指标/进度/状态/表格（排序筛选）/图表（bar/line/area/donut/scatter）、流程 diagram、分层 layers、图片/视频/音频、popover/tooltip、输入/选择/滑块/开关/复选/单选/分段/tabs、条件渲染与安全表达式。
+- **交互**：本地 set/toggle/reset、复制、打开链接、发消息回传；控件状态按会话持久化。
+- **主题**：颜色/字体/圆角/阴影取自 DSH 主题变量，支持浅色、深色与 390px 移动端。
+- **安全**：严格 Schema 校验、无 HTML/JS 执行、无 eval、URL 白名单、大小/深度/数量上限、会话隔离；交互只由用户触发。
+- **模型中立**：不注入 system prompt、persona 或 skill，不规定模型何时/如何使用富内容。
+- **工具**：`rich_msg_validate`（Schema 校验）、`rich_msg_publish`（校验并存入会话 Artifact，返回引用 id）。
+
+## 许可证
+
+MIT。
+
+本项目基于 [kyoukisu/dsh-rich-ui](https://github.com/kyoukisu/dsh-rich-ui)（MIT，Copyright (c) 2026 kyoukisu）的源码进行独立开发与重构，上游版权声明保留在 [LICENSE](LICENSE)；与上游作者无隶属、合作或背书关系。
+
+图标来自 [lucide](https://lucide.dev)（ISC）。
+
+技术文档见 `docs/`。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-rich-msg bundle layer.
+#
+# Inserts only the host plugin row. The plugin registers technical tools
+# (validation and artifact publication) and an optional artifact read route.
+# It registers NO prompt section, NO persona, NO skill and NO agent preset.
+- insert:
+    - id: rich-msg
+      name: dsh-rich-msg

package/docs/ARCHITECTURE.md

@@ -0,0 +1,134 @@
+# ARCHITECTURE
+
+本文件说明 dsh-rich-msg 的分层、生命周期与关键设计取舍。所有结论基于本机安装的 `@deepseek-ai/dsh@0.2.2-alpha.2` 实际源码/类型与真实宿主验证，不是对 DSH 未来 API 的假设。
+
+## 1. 分层
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Host（Node ESM, lib/index.js）                                │
+│  · tools.register(rich_msg_validate / rich_msg_publish)       │
+│  · ArtifactStore（会话作用域、TTL、容量、淘汰）                 │
+│  · ctx.inject(['webServer']) → 只读 GET 路由（可选）           │
+└───────────────▲──────────────────────────────────────────────┘
+                │ session log（工具调用参数 + 工具结果）
+┌───────────────┴──────────────────────────────────────────────┐
+│ Client（Browser ModuleLoader bundle, lib/client.js）          │
+│  · ChatView    ← ctx.uiConversation.binding(session).target('chat') │
+│  · FenceRenderer  DOM 扫描 + 最终性判定 + React root 挂载      │
+│  · ArtifactResolver  会话日志优先 / HTTP 路由兜底              │
+│  · ActionRelay  → ctx.sessions.scope(session).get('conversation').send │
+└───────────────▲──────────────────────────────────────────────┘
+                │ 同一份 RichSpec / 同一套 React 组件
+┌───────────────┴──────────────────────────────────────────────┐
+│ Renderer（React，框架无关于 Cordis）                            │
+│  RichResponse → 布局/数据/媒体/流程/控件/逻辑                   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+依赖方向严格单向：`host → shared ← client`，`client → ui → core`。`core` 不依赖 React，`ui` 不依赖 Cordis 或宿主服务。
+
+## 2. 宿主侧生命周期
+
+- 插件形态：npm 包 + `package.json.dsh.bundle.patch` 指向 `cordis.patch.yml`，由 profile 的 `dsh.profile.bundles` 激活。
+- `apply(ctx, config)` 只做三件事：
+  1. `ctx.tools.register(...)` 注册两个工具；
+  2. 创建 `ArtifactStore`；
+  3. `ctx.inject(['webServer'], ...)` 可选注册只读路由。
+- 所有资源登记在 `ctx.effect(() => disposeAll, 'dsh-rich-msg: host resources')` 中；fiber 卸载时逆序释放、清空 Artifact、移除路由。
+- `apply` 同时返回 disposer，兼容把返回值当日志清理函数的宿主。
+
+**不变量**：`apply` 不读取 `ctx.systemPrompt`、`ctx.persona`、`ctx.skill`、`ctx.agentPreset` 等任何模型行为服务。测试用 Proxy 记录属性访问并静态扫描源码双重保证（`tests/host/neutrality.test.ts`）。
+
+## 3. 客户端侧生命周期
+
+`apply(ctx)`：
+
+1. 构造 `ChatView`（读取 Chat Snapshot）与 `ArtifactResolver`、`ActionRelay`；
+2. 通过 `ctx.inject(['uiConversation'])` 延迟绑定 Snapshot 服务（服务不存在时自动降级）；
+3. 通过 `ctx.inject(['slots'])` 可选安装右侧栏实体详情页；
+4. 安装一次性样式；安装 Fence 渲染器；
+5. 全部登记进 `ctx.effect(() => dispose, 'dsh-rich-msg: browser resources')`。
+
+卸载时：断开 MutationObserver、取消 Snapshot 订阅、unmount 所有 React root、恢复所有被隐藏的源码块、移除 `<style>`、清理缓存。卸载路径由单测与真实宿主验证覆盖。
+
+## 4. Fence 渲染（通道 A）
+
+### 4.1 为什么是 DOM 适配器
+
+已核实的 DSH 客户端扩展点：
+
+| 扩展点 | 能力 | 结论 |
+|---|---|---|
+| `conversation.chat.node`（keyed by ChatNodeKind） | 可整体替换 `assistant-step` 渲染器 | 会重写推理折叠、文本选择、流式稳定性等宿主行为，侵入过大 |
+| `conversation.chat.reasoning.body` | 仅推理正文 | 与正文无关 |
+| `slots` / `uiRenderer` | 通用 Slot 体系 | **没有** fenced-code 渲染器注册表 |
+| `MarkdownText`（ui-primitives） | Markdown 渲染 | 只暴露链接/图片/文件委托，没有代码块扩展点 |
+| DOM | 宿主真实输出 | 官方 genui 类插件的既有技术，可失败关闭 |
+
+因此沿用"只读 DOM 适配 + 相邻挂载"的技术，但用 Chat Snapshot 补齐上游缺失的**最终消息判定**。
+
+### 4.2 判定流程
+
+```
+候选代码块（.md-code-block / .code-block / [data-code-block-content]）
+ ├─ 在 [data-rich-msg-root] 内？ → 跳过
+ ├─ 最近的 [data-chat-flow-kind] 不是 assistant-step？ → 跳过
+ ├─ 语言标签：显式非 rich-msg/rich-ui → 跳过
+ │           通用标签（宿主把未知语言本地化）→ 仅接受严格 payload 特征
+ │           （version:1 + nodes 数组，或合法 ref 文档）
+ ├─ Chat Snapshot 可用？
+ │   ├─ 该行 node.kind === 'assistant-step'？
+ │   ├─ 围栏文本属于 text 块（不是 reasoning 块）？
+ │   ├─ finality：该 assistant 步骤是整轮最后一个且其后无 tool-call？
+ │   │     running → streaming-final（可预览）
+ │   │     settled → final
+ │   │     否则  → not-final（不渲染）
+ │   └─ 若 snapshot 不可用 → 保守降级：仅已稳定行 + 不预览流式
+ └─ 通过 → 校验/挂载；任一环节失败 → 保留宿主原生代码块
+```
+
+**关键点**：`assistant-step` 在 DSH 中既包含推理过程，也包含工具调用前后的中间叙述，所以"祖先匹配"不能证明它是最终回答。Snapshot 判定解决了这一点。
+
+**调度策略（0.1.1 起）**：完全事件驱动。
+
+- 触发器只有三个：宿主 DOM 的 `MutationObserver` 批次、Chat Snapshot 订阅、`visibilitychange`；
+- 同一事件循环内的多次触发合并到一个微任务，**没有定时器、没有轮询、没有 rAF 循环**；
+- 每次只评估事件命中的行；行签名未变时零解析、零重绘；
+- **默认只在行已稳定后渲染**（不渲染流式预览）。回答完成前的围栏保持宿主原生代码块，避免每个 token 重建 React 树；
+- 渲染异常由 `RenderBoundary` 捕获：隐藏容器、恢复源码块，不重试同一失败树。
+
+### 4.3 挂载与重挂载
+
+- 每个源码块对应一个独立 `createRoot` 容器，容器插在源码块之后并设置 `hidden` 隐藏源块；
+- 同一围栏内容变化时**原地更新**（复用 root、按渲染 key 去重），不销毁重建；
+- 宿主 reconciler 可能移除外来节点：校验 `source.nextSibling === container` 并按需重插，**最多 3 次**；超限则放弃该行并恢复原生代码块，避免插入/删除拉锯；
+- **每个 document scope 只允许一个渲染器实例**（HMR/重复安装会替换旧实例，而不是双挂载）；
+- 卸载：逐个 unmount、移除容器、恢复 `source.hidden`、断开观察者与订阅。
+
+### 4.4 持久化
+
+控件状态使用 `sessionStorage`，key 由 `[插件, 会话 id, 行锚点, 块序号, ref]` 组成；只持久化 slider/switch/select/tabs 等声明式控件，输入框、日期、Action payload 一律不写。存储失败静默禁用。
+
+## 5. 工具桥接（通道 B）
+
+见 [TOOL-BRIDGE.md](TOOL-BRIDGE.md)。
+
+## 6. 为什么不注册 tool view
+
+DSH 提供 `tool.call.toolview` 按工具名键控的渲染槽。刻意**不**使用它来渲染富内容：工具阶段的内容不应冒充最终回答。工具行保持宿主默认呈现（名称、参数、结果摘要），富内容只在最终回答引用处出现。
+
+## 7. 构建与加载
+
+- Host：esbuild 打包为 ESM（平台 node，仅 Node 内置依赖）；
+- Client：esbuild 打包为 CJS 主体，由构建脚本包进
+  `window.__ModuleLoader__.load({ id, factory(require) { ... } })`；
+- `react` / `react/jsx-runtime` / `react-dom` / `react-dom/client` 保持 external，由 Web 外壳静态模块表提供；其余（含 lucide-react）打进 bundle；
+- CSS 作为文本模块打入 JS，由插件在运行时注入一个带命名空间属性的 `<style>`，卸载时移除。
+
+## 8. 已知取舍
+
+1. **DOM 契约是观测契约，不是稳定 API**：宿主升级可能改变类名/标记。渲染器在所有判定点失败关闭（保留代码块），并在升级后需要重新跑真实宿主验证。
+2. **Snapshot 不可用时无法区分推理**：降级模式只保证"不渲染流式内容 + 仅 stable 行"，无法排除推理块。文档与代码都显式记录了这一限制；真实 Web 组合中 `uiConversation` 必然存在。
+3. **引用解析优先走会话日志**：这样离线、刷新、宿主重启后仍可渲染历史回答；HTTP 路由只覆盖工具结果被压缩等边缘情况。两者都失败时显示可读诊断，不会静默丢内容。
+4. **不接管宿主 Markdown**：普通代码块、LaTeX、文件链接、图片灯箱等全部保持宿主行为。

package/docs/CHANGES.md

@@ -0,0 +1,78 @@
+# CHANGES
+
+相对上游 `kyoukisu/dsh-rich-ui@0.6.2` 的完整变更报告。
+
+## 0.1.1（稳定性修复）
+
+0.1.0 在长会话中会出现页面无响应（"此页面没有响应"）。根因是渲染调度而非数据协议：
+
+1. 流式期间每来一个 token 就销毁并重建一个 React root；
+2. 每次 DOM 变更全量扫描整个页面，长会话 / 长历史下开销失控；
+3. 复用分支把已渲染容器反向设为 `hidden`，与宿主 reconciler 反复拉扯。
+
+0.1.1 修复：
+
+- 渲染调度改为**纯事件驱动**（DOM MutationObserver 批次 / Chat Snapshot 订阅 / `visibilitychange`，微任务合并；无定时器、无轮询、无 rAF 循环）；
+- **默认只在稳定的最终回答渲染**（流式预览改为可选且默认关闭），消除 per-token React 重建；
+- 按事件命中的行**局部评估**，行签名缓存使重复扫描零解析、零重绘；
+- 同一围栏**原地更新**，不重建 root；
+- **每个 document scope 只允许一个渲染器实例**；
+- 宿主移除外来容器时最多重插 3 次，超限放弃并恢复原生代码块；
+- 修复复用分支的 `hidden` 反转 bug；
+- 删除对已移除的 `prompt-rich-ui` 目录的残留测试引用。
+
+验证：`tsc --noEmit` 0 错误；15 个测试文件 / 226 项测试通过；隔离宿主压力验证（201 行模拟历史 + 150 次流式形状 DOM 变更）0 long task、最大帧间隔 19.5ms、单 root、卸载归零、无控制台错误。
+
+## 1. 总体
+
+| 维度 | 上游 | dsh-rich-msg |
+|---|---|---|
+| 定位 | 面向单个 Agent 产品的富回答插件（含模型行为注入） | 通用、无行为倾向的富内容渲染引擎 |
+| 输出通道 | Markdown fence（DOM 适配） | Fence + Tool Bridge 双通道 |
+| 模型上下文 | 自动注入 systemPrompt 段落 + 提示文件 | 零注入；工具描述纯技术 |
+| 最终消息判定 | 仅 `assistant-step` 祖先 | Snapshot 最终性 + 推理排除 + 流式回撤 |
+| 主题 | 自有配色 + 部分桥接 | 全量 DSH token 桥接（明/暗/移动端） |
+| 构建 | Vite + tsc + 独立 demo | esbuild 双产物、无 Vite 依赖 |
+| 测试 | vitest + Playwright 快照 | 15 文件 / 226 项单测与集成测试通过 + 真实宿主 DOM 冒烟；真实模型 E2E 改为人工 |
+
+## 2. 模块级明细
+
+| 模块 | 上游原有能力 | 本次修改 | 修改原因 |
+|---|---|---|---|
+| Prompt | `src/host/index.ts` 通过 `inject:["systemPrompt"]` + `systemPrompt.section(...)` 注入 `rich-ui:fence` 指令；`prompt-rich-ui/prompt.md` 为运行时加载文件 | 删除整条注入链；删除 `prompt-rich-ui/`；技术内容整理为 `docs/PROTOCOL.md` / `docs/COMPONENTS.md`（离线文档，不被运行时读取） | 模型行为必须中立 |
+| 行为指导 | prompt 中包含"默认使用""集合优先卡片""validate 后发送"等大量行为指令 | 全部移除；任何文档不得自动进入模型上下文 | 同上 |
+| Validator | `rich_ui_validate`（描述含行为指导） | `rich_msg_validate`：仅描述输入/输出/无副作用；保留严格校验与错误信息 | 工具 API 保持技术性 |
+| Tool Bridge | 无（仅校验） | 新增 `rich_msg_publish`、`ArtifactStore`、只读 HTTP 路由、`ref` 引用协议、浏览器端解析器 | 支持 Tool 通道且不直接展示工具阶段内容 |
+| Fence 发现 | DOM MutationObserver；`rich-ui` 语言；仅 `assistant-step` 祖先 | 保留扫描框架；新增语言别名 `rich-msg`、严格 payload 特征、Chat Snapshot 校验、finality 状态机、推理排除、流式回撤、引用解析、失败关闭 | 满足"只渲染最终回答" |
+| 渲染器 | RichResponse + blocks + primitives + EntityList/Details + persistence | 直接复用；命名空间/存储前缀改为 `dsh-rich-msg`；保留既有可访问性实现 | 复用成熟实现 |
+| 主题 | `rich-ui.css`（67KB，自有 token + 部分 `--dsw-*` 桥接） | 保留组件样式；新增 `client/host-theme.css` 完整桥接（明/暗/375–480px） | Hybrid 视觉要求 |
+| Actions | `[rich-ui-action]` 信封 + 会话捕获 + 大小上限 | 前缀改为 `[rich-msg-action]`；保留白名单/上限/会话捕获/不记录 payload | 品牌统一 |
+| 实体侧栏 | `entity-tab.tsx` 注册右侧栏 tab | 保留，改为可选注入；标识符改为 `dsh-rich-msg/entity` | 保留能力 |
+| 构建 | Vite 配置 + TS 检查 + 两个 vite build | `scripts/build.mjs`：esbuild 打 Host ESM 与 Client CJS，再包 ModuleLoader；CSS 作为文本模块注入 | 摆脱 Vite/npm 构建依赖，与宿主加载协议一致 |
+| 测试 | vitest 单测（schema/UI/host）+ Playwright 快照 | 保留 schema/evaluator/UI/persistence/entityTab 测试；新增 protocol/artifacts/tools/route/neutrality/chat-view/fence-claim/dom-renderer/artifact-resolver 测试；Playwright 快照移除，改为宿主冒烟 + 人工 E2E | 覆盖新链路、不虚构验证 |
+| 文档 | README + 内部 docs + 运行时 prompt | 重写 README + 8 份技术文档 | 交付要求 |
+| 包清单 | `@kyoukisu/dsh-rich-ui` | `dsh-rich-msg` | 独立项目命名 |
+
+## 3. 保留的上游能力
+
+- RichSpec v1 Schema 与严格校验（`src/core/schema.ts`）
+- 安全表达式求值（`src/core/evaluator.ts`）
+- 流式前缀解析（`src/core/partial.ts`）
+- 全部 React 组件：布局、文本、实体、图表、表格、指标、媒体、流程、控件、逻辑
+- 图片灯箱、图库、popover/tooltip、实体详情面板、右侧栏实体 tab
+- 控件状态持久化（命名空间调整）
+- 可访问性处理（aria、键盘、读屏标签）
+
+## 3.1 验证状态
+
+- 已通过：`tsc --noEmit`（0 错误）、`vitest run`（15 文件 / 226 项）、隔离 profile 真实宿主加载与 DOM 冒烟、0.1.1 事件驱动压力验证。
+- 未完成（按用户要求停止自动化，改人工）：真实模型对话的 Fence 通道与 Tool Bridge 引用端到端验证。
+- 未验证：Android WebView、多标签页并发、超长历史压测、宿主升级后的 DOM 契约。
+
+## 4. 明确不做的事
+
+- 不注册任何 prompt / persona / skill / agent preset；
+- 不通过工具描述或初始化代码影响模型行为；
+- 不修改 DSH 主程序；
+- 不接管宿主 Markdown 渲染；
+- 不在工具行渲染富内容。

package/docs/COMPONENTS.md

@@ -0,0 +1,132 @@
+# COMPONENTS
+
+RichSpec v1 节点字段参考。`?` 表示可选字段（不是 JSON 语法）。字段未列出者一律禁止。
+
+## 根与实体
+
+**Root**：`{version:1, nodes:Node[], title?:string, entities?:Entity[], initialState?:Record<KEY,Scalar>}`
+
+**Entity**：`{id:KEY, kind:string, title:string, subtitle?, description?, image?:URL, images?:(URL|Image)[], facts?:{label:string,value:Scalar}[], cast?:{name:string,role?,image?:URL}[], sources?:{title:string,url:URL}[], related?:KEY[], badge?:{label:string,tone?}, thumbShape?:"poster"|"square"|"landscape", galleryLayout?:"paired"|"single"}`
+
+- `Image` = `{src:URL, alt:string, caption?:string}`
+- `badge.tone`：`success | info | warning | danger | accent`
+- `thumbShape` 控制行预览形状；`galleryLayout:"single"` 为单图带说明的图库
+- 所有 `related`、`entity-ref`、`open-entity` 目标必须存在
+
+## 文本
+
+**text**：`{type:"text", content:Expr, variant?:"body"|"title"|"subtitle"|"caption"}`
+
+行内仅识别：`\`code\``、`**bold**`、`[label](https://…)`、`[[entityId]]`。其他标记按字面显示；链接必须绝对 http(s)。
+
+**callout**：`{type:"callout", content:Expr, tone?:"info"|"success"|"warning"|"error"}`
+
+**code**：`{type:"code", code:string, language?:string, title?:string, lineNumbers?:boolean}`
+
+**icon**：`{type:"icon", name:string, size?:number, tone?:TONE}`（8–128；Lucide 名称）
+
+## 布局
+
+| 节点 | 字段 |
+|---|---|
+| `stack` / `row` / `grid` / `card` | `{children:Node[], gap?:0-128, title?:string}`；`grid`/`row` 支持 `columns`（1–12） |
+| `carousel` | `{children:Node[]}` |
+| `divider` | `{label?:string}` |
+| `meta` | `{items:[{text:string,icon?:string}]}` |
+| `popover` | `{label:string, children:Node[]}` |
+| `tooltip` | `{label:string, text:string}` |
+
+## 数据
+
+**stat**：`{label:string, value:Expr, delta?:Expr, deltaLabel?:string, hint?:string, tone?:"success"|"warning"|"danger"|"accent", icon?:string}`
+
+**progress**：`{value:Expr, max?:number, label?:string, tone?:"success"|"warning"|"danger"|"info"|"accent", showValue?:boolean}`
+
+**status**：`{label:string, tone?:"muted"|"success"|"warning"|"danger"|"info"|"accent"}`
+
+**computed**：`{expr:Expr, label?:string}`
+
+**table**：`{columns:[{key,label,align?:"left"|"right"|"center", format?:"text"|"number"|"status"|"progress", tones?:Record<string,TONE>, max?:number, tone?:TONE}], rows:Record<KEY,Expr>[], sortable?:boolean, filterable?:boolean, filterPlaceholder?:string, caption?:string, empty?:string}`
+
+- 列 key 唯一；行对象的字段必须对应列 key；缺格显示 "—"
+- `format:"number"`：千分位 + 右对齐
+- `format:"status"`：按 `tones`（按显示字符串索引）渲染状态 pill，未知值用 muted
+- `format:"progress"`：0–`max`（默认 100）进度条
+- `sortable` / `filterable` 为本地交互
+
+**chart**：`{kind:"bar"|"line"|"area"|"donut"|"scatter", data?:{label:string,value:Expr}[], categories?:string[], series?:{label:string,values:Expr[]}[], points?:{x:number,y:number,label?:string}[], unit?:string, xUnit?:string, caption?:string}`
+
+- `data` 用于单系列或 donut；donut 值必须非负
+- `categories` + `series` 用于 2–6 个系列，`values` 长度必须等于 `categories`
+- `scatter` 使用 1–200 个 `points`
+
+## 对象与媒体
+
+**entity-list**：`{entityIds:string[], layout?:"compact"|"feature"}`
+
+**entity-ref**：`{entityId:KEY}`
+
+**image**：`{src:URL, alt:string, caption?:string}`
+
+**image-group**：`{alt:string, label?:string, presentation?:"button"|"gallery", src?:URL[], items?:Image[]}`（`src` 与 `items` 二选一）
+
+**video**：`{src:URL, poster?:URL, title?:string, caption?:string}`（原生 controls，不自动播放，不支持第三方嵌入）
+
+**audio**：`{src:URL, title?:string, caption?:string}`
+
+**Gallery / 灯箱**：由 `images`、`image-group` 自动启用，支持键盘与读屏。
+
+## 流程
+
+**diagram**：`{steps:[{id:KEY,label:string,detail?:string,tone?:TONE,connector?:string,depth?:0|1|2}], direction?:"horizontal"|"vertical", caption?:string}`（1–12 步，id 唯一）
+
+**layers**：`{layers:[{title:string, detail?:string, icon?:string, tone?:TONE, items?:[{label,detail?,icon?,tone?}], layers?:[Layer]}], caption?:string}`
+
+- 最多 3 层嵌套；每层最多 6 个条目
+- 同一层不能同时包含 `items` 与嵌套 `layers`
+
+## 控件
+
+| 节点 | 字段 |
+|---|---|
+| `input` | `{stateKey:KEY, label?, placeholder?, inputType?:"text"|"number"|"date"}` |
+| `select` | `{stateKey:KEY, options:{label,value:Scalar}[], label?}` |
+| `slider` | `{stateKey:KEY, min:number, max:number, label?, step?:number}`（min < max，step > 0） |
+| `switch` | `{stateKey:KEY, label?}` |
+| `checkbox` | `{stateKey:KEY, label:string}` |
+| `radio` | `{stateKey:KEY, label?, layout?:"row"|"column", options:[{label,value}]}` |
+| `segmented` | 同 radio，2–4 个短选项 |
+| `tabs` | `{stateKey:KEY, tabs:[{id:KEY,label,icon?,children:Node[]}]}`（id 唯一） |
+| `button` | `{label:string, action:Action, variant?:"primary"|"secondary"|"ghost", disabled?:Expr}` |
+| `conditional` | `{when:Expr, children:Node[], elseChildren?:Node[]}` |
+
+- 共享同一 `stateKey` 的控件必须接受同一值域；
+- `input` 的日期接受 `YYYY-MM-DD` 或 `""`；文本/日期不持久化。
+
+## Actions
+
+| action | 字段 | 说明 |
+|---|---|---|
+| `set` | `{key:KEY, value:Expr}` | 本地状态更新（必须落在 domain 内） |
+| `toggle` | `{key:KEY}` | 本地布尔反转 |
+| `reset` | `{}` | 恢复默认值并清除持久化 |
+| `open-entity` | `{entityId:KEY}` | 本地详情面板/侧栏 |
+| `close-entity` | `{}` | 关闭详情 |
+| `copy` | `{text:Expr}` | 点击后写入剪贴板 |
+| `open-url` | `{url:URL}` | 点击后打开外部链接 |
+| `send-message` | `{text:Expr}` | 作为普通用户消息发回对话 |
+
+副作用（复制、打开链接、发消息）只在用户点击后发生；不会被模型数据直接触发。
+
+## 可访问性
+
+- 图表提供可访问表格/文本替代；
+- 进度条暴露 `aria-valuenow`；
+- 状态 pill 使用语义色 token；
+- 控件有可读标签；
+- 图片必须有 `alt`；
+- 深色/浅色主题下保持对比度。
+
+## 主题 token
+
+组件自身不写死颜色：全部通过 `--ru-*` 变量，由 `client/host-theme.css` 映射到 DSH 的 `--dsw-*` 令牌。详见 [THEME.md](THEME.md)。

package/docs/DEVELOPMENT.md

@@ -0,0 +1,199 @@
+# DEVELOPMENT
+
+开发、构建、打包、发布与人工验证手册。
+
+## 1. 环境
+
+| 项 | 要求 |
+|---|---|
+| Node.js | ≥ 22.19（本机 24.21.0） |
+| esbuild | 本机 `E:/tools/esbuild`，可用 `DSH_RICH_MSG_ESBUILD_DIR` 覆盖 |
+| DSH | `@deepseek-ai/dsh@0.2.2-alpha.2`（本机 `E:\tools\dsh-cli`） |
+| 依赖 | `npm install`（lucide-react 进入产物，其余为开发依赖） |
+
+本项目不使用 Vite；`tsc --noEmit` 仅做类型检查，构建由 esbuild 完成。
+
+## 2. 目录
+
+```
+src/core        RichSpec Schema / 表达式求值 / 流式前缀解析
+src/host        Node 插件：工具、Artifact Store、只读路由
+src/client      浏览器插件：Fence 渲染、Snapshot 判定、引用解析、Action
+src/ui          React Renderer + rich-ui.css + primitives
+src/shared      双端共享协议常量与文档解析
+tests           单元/集成测试（vitest + jsdom）
+scripts         build.mjs / package.mjs
+docs            技术文档
+```
+
+## 3. 构建
+
+```powershell
+npm install
+node scripts/build.mjs
+```
+
+| 产物 | 说明 |
+|---|---|
+| `lib/index.js` | Host ESM 插件（esbuild bundle，platform=node，仅 Node 内置依赖） |
+| `lib/client.js` | 浏览器 bundle，包装为 `window.__ModuleLoader__.load({id, factory(require){…}})` |
+
+- React / react-dom / jsx-runtime 为 external，由 DSH Web 外壳静态模块表提供；
+- lucide-react 与 CSS 文本一起打进 `lib/client.js`；
+- `package.json` 的 `prepare` 会在 `npm install`（包括 git 依赖）时自动构建。
+
+最近一次构建结果：
+
+```
+lib/index.js   48,876 bytes
+lib/client.js 346,449 bytes   (0.1.1)
+host esbuild warnings: 0
+tsc --noEmit: 0 errors
+```
+
+## 4. 测试（已通过，结果保留）
+
+```powershell
+npx tsc --noEmit
+npx vitest run
+```
+
+```
+Test Files  15 passed (15)
+Tests       226 passed (226)
+```
+
+> 0.1.1 修复记录：0.1.0 在长会话中会出现页面无响应——根因是流式期间每 token 重建 React root、每次 DOM 变更全量扫描整页、宿主 reconcider 与容器隐藏互相拉扯。0.1.1 改为纯事件驱动、默认只在稳定回答渲染、按行局部评估、原地更新、单 scope 单实例、重插上限。上述 226 项测试与隔离宿主压力验证（201 行模拟历史 + 150 次流式形状 DOM 变更：0 long task、最大帧间隔 19.5ms、单 root、卸载归零）均在 0.1.1 上通过。
+
+覆盖范围：
+
+| 测试文件 | 覆盖 |
+|---|---|
+| `tests/core/schema.test.ts` | RichSpec 全字段校验、非法输入、上限、实体/引用/图表/表格/控件 |
+| `tests/core/evaluator.test.ts` | 表达式求值、算子树、状态、边界 |
+| `tests/shared/protocol.test.ts` | ref 协议、Action 信封、id 语法、大小上限 |
+| `tests/host/artifacts.test.ts` | 会话隔离、TTL、容量、淘汰、清理 |
+| `tests/host/tools.test.ts` | 工具 Schema、中性描述、校验/发布行为、取消信号 |
+| `tests/host/route.test.ts` | 只读路由：200/404/405/HEAD、跨会话拒绝 |
+| `tests/host/neutrality.test.ts` | 无 prompt/persona/skill 注入、无运行时文件读取 |
+| `tests/client/chat-view.test.ts` | 最终性判定、reasoning/text 区分、Artifact 索引 |
+| `tests/client/fence-claim.test.ts` | 语言门控、通用标签 payload 特征、非法文档 |
+| `tests/client/dom-renderer.test.tsx` | 挂载/还原、中间步骤/推理/工具行不渲染、诊断、回撤 |
+| `tests/client/artifact-resolver.test.ts` | 会话日志解析、路由兜底、缺失处理 |
+| `tests/ui/*` | 上游 RichResponse / primitives / persistence / entityTab 回归 |
+
+> 按交付要求，自动化 CDP 模型端到端测试不再继续，真实模型验证改为人工执行（见第 5 节）。
+
+## 5. 在真实 DSH 中人工验证
+
+### 5.1 安装到独立 profile
+
+```powershell
+# 1) 构建
+node scripts/build.mjs
+
+# 2) 新建 profile（不修改在用的 web profile）
+$profile = "$env:USERPROFILE\.dsh\profiles\richmsg-test"
+New-Item -ItemType Directory -Force "$profile\node_modules" | Out-Null
+
+# profile/package.json
+@'
+{
+  "name": "dsh-profile-richmsg-test",
+  "private": true,
+  "dependencies": { "dsh-rich-msg": "link:E:/DSH_WORKSPACE/dsh-rich-msg" },
+  "dsh": { "profile": { "bundles": [
+    "@deepseek-ai/dsh-base",
+    "@deepseek-ai/dsh-web-app",
+    "dsh-rich-msg"
+  ], "patchReload": "live" } }
+}
+'@ | Set-Content "$profile\package.json" -Encoding utf8
+
+# 3) 建立包链接
+New-Item -ItemType Junction -Path "$profile\node_modules\dsh-rich-msg" -Target "E:\DSH_WORKSPACE\dsh-rich-msg"
+
+# 4) 启动（日志会打印带 token 的 URL）
+node <dsh>/lib/bin.js --profile richmsg-test --host 127.0.0.1 --port 58470 --no-open
+```
+
+> 开发期已用同样的独立 profile 验证过：插件出现在 boot 图、模块经 `/plugins/…` 正常分发、浏览器半生效、Fence 渲染/工具行/普通代码/流式行行为符合预期、卸载还原、零控制台错误；并留下浅色/深色/390px 截图（本地开发证据，未纳入仓库）。
+
+### 5.2 人工验收清单
+
+1. **Fence 通道**：让模型只输出一个 `rich-msg` 代码块（例如 `{"version":1,"nodes":[{"type":"text","content":"Hello"},{"type":"stat","label":"Score","value":42}]}`），确认最终回答中原位置出现组件、源码块隐藏。
+2. **推理排除**：使用会输出 reasoning 的模型，让推理中出现 `rich-msg` 围栏，确认推理区域不渲染富内容。
+3. **工具阶段排除**：调用 `rich_msg_publish` 后，确认工具行只显示普通工具卡片，没有富内容。
+4. **引用渲染**：最终回答写 `{"version":1,"ref":"<publish 返回的 id>"}`，确认渲染位置正确。
+5. **未引用不展示**：publish 后最终回答不写引用，确认页面不出现该 artifact。
+6. **流式**：观察生成过程中只出现已闭合的合法内容，并在该步骤转为中间步骤时回撤。
+7. **非法 JSON**：流式中保持代码块；稳定后显示诊断卡片（含错误与源码复制）。
+8. **普通代码块/其它语言**：完全不受影响。
+9. **刷新/历史重放**：刷新后历史回答仍渲染；控件状态按会话/行恢复。
+10. **主题与窄屏**：浅色/深色、约 390px 宽度。
+11. **卸载**：禁用插件后页面恢复原生渲染，无残留 DOM/样式。
+
+## 6. 打包
+
+```powershell
+node scripts/package.mjs
+```
+
+```
+dist/dsh-rich-msg-<version>.zip          # 可直接解压进 profile 的 node_modules
+dist/dsh-rich-msg-<version>.zip.sha256
+```
+
+ZIP 内容：`package.json`、`cordis.patch.yml`、`lib/index.js`、`lib/client.js`、`README.md`、`LICENSE`、`docs/*.md`。
+打包脚本会自动先执行构建。
+
+最近一次打包结果：`dsh-rich-msg-0.1.0.zip`（123,812 bytes）。
+
+## 7. 发布到 GitHub（不使用 force push）
+
+目标仓库：`https://github.com/Htao-uu/dsh-rich-msg`（上游 fork）。
+
+安全规则：
+
+1. **绝不 force push**；
+2. 新提交的父提交必须是远端 `main` 当前提交，保证 fast-forward；
+3. 远端已有文件（图片等）不因本地缺失而被误删；
+4. 推送前后用 `git ls-remote origin refs/heads/main` 核对。
+
+流程：
+
+```powershell
+git remote add origin https://github.com/Htao-uu/dsh-rich-msg.git
+git fetch --depth 1 --filter=blob:none origin main   # 只取提交与树，不下载二进制
+git reset --mixed FETCH_HEAD                          # index = 远端树
+git add -A                                            # 应用本次重构（含删除）
+git commit -F commit-message.txt
+git push origin HEAD:main                             # 普通 push
+git ls-remote origin refs/heads/main                  # 与本地 HEAD 一致
+```
+
+若直连 Git 不可用，可改用 GitHub REST API（`api.github.com`）：以远端 main SHA 为父提交创建 blob/tree/commit 并更新 ref，同样不使用 force。
+
+## 8. 宿主升级后的复核
+
+1. 重新检查宿主类型：`dsh-client-ui-chat`（slot 契约）、`dsh-client-ui-conversation`（snapshot）、`dsh-host-webserver`（路由）、`dsh-tools`（工具契约）；
+2. `npx tsc --noEmit` 与 `npx vitest run`；
+3. 在独立 profile 中按第 5 节人工复验；
+4. 重点复核 DOM 标记：`data-chat-flow-kind` / `data-chat-node-key` / `data-code-block-content` / `data-ds-dark-theme`；
+5. DOM 变化时渲染器失败关闭（保留原生代码块），需更新 `src/client/dom-renderer.tsx` 选择器后复验。
+
+## 9. 未验证 / 已知限制
+
+- **真实模型 Fence / Tool 双通道端到端**：未由自动化验证（按交付要求改为人工，见 5.2）；判定与解析逻辑由单测覆盖。
+- 宿主若改变工具结果/快照结构，引用解析需要重新验证。
+- 多标签页、Android WebView、超长历史压测：未验证。
+- 进程内 Artifact Store 不跨进程共享；历史引用仍依赖会话日志路径。
+- `sessionStorage` 持久化仅标签内有效。
+
+## 10. 代码约定
+
+- 双端共享代码放 `src/shared` 或 `src/core`，禁止引入 Node/浏览器专属 API；
+- React 组件不得直接依赖 Cordis 服务；
+- 所有交互副作用必须来自用户点击；
+- 新增节点类型必须同时更新 `src/core/schema.ts` 与 `docs/COMPONENTS.md`；
+- 不要重新引入 prompt/persona/skill 注入，由 `tests/host/neutrality.test.ts` 守护。