weflow-cli 1.15.1 → 1.17.0

package/docs/DATA_CONTRACT.md

@@ -72,3 +72,28 @@ This is a best-effort synchronization recipe. It must not treat a timestamp as a
 ## Future Direction
 
 The existing CLI export is the compatibility layer for the first integration. The same contract is available through the versioned, read-only MCP tool `wechat.export_messages`. It accepts `contact` and optional `limit`, `from`, and `to` values, returns JSON directly, and never returns database paths or keys. It preserves the same authorization, local-only default, field semantics, and privacy rules rather than bypassing the CLI boundary.
+
+## QQ Imports (qchat-cli)
+
+A second upstream now feeds this contract's vocabulary: `weflow-cli import qchat <file-or-dir>`
+reads a `qchat-cli` JSON export (`qce export --format json`) and lands it in a local private
+store `output/imports/qq/sessions/` (schema `weflow-import/qq-v1`, D-129). The store itself is
+not a stable contract; what is stable is the **field semantics**, which are exactly
+`weflow-message/v1`'s:
+
+| qchat-cli field | imported as | Notes |
+| --- | --- | --- |
+| `messageId` | `serverId` | Server-side globally unique (OneBot) - dedup/merge keys on it, no overlapping-window dance needed. |
+| `timestamp` | `createTime` | Unix seconds. |
+| `sender.id` | `senderUsername` | A QQ number; treat as sensitive, same level as a wxid. |
+| `sender.card` / `sender.name` | `senderName` | Group card first, then nickname. |
+| `content` / `rawMessage` | `parsedContent` / `rawContent` | Same guidance as the table above. |
+| (derived from `segments`) | `messageType` | OneBot segment types map onto the same stable names (`record→voice`, `reply→quote`, `json/xml→card`, …). |
+| — | `isSend` | Only present when the import ran with `--own-id`; absent means unknown, not false. |
+
+Consumers wired today (both opt-in, defaults unchanged): `chat-notes --source qq|all` produces
+QQ knowledge cards (names prefixed `QQ-`, same card shape and same downstream wiki consumer as
+WeChat conversations), and `search-index --include-imports` adds QQ sessions to the semantic
+index (record ids carry a `chat:qq:` segment, so a record's origin is always readable from the
+id; the phrase index derives from the semantic index and follows). Querying QQ sessions through
+`sessions` / `messages` is deliberately not part of this round (D-129).

package/docs/DECISIONS.md

@@ -4017,33 +4017,95 @@ State the decision in one or two sentences.
 
 **Consequences:** List compatibility, migration, security, or documentation follow-up when relevant.
 ```
-
-## D-127: 决策模型可以走本机（`judgeProvider=local`），概率默认当作未校准
-
-**Decision.** 新增第四条判断通路 `judgeProvider=local`：`LocalJevClient` 把本机决策模型服务
-（`decide.py serve`，APUS Reflex 4B + llama-server 的 `/decide`）当 Jev 用，**不需要 key、不联网**。
-`score` 没有连续分，改用 `choice` 在有序档位上选、把选中档位的下标当分数（下游 `score_to_relevance`
-本来就是四舍五入取整，语义等价）。
-
-**Reason.** 原生 `api.typesafe.ai` 在本机被地区封锁（D-120），`chat` 与 `openrouter` 都要把文章正文
-发给第三方。本机 4B 决策模型在官方 Frozen80 上 **66/80 = 82.50%**、**0.3 s/题**（2026-10-22 本机实测，
-RTX 5060 8GB），对"主题 / 相关度 / 该不该收录"这类**窄口径、可验证**的判断够用，而正文不出机器。
-
-**Consequences.**
-- 本机服务的概率是**候选集上的相对 softmax、未校准**（APUS 契约原文）。`confidence` 只作参考，
-  不能直接当自动放行阈值；要用阈值先在自有样本上标定。
-- **一个问题一次 HTTP**：原生 `systemone` 一次答一组，本机 `/decide` 一次只答一个 primitive。
-  日报 3 个问题 ⇒ 3 次调用，实测整篇 0.3–0.5 s（本机回环）。
-- `score` 用 **n-1 次阈值判断**（`达到「中」或「高」吗？`）合成档位，不是三选一：
-  同一批 44 篇（2026-10-16~21，Jev 实判）上，三选一对 Jev 的一致率 45.5%（`低→中` 23 次，
-  系统性偏高），阈值问法 **72.7%**、平均差 0.55 → 0.27 档。**措辞影响巨大**（同一模型同一批样本：
-  纯判据句 59.1%、带主语 + 档位 + 判据 72.7%），改这句话要重测。
-- 服务没起时抛 `JevError`（调用方按既有降级路径退到 LLM 路径），**不静默改用云端**。
-- 新增配置键 `judgeLocalUrl`（默认 `http://127.0.0.1:8090`），已登记进 `CliConfig` 与 `config set`。
-- **按主题的相关度下限（实测校准）**：211 篇同题对比（2026-10-16~21，Jev 实判）显示本机模型对
-  `AI` 类文章的相关度**系统性低估一档**（该类一致率 20.0%，`低→中` 33 次；政治/文学/新闻 90%+）。
-  `LocalJevClient.TOPIC_RELEVANCE_FLOOR = {'AI': 1}` 只把 `AI` 的 `低` 抬到 `中`：
-  该类 77.5%、总体 73.9% → 84.4%（68 篇复测 80.9%）。统一 +1 只有 82.9% 且会越界，故不采用。
-  这张表是**数据产物**：换语料/换模型要重测，`usage.calibration` 会落盘，便于事后核对。
-- 收录阈值：Jev 0.5 时收录 32/211；本机同阈值收录 30 篇、判定一致 86.7%；降到 0.35 收录 32 篇、
-  一致率不变 —— 要与 Jev 的"收录量"对齐就把阈值降到 0.35，要更保守就留 0.5。
+
+## D-127: 决策模型可以走本机（`judgeProvider=local`），概率默认当作未校准
+
+**Decision.** 新增第四条判断通路 `judgeProvider=local`：`LocalJevClient` 把本机决策模型服务
+（`decide.py serve`，APUS Reflex 4B + llama-server 的 `/decide`）当 Jev 用，**不需要 key、不联网**。
+`score` 没有连续分，改用 `choice` 在有序档位上选、把选中档位的下标当分数（下游 `score_to_relevance`
+本来就是四舍五入取整，语义等价）。
+
+**Reason.** 原生 `api.typesafe.ai` 在本机被地区封锁（D-120），`chat` 与 `openrouter` 都要把文章正文
+发给第三方。本机 4B 决策模型在官方 Frozen80 上 **66/80 = 82.50%**、**0.3 s/题**（2026-10-22 本机实测，
+RTX 5060 8GB），对"主题 / 相关度 / 该不该收录"这类**窄口径、可验证**的判断够用，而正文不出机器。
+
+**Consequences.**
+- 本机服务的概率是**候选集上的相对 softmax、未校准**（APUS 契约原文）。`confidence` 只作参考，
+  不能直接当自动放行阈值；要用阈值先在自有样本上标定。
+- **一个问题一次 HTTP**：原生 `systemone` 一次答一组，本机 `/decide` 一次只答一个 primitive。
+  日报 3 个问题 ⇒ 3 次调用，实测整篇 0.3–0.5 s（本机回环）。
+- `score` 用 **n-1 次阈值判断**（`达到「中」或「高」吗？`）合成档位，不是三选一：
+  同一批 44 篇（2026-10-16~21，Jev 实判）上，三选一对 Jev 的一致率 45.5%（`低→中` 23 次，
+  系统性偏高），阈值问法 **72.7%**、平均差 0.55 → 0.27 档。**措辞影响巨大**（同一模型同一批样本：
+  纯判据句 59.1%、带主语 + 档位 + 判据 72.7%），改这句话要重测。
+- 服务没起时抛 `JevError`（调用方按既有降级路径退到 LLM 路径），**不静默改用云端**。
+- 新增配置键 `judgeLocalUrl`（默认 `http://127.0.0.1:8090`），已登记进 `CliConfig` 与 `config set`。
+- **按主题的相关度下限（实测校准）**：211 篇同题对比（2026-10-16~21，Jev 实判）显示本机模型对
+  `AI` 类文章的相关度**系统性低估一档**（该类一致率 20.0%，`低→中` 33 次；政治/文学/新闻 90%+）。
+  `LocalJevClient.TOPIC_RELEVANCE_FLOOR = {'AI': 1}` 只把 `AI` 的 `低` 抬到 `中`：
+  该类 77.5%、总体 73.9% → 84.4%（68 篇复测 80.9%）。统一 +1 只有 82.9% 且会越界，故不采用。
+  这张表是**数据产物**：换语料/换模型要重测，`usage.calibration` 会落盘，便于事后核对。
+- 收录阈值：Jev 0.5 时收录 32/211；本机同阈值收录 30 篇、判定一致 86.7%；降到 0.35 收录 32 篇、
+  一致率不变 —— 要与 Jev 的"收录量"对齐就把阈值降到 0.35，要更保守就留 0.5。
+
+
+## D-128: 入站图片可以给助手看——它是一类新的出境，门与 D-042 同构
+
+**Status:** Active
+
+**Decision.** Bot 通道收到、且已按 `wechatMediaDownload=true` 落盘解密（D-042 的下载侧）的**图片**，
+助手可以用 `look_at_image` 的 `#信N` 句柄查看。门与 D-042 看聊天图片的那道门**同构、双层**：
+strict 模式（且非本地推理）下工具拒绝取图、`toApiMessages` 再拦一层；balanced / open 放行；
+`IMAGE_SENT` / `IMAGE_HELD` 审计与 `MAX_IMAGES_PER_TURN` 预算**共用**，不分来源。语音、视频、
+文件的消费**不在本决策内**——各自需要转写 / 压缩 / 解析，是另外的出境类别，不搭车。
+
+**Reason.** 图片消息此前整条被忽略（日志里的「忽略非文本消息 (image)」），而文件其实已经在
+本机磁盘上、下载本身已是显式 opt-in（`wechatMediaDownload` 默认 false）。但 D-042 立过的规矩
+仍然成立：「一句关于聊天的话」与「聊天里的那张照片」不是同一种披露——入站图片是**别人发给
+用户的照片**，比聊天截图又多一层：出境的内容甚至不是用户自己写的。所以决策先行、范围收窄：
+仅图片、仅 balanced / open（strict + 本地推理等于不出机器，照放）、句柄只在能看时展示
+（与 `get_messages` 的 `#N` 同一规则——不摆出一个工具必定会拒绝的东西）。
+
+**Consequences.**
+- 一条**只有图片**的来信从此会产生一轮（此前被忽略）：文本占位「（发来一张图片）」，白名单、
+  配额、串行队列照常走；未开下载或下载失败（`filePath` 为空）的图片消息**仍被忽略**，行为不变。
+- `#信N` 只指本轮来信自带的图片；`#N` 仍指聊天记录里的 `local_id`。两个句柄空间不混——
+  前者是磁盘上现成的文件，后者要跑 `read_image.py` 建媒体索引，成本差一个数量级。
+- 图片**不缩放**，超过 4 MB 直接说「太大」：入站文件是证据形态，缩了再给模型看，模型说的
+  就不是那张图（导出路径做缩放是因为那是**给人看**的页面，两者方向相反）。
+- MIME 从文件头魔数判定（png / jpeg / webp），不信任文件名扩展名——文件名来自服务端报文。
+- MCP 面不变：`look_at_image` 本来就不在 MCP 表里（文本传输接不到侧信道的图）。
+- 审计 `IMAGE_SENT` 的 `ids=` 对入站图片为空（没有 local_id）——`n=` 照记，能对上"这轮发了几张"。
+
+
+## D-129: qchat-cli 的消息从**文件契约**进来，不做进程耦合，也不当第五个消息后端
+
+**Status:** Active
+
+**Decision.** `weflow-cli import qchat <文件|目录>` 读 qchat-cli `qce export --format json`
+的产物，归一化落到本地私有存储 `output/imports/qq/sessions/`（schema `weflow-import/qq-v1`，
+字段语义与 `weflow-message/v1` 对齐：serverId/createTime/parsedContent/rawContent 与 13 个稳定
+messageType）。下游两条已落地的管道各开一个**显式开关**：`chat-notes --source qq|all` 产 QQ
+知识卡（卡片名带 `QQ-` 前缀，与微信卡同一形状、同一消费端），`search-index --include-imports`
+把 QQ 会话收进语义索引（记录 id 带 `chat:qq:` 段，与微信记录天然不撞；短语索引从语义索引
+派生，自动跟上）。默认行为逐字不变。
+
+**Reason.** 两个仓库的数据获取层性质不同（weflow 直读本地加密库、离线可查；qchat 走
+NapCatQQ/OneBot 在线服务）。让 weflow 直连 OneBot 当第五个 `chatService` 后端，等于把 qchat
+的整个客户端层复刻进 weflow、两个工具抢同一个轮询——且 `chatService` 的四个后端全是"解本地
+库"的，混进一个在线 API 客户端会改变这层的性质。文件契约让边界可枚举、可版本化，也正是
+ROADMAP P1 给 she-love-me 预留的同一条路；qchat-cli 因此**一行不用改**。
+
+**Consequences.**
+- QQ 的 `messageId` 是服务端全局唯一：去重/合并按它做，**不需要**微信侧那套重叠时间窗；
+  对 D-027 而言 qq 来源天然满足 stable-identity 判据。
+- `isSend` 只在导入时给了 `--own-id` 才写；缺省就是未知，消费方按未知处理（知识卡的行
+  标签落到群名片/昵称）。不为"好看"猜方向。
+- 存储是 **weflow 的私有形状**，不承诺稳定；对外承诺的边界是 `weflow-message/v1` 那套
+  字段语义。将来 qchat 侧产出中立契约（如 `im-message/v1`）时，读取器多认一个 schema 即可。
+- 查询层（`sessions`/`messages` 按 QQ 会话直查、per-source 路由）**明确不在本决策内**：
+  等真实需求出现再做，届时 QQ 号与 wxid 的命名空间隔离（`qq:` 前缀已备好）是第一件事。
+- 隐私边界对齐：导入的是用户本人授权的 QQ 数据（qchat 侧靠 OneBot 授权），落盘后继承
+  weflow 的纪律——QQ 号与 wxid 同级敏感；知识卡与索引沿用各自既有的出境确认门。
+- `--source all` 在微信库不可用时**降级**为只处理 QQ（说一声，不是静默）；`build
+  --include-imports` 在没有微信库的机器上也能建索引（纯 QQ 用户是真实场景）。