前言¶

在 DeepSeek Harness (DSH) 插件开发中，AI 生成的交付物通常以文本形式呈现。但当问题需要用户进行多步骤交互、参数调试、拖拽决策或实时试配时，纯文本交互显得力不从心。

dsh-web-app 旨在解决这个问题。它将 AI 生成的交付物从静态文本转化为单文件 HTML 的可交互产物——小工具、小游戏或操作面板。这些产物以 Git 仓库为事实源，在对话中通过 /webapp 命令内嵌打开，用户在页面内操作后，结果通过填空模板回传给模型，形成「人机接力」的工作流。

它是什么¶

dsh-web-app 是一个 DSH 客户端插件。它允许开发者部署单文件 HTML 应用到本地 Git 仓库，并在 DSH 对话流中通过 iframe 无缝嵌入运行。交互过程对模型不可见，但交互结果会通过用户确认后注入会话，驱动模型继续决策。

维护者：frankshi2024。
许可证：MIT。

核心功能¶

该插件提供了以下核心能力：

• 部署后自动浮现：当本回合部署或更新了应用时，对话尾部会自动出现体验卡，点击「立即体验」展开。
• 模型主动插卡：通过 dsh-web-app-show 工具，可在对话中途强制插入应用卡片。
• 零模型调用的打开：/webapp 是纯 UI 命令，打开应用的过程不消耗模型 Token。
• 一次性门票机制：每次加载生成唯一的 loadId 和 token，10 分钟过期。token 伺服时写入 HTML，绝不暴露在 URL 中，用于安全校验。
• 严格校验链：拦截回传时，依次校验 event.source、门票有效性、键集与类型（TEXT/NUMBER/BOOLEAN/JSON）严格匹配。
• 默认用户确认：回传结果前展示完整渲染文本，防止误操作。可在配置中关闭。
• 同 turn 去重：同一回合内，若未打断且 payload 严格一致，拦截重复提交。
• Git 即事实源：应用版本由分支+提交号决定，修改仓库内容并提交后，卡片「刷新」即可拉取新版。
• 全屏模式：支持一键全屏（ESC 退出），适合复杂交互。
• 分层 Skills：提供 dsh-web-app-author（部署/修改）与 dsh-web-app-interpret（解读回传）两套 skill。

安装与启用¶

在 DSH 的 profile 目录（例如 ~/.dsh/profiles/<profile>）中执行安装：

pnpm add link:/path/to/dsh-web-app

安装后，需在该 profile 的 package.json 文件中，将 "dsh-web-app" 加入 dsh.profile.bundles 数组，然后重启或热载插件。

环境要求：Node.js ^22.19.0 或 >=24.0.0。

典型用法¶

• 打开应用：在对话输入 /webapp 选择应用，或使用 /webapp <name> 直接打开指定应用。
• 全屏操作：卡片右上角点击「全屏」，或按 ESC 退出。
• 更新版本：在本地 Git 仓库修改代码并 git commit，然后在卡片上点击「刷新」按钮。
• 管理应用：点击侧边栏的「Web 应用」图标，查看版本、仓库状态或删除应用。
• 部署新应用：让 AI 执行 dsh-web-app-author skill 流程，或直接使用 dsh-web-app-deploy 工具。

技术细节与注意事项¶

• 填空模板而非源码读取：模型消费的是交互结果，而非过程。回传时使用预定义的填空模板（callback.template.md）填充用户操作结果，而非读取 HTML 源码。
• 定位对照：如果只是简单的结构化表单问答，GenUI 的表单类组件（如 ask-user-question）更轻量。dsh-web-app 适合复杂交互产物，如运维面板、旅行决策树等。
• 安全模型：
  • 使用 sandbox="allow-scripts" 的 iframe 运行，不授予 allow-same-origin，应用无法访问 Cookie 或 DOM，也无法直接请求 /api。
  • 数据通道使用插件自有前缀路由。
  • 伪造回传由门票校验和结构校验拦截，用户确认是最终兜底。
• 对等依赖：dsh-commands、dsh-tools、dsh-host-webserver 为硬注入；若 dsh-skill 缺失，插件会跳过 skills 注册。

总结¶

dsh-web-app 通过 Git 仓库和单文件 HTML 的结合，实现了 DSH 生态中「可交互产物」的落地。它解决了 AI 文本交付的局限性，让复杂的交互逻辑（如参数调优、状态切换）能够由模型设计、由人操作、由数据驱动。