weflow-cli 1.6.4 → 1.8.0

package/docs/SETUP.md

@@ -81,6 +81,26 @@ weflow-cli daily-server --date YYYY-MM-DD --open
 weflow-cli config set dailyAiEnabled false
 ```
 
+文章的主题与相关度默认可以交给 TypeSafe 的 Jev 决策模型判断（返回概率而不是一段要解析的文字）。这一步可选：**不配就沿用原来的 LLM 解析路径，行为不变。**
+
+```powershell
+weflow-cli config set typesafeApiKey "..."   # 机器绑定加密保存，和 deepseekApiKey 一样
+weflow-cli config set typesafeApiKey ""      # 清空即回到 LLM 解析路径
+```
+
+不想在日报里看到某一类（如新闻/投资/学术）：
+
+```powershell
+weflow-cli config set dailyExcludeTopics "新闻,投资,学术"   # 留空即不排除
+```
+
+**这是展示层开关，不是抓取层的**：正文照常抓取归档，只是不展示，改主意不用重抓。
+为什么不干脆不抓：拉之前可用的信息（来源+标题+摘要）判类型实测只有 60% 一致率，
+而排除不可逆。详见 OPERATIONS.md 的「不想看某一类：排除主题」。
+```
+
+配了它之后，文章标题与正文会同时发给 DeepSeek 和 `api.typesafe.ai` 两处（出网范围见下节）。
+
 日报输出和阅读器均为本地文件/回环服务。阅读器默认地址是 `http://127.0.0.1:8765/`，不要把端口暴露到局域网或公网。
 
 ## 配置与隐私
@@ -89,6 +109,8 @@ weflow-cli config set dailyAiEnabled false
 
 以下内容禁止提交：数据库、导出聊天、日报正文、`.env`、MCP 配置中的密钥、账号标识、完整日志和真实截图。MCP 客户端配置前确认其工作目录和权限；云端 AI 只处理明确选择的内容，敏感聊天优先用本地模型。
 
+日报出网的对象有两个：生成摘要的 LLM（DeepSeek 或你配置的 OpenAI 兼容端点），以及配置了 `typesafeApiKey` 之后判断文章主题与相关度的 TypeSafe Jev（`api.typesafe.ai`）。两者都会看到文章标题与正文。不需要任何出网时用 `weflow-cli daily --no-ai`。
+
 ## 最小验收
 
 ```powershell

package/docs/SYNC_CONTRACT.md

@@ -0,0 +1,180 @@
+# 同步与任务状态契约
+
+本文冻结两个内部状态 schema：`weflow-sync/v1`（跨运行的同步检查点）与 `weflow-job/v1`
+（单次运行的记录）。二者都在本机 `~/.weflow-cli/` 下，**不对外暴露**。
+
+它们是 [FUNCTIONAL-IMPROVEMENT-SPEC.md](FUNCTIONAL-IMPROVEMENT-SPEC.md) §4 与 §5 的落地，
+边界受 [DECISIONS.md](DECISIONS.md) 约束（尤其 D-014、D-019、D-025、D-027）。
+
+## 为什么是两个文件
+
+生命周期不同，不是猜测性抽象：
+
+| 文件 | 生命周期 | 记录的是 |
+| --- | --- | --- |
+| `sync/<source>-<name>-<hash>.json` | **跨运行**，每次同步覆盖 | 已覆盖到哪、分片读没读全 |
+| `jobs/<jobId>.json` | **单次运行** | 这次运行的起止、状态、结果 |
+
+一次运行写一个 job 记录；同步检查点记录"到目前为止覆盖范围"这一长期事实。
+
+## `weflow-sync/v1`
+
+路径：`~/.weflow-cli/sync/<source>-<sanitize(talker)>-<sha256(talker)[0:8]>.json`
+
+**按会话分文件**，不是一个全局文件。理由：全局文件要求跨会话读改写并合并，而分文件
+让每次写入都是整文件原子替换；同时文件名里的 hash 后缀让 `wxid_a@chatroom` 与
+`wxid_a_chatroom` 落到不同文件，而显示名不会出现在目录列表里。
+
+```json
+{
+  "schema": "weflow-sync/v1",
+  "schemaVersion": 1,
+  "source": "wechat-nt",
+  "scope": "<显示名，未知时等于 talker>",
+  "talker": "<会话标识，不是路径>",
+  "lastSuccessfulRun": "2026-09-19T09:00:00+08:00",
+  "lastAttempt": "2026-09-19T09:02:10+08:00",
+  "coveredFrom": "2026-09-01T00:00:00+08:00",
+  "coveredTo": "2026-09-19T08:59:59+08:00",
+  "checkpoint": { "newestCreateTime": 1789000000, "overlapSeconds": 300 },
+  "recordsRead": 1200,
+  "recordsDeduplicated": 14,
+  "recordsReturned": 1186,
+  "shardsRead": 4,
+  "shardsFailed": 0,
+  "shards": {
+    "scanned": 4, "opened": 4, "failed": 0,
+    "items": [
+      { "name": "message_0.db", "opened": true, "hasTalkerTable": true,
+        "rowsForTalker": 8123, "reason": null, "missingColumns": [] }
+    ]
+  },
+  "coverage": "complete",
+  "mayHaveMore": false,
+  "warnings": [],
+  "updatedAt": "2026-09-19T09:02:10+08:00"
+}
+```
+
+### 两个时间戳必须分开
+
+| 字段 | 何时推进 |
+| --- | --- |
+| `lastAttempt` | **每次尝试都推进**，无论结果 |
+| `lastSuccessfulRun` | **仅在 `coverage !== 'partial'` 时推进** |
+
+只有一个的话，"跑了但部分完成"会和"跑成功了"混为一谈——而这正是方案 §5.2 明令禁止的
+（部分完成不能返回成功状态）。
+
+### `coverage` 三档
+
+| 值 | 含义 |
+| --- | --- |
+| `complete` | 扫到的分片全部打开、打开的全读成功（无 `reason`，允许有 `missingColumns`），且 `mayHaveMore` 为 false |
+| `unverified` | 有分片**打不开**，但打开的都读成功。已读部分是可信的，未打开的分片是否含本会话消息**无法判断** |
+| `partial` | 某个**已打开**的分片带 `reason`，或 `mayHaveMore` 为 true，或分页在到达窗口起点前就短页结束 |
+
+`unverified` 不是失败：`connect_message_shards` 一直把打不开的分片当作可跳过的（这是有意设计），
+CLI 无法知道那个分片里有没有本会话的消息。如实标成 `unverified` + `warnings` 比直接失败更有用，
+也让自动化不至于卡死。
+
+`partial` 的判据是**已打开的分片带 reason**，而不是某个特定的 reason 值。除 `READ_FAILED`（读到一半
+出错）外还有两种同样意味着"这个分片的这段范围没读到"的情况：
+
+| `reason` | 含义 |
+| --- | --- |
+| `READ_FAILED` | 已打开，读的过程中出错 |
+| `SCHEMA_MISMATCH` | 已打开，但表里**没有一个**读者认得的列，这些行无法变成消息 |
+| `WINDOW_UNAVAILABLE` | 已打开，但表里没有 `create_time`，请求的时间窗无法表达。**宁可拒绝也不近似**——不筛就返回会让调用方把没读的范围记成已覆盖 |
+
+把三者都算 `partial` 是必须的：它们描述的都是"这些行没读"，而这正是 `coverage` 要回答的问题。
+
+**`missingColumns` 是另一回事，不算 partial。** 它的行**读回来了**，只是少了字段（如缺 `server_id`），
+所以 `coverage` 仍是 `complete`，另发一条 `shard-columns-missing:<分片>:<列+列>` 警告。
+把两者混为一谈，会让这类数据库上的每次同步永远报 `partial`，`lastSuccessfulRun` 永远不推进。
+列名是 schema 不是内容，写进状态文件不违反脱敏约束。
+
+`partial` 则**必须失败**（`code: 'SYNC_PARTIAL'`，退出码 1）：状态文件照写（方案 §5.2 要求
+部分完成不得删除已生成的可用结果），但 `lastSuccessfulRun` 不推进。
+
+### 时间窗下推：是优化，不是正确性来源
+
+`sync` 会把窗口下界作为**提示**传给后端（NT 走 `nt_decrypt.py messages --from`），SQL 侧因此不必
+把整段会话取回来再丢弃。但**窗口的真正执行者是 `syncService` 自己**：它在读回之后再按
+`createTime >= from` 过滤一遍。这样划分的原因是**非 NT 后端没有范围下推**，若把正确性寄托在下推上，
+这些后端上的同步会静默地整段读、却报告成"按窗口读了"。
+
+**实测（2026-09-20，本机真实数据，925 条 4 分片）**：下推带来的收益**观测不到**——
+无窗口 519 ms / `--from=最新` 514 ms，两者在噪声内。这个耗时的绝大部分是进程启动 + 每个分片的
+PBKDF2（256000 轮），跟搬多少行无关。所以下推的意义是**渐近的**（会话越大越有用），
+不是当前就能测到的时间节省；这也意味着**不要**拿它当性能优化写进发布说明。
+
+### 身份
+
+按方案 §4.2，`serverId` 非零时优先；**`localId` 绝不单独作为全局身份**（D-014 同此约束）。
+
+```
+talker|s:<serverId>                   serverId 非零
+talker|l:<localId>|t:<createTime>     否则
+```
+
+**与方案 §4.2 的一处有意偏离**：键里**不含 `shard`**。消息载荷里没有 shard 字段
+（`nt_decrypt._message_dict` 不产出它），加进去要动 `export json` 的消息契约，而 D-016/D-027
+把那条线封住了。它对本契约要解决的**重叠去重**也不必要——同一条消息重读两次，得到的
+`serverId` 或 `(localId, createTime)` 本来就一样。只有跨分片的 `(localId, createTime)` 撞车
+才需要它，而 `talker` + `createTime` 已让这种撞车极其遥远。**真观测到再加，不预先加。**
+
+### 明确不做的事
+
+**`mayHaveMore` 不是稳定游标。** 按 D-027，稳定增量游标必须在所有相关后端都支持后才能
+对外宣称；在此之前只提供重叠时间窗 + 本地去重，由下游决定重复容忍度。
+
+**不得写入**：数据库密钥、`x'<key><salt>'`、聊天正文、绝对路径（D-001 / D-002 / D-025）。
+状态服务在写盘前统一过一遍脱敏，不指望每个调用方都记得。
+
+## `weflow-job/v1`
+
+路径：`~/.weflow-cli/jobs/<jobId>.json`。`jobId` 形如 `job_20260919_0001`。
+
+```json
+{
+  "schema": "weflow-job/v1",
+  "jobId": "job_20260919_0001",
+  "kind": "sync.messages",
+  "state": "running",
+  "createdAt": "2026-09-19T09:00:00+08:00",
+  "updatedAt": "2026-09-19T09:02:10+08:00",
+  "window": { "from": 1788000000, "to": 1789000000 },
+  "progress": { "completed": 800, "total": 1200 },
+  "resumeable": true,
+  "result": { "records": 800, "recordsDeduplicated": 14, "shardsFailed": 0 },
+  "error": null
+}
+```
+
+状态机：`planned → waiting_confirmation → running → paused`，终态 `completed | partial | failed | cancelled`。
+本轮只实现 `running | completed | partial | failed`，其余是预留（不实现的不写进状态机文档当既有能力）。
+
+`partial` 是本项目新增的一档，**不算成功**。`error` 只放既有的大写错误码
+（`NOT_INITIALIZED`、`CONFIRMATION_REQUIRED`、`INVALID_ARGUMENT`、`SYNC_PARTIAL`、
+`DATABASE_CONNECTION_FAILED` 等），不写中文长句供机器解析。
+
+**幂等**：同一范围重复提交应返回已有任务或明确新建，不得静默重复写入。本轮用
+`kind + talker + 窗口` 生成幂等提示，命中未完成的同键任务时返回该任务而非新建。
+
+> 本轮 `sync` 是 job 记录的唯一写入者。若日后认为不值得单独一个文件，
+> **回退路径**：删掉 job 存储、把那个 `lastJob` 对象并入各会话的 `weflow-sync/v1` 文件。
+> 因为此刻还没有第二个消费者，这是一次单文件改动，无兼容性影响。
+
+## 版本升级策略
+
+- `schema` 变化 = 不兼容变更，需要迁移说明。
+- 只增字段 = 兼容变更；读方必须容忍未知字段（与 `DATA_CONTRACT.md` 对下游的要求一致）。
+- 读到未知 `schema` 时**不得覆盖**：报明确错误并保留原文件。
+
+## 相关文档
+
+- [功能增强技术方案](FUNCTIONAL-IMPROVEMENT-SPEC.md)
+- [消息数据契约](DATA_CONTRACT.md)
+- [技术决策记录](DECISIONS.md)
+- [项目当前状态](PROJECT_STATE.md)