# 客户 Agent 开发指南

从一个智能体 ID 出发，用 Codex 在独立项目开发自己的智能体。你决定角色、知识、业务能力和完整页面；Woodenhorse 提供模型调用、会话、历史、记忆、语音、连接器及前端托管。无需取得平台源码或自行部署客服网站。

## 01 · 开发路线与交付物

完整路径：创建智能体 → 授权 Codex → 配置角色与知识 → 独立开发页面 → 接入业务 → 上传预览 → 验收发布 → 持续更新。

- **客户管理员**：注册工作空间，在后台创建智能体，取得租户 ID 和智能体 ID，签发开发凭证，确认上线范围。开发凭证不支持创建租户或签发更多凭证。
- **Codex / 第三方开发者**：在自己的目录开发，使用公共 API 配置智能体，构建静态 ZIP 并上传到平台。不导入平台内部源码，不需要内置 React 模板或云灵页面协议。
- **客户业务后端（按需）**：验证业务用户、提供业务 API，或换取平台签名身份。基础匿名咨询不需要客户后端。
- **平台**：保管密钥、执行授权连接器、隔离租户与用户，在现有域名托管产物。正式入口始终是 `/agent/{projectId}`，每个智能体独立发布。

交付包括独立项目源码、静态 ZIP、公开配置、预览地址、测试记录；发布后补充版本号和正式入口。ZIP 只包含静态文件，不运行 Node 服务、数据库、SSR 或自定义服务端脚本。

## 02 · 准备智能体与开发凭证

打开[管理后台](/dashboard)，创建或选择目标智能体，在「接入与 API → 开发凭证」签发凭证。记录现有智能体 UUID 作为 `WH_PROJECT`；不要用租户 ID、企业目录 ID 或另建的业务 ID 替代。

按任务选择权限，读写权限分别授权：

- 页面读取、上传、预览与保存草稿：`read` + `develop`。
- 正式发布与恢复版本：额外授权 `publish`。
- 角色、欢迎语和模型：`agent:read` + `agent:write`。
- 知识库：`knowledge:read` + `knowledge:write`。
- 业务引导：`actions:read` + `actions:write`。
- 环境变量：`variables:read` + `variables:write`。
- 连接器：`connections:read` + `connections:write`。

凭证原文只在签发后显示一次，有效期 1–90 天；丢失、过期或权限不足时由管理员重新签发。开发凭证不能代替 Runtime 用户身份或项目 API Key。

在运行 Codex 的本地终端设置非敏感参数，开发凭证通过本地密钥管理注入 `WH_DEVELOPER_TOKEN`：

```sh
export WH_PLATFORM=https://agents.ipboxs.com
export WH_PROJECT=你的智能体UUID
# WH_DEVELOPER_TOKEN 由本地密钥管理注入，不写在这里。
node scripts/frontend-release.mjs state
```

上面的工具在第 04 节下载。`state` 成功代表可以读取此前端状态；其他资源权限仍需分别确认。不要把开发凭证放进提示词、浏览器代码、`VITE_*` / `NEXT_PUBLIC_*`、ZIP 或公开日志。客户只需要本地 Node.js 24+；不需要安装平台的 Go、PostgreSQL 或 Docker。

## 03 · 把任务交给 Codex

复制以下任务，补充你的需求和授权范围。凭证通过环境变量提供，提示词中只写变量名。

```text
请为我的 Woodenhorse 智能体开发独立项目。

先读取平台 /docs/customer-development.md、/docs/agent-development.md 和
/docs/runtime-api.md，再读取 /developers/runtime/README.md 与 index.d.ts。
平台地址从 WH_PLATFORM 读取，智能体 ID 从 WH_PROJECT 读取，
开发凭证从 WH_DEVELOPER_TOKEN 读取，绝不输出凭证或放入前端产物。

需求：[填写服务对象、角色、知识来源、设计参考、页面功能和业务接口]
工作目录：[填写独立项目目录]
本次授权：[仅开发与预览 / 允许修改智能体配置 / 允许正式发布，明确选择]

先读取已有资源及 revision，确认权限和接口契约，再开发。
从 /developers/runtime/agent-starter.zip 下载最小项目或自选静态技术栈。
不要导入平台源码，不要求内置模板，不新增运行域名。
基础咨询不依赖业务登录；业务接口通过连接器调用，Secret 留在服务端。
实现并验证流式消息、停止、历史、新会话、记忆、语音和失败提示；
按需实现业务卡片，验证桌面、手机和两用户隔离。
构建根目录含 index.html 的 ZIP，上传并创建预览。
先交付可验收预览；只有本次明确授权正式发布时才执行 publish。
报告变更、artifactId、版本、地址、验证结果与尚未联调的客户接口。
```

[详细 Codex 任务说明](/docs/agent-development.md)提供连接器和身份边界；[API 契约](/docs/runtime-api.md)提供精确路径、请求字段和限制。缺失业务接口文档时先完成无业务依赖的聊天页面，列出所需参数、认证、响应和测试账号，不能把模拟数据当作客户真实业务。

## 04 · 启动独立项目

[下载最小项目 ZIP](/developers/runtime/agent-starter.zip)。项目包含当前 SDK、发布工具、无框架聊天示例、静态构建与本地服务，不依赖平台仓库或 npm 上的私有包。

```sh
curl --fail --show-error --location \
  https://agents.ipboxs.com/developers/runtime/agent-starter.zip -o agent-starter.zip
unzip agent-starter.zip -d my-agent
cd my-agent
# 编辑 config.js，填入平台地址和已有智能体 UUID；这些是公开参数。
npm run dev
# 打开 http://127.0.0.1:4173
```

本地示例连接真实 Runtime，会产生模型用量；它不是模拟客服。独立运行的匿名连接仅在当前页面内存中，刷新后不保证恢复。跨刷新历史、预览沙箱和麦克风应在上传后的官方入口验收；本地服务不模拟宿主权限。

示例使用原生 HTML/CSS/JavaScript。你可以替换成 React、Vue、Svelte 或其他静态技术栈。SDK 已随项目放在 `runtime/`；无需从公共 npm 注册表安装 `@woodenhorse/runtime-client`。Vite 等构建工具必须设置相对资源基址 `./`，推荐 hash 路由。

最小 SDK 调用：

```js
import {createRuntimeClient} from './runtime/index.mjs';
const client = createRuntimeClient({
  baseURL: 'https://agents.ipboxs.com',
  projectId: '替换为智能体UUID'
});
const session = await client.bootstrap();
const controller = new AbortController();
for await (const event of client.send(session.conversationId, '你好', {
  signal: controller.signal
})) {
  if (event.type === 'delta') console.log(event.content);
}
// 停止按钮调用 controller.abort()，随后读取历史确认保存状态。
```

页面必须展示初始化、发送中、空状态、错误和重试状态。用 `textContent` 或经过安全处理的 Markdown 渲染模型内容。不能仅将 HTTP 200 当作生成成功：SSE 中也可能出现错误；SDK 会抛出 `RuntimeError`。不要自动重放消息。

## 05 · 定义角色、模型与知识

管理 API 根路径为 `$WH_PLATFORM/api/v1/developer/projects/$WH_PROJECT`，由本地 Codex 使用开发凭证调用。先 GET 当前资源，再按 API 白名单增改：

- `/config`：名称、角色提示词、欢迎语、模型等；可选配置专属 OpenAI Chat Completions 兼容模型服务与独立 ASR。
- `/knowledge`：业务说明、FAQ、规则等文本知识。支持 TXT / Markdown 内容，当前为关键词检索，不支持直接上传 PDF 解析。
- `/actions`：常驻业务入口或模型按需展示的引导卡片；实际业务在客户页面执行。

[配置与知识接口示例](/docs/runtime-api.md#智能体配置项目知识库与业务引导管理)。自定义模型 Key 和 ASR Key 只写不读；更换服务地址需同时提供新 Key，自定义服务失败不会自动换用平台 Key。模型和 ASR 独立配置，模板仍调用平台 SDK。

这些资源修改不随前端草稿隔离，会影响后续请求。已有生产智能体建议先另建测试智能体验证，再在授权范围内修改目标配置。前端回滚不会恢复角色、知识、密钥或连接器。

## 06 · 会话、历史、记忆与语音

- `client.bootstrap()`：获取公开配置、最近会话和消息；初始化完成后再允许发送。
- `client.send(id, text, {signal})`：逐条处理 `delta`、`saved`、`done`；停止时中止请求，随后用 `messages(id)` 核对服务端已保存内容，避免重复发送。
- `client.conversations()` / `client.messages(id)`：列出会话、选择历史并显示消息。历史消息中的卡片也应按需展示。
- `client.newConversation()`：创建独立会话；使用返回的 `conversation.id`。`deleteConversation(id, currentId)` 会删除对话，界面应先让用户确认；删除对话不清除长期记忆。
- `client.memory()`：读取记忆；修改或清除时使用读取到的 `revision`。409 时重新读取，不能覆盖其他窗口的更新。
- `client.voiceInput()`：在官方宿主页中请求录音转写，将 `{text}` 填入输入框由用户确认发送。提供取消、拒绝授权和不可用提示；本地独立页面没有官方语音宿主。
- `client.action(actionId, messageId)`：解析当前允许的业务跳转，动态卡片传入其来源消息 ID。用户点击后用 `<a target="_top">` 离开沙箱，不能让模型生成任意业务 URL。

最小下载项目仅演示启动、发送、停止和新会话；完整交付应补齐上述按需求需要的界面，并按第 10 节验收。[SDK 方法与类型](/developers/runtime/index.d.ts) · [运行 API 与 SSE](/docs/runtime-api.md#客服运行-api)。

## 07 · 用户身份与宿主上下文

基础咨询使用平台自动建立的随机访客连接，无需业务登录。官方宿主页负责匿名恢复凭证；SDK 不在沙箱中访问 Cookie 或 localStorage。公开的 `userId` 不能用于恢复另一用户历史。

宿主可以传任意可选 JSON `data`，不传时为空上下文，聊天仍正常。`client.context()` 读取当前会话上下文。完整 data 会提供给模板及智能体选定的 AI 服务，因此只传对话确实需要的数据，不放平台开发凭证或共享 API Key。

```html
<script src="https://agents.ipboxs.com/widget.js"
  data-tenant-id="替换为租户ID"
  data-project-uuid="替换为智能体UUID"
  data-data='{"page":"product","productId":"demo-product"}'
  async></script>
```

需要客户已登录用户跨设备延续历史时，由客户后端验证自身会话，再用项目 API Key 调用 `POST /api/v1/tokens`，提交 `tenantId`、`projectId` 和可信 `userId`，取得 15 分钟用户 token。通过 widget `data-token` 或 SDK 的 `getToken` 接入，项目 API Key 永远留在后端。

业务登录、data 中的账号和平台签名身份是独立概念；匿名与签名用户不自动合并。模板可用 `historyScope` / `historyScopePaths` 声明浏览器内账号分组，但分组字段不授予身份。签名 token 不持久化；跨设备能力不能通过公开业务 ID 实现。[完整身份与恢复协议](/docs/runtime-api.md#三类凭证不能混用)。

## 08 · 接入客户业务与连接器

先取得客户接口的 HTTPS 地址、方法、认证、输入 schema、响应说明、超时与错误约定，区分只读查询和有副作用的操作。平台不是任意 URL 代理，也不运行上传的后端代码。

- **环境变量**保管共享凭证：通过 `/variables` 创建 Secret，`allowedHosts` 精确限制目标主机。页面不能读取值。
- **连接器**描述调用：HTTP 使用 `kind:service`，MCP 使用 `kind:mcp`；headers 或 POST 顶层 `requestValues` 用 `<NAME>` 引用 Secret，用 `<data.path>` 引用本次宿主上下文。实际 JSON 格式见[连接器契约](/docs/runtime-api.md#connectors)。
- **AI 按需只读查询**：`behavior:assistant` + `usage:assistant`，填写准确用途、参数和返回值说明。
- **新会话上下文**：`behavior:context` + `usage:assistant`，用固定 `contextInput`，每智能体最多启用 3 个自动查询工具。会话初始化获取一次、后续复用，变更从新会话生效。
- **页面明确调用**：HTTP `usage:template`，或与 AI 共用只读接口使用 `both`；先 bootstrap，再 `client.connector(connectorId, input)`。只提交 schema 允许的用户输入。
- **MCP**：创建、发现工具、核对真实只读行为、逐项授权后再启用；不能把写入或破坏性工具授权给 AI 查询。

`requiresIdentity` 默认 false，仅当上游依赖平台签名身份时开启。上游必须验证它实际使用的认证和数据归属，不能信任浏览器传入的 userId。参数缺失或业务接口失败时，基础咨询仍可使用。

当前不支持任意脚本、动态 HMAC、嵌套服务端注入字段、表单编码或 OAuth 自动刷新。需要这些能力时先由客户后端适配。使用测试账号验证有副作用的调用，不自动重试提交；前端发布和回滚不能撤销真实业务操作。

## 09 · 构建、预览、发布与回滚

在最小项目中执行：

```sh
npm run build
# macOS / Linux 在 dist 内打包，避免多出 dist 目录层级。
(cd dist && zip -r ../dist.zip .)
node scripts/frontend-release.mjs upload ./dist.zip
```

ZIP 根目录必须有非空 `index.html`；不要包含 `.env`、凭证、`node_modules`、符号链接或隐藏文件。当前最多 1024 个条目，压缩和解压总量各 20 MiB；每智能体最多 100 个产物、200 MiB 解压内容。

使用上传返回的 `artifactId` 创建项目根目录 `frontend-config.json`，`data` 是公开前端配置，不是用户 context：

```json
{
  "enabled": true,
  "artifactId": "替换为上传返回的artifactId",
  "version": "v1.0.0",
  "data": {"brand": "我的智能体"}
}
```

```sh
node scripts/frontend-release.mjs preview ./frontend-config.json
node scripts/frontend-release.mjs state
# CURRENT_REVISION 使用最新 state 返回值；不是固定数字。
node scripts/frontend-release.mjs draft ./frontend-config.json "$CURRENT_REVISION"
# 验收通过且获得发布授权后，使用保存草稿返回的最新 revision。
node scripts/frontend-release.mjs publish "$DRAFT_REVISION"
```

打开 preview 返回的 URL，在官方沙箱验收。预览 15 分钟有效，是配置快照；只授予产物访问，SDK 另外建立访客或使用已授权测试身份。URL 含临时访问能力，不放入公开日志。过期后重新创建预览，不修改 URL 绕过。

发布后客户访问 `https://agents.ipboxs.com/agent/{projectId}`。每次更新重新构建、上传并使用新版本名，再预览、保存草稿和发布，无需重新部署平台或配置域名。

```sh
node scripts/frontend-release.mjs state
# RELEASE_ID 从 versions 选择；REVISION 使用刚读取的最新值。
node scripts/frontend-release.mjs restore RELEASE_ID "$REVISION"
```

409 表示有并发更新，重新读取并确认合并。上传超时先用 `artifacts` 核对是否已经成功，不能盲目重复创建。回滚只恢复前端代码和公开配置。[精确发布 API](/docs/runtime-api.md#发布-api)。

## 10 · 验收与交付清单

正式发布前逐项记录结果，区分本地测试、受控夹具和真实客户联调：

- 桌面与手机：布局可读、输入可用、键盘可操作，加载与错误有明确反馈。
- 对话：首次打开、流式输出、停止、失败后核对历史；不显示残缺回答为已保存成功。
- 会话：刷新重进、历史选择、新建、删除；长期记忆读写与 revision 冲突处理。
- 身份：两个独立浏览器用户、两个智能体之间无数据混用；匿名、签名身份、退出和换号行为符合约定。
- 语音：官方入口下授权、取消、转写失败、转写后确认；真实供应商未测时明确标注。
- 业务：缺参数、无权限、超时、上游错误、卡片跳转与认证；真实客户未联调的项目单独列出。
- 发布：预览与正式入口一致，检查相对资源加载；恢复上一版本后仍可使用。
- 安全：ZIP、前端公开 data、源码和日志无开发凭证或共享密钥。

交付记录至少包含：智能体 ID、源码位置、构建命令、artifactId、版本、预览或正式入口、修改过的内容资源、变量名称（无值）、连接器 ID / 用途、验证结果、未完成事项及上一可恢复版本。只拿到预览不代表已正式上线。

## 11 · 常见问题与能力边界

- **401**：检查凭证类型、期限和目标智能体。开发凭证只用于管理 API，Runtime 使用用户或访客 token；不要互换。
- **403**：检查具体缺少的权限、连接器用途、签名身份要求或来源策略。由管理员授权，不借其他身份绕过。
- **404**：核对 ID 与目标服务器部署版本。仅本地实现的能力不能假定线上已经提供。
- **409**：重新读取对应资源的 revision / expectedVersion，合并后重试；不能把前端 revision 用在变量上。
- **413 / ZIP 被拒绝**：检查容量、根目录 index.html、隐藏文件、路径和条目数，重新构建上传。
- **429**：展示限流提示并等待，不切换用户绕过配额。
- **页面空白 / 资源 404**：检查构建基址为 `./`，ZIP 没有多包一层目录；先检查浏览器控制台，再创建新预览。
- **本地正常，托管失败**：沙箱无同源存储和后台 Cookie 权限，不支持 Service Worker 或脚本弹窗。使用 SDK 和用户点击的 `_top` 链接，麦克风交给宿主页。
- **语音不可用**：确认官方宿主、浏览器授权、平台语音开关、ASR 配置与额度，不能把本地无宿主误判为平台故障。
- **连接器无数据**：核对启用状态、usage、behavior、inputSchema、目标主机授权、变量引用和客户接口实际认证；context 修改后建立新会话。

向平台反馈时提供时间、智能体 ID、接口路径、状态码和脱敏后的复现步骤；不要提交 token、请求认证头、完整用户 context 或客户隐私数据。

## 12 · 文档与兼容客户端

- [完整客户指南 Markdown](/docs/customer-development.md)：本页面同源内容，可交给 Codex 直接读取。
- [编程智能体任务说明](/docs/agent-development.md)：开发执行规范。
- [完整 API 参考](/docs/runtime-api.md)：请求字段、限制、权限和协议。
- [SDK README](/developers/runtime/README.md) · [类型定义](/developers/runtime/index.d.ts) · [发布工具](/developers/runtime/frontend-release.mjs) · [最小项目](/developers/runtime/agent-starter.zip)。
- [云灵客户接口](/docs/yunling/customer-api.md) · [页面配置](/docs/yunling/page-config.md) · [OpenAPI](/docs/yunling/openapi.json) · [PDF](/docs/yunling/customer-development-guide.pdf) · [演示](/demo/yunling)：已有云灵客户端的兼容资料，独立项目按自身业务选择参考。

所有示例须替换为你的目标 ID 与接口。文档描述当前仓库契约，目标服务器实际能力以部署版本和接口响应为准。第三方无需克隆平台仓库即可完成这条开发路径。
