前言¶
DeepSeek Harness（DSH）里，模型回答通常以 Markdown 文本为主。若要在回复下方呈现对比表、图表、步骤条、日历等结构化界面，常见做法是让模型直接输出 HTML 或在前端硬编码每种场景的布局。前者难以校验、安全风险大；后者与具体内容强耦合，模型也难以只描述「要什么」而不描述「怎么摆」。
社区插件 dsh-iui（维护者 zengwenliang416，SkillHub 分类为客户端）走的是另一条路径：模型通过 render_ui 给出语义化的 content block，插件校验后映射到组件，在回复下方渲染为基于 Astryx 的交互卡片。可选接入 TypeSafe Jev 做组件选型。插件不修改 DSH 源码，以纯插件形式挂载到 profile。
这是什么¶
dsh-iui 是 DSH 的 Intelligent UI 插件：语义内容块（content block）经校验与组件决策后，在沙箱 iframe 中渲染为交互式 Astryx 卡片。字段说明由 ui_reference 工具按需提供，常驻系统提示只需几句话，减轻提示词体积。
工作方式¶
下面按 README 中的链路说明端到端行为。
- 模型给出语义内容。 模型调用
render_ui，提交 summary、comparison、calculator、calendar 等类型的内容块，只描述内容与字段，不描述页面布局。 - 宿主校验。 插件按字段 schema 和跨字段规则校验每个块。例如对比项需覆盖全部属性、公式只能引用输入项、日期须为真实日期。校验失败时返回带路径的错误信息，由模型修正后重试。
- 决定组件。 每个内容块对应若干候选组件（如 chart 可选 bar、line、area、scatter）。若配置了 Jev 则由 Jev 选择；Jev 不可用或置信度不足时回退到规则选择。
- 在沙箱中渲染。 卡片在
sandbox="allow-scripts"的 iframe 中用 React 19 和 Astryx 渲染，iframe 的 CSP 禁止一切网络请求。链接点击由外层页面在新标签页打开，且仅允许http/https。卡片上的交互状态（选项、输入、勾选、日期等）按会话保存在浏览器本地。
内容块与组件¶
当前 README 列出 25 类内容块、57 个组件变体。下表为各类块及其候选组件（与仓库文档一致）。
| 内容块 | 候选组件 |
|---|---|
| summary | callout、card |
| notice | banner、inline |
| comparison | table、card-grid |
| choice | segmented、option-cards、radio-list |
| calculator | sliders、number-fields |
| steps | stepper、numbered-list、accordion |
| metrics | stat-cards、metadata、progress |
| checklist | checkbox-list、cards |
| faq | accordion、list |
| sections | tabs、radio-list、accordion |
| chart | bar、line、area、scatter |
| code | code-block、numbered |
| quote | blockquote、card |
| tags | tokens、badges |
| text | markdown、compact |
| timeline | vertical-steps、dated-list |
| tree | tree、nested-list |
| gallery | carousel、grid |
| glossary | metadata、infotips、list |
| shortcuts | table、list |
| sources | citations、links |
| status | dots、badges |
| timer | countdown、stopwatch |
| people | list、cards |
| calendar | calendar、agenda |
安装与启用¶
环境要求：Node.js 24.9 或更高，DSH 0.2.2 或更高。npm 包名为 @zengwenliang416/dsh-iui（package.json 版本 0.1.0，许可证 MIT）。
在目标 profile 上执行官方安装命令，再启动对应 profile：
dsh plugin --profile <profile> add @zengwenliang416/dsh-iui
dsh <profile>
安装后，插件的 cordis.patch.yml 会在 profile 根部插入 dsh-iui，render_ui 与 ui_reference 进入全局工具层。
插件以当前 DSH 进程的权限运行，安装前建议在 GitHub 上查看源码与 THIRD_PARTY_NOTICES.md（沙箱渲染器含第三方代码）。
配置 Jev（可选）¶
不配置即可使用，此时始终由规则决定组件。若启用 Jev 做组件决策，先设置环境变量 TYPESAFE_API_KEY，再按需编辑 profile 的 cordis.yml：
dsh-iui:
jev:
enabled: true # 设为 false 时始终使用规则
endpoint: https://api.typesafe.ai/v1/systemone
model: jev-latest
apiKeyEnv: TYPESAFE_API_KEY
timeoutMs: 4000
minConfidence: 0.5 # Jev 置信度低于该值时改用规则
启用 Jev 后，卡片标题与内容块会发送至 TypeSafe 用于决策。若不希望内容离开本机，将 jev.enabled 设为 false。
典型用法（模型侧）¶
文档未给出固定对话脚本，但工具契约明确：模型在需要结构化界面时调用 render_ui，按各 content block 的 schema 填写字段；不确定字段含义时可调用 ui_reference 查询说明。校验失败时根据返回的路径化错误修正 payload 后重试。用户侧在 Web 客户端刷新或新开对话后即可在回复下方看到卡片并进行交互（状态保存在浏览器本地）。
适用场景与注意¶
适合： 希望在 DSH 对话中展示对比、指标、图表、步骤、日历等结构化 UI，且希望布局由插件与规则（或 Jev）承担，而不是让模型写 HTML 的开发者。
注意：
- 纯客户端渲染 + 严格 CSP：卡片内无法自行发网络请求，外链由外层打开。
- Jev 为可选能力，涉及外发内容时需自行评估隐私与合规。
- 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；插件生态遵循 DSH「一切皆插件」的思路，以社区维护为主。
开发与本地调试¶
贡献者与二次开发者可在仓库内执行：
pnpm install && pnpm --dir island install
pnpm run build # 构建沙箱渲染器并嵌入，然后构建插件
pnpm run typecheck
pnpm run test
pnpm run gallery -- /tmp/iui-gallery light # 首次运行前先执行 npx playwright install chromium
本地调试时，用本地路径替代包名安装插件；修改并重新构建后刷新页面即可：
dsh plugin --profile <profile> add <本仓库路径>
仓库还提供 scripts/render-cards.mjs（从会话记录截图卡片）与 scripts/demo.mjs（对运行中的 DSH 录制端到端演示）。
结尾¶
dsh-iui 把「模型描述语义块 → 校验 → 选组件 → 沙箱渲染」串成一条可复用的 Intelligent UI 链路，并与 DSH 工具层通过 render_ui / ui_reference 对接。需要查阅安装说明与完整内容块列表时，见 SkillHub 目录页 与 GitHub 仓库。
