dsh-web-app

Readme

# dsh-web-app

**AI 交付给人类的可交互产物** —— 一个小工具、一个小游戏、一张可操作的图表面板，住在 Git 仓库里，对话中 `/webapp` 一键内嵌打开；人在里面交互出结果，一键回传给 AI 继续干活。

AI-delivered interactive artifacts for DeepSeek Harness (DSH): single-file HTML apps — tools, toys, dashboards, mini-games — live in per-app Git repos, open inline in a conversation via `/webapp`, and their *interaction outcomes* flow back to the model as template-filled user messages (behind an explicit confirmation step).

## 它是干什么的

AI 的交付物不再只是文字。一个正则试配器、一张旅行方案对比板、一个排障决策树、一局小游戏——这些「产物」天然是可交互的：人要亲手点、拖、试、权衡，实时看到结果。本插件让这类产物以单文件 HTML 的形式被 AI 随手创造、部署、复用：

1. **AI 部署**：`dsh-web-app-deploy` 工具收 `name + html + metadata + template`，建档三件套（`index.html` / `app.json` / `callback.template.md`）→ git init + 首提交 → 登记注册表；
2. **用户打开**：`/webapp [name]`（不触发模型调用），应用在对话卡片里以 sandbox iframe 内嵌运行；侧边栏「Web 应用」面板管版本与删除；
3. **人在产物里交互**：调参、试配、拖选、玩耍——这一步模型不可见，也不需要可见；
4. **交互结果回传**：用户一键提交 → 桥的门票/结构校验 → **确认弹窗展示渲染全文** → 按填空模板渲染后注入当前会话的用户消息 → 模型读到连贯的「用户汇报」（含应用名、版本、各变量语义），接着上下文继续决策。

运维面板（选好环境/并发/策略，回传给 AI 执行）、旅行计划决策器（拖完路线偏好，回传生成行程）都是这个「人机接力」模式的场景：**交互发生在先，回传发生在后**。

> 定位对照：如果只是「向用户提一个结构化问题」，GenUI 的表单类组件（ask-user-question 等）更轻量，直接用那个就好。本项目的价值在产物本身——交互过程就是目的，回传只是接力棒。演化路线里「接后端」的方向同样服务于这个属性：更重的交互产物（多文件、数据接口、持久状态）需要后端支撑，而不是为了把表单做复杂。

为什么是「填空模板」而不是让模型去读 HTML：模型消费的是交互的**结果**，不是交互过程——没有上下文的模型收到一组凭空数据不知道它是什么；读 HTML 源码 token 开销太大。模板由 AI 在开发期写好，回传时插件填值，模型读到的是人话。

## 特性

- **部署后自动浮现**：turn 结束（含被打断）时若本 turn 部署/更新过应用，turn 尾部自动出现折叠体验卡，点「立即体验」才展开
- **模型主动插卡**：`dsh-web-app-show { name, expand? }` 工具可在对话中途插入卡片——调用瞬间输入框上方出现聚焦条（点「立即体验」全屏打开），turn 尾部同样留卡
- **零模型调用的打开**：`/webapp` 是纯 UI 命令，打开应用这件事模型不可见
- **一次性门票**：每次加载铸新票（loadId+token 双 UUID、绑应用名、10 分钟过期），token 伺服时盖章进 HTML、永不进 URL
- **严格校验链**：`event.source` 比对 → `source/type` → 门票 → values 键集与类型严格匹配（TEXT/NUMBER/BOOLEAN/JSON 四型，JSON 按字符串传输）
- **默认用户确认**：确认弹窗展示渲染后的完整文本；`app.json` 可声明 `confirm:false`（卡片常驻风险提示）
- **同 turn 去重**：同一 turn、未压缩/打断、payload 严格一致 ⇒ 拦截重复提交；其余一律照传
- **Git 即事实源**：部署指针 = 分支+提交，伺服按指针出文件；改应用 = 改仓库 + 提交，卡片「刷新」即拉新版；同名拒绝再部署
- **全屏模式**：卡片一键全屏（显式退出按钮 + ESC）
- **分层 skills**：`dsh-web-app-author`（造/改应用）与 `dsh-web-app-interpret`（解读回传）随包注入

## 安装

```bash
# 在 DSH profile 目录（如 ~/.dsh/profiles/<profile>）中：
pnpm add link:/path/to/dsh-web-app
```

并在该 profile 的 `package.json` 的 `dsh.profile.bundles` 数组中加入 `"dsh-web-app"`。重启或热载后生效。

> 对等依赖（均为可选）：`dsh-commands` / `dsh-tools` / `dsh-host-webserver` 为硬注入；`dsh-skill`（skills 注册）缺失时跳过。

## 使用

| 动作 | 入口 |
| --- | --- |
| 打开应用 | 对话输入 `/webapp`（选择器）或 `/webapp <name>`（深链） |
| 全屏 | 卡片右上角「全屏」；红色「✕ 退出全屏」按钮或 ESC 退出 |
| 拉取新版本 | 改仓库 + `git commit` 后，点卡片「刷新」 |
| 管理 | 侧边栏「Web 应用」图标：版本/仓库状态/删除 |
| 部署新应用 | 让 AI 走 `dsh-web-app-author` skill 流程（`dsh-web-app-deploy` 工具 + `dsh-web-app-check` 自检） |

应用数据落在 `$DSH_HOME/dsh-web-app/`：`apps/<name>/` 为各应用 Git 仓库，`registry.json` 为注册表。

## 一个最小应用

```html
<script>
  const APP_TOKEN = "{{__TOKEN__}}"; // 伺服时盖章；仓库里保持占位符原样
  function submit(values) {
    window.parent.postMessage(
      { source: "dsh-web-app", type: "submit", token: APP_TOKEN, values }, "*");
  }
</script>
```

变量在 `app.json` 声明（`TEXT_1`/`NUMBER_1`/`BOOLEAN_1`/`JSON_1` 固定词表 + label + purpose），回传模板 `callback.template.md` 以 `[webapp 回传]` 开头、用 `{{SLOT}}` 占位。完整契约见 [docs/callback-contract.md](docs/callback-contract.md)，可运行的示例见 [examples/config-panel](examples/config-panel/)。

## 安全模型（摘要）

iframe 固定 `sandbox="allow-scripts"`（opaque origin，不授予 `allow-same-origin`——应用拿不到 cookie/DOM，也走不了 `/api` 鉴权通道）；数据通道是插件自有前缀路由（无鉴权，回环绑定下暴露面 = 本机进程）；伪造回传由门票 + 结构校验拦截，**用户确认是最终兜底**。

## 开发

```bash
node --test   # 52 项测试：契约校验 / 注册表 / git / 部署 / 自检 / HTTP 全链路
```

仓库结构：`lib/`（host 半 ESM + `client.js` 浏览器半）、`skills/`（分层 skill）、`examples/`（示例应用）、`docs/`（设计文档——[MVP 设计](docs/mvp-design.md) · [回传契约](docs/callback-contract.md) · [决策记录](docs/decisions.md) · [路线图](docs/roadmap.md) · [SDK 侦查笔记](docs/sdk-notes.md)）。

## License

[MIT](LICENSE)