AskaEth/Cyrene_v2
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(search): 新增腾讯云·元宝搜索与秘塔搜索两家 provider
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
Details
CI / Frontend (tsc + vite build) (push) Has been cancelled
Details

Browse Source 
接入位表六家扩到八家，端点形状与错误码一字未改（契约 v0.87，仅两处名单）。

- tencent_wsa：POST {base}/SearchPro + Authorization Bearer，零签名。
  两条官方口径决定实现：HTTP 状态码恒 200（判失败只能读 Response.Error.Code）；
  Pages 是「JSON 字符串数组」需二次解析。错误码按官方表分类
  （UnauthorizedOperation/AuthFailure.* = 凭据、ResourceUnavailable = 欠费、
  RequestLimitExceeded* = 限流），文案只带 code 不带上游 Message。
- metaso：POST {base}/api/v1/search，响应 schema 仅第三方来源且互相打架，
  实现走宽松解析（数组候选与字段名回退），逐处标「未实测」。
- 零新 env 键：两家只走 $DATA_DIR/config/plugins/web-search.json，
  .env / .env.example 未动；组合根 websearch_providers.go 零功能改动。
- 契约 v0.87：values.provider 合法闭集与 plugin.providers 候选各加两条，
  计数不变（14 + 25 + 40 = 79）。
This commit is contained in:
AskaEth committed 2026-10-07 13:42:41 +08:00
1 parent 8e3311cea2
commit ce9af42945
21 files changed
+1219 -36
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Docs/api-client.md
+15 -4
View File
@@ -1,6 +1,6 @@
# Cyrene v2 客户端 API 契约
> **契约版本：`v0.86`**（上一版 `v0.85`，其条目见 §6；`v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。
> **契约版本：`v0.87`**（上一版 `v0.86`，其条目见 §6；`v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。
> **读者**：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等**跨平台客户端开发者**。
> **唯一真源 = 当前代码**（`internal/services/gateway/*` 等）。本文档由代码逐条核对得出；与代码不符时**以代码为准**，并回改本文档。
> **旧的超详细版已归档、只读**：`Docs/archive/api-client.v0.65.md`（412 KB，含 v0.28→v0.65 全部历史条目）与 `Docs/archive/api-reference.v0.65.md`（170 KB，后端全量字段级文档）。归档的原因是**结构性臃肿 + 历史条目并列 + 长期漂移**；本文档**不复制**那段历史，需要考古时去归档。
@@ -23,6 +23,7 @@
> **v0.77 是链路图按路分桶 + 记忆整理护栏/异步落地版（已实现；纯增量）**：① **`graph_update` 按路分桶**（切片 FV2）—— 帧 `data` 新增可选 `turnId`（该图的**路**的权威回合标识）与 `round`（会话轮次号）；真并行（`parallel:true`）时同一会话**每一路各发自己的帧**（`data.id` / `data.turnId` 各不相同），两路不再互相顶掉；`GET /api/v1/admin/flow/graph` 响应新增 `lanes[]`（**最近一轮每一路**的图，恒为非 null 数组），`graph` 语义不变（最新一路 / 指定轮 / `null` 诚实空态）⇒ **老的读取方零改动**。**无破坏性变更**（两个新键可选；单路时 `turnId` 缺席 ⇒ 客户端行为与 v0.75 逐字相同）。详见 **§2.2 B13 / §3.4.5 / §4.11 / §7.4-19**。② **记忆整理护栏抬高 + 诚实截断 + 试算异步落地**（切片 MT-A）—— 每分区候选上限 `MEMORY_TIDY_CANDIDATE_LIMIT` 默认值 `20 → 200`、两两比对上限改为 env 键新键 `MEMORY_TIDY_COMPARE_LIMIT`（默认 `2000`，原先**写死** `400`）；配置事实面 **12 → 13 条**；`truncated` 新增第 4 种标签 **`(budget)`**（墙钟时间预算截断）；**v0.76 ③ 的加性异步已落地**（`?async=1` + B15 轮询可用；新错误码 **`tidy_run_not_found`**）。详见 **§2.2 B14/B15 / §4.10(a) / §4.12 / §4.12.1 / §5**。③ **「入库前审查」的 4 个 env 键登记**（切片 MT-B，纯增量）—— `MEMORY_REVIEW_ENABLED`（`true`）/ `MEMORY_REVIEW_QUEUE_SIZE`（`256`）/ `MEMORY_REVIEW_SCAN_LIMIT`（`200`）/ `MEMORY_REVIEW_TIMEOUT_SEC`（`20`）；⚠️ 该切片的**面板读侧 / 回滚端点目前没有 HTTP 入口**（见 §7.2）。详见 **§5**。
> **v0.86 是「搜索结果条数上限可配」版（已实现并推库 `bff57bd` + `c68387a`；**纯增量：面板多一个 number 字段 + 两个动作各多一个键；无破坏性变更**）**：`web-search` 的「结果条数上限」从**改不了**变成**面板上真能改**（此前三处断点：字段表里没这个字段 / `saveProvider` 只并四个键 / `mergeSelectionPatch` 只处理 `primary`+`fallback` ⇒ **手工塞进 `values` 也会被静默丢弃**，「我改了它却没变」成立）。① **面板声明**新增字段：`pluginId=web-search` / `panel=providers` / form `add` 多一个 **`maxResults`**（`type:"number"`, `min:1`, 标签「结果条数上限（默认 10）」）—— 前端本就渲染 `number` ⇒ **客户端零改动**。② **`plugin.saveProvider` 的 `values` 新增可写键 `maxResults`**：**三态** —— 缺位/null ⇒ 不改动；**正整数**（含整数字符串）⇒ 采用；`0` / 负数 / 小数 / 空串 / 非数 / 布尔 / 数组 ⇒ **`400 invalid_payload`**，且**盘上一字节不动**（**绝不静默忽略**）。③ 响应新增回显：`plugin.saveProvider` 的 `data.result.maxResults`（**0 = 文件里未声明**）、`plugin.reauthProvider` 的 `values.maxResults`（盘上有值才出现 ⇒ 用于「重配凭据」回填，否则一保存就把上限清掉）。④ **语义**：面板文件的 `maxResults` **压过** `.env` 的 `WEB_SEARCH_MAX_RESULTS`，是**运行期真上限**（模型的 `count` 只能更小），**保存即生效**（走既有热重载，响应里的 `hotReload`）；代码默认值 **5 → 10**（三处口径已一致：env 默认 / io 包 `defaultMaxResults` / 面板文件）。⑤ **计数不变**（无新端点 ⇒ §2.0 维持 `14 + 25 + 40 = 79`）。⚠️ **已知取舍（如实）**：**清空输入框 = `400`**（后端按「非数 ⇒ 报错」拒）⇒ 面板上**没有「去掉上限」的手势**（要回到 `.env` 兜底得改文件）；**小数/负数一律拒**；文件里没写该键时 `reauth` **不回填**（避免回填 0 让保存整笔进不去），因此那个框是空的、看不出当前生效值。
> **v0.87 是「搜索 provider 扩到八家」版（已实现，纯增量；⚠️ 两家的成功响应都未真机实测）**：新增两家已登记接入位 —— **`tencent_wsa`**（腾讯云·元宝搜索，`POST {base}/SearchPro` + `Authorization: Bearer`，**零签名**；🔴 **HTTP 状态码恒 200** ⇒ 判失败**只能**读响应体 `Response.Error.Code`；`Pages` 是**JSON 字符串数组** ⇒ 需二次解析）与 **`metaso`**（秘塔搜索，`POST {base}/api/v1/search`；⚠️ 响应 schema 全部来自第三方来源且互相打架 ⇒ 实现走**宽松解析、未实测**）。对客户端的**唯一影响是两处名单**：`plugin.saveProvider` 的 `values.provider` 合法闭集（**六家 → 八家**）与 `plugin.providers` 的候选（多两条 `{value,label}`，中文名见 §6 本版条目）—— **端点形状 / 错误码 / 三态写回语义 / §2.0 计数（`14 + 25 + 40 = 79`）全部一字未改**，且前端候选本就是 `optionsFrom` 数据驱动 ⇒ **客户端零改动**。**零新配置键**：两家只走 `$DATA_DIR/config/plugins/web-search.json`，`.env` / `.env.example` **未动**。
> **v0.85 是「整理不再只产建议」版（已实现并推库 `6d92536`；**新增 1 条 writeAuth 端点 + 一处行为变更（整理默认自动落地）+ `link` 候选停产；无破坏性变更**）**：① **新增端点 `POST /api/v1/admin/memories/candidates/reject?action=&limit=`（B25）** —— 按**动作**批量把 `pending` 候选标成 `rejected`（**幂等、只改候选状态、绝不碰记忆行**）。`action` **必填**且是**闭集**（`merge|link|archive|reclassify|keep`，未知值 → `400 bad_request`）；`limit` 缺省 **1000**、硬顶 **10000**、非整数 → `400`。`200 {data:{action,limit,total,rejected,truncated}}`（`total` 是命中筛选的**真**条数，`rejected` 只覆盖 `limit` 之内 ⇒ 不等时 `truncated:true`）。审计 `memory.tidy.reject`（只带计数）。语义见 **§4.15(e)**。② 🔴 **行为变更（默认生效）：整理在轮末会「自动落地」两类高置信动作**，不再只产建议（主人 2026-10-07 口径「该删就删」）——**可自动的只有**：`merge`（**字面重复** ∨「事实集合等价 ∧ 相似度 ≥ 0.95」）、`archive`（理由 = `one_off_event` **且不像习惯**）。**不自动**：`reclassify`、低置信 merge、跨分区/跨角色、任何改正文、**受限来源（群聊/陌生人）**。六条护栏：软动作（正文不改、行不删）/ **每轮上限 50**（硬顶 500，超限如实 `truncated`）/ 审计 `memory.tidy.apply`（`auto=true`）/ **可 revert**（回滚路径与人工应用同一条）/ 幂等 / **一键关回只产建议**（`$DATA_DIR/config/memory-tidy.json` 的 `{"autoApply": false}`，**零新 env 键**）。⚠️ **面板侧的候选列表仍可能显示历史 `link` 行**，直到用 B25 清掉。③ **`link` 候选停产**：`link` 在 `design/23 §14` 里被列为**未细化**（既无落点也无数据模型），且 `applyable()` 只认 merge/archive/reclassify ⇒ **应用 link 恒 `skipped`，产出它只是往待办里灌噪音**。现在规则层不再产出（判 `keep`）；`TidyLink` 常量保留**只为读历史行**。存量用 B25 清（主会话已执行）。④ **计数**：`writeAuth` 段 24 → **25**、管理路由总数 78 → **79**（`14 + 25 + 40`；`routes.go` 核：经 `writeAuth` 挂载的 admin 路由实有 **27**，按历史口径减 §2.4(a) 的 `channels/events` 与 `.../counters` ⇒ **25**）。⑤ ⚠️ **诚实边界**：**未部署**（要一次 `build` + `restart`）；**自动档的真机行为未验**（不能重启后端）；`reclassify` 仍全部人工；`TidyRuleVersion` **刻意未升版**（本次不改变任何判定结论，升版会让既有候选按幂等键复制出重复行）。
@@ -1254,7 +1255,7 @@
| `plugin.testProvider` | 测试连通（**真发一次最小检索**） | write（table `rowActions`） | `{"row":{"provider":"bocha"}}`（亦可给 `{"values":{…}}` 或顶层 `provider`） | `{"ok":true,"provider":"bocha","count":1,"latencyMs":123}`；**没通 = 非 2xx**（见错误表），**不在 200 里回 `ok:false`** |
| `plugin.reauthProvider` | 重配凭据：把该条带回表单 | write（table `rowActions`） | `{"row":{"provider":"bocha"}}` | `{"values":{"provider":"bocha","apiKey":"****cdef","baseUrl":"https://api.bocha.cn","enabled":true,"primary":"bocha","fallback":["searxng"]}}`（**`apiKey` 只回掩码**；前端对 secret 字段一律不回填输入框，**空 = 不改动**）。⚠️ **v0.80 起 `values` 另带两个文件级字段** `primary`（字符串）/ `fallback`（字符串数组）—— **不带它们**的话，面板「清空降级链」在客户端三态写回里会落成「缺位 = 不改动」（**清不掉**） |
`plugin.saveProvider` 的**三态写回哨兵**（写侧语义，前端须照此送值）：`values.apiKey` **缺位** ⇒ 保留盘上原值；**空串** ⇒ 显式清空；非空 ⇒ 覆盖。`values.baseUrl` / `values.enabled` **缺位** ⇒ 保留；给出（含 `""` / `false`）⇒ 采用（`enabled` 给非布尔值 ⇒ `400 invalid_payload`，**不静默保留**）。`values.provider` **必填**，且必须是本期已登记的接入位（`searxng` / `zhipu` / `aliyun_iqs` / `bocha` / `volcengine` / `baidu_qianfan`），否则 `400 unknown_provider`。
`plugin.saveProvider` 的**三态写回哨兵**（写侧语义，前端须照此送值）：`values.apiKey` **缺位** ⇒ 保留盘上原值；**空串** ⇒ 显式清空；非空 ⇒ 覆盖。`values.baseUrl` / `values.enabled` **缺位** ⇒ 保留；给出（含 `""` / `false`）⇒ 采用（`enabled` 给非布尔值 ⇒ `400 invalid_payload`，**不静默保留**）。`values.provider` **必填**，且必须是本期已登记的接入位（`searxng` / `zhipu` / `aliyun_iqs` / `bocha` / `volcengine` / `baidu_qianfan` / **`tencent_wsa`** / **`metaso`**），否则 `400 unknown_provider`。🆕 **v0.87：名单由六家扩到八家**（新增腾讯云·元宝搜索与秘塔搜索），**端点形状与错误码一字未改**。
**（v0.80 新增）两个文件级字段的三态写回**（与条目字段同一套哨兵语义）：`values.primary` **缺位** ⇒ 保留盘上值；给字符串（含空串 / `off` / `none`）⇒ 采用 —— **空串与 `off` / `none` 都是「关掉这把工具」的哨兵**（`off` / `none` 大小写与空白不敏感），`WEB_SEARCH_PROVIDER` 与面板**共用同一套关闭语义**（不另造第二套）。`values.primary` 指名一家**已登记但未配齐**的家 ⇒ **`400 primary_not_configured`**（**写盘之前**就拒，因为那份配置会让后端下次起不来）。`values.fallback` **缺位** ⇒ 保留；给数组（或逗号 / 顿号 / 分号 / 换行分隔的字符串）⇒ 采用（去空白、去重、丢空项）；元素**未登记** ⇒ `400 unknown_provider`；给非数组 / 非字符串 ⇒ `400 invalid_payload`（**不静默当空数组** —— 那等于一次保存悄悄清空降级链）。降级链**允许**放本期已登记但**尚未配齐**的家（运行期会跳过它）。
@@ -1486,7 +1487,17 @@ curl -s -X POST -H "X-API-Key: $KEY" \
> 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。
> 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。**
### v0.86（当前契约版本）
### v0.87（当前契约版本）
**「搜索 provider 扩到八家」版 —— 名单扩充，端点形状与错误码一字未改**（切片 `agent-389`，本次提交；依据：主人「我看之前不是走有头CDP扒了好几家搜索提供商的接口方式在本地参考文档吗？为什么不都做一下适配？」+「优先只做国内能用到的几家」。）
- **新增两家已登记接入位**：`tencent_wsa`（腾讯云·元宝搜索，`POST {base}/SearchPro` + `Authorization: Bearer`，**零签名**）与 `metaso`（秘塔搜索，`POST {base}/api/v1/search`）。
- **契约面影响（只有两处，且都是名单扩充）**：① `plugin.saveProvider` 的 `values.provider` 合法名单 **六家 → 八家**（见 §4.14 的三态写回那段）；② `plugin.providers` 候选新增两条 `{value,label}`（中文名见 §6 本版上方那条的逐字表）。**§2.0 计数不变**（无新端点，维持 `14 + 25 + 40 = 79`）。
- **前端零改动**：候选是数据驱动的（`optionsFrom`），中文名只是 `label`。
- ⚠️ **诚实边界（如实，别当已验）**：① **腾讯成功响应未真机实测**（无 key）—— 依据是官方文档 + 本机无 key 探测（缺 `Authorization` 也回 **HTTP 200** + `Response.Error`）；② **秘塔响应 schema 全部来自第三方来源且互相打架** ⇒ 代码走**宽松解析**（多字段名回退），**未真机验证**，拿到真 key 后必须按真实报文收窄；③ 两家的请求体都**只发官方确证为必选的字段**（腾讯只发 `Query`），条数靠本地截断。
- **零新配置键**：两家只走 `$DATA_DIR/config/plugins/web-search.json`；`.env` / `.env.example` **未动**（`.env` 冻结口径不变）。
### v0.86
**「搜索结果条数上限可配」版 —— 面板多一个 number 字段 + 两个动作各多一个键**（切片 `bff57bd` + `c68387a`；依据：主人 2026-10-07 口径「返回五条结果会不会太少了？」+ 上一片登记的「`maxResults` 在面板上根本改不了」那条真缺陷。）
@@ -1510,7 +1521,7 @@ curl -s -X POST -H "X-API-Key: $KEY" \
**「显示名 + 段落标签硬约束」版 —— 一处形状变更（插件动作响应）+ 一处新增产出侧硬约束 + 一条模型面登记**（依据：主人报障「下拉里全给英文名，你甚至不愿意带个括号把中文名写上去」；安卓端登记 `<p><p>正文</p>` 畸形；`design/28 §1 M5 / §8 B5` 的浏览器降级档。切片：显示名 `c46053e`、段落修复 `8051906`、provider 配置面去 env 化 `bc1dee3`、搜索 linkless 修复 `2c56bc9`。）
- **① 形状变更：`plugin.providers` 候选从裸字符串数组 → 对象数组 `{value,label}`**。见 **§4.14(c)** 与 §2.1 A14。根因**不是**漏写文案，而是**整条链路没有「显示名」的位置**（字段声明只有 `optionsFrom`，动作回的就是 `KnownNames()` 的纯 id 数组）。中文名逐字：`SearXNG 本地兜底（searxng）` / `智谱 BigModel（zhipu）` / `阿里云 IQS 信息查询（aliyun_iqs）` / `博查 Bocha（bocha）` / `火山引擎·豆包搜索（volcengine）` / `百度千帆 AI 搜索（baidu_qianfan）`。🔴 **`label` 仅供显示、`value` 才是落盘值**；前端解码器兼容三种形状 ⇒ 其他插件零影响；表格按 `value→label` 索引显示、查不到回落原值。
- **① 形状变更：`plugin.providers` 候选从裸字符串数组 → 对象数组 `{value,label}`**。见 **§4.14(c)** 与 §2.1 A14。根因**不是**漏写文案，而是**整条链路没有「显示名」的位置**（字段声明只有 `optionsFrom`，动作回的就是 `KnownNames()` 的纯 id 数组）。中文名逐字：`SearXNG 本地兜底（searxng）` / `智谱 BigModel（zhipu）` / `阿里云 IQS 信息查询（aliyun_iqs）` / `博查 Bocha（bocha）` / `火山引擎·豆包搜索（volcengine）` / `百度千帆 AI 搜索（baidu_qianfan）` / **`腾讯云·元宝搜索（tencent_wsa）`** / **`秘塔搜索 Metaso（metaso）`**（🆕 **v0.87 起八家**）。🔴 **`label` 仅供显示、`value` 才是落盘值**；前端解码器兼容三种形状 ⇒ 其他插件零影响；表格按 `value→label` 索引显示、查不到回落原值。
- **② 新增产出侧硬约束：助手文本不得出现未配对的段落标签**（落单 `<p …>` / `</p>`）。见 **§4.16**。修的是安卓登记的 `<p><p>正文</p>`；**两半根因都在产出侧**（规整器原样放过 + 在「末段漏 `</p>`」时亲手制造），另修一个幂等漏洞。**历史行不回填**、消费方**仍应保留**容错。
- **③ 模型面登记（非客户端契约面）**：`web-fetch` 的浏览器渲染降级档已接线，返回体用 `fetchedBy`（`direct` / `browser`）**如实标注**正文实际来自哪条路；两条档的失败各自留痕，**绝不静默替换**，被 SSRF 拒绝的目标**不换路**。
- **④ provider 配置面「去 env 化」（对客户端零形状影响，登记供跨端对照）**：新增 provider 不再需要新的 `.env` 键 —— 面板文件 `$DATA_DIR/config/plugins/web-search.json` **是权威**，`.env` 只在文件缺失/为空时**播种**（文件一旦存在，「文件里没有的家」**不从 env 复活** —— 这是既有回归用例钉住的口径，本次未改）；各家「没配 baseUrl 就回落代码默认值」的默认值表移进接入位表（`search.Descriptor.DefaultBaseURL`），**逐字未变**。