Tianyi Cui
3ca9c7d489
Rename the tool-presentation transport from code-mode to ptc everywhere that is not written into session logs: the mode config value becomes 'ptc', the preset directory/id becomes ptc, the demo becomes demo:ptc, the dispatch waterfall becomes tools/ptc-dispatch-log (types PtcDispatch*), the prompt rule becomes tools:ptc-only, source/test files become ptc.ts etc., and prose says PTC mode / PTC 模式. The session-persistent vocabulary (durable events tool/code-dispatch*, logged plugin name tools-code-mode, sub-call id segment :code:) intentionally stays and moves in the stacked persistence PR, which is blocked until the SESSION_FORMAT_VERSION v0→v1 migration lands with it. run_code, its code parameter, CodeSdkLanguage, CodeRunFailedError, the dsh-code-runtime family, third-party codex names, and frozen archived notes keep their names.
6.0 KiB
Agent Note: 已交付组合中的默认 Web 搜索
Status: implemented
English | 中文
问题
该 harness 已具备完整的 Web 能力体系：提供方注册表、DeepSeek、Exa 和 Perplexity 搜索提供方、本地抓取、稳定的面向模型工具，以及结构化结果呈现，但已交付的 dsh web 组合没有挂载其中任何一项。除非部署提供自定义覆盖层，否则模型无法发现最新信息。仅挂载现有 DeepSeek 提供方仍无法打通 WebUI 链路：Models 页面通过 ctx.credentials 存储 DEEPSEEK_API_KEY，而搜索提供方只会在插件加载时固定读取进程环境，因此在运行中的 UI 输入或轮换的密钥无法用于搜索。
决策
apps/cli/config/base.cordis.yml 明确挂载 dsh-web，配置 searchProvider: deepseek-official 与 fetchProvider: http，同时挂载 dsh-web-search-deepseek、dsh-web-fetch-http，并以 fetch: false 和 searchTimeoutMs: 60000 挂载 dsh-tool-web。因此，共享 base 只会暴露 web_search，除非产品 preset 启用抓取；已交付的 Web cordis、ptc 与 standard preset 会启用抓取。显式提供方 id 使选择不受注册顺序影响，同时个人覆盖层或 --config 覆盖层仍可替换或禁用这些配置项。已交付的一分钟预算用于覆盖一次辅助 DeepSeek Messages 请求及服务端检索，同时保持 dsh-tool-web 提供方无关的 30 秒默认值不变，以供自定义组合使用。Web 能力 seam 决策负责公开抓取安全策略与 Web preset 默认值。
DeepSeek 搜索使用与官方会话适配器相同的 DEEPSEEK_API_KEY 凭据引用。提供方在每次搜索内部通过可选的 ctx.credentials 服务解析该引用；只有未挂载该 seam 的组合才会回退到启动进程的环境变量，非空的 apiKey 字面值仍作为程序化配置的最后兜底。因此，由 Web 的 Models 页存储或轮换的密钥无需重启即可用于下一次搜索，提供方也无需保留该值。由于 WebSearchProvider.available() 是同步方法，它会将已安装解析器视为本地可用；若动态凭据缺失，操作会以提供方专属错误码 WEB_PROVIDER_CREDENTIAL_MISSING 失败，而稳定的工具 schema 仍保持注册。
搜索端点与 chat completions 保持独立：DEEPSEEK_SEARCH_BASE_URL 覆盖 Anthropic 兼容基址，DEEPSEEK_BASE_URL 则继续配置会话请求。每次 web_search 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 web/deepseek-search-llm-request，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
默认挂载不会创建 Web 专用权限策略。web_search 与已启用的 web_fetch 调用会在 bash／文件系统沙箱及审批 preset 之外执行，并遵循 dsh-tool-web 的现有约定。HTTP 提供方把抓取限制到已验证的公开目的地址，但不限制公开数据出站。已交付的 workspace-write 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 tools/pre-execute 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
考虑过的替代方案
仅挂载 dsh-tool-web。 不予采纳：稳定的 schema 如果没有已注册提供方，每次默认调用都会失败。启用状态与后端可用性刻意分离，但已交付的默认配置必须提供其预期实现。
从 cordis.yml 读取 $DSH_HOME/.env，或将其提升到 process.env。 不予采纳：凭据提供方拥有该文件，环境变量值是只读覆盖；提升后存储的密钥将无法轮换，还会绕过经审计的密钥边界。
在提供方加载时固定读取 process.env.DEEPSEEK_API_KEY。 不予采纳：Web Models 页面通过 ctx.credentials 写入密钥；产品文档规定的首次运行路径必须保证下一次操作无需重启即可生效。
将 Web 工具保留在 web.cordis.yml 中。 不予采纳：这会保留 TUI 与 Web／无头界面之间无法解释的工具清单差异。这些配置行并非界面特有，因此其唯一归属是 base.cordis.yml；工具清单决策记录了这一共享组合。
提高 dsh-tool-web 的提供方无关超时。 不予采纳：自定义提供方和部署有各自不同的延迟预期；这一部署预算应归已交付的 DeepSeek 组合所有。
在每个共享 base surface 上启用抓取。 不予采纳：共享 base 服务于网络策略不同的产品。它会挂载仅限公网的提供方，但保持工具按需启用；已交付的 Web preset 会有意启用该工具，其他产品则可以继续隐藏它或添加更严格的网络策略。
后果
每个共享 base surface 的原生模型请求都会携带 web_search schema 与搜索指引；Web／无头 PTC 模式 通过 run_code 公开相同的搜索能力。搜索会增加一次完整的辅助模型调用，并可能多次使用原生服务器工具；发起会话的日志仍可精确重建其不含密钥的请求。已交付的 Web cordis、ptc 与 standard preset 还会暴露 web_fetch，实施公开地址强制校验且无需逐次审批。Web 快照通道会启动已交付配置树，使用本地 Messages fixture（测试前置数据），经由真实 DeepSeek 提供方驱动一次回放的 web_search 调用，断言持久化的辅助请求与结构化结果，并固定最终浏览器呈现。组合冒烟测试会固定共享搜索清单与各 preset 的抓取选择；构建后组合配置的转储固定已交付的一分钟搜索预算；提供方测试固定缺失、已存储及已轮换凭据的行为，以及字面值与环境变量的兼容性。