消息连接与知识读取对象¶
消息接收连接是工作区管理资源。运行期知识接口供当前智能体任务使用,需要该任务的身份、来源范围和短期授权。
连接与输入标识¶
变量 |
来源 |
|---|---|
|
当前环境的工作区和有对应权限的个人访问令牌。 |
|
目录中选定智能体的真实所属工作区与 ID。 |
|
当前目标可用的运行模型,agent 目标必须明确指定。 |
|
创建响应或同一目标连接列表的 id。 |
|
最新连接详情的 association_version。 |
|
最新连接详情的 config_version。 |
|
JSON 文件,保存所选平台创建托管连接所需的凭据对象;限制访问,不写入日志或仓库。 |
|
当前部署的完整 HTTPS 回调地址,路径与连接详情 callback_path 一致。 |
连接所属工作区与路径及 X-Workspace-ID 一致。团队目标属于该工作区;智能体目标属于当前或系统工作区,使用目录真实值,不能自行伪造空间标识。
消息接收连接¶
字段 |
类型 |
说明 |
|---|---|---|
|
string |
接收连接 ID。 |
|
string |
执行工作区。 |
|
string |
agent 或 team。 |
|
string |
目标所属空间。 |
|
string |
目标标识。 |
|
string |
所选平台。 |
|
string |
所选通道类型。 |
|
string |
managed_stream、callback 或 mail_polling。 |
|
string |
callback/mail_polling 引用的独立通道实例。 |
|
object |
可回读的非敏感平台配置。 |
|
string |
智能体目标选择的模型。 |
|
integer |
目标关联版本。 |
|
integer |
当前连接配置版本。 |
|
string |
建立连接的用户。 |
|
boolean |
是否启用。 |
|
string |
平台账号关联身份。 |
|
string |
enabled 或 disabled。 |
|
string |
接收器当前观察状态。 |
|
string |
最近接收时间,存在时返回。 |
|
string |
最近运行错误代码,存在时返回。 |
|
string |
回调模式的当前部署相对路径,存在时返回。 |
|
string |
创建时间。 |
|
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,不无限轮询。此处的令牌和密钥只交给受保护客户端。
任务知识连接¶
变量 |
来源 |
|---|---|
|
当前任务注入的产品服务前缀;不要替换为另一个环境或终端保存的地址。 |
|
当前任务的技术连接凭据。 |
|
当前任务所属执行工作区。 |
|
当前任务注入的完整短期授权头值,保留原值。 |
|
每次新操作生成的独立 ID;同一请求重放保留该 ID 与原输入。 |
|
当前问题的有效检索文本。 |
|
同一任务检索/查询产生的原始 artifact_id。 |
|
所选文本证据的原始 chunk_id。 |
|
同一文本证据的 file_id。 |
|
同一证据返回的实际整数模型 ID。 |
|
证据中的解析原文定位 ID,不能用原文件 ID 推算。 |
|
describe-tables 的任务允许表名。 |
|
按已读结构与问题准备的只读 SQL 文本文件。 |
|
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 仍须单独处理。
能力列表只证明实现声明,不能证明环境就绪。回调校验和二维码请求可能调用供应商;需要临时账号、可控目标与反向清理计划。不要把一套环境的回调或任务授权复用于另一套环境。