SuperAPI AI 工具集

baiducloud-gateway

通用与其它

查看项目

更新于 11-10 06:15

技能介绍

用途与定位

baiducloud-gateway 是面向所有 baiducloud-* 与 qianfan-* 技能的前置调用网关。按资料要求,应在调用其他任何 baiducloud-* 或 qianfan-* 技能之前立即运行一次 gateway.mjs,并在目标技能执行结束后再运行一次以上报结果。qianfan-* 技能随 qianfan CLI 分发、不经过 baiducloud-qianfan,此类情况需使用 --source-layer qianfan-cli,并先执行 qianfan-gate 账号检查。

网关做两件事,且始终 fail-open,不阻塞真正的工作:

  1. 更新检查:通过通用 Skills CLI 查询目标技能是否过时,若已过时则提醒用户重新安装。
  2. 归因上报:向独立远端端点发送一条脱敏事件。请求使用本地 OAuth/STS 凭据签名,后端经 IAM 从签名解析账号 id(aid);客户端从不发送 aid 或任何原始凭据。

主要能力

  • preflight:调用前执行更新检查并生成归因事件,输出 attribution.event_id / session_id / turn_id。会话首次调用省略 --session-id,一轮对话首次调用省略 --turn-id,后续调用需回传已生成的值。
  • report:技能结束后(无论成功失败)提交结果报告,通过 event_id 与 preflight 事件关联。成功时携带响应 http status 与 request id;失败时额外提供 error-category / error-code。
  • check-update:单独执行更新检查。对 bce-cli 或 qianfan-cli 执行层做 CLI 二进制更新检查,只读、缓存 24 小时,输出 cli_update {tool, current, latest, available, upgrade_command};设置 GATEWAY_CLI_UPDATE_DISABLE=1 可跳过。脚本本身不升级,由 Agent 按网关规则执行 upgrade_command。
  • --dry-run:仅查看签名请求而不实际发送。

上报字段

aid 不由客户端发送,由服务端通过签名请求中的 STS token 经 IAM 解析。caller_type 在用户明确选择并调用技能时为 human,否则默认 ai_agent,可通过 --caller-type 或 BAIDUCLOUD_SKILL_CALLER_TYPE 设置。caller_name 为宿主 Agent(如 claude、codex、comate),可通过 --caller-name 或 BAIDUCLOUD_SKILL_CALLER_NAME 设置,默认 unknown。skill_name 为承载能力的技能名,如 baiducloud-cli。source_layer 为执行层,取值 bce-cli / openapi-runtime / qianfan-cli(另有 bcecmd)。event_id 格式 bcs-e-{uuid},每次技能调用一个,用于关联调用前后报告。session_id 格式 bcs-s-{uuid},每段会话一个;turn_id 格式 bcs-t-{uuid},每个用户轮次一个。event、intent、operation、outcome、error_category、error_code、http_status、request_id 用于意图分布与失败原因分析;http_status(100-599)与 request_id 在每次结果报告中都要带上,便于后端关联日志、定位失败详情;error_category / error_code 仅失败时使用。这些字段只接受枚举或短标识符,绝不包含用户原文、错误消息、资源 id、IP 或参数值;无效值会被丢弃并在 ignored_fields 中按字段名列明。请求 User-Agent 仅携带产品令牌 BaiduCloudSkill/1.0。

使用方式(示例)

调用前: node scripts/gateway.mjs preflight --skill baiducloud-cli --source-layer bce-cli --caller-type ai_agent --caller-name comate --intent query --operation bcc.ListInstances

成功结果报告: node scripts/gateway.mjs report --skill baiducloud-cli --source-layer bce-cli --event-id <attribution.event_id from preflight> --session-id <attribution.session_id> --turn-id <attribution.turn_id> --outcome success --http-status 200 --request-id <requestId from the response>

失败结果报告: node scripts/gateway.mjs report --skill baiducloud-cli --source-layer bce-cli --event-id <attribution.event_id from preflight> --session-id <attribution.session_id> --turn-id <attribution.turn_id> --outcome failure --error-category permission --error-code AccessDenied --http-status 403 --request-id <requestId from the error response>

仅上报或仅检查更新: node scripts/gateway.mjs report --skill baiducloud-openapi --source-layer openapi-runtime node scripts/gateway.mjs check-update --skill baiducloud-cli

CLI 更新检查: node scripts/gateway.mjs check-update --skill qianfan-chat --source-layer qianfan-cli

查看签名请求而不发送: node scripts/gateway.mjs report --skill baiducloud-cli --source-layer bce-cli --dry-run

安全与控制

  • 上报只发送至 https 百度云主机(白名单,不允许裸 IP,不允许 user:pass@ 形式的 userinfo);端点不合规则跳过而非强制发送。发送前解析主机,若指向私有/保留地址则拒绝。
  • BAIDUCLOUD_SKILLS_TELEMETRY_ENDPOINT 可覆盖端点,默认值为 https://cloud.baidu.com/api/baiducloud_skill/behavior。
  • BAIDUCLOUD_SKILL_REPORT_DISABLE=1 可关闭发送。
  • BAIDUCLOUD_SKILL_REPORT_DEV=1(仅开发用)额外允许 http(s) 回环端点(localhost / 127.0.0.0/8 / ::1),便于向本地 scripts/report_sink.mjs 自测;仅对该回环目标绕过 DNS 全局 IP 防护,默认关闭。
  • 从不读取、复制或打印 OAuth 凭据文件内容;凭据仅随标准签名头传递。
  • 所有失败(无登录状态、网络错误、缺少 Skills CLI)均 fail-open,绝不阻塞下游技能。

强制前置规则安装

如需强制“始终先运行网关”,可将 references/gateway-rule.md 中的 always-apply 规则安装到宿主 Agent 规则目录。在该技能目录运行 node scripts/install_rule.mjs:会向所有检测到的宿主写入规则(Comate ~/.comate/rules/、Claude Code ~/.claude/rules/、Codex ~/.codex/AGENTS.md),无需确认,幂等,且不会通过符号链接写入或覆盖非其创建的文件。--project <dir> 添加 Cursor 项目规则,--host 显式选择宿主,--dry-run 预览,--uninstall 卸载。

适用场景与限制

适用于调用百度云相关技能、需要检查技能/CLI 版本并上报脱敏调用归因的智能体工作流。限制在于:只面向百度云系列技能,不支持其他产品的技能调用;上报仅限枚举与短标识符,不能借此传递业务数据;默认端点与开关受环境变量控制;资料未提供收费、价格和具体平台兼容性信息。