# 用你的编程智能体来定制页面：开发 Agent API 接入指南

范围与验收边界见仓库 `docs/platform-delivery.md`，线上部署以发布记录为准。接口前缀 v1。`projectId` 就是现有智能体 ID，不创建另一套租户或智能体身份。

本指南覆盖智能体配置、环境变量、MCP / HTTP Service 连接器以及独立客服前端的开发与发布，对应 2026-11-06 连接器发布版本。目标服务器的实际能力以部署版本与接口响应为准。

页面 JavaScript 可以编排已配置连接器的调用；读取共享密钥、动态签名及服务端 Token 交换需在服务器执行。当前支持认证头和 POST JSON 参数的变量展开，尚不支持上传自定义服务端 JavaScript 执行多步认证。

可直接交给编程智能体的任务说明：[开发任务提示词](https://getwoodenhorse.com/docs/agent-development.md)（仓库源文件：`docs/agent-development.md`）。接口索引：[客服运行 API](#客服运行-api) · [前端发布 API](#发布-api) · [配置、知识库和业务引导](#智能体配置项目知识库与业务引导管理) · [环境变量](#agent-credentials) · [连接器与模板调用](#connectors)。

## 从配置到发布的工作流程

### 1. 准备开发凭证和独立项目

管理员为目标智能体签发 `wh_dev_…` 开发凭证，按任务明确授权。读写权限独立，写权限不隐含读权限。

| 开发任务 | 所需权限 |
| --- | --- |
| 查询前端状态、上传产物、预览和保存草稿 | `read`、`develop` |
| 发布或恢复前端版本 | `read`、`publish` |
| 读取和修改智能体名称、欢迎语、模型、提示词 | `agent:read`、`agent:write` |
| 管理知识库 | `knowledge:read`、`knowledge:write` |
| 管理业务引导 | `actions:read`、`actions:write` |
| 创建、轮换及核对 agent 级环境变量 | `variables:read`、`variables:write` |
| 管理连接器、认证配置、MCP 工具发现及授权 | `connections:read`、`connections:write` |

在本地设置 `WH_PLATFORM=https://getwoodenhorse.com`、`WH_PROJECT=目标智能体UUID`；`WH_DEVELOPER_TOKEN` 由密钥管理注入。所有管理请求发往 `$WH_PLATFORM/api/v1/developer/projects/$WH_PROJECT`，不附后台 Cookie。缺少权限返回 403，应由管理员重新签发具备相应权限的凭证，不改用用户 token。

页面代码放在独立项目或目录，自选静态前端技术栈，使用公开 Runtime API / SDK。无需修改平台仓库、注册内置 React 模板或实现云灵 page manifest。SDK 文件和本地发布 CLI 分发于 `/developers/runtime/`，也可由平台提供 `npm pack` 生成的 SDK 安装包。

### 2. 配置智能体内容、变量和连接器

先 GET 当前配置及资源列表，确认已有资源后再创建或修改。`/config` 管角色与模型，`/knowledge` 管资料，`/actions` 管业务跳转。接口接入只使用两个配置入口：**环境变量保管值，连接器描述如何调用**。

| 场景 | 配置方式 | 调用方 |
| --- | --- | --- |
| 标准 MCP 查询 | `kind:"mcp"`；创建 → 发现工具 → 逐项授权只读工具 → 启用 | 客服按需查询 |
| 会话开始时获取用户/业务上下文 | `behavior:"context"`；MCP 或 HTTP 均可，固定参数用 contextInput | 打开对话框建立会话时读取一次 |
| 非 MCP HTTP 查询 | `kind:"service", behavior:"assistant", usage:"assistant"`；填写用途、参数 schema 和返回数据说明 | 客服按需查询 |
| 定制页面的特殊登录等接口 | `kind:"service", usage:"template"`；用户输入放 inputSchema，应用密钥引用放 headers 或 POST requestValues | 页面明确调用 |
| 客服和页面共用只读接口 | `kind:"service", usage:"both"` | 客服及页面 |
| 维护已有固定页面业务或对话前上下文 | `/connectors/_service`、`/connectors/_context` 及其认证子路径 | 原协议兼容执行 |

先通过 `POST /variables` 保存 Secret，并用 `allowedHosts` 授权确切目标主机；再在连接器中用 `<NAME>` 引用。认证头支持拼接、Bearer、Basic Base64，特殊 POST JSON 接口可用 `requestValues` 注入服务端字段。所有展开由平台服务器完成，页面不能读取环境变量原文。新接口无需再配置一份旧「认证请求头」或 context_url；会话初始化时若启用了 context 连接器，该会话复用快照、不再拉取旧 context_url；否则保留旧上下文协议。

管理脚本创建变量示例（Node.js ES Module；先 GET `/variables` 核对是否已存在；密钥通过本地环境注入）：

```js
const {WH_PLATFORM, WH_PROJECT, WH_DEVELOPER_TOKEN, CUSTOMER_API_TOKEN} = process.env;
if (!WH_PLATFORM || !WH_PROJECT || !WH_DEVELOPER_TOKEN || !CUSTOMER_API_TOKEN) {
  throw new Error('缺少平台地址、智能体 ID、开发凭证或客户接口密钥');
}
const response = await fetch(`${WH_PLATFORM}/api/v1/developer/projects/${encodeURIComponent(WH_PROJECT)}/variables`, {
  method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30000),
  headers: {Authorization: `Bearer ${WH_DEVELOPER_TOKEN}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'API_TOKEN', type: 'secret', value: CUSTOMER_API_TOKEN,
    description: '客户业务接口凭证', allowedHosts: ['api.customer.com']})
});
if (!response.ok) throw new Error(`变量创建失败：HTTP ${response.status}`);
const variable = await response.json(); // 仅返回 Secret 元信息；不要记录请求体或密钥。
```

将示例主机替换为实际接口主机，且与连接器 URL 一致。完整 MCP / HTTP JSON 配置及修订流程见[连接器管理](#connectors)。变量修改使用 `expectedVersion`，连接器与前端修改使用各自当前 `revision`；不能混用或硬编码。409 后重新读取并合并，POST 超时后先查询是否已创建，避免重复资源。

### 3. 开发并联调页面

页面用 `createRuntimeClient` 接入会话、消息、记忆、语音和业务入口。需要页面调用的 HTTP Service，通过 `client.connectors()` 获取开放能力，以 `client.connector(connectorId, input)` 调用固定连接器；不提交 URL、认证头或变量名。连接器 ID 可放在前端公开 `data` 配置中，密钥不能放入其中。

Runtime 使用客户后端签发的短期用户 Bearer，或下文的平台正式访客凭证，不能用 `wh_dev_…`。应用身份是增强信息，普通咨询可使用匿名会话；个人业务仍按各接口的身份要求校验。业务登录返回的 accessToken 不自动成为平台用户身份，已验证身份签发仍由客户后端负责。用两个独立用户/访客验证数据隔离、缺参数和失败状态，并检查桌面/手机布局、流式停止及历史恢复。

### 4. 构建、预览和发布

本地构建静态文件，ZIP 根目录包含 index.html，资源路径使用相对路径。通过 frontend API 上传产物，使用返回的 artifactId 生成配置并创建预览；预览凭证只授予代码访问，真实 Runtime 联调另需测试用户 token。验证后读取最新前端 revision，保存草稿，按用户授权显式发布。稳定入口始终为 `/agent/{projectId}`，无需客户自建网站或域名。

智能体内容、变量及 assistant 连接器修改从后续请求生效，context 连接器配置在新会话生效；前端代码和公开 data 则走草稿/发布。恢复前端历史版本不会恢复旧密钥、旧连接器或旧知识内容。联调有业务副作用的模板接口时使用测试系统和测试账号。

## 接入方式

客户 App / 小程序保留自己的业务页面。引入平台 widget，或在 WebView 打开平台官方入口 `/agent/{projectId}`；平台按 ID 选择已发布皮肤、设置和用户上下文。没有自定义皮肤时使用原有客服。客户不部署客服网站、不配置域名。

开发 Agent 在独立目录开发完整的客服 HTML/CSS/JavaScript，使用本指南中的 API 或 `@woodenhorse/runtime-client`。本地构建 ZIP → 上传 → 预览 → 保存草稿 → 发布。上传检查文件结构及配额，不校验设计风格。支持任何能输出静态文件的技术栈；服务器渲染、数据库、Node 服务不装入 ZIP。

## 三类凭证不能混用

| 凭证 | 保存位置 | 权限 |
| --- | --- | --- |
| 项目 API Key | 客户后端 | 为当前登录用户申请短期身份凭证 |
| 用户 Bearer token | 当前页面内存 | 当前租户、智能体、用户的客服数据，15 分钟有效 |
| 项目开发凭证 `wh_dev_…` | 本地 Agent 的环境变量/密钥存储 | 按授权管理页面产物、智能体配置、知识库、业务引导、环境变量和连接器；不能冒充客户用户 |

客户接口 Token / API Key 是另一类上游凭证：存为目标智能体的 Secret 环境变量，由平台在连接器出站时使用，不发给模板或模型。它不代替上述平台凭证。

客户后端调用 `POST /api/v1/tokens`，请求头 `Authorization: Bearer <项目 API Key>`，JSON：

```json
{"tenantId":"TENANT_UUID","projectId":"PROJECT_UUID","userId":"customer_user_123"}
```

返回 `{token, expiresAt}`。客户后端必须从已登录会话推导 userId，不能相信浏览器任意传来的 userId。开发凭证、预览链接均不能代替用户身份。

H5 嵌入只需租户和项目。`data-data` 是可选的任意 JSON，没有固定业务字段，不传也正常聊天：

```html
<script src="https://getwoodenhorse.com/widget.js"
  data-tenant-id="TENANT_UUID"
  data-project-uuid="PROJECT_UUID"
  data-data='{"userId":"customer-123","authToken":"HOST_TOKEN","source":{"page":"/products"}}'
  data-label="咨询客服"></script>
```

`data-user-id` 不再作为 widget 接入参数；用户标识按宿主需要放进 data。平台签名身份仍可单独通过 `data-token` 交入，但它不是使用宿主 data 或基础客服的前提。宿主 auth token 与平台 Bearer 是不同凭证。

托管模板可用入口 query `voice=true` 选择显示语音输入。widget 设置 `data-chat-voice="true"` 时，会在其统一客服跳转地址、嵌入页面及新窗口链接中传递 `voice=true`；缺省及其他值不传。不自动读取宿主页面的 query，不把此开关混入业务 data 或历史分区。该参数控制模板的语音输入入口，不等同于 `data-voice` 的悬浮按钮录音模式；模板仍需检查 Runtime 语音可用状态。直接 WebView 链接已有 query 时追加 `&voice=true`，没有 query 时使用 `?voice=true`，均放在 `#` 之前；对完整目标 URL 做编码时，应先把此参数加入目标 URL，再编码。


widget 是悬浮入口。正式链接仍按智能体 ID 打开，不把构建版本写死在客户 App 中。原生 App / 小程序可用悬浮按钮打开 `https://getwoodenhorse.com/agent/PROJECT_UUID?user=customer_user_123#token=SHORT_LIVED_USER_TOKEN`；需配置平台页面的 WebView 业务域名，具体宿主白名单由该宿主完成。token 只在 fragment 中传递，页面读取后应从地址栏清除，不放 query、日志或持久存储。到期由客户宿主重新申请并重新进入；长会话自动续签/宿主消息桥尚不属于当前 SDK，不能声称已提供。

## 客服运行 API

根路径 `/api/v1/projects/{projectId}/runtime/`。除 `visitor` 首次获取会话外，每次请求使用 `Authorization: Bearer <用户或访客 token>`，JSON 请求携带 `Content-Type: application/json`。浏览器使用 `credentials: omit`；API 不依赖第三方 Cookie。允许平台宿主页及已授权浏览器沙箱的 Origin: null；null 不是可信身份，实际请求仍验证签名身份或服务端签发的匿名 capability。其他智能体 ID、用户 ID 或会话 ID 不能借换路径访问。

`POST visitor` 接受 `{}` 新建随机匿名用户，或 `{resumeToken}` 凭已有恢复凭证续接同一用户，均不携带 Authorization。返回 HTTP 201 `{token,expiresAt,identityMode:"anonymous",resumeToken,resumeExpiresAt}`；短期 token 有效8小时，恢复凭证有效30天并在续接时延长，只保存摘要。恢复凭证仅用于 visitor，不能充当 Runtime Bearer；跨项目、过期或无效凭证返回401。可用尚有效的旧访客 token 换取恢复凭证；同源可信宿主还可凭已有效的旧匿名 Cookie 迁移，不能仅凭 user 字段恢复他人历史。SDK 为 `client.createVisitor()`。官方宿主页在本浏览器 localStorage 按项目和模板指定的历史 scope 保管访客连接，恢复凭证不交给模板或 AI；签名 token 与 preview 不持久化。模板可传 `historyScope` 或 `historyScopePaths` 指定账号分组，业务字段本身不授予身份。不指定时使用本浏览器的独立访客组。来源、项目限流及沙箱校验继续保留。无 ID 可正常聊天、语音、管理自己的记录及调用 `requiresIdentity:false` 的连接器；匿名和签名用户历史不自动合并。

模板应优先使用应用传来的有效用户凭证；未提供时直接建立访客会话，初始化收到401时可以在明确切换为独立访客后重新读取初始化数据。不要因应用身份或可选业务资料不可用而禁用基础咨询。403/429/服务故障不作身份失败绕过，不自动重放用户消息或业务提交；平台或模型自身不可用仍需如实显示可重试状态。

| 路径 | 方法 | 请求 / 结果 |
| --- | --- | --- |
| config | GET | `{apiVersion, frontend:{artifactId,version,data,…}, voice}`；data 是客户自定义公开设置 |
| bootstrap | POST | `{data?: 任意 JSON}` → `context`、`timeContext` 及智能体公开信息、当前用户、会话、消息、导航入口、语音能力 |
| visitor | POST | `{}` 或 `{resumeToken}` → 新建或恢复匿名会话；后续请求仍需短期 Bearer |
| messages | POST | `{conversationId,message}` → SSE，按顺序处理 delta、saved、done；错误事件不可当作成功 |
| conversations | GET | 会话列表；可带 `?conversationId=…` 读取自己的历史 |
| conversations | POST | `{data?: 任意 JSON}` → `{conversation}` |
| conversations | DELETE | `{conversationId,currentConversationId?}` |
| memory | GET / PATCH / DELETE | 读取记忆；修改/清除携带当前 revision，冲突返回 409 |
| service | GET | 已发布的业务内容与能力 |
| service | POST | `{operation,input,key}`；业务操作契约沿用 `docs/yunling/customer-api.md`，并非要求使用云灵页面 |
| connectors | GET | `{connectors:[{id,name,description,inputSchema,responseDescription}]}`，仅已启用的 template/both HTTP Service |
| connectors | POST | `{connectorId,input:{…},conversationId?}` → `{data:…上游 JSON}`；详见[模板调用](#定制模板引用变量服务端请求参数) |
| action | POST | `{actionId,messageId?}` → `{url}`；动态卡片须传其来源消息 ID |
| audio | POST | 原始 PCM；`audio/pcm;rate=16000;channels=1;format=s16le` → 转写结果 |

`bootstrap.timeContext` 是平台服务器提供的当前时间，包含 `now`（带时区偏移的 RFC3339）、`date`（YYYY-MM-DD）、`weekday`、`timeZone`（IANA）、`weekStart` 和 `nextWeekStart`（周一的日期）。使用项目已发布业务设置的 `timeZone`，未设置时默认 `Asia/Shanghai`。它与任意宿主 `context` 独立，不写入用户资料或历史。平台每轮消息重新取时，同一轮查询规划与最终回答使用同一份时间基准，用于换算“明天”“下周五”等相对日期；模板无需注入时间或修改宿主 data。

任意布局、样式、路由由模板代码负责；不能假定通用运行接口会发出云灵页面组件指令。`bootstrap.appearance` 为旧客户端兼容字段，不是必须实现的协议。通用 API 没有在线编辑器，也不提供任意后端代码执行。

使用 `packages/runtime-client` 的 `npm pack` 产物即可在独立项目安装 SDK，无需导入 Woodenhorse 的 src。调用 `createRuntimeClient({baseURL,projectId,data?,historyScope?,historyScopePaths?,getToken?,previewToken?})`；baseURL 应固定为部署时确认的平台地址，不能无校验地信任任意 URL 参数。默认通过可信宿主页获得连接和 context，独立运行时自动建立访客连接；显式传 getToken 时每次请求调用它。取消生成使用 AbortController；不自动重放消息或业务提交，连接中断后先读取历史确认保存状态。在官方入口内调用 `await client.voiceInput({signal})`，平台宿主页显示录音确认、采集麦克风并调用平台 PCM 转写，返回 `{text}`；模板将文字放入输入框供确认，不能自动发送。沙箱内不能直接调用 getUserMedia。客户 App 原生录音可使用 `client.transcribe(pcm)`。

官方发布入口支持可选的**当前标签页重连信息**：模板向固定平台 origin 发送 `postMessage({type:"woodenhorse:entry:save",id,fragment})`。仅当前沙箱 iframe 的 `Origin:null` 消息可用；宿主页以 `{type:"woodenhorse:entry:saved",id,error?}` 回应，模板必须核对父窗口、平台 origin 与 id。fragment 最多 4096 字符，不允许 `token` 或 `preview` 参数；空值清除。宿主页按 projectId 存入 sessionStorage，8 小时到期，不跨标签页或项目共享；preview 禁用，存储不可用时返回错误。刷新且未携带新 fragment 时，恢复数据仅转交本项目的沙箱；显式新 fragment 优先并清除旧数据。

此能力只保留接入方明确提供的恢复参数，不签发或证明身份，也不替代客户登录。允许公开演示的客户服务可以使用随机测试 capability 恢复测试会话，再由客户后端换取短期平台 token；不得把 query 中的 user 当作登录依据。真实客户应另行设计并授权其恢复方式。平台用户 token 仍只保留内存；自动续签由客户的 getToken 实现，不是 SDK 自动提供。模板应处理宿主页不支持或浏览器禁用存储的情况；不得因此自动重放消息或业务提交。


### 对话中的查询结果卡片

支持自定义列表卡片的客户端可对 `POST runtime/messages` 显式传入 `queryCards: true`，SDK 对应 `client.send(conversationId, message, {queryCards: true, signal})`。默认关闭，旧客户端继续使用原有 action/service 卡片。可同时传入 `supportedActionIds: ["已配置动作 ID"]`（最多 100 项）声明此客户端支持的旧动作子集；省略保持原行为，空数组关闭旧动作。平台与模型只使用当前项目已配置且在该数组中的动作，未知 ID 不增加任何权限。独立前端可借此保留订单/售后等入口，同时将旧的通用选购入口替换为查询结果卡片。

平台按需查询成功后提供 `show_query_cards` 给回复模型。模型选择本轮查询的 `queryId` 和相对于 `result.data` 的列表项 JSON Pointer（例如 `/products/0`），同时填写 `summary` 给出面向用户的选择结论、依据与限制；该说明属于回复正文，不写入业务快照。只返回卡片时平台使用经过来源校验的说明，简短等待承诺会进行一次有界答复补全。模型不能提交商品名称、价格、链接或其他替代数据。服务端验证来源、路径和体积，最多返回六个对象列表项；失败、上下文连接器及其他用户/项目的数据不能作为来源。查询不执行订单、付款或其他写入。选购查询缺少必填条件时，规划器可针对已授权查询的必填字段返回有界的对话追问；平台直接保存该问题，不查询、不生成卡片，待用户补齐后继续。

`saved.cards[]` 及历史消息中的结果卡片含 `queryResult: {connectorId, queriedAt, input, data}`，`data` 是已脱敏查询列表项的原始快照，`input` 是本次经过参数校验的查询条件。快照随消息保存，恢复历史时无需重放业务查询。客户端只渲染自己支持的连接器格式，使用固定可信业务域名与经过校验的业务 ID 构造购买入口；不可使用模型猜测的 URL。历史价格与可用状态不是库存承诺，以客户业务页面为准。此协议不提供小程序原生路由，原生桥或业务登录由客户宿主负责。

## 发布 API

管理员可以在后台「接入与 API → 开发凭证」签发和管理：先选择智能体，填写凭证名称、权限和 1–90 天有效期。默认仅授予 read / develop，允许直接发布时再勾选 publish。原文仅签发后显示一次；列表显示名称、权限、到期时间，可提前撤销，遗失后重新签发。编程智能体使用环境变量 `WH_DEVELOPER_TOKEN`，不要放入模板或代码仓库。这与用于签发用户身份的「项目 API Key」不同。

也可通过 API 管理：管理员用原有登录会话调用 `POST /api/projects/{projectId}/frontend/credentials`，同源 JSON：

```json
{"name":"供应商开发 Agent","scopes":["read","develop"],"expiresInDays":7}
```

返回开发凭证（仅此次返回明文）。有效期 1–90 天；`GET` 同路径列出元数据，`DELETE` 同路径传 `{id}` 撤销。建议将 publish 授予负责验收发布的 Agent，开发凭证不能再签发开发凭证。

本地 Agent 使用 `Authorization: Bearer <开发凭证>`。根路径：
`/api/v1/developer/projects/{projectId}/frontend`。这些接口供本地 CLI / 服务端调用，不提供浏览器跨域访问或 Cookie 身份回退。

| 路径 | 方法 | 权限 | 内容 |
| --- | --- | --- | --- |
| 根路径 | GET | read | draft、published、revision、versions |
| /artifacts | POST | develop | `application/zip` 原始请求体，返回 artifactId、sha256、sizeBytes、fileCount、entryURL |
| /artifacts | GET | read | 产物元数据 |
| /preview | POST | develop | `{config}` → url、previewToken、expiresIn=900 |
| /draft | PUT | develop | `{revision,config}` |
| /publish | POST | publish | `{revision}`，原子切换当前皮肤 |
| /restore | POST | publish | `{revision,versionId}`，恢复 versions 中的历史发布 |

config 最小示例：

```json
{"enabled":true,"artifactId":"UPLOAD_RESULT_ID","version":"v1.0.0","data":{"brand":"云顶","layout":"custom"}}
```

entryURL、allowedOrigins 由平台生成，不接受外部网站注册。所有智能体共用运行地址，产物通过路径区分；这些内部地址不需要客户填写。data 是公开配置，不能放密码或 API Key。同一已发布 version 不能对应另一份代码或配置；新修改需新版本名。revision 不匹配返回 409，先读取再人工/Agent 判断冲突，不盲目覆盖。

预览分享 URL 同样使用 `/agent/{projectId}?previewArtifact={artifactId}`，只有明确指定预览产物时使用预览快照；默认入口、widget、小程序/H5 和后台「预览对话」都解析当前已发布版本。`/preview/{id}` 仅是后台身份换取助手，不是另一套模板渲染器。内置 appearance 草稿仅在未启用托管模板时生效。旧构建 `__preview` 入口兼容跳转到智能体入口。预览分享 URL 将 capability 放在 fragment，可信宿主页读取后清除地址栏 fragment，再用 `/builds/{id}/__preview/{capability}/` 加载沙箱内的相对静态资源；模板读取 fragment 中的 preview 传给 SDK 的 previewToken。此路径能力仅授予 15 分钟源码访问权，不含用户身份，不能公开记录或转发，平台不设置预览 Cookie。若自行开启代理访问日志，须脱敏该路径；Referrer-Policy 始终为 no-referrer。预览配置是创建时快照，15 分钟过期。若需联调真实运行 API，还要由客户后端获取测试用户 token，追加到 fragment；不会给预览者赋予任意客户身份。预览使用同一业务服务，测试用户也可能触发已启用的真实操作，应在测试智能体/demo 模式联调。

本地调用工具示例：

```sh
export WH_PLATFORM=https://getwoodenhorse.com
export WH_PROJECT=PROJECT_UUID
# WH_DEVELOPER_TOKEN 由密钥管理注入，不写进仓库或上传产物
node scripts/frontend-release.mjs upload ./dist.zip
node scripts/frontend-release.mjs state
node scripts/frontend-release.mjs preview ./frontend-config.json
# 以下修订号取自每一步最新响应；不要假定为 0、1、2。
node scripts/frontend-release.mjs draft ./frontend-config.json "$CURRENT_REVISION"
node scripts/frontend-release.mjs publish "$DRAFT_REVISION"
node scripts/frontend-release.mjs restore RELEASE_ID "$PUBLISHED_REVISION"
```

该工具只执行显式命令，不会上传后自动发布。

## 产物约定与运行限制

- ZIP 根目录有非空 index.html；支持 JS 模块、CSS、图片、字体等静态资源。必须按相对路径构建（例如 Vite base 为 `./`），不要用 `/assets/…` 指向运行站点根。推荐 hash 路由；HTML 导航缺失路径会回退 index.html，缺失资源返回 404。
- 最多 1024 个 ZIP 条目，压缩包和解压总量各 20 MiB；每智能体最多 100 个构建、200 MiB 解压内容。拒绝路径穿越、符号链接、重复文件、隐藏文件及 `__` 平台保留路径。不得上传源码密钥、.env、node_modules。
- 产物不可修改，上传新构建后再发布；回滚恢复代码和公开配置，不撤销已经发生的客户业务操作。首次发布过的静态产物可长期缓存，不能把代码发布当作保密或删除机制。
- 所有智能体的文件与入口在同一个平台域名。模板在不包含 allow-same-origin 的沙箱内执行，不能访问后台 DOM、Cookie、localStorage、IndexedDB 或 Service Worker。文件响应同样携带 CSP sandbox，直接打开静态 URL 也不解除隔离。用户 token 和上下文仅保留内存。平台禁止外部嵌入和脚本弹窗；业务链接使用用户点击的 `<a target="_top">` 跳转回客户 App 的业务 URL。
- 完整页面可以定制，但仍受平台运行权限约束。自定义客户后端数据接入由 PMR-00024 定义，当前不提供任意 URL 的开放代理。

## 平台部署（客户无需执行）

沿用 `APP_URL=https://getwoodenhorse.com` 和现有 DNS/HTTPS。无需 FRONTEND_HOST、FRONTEND_ORIGIN 或新增域名。Caddy 将 `/agent/*`、`/builds/*`、`/api/*` 路由到 API；`/agent/{id}` 是稳定入口，`/builds/{artifactId}/` 是静态资源路径。沙箱与语音宿主由平台实现，供应商只交付静态文件并使用 SDK。旧 `/chat/{id}` 仅兼容跳转到 `/agent/{id}`，不再独立渲染内置模板。无定制或定制停用时，平台通过私网 `WEB_URL` 加载内置页面，浏览器地址仍为 `/agent/{id}`；Docker Compose 固定为 `http://web:3000`，不新增公开域名。

产物逐文件存储于 PostgreSQL，与元数据同一事务持久化，现有数据库备份包含构建。当前采用上述容量配额；后续存储量需要扩展时再替换为对象存储，不提前引入多套部署系统。自定义页面与内置客服共享域名，但不共享脚本执行权限。模板全局 CSS/JS 不注入后台或宿主 DOM。

## 智能体配置、项目知识库与业务引导管理

同一枚 `wh_dev_…` 开发凭证可以同时管理模板和智能体内容。后台「接入与 API → 开发凭证」签发时按需勾选下列权限；既有凭证不自动扩权，需要重新签发。权限只覆盖签发时选定的 projectId，不允许创建其他智能体、访问用户对话/记忆、生成项目 API Key、签发用户身份或再次签发开发凭证。

| 权限 | 授权操作 |
| --- | --- |
| `agent:read` | 读取标准化智能体配置和平台支持的模型名称 |
| `agent:write` | 修改标准配置；兼容修改旧上下文接口，新连接使用 connections 权限 |
| `knowledge:read` | 读取项目知识资料列表和全文 |
| `knowledge:write` | 新增、局部修改、删除资料 |
| `actions:read` | 读取业务引导列表和详情 |
| `actions:write` | 新增、局部修改、删除业务引导 |
| `connections:read` | 读取 MCP / HTTP Service 连接器、工具列表和认证模板 |
| `connections:write` | 创建、修改、删除、启停连接器，发现及授权 MCP 查询工具 |
| `variables:read` | 读取变量元信息、引用及普通 String 值；Secret 不读回 |
| `variables:write` | 创建、轮换、停用和删除变量及修改主机授权 |

连接器属于同一套智能体管理 API，使用同一项目开发凭证管理，无需后台登录或浏览器操作。完整配置字段、修订号规则以及 MCP 发现/授权流程见下方[连接器管理](#connectors)；用途、参数、返回数据说明和认证头均可通过 API 配置。

这些权限相互独立；写权限不会自动获得列表/读取权限。模板的 `read / develop / publish` 保持原义。Secret 和旧连接 token 不返回原文；普通 String 允许管理读取，不应用于密钥。写响应只返回该操作结果。业务引导、知识库和配置修改**立即生效**，不经过模板发布；删除知识资料不删除已有对话。

所有请求使用 `Authorization: Bearer $WH_DEVELOPER_TOKEN`，根路径 `/api/v1/developer/projects/{projectId}`。JSON 写入带 `Content-Type: application/json`；接口只供本地开发工具或服务端使用，不使用后台 Cookie 或浏览器 CORS。凭证失效/过期/跨项目返回 401，缺少权限返回 403，字段错误返回 400，资源不存在返回 404。

| 路径 | 方法 | 请求及响应 |
| --- | --- | --- |
| `/config` | GET | `{apiVersion:"v1",projectId,config,models}` |
| `/config` | PATCH | 仅提交要修改的配置字段；返回 `{config}` |
| `/knowledge` | GET | `{knowledge:[{id,project_id,title,content,created_at}]}` |
| `/knowledge` | POST | `{title,content}` → 201 `{id}` |
| `/knowledge/{id}` | GET | `{item:{id,project_id,title,content,created_at}}` |
| `/knowledge/{id}` | PATCH | `{title?,content?}` → `{ok:true}` |
| `/knowledge/{id}` | DELETE | `{ok:true}`，删除已不存在的项目内 ID 同样成功 |
| `/actions` | GET | `{actions:[{id,project_id,label,url,description,display_mode,created_at}]}` |
| `/actions` | POST | `{label,url,description?,display_mode?}` → 201 `{id}` |
| `/actions/{id}` | GET | `{item:{id,project_id,label,url,description,display_mode,created_at}}` |
| `/actions/{id}` | PATCH | 仅提交要修改的引导字段 → `{ok:true}` |
| `/actions/{id}` | DELETE | `{ok:true}`，删除已不存在的项目内 ID 同样成功 |

配置字段：`name`（1–60 字）、`description`（0–240 字）、`system_prompt`（0–6000 字）、`welcome`（1–600 字）、`model`（平台模式从 GET 返回的 models 中选择；自定义模式允许任意 1–100 字符模型 ID）、`color`（#RRGGBB）、`active`（布尔值）、`context_url`（空字符串或公网 HTTPS 地址）。GET 返回 `context_token_set` 布尔值，不返回 `context_token`。PATCH 可额外传 `context_token` 设置访问令牌（1–2000 字），或 `clear_context_token:true` 清除；不传/传空字符串保留原值。`context_url` 和令牌用于服务端向客户接口取得 AI 上下文。授予 `agent:write` 即允许持有者变更这一数据连接，应只授权负责智能体集成的开发者。

`fixed_replies` 为可选数组（最多50条、100KB），不传保留，`[]` 清除。每条 `{id,question,reply,actionIds?}`：整条用户消息去除首尾空白后与 question 完全匹配时，服务器逐字返回 reply，跳过模型生成；不做子串、语义或标点归一化。非命中保持原流程，回复沿用正式 SSE、会话隔离、限流和历史保存。actionIds 只能选择本项目已配置且客户端支持的卡片，不执行任何业务。配置继承原 agent:read/write 与拥有者锁定规则，普通基本设置保存不会清除它。

可选 `lookup:{connectorId,input,conditions?}` 在匹配后先执行本项目已授权的 assistant/both 只读 HTTP 连接器；conditions 是返回对象点路径到标量值的映射（例如 `data.profile.enabled:true`）。条件全部实际满足后才采用固定回复，否则走普通对话，不能用空偏好伪造历史。无 conditions 仅用于查询前说明，不代表查到数据或完成操作。只配置静态文案或不承诺实际结果的查证说明；不要将实时价格、订单结果或未授权业务动作写成固定事实。

连接器服务端请求额外包含 `X-Woodenhorse-Principal-Id`：平台生成的项目隔离、不透明访客主体摘要，匿名和已验证访客均可有值，便于可选 Profile 服务隔离记录。它不表示云顶账号或应用登录，也不能替代上游业务认证；`X-Woodenhorse-User-Id` 仍只在已验证身份下发送。此头不接受模板/模型覆盖。


智能体独立模型配置复用 `/config` 和 `agent:read/write`：`llm_base_url` 为空表示平台模型，非空须为公网 HTTPS 443 基础地址，不含账号、查询参数或片段，自动追加 `/chat/completions`。`llm_api_key` 为只写字段（最多 8000 个可见 ASCII 字符），首次设置/更换地址时必须同时提供；省略或空字符串保留原 Key。更换地址不能沿用旧 Key。GET/PATCH 只返回 `llm_base_url`、`model` 和 `llm_api_key_set` 布尔值，不返回 Key、密文或加密密钥 ID。返回的 `llm_api_key_set` 是只读状态，PATCH 不提交此字段。恢复平台服务需 PATCH `{llm_base_url:"",model:"平台支持的模型"}`，同时删除自定义 Key。`agent:write` 可修改模型目标并替换 Key，只授权可信开发者。

Key 由服务端 `WH_VARIABLE_KEYS` / `WH_VARIABLE_ACTIVE_KEY` 的 AES-256-GCM 密钥环加密，绑定租户、智能体和 API 地址；未配置加密时拒绝保存新 Key（503），不写明文。自定义服务须兼容 OpenAI Chat Completions（Bearer、messages、max_tokens、SSE，按功能支持 tools）。对话、记忆、优化和连接器规划均使用同一智能体配置；失败或加密密钥不可用时不回退到平台 Key。每次出站检查 DNS/IP 并固定拨号目标，禁止访问内网、非 HTTPS 和重定向。语音 ASR 使用独立配置，不受聊天模型设置影响。

智能体独立语音配置（PMR-00031）也复用 `/config` 和 `agent:read/write`：

| 字段 | 规则 |
| --- | --- |
| `asr_ws_url` | 空字符串表示使用平台默认；自定义须为公网 WSS 443 完整地址，不含账号、查询参数或片段 |
| `asr_model` | 自定义服务的模型 ID，1–100 字符，与聊天 `model` 独立 |
| `asr_api_key` | 只写，最多 8000 个可见 ASCII 字符；首次配置或更换 URL 必填，省略或空字符串保留原 Key |
| `asr_api_key_set` | 只读布尔值，表示是否保存了自定义 Key，PATCH 不提交 |

例如 PATCH `{"asr_ws_url":"wss://asr.example.com/api-ws/v1/inference","asr_model":"fun-asr-realtime","asr_api_key":"由服务端密钥管理注入"}`。服务须兼容 DashScope/FunASR WebSocket 协议（Bearer、run-task/finish-task、16kHz 单声道 s16le PCM）；不支持把普通 HTTP 转写 API 填入此处。服务 URL 是完整地址，平台不追加路径。恢复平台默认只需 PATCH `{"asr_ws_url":""}`，同时删除自定义模型、URL 和 Key。省略语音字段会保留原配置，旧客户端兼容。

语音 Key 使用相同 AES-256-GCM 密钥环，独立绑定租户、智能体及完整语音 URL，不返回 Key、密文或密钥 ID。所有内置、widget、可信宿主及 Runtime 转写入口按当前 agent 选择服务；bootstrap/config 的 `voice.enabled` 反映该 agent 的配置，公开响应不包含服务地址或模型凭证。自定义服务可在未设置平台 ASR Key 时独立使用；全局 `ASR_ENABLED=false` 仍关闭所有语音。租户日额度、并发和身份校验沿用现有机制。自定义服务在保存、使用及拨号时校验公网地址并固定目标 IP，拒绝重定向；服务或 Key 不可用时返回错误，不回退到平台服务或 Key。

服务端管理 API（Service API）示例：下列请求无需后台 Cookie。读取需 `agent:read`，设置、替换 Key 和恢复平台模型需 `agent:write`。`WH_MODEL_API_KEY` 由服务端密钥管理注入，不写入命令行参数或仓库：

```python
import json
import os
import urllib.request

endpoint = (os.environ["WH_PLATFORM"].rstrip("/")
            + "/api/v1/developer/projects/" + os.environ["WH_PROJECT"] + "/config")

def model_config(patch=None):
    request = urllib.request.Request(
        endpoint,
        data=None if patch is None else json.dumps(patch).encode(),
        method="GET" if patch is None else "PATCH",
        headers={"Authorization": "Bearer " + os.environ["WH_DEVELOPER_TOKEN"],
                 "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=15) as response:
        return json.load(response)

# 设置此智能体的模型服务；返回配置与 llm_api_key_set，不返回 Key。
model_config({"llm_base_url": "https://api.example.com/v1",
              "model": "provider-model-id",
              "llm_api_key": os.environ["WH_MODEL_API_KEY"]})
config = model_config()["config"]
# 替换 Key：地址不变时可只提交这个字段。
model_config({"llm_api_key": os.environ["WH_MODEL_API_KEY"]})
# 只改模型，保留现有地址和 Key。
model_config({"model": "another-provider-model-id"})
# 恢复平台服务，同时删除自定义地址和 Key。
model_config({"llm_base_url": "", "model": "gpt-4o-mini"})
```

知识库只支持文本和 Markdown，最多 100 份，标题 1–120 字、正文 1–60000 字。PDF/Office 等需开发工具先提取为文本。业务引导最多 6 条；label 1–24 字，url 1–2000 字，description 最多 240 字。`display_mode` 为 `button`（默认，常驻按钮）或 `card`（按需卡片，必须提供 description）。URL 使用现有业务引导规则；系统自动附带 tenantId、projectId、userId，不为它们配置占位符。动态业务参数只允许在查询参数值中使用 `<参数名>`（例如 `?sku=<sku>`），并须在 description 中说明。配置和 PATCH 字段未传则保留，未知字段拒绝；不接受客户端通过 tenant_id/project_id 改变资源归属。创建不是幂等请求，网络中断后先列出资料/引导确认是否已创建，避免盲目重试产生重复内容。

旧 `context_url` / `context_token` 字段保留兼容；新接入优先使用连接器。维护旧上下文也可用 `/connectors/_context`，仅需 connections 权限，无需扩大智能体配置权限。

示例：编程智能体读取配置、修改智能体名称、加入知识资料、配置业务跳转（环境变量由本地密钥管理注入）：

```bash
# 需要 agent:read、agent:write、knowledge:write、actions:write
BASE="$WH_PLATFORM/api/v1/developer/projects/$WH_PROJECT"
curl --fail-with-body "$BASE/config" -H "Authorization: Bearer $WH_DEVELOPER_TOKEN"
curl --fail-with-body -X PATCH "$BASE/config" \
  -H "Authorization: Bearer $WH_DEVELOPER_TOKEN" -H 'Content-Type: application/json' \
  --data '{"name":"云顶客服","welcome":"你好，想了解什么？"}'
curl --fail-with-body -X POST "$BASE/knowledge" \
  -H "Authorization: Bearer $WH_DEVELOPER_TOKEN" -H 'Content-Type: application/json' \
  --data '{"title":"营业时间","content":"这里填写客户确认的真实营业时间。"}'
curl --fail-with-body -X POST "$BASE/actions" \
  -H "Authorization: Bearer $WH_DEVELOPER_TOKEN" -H 'Content-Type: application/json' \
  --data '{"label":"我的订单","url":"https://customer.example/orders","description":"用户需要查询订单时展示","display_mode":"card"}'
```

当前标准化配置不包含历史云灵 appearance 配置或图片上传；这些现有后台功能不因本次扩展自动向开发凭证开放。独立 HTML 模板继续通过上文 frontend API 管理。PMR-00025 来源场景扩展仍独立跟进。


<a id="agent-credentials"></a>
## 智能体环境变量与出站认证

后台入口：智能体 → 编辑智能体 → **环境变量**。此处的变量是平台保管、仅供服务端中转使用的 agent 级配置，**不是**供应商前端构建环境，也不会注入页面、Runtime config、提示词、工具参数或进程环境。按现有 `projectId` 隔离，同租户不同智能体也不能互相引用。名称可以相同。

人工 UI 和编程 Agent 复用相同校验与存储。UI 使用登录 Cookie 和同源写入保护；本地 Agent 使用 `Authorization: Bearer wh_dev_…`，无 Cookie 回退、不允许浏览器 Origin。开发 API 根路径仍为 `/api/v1/developer/projects/{projectId}`。

| 新权限（默认不授予） | 能力 |
| --- | --- |
| `variables:read` | 查看变量元信息、引用目标和普通 String 值；Secret 原文永不返回 |
| `variables:write` | 创建、轮换、停用、删除变量及修改允许主机 |
| `connections:read` | 读取连接配置、认证模板和 revision |
| `connections:write` | 设置连接地址、运行模式和认证模板；可使用已授权变量向指定主机发起认证 |

`agent:write`、旧 read/develop/publish 不包含这些权限。通过旧 `/config` 修改上下文接口 URL 需要 `agent:write`，通过统一 `/connectors/_context` 则使用 `connections:write`；已启用自定义认证时均检查变量主机授权。持有 `connections:write` 的开发 Agent 可以配置使用现有 Secret，但不能通过读取接口取回其明文；请按用途单独委派。

### 变量 API

| 方法和相对路径 | 请求/返回 |
| --- | --- |
| `GET /variables` | `{variables, encryptionReady}` |
| `GET /variables/{NAME}` | 单个变量元信息及引用目标 |
| `POST /variables` | `{name,type,value,description?,allowedHosts,status?}`，201 |
| `PATCH /variables/{NAME}` | `{expectedVersion,value?,description?,allowedHosts?,status?}` |
| `DELETE /variables/{NAME}` | JSON `{expectedVersion}` |

UI API 的对应路径为 `/api/projects/{projectId}/variables…`。名称规则 `[A-Z][A-Z0-9_]{0,63}`；类型 `secret` / `string` 创建后不可修改。最多 100 个变量，值 1–8192 字节且无非法 HTTP 控制字符。Secret 推荐用于 Token、API Key、密码；String 仅适合可供授权管理者读取的普通数据。两类值均加密落库。

每个变量必须指定 1–20 个 `allowedHosts`，精确主机名、无协议/端口/路径/通配符，如 `["api.customer.com"]`。主机授权不绕过公共 HTTPS/DNS/IP/SSRF 限制。实际出站时从已认证项目推导命名空间，不接受浏览器/模型提供租户或变量选择。

Secret 响应仅含 `name,type,description,valueSet,version,status,allowedHosts,references,createdAt,updatedAt`；普通 String 额外返回 `value`。`references` 为 `service` / `context` / `connector:<连接器 ID>`，列出认证头及 requestValues 的引用（包括停用的连接器）。被引用时停用/删除返回 409；轮换可直接提交新值，新请求立即生效。修改后 version 加一，并发旧版本写入返回 409。所有 API 实例每次读取数据库，无最多 30 秒的缓存等待；单请求以一次 SELECT 获取一致版本快照。配置回退不会恢复旧密钥。

### 原业务与上下文认证 API（兼容）

新 MCP / HTTP Service 的认证直接配置在连接器 `headers` 中，完整示例见[连接器管理](#connectors)。本节只说明已有固定业务与上下文连接；统一入口为 `/connectors/_service/authentication`、`/connectors/_context/authentication`，以下旧路径保持兼容。

`GET /authentication/{target}` 和 `PUT /authentication/{target}`，target 为 `service`（页面业务中转）或 `context`（AI 上下文接口）。两个接口独立配置。UI 对应 `/api/projects/{projectId}/authentication/{target}`。PUT 必须带读取到的 `revision`，冲突返回 409；保存即时生效，不走模板发布或内容草稿。

```json
{
  "revision": 0,
  "mode": "headers",
  "headers": [
    {"name": "X-WH-Secret", "value": "<API_SECRET>"},
    {"name": "X-Client-ID", "value": "Client <CLIENT_ID>"}
  ]
}
```

先通过 POST `/variables` 创建 `API_SECRET` 等变量，再保存认证配置。每个请求头必须引用至少一个 `<NAME>`，支持常量前缀、后缀和多个变量拼接。模板只用于管理配置，一次替换，不递归解释变量内容。不要直接在模板中填写密钥。

Bearer：`{"name":"Authorization","value":"Bearer <API_TOKEN>"}`。

Basic：`{"name":"Authorization","value":"<API_USERNAME>:<API_PASSWORD>","encoding":"base64","prefix":"Basic "}`，顺序为替换变量 → UTF-8 Base64 → 添加 prefix；空格需保留。`encoding` 为 `none`（默认）或 `base64`。

自定义头 1–20 个、大小写无关去重，禁止 CR/LF/控制字符；不能覆盖 Host、Cookie、Content-Type、连接/代理头、Idempotency-Key 或平台身份头。JSON Content-Type/Accept 和已验证身份由平台设置。缺变量、停用、解密失败、主机不匹配时拒绝出站，不回退旧令牌。认证保存时检查已配置的目标；也可先准备认证再保存目标 URL，保存连接和每次执行均重新检查主机授权。无任意代码/表达式、动态 HMAC 签名、OAuth 自动刷新；需要这些协议时应基于实际上游契约添加受限认证类型。

`mode: "legacy", headers: []` 保留原 Bearer 行为。切换为 headers 会清除对应的旧明文 token，且不再附加旧 Authorization。服务正式模式切回 legacy 前应先停用连接，再设置旧令牌。context 的旧令牌可在「连接器 → 已有页面业务与上下文连接」重新输入。旧项目无需迁移即可继续运行；推荐手工将旧值写入 Secret 后切换认证，平台不会向前端返回旧值。

业务连接管理也向开发 Agent 开放：`GET /service`（`connections:read`）读取既有配置，`PUT /service/connector`（`connections:write`）提交 `{revision,mode,baseURL,loginURL,token?}`。headers 模式拒绝同时提交旧 token；live 要求有效目标和认证。连接修订号独立于认证修订号，认证切换清除旧 token 时也可能更新连接 revision，写连接前重新 GET。内容 draft/publish 未向开发凭证开放。UI 中独立模板在「连接器 → 已有页面业务与上下文连接」配置原业务协议，不必使用云灵模板。

### 密钥部署与验证边界

API 进程从部署密钥存储注入 `WH_VARIABLE_KEYS`（`{"key-id":"base64-32-byte-key"}`）和 `WH_VARIABLE_ACTIVE_KEY`（当前 key-id）。缺省时变量创建/轮换不可用、UI 显示未配置，已有旧连接不受影响；格式错误时 API 启动失败。不要将主密钥放入数据库、仓库、前端产物或日志。所有实例须共享同一 keyring，并独立备份。AES-256-GCM 的 AAD 绑定 tenant/project/name/version。新增主密钥后保留旧 key-id；变量更新会用当前主密钥重新加密，确认无旧引用后才可移除旧密钥。没有历史明文读取接口。

审计表 `agent_credential_audit` 只保存项目、操作者（owner/developer credential ID）、资源名、动作、版本与时间，不保存 value。出站认证不会进入调试导出；客户 JSON 中意外回显的原始变量值、组合头和 Base64 值会在提供给 Runtime/模型前脱敏。上游错误内容不透传。禁止重定向及原有响应白名单校验继续执行。

本功能没有实现附件建议中的租户共享变量、baseURL 变量展开、按操作路由、云顶数据适配或真实客户联调。Service 仍使用已有操作路径和输入/输出契约；启用全局 live 前需确认所有会使用的操作均已接入。PMR-00024 既有中转继续复用，PMR-00025 来源场景功能未因此完成。


<a id="connectors"></a>
## MCP 与 HTTP Service 连接器（2026-11-06）

后台统一为 **环境变量**（agent 级变量）与 **连接器**（接口地址、认证、用途和参数）两个入口。原「认证请求头」与基本设置中的上下文地址已收拢到「连接器 → 已有页面业务与上下文连接」；云灵内容设置只编辑内容。原业务 Service / AI context 保留原配置与运行协议，不复制连接数据、不自动重复创建新连接器。配置不依赖前端重新发布；context 配置在新会话生效，assistant 配置从后续请求生效。UI 供管理员使用；编程 Agent 使用下列开发 API。

根路径：`/api/v1/developer/projects/{projectId}/connectors`。使用 `Authorization: Bearer <项目开发凭证>`；不使用后台 Cookie，不发送浏览器 Origin。读取需要 `connections:read`，创建/修改/删除/发现工具需要 `connections:write`。旧 read/develop/publish 不自动获得权限。后台会话使用同一业务校验的 `/api/projects/{projectId}/connectors`。

| 路径 | 方法 | 请求 / 响应 |
| --- | --- | --- |
| `/connectors` | GET | `{connectors:[Connector,…]}` |
| `/connectors/{id}` | GET | 单个 Connector；跨项目返回不存在 |
| `/connectors` | POST | 创建下述配置 → Connector，HTTP 201 |
| `/connectors/{id}` | PATCH | `{revision,…需要修改的字段}` → 更新后的 Connector |
| `/connectors/{id}` | DELETE | `{revision}` → `{deleted:true}` |
| `/connectors/{id}/discover` | POST | `{revision}` → 保存发现的工具和协议版本后的 Connector；仅 MCP |

所有修改、删除和发现操作使用当前 `revision`，过期返回 409；重新读取后再编辑。创建时不传 revision。失败发现返回 502，已有配置保留，不自动授权新工具。每个智能体最多 10 个连接器，每个 MCP 最多授权 10 个工具，assistant 行为合计最多 40 个查询工具；context 行为合计最多 3 个自动查询工具。每种行为已启用的参数与说明合计最多 128000 字节。工具发现每智能体每分钟最多 20 次。

Connector 可写字段：`name`（1–80 字）、`kind`（mcp/service）、`url`、`description`、`headers`、`enabled`、`requiresIdentity`、`responseDescription`、`method`、`inputSchema`、`allowedTools`、`usage`、`requestValues`、`behavior`、`contextInput`、`revision`。其他字段拒绝写入。只读字段：`id`、`tools`（name/description/inputSchema/annotations）、`protocolVersion`。`enabled` 默认 false，`requiresIdentity` 默认 false；只有依赖平台签名身份头的接口才设为 true。`usage` 默认 assistant，可选 template 或 both；MCP 只允许 assistant。宿主自有认证由连接器按实际接口契约传递，并由上游核验权限。PATCH 中 inputSchema / requestValues / contextInput 整个对象替换，传 `{}` 可清空服务端参数或固定参数。

### 两种调用行为：context 与 assistant

`kind` 决定连接协议（mcp/service），`behavior` 决定调用时机；两种协议都支持两种行为。省略 behavior 时默认 `assistant`，旧连接器保持原来的按需调用行为。

| behavior | 执行时机 | 参数来源 | 结果用途 |
| --- | --- | --- | --- |
| context | 打开对话框建立会话时读取一次，包括首次问候之前 | contextInput 固定 JSON 对象，默认 `{}` | 同时提供给按需查询规划和最终回复 |
| assistant | 客服判断本轮问题需要实时数据时调用 | 模型按 inputSchema / MCP 工具定义生成 | 提供给本轮回复 |

context 不产生模型规划请求；每次初始化自动获取最多 3 个已授权查询工具，共享 15 秒时限，结果资料总量最多约 64000 字节。读取失败不会阻断对话，客服须说明无法核实，不能编造。结果作为服务器端 session 快照绑定 conversationId，同一会话重新打开、刷新或后续发消息均复用，不跨用户或智能体共享，也不计入长期记忆。新建会话重新获取；读取失败的结果也保存，本会话不自动重试。context 配置变更在新会话生效，assistant 配置从后续请求生效。

打开页面时调用现有 `POST /api/v1/projects/{projectId}/runtime/bootstrap` 即会初始化选中会话；新建或打开其他会话也会初始化。初始化操作由平台处理，页面无需另发 context 请求，快照不会出现在 bootstrap、会话列表或历史消息响应中。旧客户端若未经过上述入口，在第一条消息时补做一次初始化。

contextInput 必须为 JSON 对象，最多 8192 字节，不展开变量；业务字段名由接口定义；HTTP GET 只接受字符串、数字、布尔值。启用时须满足 HTTP inputSchema 或**每个已授权 MCP 工具**的参数定义，多个 MCP 工具共用同一份固定参数。无参数接口保留 `{}`。认证由 headers 或 POST requestValues 引用 agent 环境变量或宿主 data 路径；可信用户身份由平台单独传递。assistant 行为不允许非空 contextInput。

usage 与 behavior 是独立概念：usage 控制客服/模板调用权限；context 由平台自动获取，仅允许 usage=assistant，不向模板 Runtime 调用目录开放。assistant 行为保留 template/both 页面调用能力。

HTTP 上下文示例（先将 API_TOKEN 存入 Secret 并授权目标主机；下列配置可通过 UI 或 POST /connectors 创建）：

```json
{
  "name":"当前用户资料",
  "kind":"service",
  "behavior":"context",
  "usage":"assistant",
  "url":"https://api.customer.com/profile",
  "method":"GET",
  "description":"获取当前已验证用户的账户资料，供客服理解用户背景。",
  "inputSchema":{"type":"object","properties":{},"additionalProperties":false},
  "contextInput":{},
  "responseDescription":"profile 为账户资料；空值表示尚无资料，不能推测。",
  "headers":[{"name":"Authorization","value":"Bearer <API_TOKEN>"}],
  "requiresIdentity":true,
  "enabled":true
}
```

HTTP context 和 assistant 均支持 `method:"GET"` / `method:"POST"`。context 的 GET 把 contextInput 写入查询参数，POST 把 contextInput 写入 JSON 请求体，并合入 requestValues 中的服务端变量字段；POST 可传嵌套对象。

MCP 上下文也设置 behavior=context；按下文先 discover、逐项授权，再启用。如工具需要固定参数，在 contextInput 中提供，不能依赖本轮模型补齐。切换已有连接器行为用 PATCH `{revision,behavior,...}`；若从 context 切换 assistant，需一并清空 contextInput。

旧 `/connectors/_context`、context_url 及其认证接口保留兼容。**新会话初始化时若启用了 context 连接器，只执行新 context 连接器**；即使身份不足、超时或调用失败，也不会额外请求旧 context_url。停用所有 context 连接器后，新会话恢复旧行为；已有会话继续使用已初始化快照。这里说明连接器结果快照；宿主 data/context 则按下文自动接入契约。

### MCP：添加 → 发现工具 → 选择授权 → 启用

```json
{
  "name":"订单 MCP",
  "kind":"mcp",
  "url":"https://api.customer.com/mcp",
  "headers":[{"name":"Authorization","value":"Bearer <API_TOKEN>"}],
  "description":"查询当前登录用户的订单状态，只读查询",
  "requiresIdentity":true
}
```

先创建 agent 级环境变量 `API_TOKEN`，`allowedHosts` 包含 `api.customer.com`。取得连接器 ID 和 revision 后 POST `/{id}/discover`，从返回 tools 中选择实际只读工具，再 PATCH（示例 2 须替换为 discover 返回的当前 revision）：

```json
{"revision":2,"allowedTools":["lookup_order"],"enabled":true}
```

支持远程 HTTPS **Streamable HTTP**，包括 JSON 结果、请求内 SSE、工具列表分页、tools/call，以及 2026-07-28 的元信息和参数头映射；兼容 2025-11-25、2025-06-18、2025-03-26 的初始化和会话流程。每次查询独立连接/会话，完成后关闭，不跨用户复用。遵循 [MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http) 与 [Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) 契约。不包含本机 stdio、旧版独立 HTTP+SSE、资源/提示词管理、OAuth 登录和 token 自动刷新；认证使用平台变量模板。

管理员逐项授权查询工具。明确标注 `readOnlyHint:false` 或 `destructiveHint:true` 的工具不能授权；缺少标注时需管理员确认其业务行为只读。远端工具的名称、描述、参数或注解变化后，本轮拒绝执行；重新发现会移除变化工具的授权，需管理员复核。改变地址、类型或认证头会清空发现和授权结果，并停用 MCP。

### 非 MCP Service：提供用途、参数、返回数据说明

```json
{
  "name":"订单查询",
  "kind":"service",
  "url":"https://api.customer.com/orders/search",
  "method":"POST",
  "description":"用户明确询问自己的订单时使用；query 为用户确认的订单查询条件。不能创建、修改或取消订单。",
  "inputSchema":{
    "type":"object",
    "properties":{"query":{"type":"string","description":"用户确认的订单关键词"}},
    "required":["query"],
    "additionalProperties":false
  },
  "responseDescription":"orders 为当前用户订单数组；status 为 paid/unpaid/cancelled；amount 单位为分。空数组表示没有匹配订单。",
  "headers":[{"name":"Authorization","value":"Bearer <API_TOKEN>"}],
  "enabled":true,
  "requiresIdentity":true
}
```

Service 的上下文 `description`、返回数据 `responseDescription` 必填；`inputSchema` 为根类型 object 的自包含 JSON Schema（最多 16000 字节，默认空对象定义）。定义参数名称、类型、用途及必填项；服务端按 schema 校验实际参数，不下载外部 `$ref`。GET 把标量参数放入 URL query，POST 把参数对象作为 JSON body；不支持任意方法、脚本、路径模板或动态签名。assistant/both 只用于只读查询；登录等有业务副作用的流程必须选 template，由页面明确调用。上游须返回 HTTP 200、`application/json` 和最多 32000 字节的有效 JSON。上游业务仍应自行保证只读及用户授权。

HTTP Service 的顶层标量参数可添加 `x-http-header`，将该参数发送为指定业务请求头，同时从 JSON body／query 中移除。例如 `userId:{"type":"string","x-http-header":"X-User-ID"}`、`submissionKey:{"type":"string","x-http-header":"Idempotency-Key"}`。这只是上游业务参数，不建立平台身份。仍按 schema 校验、拒绝控制字符和重复头；不能覆盖认证头、Cookie、HTTP 协议头或平台 `X-Woodenhorse-*` 身份头。提交编号由模板针对一次明确操作稳定生成，重试复用；写入类连接器使用 `usage:"template"`，不向模型开放。没有映射标记的旧连接器保持原行为，MCP 不使用此扩展。

### assistant 按需查询与身份边界

assistant 行为根据本轮问题、最近对话及已获取的 context 数据，先决定是否需要查询，最多执行 3 次，再把结果作为资料用于原有流式回复。问候、闲聊和资料已足够时可以不查询。没有授权连接器时沿用原对话流程。缺参数应追问，失败不得编造业务结果；查询结果不表示已办理、下单或付款。每轮规划和查询合计最多 30 秒；MCP 发现最多 15 秒。模型供应商可能产生额外一次规划请求，结果资料总量最多约 64000 字节。

出站必须是公网 HTTPS 443，验证 DNS/IP 并固定实际拨号目标；禁止重定向。认证头可以为空（公开接口），否则每个头至少引用一个智能体变量，支持拼接、Base64 和前缀；不允许在配置中直接保存密钥或覆盖平台身份/协议头。变量主机授权每次执行重新检查，Secret 不提供给模型和浏览器；回显认证值会脱敏。接口读取只返回认证模板。

平台独立发送 `X-Woodenhorse-Tenant-Id`、`X-Woodenhorse-Project-Id`；已验证用户另带 `X-Woodenhorse-User-Id`（非 ASCII 等值采用 `=?base64?<Base64 UTF-8>?=` 编码）。平台身份头来自平台验证结果，与业务参数分开。业务 schema 可以包含 userId、tenantId 等任意字段，由 AI 按宿主 context 与接口定义匹配；这些参数不改变平台身份或资源归属。`requiresIdentity` 默认 false，匿名调用没有 User-Id 头；依赖平台签名身份的接口显式设为 true。上游按自身认证契约核验调用权限及数据归属。

`X-Woodenhorse-User-Id` 的值由客户后端在签发短期用户凭证时绑定到已验证的业务用户；模板负责衔接业务登录及取得凭证，平台负责验证并自动设置请求头。该头名称是平台协议，不是模板可配置的认证头。用户资料连接器可以发送空参数 `{}`，上游通过这个头按用户 ID 查询资料；不需要在 `inputSchema` 或 `contextInput` 中重复配置用户 ID。当前不提供将可信身份自动映射为自定义 query/body 字段的配置，上游使用其他身份参数契约时需接入适配。客服页面的公开分享入口由接入方实现，不改变个人资料连接器的身份要求；Mock 分配合成账号不等于真实客户登录或平台原生匿名身份。

客服查询通过已有消息 API；只有显式开放给模板的 HTTP Service 可以经下面的运行 API 调用。连接器更新带版本锁并写入不含密钥的审计。服务端测试使用受控 HTTPS/MCP/模型夹具，不能代替客户真实接口联调。

### 定制模板引用变量：服务端请求参数

Secret 不进入 HTML、JavaScript、运行配置或浏览器存储；不提供向模板返回变量原文的接口。特殊登录流程可配置仅供模板调用的 HTTP Service。模板提交用户输入，平台在固定目标的请求头和 POST JSON 请求体中展开变量引用。

编程 Agent 先创建环境变量 `APP_SECRET` 并授权目标主机，再通过 `/connectors` 创建：

```json
{
  "name":"定制登录",
  "kind":"service",
  "usage":"template",
  "url":"https://api.customer.com/login",
  "method":"POST",
  "description":"页面取得用户的一次性 code 后调用，以应用密钥交换此用户的业务登录结果。",
  "inputSchema":{
    "type":"object",
    "properties":{"code":{"type":"string","description":"用户的一次性登录 code"}},
    "required":["code"],
    "additionalProperties":false
  },
  "requestValues":{"appSecret":"<APP_SECRET>"},
  "responseDescription":"accessToken 是此用户的业务登录结果；共享应用密钥不返回。",
  "enabled":true,
  "requiresIdentity":true
}
```

`requestValues` 为顶层字段名到字符串模板的映射（最多 20 字段、16000 字节）。每项至少引用一个 `<NAME>` 环境变量或 `<data.path>` 宿主上下文路径，支持组合字符串。环境变量使用与认证头相同的可用性和精确主机授权规则；宿主路径从当前会话快照读取。只支持 POST JSON，避免将密钥写入 URL；嵌套 JSON、表单编码、脚本和动态签名不在此契约中。服务端字段不列入 inputSchema.properties，实际调用参数按 inputSchema 验证，不能覆盖这些字段，也不能伪造平台身份。禁用、删除或收回变量主机授权前必须先解除引用，停用连接器也会保留引用保护。变量轮换对后续调用立即生效。

运行根路径：`/api/v1/projects/{projectId}/runtime`。沿用已发布前端来源、预览凭证及短期**用户** Bearer 校验；开发凭证不能充当运行身份。不会向浏览器发放任意地址代理能力。

| 路径 | 方法 | 契约 |
| --- | --- | --- |
| `/connectors` | GET | `{connectors:[{id,name,description,inputSchema,responseDescription}]}`，仅列出已启用且向当前模板用户开放的 HTTP Service；不含地址、认证模板或服务端参数 |
| `/connectors` | POST | `{connectorId,input:{…用户输入}}` → `{data:…上游 JSON}`；只允许 usage=template/both；错误参数 400、未开放/停用 403、跨项目不存在 404、上游失败 502 |

模板 SDK：

```js
const available = await client.connectors();
const result = await client.connector("连接器 ID", {code: oneTimeCode});
// 请求由平台服务器发出，最终 JSON 为 {code: oneTimeCode, appSecret: 环境变量值}。
// 浏览器仅收到 result.data；共享变量/认证值的回显会被脱敏。
```

每智能体每用户每分钟最多 30 次模板调用，无自动重试；平台不持久化请求体。上游应校验 code、业务登录状态和用户归属。现有短期用户凭证仍由客户后端签发；业务登录响应不会自动创建或变更 Woodenhorse 平台身份。template 连接器不进入模型目录，不执行客服自动查询。both 仅适合客服与页面共用的只读接口。

### 已有业务与上下文连接的统一 API 入口

以下路径均相对于开发项目根路径，读取使用 connections:read，修改使用 connections:write。它们直接调用原业务校验与同一份数据库配置；原 `/service`、`/authentication` 和项目配置接口继续兼容。

| 路径 | 方法 | 契约 |
| --- | --- | --- |
| `/connectors/_service` | GET / PUT | GET 原 ServiceSettings；PUT `{revision,mode,baseURL,loginURL,token?}`，与原 `/service/connector` 相同 |
| `/connectors/_context` | GET / PATCH | GET `{context_url,context_token_set}`；PATCH 仅允许 `context_url`、只写的 `context_token`、布尔 `clear_context_token`，保留其他智能体配置 |
| `/connectors/_service/authentication` | GET / PUT | 原 service 认证配置 `{mode,headers,revision}` |
| `/connectors/_context/authentication` | GET / PUT | 原 context 认证配置 `{mode,headers,revision}` |

`_service` 仍执行旧固定业务操作；`_context` 仍在对话前获取上下文。它们不是按需查询工具，不重复出现在模型工具目录中。新接口直接创建 MCP/HTTP 连接器；无需同时配置旧上下文接口。基本信息保存不会清除已迁入连接器页的上下文地址。


## 宿主 data 与会话 context（PMR-00030）

宿主可通过 widget 的 `data-data`，或 `/agent/{projectId}#data=<URL 编码 JSON>` 传入任意 JSON（包括对象、数组、标量、null），最多 16384 个 UTF-8 字节。不要把凭证放查询字符串。入口会从地址栏移除 data；托管模板通过 SDK 宿主桥读取，不依赖模板 URL 自行解析。内置模板读取同一 data 协议。未传 data 等价于空对象，走同一聊天流程。

```js
const client = createRuntimeClient({baseURL:'https://getwoodenhorse.com',projectId:'PROJECT_UUID'});
const session = await client.bootstrap(); // 自动附带宿主 data
const context = await client.context();   // 当前会话的完整 context
// 模板自行解释字段，用于展示、交互或可信业务域名上的链接。
```

平台自动把完整 context 同时提供给回复模型和连接器规划器。AI 根据连接器用途及 schema 匹配业务参数，字段名 `userId`、`authToken` 等没有平台业务语义，也不授予平台身份。连接器认证可使用任意宿主路径，例如 `headers:[{name:"Authorization",value:"Bearer <data.credentials.access>"}]`；POST `requestValues` 同样支持 `<data.path>` 与 `<NAME>` 环境变量混用。路径段支持英文字母、数字、下划线、短横线；值必须是非空标量，单次展开，不执行代码。缺少必需路径时仅该连接器调用失败，普通聊天不受影响。连接器定义负责说明接口契约，不要求客户实现统一登录或查询接口。

宿主 token 随完整 context 提供给该智能体所配置的 AI；平台持有的环境变量 Secret 继续只在服务端展开。出站认证值及上游回显沿用脱敏，不写请求日志。`requiresIdentity:false` 表示不依赖平台签名身份，上游仍按自己的认证约定核验权限；`true` 则另要求平台签名身份。浏览器提交的 data 不能改写平台保留身份头、跨租户或跨用户访问。

bootstrap 自动恢复当前用户最近会话及消息，入口 data 变化时更新该会话的宿主 context，不再因此清空聊天或创建新访客。数据库以平台 AES-GCM 密钥环加密保存，删除会话级联删除。显式新建会话使用当前入口 data；其他历史会话保留各自 context，`messages(id)` 和 `deleteConversation` 返回所选会话 context，SDK 同步更新 `client.context()`。context 不自动写入长期记忆；连接器自动初始化结果仍按会话快照独立保存。会话列表不包含 context 或密文；拥有者读取单个会话可取得其 context。SDK 调用连接器附上当前 conversationId，服务器核验归属后解析认证路径。直接调用 Runtime 时亦应提供该 ID。

`frontend.config.data` 是发布时的公开模板配置，与每次宿主传入的 data/context 独立；共享 API Key、应用 Secret 继续放智能体环境变量。模板中不得保存项目开发凭证。

## Structured product knowledge catalogs

Product catalogs are project-scoped structured knowledge, separate from ordinary documents and their quota. Owners can browse counts, source synchronization time, category filters, names, descriptions and reference prices in Project Knowledge. Catalog policies belong to the project; the platform does not prescribe supplier categories.

Owner routes are `/api/projects/{projectId}/catalogs`. Local development agents use `/api/v1/developer/projects/{projectId}/catalogs` with `knowledge:read` or `knowledge:write` scopes.

- `GET /catalogs`: metadata list; `GET /catalogs/{id}`: one catalog; `GET /catalogs/{id}/products?q=&category=&page=1`: management browsing, 20 products per page.
- `POST /catalogs`: `{name,description,allowedHosts:["supplier.example"],segments:[{key:"tickets",label:"Tickets without accommodation",categories:["Ticket"],includeAny:["ticket"],excludeAny:["hotel"]}]}`. Categories match exactly; optional name terms match case-insensitively. At most 10 catalogs per project, 30 segments each.
- `PATCH /catalogs/{id}`: `{revision,...name,description,allowedHosts,segments,enabled}`. Metadata updates use optimistic revisions; conflicts return 409.
- `POST /catalogs/{id}/sync-token`: `{revision}` rotates a catalog-only `wh_sync_` credential. It is returned once, only stored as a hash, and grants **GET status / PUT full snapshot** at `/api/v1/catalog-sync/{id}`. It has no project, chat, document or connector management access. Browser-origin calls are rejected. Keep it outside public artifacts; do not deploy developer credentials to scheduled jobs.
- `PUT /catalogs/{id}/snapshot` or the scoped sync endpoint: `{revision,hash,products:[...]}`. `hash` is lowercase SHA-256 of the exact UTF-8 JSON bytes of the `products` array. Each record requires `id`, `name`, `description`, `category`, nonnegative integer `priceCents`, three-character `currency`, boolean `available` and HTTPS `productURL` on an authorized host. Additional product fields are retained as data. Maximum 8 MiB, 10,000 records. Empty, malformed, duplicate-ID, invalid-link or partial uploads are rejected without replacing the old snapshot. Full replacements are atomic and include removals. Identical hashes do not rewrite data or increment revision. The caller must fetch a fresh revision after 409 and save its local hash only after matching acknowledgment.

Enabled populated catalogs appear as read-only query tools and runtime template connectors. The connector ID equals the catalog ID. Calls require the configured `segment`; unsupported fields/categories are rejected. Optional `query`, explicit `exclude` name terms and pagination narrow results. Date and total-person fields (`date`, `endDate`, `adults`, `children:0`) may be retained with query-card conditions but do not perform inventory or date pricing. Optional per-product `applicableWeekdays` (unique integers 1=Monday through 7=Sunday) restricts an explicit query date to supplier-declared weekdays; an empty/missing list establishes no date guarantee. Optional `applicableDateRanges` is an array (at most 32) of `{start:"YYYY-MM-DD",end:"YYYY-MM-DD"|null}` with inclusive bounds. A date outside all declared ranges is excluded before pagination; date and weekday constraints both apply. A null end represents an undeclared end, not a guaranteed future season. Missing/empty ranges add no date guarantee. Holiday eligibility is never inferred. `data.products` contains source records with `catalogVersion` and `catalogSyncedAt`; `data.catalog.priceIsReference` is true. A catalog query cannot fall back to another category. Existing query-card snapshots retain the original data and conditions; subsequent imports do not rewrite history. Prices and availability are directory references, not a booking confirmation or live inventory guarantee.

## 智能体锁定

后台拥有者可通过 `PUT /api/projects/{projectId}/lock` 提交 `{"locked":true}` 锁定，提交 `false` 解锁。此接口使用后台登录与同源校验，不向项目开发凭证开放。后台项目和开发配置读取返回只读 `locked` 状态。

锁定后所有项目管理写请求（包括设置、知识、目录同步、引导、变量、连接器、凭证及模板上传/发布）返回 HTTP 423；解锁接口除外。管理写入和锁定转换按项目串行，锁定成功时此前管理写入已结束。读取与已发布智能体的 Runtime 聊天、业务调用继续可用。锁定不是暂停服务或撤销用户身份。

拥有者删除智能体使用 `DELETE /api/projects/{projectId}`，请求体必须为 `{"confirmName":"当前智能体完整名称"}`。后台先打开二次确认对话框，输入名称一致后才能提交。锁定时返回 423；跨租户或已删除项目返回 404。删除级联移除项目关联记录、凭证和托管产物，清理项目图片文件，已发布入口停止服务；其他智能体不受影响。开发凭证不提供项目删除权限。

## 系统 DeepSeek 4.1 Flash

系统模型列表提供 `deepseek-v4.1-flash`，后台显示为 **DeepSeek 4.1 Flash**。此 ID 来自平台上游模型目录；DeepSeek 官方直连对应 `deepseek-flash`，使用自定义服务时按对应服务商契约填写。系统选项沿用既有平台模型服务和额度，不改变已有智能体的模型设置。聊天、连接器规划、记忆整理和 AI 优化使用保存的模型；此模型请求沿用显式关闭 thinking 的兼容设置。

### 可选对话整理与外部画像存储

拥有者/开发 `agent:read/write` 的 `/config` 增加 `conversation_processing` 对象，默认 `{}` 不启用，普通基本设置保存保留原值：

```json
{"enabled":true,"readConnectorId":"PROFILE_GET_ID","writeConnectorId":"MEMORY_POST_ID"}
```

开启时复用该智能体的模型和加密凭证，不切换供应商。读连接器必须为本项目启用的 HTTP GET、behavior=assistant、usage=template/both；写连接器必须 POST、usage=template，不能成为模型可调用的写工具。调用沿用连接器的服务端变量、目标主机授权、SSRF 和可信随机 principal 头。输入、宿主信息和摘要视为资料，不授予业务执行权限。未启用的项目保留原记忆流程。

读取返回 `profile:{enabled,preferences}`（手动偏好，可选）以及 `automaticMemory:{enabled,revision,facts:[{key,value,evidence?}]}`。主回复前读取，失败继续聊天。自动画像仅接受本轮用户明确陈述的长期称呼/滑雪水平/板种/兴趣/学习目标/回答方式（key: name/skiLevel/skiType/interest/learningGoal/responseStyle/otherPreference）；来源摘录须与本轮用户文字连续匹配，联系方式、凭证等拒绝写入，不从助手或宿主资料推断。主回复保存后，由模型判断是否需要修改；写连接器参数为 `{revision,userId,conversationId,messageId,upsert:[{key,value,evidence}],remove:[{key,evidence}]}`。userId仅来自当前会话宿主上下文，供外部服务索引，不作平台认证。显式启用整理、且读取连接器 schema 声明可选 userId 时，自动读取、固定问答及普通查询共用当前宿主 ID，忽略读取参数中其他 ID；无宿主 ID 时省略该字段。兼容 userId、USERID、user_id、字符串 user 及 user.userId/user.id；未声明该字段的连接器和未启用项目不受影响。外部服务决定以业务 userId 共享或可信 principal 隔离，并检查 revision 与开关；按未验证宿主 ID 共享不能证明账号所有权，上线使用需应用方明确接受此风险或接入正式身份校验。平台显式关闭记忆的访客不提取画像。清除、关闭及来源管理由存储服务按自身已授权界面处理。新流程替代原内置长期记忆提取，未迁移既有内置记忆。

待整理原文超过24条或18000字时，生成本会话较早部分的滚动摘要，保留近期至少12条原文；摘要保留日期、总人数、商品ID、确认条件和待办，不表示订单或支付成功。原始历史不改写；删除会话同时删除摘要。后续对话使用摘要与近期原文，提取失败保留旧摘要与历史。`saved`表示回复已保存；最终SSE `done`增加 `contextCompressed`，`memoryStatus` 为 unchanged/updated/failed，画像结果仍以存储服务实际记录为准。整理有25秒独立上限，失败不撤销已保存回复。

### 可选的模型交互目标判断

独立模板可向 Runtime `messages` 提交 `interactionGoals: [{id, description}]`（最多24项，ID为1–64个字母数字/下划线/连字符，描述最多600字）。平台复用项目模型，结合当前消息和最近的当前会话进行独立目标判断，与正文生成并行，不依赖回复关键词或逐字模板。未声明时不会调用此判断。

模型只能选择本轮候选ID或不选；有效选择作为 `{id:"interaction-goal:<ID>", label:"后续操作", interactionGoal:"<ID>"}` 存于 `saved.cards` 及历史消息。模板只渲染自身实现的ID，不把此卡传给 `action()`。它仅是展示元数据，不增加连接器、身份或写入权限，不会执行业务。固定回复原文不变。判断超时（12秒）或无效输出时不产生目标卡，普通聊天继续；恢复历史使用已保存判断，不重新调用模型或自动执行业务。旧客户端无需改动。

## 用户主动评价

`GET /api/v1/projects/{projectId}/runtime/feedback?conversationId=…` 返回当前用户该会话的 `ratings` 和 `prompt`；`POST` 接收 `conversationId` 及以下操作：

- `action:rate, scope:message, messageId, rating:positive|negative`：评价已保存的 assistant 回复。
- `action:offer, messageId`：模板选择合适时机请求整体评价邀请；服务端按会话稳定选择第 3–6 条回复开始允许，每会话只保存一次邀请及锚点，同一运行用户24小时内最多新邀一次。
- `action:rate, scope:conversation, rating:positive|negative`：对已邀请的会话评价。
- `action:dismiss`：关闭该会话的整体邀请，刷新不重置。

SDK 使用 `feedback(conversationId)` / `submitFeedback(input)`。同一回复或整体评价重复提交会更新原票，不累加；成功响应前不要显示已保存。会话及消息必须属于 Bearer 凭证的当前用户和项目；用户消息、跨用户/跨项目消息不能评价。删除会话时级联删除评价。恢复历史只读状态，模板不应追溯邀请，也不应在危险/投诉等场景请求评价。

后台“用户评价”按当前智能体显示分类统计、筛选、分页和关联原对话。管理接口 `GET /api/projects/{id}/feedback` 需项目管理权限；开发接口 `GET /api/v1/developer/projects/{id}/feedback` 需 `agent:read`。可选 `scope=message|conversation`、`rating=positive|negative`、`offset`（每页50条）。这些接口不提供模型写入工具。

### Reply read-aloud (2026-11-16)

`POST /api/v1/projects/{projectId}/runtime/speech`, SDK `speech({conversationId,messageId,text},{signal})`, returns a private `audio/mpeg` Blob, never a provider URL or credential. It requires an owned conversation and assistant message; `text` is the template's displayed plain text (1–600 Unicode characters per request). Split longer replies and strip Markdown locally. Synthesis is explicit user action; stop playback and abort requests on conversation changes, page hiding or cancellation. Do not automatically read messages. Mobile browsers can require a second tap after synthesis; retain the prepared clip in memory for that tap.

The server reuses the agent's encrypted official DashScope ASR credential at its exact configured inference endpoint, only for official Beijing/Singapore DashScope hosts. Other ASR services do not implicitly enable TTS. Default model `qwen-audio-3.1-tts-flash`, voice `longanhuan_v3.1`; deployment settings `TTS_MODEL`, `TTS_VOICE`, `TTS_ENABLED` control this separately from the chat model. No provider keys or text/audio are returned in accounting metadata. Limits: 600 characters/request, 8MiB audio, 45s synthesis deadline, one concurrent request/user, eight/tenant, 50,000 characters/tenant/UTC day; ASR quotas remain independent. Failed/cancelled synthesis is also counted. Text and audio remain in memory only. This optional feature does not change microphone `voice=true` behavior.
