# 公开链接与访客身份

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

公开 Web 应用在发布记录允许的范围内为匿名访客提供会话。发布 token、访客 session 和登录用户的产品凭据分别有各自用途。

<span id="prepare"></span>

## 调用前准备

内部源码或前端代码中的历史 `/api/v1` 字符串不能直接作为部署地址。`WEBAPP_SHORT_CODE`是链接中的22字符短码；`AGENT_ID`、`WEBAPP_TOKEN` 来自发布链接或解析结果，`WEBAPP_SESSION` 来自 session 响应。示例均使用占位值，不填写真实凭据到维护记录。

1. 对 `?k=...` 链接，向 resolve 提交 `k`，取得 `agent_id`，随后以短码作为 `t`。旧式链接使用 `webapp` 与 `t`；不能混合两种解析输入。
2. 首次访问创建 session。保存 `session_token` 及 `expires_in`；后续数据请求使用查询参数 `s`，刷新接口则使用 JSON 字段 `session`。
3. 使用同一身份创建会话，保存 `data.id`。消息、事件、附件、反馈和 MCP 应用操作继续携带当前链接及该身份，并引用自己的会话/任务。
4. 返回访问时刷新尚有效的 session。明确失效后才创建新身份；依赖故障应保留原身份并重试。

这些接口 handler 不读取产品 PAT、登录 Cookie 或 CSRF 参数作为访客凭据。部署网关的跨域和 Cookie 策略仍需环境核对，不能由 handler 推断线上策略。

## 生命周期

session 有效期固定 604800 秒。刷新签发新凭据并延续同一访客，旧凭据仍可用到自身到期；重新创建 session 则是新访客，不能列出旧身份的会话。

session 签名绑定发布工作区、智能体及访客身份，不直接绑定链接 token。轮换链接后，旧链接不能继续通过准入；取得新链接且原 session 仍有效时，不能声称原 session 已被密码学吊销。停用或轮换会在后续公开请求和流的重读时重新校验，不等于立即取消已经准入的后台任务。

同一智能体在不同工作区有独立发布记录。公开会话必须属于本访客、目标智能体、purpose=webapp 且为 active。归档后消息、事件、反馈和任务产物等公开访问同样不再准入。发布方管理历史的可见性使用另一组接口。

新 session 绑定发布记录的创建代次，删除再创建的发布不能继承原代次身份；旧记录兼容及依赖故障分别保留明确错误。resolve 只检查链接及展示事实，不证明智能体当前 active、发布身份可执行或模型任务一定成功。

<span id="errors"></span>

## 错误与身份处理

普通成功响应使用数值 `code=0` 和 `data`；错误使用 `code/message`。下载、预览及 A2A 流按各自响应处理。

| HTTP/代码 | 含义与处理 |
| --- | --- |
| 404 / 3 | 公开准入不可用，包括链接、session、会话或任务绑定不匹配；不要据此判定对象全局不存在。 |
| 404 / 16 | 匹配的链接已停用；无需丢弃已存访客身份。 |
| 404 / 17 | 刷新接口确认 session 无效；新身份将不具有旧身份的历史。 |
| 400 / 2 | 可修正输入，包括标题、反馈及文件等参数。 |
| 409 / 2 | 会话忙等冲突；不能当成不存在。 |
| 429 / 18 | 发布共享上传预算不足。 |
| 500 / 1 | 存储或运行依赖故障；保留访客身份，不以新建 session 掩盖故障。 |

预览另有 415、413/19、422/20；MCP 应用另有 400、404、409、503/15 等结果。A2A 在打开流前还可返回 JSON-RPC 错误，流打开后检查错误帧，不能只看 HTTP 状态。

权限规范仍有旧“全部失败404”和“刷新失败code3”的描述，与当前 handler/service、前端实际分支不一致；
