联枢:接口与工具

记录、排查与边界

调用请求、调用日志和审计在哪,常见问题怎么处理,以及目前做不到的事。

调用请求、调用日志与运行概览

「调用请求」在「接口与工具(联枢) › 调用与审批」组下,「调用日志」「运行概览」「操作审计」在「接口与工具(联枢) › 运行记录」组下。

页面用途
调用请求查看需要审批的调用请求,默认显示待审批。可按状态和「调用方式」(逐次审批、直接调用、工作流步骤)筛选。点「查看详情」(抽屉标题「冻结请求详情」)看工具、方法和路径、调用者、状态、有效期和参数表,完整的冻结内容收在「原始冻结请求」里。待批或已批准未执行的请求可以撤销,需要填写 2 到 200 字的原因
调用日志每次实际调用的结果、耗时和已脱敏的参数,可按工具编号、目标或调用者编号搜索。「导出 CSV」按当前搜索导出最新的记录,内容已脱敏,最多 1 万条、2 MB,每次导出都记审计。上游返回错误时,结果列显示「上游 HTTP 502(响应已脱敏)」(502 为示例状态码),被截断时加「,截断至 2 KB」。点「查看详情」,在「证据」里看上游错误体(前 16KB 脱敏,再截到 2KB),只对管理员可见
运行概览选「最近 1 小时」「最近 24 小时」或「最近 7 天」,按工具看调用次数、错误数和错误率、P50 和 P95 耗时,以及趋势线。失败和结果待核验都算错误。限额拒绝的调用不计入,要到「操作审计」查
操作审计记录联枢里的配置变更、撤销、拒绝和限额拒绝等事件,是追加写入的哈希链,不受保留期影响。入站事件、触发、轮询和超期也各有记录,其中每收到一条非重复事件写一条「接收入站事件」。登录、Key、授权和 Agent 调用的平台审计在控制台的「审计日志」

「调用请求」「调用日志」「操作审计」是游标分页,页脚按「最新 / 较新 / 更早」翻页,每页 10、20 或 50 条,默认 20 条。调用者和审批人显示「接入中心 › Agent 与密钥」里的名称和短 ID。已结束的调用请求和调用日志默认保留 30 天(ECHOMIND_INTEGRATIONS_REQUEST_RETENTION_DAYS、ECHOMIND_INTEGRATIONS_LOG_RETENTION_DAYS,0 表示永久保留),默认的 compose 不会把这两个变量传进容器,要在部署的 compose 里另行传入。待批、执行中和结果待核验的请求永远不会被自动删除。

日志与排查

联枢自己的记录在面板里:「调用日志」「调用请求」「运行概览」「操作审计」和「计划与执行」。常见问题如下。

现象原因与处理
保存连接时提示地址不在允许来源内,或提示服务端尚未配置允许的来源请部署管理员把这个来源加入 ECHOMIND_INTEGRATIONS_ALLOWED_ORIGINS。使用令牌端点时,它的来源也要加入。
INSECURE_ORIGIN明文 http: 来源还要列入 ECHOMIND_INTEGRATIONS_INSECURE_ORIGINS。
EGRESS_DENIED(出站策略拒绝)地址解析到了回环、私网等受限网段。把它列入 ECHOMIND_EGRESS_ALLOW。
启用工具被拒绝,提示缺少访问权限说明(CREDENTIAL_SCOPE_REQUIRED)回到「上游连接」,填写访问权限说明。
测试连接未通过401 和 403 之外的响应才算可达。检查服务地址、凭据、令牌端点和 CA 证书。
STDIO_NOT_REGISTERED,或保存 stdio 连接时提示服务端没有登记服务请运维在 ECHOMIND_INTEGRATIONS_STDIO_SERVERS 里登记,再刷新面板。
MCP_STDIO_BUSY、MCP_STDIO_EXITED同一服务的进程数已满,或子进程崩溃。后者标准错误输出的末尾 2KB 脱敏后进入调用日志,下一次调用会自动启动新进程。
MCP 工具没有出现连接要先启用,再在行上「更多」里点「同步工具」。同步来的工具默认停用,要审核后启用。
Agent 看不到某个工具检查是否授予了该工具的「查看目录」、工具是否已启用、所属连接是否启用。能力组只显示已发布的。
INVALID_SCHEMA(参数格式错误)契约用了子集之外的关键字,或根节点不是 object。按「参数契约」一节修改。
BUDGET_EXCEEDED(超出调用限额)消息里写明哪一项和重置时间。限额拒绝不进调用日志,在「操作审计」里查。调整限额要改工具的「调用限额」。
RESULT_TOO_LARGE投影后的结果超过 96KB。减少返回字段,或改用分页聚合。
APPROVAL_STALE(审批已失效)计划过期,或工作流、工具、连接、调用者授权在期间变了。让调用者重新生成计划。
CALLER_UNRESOLVED(无法确定调用者身份)工具用了调用者身份,但调用者是服务 Agent、管理员,或人员没有登记对应的工号或外部 ID。
调用被直接拒绝,提示没有人能审批在「授权管理」里给人员、岗位角色或单位授予「审批」,并确认 Agent 有归属人员。
写操作显示「结果待核验」请求发出后没有确认结果。不要重复提交,先到上游系统核实,再处置。
运行已暂停,待处置在「计划与执行」里看暂停原因。处置在审批页进行,管理员只能终止。
事件到了但工作流没启动或没继续触发规则对应的工作流改过后要重新保存规则。服务 Agent 的授权要齐全。等待步骤要先处于等待中,事件先到不会补匹配。关联键必须相同。
定时任务暂停了连续 3 次未成功会暂停,在列表里「恢复」。检查运行身份是否仍是活跃的人员,以及限额。

备份联枢时,请同时保存数据库和状态目录里的加密密钥文件(国际套件是 encryption.key,国密套件是 encryption.sm4.key)。丢失后,已保存的上游凭据无法解密。文件放在 S3 兼容对象存储时,对象由对象存储自己的版本和备份策略负责;启用了客户端加密时,状态目录里的 blob.key(国密套件是 blob.sm4.key)也要备份。

目前的边界

  • 协议:HTTP 只支持 JSON 请求和响应,文件上传和下载除外。GraphQL 只支持固定文档,不支持 subscription,不支持调用者身份和分页聚合。MCP 支持工具的发现和调用,不支持旧的独立 SSE 入口,也不支持 resources、prompts 和采样等服务端主动交互。
  • 认证:不提供需要用户交互的 OAuth 授权码流程。需要短信、动态口令或验证码的登录不适用。生产 SSO 和多租户账户不在范围内。
  • 契约:参数契约只支持有限的 JSON Schema 子集,没有 $ref、pattern 和 format。
  • 工作流:不执行代码,没有表达式语言,执行条件只有四种判断,条件之间只能是「并且」。最多 30 步,条件最多 5 条,批量输入最多 200 条。含等待步骤的工作流不能设为定时任务。
  • 写操作:写步骤的结果不明时,联枢不会自动重发。没有声明幂等键的写步骤,不能重试,只能核实后处置。终止运行不会回滚已执行的步骤。
  • 管理员权限:平台管理员不能批准任何调用、计划或批次,只能撤销待批项和已批准未执行的项,以及终止暂停的运行。
  • 本地 stdio:面板里不能登记或托管任意本地进程。stdio 子进程不受出站策略约束,运维要自行做好隔离。
  • 轮询:每次最多 500 条、100 个事件,不翻页,只看得见轮询时刻的状态,中间状态会丢失。
  • 数量:每个联枢最多 100 个连接、500 个工具、50 条轮询、200 个工作流、100 个能力组、500 个调用模板、100 个定时任务、200 条触发规则,OpenAPI 导入每次最多 100 个操作。联枢没有提供长期合规日志的承诺。
  • 真实上游的验证范围:有记录的真实上游验证包括本地的协议实验服务和两个公开的只读服务(DeepWiki 的 MCP、GitHub REST)。企业私有的认证方式、各平台的令牌换取和机器人签名、生产写接口,都需要按目标服务另行验证后再上线。钉钉、飞书的入站事件没有在真实租户上验证。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。