weflow-cli 1.15.1 → 1.17.0

package/docs/REPLAY.md

@@ -0,0 +1,169 @@
+# 时间重放（Replay）施工文档
+
+> 目标：把「关系网络怎么长出来的」做成能按月回放的东西。数据全部来自本地库，不联网、不调模型。
+>
+> 本文是施工前的规格，含**探测到的真实数据形状**。所有数字来自 2026-10-25 对当前库的一次扫描。
+
+---
+
+## 1. 要做什么
+
+一条命令，按月回放：
+
+```
+weflow-cli replay                 # 文本：每月一段，看数字与断边
+weflow-cli replay --out out.html  # 动画：按播放键，看边长出来
+```
+
+**核心看点不是"图变大了"**（那只是数据变多），而是**边断掉、边新长出来**。
+
+---
+
+## 2. 数据现实（先看这个，它决定了设计）
+
+扫描结果：**32 个月（2024-03 ~ 2026-10）**，但有三个阶段：
+
+| 阶段 | 月份 | 每月会话数 | 每月消息 | 说明 |
+|---|---|---|---|---|
+| 稀薄期 | 2024-03 ~ 2025-08（17 个月） | 1 ~ 2 | 7 ~ 695 | 几乎只有一两个会话 |
+| 完整期 | 2025-09 ~ 2026-10（14 个月） | 42 ~ 74 | 1,860 ~ 12,805 | 数据齐全 |
+| 低谷 | 2026-02 | 31 | 1,860 | 春节，正常 |
+
+单聊关系 80 个、群 65 个。其中：
+
+- **最长连续活跃 22 个月**（一段关系从 2024 一直到现在）
+- 连续 ≥3 个月的只有 **41%**
+- **36 个单聊只出现过 1 个月**（45%）—— 一闪而过
+
+### 由此得到三条硬约束
+
+1. **不能从 2024-03 直接播**：前 17 个月几乎是一条空线，看的人会以为坏了。
+   → 每一帧必须**同时输出"当月数据完整度"**（会话数），让它自己说明这一段是数据缺失、不是没聊天。
+2. **不能把所有关系都画上**：36 个一闪而过的单聊会让画面在后半段剧烈抖动。
+   → 设最低门槛（当月 ≥10 条才进图），并在输出里说明被过滤了多少。
+3. **群的"成员变化"拿不到时间戳**：`contact.db` 的 `chatroom_member` 只有**当前**成员，没有"谁何时进群"。
+   → 拓扑变化只能**从发言推断**：本月在这个群说过话 = 本月活跃成员。文档、代码、输出都要写清楚这是推断，不是成员名单。
+
+---
+
+## 3. 数据模型
+
+### 帧
+
+一帧 = 一个自然月。字段：
+
+| 字段 | 含义 | 来源 |
+|---|---|---|
+| `month` | `YYYY-MM` | `create_time` |
+| `messages` | 当月消息总数 | 计数 |
+| `talkers` | 当月有消息的会话数 | `distinct talker` |
+| `people` | 当月发过言的人数 | `real_sender_id` → `Name2Id` |
+| `completeness` | **数据完整度标记** | 会话数 ≥ 20 记 `full`，否则 `sparse` |
+| `edges` | 当月的边（见下） | 聚合 |
+
+### 节点
+
+| 类型 | 定义 | 大小由什么决定 |
+|---|---|---|
+| 人 | 发过言的 `real_sender_id` | 当月发言条数 |
+| 群 | `@chatroom` 会话 | 当月消息条数 |
+
+### 边
+
+| 边 | 含义 | 权重 |
+|---|---|---|
+| 人—人 | 两人在**同一个群**里都发过言（弱关系） | 共现次数 |
+| 我—人 | 单聊有消息（强关系） | 当月消息条数 |
+| 群—人 | 这个人在这个群说过话（**推断的活跃成员**） | 当月发言条数 |
+
+**边权只叫「互动量」，不叫「亲密度」。** 和同事一天 50 条是工作，和家人一周 3 条是亲近。
+除非把「主动发起比例 / 回复延迟 / 深夜时段」也算进去，但那需要单独校准，不在这一期。
+
+---
+
+## 4. 每月的边状态
+
+每帧给每条边打一个状态，这是动画的"颜色"来源：
+
+| 状态 | 判据 |
+|---|---|
+| `new` | 上月没有这条边，本月出现 |
+| `stable` | 连续 ≥3 个月存在 |
+| `fading` | 存在，但权重比上上个月降 ≥50% |
+| `gone` | 上月有，本月没有 |
+
+**`gone` 是最重要的产出**——"和某人最后一次说话是 2025-12，之后再没出现过"。
+
+---
+
+## 5. 分两期
+
+### 一期：文本版（CLI）
+
+```
+weflow-cli replay [--months 6] [--min-weight 10] [--json]
+```
+
+输出形态：
+
+```
+2025-09  full    消息 4,748 · 会话 47 · 发言者 190
+  新出现 12 条关系（例：联系人A、联系人B…）
+  断掉   3 条关系（例：联系人C 最后一句「改天聊」）
+2025-10  full    消息 6,751 · 会话 45 · 发言者 189
+  …
+```
+
+**先做它的理由**：数字对了、断边捞得出来了，动画才有意义。如果数据显示"其实没什么断的"，二期直接砍掉。
+
+### 二期：HTML 动画
+
+单文件、无外部依赖、离线可开。三条轨道：
+
+1. 主画布：关系网络逐月生长（边按状态着色，`gone` 留一道残影后消失）
+2. 右侧：消息量 / 会话数 曲线，播放头随时间走
+3. 底部：当月高频词（取自已有的 `.articles.json` 与消息文本，不调模型）
+
+按「播放」逐帧推进，可拖时间轴、可单月步进。
+
+---
+
+## 6. 验收标准（可验，不是"看着差不多"）
+
+| 编号 | 检查 | 判据 |
+|---|---|---|
+| A1 | 帧数守恒 | `--json` 的帧数 == 库里出现的月数 |
+| A2 | 消息数守恒 | 各帧 `messages` 之和 == 全库消息总数（误差 0） |
+| A3 | 完整度标记正确 | 2025-08 必须 `sparse`，2025-09 必须 `full` |
+| A4 | 断边可复现 | 任取一条 `gone`，用它两个月的原始消息能手算出来 |
+| A5 | 过滤有交代 | 被 `--min-weight` 过滤掉的边数要打印出来，不许静默丢 |
+| A6 | 不联网 | 全程无出网请求（纯本地读取） |
+
+A2 是关键——它对不上就说明有分片没读到，那个"关系消失了"可能是假象。
+
+---
+
+## 7. 不做的事（明确划掉）
+
+- **不做"亲密度"**：只输出互动量，命名就叫 `interactions`。
+- **不做"谁什么时候进群"**：没有时间戳，不猜。
+- **不做增量/实时**：一次全量扫描，30 秒内跑完即可，不做缓存。
+- **不接 AI**：这一期的卖点是"数据自己长出来的形状"，加模型只会让人怀疑画的东西是编的。
+
+---
+
+## 8. 工作量
+
+| 期 | 内容 | 预计 |
+|---|---|---|
+| 一期 | 扫描 + 按月聚合 + 断边检测 + CLI + 测试（A1–A6） | 2–3 小时 |
+| 二期 | 单文件 HTML + 帧数据内嵌 + 播放控件 | 3–4 小时 |
+
+一期风险最高的是 **A2 守恒**：现有代码里消息读取有"某分片读不了"的分支，如果扫的时候有分片失败，总数会少于真实值，而断边看起来就像真断了。所以一期**必须先做守恒检查，再输出任何结论**。
+
+---
+
+## 9. 参考
+
+- 触发这份文档的文章：<https://mp.weixin.qq.com/s/T3ScldZVOuXD13tZpn-rSg>（讲 Obsidian 插件 Maps of the Ideaverse 的时间重放）
+- 该插件的图是**二值**的（笔记有链接/没链接），只能表现"连线生长"；我们的边加权且多层（共同群 / 单聊 / 共同话题），能表现"边变粗、变细、断掉"。

package/docs/SYNC_CONTRACT.md

@@ -1,180 +1,197 @@
-# 同步与任务状态契约
-
-本文冻结两个内部状态 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)
+# 同步与任务状态契约
+
+本文冻结两个内部状态 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)
+
+## 稳定游标的路径可见（`sync cursor-probe`）
+
+D-027 的结论仍然成立：**没有稳定游标**，增量读取就是"重叠时间窗 + 本地去重"。2026-10-23
+起，`false` 这个结论背后的路径是可查的，而不是一个黑盒布尔：
+
+- `capabilities --json` 的 `read.exports.incrementalRead.cursorReadiness` 列出五条判据
+  （稳定身份 / 跨分片可比的顺序键 / 时间窗下推 / 覆盖报告 / 所有后端同时满足）与四个消息后端
+  （`nt` / `raw-sqlite-4x` / `wcdb-4x` / `legacy-3x`）各自的代码事实；其中 `probe:` 指向的命令串
+  由 `check_readme_commands.py` 与 `cli:`/`preview:` 一起校验。
+- `sync cursor-probe --json`（只读、本地、无确认门）实测 NT 后端的**数据侧**：schema 检查全量
+  （每张消息表的锚点列），身份检查有界采样（每分片 5 张表、每表两端各 500 行，可调），结果自带
+  `exhaustive: false`。server_id 以**字符串**上报（int64 过 2^53 在 JSON.parse 里会丢精度）。
+  探针不翻结论：`stableCursor` 恒为 `false`，直到 D-027 的条件满足。
+
+判据与后端事实的单一来源是 `src/services/cursorProbe.ts`（代码事实）与 `nt_decrypt.py
+cursor-probe`（数据事实）；改读取器（下推 / 报告 / 顺序键）时同步改那张表。