# 用你的编程智能体来定制页面

首次接入请先读[完整客户开发指南](https://agents.ipboxs.com/docs/customer-development.md)，下载[独立最小项目](https://agents.ipboxs.com/developers/runtime/agent-starter.zip)。本说明用于约束执行流程；精确请求字段以 API 契约为准。

将以下任务说明交给你的编程智能体，并提供目标智能体 ID、需求与设计参考。开发凭证和客户接口密钥通过本地密钥管理提供，不粘贴到提示词、仓库或前端文件中。

完整接口契约：[开发 Agent API 接入指南](https://agents.ipboxs.com/docs/runtime-api.md)。本文件对应仓库 `docs/agent-development.md`，接口指南源文件为 `docs/runtime-api.md`。本文对应 2026-11-08 智能体独立模型与服务端管理 API 版本，执行前核对目标服务器版本。

## 可复制的开发任务

请为指定 Woodenhorse 智能体定制并开发客服页面，使用平台公共 API 管理智能体和发布前端。

开始前读取开发 Agent API 接入指南，确认目标平台地址、projectId、已有配置及本次授权范围。使用本地环境中的 `WH_PLATFORM`、`WH_PROJECT`、`WH_DEVELOPER_TOKEN`；目标平台默认为 `https://agents.ipboxs.com`。projectId 就是现有智能体 ID，不另建租户或身份。先读取现有资源再增改，避免重复创建。

1. **确认权限。** 前端开发需要 read/develop，发布和回滚需要 publish；智能体、知识库、业务引导分别使用 agent、knowledge、actions 的读写权限。环境变量需要 variables:read / variables:write，连接器需要 connections:read / connections:write。权限独立，缺失返回 403 时列明缺少的权限，由管理员重新签发；不尝试用其他身份绕过。
2. **在独立目录开发。** 自选可输出静态文件的技术栈，根据需求实现布局、交互和响应式页面。使用公开 Runtime API 或 `@woodenhorse/runtime-client`，不导入平台 src、不要求内置 React 模板或云灵 page manifest。客户前端不需要自行托管或配置域名。
3. **配置客服内容。** 按需使用开发 API `/config`、`/knowledge`、`/actions` 管理角色模型、资料和业务引导。这些修改立即生效，不能假设它们随前端草稿隔离。
4. **统一管理接口。** 环境变量仅保管 agent 级的值；连接器管理接口地址、认证及用途。共享 Token、API Key、应用密钥存为 Secret，allowedHosts 精确授权实际目标主机，连接器使用 `<NAME>` 引用。宿主随会话提供的认证值保留在 data，并用 `<data.path>` 引用。不要另建一套页面认证配置。
5. **按调用场景选连接器。** 上下文和实时数据统一使用连接器：behavior=context 在打开对话框建立会话时获取一次，保存到当前 conversationId 的 session，后续复用，新会话重新获取，behavior=assistant 按需查询（默认）。两种行为都支持 MCP / HTTP。contextInput 为固定参数，默认 `{}`，启用前须满足所授权接口的参数定义；用户身份由平台传递，密钥继续用环境变量。context 仅允许 usage=assistant，每个智能体最多启用 3 个自动查询工具。 MCP 使用 kind=mcp，创建后发现工具、核对真实只读行为、逐项授权，再启用。非 MCP HTTP Service 的 context/assistant 均支持 method=GET/POST，GET 传查询参数，POST 传 JSON。必须说明用途、参数 inputSchema 和返回数据 responseDescription；assistant 行为的客服按需只读查询使用 usage=assistant，页面特殊登录等明确调用使用 usage=template，共用只读接口可用 both。维护旧固定业务或对话前上下文时使用 `/connectors/_service`、`/connectors/_context`，不重复接入同一功能。新会话初始化时启用 context 连接器后不再拉取旧 context_url（失败也不回退）；停用全部 context 连接器后新会话恢复旧协议，已有会话保留快照。context 配置变更从新会话生效。
6. **安全实现特殊接口。** 页面只能提交 schema 允许的用户输入。认证头引用写在 headers，需要应用密钥的 POST JSON 顶层字段写在 requestValues；由平台服务器展开变量。页面通过 `client.connector(connectorId, input)` 调用固定连接器，不能读取 Secret 或任意指定 URL、认证头。无需密钥的连接器 ID 可存公开前端 data。当前不支持任意脚本、动态 HMAC、嵌套服务端字段、表单编码或 OAuth 自动刷新；若上游要求这些能力，明确指出契约缺口。
7. **保持用户身份隔离。** 管理 API 使用 wh_dev_ 开发凭证；Runtime 使用平台连接 Bearer；可选签名身份独立配置。项目 API Key 留在客户后端；上游接口凭证留在平台变量中。SDK 默认使用平台自动建立的独立连接，业务登录结果不会自动成为平台身份。上游应核验平台认证并按可信身份头检查数据归属。
8. **联调并交付。** 验证消息流、停止、历史、记忆、语音入口及业务调用，检查桌面和手机、缺参数、失败提示与两用户数据隔离。使用测试账号和测试系统验证有副作用的接口，不自动重试业务提交。说明哪些验证使用夹具，哪些真实客户接口尚未联调。
9. **上传、预览、发布。** 本地构建并生成根目录含 index.html 的静态 ZIP，资源使用相对路径，不含 .env 或密钥。用 frontend API 上传，按返回的 artifactId 生成公开配置并预览；previewToken 只授予代码访问，运行联调使用 SDK 自动连接或可选测试用户 token。保存草稿和发布前读取当前 revision；409 后读取合并，创建超时后先核对是否成功。只有本次已授权发布时才显式执行 publish，否则交付预览和草稿。正式入口保持 `/agent/{projectId}`。

变量更新使用 expectedVersion；连接器、认证和前端使用各自的 revision，均取自对应读取结果。Secret 轮换立即生效；前端回滚仅恢复代码和公开 data，不恢复变量、连接器、知识库或已发生的业务操作。

交付时列出修改的智能体内容、变量名称（不含值）、连接器 ID / behavior / 用途、前端 artifactId / version、预览或正式入口、验证结果，以及尚缺的上游契约或权限。区分本地实现、服务器部署和真实客户联调状态。

## 模板、宿主上下文与连接器的分工

宿主自由传入可选 data，平台自动将完整 context 提供给 AI 和模板。没有 data 就正常聊天，不需要接入方额外实现登录。模板在官方入口中调用 `createRuntimeClient({baseURL,projectId})`、`client.bootstrap()` 即可，通过 `client.context()` 取得当前会话数据。原生或独立调用可显式传 data。平台不规定字段结构，也不硬编码 userId、酒店或客户接口的用途。

AI 按连接器定义自适应选择工具并匹配参数；连接器说明应准确描述参数、返回值和认证约定。宿主认证头可写为 `Bearer <data.authToken>`，POST requestValues 也可引用任意 data 路径；共享服务凭证仍引用 `<NAME>` 环境变量。仅当接口依赖平台签名身份时，才开启 requiresIdentity；默认 false。宿主凭证由实际客户接口验证，不自动成为平台身份。

重新进入调用 bootstrap，自动加载当前用户最近会话及消息，新的入口 data 更新当前会话 context，不因来源页面变化丢失历史。显式新建会话仍独立，其他历史会话保留各自 context。模板通过 `historyScope` 或 `historyScopePaths` 声明业务账号分组，官方宿主按项目、浏览器、scope 保存匿名恢复凭证（30天，可续接）；短期 Runtime token 为8小时，长效恢复凭证不交给模板或 AI。字段是分组线索，不是认证，不能凭公开 user 参数访问另一浏览器历史。没有 ID 时使用独立访客组并正常聊天。存储清除、凭证到期及跨设备恢复不由公开 ID 自动关联。新模板必须使用本次发布 SDK。宿主 data 可包含凭证，不写日志、公开示例默认值或长期记忆；完整 data 会发送给智能体选定的 AI 服务。

## SDK 与发布工具

平台分发框架无关 SDK：`/developers/runtime/index.mjs`、`index.d.ts`、`README.md`、`package.json`。可在本地组装包或使用平台提供的 npm pack 安装包。发布 CLI 为 `/developers/runtime/frontend-release.mjs`；下载后在本地运行，其环境变量同上，命令格式见接口指南。

旧 `chat-template-kit.zip` 仅用于维护平台内置源码模板，不是独立前端开发的必备包。

智能体可独立选择模型：通过 `agent:write` PATCH `/config` 的 `llm_base_url`、`llm_api_key` 和 `model`，使用兼容 OpenAI Chat Completions 的公网 HTTPS 服务。Key 只写不读，留空保留，改地址须同时提供新 Key。恢复平台模式用 `{llm_base_url:"",model:"平台支持的模型"}` 并删除原 Key。部署需配置服务端加密密钥环；不要把 Key 写入页面代码、ZIP、日志或公开配置。完整契约见 runtime-api.md 的配置小节。

智能体也可独立配置语音识别：`PATCH /config` 设置 `asr_ws_url`、`asr_model`、只写的 `asr_api_key`，覆盖系统 ASR 配置。URL 须为公网 WSS 443 完整地址，服务兼容 DashScope/FunASR WebSocket；不能使用普通 HTTP 转写接口。Key 加密且不读回，首次设置或更换 URL 必填，留空保留。设置 `asr_ws_url:""` 恢复平台默认并删除自定义配置。读取只返回 `asr_api_key_set` 状态；仍受平台语音总开关和租户额度约束，自定义失败不回退。模板继续使用原语音 API/SDK，无需持有上游 Key。
