# Ziin Host Integration Pack

这个目录放的是最小宿主接入示例，可直接下载使用。

- `ziin-web-embed-demo.html`
  - 浏览器静态页面最小调用示例
- `ziin-node-client-demo.mjs`
  - Node.js 服务端调用 `query + feedback + ASR` 示例
- `ziin-media-client-demo.mjs`
  - 只演示媒体上传、发起 ASR、轮询结果
- `fixtures/Audio.mp3`
  - Node / Media 示例默认使用的音频样例
- `ziin-mini-program-demo.js`
  - 微信小程序调用示例
- `ziin-host-agent-demo.html`
  - 浏览器里直接演示宿主上下文编辑、真实 query、结构化返回、actionPlans payload 和验收动作信号
- `ziin-host-agent-demo.mjs`
  - 宿主已有智能体时的 Node.js 二次转述示例，已演示 `createHostAdapter(...)` 和 `createAcceptanceActionPlanAdapter(...)` 用法
- `/embed`
  - 官网里的宿主动作闭环演示页，可直接看到 `scroll_to / focus_field / open_dialog` 让页面发生变化

统一公网地址：

- Query: `https://ziin.shenliu.cc/api/ziin/query`
- Feedback: `https://ziin.shenliu.cc/api/ziin/feedback`
- Schema: `https://ziin.shenliu.cc/api/ziin/schema`
- Media Upload Token: `https://ziin.shenliu.cc/api/media/upload-token`
- Media Upload Complete: `https://ziin.shenliu.cc/api/media/upload-complete`
- ASR: `https://ziin.shenliu.cc/api/media/asr/transcribe`
- Task Query: `https://ziin.shenliu.cc/api/media/tasks/:taskId`

推荐起手顺序：

1. 先打开 `ziin-web-embed-demo.html`
   - 目标：确认公网 SDK、widget、query 和验收动作信号都能跑通
   - 重点看：能否挂载 widget、能否发问、日志里是否出现 acceptance 信号
2. 再打开 `ziin-host-agent-demo.html`
   - 目标：确认宿主已有 AI 时，如何消费 answer、steps、warnings、routing、actionPlans.payload
   - 重点看：结构化返回、payload 展示、点击 actionPlans 后的验收日志
3. 如果宿主是服务端代理，再看 `ziin-host-agent-demo.mjs` 或 `ziin-node-client-demo.mjs`
   - 目标：把浏览器示例里的逻辑迁到 BFF / 网关 / 服务端
4. 最后再把 `createAcceptanceActionPlanAdapter(...)` 换成你们自己的真实 handler
   - 目标：从“看懂协议”切到“真正驱动宿主页”

不要一上来就直接改 Node 示例或媒体示例。先把前两个浏览器示例跑通，能最快确认宿主理解的是不是同一套协议。

推荐接法：

- 如果宿主后端或 BFF 调用 Ziin，优先用 SDK 里的 `createHostAdapter(...)`
- 如果宿主是 Web 前端悬浮助手或内嵌页，优先用 `createHostRuntimeAdapter(...)`
- 如果宿主要直接挂一个产品化悬浮窗，直接用 `createZiinWidget(...)`
- 把公共字段沉到 adapter defaults 里：
  - `mode`
  - `softwareId`
  - `tenantId`
  - `userId`
  - 公共 `context`
- 每次请求只补当前问题、当前页面上下文差异和多模态输入
- `actionPlans` 必须由宿主按白名单执行，建议通过 `createActionPlanExecutor(...)` 统一收口
- 如果宿主要先做可见验收，优先直接用 `createAcceptanceActionPlanAdapter(...)`，它会把 `navigate / focus_field / fill_field / open_dialog / submit_draft / explain_permission`
  统一转成标准验收信号，客户可以先看懂动作协议，再换成自己的真实 handler
- widget 当前额外支持：
  - 宿主上下文条自动展示
  - 主题配置
  - 查询/动作事件回调
  - `openPanel()` / `refreshContext()` / `setContext()` 等显式控制方法

示例资源约定：

- `ziin-node-client-demo.mjs` 和 `ziin-media-client-demo.mjs` 默认读取 `fixtures/Audio.mp3`
- 两个 Node 示例默认请求 `http://127.0.0.1:3016`
- 适合先在本机已启动的 Ziin 服务上做交付回放
- 如果要切到公网或其他环境，执行前设置：
  - `export ZIIN_BASE_URL=https://ziin.shenliu.cc`
- 如果目标环境开启了 Key 校验，执行前设置：
  - `export ZIIN_API_TOKEN=your_api_token`
- 如果要换成你自己的音频，执行前设置：
  - `export ZIIN_AUDIO_FILE=/absolute/path/to/your/audio.mp3`

推荐本地回放顺序：

```bash
cd <ziin-repo>
npm run build
npm run start
node public/examples/ziin-node-client-demo.mjs
node public/examples/ziin-media-client-demo.mjs
```