Skip to content

Hosting Zhipu 平台网页工具（TFRS-412 / TFRS-413）

工具名称为 HostingZhipuWebReader 和 HostingZhipuWebSearch。 草稿工厂为 HostingZhipuWebReaderDraftSetting 和 HostingZhipuWebSearchDraftSetting， 分别对应同名前缀的 Setting / TemplateSetting。旧 GatewayWeb*Tool*Setting 标识仍可加载， 已有常用工具栏引用会转换为新名称。原生 ZhipuWebReaderToolSetting、ZhipuWebSearchToolSetting 继续使用 Provider BYOK 契约。

两个工具分别默认调用平台完整地址，无需填写根地址或工具配置引用：

{
  "base_url": "https://proxy.turingfocus.cn/v1/tools/zhipu_web_search/invoke",
  "vkey": "<具备该工具权限的平台 vkey>",
  "count": 10,
  "content_size": "medium",
  "search_recency_filter": "oneWeek",
  "request_timeout": 130,
  "merge_context": true
}

Search 默认地址如上；Fetch 默认地址为 https://proxy.turingfocus.cn/v1/tools/zhipu_web_fetch/invoke，不接受搜索配置字段。 base_url 是完整调用地址（不是 SDK 基础地址），直接 POST，不追加路径。 支持 HTTP(S) 和代理路径前缀，路径须以 /v1/tools/{ref}/invoke 结尾； 禁止内嵌凭据、查询或片段。内部从路径提取 ref 维持幂等身份。 默认 ref 的线上可用性及授权仍由实际 Manager 发布结果决定。

vkey 必须具备 tool_config:<ref> scope，不是 Provider Key。 新配置不读取环境变量。旧格式 gateway_url + tool_config_ref + gateway_api_key / gateway_api_key_env 仍可读取，转换为完整地址和 vkey； 新旧连接字段不能混用。旧环境变量引用保留为内部兼容字段 legacy_gateway_api_key_env，不显示于 JSON Schema 表单，且不会在保存时展开为密钥。 旧引用继续在运行时读取，因此支持密钥轮换；显式 vkey 优先。 更新旧配置时应保留内部引用字段，或在迁移时填写显式 vkey 后移除引用。 缺少凭据可保存草稿、发布配置和生成 schema，实际调用返回配置错误。 连接配置仅应由可信配置管理员管理；自定义地址会收到所配置的 vkey。

WebFetch 的 LLM 参数为 url。WebSearch 保留 search_query（1–70 字符）及可选 count、content_size、recency。Search 新增机器人配置 count（1–50）、 content_size（medium/high）、search_recency_filter（映射 recency）。 优先级：显式调用参数 > 非空机器人配置 > Gateway 已发布配置。 机器人配置默认留空，维持平台默认行为；不会擅自复制智谱 BYOK 的不同默认值。 地址、vkey 和其他连接配置不进入 LLM 参数。

完整智谱参数仍在等待 Gateway 扩展契约：搜索引擎、域名过滤、意图改写及 Reader 格式/抓取超时/缓存/图片选项目前不暴露，也不静默丢弃。 不能把原生工具配置整包复制到托管工具。参见 gateway-web-tools-feature-plan.md 的参数矩阵和上游请求草案。 Profile 由平台控制；Robot 不持有内部控制面凭据，不修改 ZAI_BASE_URL，不添加 Provider 计费事件。

工具通过 Drive 获取持久化 ToolCall.call_id（运行时 current_tool_call_id）， 结合工具配置引用计算 64 位十六进制 SHA-256 幂等键。调用者重试同一逻辑调用时必须 复用原 ToolCall，不能重新创建调用 ID；缺失该 ID 时拒绝出站。HTTP 客户端不自动重试、 不轮询、不跟随重定向。409、interrupted、超时和网络失败保留原键，不能换新 ID 来“恢复”未知结局。新的用户调用必须使用新的 ToolCall。

ToolReturn.origin 保留现有网页/搜索结构，新增 gateway.idempotency_key， 有 Gateway invocation ID 时包含 gateway.tool_invocation_id；失败保留结构化 origin.error。msg_meta.success=false 的已完成工具事件记为 failed， done=false 为 running。缺失 meta 或无法解析的旧返回保留按事件名判定的兼容行为。 失败返回继续进入 Socket/历史查询共用 DTO，异常和取消仍分别为 failed / aborted。 不回写历史轨迹。

本仓验证包含 HTTPX 请求/响应契约、Drive 重建幂等、BYOK 回归、三态工厂和真实 PostgreSQL 发布及轨迹持久化。真实 beta Provider 搜索→读取、授权迁移、回退和计费 验证属于 TFRM-566 / TFRS-414；前端展示属于 TFRF-141。配置消费者可据本文件准备迁移， 不需要等待这些任务才能合并 Server 代码。

2026-09-09 原生工具官方契约对齐

原生 Search/Reader 的当前官方默认值和限制已核对，详细来源见 方案中的官方核对记录。 Search 搜索词最多 70 字符，新配置 search_intent 默认 false；搜狗 count 只允许 10/20/30/40/50。 Reader 新配置 retain_images 默认 true。既有显式值保留，省略值采用新默认。 平台仍使用已发布 Profile 的默认值，不擅自覆盖平台治理设置。

未完成的旧草稿可以继续读取和保存；部分 root/ref 以内部 legacy_incomplete_connection 保留， 已有 root 会显示为待补齐的调用地址。补齐有效完整地址及其他必需配置后方可发布。