WebSearch MCP Server AGENTS.md changelog

https://raw.githubusercontent.com/daidaij/websearch-mcpserver/HEAD/AGENTS.md

− searxng/          # SearXNG 兼容 HTTP 端点− - **当前状态：** 三项随 `v3.10.4` 交付（base Release 含 4 平台整包 + GHCR 镜像）；按用户要求本次**不打 `-registry` tag**，MCP Registry 停在 `3.10.3`− - **验收：** `go build ./...`、`go vet ./...` 干净；`go test -short -count=1 ./...` 与 `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8` 复跑全绿；`go test ./pkg/i18n/`（新增 2 条 log key）绿；本次改动的 Go 文件在 LF 化副本上 `gofmt -l` 干净；整包步骤用假 dist 树本地干跑（4 平台产物名、包内清单、tar owner/mtime 均核对），`actionlint@v1.7.12` 0 findings；`SetLoggerLevel` 回归测试在改回旧实现时确认失败（级别停在 trace）− - 本机部署 `D:\Programs\websearch` 已升级到 `v3.10.2`（2026-10-25，用 base Release 的 `websearch-mcpserver-windows-amd64.exe` 覆盖，sha256 `beb21986…` 与 Release 一致；上一版 `v3.10.0` 备份为 `websearch-mcpserver.exe.bak-pre-v3.10.2`）；`everything.max_results: 10`；`cleanfetch.auto_proxy: true`；新供应商已配测试 Key（tinyfish/keenable 进 `apipool.engines`，github PAT 提额，search_history 已开启），`mcp_hub.fetch_mode: prefer` 激活远端抓取链；`academic.enabled: false`，故 MCP 工具数为 4（smartsearch / cleanfetch / file_search / search_history）− - [ ] v3.10.4 整包真机走查：从 Release 下载对应平台压缩包、解压、按包内 README 启动、把 `skills/websearch-mcp` 装进宿主 Skill 目录（本批只有本地干跑 + 内容清单核对，CI 侧未见真实运行结果）+ 7. **发布矩阵对称：npm 走 `-npm` 后缀 tag，不随普通 tag 发**。普通 tag（`vX.Y.Z`）只发 Release + GHCR；产物就绪后再单独打 `vX.Y.Z-npm`，由 **`npm-plugin.yml` 自己的 `on.push.tags` 接**（`release.yml` 的 tags 已排除 `-npm`，`docker.yml` 也跳过），从 **base tag** 的 Release 下载并校验 `websearch-mcp-cli-*`，按「4 平台包 → `websearch-mcp-cli` → `dsh-websearch-mcpserver`」顺序发 6 个包，npm 版本取 base 版本（`v3.10.5-npm` → `3.10.5`，`publish.sh` 剥 `-npm` 后缀）。这与 `-registry` 发 MCP Registry 的链路对称：两种后缀 tag 都不重编译、不建 base Release、不推 GHCR 镜像。**发布认证是 npm Trusted Publishing（OIDC）**：+ ### 初始化失败不再 panic — done（2026-11-11，未发版）+ - **当前状态：** `ServerOption` 从 `func()` 改为 `func() error`，`Init` 逐项传播；搜索引擎、缓存命名空间与缓存构造失败沿 `Run` / `cmd/cli` 返回，入口打印友好错误而不是堆栈。`Handler` 嵌入路径仍按文档在边界 fail-fast panic+ - **附带：** 新增 `tool.init.search_engine_failed` / `cache_namespace_failed` / `cache_failed` 三条中英文案；`docs/api` 的嵌入边界同步区分 `Run` 返回 error 与 `Handler` panic+ - **验证：** `go build ./...`、`go vet ./...`、`go test -short ./...`、`go test ./pkg/i18n/`+ ### SearXNG 兼容端点移除 — done（2026-11-11，未发版）+ - **当前状态：** 删除 `searxng/` 包与 `GET /searxng/search` 路由，移除仅服务于它的 `mcp.GetSearchGroup`；清理 `log.searxng.*` 文案、配置样例鉴权注释与文档/图源中的端点引用+ - **理由：** 该端点只实现 JSON 子集（仅读取 `q`），与 MCP 的 `smartsearch` / `cleanfetch` 能力重复，实际使用面为零；保留需要持续维护 LiteLLM 兼容口径与文档，收益低于成本+ - **影响：** 破坏性变更，记入 CHANGELOG Unreleased；LiteLLM 等 SearXNG 客户端改走 MCP 端点或客户端侧适配+ - **验证：** `go build ./...`、`go test -short ./...`、`go test ./pkg/i18n/`+ ### 搜索质量闭环 — done（2026-11-11，已合入 master `61427d4`，未发版）+ - **当前状态：** 分支 `feat/search-quality-loop` 已合入 master 并推送，未打 tag、未发 Release/GHCR/Registry；合入内容包含今天远端两个分支（`feat/search-budget-and-params` 的批量/depth/sources/内容预算、`fix/hosted-mcp-ua` 的入站 UA 透传）与 D1 / D2 / D5、D3 部分落地，以及 KeyPool / ShowMeta / 进程内指标三项工程债治理+ - **D5：** `NewMCPServer` 在 `ServerOptions.Instructions` 下发中英双语工具选择纪律（发现 / 读正文 / 查论文 / 本地文件 / 历史），调用方显式设置时尊重其值；`skills/websearch-mcp/SKILL.md` 增补「参数纪律」+ - **D2：** 新增叶子包 `pkg/errcode`（稳定码 + `CodeOf` / `Message`）；`core.ClassifyFailure`、`telemetry.ClassifyErrorKind`、`mcp.isAntiBotFailure` 改为码优先、关键词兜底；`antirobot.ErrLocalRateLimit`、`provider.KeyError`、`webfetch` 分类附码；`adapter/baidu_fallback.go` 双失败用 `errcode.Message` 保留主备原因+ - **D3（部分）：** `googlenews` / `wikipedia` 补 `ContextEngine`（`NewRequestWithContext`）；`hybrid` 的包装 goroutine 与 `cleanfetch` 统一预算未动+ - **D1：** `bench/quality` 20 条中英固定 fixture，逐 case 与聚合输出 P@8 / R@8 / MRR@8，聚合门槛拦退化；合成候选集只衡量排序回归，真实 HTML fixture 仍归 T2+ - **工程债：** provider Key 池改为命名结构体 `mode.ProviderPools`；`core.ShowMeta` 改为 `atomic.Bool` + setter；`/metrics` 增加进程内指标（在飞请求、uptime、goroutine、堆分配、`websearch_telemetry_enabled`），控制台关闭时返回 200 并省略遥测序列+ - **解析契约：** Bing 与 DDG 补 HTML parser fixture；baidu（JSON feed）、google、so360、googlenews（RSS）、wikipedia（JSON）已有解析测试+ - **工具面取舍：** `depth` / `max_chars` / `fetch_top_n` 只塑造 web 正文；仅 academic 时显式传这三个参数返回错误，避免静默无效。未新增任何 MCP 参数或工具+ - **暂缓：** D4（citation / untrusted 边界，改输出契约）、D6（垂直源）、D7（配置分层）、D8 tracing 与显式 DI、真实检索快照/定时 live smoke+ - **验收：** `go build ./...`、`go vet ./...`、`go test -short -count=1 ./...` 与 `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8` 复跑全绿；`go test -race -short ./server/ ./pkg/search/{hybrid,core,mode}/` 绿；`go test ./pkg/i18n/ ./pkg/errcode/ ./bench/quality/` 绿；`pkg/academic` 的 PubMed 真网测试偶发 `unexpected EOF`，单跑通过，属既有 flake+ - **当前状态：** 三项随 `v3.10.4` 交付：base Release 24 个产物（8 裸二进制 + 4 平台整包 + 12 校验和，整包 19.9–21.2 MB，约为同平台两个裸二进制之和的 39%）、`release.yml` 与 `docker.yml` 均 success、GHCR `3.10.4` 镜像已推；按用户要求本次**不打 `-registry` tag**，MCP Registry 仍停在 `3.10.3`（已核对 registry 列表无 `3.10.4`）+ - **验收：** `go build ./...`、`go vet ./...` 干净；`go test -short -count=1 ./...` 与 `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8` 复跑全绿；`go test ./pkg/i18n/`（新增 2 条 log key）绿；本次改动的 Go 文件在 LF 化副本上 `gofmt -l` 干净；`actionlint@v1.7.12` 0 findings；`SetLoggerLevel` 回归测试在改回旧实现时确认失败（级别停在 trace）。**发布产物核对（2026-11-05）：** 从 v3.10.4 下载 windows `.zip` 与 linux `.tar.gz`，sha256 与随附 `.sha256` 一致；包内为两个二进制 + 两份样例配置 + LICENSE + 中英 README + 完整 `skills/`（含 `everything-http-server` 与 `websearch-mcp/agents|references`）；包内服务端二进制与裸二进制 + - 本机部署实际路径是 **`D:\tool\websearch-mcpserver`**（旧记录里的 `D:\Programs\websearch` 已不存在，属过期信息）。2026-11-05 已从旧构建（exe 报 `dev`、sha256 `753370a5…`）升级到 **`v3.10.4`**（sha256 `775ab905…`，与 Release 整包内 exe 一致），并按下述口径迁移配置+   - **启动方式**：Startup 目录 `WebSearchMCP.lnk` → `wscript.exe "D:\tool\websearch-mcpserver\autostart.vbs"`，vbs 设 `WEBSEARCH_CONFIG=D:\tool\websearch-mcpserver\config.yaml` 后 `start`（隐藏窗口、脱离 shell 作业）；手工重启必须脱离当前 shell 作业（用 WMI `Win32_Process.Create` 或双击快捷方式），否则作业对象销毁会连带杀掉服务+   - **配置迁移**：旧 `config.yaml`（1.5 KB 精简版，30 个生效键）整体搬进 v3.10.4 的 `config.example.yaml` 结构（35 KB，带全量注释），生效键 64 个、旧键零丢失零改值：`port 8338` / `log_level info` / `mode apipool` / `network china` / 8 条 `black_list_host` / `rate_limit 3·60` / `anysearch`（2 Key，num_results 10）/ `exa`（num_results 5，lookback_days 90）/ `tavily` / `apipool`（weighted，engines = anysearch → tavily → exa）/ `bing` 启用 / `duckduckgo` 关闭 / `academic` 关闭 / `cleanfetch` 启用 / `log 1·1`+   - **新版本默认行为的取舍**：v3.10.x 的 `start` 会默认生成 `dashboard.yaml`（含随机口令）启用控制中心，并建 `data/` 遥测库与桌面快捷方式。本次按「迁移旧参数与模式」的口径在 `config.yaml` 里显式写 `dashboard.enabled: false` 沿用旧行为，已删除生成的 `dashboard.yaml` / `data/` / 图标与桌面 `.lnk`（`fetchdata/` 属 cleanfetch 输出，保留）；要开控制中心把那行改 true 重启即可+   - **备份**：`websearch-mcpserver.exe.bak-pre-v3.10.4`（旧 exe）、`config.yaml.bak-pre-v3.10.4`（旧配置）+   - **验收**：MCP `serverInfo.version = v3.10.4`；工具 2 个（smartsearch / cleanfetch；`file_search` 因 Everything HTTP Server 未运行而不暴露，`academic`/`search_history` 关闭）；真机 smartsearch 走 anysearch 返回 10 条、`/searxng/search` 返回 10 条；重启后日志 0 条 `level=debug`（`log_level: info` 生效）+ - [ ] v3.10.4 整包真机走查（剩余部分）：解压后按包内 README 启动服务、把 `skills/websearch-mcp` 装进宿主 Skill 目录并确认工具清单与项目标签生效（下载/校验和/包内清单已在发版当日核对）

https://raw.githubusercontent.com/daidaij/websearch-mcpserver/HEAD/AGENTS.md

− | **搜索引擎搜索** | 内置百度/Bing/DuckDuckGo/Google 多引擎并发编排，支持 Tavily/Exa/AnySearch/豆包等 API 引擎混合 |− | **API 搜索** | API Key 池轮转模式，支持百度千帆/Tavily/Exa/AnySearch/豆包等多种 API 供应商，失败自动切换 |− 5. **发布矩阵拆分，不要合成一套 6 平台**：GitHub Release = linux/windows amd64 + darwin amd64/arm64；GHCR = linux/amd64+arm64；MCP Registry mcpb 走 `vX.Y.Z-registry` tag 的**独立 Release 页**（`--expect-packages 4`，server.json 下载链接指向该页，base Release 只放二进制，两类产物分开）。**先打普通 tag（`vX.Y.Z`）发 Release 并推 GHCR 镜像**；**发完、Release 产物就绪后再单独打 `-registry` 后缀 tag 发 MCP Registry**（不推镜像，不要和版本 tag 一起推）。后补的 `vX.Y.Z-registry` 钉同一 commit（重跑工作流时需钉到含新 workflow 的 commit——打包原料从 base Release 下载，不重编译）。linux-arm64 走 GHCR，不要把 linux-arm64 / windows-ar− 5. **品牌可定制**：`dashboard.brand`（title/logo/theme/accent）走 overview/settings 响应注入；主题 = `green/blue/mono` 三预设（CSS 变量块）+ accent 覆盖，本浏览器选择存 localStorage。桌面快捷方式图标跟主题（`cmd/assets/app-{theme}.ico`），启动时轻量检查（marker 文件字符串比较）主题变化才重建。− - **Go 构建临时目录**：`GOTMPDIR=D:	mp`（`go env -w` + 用户环境变量已配置）。卡巴斯基锁定系统 TEMP 会导致 `go build` 偶发 Access denied，构建/测试编译临时目录已统一指向 `D:	mp`，在该目录配置杀软排除即可规避；`go test` 的 `t.TempDir()` 数据目录仍走系统 TEMP（改全局 TMP/TEMP 影响面大，未动）。− > 已完成任务的交接详情已归档至 `.handoff/archive/`（不入库）。此处只保留当前状态、运维待办与待验证项。− ### 当前状态（2026-10-19）− - `master` 已推送 `b780769`：优化路线图首批八项落地（R1 context 贯通 + per-engine 软超时、R2 诊断 per-request、R3 缓存并发读、Q1 URL 归一化、Q2 守卫校准回放、O1 `/metrics`、T1 SSRF fuzz、T3 CI race + lint）。全量 `go test ./...`、`go test -race -short ./...`、golangci-lint、actionlint 全绿。− - 剩余优化项见 [docs/optimization-roadmap.md](docs/optimization-roadmap.md) 待办区：Q3 摘要 token 预算、E1 go-sdk v1.8 升级、T2 引擎解析测试补密度。− - 待发布：批次 1+3 → `v3.8.x` 补丁版；R1（批次 2）→ `v3.9.0`。`-registry` tag 按发布矩阵在 base Release 就绪后另打。− - 本机部署 `D:\Programs\websearch` 仍跑旧二进制；其 config.yaml 显式的 `everything.max_results: 50` 会被硬上限收敛为 20（要默认 10 需删该行或改 10）。− - MCP Registry 缺 `v3.6.1` / `v3.6.2`（历次未打 `-registry` tag），如需补发在原 commit 上补 tag。− - 新引擎真实链路长期回归：验证码页出现频率、anysearch 匿名档限流阈值、googlenews 回源失败率。− - 冷却落盘真网冷启动回归（重启后 ddg/arxiv 实际避让）；date_source 新旧缓存行往返实测。+ | **搜索引擎搜索** | 内置百度/Bing/DuckDuckGo/Google 多引擎并发编排，支持 Tavily/Exa/AnySearch/豆包/元宝等 API 引擎混合 |+ | **API 搜索** | API Key 池轮转模式，支持百度千帆/Tavily/Exa/AnySearch/豆包/元宝等多种 API 供应商，失败自动切换 |+ ### 国际化（i18n）+ - 用户可见文案一律走 `pkg/i18n` 的符号化 key，**不在调用点写裸字符串**：日志 `log.InfoT("log.<域>.<事件>", "name", v)`、Go 侧 `i18n.T` / `i18n.TCtx`、MCP 参数说明 `jsonschema:"mcp.param.<工具>.<字段>"`、前端 `data-i18n` 或 `t('web.<区域>.<名字>')`+ - 文案数据住 `pkg/i18n/locales/<域>.<语言>.json`（域：`log` / `mcp` / `dashboard` / `web`）；加文案只动 JSON，加语言 = 加一组同域文件 + `pkg/i18n/language.go` 的 `supported`+ - 改完必须跑 `go test ./pkg/i18n/`：目录审计会拦截漏登记、死条目、zh/en key 集合不一致、占位符集合不一致+ - 完整约定与生命周期（日志/MCP 为进程默认语言、HTTP 面按 `Accept-Language` 每请求协商）见 [docs/developers.md](docs/developers.md) 第 7 节+ | 腾讯云元宝搜索（2026-10-24 接入） | API KEY 方式 `POST api.wsa.cloud.tencent.com/SearchPro`，Bearer sk-...，返回 `Response.Pages[]`（JSON 字符串）；每月免费 2000 次，超出按量后付费（约 20 元/千次） | 已注册（`yuanbao.*`，默认不加入 apipool；hybrid 有 Key 时参与）；`yuanbao.monthly_limit` 默认 2000 并在请求前落盘拦截，禁止默认放开 |+ | TinyFish / Keenable 供应商（2026-10-24 接入） | TinyFish 仅 Key 档（免费搜索 12000 次/天、fetch 1000 URL/天，00:00 UTC 重置，国内直连实测无需代理）；Keenable 未配 Key 自动走 public 免 Key 端点（`X-Keenable-Title` 标识，按出口 IP 限流） | 均已注册（`tinyfish.*` / `keenable.*`）；两者默认不进 `apipool.engines`，hybrid 中 TinyFish 有 Key 即参与、Keenable 的 public 档需显式 `enabled: true` 才参与（质量待观察）；fetch 能力并入 cleanfetch 远端抓取链（沿用 `mcp_hub.fetch_mode`） |+ | `search_history` 本地历史（2026-10-24 接入，试验性） | smartsearch 成功后落本地 SQLite（FTS5），`search_history` MCP 工具全文检索；数据不出网，默认保留 30 天 | `search_history.enabled` 零值 = 不建库、不注册工具；实用性待真机确认，确认有价值后再转正式工具 |+ | 国际化（i18n，2026-10-25 治理） | `language: auto|zh|en` 覆盖日志 / MCP 工具描述与参数 Schema / 控制中心 / 工具返回内容四面（八域）；文案住 `pkg/i18n/locales/<域>.<语言>.json`，go-i18n + x/text 运行时，审计测试 `pkg/i18n/catalog_test.go` 双向比对代码引用与目录条目 | 新增文案只动 JSON + 用 key，勿在调用点写裸字符串；MCP 描述注册时固化、改语言需重启；HTTP 面按 `Accept-Language` 每请求协商；工具返回内容只治理本服务自产文案（外部内容与 `format_md.go` 骨架不动）；改错误文案必须同步核对三处关键词判类 |+ | GitHub（2026-10-24 接入） | `api.github.com` 国内直连可达无需代理；匿名 search 10/min、core 60/h，PAT 提额 search 30/min、core 5000/h（官方 docs 核对）；github.com HTML 是 JS 渲染抓不到，搜索与 cleanfetch 仓库/blob 特判均优先走 REST API（`blob` 走 contents API 取原文——raw.githubusercontent CDN 国内无代理不可达，勿改回），API 失败自动回退（搜索回 Bing `site:github.com`，抓取回 webfetch → Jina 链）；code search 要求认证不做 | 已注册（`github.enabled`，默认关闭；`github.api_key`/`token_list` 配 PAT，env `GITHUB_TOKEN`）；限流冷却取 Retry-After / x-ratelimit-reset；EngineAdapters.GitHub 收接口类型（typed-nil 陷+ | Reddit（2026-10-24 评审后整线放弃） | 浏览器 UA 全拦（HTML/.json/api 均 403），`.rss` 用脚本 UA 可达但 PullPush 被 Cloudflare 挡死；官方 2026-09-30 公告：新公共 API 申请 2026-10-31 截止、RSS 2026-11-13 全线停、未注册 app 2027-01-12 移除、公共 Data API 2027-03 终止 | 两条候选通道（OAuth script app / RSS 兜底）均在死线上，收益期 < 5 个月，不立项；OAuth 调研结论留档 docs/optimization-roadmap.md N7，上游重开（Devvit/普适免费档）再议 |+ 5. **发布矩阵拆分，不要合成一套 6 平台**：GitHub Release = linux/windows amd64 + darwin amd64/arm64；GHCR = linux/amd64+arm64；MCP Registry mcpb 走 `vX.Y.Z-registry` tag 的**独立 Release 页**（`--expect-packages 4`，server.json 下载链接指向该页，base Release 只放裸二进制与每平台整包（含 `skills/`），不放 mcpb，两类产物分开）。**先打普通 tag（`vX.Y.Z`）发 Release 并推 GHCR 镜像**；**发完、Release 产物就绪后再单独打 `-registry` 后缀 tag 发 MCP Registry**（不推镜像，不要和版本 tag 一起推）。后补的 `vX.Y.Z-registry` 钉同一 commit（重跑工作流时需钉到含新 workflow 的 commit——打包原料从 base Release 下载，不重编译）。linux-arm64 走 GHCR，+ 5. **品牌可定制**：`dashboard.brand`（title/logo/theme/accent）走 overview/settings 响应注入；主题 = `green/blue/mono` 三预设（CSS 变量块）+ accent 覆盖，本浏览器选择存 localStorage。桌面快捷方式图标跟主题（`cmd/assets/app-{theme}.ico`）；`start`/`open`/`install` 读取 `.lnk` 逐项校验目标、参数、工作目录与图标，主题或图标内容变化时落盘带内容哈希的新 ico 并重建。+ - **Go 构建临时目录**：`GOTMPDIR=D:\tmp`（`go env -w` + 用户环境变量已配置）。卡巴斯基锁定系统 TEMP 会导致 `go build` 偶发 Access denied，构建/测试编译临时目录已统一指向 `D:\tmp`，在该目录配置杀软排除即可规避；`go test` 的 `t.TempDir()` 数据目录仍走系统 TEMP（改全局 TMP/TEMP 影响面大，未动）。+ - **Go 源码行尾已统一 LF（2026-10-25，`f342a4d`）**：`.gitattributes` 钉死 `*.go text eol=lf`，工作树已全量转 LF、gofmt 历史格式债已清——此后 `gofmt -l` 报告皆为真实问题，直接修；勿删 `.gitattributes`，否则 autocrlf 检出 CRLF 会让 gofmt 重新全文件误报。+ > 已完成任务的交接详情已归档至 `.handoff/archive/`（不入库）。此处只保留当前活跃任务、运维待办与待验证项。+ ### 发布整包（含 Skill）+ log_level 生效 / 并发失败留痕 + SQLite 连接池上限 — done（2026-11-05，随 v3.10.4 发布；本次未发 MCP Registry）+ - **当前状态：** 三项随 `v3.10.4` 交付（base Release 含 4 平台整包 + GHCR 镜像）；按用户要求本次**不打 `-registry` tag**，MCP Registry 停在 `3.10.3`+ - **实现要点：** ① `release.yml` 的 release job 新增 `Package platform archives`：用 checkout 到的源码把 dist 里的裸二进制打成本平台整包（Windows `zip -9`、Linux/macOS `tar -czf` gzip -9，tar 带 `--sort=name --owner=0 --group=0 --numeric-owner`），包内为 `websearch-mcpserver-<平台>/`（两个二进制 + 两个 config 样例 + LICENSE + 中英 README + `skills/`）；中间目录 `pkg/` 落在 `dist/` 之外，避免被 `gh release create dist/websearch-mcpserver-*` 通配带进 Release；既有校验和步骤的通配顺带覆盖整包。② `publish-registry` 的 base 下载通配 `websearch-mcpserver-*` 现在也会命中整包与 `.sha256`，加 `find dist -+ - **验收：** `go build ./...`、`go vet ./...` 干净；`go test -short -count=1 ./...` 与 `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8` 复跑全绿；`go test ./pkg/i18n/`（新增 2 条 log key）绿；本次改动的 Go 文件在 LF 化副本上 `gofmt -l` 干净；整包步骤用假 dist 树本地干跑（4 平台产物名、包内清单、tar owner/mtime 均核对），`actionlint@v1.7.12` 0 findings；`SetLoggerLevel` 回归测试在改回旧实现时确认失败（级别停在 trace）+ - **开口项：** 上游限流导致的并发失败本身未治理（本次只补日志可见性，入口侧并发上限待评估）；`cache.ConnMaxIdleTime`/`MaxIdleConns` 未调（空闲连接的页缓存仍常驻）+ - **详情指针：** 本批无独立 `.handoff/` 文件（改动集中在 CI 与三处小修）+ ### 本机环境收口（部署 v3.10.2 + grok 子代理模型）— done（2026-10-25）+ - **当前状态：** 本机部署 `D:\Programs\websearch` 已升级到 `v3.10.2` 并验证；grok CLI 的子代理默认模型改为组 `cline-pass`（DeepSeek V4.1 Flash 主 / GLM-5.3 Flash 备），新会话已验证解析到链首条目+ - **关键证据：** 部署 exe sha256 `beb21986…` 与 base Release 一致、MCP `serverInfo.version = v3.10.2`、真机 smartsearch 与控制中心语言协商通过；子代理 `meta.json` 的 `effective_model_id = cline-pass/deepseek-v4.1-flash`；AGENTS.md 同步提交 `f22179e`+ - **开口项：** registry 里 `3.10.2` 的 `fileSha256` 陈旧（只有换版本号能刷新，待用户拍板）；本地 grok fork 仓库两个待办文件未提交+ - **详情指针：** [`.handoff/local-env-and-grok-cli.md`](.handoff/local-env-and-grok-cli.md)+ ### i18n 治理（日志/MCP 元数据/控制中心/工具返回内容 语言模式 auto|zh|en）— done（2026-10-25，随 v3.10.2 发布）+ - **当前状态：** 四面 zh-en 双档已全部落地并随 `v3.10.2` 发布（Release + GHCR + MCP Registry 三线就绪）；该版本同日回收重发过一次（先发三面、补完第四面后同版本号重发），base tag 钉 `d79e853`、`-registry` tag 钉 `9883818`+ - **实现要点：** `pkg/i18n` 基于 `nicksnyder/go-i18n/v2` + `golang.org/x/text/language`（原设计是 zh 当 key 的 Go map，评审后改为符号化 key + 外置 JSON）；文案住 `pkg/i18n/locales/<域>.<语言>.json`（八域：log/mcp/dashboard/web + tool/fetch/provider/search）；调用形态 `log.*T(key, "name", v)` 与 `i18n.T`/`i18n.TCtx`；MCP 参数说明改为 `jsonschema:"mcp.param.*"` 并在注册时渲染输入 Schema（顺带修掉 `description,` 前缀透出给客户端的既有缺陷）；控制中心按 `Accept-Language` 每请求协商，`serveIndex` 改写 `<html lang>` 并把前端文案内联进页面（首帧即正确语言）；工具返回内容按「只治理本服务自产文案」口径迁入四域，稳定哨兵（`errors.Is` 身份）与本地化文案分离+ - **防漏机制：** `pkg/i18n/catalog_test.go` 强制每个域 zh/en key 集合一致、同一 key 占位符集合一致、代码引用与目录条目双向一致；纯转发包装（key 由调用方给出）须显式登记 `dynamicKeyAllowlist` 并写理由+ - **验收：** `go build ./...`、`go vet ./...`、`gofmt -l` 干净；默认语言与 `LANG=en_US.UTF-8` 下 `go test -short -count=1 ./...` 均全绿、`go test ./pkg/i18n/`（目录审计，八域 700+ 条）绿；`-race -short` 仅剩 Windows TempDir 既有 flake；5 个前端 node 用例全 PASS；`golangci-lint --new-from-rev=v3.10.1` 0 issues；真机探针实测 `auto`/空值/未知值在本机（系统区域 zh-CN）解析为 `zh`、`zh`→zh、`en`→en，`Accept-Language: en-US`→en、`fr-FR` 回落配置值；中英双语渲染探针逐条核对四域（占位符替换、CLDR 复数、en 无残留中文）+ - **遗留（第四面）：已完成。** 工具**返回内容**里本服务自产的提示/告警/错误/进度已全部接入 i18n：`tool` 域（`mcp/`，121 条，`0268707`）、`fetch` 域（`pkg/fetch/**`，127 条，`2f18a0d`）、`provider` 域（`pkg/search/provider/**`，92 条，`7e16572`）、`search` 域（`pkg/search/{core,hybrid,adapter,apipool,engine}` + `pkg/llm` + `pkg/history` + `pkg/academic`，50 条，`1fac4e9`），共 390 条+ - **第四面口径（用户 2026-10-25 明确）：** 只治理**本服务自产**的提示/告警/错误文本；**网页正文、API 供应商返回的结果文本、上游库自带的中文串不治理**。结果记录骨架（`pkg/search/core/format_md.go` 的 `## 结果` / `**标题**` / `**url**` / `**内容**` / 日期注记 / `usage_note` 固定行）由 `contract_test.go` 固化，**保持不动**；`BuildUserPrompt` 的 LLM 提示词、`enhance` 的停用词与意图关键词表、`telemetry` / `antirobot` 的判类关键词表同属算法输入，也不动+ - **第四面的坑（改前必读）：** 翻译错误文案会打断三处按关键词判类的逻辑——`mcp/tool_search.go` 的 `isAntiBotFailure`（已改为中英并列）、`pkg/search/core/diagnostics.go` 的 `ClassifyFailure`、`pkg/telemetry/errorkind.go` 的 `ErrorKindNoResult` 等；改对应文案时必须同步补英文关键词或改用哨兵错误。另：`mcp/tool_academic.go` 的 `academicProviderErrorsFromError` 按中文前缀解析上游错误，**该前缀在仓库里无生产者（既有死路径）**，勿据其推断文案来源+ - **未纳入第四面：** `mcp/options.go` 三处 `panic`（启动期 stderr 诊断，非工具返回内容）+ - **详情指针：** [`.handoff/i18n-governance.md`](.handoff/i18n-governance.md)+ ### v3.10.1 发布后审查修复 — done（2026-10-25，v3.10.0 三线下架回收）

Showing the first 40 of each.

https://raw.githubusercontent.com/daidaij/websearch-mcpserver/HEAD/AGENTS.md

− ### search-upgrade — done（v3.6.2 已发布，2026-10-06）− - **当前状态：** 按五期拆分推进（用户确认）；**一期已提交 `6aa7ca8`**（P0-1 失败透出统一契约 + P1-6 共识按 family 计票 + P1-7 off-topic 整桶守卫 + P1-8 freshness 缓存 TTL）；**二期已提交 `f6da753`**（P1-4 date_source 三态注记 + P1-5 熔断落盘 + P1-10 Resource 化）；**三期已提交 `9b16ef7`**（P0-2 零 Key 来源扩充：so360 直连可用 / anysearch 匿名档 / wikipedia+googlenews 需代理，逐个出口实测后注册且结论补能力边界表；超限落盘 `smartsearch.inline_max_chars`；P1-7 处置=三态 `off_topic_guard` 默认 shadow（用户拍板）；小修：学术日期 FormatDateSource 注记 + MCP 握手版本对齐；BuildEngineMode/BuildHybridMode 改用 EngineAdapters 命名结构体）；**四期已取消**；− - **关键证据：** 计划全文 `docs/plans/2026-10-search-upgrade.md`；一期契约层在 `pkg/search/core/diagnostics.go`− - **纪律（用户 mid-turn 明示）：** 遵循项目既有设计风格与原则；提交前性能审查（避免负面性能影响的实现）；每期完成即交接− - **详情指针：** [.handoff/search-upgrade.md](.handoff/search-upgrade.md)− ### file-search — done（v3.7.0 已发布，2026-10-10）− - **已发布：** `feat/file-search-everything` 合入 master（merge `4f33610`）→ `v3.7.0`（GitHub Release 四平台二进制 + GHCR `3.7.0`/`3.7`/`latest`）→ `v3.7.0-registry`（MCP Registry 已收录 `io.github.daidaiJ/websearch-mcpserver 3.7.0`，4 个 mcpb）− - **本次改动：** `file_search` 单页返回默认 10、硬上限 20（`everything.max_results` 改默认值，超限收敛并在响应内说明），新增 `page` 分页（过滤后连续切片，候选池触顶有明确提示）；真机集成测试在 `mcp/tool_filesearch_live_test.go`（`WS_EVERYTHING_URL` 门控，未设置即整包跳过，不走 `internal/testenv`）− - **待办：** 本机部署 `D:\Programs\websearch` 仍跑旧二进制，且 config.yaml 里显式的 `everything.max_results: 50` 会被新硬上限收敛成 20（要默认 10 需删该行或改 10）；registry 缺 `v3.6.1` / `v3.6.2`（历次没打 `-registry` tag），如需补发在自己的原 commit 上补 tag− ### 未验证事项− - [x] 候选零 Key 引擎在国内出口的实际可用性 —— 三期已实测（so360 直连✓ / anysearch 匿名档直连✓ / wikipedia+googlenews 代理✓，结论见能力边界表）− - [x] P1-7 off-topic 守卫处置（2026-10-06 用户拍板：三态 `smartsearch.off_topic_guard`，默认 shadow 只记录不丢弃）；守卫阈值仍未校准，shadow 日志/失败清单为后续校准积累证据− - [x] 超限落盘小项 + 学术日期注记 + 握手版本对齐 —— 三期已完成− - [x] 五期：全量文档同步（docs/search/api/README 补一至三期响应行为说明 + 工具描述适用边界）—— 已完成；P0-3 插件市场分发经评估取消（结论见 .handoff）− - [ ] 三期新引擎真实链路长期回归（验证码页出现频率、anysearch 匿名档限流阈值实测校准、googlenews 回源失败率）− - [ ] 二期冷却落盘真网冷启动回归（重启后 ddg/arxiv 实际避让）；date_source 新旧行缓存往返实测+ > 已完成任务的交接详情已归档至 `.handoff/archive/`（不入库）。此处只保留当前状态、运维待办与待验证项。+ ### 当前状态（2026-10-19）+ - `master` 已推送 `b780769`：优化路线图首批八项落地（R1 context 贯通 + per-engine 软超时、R2 诊断 per-request、R3 缓存并发读、Q1 URL 归一化、Q2 守卫校准回放、O1 `/metrics`、T1 SSRF fuzz、T3 CI race + lint）。全量 `go test ./...`、`go test -race -short ./...`、golangci-lint、actionlint 全绿。+ - 剩余优化项见 [docs/optimization-roadmap.md](docs/optimization-roadmap.md) 待办区：Q3 摘要 token 预算、E1 go-sdk v1.8 升级、T2 引擎解析测试补密度。+ - 待发布：批次 1+3 → `v3.8.x` 补丁版；R1（批次 2）→ `v3.9.0`。`-registry` tag 按发布矩阵在 base Release 就绪后另打。+ ### 运维待办+ - 本机部署 `D:\Programs\websearch` 仍跑旧二进制；其 config.yaml 显式的 `everything.max_results: 50` 会被硬上限收敛为 20（要默认 10 需删该行或改 10）。+ - MCP Registry 缺 `v3.6.1` / `v3.6.2`（历次未打 `-registry` tag），如需补发在原 commit 上补 tag。+ ### 待验证+ - 新引擎真实链路长期回归：验证码页出现频率、anysearch 匿名档限流阈值、googlenews 回源失败率。+ - 冷却落盘真网冷启动回归（重启后 ddg/arxiv 实际避让）；date_source 新旧缓存行往返实测。

https://raw.githubusercontent.com/daidaij/websearch-mcpserver/HEAD/AGENTS.md

− 2. **写操作安全模型（不可退让）**：所有写端点（设置/密钥/重启/清缓存/额度重置修正）= 仅 loopback + `X-Admin-Password` 头，服务端常量时间比较；口令只能配在 `dashboard.yaml`（`admin_password` / `admin_password_sha256`），**永远不出现在设置页白名单和 secrets 覆盖文件**——WebUI 无法读取或修改它。未配置口令 = 写端点整体禁用。− ### search-upgrade — in-progress（一至五期全部完成，待推送）− - **当前状态：** 按五期拆分推进（用户确认）；**一期已提交 `6aa7ca8`**（P0-1 失败透出统一契约 + P1-6 共识按 family 计票 + P1-7 off-topic 整桶守卫 + P1-8 freshness 缓存 TTL）；**二期已提交 `f6da753`**（P1-4 date_source 三态注记 + P1-5 熔断落盘 + P1-10 Resource 化）；**三期已提交 `9b16ef7`**（P0-2 零 Key 来源扩充：so360 直连可用 / anysearch 匿名档 / wikipedia+googlenews 需代理，逐个出口实测后注册且结论补能力边界表；超限落盘 `smartsearch.inline_max_chars`；P1-7 处置=三态 `off_topic_guard` 默认 shadow（用户拍板）；小修：学术日期 FormatDateSource 注记 + MCP 握手版本对齐；BuildEngineMode/BuildHybridMode 改用 EngineAdapters 命名结构体）；**四期已取消**；− - **关键证据：** 计划全文 `docs/plans/2026-10-search-upgrade.md`；分支 `feat/search-upgrade`（基线 master@67ac2fb v3.6.1）；一期契约层在 `pkg/search/core/diagnostics.go`；`feat/file-search-everything` 尚未合并（领先 6 提交）+ 6. **README 顶部配图有渲染源**：`docs/images/src/`（HTML + Playwright 脚本，`python docs/images/src/render.py` 直接覆写 `docs/images/*.png`），改图改 HTML、不要手工编辑 PNG；源与用法见 `docs/images/src/README.md`+ 2. **写操作安全模型（不可退让）**：所有写端点（设置/密钥/重启/清缓存/额度重置修正）**默认仅 loopback** + `X-Admin-Password` 头，服务端常量时间比较。用户可在 `dashboard.yaml` 配置 `write_allowed_networks` 放行任意 CIDR/IP；空值或任一非法条目均回退 loopback。读白名单及转发头不授予写权限。口令只能配在 `dashboard.yaml`（`admin_password` / `admin_password_sha256`），**永远不出现在设置页白名单和 secrets 覆盖文件**——WebUI 无法读取或修改它。未配置口令 = 写端点整体禁用。+ ### search-upgrade — done（v3.6.2 已发布，2026-10-06）+ - **当前状态：** 按五期拆分推进（用户确认）；**一期已提交 `6aa7ca8`**（P0-1 失败透出统一契约 + P1-6 共识按 family 计票 + P1-7 off-topic 整桶守卫 + P1-8 freshness 缓存 TTL）；**二期已提交 `f6da753`**（P1-4 date_source 三态注记 + P1-5 熔断落盘 + P1-10 Resource 化）；**三期已提交 `9b16ef7`**（P0-2 零 Key 来源扩充：so360 直连可用 / anysearch 匿名档 / wikipedia+googlenews 需代理，逐个出口实测后注册且结论补能力边界表；超限落盘 `smartsearch.inline_max_chars`；P1-7 处置=三态 `off_topic_guard` 默认 shadow（用户拍板）；小修：学术日期 FormatDateSource 注记 + MCP 握手版本对齐；BuildEngineMode/BuildHybridMode 改用 EngineAdapters 命名结构体）；**四期已取消**；+ - **关键证据：** 计划全文 `docs/plans/2026-10-search-upgrade.md`；一期契约层在 `pkg/search/core/diagnostics.go`+ ### file-search — done（v3.7.0 已发布，2026-10-10）+ - **已发布：** `feat/file-search-everything` 合入 master（merge `4f33610`）→ `v3.7.0`（GitHub Release 四平台二进制 + GHCR `3.7.0`/`3.7`/`latest`）→ `v3.7.0-registry`（MCP Registry 已收录 `io.github.daidaiJ/websearch-mcpserver 3.7.0`，4 个 mcpb）+ - **本次改动：** `file_search` 单页返回默认 10、硬上限 20（`everything.max_results` 改默认值，超限收敛并在响应内说明），新增 `page` 分页（过滤后连续切片，候选池触顶有明确提示）；真机集成测试在 `mcp/tool_filesearch_live_test.go`（`WS_EVERYTHING_URL` 门控，未设置即整包跳过，不走 `internal/testenv`）+ - **待办：** 本机部署 `D:\Programs\websearch` 仍跑旧二进制，且 config.yaml 里显式的 `everything.max_results: 50` 会被新硬上限收敛成 20（要默认 10 需删该行或改 10）；registry 缺 `v3.6.1` / `v3.6.2`（历次没打 `-registry` tag），如需补发在自己的原 commit 上补 tag

https://raw.githubusercontent.com/daidaij/websearch-mcpserver/HEAD/AGENTS.md

+ | 360 搜索（so360，2026-10-06 出口实测） | 直连与代理均 HTTP 200 + 自然结果（`li.res-list` + `data-mdurl` 真实 URL，`div.g-mohe` 特型卡需过滤）；解析契约对齐上游 so360.py | 已注册（`so360.enabled`，默认关闭）；验证码页 wappass 按反爬拦截报错 |+ | AnySearch 匿名档（2026-10-06 出口实测） | 直连与代理均 200，POST 不带 Authorization 即匿名 IP 限流档（上游 anysearch.py 注释同口径），结果在 `data.results` | KeyPool 为空自动走匿名档，本端保守钳制 1/s·20/min；上游未公布阈值，调参须实测 |+ | Wikipedia / Google News（2026-10-06 出口实测） | 直连均超时；代理下 Wikipedia MediaWiki API 200 + 正常 JSON，Google News RSS 200 + 52 item 且 batchexecute RPC 可回源发布方 URL（f.req 须三层嵌套 + ts 数字形态，否则 400） | 已注册（均需代理，无可用代理解析时跳过）；Google News 解析契约对齐上游 gnews.py |+ ## 本地环境+ - **Go 构建临时目录**：`GOTMPDIR=D:	mp`（`go env -w` + 用户环境变量已配置）。卡巴斯基锁定系统 TEMP 会导致 `go build` 偶发 Access denied，构建/测试编译临时目录已统一指向 `D:	mp`，在该目录配置杀软排除即可规避；`go test` 的 `t.TempDir()` 数据目录仍走系统 TEMP（改全局 TMP/TEMP 影响面大，未动）。+ ## 🔄 Handoff 摘要+ ### search-upgrade — in-progress（一至五期全部完成，待推送）+ - **当前状态：** 按五期拆分推进（用户确认）；**一期已提交 `6aa7ca8`**（P0-1 失败透出统一契约 + P1-6 共识按 family 计票 + P1-7 off-topic 整桶守卫 + P1-8 freshness 缓存 TTL）；**二期已提交 `f6da753`**（P1-4 date_source 三态注记 + P1-5 熔断落盘 + P1-10 Resource 化）；**三期已提交 `9b16ef7`**（P0-2 零 Key 来源扩充：so360 直连可用 / anysearch 匿名档 / wikipedia+googlenews 需代理，逐个出口实测后注册且结论补能力边界表；超限落盘 `smartsearch.inline_max_chars`；P1-7 处置=三态 `off_topic_guard` 默认 shadow（用户拍板）；小修：学术日期 FormatDateSource 注记 + MCP 握手版本对齐；BuildEngineMode/BuildHybridMode 改用 EngineAdapters 命名结构体）；**四期已取消**；+ - **关键证据：** 计划全文 `docs/plans/2026-10-search-upgrade.md`；分支 `feat/search-upgrade`（基线 master@67ac2fb v3.6.1）；一期契约层在 `pkg/search/core/diagnostics.go`；`feat/file-search-everything` 尚未合并（领先 6 提交）+ - **纪律（用户 mid-turn 明示）：** 遵循项目既有设计风格与原则；提交前性能审查（避免负面性能影响的实现）；每期完成即交接+ - **详情指针：** [.handoff/search-upgrade.md](.handoff/search-upgrade.md)+ ### 未验证事项+ - [x] 候选零 Key 引擎在国内出口的实际可用性 —— 三期已实测（so360 直连✓ / anysearch 匿名档直连✓ / wikipedia+googlenews 代理✓，结论见能力边界表）+ - [x] P1-7 off-topic 守卫处置（2026-10-06 用户拍板：三态 `smartsearch.off_topic_guard`，默认 shadow 只记录不丢弃）；守卫阈值仍未校准，shadow 日志/失败清单为后续校准积累证据+ - [x] 超限落盘小项 + 学术日期注记 + 握手版本对齐 —— 三期已完成+ - [x] 五期：全量文档同步（docs/search/api/README 补一至三期响应行为说明 + 工具描述适用边界）—— 已完成；P0-3 插件市场分发经评估取消（结论见 .handoff）+ - [ ] 三期新引擎真实链路长期回归（验证码页出现频率、anysearch 匿名档限流阈值实测校准、googlenews 回源失败率）+ - [ ] 二期冷却落盘真网冷启动回归（重启后 ddg/arxiv 实际避让）；date_source 新旧行缓存往返实测