用 Codex,开发你自己的智能体。
从角色与知识到完整页面和业务能力,在独立项目开发,由平台托管发布。一个智能体 ID,一条完整的交付路径。
01 · 开发路线与交付物
完整路径:创建智能体 → 授权 Codex → 配置角色与知识 → 独立开发页面 → 接入业务 → 上传预览 → 验收发布 → 持续更新。
- 客户管理员:注册工作空间,在后台创建智能体,取得租户 ID 和智能体 ID,签发开发凭证,确认上线范围。开发凭证不支持创建租户或签发更多凭证。
- Codex / 第三方开发者:在自己的目录开发,使用公共 API 配置智能体,构建静态 ZIP 并上传到平台。不导入平台内部源码,不需要内置 React 模板或云灵页面协议。
- 客户业务后端(按需):验证业务用户、提供业务 API,或换取平台签名身份。基础匿名咨询不需要客户后端。
- 平台:保管密钥、执行授权连接器、隔离租户与用户,在现有域名托管产物。正式入口始终是
/agent/{projectId},每个智能体独立发布。
交付包括独立项目源码、静态 ZIP、公开配置、预览地址、测试记录;发布后补充版本号和正式入口。ZIP 只包含静态文件,不运行 Node 服务、数据库、SSR 或自定义服务端脚本。
02 · 准备智能体与开发凭证
打开管理后台,创建或选择目标智能体,在「接入与 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:
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
复制以下任务,补充你的需求和授权范围。凭证通过环境变量提供,提示词中只写变量名。
请为我的 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 任务说明提供连接器和身份边界;API 契约提供精确路径、请求字段和限制。缺失业务接口文档时先完成无业务依赖的聊天页面,列出所需参数、认证、响应和测试账号,不能把模拟数据当作客户真实业务。
04 · 启动独立项目
下载最小项目 ZIP。项目包含当前 SDK、发布工具、无框架聊天示例、静态构建与本地服务,不依赖平台仓库或 npm 上的私有包。
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 调用:
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:常驻业务入口或模型按需展示的引导卡片;实际业务在客户页面执行。
配置与知识接口示例。自定义模型 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 方法与类型 · 运行 API 与 SSE。
07 · 用户身份与宿主上下文
基础咨询使用平台自动建立的随机访客连接,无需业务登录。官方宿主页负责匿名恢复凭证;SDK 不在沙箱中访问 Cookie 或 localStorage。公开的 userId 不能用于恢复另一用户历史。
宿主可以传任意可选 JSON data,不传时为空上下文,聊天仍正常。client.context() 读取当前会话上下文。完整 data 会提供给模板及智能体选定的 AI 服务,因此只传对话确实需要的数据,不放平台开发凭证或共享 API Key。
<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 实现。完整身份与恢复协议。
08 · 接入客户业务与连接器
先取得客户接口的 HTTPS 地址、方法、认证、输入 schema、响应说明、超时与错误约定,区分只读查询和有副作用的操作。平台不是任意 URL 代理,也不运行上传的后端代码。
- 环境变量保管共享凭证:通过
/variables创建 Secret,allowedHosts精确限制目标主机。页面不能读取值。 - 连接器描述调用:HTTP 使用
kind:service,MCP 使用kind:mcp;headers 或 POST 顶层requestValues用<NAME>引用 Secret,用<data.path>引用本次宿主上下文。实际 JSON 格式见连接器契约。 - 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 · 构建、预览、发布与回滚
在最小项目中执行:
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:
{
"enabled": true,
"artifactId": "替换为上传返回的artifactId",
"version": "v1.0.0",
"data": {"brand": "我的智能体"}
}
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}。每次更新重新构建、上传并使用新版本名,再预览、保存草稿和发布,无需重新部署平台或配置域名。
node scripts/frontend-release.mjs state
# RELEASE_ID 从 versions 选择;REVISION 使用刚读取的最新值。
node scripts/frontend-release.mjs restore RELEASE_ID "$REVISION"
409 表示有并发更新,重新读取并确认合并。上传超时先用 artifacts 核对是否已经成功,不能盲目重复创建。回滚只恢复前端代码和公开配置。精确发布 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:本页面同源内容,可交给 Codex 直接读取。
- 编程智能体任务说明:开发执行规范。
- 完整 API 参考:请求字段、限制、权限和协议。
- SDK README · 类型定义 · 发布工具 · 最小项目。
- 云灵客户接口 · 页面配置 · OpenAPI · PDF · 演示:已有云灵客户端的兼容资料,独立项目按自身业务选择参考。
所有示例须替换为你的目标 ID 与接口。文档描述当前仓库契约,目标服务器实际能力以部署版本和接口响应为准。第三方无需克隆平台仓库即可完成这条开发路径。