dsh-rich-msg 0.0.0-stage → 0.1.0

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,255 @@
-# 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.
+一个独立、无模型行为倾向的 **DSH 富内容消息渲染引擎**（Rich Message Renderer）。
+
+它把结构化 JSON 协议渲染成美观、可交互、跟随宿主主题的消息内容，并提供两条互不耦合的输出通道：
+
+| 通道 | 数据来源 | 最终展示位置 |
+|---|---|---|
+| **A. Markdown Fence** | 最终 Assistant 回答正文中的 ```rich-msg 代码围栏 | 原位替换该代码块 |
+| **B. Tool Bridge** | 工具调用 `rich_msg_publish` 暂存的结构化内容 + 最终回答中的 `ref` 引用 | 最终回答中引用所在的位置 |
+
+两条通道共用同一套 Schema、校验器、React Renderer 与主题适配层。
+
+本项目是**纯技术渲染层**：它不注入 system prompt / developer prompt / persona / skill，不规定模型何时使用富内容，也不改变模型回答风格。是否使用、何时使用、如何组织内容，完全由使用者自己的 Persona、Prompt 或上层应用决定。
+
+---
+
+## 设计目标
+
+1. **协议先行**：先定义并校验数据结构，再渲染；非法数据永不执行、永不修补。
+2. **双通道、单渲染器**：Fence 与 Tool 两种入口最终都落到同一个 `RichResponse`。
+3. **只渲染最终回答**：推理过程、工具调用阶段、中间步骤中的内容不会被当成最终 UI 展示。
+4. **宿主优先的视觉**：组件保留自己的布局语言，颜色、字体、背景、边框、圆角、阴影全部取自 DSH 主题变量；明暗主题与移动端开箱即用。
+5. **安全默认**：声明式 JSON、无 HTML/JS 执行、无 eval、URL 白名单、Action 白名单、大小/深度/数量限制、Session 隔离。
+6. **可卸载、可重挂载**：所有 React root、样式、监听器、路由、缓存都有明确的生命周期。
+
+## 它不负责什么
+
+- 不决定模型应该如何思考、回答、教学或组织内容。
+- 不注册任何 prompt 段落、Persona、Skill 或 Agent 预设。
+- 不通过工具描述夹带 UI 使用策略。
+- 不替使用者选择模型、语气或教学策略。
+
+---
+
+## 架构
+
+```
+dsh-rich-msg
+├── Host Integration（Node / Cordis 插件）
+│   ├── lib/index.js         插件入口：注册工具、装配 Artifact Store、可选 HTTP 读取路由
+│   ├── Artifact Store       会话作用域、带 TTL / 容量上限 / 淘汰策略的内存存储
+│   └── Final Message Bridge 由「工具暂存 + 最终回答引用」构成的两段式桥接
+│
+├── Protocol（框架无关）
+│   ├── core/schema.ts       RichSpec v1 定义与严格校验
+│   ├── core/evaluator.ts    安全表达式求值（无 eval）
+│   ├── core/partial.ts      流式前缀解析（只呈现已闭合且合法的部分）
+│   └── shared/protocol.ts   Fence 语言、ref 协议、Action 信封、DOM 标记、上限
+│
+├── Renderer（React）
+│   ├── ui/RichResponse.tsx  节点调度、交互状态、持久化
+│   ├── ui/blocks/*          Chart / Table / Metrics / Media / Layers / Code / Field
+│   ├── ui/EntityList.tsx    实体列表与详情
+│   └── ui/primitives/*      Popover / Tooltip / Lightbox / Gallery 等基础件
+│
+├── Client Integration（浏览器）
+│   ├── client/dom-renderer.tsx  Fence 发现、最终消息判定、挂载/回滚
+│   ├── client/chat-view.ts     读取 Chat Snapshot：最终性、推理排除、Artifact 索引
+│   ├── client/artifact-resolver.ts  ref 解析（会话日志优先，HTTP 路由兜底）
+│   ├── client/actions.ts        交互事件 → 用户消息
+│   └── client/entity-tab.tsx    可选：右侧栏实体详情页
+│
+├── Theme
+│   └── client/host-theme.css    DSH 主题变量 → 组件 token（明/暗/移动端）
+│
+└── Tests / scripts
+```
+
+详细设计见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
+---
+
+## 两条输出通道
+
+### A. Markdown Fence
+
+最终 Assistant 回答中：
+
+````markdown
+```rich-msg
+{"version":1,"nodes":[{"type":"text","content":"Hello"},{"type":"stat","label":"Score","value":42}]}
+```
+````
+
+渲染器会：
+
+1. 只处理 **最终回答** 的 `assistant-step` 行，并用 Chat Snapshot 校验：该步骤是整轮对话的收尾回答，且其后没有工具调用；
+2. 通过 Snapshot 中该步骤的内容块区分 **正文** 与 **推理**：推理块中的围栏永不渲染；
+3. 校验 JSON；非法内容保持原生代码块（流式中）或显示诊断卡片（已稳定）；
+4. 在原位置挂载独立的 React root 并隐藏源码块，卸载时完整还原。
+
+`rich-ui` 作为上游兼容别名同样被接受。普通代码块、其他语言、工具行内容完全不受影响。
+
+### B. Tool Bridge
+
+工具调用负责**准备**内容，最终回答负责**决定是否呈现**：
+
+```
+模型调用 rich_msg_publish({document})
+   → Host 校验、存入会话作用域 Artifact Store
+   → 返回 {ok:true, id:"rm_…", kind, summary}
+模型在最终回答中写：
+```rich-msg
+{"version":1,"ref":"rm_…"}
+```
+   → 浏览器从会话日志中的工具调用还原文档（主路径）
+   → 或读取 Host 的只读路由（兜底）
+   → 在最终回答的引用位置渲染
+```
+
+如果最终回答没有引用该 id，内容不会被显示；工具阶段本身不渲染任何富内容。
+
+详细数据流与验证方法见 [docs/TOOL-BRIDGE.md](docs/TOOL-BRIDGE.md)。
+
+---
+
+## 支持的能力
+
+组件与字段的完整清单见 [docs/COMPONENTS.md](docs/COMPONENTS.md)，数据协议见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。
+
+- **布局**：`stack` / `row` / `grid` / `card` / `carousel` / `divider` / `meta`
+- **文本**：`text`（行内 code/bold/链接/实体 chip）、`callout`、`code`
+- **对象**：`entity-list` / `entity-ref` / 实体详情面板 / 图库 / 图片灯箱 / `image` / `image-group` / `gallery`
+- **数据**：`stat` / `progress` / `status` / `table`（排序、筛选、状态色、进度列）/ `chart`（bar/line/area/donut/scatter）/ `computed`
+- **流程**：`diagram` / `layers`
+- **媒体**：`image` / `video` / `audio` / `popover` / `tooltip`
+- **控件**：`input` / `select` / `slider` / `switch` / `checkbox` / `radio` / `segmented` / `tabs`
+- **逻辑**：`expression` / `conditional` / 本地 Action（set/toggle/reset/open-entity/close-entity/copy/open-url/send-message）
+
+## 工具接口
+
+| 工具 | 输入 | 输出 | 说明 |
+|---|---|---|---|
+| `rich_msg_validate` | `{document: string}` | `{valid, error?, title?, nodes?, entities?}` | 只做 Schema 校验，无副作用 |
+| `rich_msg_publish` | `{document: string}` | `{ok, id?, kind?, summary?, error?}` | 校验并存入当前会话的 Artifact Store，返回稳定引用 id |
+
+工具描述只说明输入、输出与副作用，不包含任何"何时应该使用"的行为指导。
+
+## 安装
+
+### 方式一：本地 link（开发）
+
+```powershell
+# 1) 构建
+node scripts/build.mjs
+
+# 2) 在 %USERPROFILE%.dshprofiles<name>package.json 中声明（示例）
+#    {
+#      "name": "dsh-profile-richmsg",
+#      "private": true,
+#      "dependencies": { "dsh-rich-msg": "link:E:/path/to/dsh-rich-msg" },
+#      "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-rich-msg"] } }
+#    }
+#    并在该 profile 的 node_modules 下建立指向本目录的 junction/symlink。
+
+# 3) 启动该 profile
+node <dsh>/lib/bin.js --profile <name> --host 127.0.0.1 --port 58470 --no-open
+```
+
+### 方式二：作为依赖安装
+
+把本包发布/复制到可解析的位置后，在 profile 的 `package.json` 中：
+
+```json
+{
+  "dependencies": { "dsh-rich-msg": "link:E:/path/to/dsh-rich-msg" },
+  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-rich-msg"] } }
+}
+```
+
+```powershell
+dsh plugin --profile <profile> add link:E:/path/to/dsh-rich-msg
+# 并把 "dsh-rich-msg" 加入 dsh.profile.bundles
+```
+
+> 新增/替换包后需要重启宿主进程；客户端资源会按 boot revision 重新生成。
+
+## 主题
+
+- 全部颜色/字体/圆角/阴影来自 DSH 的 `--dsw-*` 令牌；
+- 同时支持浅色与深色主题（跟随 `data-ds-dark-theme` 与上游 `data-theme="dark"`）；
+- 组件不覆盖宿主消息气泡、侧边栏或其它插件的布局；
+- 移动端 390px 宽度下保持可读。
+
+详见 [docs/THEME.md](docs/THEME.md)。
+
+## 安全
+
+- 只接受声明式 JSON；
+- 拒绝 `__proto__` / `constructor` / `prototype` 键，防原型污染；
+- 文档大小、嵌套深度、数组长度、组件数量、字符串长度全部有上限；
+- URL 仅允许 http(s)，禁止内嵌凭据与危险协议；
+- Action 事件白名单校验；交互只由用户触发；
+- 富内容不能直接调用任意 DSH 工具；
+- Artifact 按 Session 隔离，跨 Session 查询与不存在等价；
+- 日志不写入文档内容或表单值。
+
+详见 [docs/SECURITY.md](docs/SECURITY.md)。
+
+## 兼容性与已验证范围
+
+- 目标宿主：`@deepseek-ai/dsh@0.2.2-alpha.2`（本机 `E:\tools\dsh-cli`）。
+- Fence 发现依赖宿主 DOM 标记（`data-chat-flow-kind`、`data-code-block-content` 等）。宿主升级后需重新验证；标记变化时渲染器**失败关闭**（保留原生代码块）。
+- 最终消息判定依赖 Chat Snapshot（`uiConversation`）。该服务不可用时退化为保守的 DOM 规则（仅已稳定的 assistant 行，且不预览流式内容），并在文档中明确记录这一降级。
+- **已验证**：13 个测试文件 / 210 项单元与集成测试通过；`tsc --noEmit` 0 错误；隔离 profile 下真实 DSH 宿主加载与 DOM 冒烟验证通过（插件加载、模块分发、Fence 渲染、普通代码/工具行/流式行不接管、卸载还原、零控制台错误、浅色/深色/390px 截图）。
+- **未验证（待人工）**：真实模型对话下的 Fence 通道与 Tool Bridge 引用渲染。自动化 CDP 发送消息未打通，已按交付要求停止；请按 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) 第 5.3 节清单在真实 DSH 中人工验证。
+
+## 上游项目与许可证
+
+- 本项目基于 **kyoukisu/dsh-rich-ui**（MIT）的源码进行独立开发与重构：保留了其成熟的 RichSpec Schema、表达式求值器、React 组件与视觉实现，重写了宿主集成、消息判定、工具桥接、主题桥接与文档，并移除了运行时 Prompt 注入。
+- 上游版权声明保留在 [LICENSE](LICENSE)（MIT, Copyright (c) 2026 kyoukisu）。
+- 图标来自 [lucide-react](https://lucide.dev)（ISC），详见 [docs/THIRD-PARTY.md](docs/THIRD-PARTY.md)。
+- 本项目与上游作者无隶属、合作或背书关系；名称 `dsh-rich-msg` 用于区分衍生项目。
+
+## 变更报告
+
+| 模块 | 上游原有能力 | 本次修改 | 修改原因 |
+|---|---|---|---|
+| Prompt | 通过 `inject: ["systemPrompt"]` 注册 `rich-ui:fence` 段落，构建行为指令并注入每次请求 | **完全移除**运行时注入；删除 `prompt-rich-ui/` 运行时文件；技术内容改为离线文档 | 保持模型行为中立 |
+| Validator | `rich_ui_validate` 工具，描述含"默认使用/优先"等行为指导 | 保留校验能力，改名为 `rich_msg_validate`，描述仅含参数、返回与副作用 | 工具 API 保持纯技术性 |
+| Tool | 仅校验，无状态 | 新增 `rich_msg_publish` + 会话作用域 Artifact Store + 只读读取路由 | 支持 Tool 输出通道 |
+| Fence | DOM MutationObserver 扫描 `rich-ui` 围栏，仅以 assistant-step 祖先判定 | 保留扫描技术；新增 Chat Snapshot 最终性判定、推理排除、流式回撤、引用解析、稳定重挂载 | 只渲染最终回答，不误渲染推理/工具阶段 |
+| Renderer | RichSpec React 组件体系 | 复用全部组件；命名空间改为 `dsh-rich-msg`；保留既有可访问性修复 | 降低改造成本 |
+| Theme | 自带配色 + 部分 DSH token 桥接 | 新增完整桥接层（明/暗/移动端），统一映射 `--dsw-*` | Hybrid 视觉要求 |
+| Actions | `[rich-ui-action]` 用户消息 | 改为 `[rich-msg-action]`，保留白名单、大小上限、会话捕获 | 品牌统一与安全 |
+| Build | Vite + tsc + 独立 demo | esbuild 双产物（Host ESM / Client ModuleLoader bundle），无需 Vite 运行时 | 简化构建、与宿主加载协议对齐 |
+| Tests | vitest 单测 + Playwright 截图 | 保留并扩充为 13 文件 / 210 项单测与集成测试；新增真实宿主 DOM 冒烟脚本；真实模型 E2E 改为人工验证 | 可复现、不虚构验证 |
+| Docs | 上游内部文档 + 运行时 prompt 文件 | 重写为 7 份技术文档，且明确不得成为运行时 prompt | 交付要求 |
+
+完整说明见 [docs/CHANGES.md](docs/CHANGES.md)。
+
+## 开发
+
+```powershell
+node scripts/build.mjs               # 构建 lib/index.js 与 lib/client.js
+npx tsc --noEmit                     # 类型检查
+npx vitest run                       # 单元 + 集成测试
+node scripts/package.mjs             # 打包 dist/*.zip + sha256
+```
+
+详见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
+
+## 目录
+
+```
+src/core        协议与求值
+src/host        Node 插件：工具、Artifact Store、读取路由
+src/client      浏览器插件：Fence 渲染、消息判定、引用解析、交互回传
+src/ui          React Renderer 与样式
+src/shared      双端共享协议常量
+tests           单元与集成测试
+scripts         构建与真实宿主验证脚本
+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,126 @@
+# 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 判定解决了这一点，并且当模型在后续步骤调用工具时，已挂载的流式预览会被**自动回撤**（恢复到原生代码块）。
+
+### 4.3 挂载与重挂载
+
+- 每个源码块对应一个独立 `createRoot` 容器，容器插在源码块之后并设置 `hidden` 隐藏源块；
+- 复用条件：raw 文本、会话、streaming 状态、行 owner、模式（spec/ref/diagnostic）全部一致，避免每个 token 重建整棵树；
+- 宿主 reconcillation 可能移动节点：每次扫描校验 `source.nextSibling === container`，需要时重新插入；
+- 渲染异常由 `RenderBoundary` 捕获：隐藏容器、恢复源码块，不产生无限重试；
+- 卸载：逐个 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,57 @@
+# CHANGES
+
+相对上游 `kyoukisu/dsh-rich-ui@0.6.2` 的完整变更报告。
+
+## 1. 总体
+
+| 维度 | 上游 | dsh-rich-msg |
+|---|---|---|
+| 定位 | 面向单个 Agent 产品的富回答插件（含模型行为注入） | 通用、无行为倾向的富内容渲染引擎 |
+| 输出通道 | Markdown fence（DOM 适配） | Fence + Tool Bridge 双通道 |
+| 模型上下文 | 自动注入 systemPrompt 段落 + 提示文件 | 零注入；工具描述纯技术 |
+| 最终消息判定 | 仅 `assistant-step` 祖先 | Snapshot 最终性 + 推理排除 + 流式回撤 |
+| 主题 | 自有配色 + 部分桥接 | 全量 DSH token 桥接（明/暗/移动端） |
+| 构建 | Vite + tsc + 独立 demo | esbuild 双产物、无 Vite 依赖 |
+| 测试 | vitest + Playwright 快照 | 13 文件 / 210 项单测与集成测试通过 + 真实宿主 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`（210/210）、隔离 profile 真实宿主加载与 DOM 冒烟。
+- 未完成（按用户要求停止自动化，改人工）：真实模型对话的 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)。