# 消息连接与知识读取对象

消息接收连接是工作区管理资源。运行期知识接口供当前智能体任务使用，需要该任务的身份、来源范围和短期授权。

## 连接与输入标识

| 变量 | 来源 |
| --- | --- |
| `WORKSPACE_ID`、`AI_STUDIO_API_KEY` | 当前环境的工作区和有对应权限的个人访问令牌。 |
| `AGENT_WORKSPACE_ID`、`AGENT_ID` | 目录中选定智能体的真实所属工作区与 ID。 |
| `AGENT_MODEL` | 当前目标可用的运行模型，agent 目标必须明确指定。 |
| `CONNECTION_ID` | 创建响应或同一目标连接列表的 id。 |
| `ASSOCIATION_VERSION` | 最新连接详情的 association_version。 |
| `CONFIG_VERSION` | 最新连接详情的 config_version。 |
| `MANAGED_CREDENTIALS_FILE` | JSON 文件，保存所选平台创建托管连接所需的凭据对象；限制访问，不写入日志或仓库。 |
| `CALLBACK_URL` | 当前部署的完整 HTTPS 回调地址，路径与连接详情 callback_path 一致。 |

连接所属工作区与路径及 X-Workspace-ID 一致。团队目标属于该工作区；智能体目标属于当前或系统工作区，使用目录真实值，不能自行伪造空间标识。

## 消息接收连接

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 接收连接 ID。 |
| `workspace_id` | string | 执行工作区。 |
| `target.kind` | string | agent 或 team。 |
| `target.workspace_id` | string | 目标所属空间。 |
| `target.id` | string | 目标标识。 |
| `provider` | string | 所选平台。 |
| `channel_type` | string | 所选通道类型。 |
| `receive_mode` | string | managed_stream、callback 或 mail_polling。 |
| `channel_instance_id` | string | callback/mail_polling 引用的独立通道实例。 |
| `provider_config` | object | 可回读的非敏感平台配置。 |
| `agent_model` | string | 智能体目标选择的模型。 |
| `association_version` | integer | 目标关联版本。 |
| `config_version` | integer | 当前连接配置版本。 |
| `connected_by_user_id` | string | 建立连接的用户。 |
| `enabled` | boolean | 是否启用。 |
| `account_identity` | string | 平台账号关联身份。 |
| `desired_state` | string | enabled 或 disabled。 |
| `observed_state` | string | 接收器当前观察状态。 |
| `last_receive_at` | string | 最近接收时间，存在时返回。 |
| `last_error_code` | string | 最近运行错误代码，存在时返回。 |
| `callback_path` | string | 回调模式的当前部署相对路径，存在时返回。 |
| `created_at` | string | 创建时间。 |
| `updated_at` | string | 更新时间。 |

`starting/reconnecting` 表示建立或恢复连接中。`auth_failed/config_invalid` 需先修正凭据或配置。`connected` 只表示连接层状态；继续验证真实消息、目标任务与回复。`waiting_for_first_message` 表示等待外部首条输入；`stopped` 为停止状态。

创建 managed_stream 会启用并进入 starting，mail_polling 会等待输入，callback 初始停用。callback 的 `/test` 通过后会启用连接并增加 config_version，不是无副作用的读取。

### 托管凭据

| 平台组合 | 创建所需字段 | 更新所需字段 |
| --- | --- | --- |
| wecom / wecom_ai_bot | bot_id、secret | secret |
| slack / slack_app | app_id、app_token、bot_token | app_token 或 bot_token，可同时更新 |
| feishu / feishu_app | app_id、app_secret | app_secret |

Slack App Token 以 xapp- 开头，Bot Token 以 xoxb- 开头。不能混入其他平台字段。更新时不重传创建用的 App ID/Bot ID；平台账号身份与可轮换密钥分别处理。

### 回调校验的两类成功 HTTP 响应

校验成功返回连接对象；供应商通道测试未通过时，HTTP 200 还可能返回测试对象。后者包含 `ok:false`、`status`、`last_test_status`、`last_test_error`、可选错误分类/建议及 `last_tested_at`。不能只检查 HTTP 状态或直接当连接对象读取。

Telegram 校验会登记当前完整 HTTPS Webhook 地址。其他平台分支核验通道实例；具体失败通过测试对象或错误响应返回。托管和邮件轮询模式不使用这个校验动作。

### 企业微信扫码

扫码接口的 pending 响应包含 session_token、qr_url、expires_at。携带原令牌查询，同一账号、目标与工作区必须保持一致。authorized 后会返回 bot_id/secret，尚未保存真实接收连接；随后调用创建接口。expired 后结束旧会话，遵守 429/Retry-After，不无限轮询。此处的令牌和密钥只交给受保护客户端。

## 任务知识连接

| 变量 | 来源 |
| --- | --- |
| `MOI_ENDPOINT` | 当前任务注入的产品服务前缀；不要替换为另一个环境或终端保存的地址。 |
| `MOI_API_KEY` | 当前任务的技术连接凭据。 |
| `MOI_WORKSPACE_ID` | 当前任务所属执行工作区。 |
| `MOI_RUNTIME_AUTHORIZATION` | 当前任务注入的完整短期授权头值，保留原值。 |
| `REQUEST_ID` | 每次新操作生成的独立 ID；同一请求重放保留该 ID 与原输入。 |
| `KNOWLEDGE_QUERY` | 当前问题的有效检索文本。 |
| `ARTIFACT_ID` | 同一任务检索/查询产生的原始 artifact_id。 |
| `CHUNK_ID` | 所选文本证据的原始 chunk_id。 |
| `FILE_ID` | 同一文本证据的 file_id。 |
| `SEMANTIC_MODEL_ID` | 同一证据返回的实际整数模型 ID。 |
| `MARKDOWN_FILE_ID` | 证据中的解析原文定位 ID，不能用原文件 ID 推算。 |
| `TABLE_NAME` | describe-tables 的任务允许表名。 |
| `KNOWLEDGE_SQL_FILE` | 按已读结构与问题准备的只读 SQL 文本文件。 |
| `CITATION_SOURCES_FILE` | JSON 数组，保存当前回答实际采用的全部来源。 |

这些接口不能用普通 PAT 替代任务身份，不能在请求体中切换任务、用户或角色。request_id 须为 1–256 字节、无首尾空白、不以 audit: 开头。不能用新 ID 绕过同一操作的重放检查。

## 知识结果与读取模式

运行期知识成功 HTTP 包使用 code="OK"，data 包含 call_id、output、可选 failed/artifacts/metadata。failed 为 true 时仍是业务失败。所有输出均保留本任务证据身份，不能按名称重建文件、模型或产物 ID。

文本检索的完整段落保存在 artifacts[].data.chunks；读取时保留同一产物的 artifact_id 和段落 chunk_id/file_id/semantic_model_id。output 可能是有界视图，不能据预览或截断文本生成“已完整读取”的证明。

| 读取模式 | 输入 | 完成与后续 |
| --- | --- | --- |
| 单段证据 | artifact_id、chunk_id，必要时 file_id/semantic_model_id；整数 cursor | output.content 原文；has_more 为真时使用原 next_cursor 继续。 |
| 证据列表 | artifact_id，省略单段选择；显式传对象 cursor={item_index:0,content_offset:0} 开始 | output.items 为本页窗口；complete=true 表示读完，未完成时使用对象 next_cursor。 |
| 固定产物分片 | artifact_id、part_index | output.part 和 part_count；不与分段、字符分页或本地读取证明字段组合。 |
| 本地完整读取登记 | 单段身份及 local_content_sha256，或 local_reads 数组 | 服务器核验原始内容摘要后登记；不与分页参数混用。 |
| 解析 Markdown | markdown_file_id、整数 cursor | output.content；next_cursor=0 时结束，没有 has_more。 |

证据字符窗口有效范围为 1–8000，省略/0 使用 2000。游标按 Unicode 字符位置，不按 UTF-8 字节计算。Markdown 窗口的非正值使用 8000，最大 20000；它和证据窗口的默认值不同。

仅传 artifact_id 而不指定读取模式时，通用回读还可能返回产物对象和 part_count；不要据此假定进入证据列表分页。

单段本地读取证明需要 artifact_id/chunk_id 和完整内容摘要，file_id/semantic_model_id 用于定位；local_reads 每项提供这组字段和摘要，批量形式不与顶层单段字段同时提交。成功只表示该任务的原始段落已被完整登记，不能据此推断整个来源或知识库都读完。

解析原文从当前有效分段重建。持久化证据产物与当前解析原文投影承担不同用途；不能将“当前分段读取会反映删除/停用”扩展成所有历史产物都会重写。

### 检索和引用

普通 search 要求有效 keywords 和大于 0 的 max_hits。source_page 模式使用模型 ID、文件 ID、页大小与不透明游标，不能与普通检索字段混用；以 output.source_page.has_more 判断是否结束。按来源列出启用索引段落不是语义排名，也不证明未索引内容不存在。

图片检索返回 output.results、count 和适用的 mode，以及对应产物。查询图片 ID 与返回图片证据标识不能互换；API 参数不接收模型内部的 query_visual 或多图字段。

结构化查询限当前任务允许表上的只读 SELECT。结果包含实际 SQL、列名、行、行数、截断及来源产物；省略 semantic_claims 不会绕过服务器保存的强制语义条件。先读表结构和约束，再查询和选择来源。

cite 提交当前回答的完整来源集合；文本来源至少保留 type=rag_chunk、artifact_id、chunk_id 及原身份。没有依据时明确传 sources:[]。检查 output.accepted；未接受时补齐返回的未读窗口再选择。选择通过后仍需根据证据写回答。

## 错误与环境

消息接收业务成功包的 code 为数字 0；业务错误用数字 code/message/details.reason。准入层可能使用字符串 code/msg。运行期知识通常使用字符串 code/msg；HTTP 200 下的 data.failed 或 output.accepted=false 仍须单独处理。

能力列表只证明实现声明，不能证明环境就绪。回调校验和二维码请求可能调用供应商；需要临时账号、可控目标与反向清理计划。不要把一套环境的回调或任务授权复用于另一套环境。
