消息连接与知识读取对象

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

连接与输入标识

变量

来源

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 仍须单独处理。

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

最后更新于