dsh-web-search-enhanced 0.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 dsh-web-search-enhanced contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,77 @@
+# dsh-web-search-enhanced
+
+<strong>dsh-web-search-enhanced</strong> 是一个第三方 DeepSeek Harness <code>ctx.web</code> 搜索提供方。它保留模型看到的原生 <code>web_search</code> 工具与 <code>WebSearchResult</code> 输出，但允许 Web Profile 在三种上游协议之间切换：Anthropic Messages v1、OpenAI Responses API 和 OpenAI Chat Completions API。
+
+## 功能
+
+- 通过 <code>modelMode</code> 选择固定搜索路由，或跟随当前会话模型及其调用协议；
+- 跟随模式无法解析当前路由时，使用可配置的 <code>fallbackModel</code>；
+- 通过 <code>protocol</code> 切换固定/兜底路由的三种非流式 HTTP 协议；
+- 通过 <code>toolIdentifier</code> 覆盖上游内置搜索标识符；
+- 通过 <code>maxTokens</code> 配置 <code>max_tokens</code> 或 <code>max_output_tokens</code>；
+- 将三种响应中的来源与引用归一化为 DSH <code>WebSearchResult</code>；
+- 在「设置 → 插件 → 插件配置」中提供可暂存、校验、保存、放弃和恢复 Profile 默认值的双语配置卡片；
+- 拒绝携带凭据的 HTTP 重定向，并把取消、缺少凭据和上游错误映射为可路由的 <code>WebError</code> code。
+
+## 安装
+
+~~~bash
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced
+~~~
+
+安装后完整重启 <code>dsh web</code>。随包 <code>cordis.patch.yml</code> 会把 <code>ctx.web</code> 的 <code>searchProvider</code> 指向 <code>enhanced-search</code>，并禁用原生 <code>web-search-deepseek</code> provider；模型侧仍使用稳定的 <code>web_search</code> 工具。
+
+## 配置
+
+默认配置与 DSH 原生 DeepSeek 搜索兼容：
+
+~~~yaml
+- id: web-search-enhanced
+  config:
+    modelMode: configured
+    protocol: anthropic-messages
+    baseURL: https://api.deepseek.com/anthropic/v1
+    model: deepseek-v4-flash
+    fallbackModel: deepseek-v4-flash
+    apiKeyEnv: WEB_SEARCH_ENHANCED_API
+    maxTokens: 4096
+~~~
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| <code>modelMode</code> | <code>configured</code> | <code>configured</code> 使用固定路由；<code>current-session</code> 跟随当前模型、Provider 和调用协议 |
+| <code>fallbackModel</code> | 固定 <code>model</code> | 当前 Session 路由无法解析时使用的模型 |
+| <code>protocol</code> | <code>anthropic-messages</code> | 固定/兜底路由使用的协议 |
+| <code>toolIdentifier</code> | 按协议推导 | Anthropic/Responses 的 tool type；Chat 的 vendor-options 模式为自定义选项字段名 |
+| <code>maxTokens</code> | <code>4096</code> | Anthropic/Chat 写入 <code>max_tokens</code>，Responses 写入 <code>max_output_tokens</code> |
+| <code>baseURL</code> | DeepSeek Anthropic base | 按协议追加 <code>/messages</code>、<code>/responses</code> 或 <code>/chat/completions</code> |
+| <code>model</code> | <code>deepseek-v4-flash</code> | 支持服务端网页搜索的模型 ID |
+| <code>apiKeyEnv</code> | <code>WEB_SEARCH_ENHANCED_API</code> | 固定/兜底路由读取 API Key 的凭据引用；当前会话模式优先使用当前 LLM 路由引用 |
+| <code>maxUses</code> | <code>5</code> | 仅 Anthropic Messages 的 <code>max_uses</code> |
+| <code>chatSearchMode</code> | <code>search-model</code> | 官方专用搜索模型，或明确声明的 <code>vendor-options</code> 扩展 |
+| <code>searchContextSize</code> | 上游默认 | OpenAI 兼容模式可选 <code>low</code>、<code>medium</code>、<code>high</code> |
+
+<code>toolIdentifier</code> 留空时：Anthropic 使用 <code>web_search_20250305</code>；Responses 使用 <code>web_search</code>；Chat 的 vendor-options 模式使用 <code>web_search_options</code>。官方 Chat Completions 只在专用搜索模型上提供联网搜索，使用固定顶层 <code>web_search_options</code> 字段，而不是 Responses 风格的 <code>tools[]</code>；只有网关明确声明自定义字段时才选择 vendor-options。
+
+设置页面提供一次性 API Key 输入框。密钥通过 <code>ctx.remote.credentials.set()</code> 保存到 Harness credentials，成功后清空输入框；普通 settings document 永远不会回显密钥。
+
+## Standalone 限制
+
+本插件与参考实现 <code>dsh-web-search-responses</code> 一样直接从 <code>ctx.web</code> 调用上游搜索模型，不新增 SessionEvent。DSH 当前持久化层只接受编译进 Host runtime catalog 的事件，外部插件仅做 TypeScript declaration merge 会导致会话恢复拒绝未知事件，因此本插件不会写入自定义事件。
+
+原始 <code>web_search</code> query 仍由 DSH 的 <code>tool/call</code> 记录，但实际 endpoint、model 和协议请求 body 不能从当前 session log 完整重建。这是纯外部插件且不修改 Core 时无法消除的限制；需要严格辅助模型请求重放的部署不应启用本插件。
+
+## 开发
+
+~~~bash
+pnpm install
+pnpm run check
+~~~
+
+若系统 pnpm 状态目录不可写：
+
+~~~bash
+XDG_DATA_HOME=$PWD/.xdg/data XDG_CONFIG_HOME=$PWD/.xdg/config PNPM_HOME=$PWD/.pnpm-home pnpm install
+~~~
+
+详细需求分析、架构与风险见 [docs/design.zh-CN.md](docs/design.zh-CN.md)。

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# Select the enhanced provider for DSH's stable model-facing web_search tool.
+# The WebRuntime row is replaced as a whole, so keep both selectors here.
+- id: web
+  config:
+    searchProvider: enhanced-search
+    fetchProvider: http
+
+# Avoid registering two implementations under separate selectable ids by default.
+- id: web-search-deepseek
+  disabled: true
+
+- insert:
+    - id: web-search-enhanced
+      name: dsh-web-search-enhanced
+      config:
+        modelMode: configured
+        protocol: anthropic-messages
+        apiKeyEnv: WEB_SEARCH_ENHANCED_API
+        fallbackModel: deepseek-v4-flash
+        maxTokens: 4096

package/docs/design.zh-CN.md

@@ -0,0 +1,79 @@
+# dsh-web-search-enhanced 需求分析与架构设计
+
+## 1. 需求评估
+
+DSH 的模型侧 <code>web_search</code> 并不直接绑定某个 HTTP 协议。调用链是 <code>dsh-tool-web → ctx.web.search() → WebSearchProvider</code>，因此正确扩展点不是覆盖工具注册表，也不是修改 agent loop，而是注册新的 <code>ctx.web</code> search provider，并在 WebRuntime 配置中选择该 provider。这样可保持模型工具名称、参数、权限、超时与结果渲染不变。
+
+本插件必须支持三种协议切换、上游内置搜索标识符和最大输出 Token 配置、Web Profile 可视化编辑，以及统一的 <code>WebSearchResult</code>。为使协议可实际调用，还必须配置 <code>baseURL</code>、<code>model</code> 和 <code>apiKeyEnv</code>。<code>maxUses</code>、<code>apiVersion</code> 与 <code>searchContextSize</code> 是协议适配需要的窄扩展字段。
+
+插件在 <code>current-session</code> 模式下读取当前 Agent 的模型选择与 <code>llm-pi-ai</code> 路由配置，跟随模型、Provider、调用协议、接口地址和凭据；无法解析时使用固定配置及 <code>fallbackModel</code>。非目标包括重新注册模型侧工具、通用函数工具执行、浏览器写入 settings document 明文 API Key，以及修改 deepseek-harness 源码。
+
+## 2. 组件与数据流
+
+~~~mermaid
+flowchart LR
+  M[Agent model] --> T[dsh-tool-web / web_search]
+  T --> W[ctx.web]
+  W --> P[EnhancedSearchProvider]
+  S[Web Profile settings] --> P
+  P --> A[Protocol request adapter]
+  A --> H[Credentialed HTTPS request]
+  H --> R[Protocol response parser]
+  R --> N[WebSearchResult]
+  N --> T
+~~~
+
+Host 入口通过 <code>installSettingsSection</code> 注册 <code>web-search-enhanced</code> namespace。每次搜索开始时只读取一次 resolved settings，保证一次调用不会混用更新前后的 endpoint、协议和 Token 上限。provider ID 在注册时固定；实时设置不能修改该字段，否则 <code>ctx.web</code> 的 provider 选择会与已注册对象不一致。
+
+Client 入口把相同 namespace 绑定到 <code>settings.plugin.item</code> keyed slot。插件配置页只在 Host 暴露 namespace 时渲染卡片，未加载 Host 插件时不会出现不可用配置项。
+
+## 3. 协议映射
+
+| 协议 | Endpoint | 搜索标识符位置 | Token 字段 | 响应来源 |
+| --- | --- | --- | --- | --- |
+| Anthropic Messages v1 | <code>/messages</code> | <code>tools[0].type</code>，默认 <code>web_search_20250305</code> | <code>max_tokens</code> | <code>web_search_tool_result</code> + text citations |
+| OpenAI Responses | <code>/responses</code> | <code>tools[0].type</code> 与 <code>tool_choice.type</code>，默认 <code>web_search</code> | <code>max_output_tokens</code> | <code>web_search_call</code>、sources、message annotations |
+| OpenAI Chat Completions | <code>/chat/completions</code> | 官方模式固定 <code>web_search_options</code>；vendor 模式可配置字段名 | <code>max_tokens</code> | assistant message annotations 与顶层 citations |
+
+Chat Completions 与 Responses 的联网搜索表示不同。官方 Chat Completions 仅支持专用搜索模型，并通过固定 <code>web_search_options</code> 启用搜索，不接收 Responses 的 built-in <code>tools[]</code>。默认 <code>chatSearchMode=search-model</code> 固定使用该官方字段；只有网关明确声明自定义顶层选项字段时才选择 <code>vendor-options</code>，此时 <code>toolIdentifier</code> 才控制字段名。
+
+所有请求设置 <code>stream: false</code>。Responses 强制 <code>tool_choice</code> 为配置的 built-in 类型；Anthropic 通过 <code>max_uses</code> 约束服务端搜索次数；Chat 由专用搜索模型与搜索选项字段决定搜索执行；普通 Chat 模型不构成可用的 web search capability。
+
+## 4. 配置模型
+
+Schema defaults → Profile composition base → 用户持久化覆盖构成设置层级。resolved config 在操作入口校验 provider ID、绝对 URL、必填字符串、安全标识符、正整数 Token/使用次数和封闭 context-size 枚举。配置卡片采用暂存编辑；客户端即时校验，Host 执行权威校验。恢复 Profile 清除用户层字段，不复制默认值。
+
+## 5. 错误与安全
+
+| code | 条件 |
+| --- | --- |
+| <code>WEB_PROVIDER_CREDENTIAL_MISSING</code> | literal key、<code>ctx.credentials</code> 与 launch environment 均不可用 |
+| <code>WEB_ABORTED</code> | 调用前、请求中或读取响应时取消 |
+| <code>WEB_PROVIDER_ERROR</code> | 网络、HTTP、JSON、协议结果或服务端搜索失败 |
+
+所有凭据请求设置 <code>redirect: error</code>，在跟随重定向前失败，避免 Authorization 或 <code>x-api-key</code> 自动转发到其他 origin。Anthropic 同时发送 <code>x-api-key</code> 与 Bearer 以兼容 DeepSeek 和 Anthropic-compatible gateway；OpenAI 协议仅发送 Bearer。错误消息不包含密钥。<code>baseURL</code> 禁止 userinfo、query 和 fragment，避免 URL 本身携带凭据。
+
+Parser 不从自然语言伪造来源。Anthropic 或 Responses 没有服务端搜索执行标记时直接失败；Chat Completions 公开响应没有独立 search-call item，因此以 assistant message 为最小成功条件，并从 annotations/citations 提取来源。
+
+## 6. UX 设计
+
+卡片复用 DSH 设置页语义：12px 卡片圆角、14×16px header、<code>--dsw-alias-*</code> token、折叠箭头、未保存徽标、34px 表单控件、帮助文本，以及保存/放弃/恢复 Profile footer。界面提供中英文 typed dictionary、可访问 label、<code>aria-expanded</code>、<code>aria-invalid</code> 与错误状态。
+
+协议切换会改变高级字段：Anthropic 显示 <code>maxUses</code> 与 <code>apiVersion</code>；OpenAI 显示 <code>searchContextSize</code>。<code>toolIdentifier</code> 帮助文案随协议说明准确 wire 位置。
+
+## 7. 测试策略
+
+- 协议单元测试固定 endpoint、搜索标识符位置与 Token 字段；
+- parser 测试覆盖引用合并、去重与缺少 search-call 失败；
+- provider 测试覆盖重定向策略、取消、缺少凭据、HTTP 错误与成功归一化；
+- settings 测试覆盖默认值、非法字段与动态协议更新；
+- Client helper 测试覆盖 draft、输入校验、凭据引用默认值与双语字典；
+- 跟随模式测试覆盖当前模型、三种协议、路由凭据、fallbackModel 与预算字段；
+- 发布验证检查 Host ESM、Client bundle、类型声明、协议子路径与 Cordis patch。
+
+## 8. 已知风险与后续工作
+
+1. DSH 当前没有外部插件可注册的持久化 SessionEvent catalog。参考插件 <code>dsh-web-search-responses</code> 也不记录其辅助 Responses 请求。本插件不会伪造现有 DeepSeek 专用事件，也不会写出 Host 无法恢复的未知事件；因此实际 endpoint、model 与完整协议 body 不可由 session log 重建。严格执行辅助模型请求可重放的部署不能使用本 standalone 插件。
+2. OpenAI-compatible 网关可能只实现部分官方字段。Adapter 保持严格，不做静默 fallback。
+3. Responses 的完整 <code>action.sources</code> 可能要求提供方支持显式 include；message annotations 仍可提供引用。应在确认目标网关后再增加兼容开关。
+4. API Key 设置 UI 通过 <code>ctx.remote.credentials.set()</code> 写入 Harness credentials；输入框只持有待写入值，成功后清空，普通 settings document 不保存密钥。

package/docs/harness-contract.md

@@ -0,0 +1,30 @@
+# Harness Contract
+
+## Source of truth
+
+Extracted from DeepSeek Harness commit `cd5ef8148158c3a752a658978873241fdf8e2bbc` and source package line `0.1.2-alpha.1`. Installable dependencies use the npm `next` line `0.1.1-rc.2`; source and registry baselines are intentionally recorded separately.
+
+Representative sources:
+
+- `packages/fs/tool-fs/src/index.ts`: named Cordis exports, Schemastery config, required and conditional injection.
+- `packages/core/tools/src/schema.ts`: tool definitions and execution contracts.
+- `packages/client/tsdown.client.ts`: ModuleLoader output, external purity, CSS, and build faces.
+- `packages/client/ui-settings-plugins/package.json`: `dsh.client`, exports, peers, and files.
+- `packages/client/ui-settings-plugins/src/client/index.ts`: browser surface ownership.
+- `packages/api/settings-controller/src/index.ts`: redacted settings namespaces and Remote ownership.
+
+## Portable contract retained here
+
+One package exposes a Node host half and optional browser half. `dsh.bundle.patch` publishes composition defaults; `dsh.client` declares browser dependencies. Client output calls `window.__ModuleLoader__.load` and resolves shared identity through injected `require`. TypeScript uses strict NodeNext semantics, relative runtime imports end in `.js`, declarations live under `lib/types`, and published files are explicit.
+
+## Deliberately not copied
+
+The internal monorepo uses `workspace:^`, project references, generated catalogs, build faces, Typert generators, oxlint, package-invariant gates, static-linked client channels, and root release orchestration. Those are repository infrastructure, not portable plugin API. Typert generation is especially monorepo-bound today, so this basic template demonstrates a narrow optional RPC adapter instead of copying generated internals.
+
+## Upgrade checklist
+
+- Compare DSH package versions and Node/pnpm engines.
+- Inspect `packages/client/tsdown.client.ts` for loader, external, CSS, and build changes.
+- Inspect a current tool package for `defineTool` changes.
+- Inspect a current client package for slot, locale, and `dsh.client.inject` changes.
+- Run `pnpm run check`, then verify the packed plugin in the current DSH GUI after refresh.

package/docs/template-comparison.md

@@ -0,0 +1,35 @@
+# Existing Template Comparison
+
+Audited on 2026-08-28 against DeepSeek Harness `cd5ef8148158c3a752a658978873241fdf8e2bbc`.
+
+| Area | bugmaker2 | kun2-5code | sunshine-lang | This template |
+| --- | --- | --- | --- | --- |
+| Audit commit | `31af7eb` | `0b4fbda` | `6417045` | harness-derived |
+| Shape | Dual host/client, Typert, React | Six host shapes, 14 UI surfaces | Minimal host-only tool | Small host/tool plus optional UI/RPC |
+| Build | esbuild + tsc | tsdown + loader wrapper | tsc only | tsc declarations + tsdown adapter |
+| Tests | Vitest contracts/runtime | One build smoke | Unwired integration file | Vitest + build + tarball gate |
+| Publish gate | check, no packed consumer | prepare only | none | prepublish check and pack extraction |
+| Scaffolding | Manual rename checklist | Fork/edit | Script with weak exclusions | Validated name, excludes VCS/build state |
+| DSH baseline | old rc.6, wildcard peers | rc.5/rc.6, obsolete settings docs | rc.1 tools | documented alpha baseline |
+
+## Assessment
+
+### bugmaker2/dsh-web-search-enhanced
+
+The strongest contract-oriented example. Shared Zod/Typert descriptors, lifecycle handling, React, i18n, lint and CI are useful. Its handwritten loader, duplicated manifest, wildcard optional peers, manual ten-point rename, old rc.6 baseline, and missing packed-consumer gate increase drift risk.
+
+### kun2-5code/dsh-web-search-enhanced
+
+The best catalog of extension shapes and UI slots, useful as an API showcase rather than a minimal production baseline. Its README still describes a settings whitelist and internal paths absent from the current settings controller. It lacks lint, Vitest, package verification, compatibility engines, and prepublish checks.
+
+### sunshine-lang/dsh-web-search-enhanced
+
+The clearest host-only starter and only compared repository with a scaffold script. Its exports and tool example are sound, but it lacks client/RPC/UI, package exports, peer separation, typecheck/test/publish gates, and a wired integration test. Its scaffold may copy `lib` and handles arguments weakly.
+
+## Material differences here
+
+- Internal package files are evidence, while nonportable monorepo machinery is called out explicitly.
+- One example is kept per important boundary instead of maximizing feature count.
+- Client externals derive from peers and the ModuleLoader compatibility adapter is isolated.
+- The exact tarball is extracted and checked.
+- Host-only deletion and deterministic scaffolding are documented.