平台网页工具配置改进方案
日期：2026-09-09。状态：用户已确认方案；本仓独立部分实施中，全部参数仍待 Gateway 契约和联调。
目标与范围
改进现有 GatewayWebSearch / GatewayWebFetch，作为平台智谱搜索和网页读取工具。 用户通常只填写平台 vkey；可修改完整调用地址及业务选项。保留原智谱 BYOK 工具。 连接配置属于机器人配置，不进入 LLM 调用参数。
默认完整地址：
- Search：https://proxy.turingfocus.cn/v1/tools/zhipu_web_search/invoke
- Fetch：https://proxy.turingfocus.cn/v1/tools/zhipu_web_fetch/invoke
base_url 的字段说明明确为“完整工具调用地址”，直接 POST，不追加路径。
vkey 是平台凭据，使用 Authorization Bearer。新配置界面不再提供
gateway_url、tool_config_ref、gateway_api_key、gateway_api_key_env。
追踪与现状
建议复用 TFRS-412（已在进行中），父级 TFRS-411；不重复建立 Server 任务。 TFRS-412 原验收明确只开放部分选项，需在方案确认后更新为本次最终范围。 TFRM-566 负责配置迁移，TFRS-414 负责末端集成验收，需同步新字段契约。 Gateway 参数扩展应先检查是否有等价任务，再建立关联实施项；本文附上可转交请求。
证据为本地代码及 2026-09-09 读取的 Jira：
tfrobotserver/robot/extensions/drive/tool/gateway_web.py：根地址校验、路径拼接、请求转换、幂等。tfrobotserver/robot/factory/drive/tool/gateway_web.py：目前两个工具共用配置类，缺少分别的默认地址。../tfrs-llm-gateway/adapters/tool_websearch_zhipu.py:172：调用选项只有 count/content_size/recency。../tfrs-llm-gateway/adapters/tool_webfetch.py:170：allowed_invocation_options 为空。- TFRS-411 / TFRM-566 记录两个默认 ref 已在 beta 发布；本次未重新验证线上状态。
业务参数与依赖
“对齐原智谱工具参数”包括配置字段，不表示把所有配置都变成 LLM 参数。 原工具业务配置默认值与 Gateway 默认值存在差异，不能直接复制后宣称行为等价。
| 原工具字段 | 当前平台支持情况 | 计划 |
|---|---|---|
| search_query | 映射 input.query，1–70 字符；原工具原允许至 200，本次按官方修正为 70 | 保持平台 70 字符限制并明确说明，放宽需上游确认 |
| count、content_size | 调用 options 已支持 | 新增对应机器人配置，保留现有可选调用覆盖 |
| search_recency_filter | 调用字段名为 recency | 配置沿用原工具命名，发送时映射 recency |
| search_engine | 平台固定 search_std，其他原工具引擎未开放 | Gateway 扩展并验证后开放 |
| search_intent | 平台固定 false，原工具原默认 true，本次按官方改为 false | Gateway 扩展并验证后开放，不能发送原默认值到旧契约 |
| search_domain_filter | Profile / 调用均未列出 | Gateway 补充透传和校验后开放 |
| return_format、no_cache、retain_images、no_gfm | 仅平台配置可设置 | Gateway 开放调用覆盖后开放 Robot 配置 |
| keep_img_data_url、with_images_summary、with_links_summary | 仅平台配置可设置 | 同上 |
| fetch_timeout | 平台 timeout 为 1–60 秒，原工具 1–300 秒 | 映射 timeout，最终范围以双方确认契约为准 |
| request_timeout | Robot HTTP 超时 | 继续本地处理，不当成 Provider 抓取超时 |
兼容阶段：业务配置不填写时省略对应 options，让平台继续使用已发布配置。 已支持搜索选项优先级为显式调用值 > 显式机器人配置 > 平台默认。 现有 LLM 调用参数 recency 保留；其他 Provider 选项只作为机器人配置，除非后续明确批准扩大 LLM 参数面。 上游未支持的字段不提前以可用字段发布，不静默吞掉；全参数未联调完成不能关闭整个需求。
本仓实施设计
- 共用连接校验和客户端；Search/Fetch 分别定义默认完整地址及业务配置。 工厂 Draft/Template/Online 复用运行时约束，保留现有 Setting 注册名称与工具标识。
- URL 校验改为完整 HTTP(S) 调用地址校验，拒绝内嵌凭据、查询和片段； 支持代理前缀，但要求路径以 /v1/tools/{ref}/invoke 结尾，以便从路径确定配置引用。 ref 不再作为用户字段，而是内部从已校验的地址提取。
- 保持原有 hash([ref, current_tool_call_id]) 幂等算法，避免仅迁移连接配置就改变已有调用身份。 地址在一次调用中固定；不自动换地址、不重试、不跟随重定向。
- 新配置仅使用显式 vkey。旧持久化配置通过输入兼容层转成完整地址和新密钥字段； 如旧配置依赖自定义环境变量引用，保留内部旧配置读取语义直到迁移，不能在序列化时自动固化环境密钥。 旧字段不重新出现在新表单 schema。新旧字段冲突时明确拒绝，不能猜测使用哪份凭据。
- 复用 ToolReturn 转换、失败处理与 UI 卡片格式；保留结构化错误和 invocation ID。
- 接收 Gateway 扩展的最终契约后补齐剩余参数，并更新说明与迁移示例。
文件与实施顺序
| 文件 | 改动 |
|---|---|
| tfrobotserver/robot/extensions/drive/tool/gateway_web.py | 完整地址、vkey、分工具配置、旧配置输入兼容、options 转换 |
| tfrobotserver/robot/factory/drive/tool/gateway_web.py | 分工具三态配置、默认地址、表单字段和配置验证 |
| tests/unit_tests/robot/extensions/drive/tool/test_gateway_web.py | 请求路径/鉴权/参数/错误/幂等/旧配置兼容 |
| tests/unit_tests/robot/factory/drive/tool/test_gateway_web_factory.py | 三态默认值、schema 不泄漏旧连接字段、注册兼容 |
| tests/integration_tests/robot/factory/drive/tool/test_gateway_web.py | 真实 PG 保存发布构建、旧配置兼容 |
| tests/integration_tests/robot/factory/drive/tool/test_gateway_web.py（扩展） | 真实 HTTP socket 验证完整地址；平台 Gateway 联调仍属外部验收 |
| docs/gateway-web-tools.md | 配置说明、参数范围、迁移方式、验证状态 |
先实施不依赖上游的完整地址/vkey及已支持选项，随后接入经确认的扩展契约。 不修改其他仓库代码；本仓 CLAUDE.md 明确其他仓库仅供只读参考。
验证与验收
- 单测：默认地址、自定义地址直接 POST 无重复路径、Bearer 凭据、非法 URL、配置冲突、缺凭据错误。
- 原有幂等、403、409、超时、同步/异步和 BYOK 回归。
- 三态 schema/序列化/注册；真实 PG 验证草稿保存→发布→构建，验证旧格式可读取。
- 实际 Gateway HTTP 路由联调：搜索→读取，业务选项效果、未授权及非法选项错误。 不能以 mock transport 代替所修改的跨仓契约验证。真实 Provider 联调需要测试环境和具备工具权限的测试 vkey。
- 使用定向 Ruff/MyPy 和相关测试；新增真实设施用例必须实际通过，缺少设施时记录未通过原因。
- 实现后执行 add-feature 要求的隔离上下文只读子代理审查；修复阻塞项后复审。
- 部分 Server 改进完成不等于全参数功能完成，不关闭 TFRS-411 / TFRS-414 或未完成的本任务。
可转交 Gateway 的 Feature Request 草案
请求方：TFRobotServer / TFRS-412；关联目标：TFRS-411。优先级：P1，阻塞“完整智谱业务参数”部分。
用户需要在平台搜索/读取工具里调整与原智谱工具相同的业务选项，仍由平台鉴权、计费和执行。 目前仅搜索三个选项可由调用者覆盖，读取完全不能覆盖，无法兑现完整参数配置体验。
期望能力：
- 上述参数矩阵中未开放的选项能在允许的权限与平台策略下由调用者设置，并产生对应效果。
- 不支持或被平台禁止的选项返回明确错误；不得接受后忽略，也不能绕开平台授权或计费治理。
- 不传选项保留已发布配置行为；确认默认值、限制和旧客户端兼容策略。
- 确认现有默认 search/fetch 路由可使用新能力，或提供版本/迁移方案。
技术建议（由 Gateway 团队评审决定）：扩展 options 白名单及 Profile 类型/范围，落实 Provider 参数映射； 复用现有 /v1/tools/{ref}/invoke、工具 scope、幂等、审计及计费链路。
交付要求：最终接口与参数文档、配置覆盖优先级、鉴权说明、错误码、默认值/限制差异、 兼容及版本变更说明、可运行的联调环境与测试证据。收到回复后据其最终契约实施 Server 剩余部分。
待确认
按以上顺序实施：复用 TFRS-412，先完成 Server 可独立部分，保留完整参数为上游依赖； 本文件的 Gateway 请求草案由用户转交或另行明确授权发送。用户已确认本方案；Gateway 请求草案尚未发送。
官方文档核对与追加范围（用户已授权，2026-09-09）
核对 智谱搜索接口 和 智谱网页读取接口。 文档未提供这些字段的逐项变更日期，以下为当前契约差异，不宣称均为近期新增。
- 原生 Search：搜索词最多 70 字符；新配置默认关闭意图识别；搜狗数量限制为 10/20/30/40/50；域名与时间过滤同时设置时 count 不生效，补充配置说明。
- 原生 Reader：新配置默认保留图片。原有缓存、格式、图片及摘要选项仍在官方文档中，没有确认新增业务选项。
- 显式保存的旧 search_intent / retain_images 值继续保留；省略字段使用新的官方默认值。
- 平台 Search 复用原生搜索词字段约束。平台现有 Profile 的意图默认 false、读取图片默认 true 已一致；不把原生完整参数发送到未开放的 Gateway options。
- 官方 Reader 文档未声明 timeout 的上限；原生 300 秒与 Gateway 60 秒是当前实现限制，不能当成官方限制。request_id/user_id 属于请求追踪/用户标识，不作为固定业务工具配置或 LLM 参数新增。
追加文件：原生 Search/Reader 的 extensions 和 factory 文件及对应既有单测。 验收包括实际 SDK 请求构造验证默认值、70/71 字符边界、搜狗数量发布校验和显式旧值保留。 Gateway 协作请求同步以本节当前默认值/限制为依据，仍等待上游最终契约。
本仓验证记录
- 定向测试：102 passed，包含 Gateway、原生 Search/Reader 运行时与工厂单测，以及 11 项真实 PG 集成测试。
- PG 使用本次临时创建的本地实例，不重置已有数据库。两个完整地址用例经真实 HTTP socket 验证，但服务端为本地测试 handler，不能替代平台 Gateway/Provider 验收。
- 旧草稿原始 JSON 经 ORM 恢复、再次保存、补齐后发布已通过。
- 原生默认参数经实际 zai-sdk 构造请求并用 mock transport 核验。
- 6 个源文件定向 MyPy（--follow-imports=silent）通过；改动 Python 文件 Ruff lint/format 通过。
- 首轮隔离审查发现旧未完成草稿兼容问题，已修复并增加回归；最终隔离复审 APPROVE，无阻塞项或新增建议。
- 代码未提交、未推送、未部署。TFRS-412 保持进行中；Gateway 全参数扩展及 TFRS-414 真实平台末端验收仍未完成。