先让 Ziin 知道你在哪、你能做什么、你卡在哪里，再谈它像不像智能体。
- 语音和 UI 不是最核心的差异点。
- 页面理解、权限边界和动作协议才是关键分水岭。
- 宿主不给上下文，回答再流畅也还是容易空。
Host Guide
宿主接入标准清单
这页是给宿主技术负责人和实施同学看的。目标不是讲产品愿景，而是说明接入时最少要给什么、补什么最值钱、做到什么程度才算真的开始像智能体。
Checklist
最小字段清单
先把对效果最敏感的字段说清楚，避免宿主接入时靠猜。必须给
softwareId、tenantId、userId、question、route。没有这几项，Ziin 只能退化成泛化问答。
强烈建议给
pageTitle、selectedMenu、platform、pageId、roleCodes、permissionCodes。
排错场景建议给
errors、formState、workflowNode、recordId。这样才能知道用户到底卡在哪一步。
往智能体升级建议给
availableActions，例如 open_page、focus_field、open_dialog、submit_draft。
Progression
宿主能力分级
接入不是二元状态，而是从说明书型逐步走到可执行助手型。L1 说明书型
只有 question，最多加 route。能回答一些问题，但更像会说话的帮助中心。
L2 基础上下文型
带 route、pageTitle、selectedMenu、platform，开始知道用户当前在哪一页。
L3 页面理解型
再加 pageId、recordId、workflowNode、errors、formState，开始能判断当前卡点。
L4 可执行助手型
再加 availableActions，宿主支持跳转、定位、聚焦字段等动作协议。
L5 持续优化型
知识、反馈、命中率、版本变更和宿主评估形成持续闭环，而不是一次性接入。
Payload
推荐的 Query 上下文示例
这里不是理论字段表，而是一条宿主真正可以照着发的请求体。{
"question": "为什么这个页面提交失败？",
"mode": "embedded-agent",
"softwareId": "erp-suite",
"tenantId": "tenant-east-cn",
"userId": "u-1001",
"module": "inventory",
"context": {
"route": "/inventory/inbound/create",
"pageTitle": "新建入库单",
"selectedMenu": "仓储中心 / 入库管理",
"platform": "web",
"pageId": "inventory_inbound_create",
"recordId": "IN-20260417-001",
"roleCodes": ["warehouse_clerk"],
"permissionCodes": ["inventory.write"],
"workflowNode": "draft",
"errors": [
{ "code": "REQUIRED_FIELD", "field": "warehouseId", "message": "仓库不能为空" }
],
"formState": {
"supplierId": "SUP-01",
"lineCount": 2
},
"availableActions": ["open_page", "focus_field", "open_dialog"]
}
}Delivery
宿主应该准备的资料
不是只给一个 API Key 就能接好，宿主还需要把真实系统知识和边界准备出来。- 菜单树与页面路由清单
- 角色与权限码映射
- 试点模块操作手册 / SOP / FAQ
- 常见错误和排错说明
- Token 或 query 上下文字段说明
- 版本变更时的知识更新负责人
Improve
怎么把效果提上去
这条路线更务实：先让它答得贴近当前页面，再让它逐步能帮你动手。第一步：先跑通
先用一个试点模块把 query 跑通，不要一上来覆盖全系统。
第二步：补真实上下文
优先补 route、pageId、permissionCodes、errors、formState，不要先纠结 UI。
第三步：接反馈闭环
把 useful / not_useful 和未解决问题回流接上，否则无法判断是不是真的好用。
第四步：补动作协议
让助手不止会解释，还能打开页面、定位字段、打开弹窗、提交草稿等，但必须由宿主前端按白名单执行。
第五步：接连续陪跑
围绕同一个 recordId 继承 route、pageId、workflowNode，让后续追问不用每次重新说明上下文。