weflow-cli 1.6.4 → 1.7.0

package/docs/DECISIONS.md

@@ -2,6 +2,9 @@
 
 > Record decisions that affect long-term maintenance. Each entry explains the chosen direction and the reason, not every implementation detail.
 
+> 编号说明：`D-009` 从未使用（D-008 直接跳到 D-010），保留为空号；
+> 历史上曾有两条决策共用 `D-016`，其中「architecture visuals」一条改号为 `D-028`。
+
 ## D-001: Local-first data handling
 
 **Status:** Active
@@ -114,6 +117,16 @@ HTML export selects message-resource records by nonzero server message ID. It do
 
 **Consequences:** WeChat 4.x V2 media keys are derived from local `kvcomm` data, verified against a real cached V2 header, and used only in memory during export. Remote emoticons are decrypted with message-provided keys; entity-escaped XML is normalized; and URL fallbacks cover encrypted, thumbnail, CDN, and external fields. Structured app cards keep their links and use cached or resolved covers when available. Some messages remain placeholders when reliable identity or source media is unavailable. Synthetic tests cover these paths; reporter verification is still needed for issue #7.
 
+## D-015: Keep documentation synchronized with the source baseline
+
+**Status:** Active
+
+User-facing setup and troubleshooting documents describe supported commands and guarantees only when they are present in the current CLI and scripts. The project state and decision log remain the handoff source for agents; architecture explains boundaries and data flow; the README stays a short entry point.
+
+**Reason:** The project has both a GitHub source workflow and a separately published npm package. Stale examples, hard-coded tool counts, or old compatibility claims can cause users to run the wrong code or expose sensitive data while troubleshooting.
+
+**Consequences:** When command options, platform support, data flow, security boundaries, or verification status changes, update the relevant document in the same change. Validate examples against `--help` and keep generated local output out of commits.
+
 ## D-016: Establish a stable downstream data boundary
 
 **Status:** Active
@@ -144,26 +157,6 @@ The CLI exposes `capabilities --json` as the first call for automation. Read-ori
 
 **Consequences:** New user-facing commands should be added to the capability response and should declare whether they read local data, invoke AI, or cause side effects. This is an additive interface and does not change existing human-readable output.
 
-## D-015: Keep documentation synchronized with the source baseline
-
-**Status:** Active
-
-User-facing setup and troubleshooting documents describe supported commands and guarantees only when they are present in the current CLI and scripts. The project state and decision log remain the handoff source for agents; architecture explains boundaries and data flow; the README stays a short entry point.
-
-**Reason:** The project has both a GitHub source workflow and a separately published npm package. Stale examples, hard-coded tool counts, or old compatibility claims can cause users to run the wrong code or expose sensitive data while troubleshooting.
-
-**Consequences:** When command options, platform support, data flow, security boundaries, or verification status changes, update the relevant document in the same change. Validate examples against `--help` and keep generated local output out of commits.
-
-## D-016: Use GPT-image-2 for future architecture visuals
-
-**Status:** Active
-
-When a new architecture diagram visual is requested, use GPT-image-2 for the visual asset. Keep the diagram's structure and labels aligned with the source documentation, validate the final dimensions and legibility, and retain a maintainable source representation when practical.
-
-**Reason:** The project owner wants architecture visuals to use the project's image-generation workflow while keeping technical documentation understandable and reviewable.
-
-**Consequences:** Do not silently substitute an unrelated image-generation model. Do not treat generated pixels as the source of truth; `ARCHITECTURE.md` and the code remain authoritative.
-
 ## D-019: Require preview and confirmation for side effects
 
 **Status:** Active
@@ -254,6 +247,53 @@ The bundled WCDB DLL exposes a raw SQL query ABI without parameter binding. `exe
 
 **Consequences:** Consumers can perform overlapping time-window reads and deduplicate locally. A stable incremental cursor remains a separate future change and must be supported by all relevant database backends before it is advertised.
 
+## D-028: Use GPT-image-2 for future architecture visuals
+
+**Status:** Active
+
+When a new architecture diagram visual is requested, use GPT-image-2 for the visual asset. Keep the diagram's structure and labels aligned with the source documentation, validate the final dimensions and legibility, and retain a maintainable source representation when practical.
+
+**Reason:** The project owner wants architecture visuals to use the project's image-generation workflow while keeping technical documentation understandable and reviewable.
+
+**Consequences:** Do not silently substitute an unrelated image-generation model. Do not treat generated pixels as the source of truth; `ARCHITECTURE.md` and the code remain authoritative.
+
+## D-029: Keep the sync and media-coverage work additive
+
+**Status:** Active
+
+`weflow-sync/v1` and `weflow-job/v1` are new local state contracts written under
+`~/.weflow-cli/`. The `sync` command and the export media report are additive: no existing command
+changes its behaviour, its stdout contract, or its JSON schema. `export <talker> html` gains one
+side file (`<prefix>_media.json`) and one extra key in its trailing stdout JSON, both of which the
+only consumer ignores; `--media-report 0` restores the previous file set exactly.
+
+**Reason:** D-016 fences the exported message contract and D-027 fences coverage metadata, so a
+change that redefines existing fields would need a compatibility review this work does not warrant.
+The gaps being closed - shard read failures dropped silently, media counters computed and discarded
+- are observations about what already happened, not redefinitions.
+
+**Consequences:**
+
+- Sync state is **one file per conversation** (`sync/<source>-<name>-<hash>.json`), so every write is
+  a whole-file atomic replace and no cross-conversation read-modify-write merge is needed. The hash
+  suffix keeps `wxid_a@chatroom` and `wxid_a_chatroom` distinct without putting display names in a
+  directory listing.
+- `lastAttempt` and `lastSuccessfulRun` advance separately. A run that is `partial` still writes its
+  state and its job record, but must not advance `lastSuccessfulRun` and must not return success
+  (the spec's rule that partial completion is not success).
+- The message identity keeps `serverId` when nonzero and otherwise uses `localId` + `createTime`.
+  It **omits `shard`**, deviating from the spec's §4.2 sketch: messages do not carry a shard field,
+  adding one would touch the fenced export contract, and overlap deduplication does not need it.
+  Add it only if a cross-shard collision is actually observed.
+- `sync retry` is **not** implemented. With no local index and no partial writes it would be exactly
+  the same operation as re-running the window, and the failed-shard list is already in `sync status`.
+  A command that is a synonym is worse than no command.
+- `sync` is the only writer of `weflow-job/v1` in this round. If a single consumer is judged not to
+  justify the file, the reversal is: delete the job store and fold `lastJob` into each
+  `weflow-sync/v1` file. Nothing else reads it, so that is a one-file change.
+- Still not advertised: a stable incremental cursor. D-027 stands - overlapping windows plus local
+  deduplication is what this exposes.
+
 ## Decision Template
 
 

package/docs/FUNCTIONAL-IMPROVEMENT-SPEC.md

@@ -0,0 +1,338 @@
+# WeFlow CLI 功能增强技术方案
+
+> 状态：提案
+> 
+> 更新时间：2026-09-19
+> 
+> 适用范围：CLI、MCP、本地阅读器、聊天导出、日报、知识库和可选助手
+
+本文把 WeFlow CLI 下一阶段的功能改进整理为可拆分的技术方案。它补充 [ROADMAP.md](ROADMAP.md) 的方向说明，面向实现、评审和验收；已经实现的能力以 [PROJECT_STATE.md](PROJECT_STATE.md) 为准。
+
+## 1. 产品目标
+
+WeFlow CLI 已经覆盖本地聊天读取、联系人与收藏、HTML/JSON/TXT/Excel 导出、公众号日报、知识库检索、RAG、只读 MCP 和 Bot 助手。下一阶段不以增加零散命令为主要目标，而是把这些能力连接成四条可恢复、可验证的工作流：
+
+1. **同步：** 从本地数据源读取增量变化，并明确哪些数据已覆盖、哪些数据读取失败。
+2. **整理：** 将消息、媒体、文章和笔记写入统一的本地索引，保留原始来源。
+3. **使用：** 通过搜索、阅读器、导出和 MCP 查询这些数据，并能回到原始记录。
+4. **分析：** 在用户选择的范围内调用本地或云端 AI，输出带来源的结果。
+
+功能完成的标准不是命令数量，而是用户可以在失败后继续运行、在结果中看到覆盖边界，并能验证 AI 或导出结果来自哪些原始资料。
+
+## 2. 现状与功能缺口
+
+| 能力 | 当前基础 | 需要补齐的功能 |
+| --- | --- | --- |
+| 本地数据 | 支持会话、联系人、消息、收藏、朋友圈缓存和多种导出；已处理部分消息分片 | 增量同步、稳定游标、覆盖报告、失败分片重试和统一索引 |
+| 媒体导出 | 支持图片、表情、视频、链接卡片，部分场景支持语音转写 | 媒体清单、缺失原因、去重、导出断点和可迁移资料包 |
+| 日报阅读 | 支持来源筛选、分类、摘要、HTML 阅读器和收藏同步 | 来源健康、抓取重试、文章去重、阅读状态和离线归档 |
+| 搜索与知识库 | 支持语义搜索、RAG、Vault 和阅读笔记 | 混合检索、增量索引、引用定位、结果解释和评估集 |
+| MCP | 默认只读、有限制、使用版本化消息契约 | 稳定游标、更多只读资源、统一错误码和任务状态查询 |
+| 助手 | 有隐私模式、白名单、Bot 通道和确认边界 | 收件箱/发件箱、幂等发送、投递状态和会话级记忆控制 |
+
+## 3. 优先级和交付顺序
+
+### P0：数据可信和任务可恢复
+
+先完成增量同步、统一任务状态和导出覆盖报告。这一阶段解决“有没有读全”“导出到哪一步”“缺的媒体是什么”三个问题。
+
+### P1：检索和阅读闭环
+
+在可信数据基础上完成混合搜索、引用定位、日报增量抓取和离线阅读。此阶段应让用户能够从一篇 AI 摘要或一个搜索结果返回到原始消息或文章。
+
+### P2：受控 AI 和只读生态
+
+统一 AI 执行层、MCP 增量接口和助手收发队列。所有云端分析和外发操作继续沿用预览、确认和隐私模式。
+
+### P3：迁移和平台扩展
+
+最后增加资料包迁移、Markdown/Obsidian 等互操作格式，以及 Linux/macOS 的能力适配。平台扩展必须建立在能力检测和明确降级结果上。
+
+## 4. 统一数据同步和索引
+
+### 4.1 模块划分
+
+建议把同步流程拆成以下模块：
+
+| 模块 | 责任 |
+| --- | --- |
+| `SourceAdapter` | 从 NT 数据库、传统数据库、日报目录或文章源读取记录 |
+| `Normalizer` | 将不同来源转换为统一记录，保留未知字段 |
+| `IdentityResolver` | 生成消息、文章和媒体的稳定身份，拒绝不可靠匹配 |
+| `CheckpointStore` | 保存分片、时间窗、游标和失败重试状态 |
+| `LocalIndex` | 写入全文索引、向量索引和元数据索引 |
+| `CoverageReporter` | 统计读取范围、缺失分片、媒体覆盖和重复记录 |
+
+### 4.2 消息身份
+
+在稳定游标尚未得到所有后端支持前，使用组合身份并允许重叠读取：
+
+```text
+messageKey = source + talker + shard + localId + serverId + createTime
+```
+
+其中 `serverId` 为非零值时优先使用；`localId` 不能单独作为全局身份。时间窗同步应保留少量重叠范围，由本地去重保证边界消息不丢失。
+
+### 4.3 同步状态示例
+
+状态文件不得包含密钥、完整聊天正文或无必要的本地绝对路径。可以保存如下信息：
+
+```json
+{
+  "schema": "weflow-sync/v1",
+  "source": "wechat-nt",
+  "scope": "示例联系人",
+  "lastSuccessfulRun": "2026-09-19T09:00:00+08:00",
+  "coveredFrom": "2026-09-01T00:00:00+08:00",
+  "coveredTo": "2026-09-19T08:59:59+08:00",
+  "recordsRead": 1200,
+  "recordsDeduplicated": 14,
+  "shardsRead": 4,
+  "shardsFailed": 0,
+  "mayHaveMore": false,
+  "warnings": []
+}
+```
+
+### 4.4 建议入口
+
+具体命令名称可以由实现者决定，但应覆盖以下能力：
+
+- `sync --dry-run --json`：只返回范围、预计记录数和风险标记；
+- `sync run`：执行全量或增量同步；
+- `sync status --json`：查看最后一次运行、覆盖范围和失败项；
+- `sync retry`：只重跑失败分片或失败来源；
+- `sync verify`：检查索引与原始数据的时间边界和计数摘要。
+
+## 5. 统一任务中心
+
+导出、日报、索引、语音转写和知识处理应共享任务模型，而不是各自实现一套进度逻辑。
+
+### 5.1 生命周期
+
+```text
+planned → waiting_confirmation → running → paused
+                                  ↘ completed
+                                  ↘ failed
+                                  ↘ cancelled
+```
+
+任务必须具备稳定的 `jobId` 和幂等键。重复提交同一范围的任务时，应返回已有任务或明确创建新任务，不能悄悄重复写入。
+
+### 5.2 任务记录
+
+```json
+{
+  "schema": "weflow-job/v1",
+  "jobId": "job_20260919_0001",
+  "kind": "export.html",
+  "state": "running",
+  "createdAt": "2026-09-19T09:00:00+08:00",
+  "updatedAt": "2026-09-19T09:02:10+08:00",
+  "progress": { "completed": 800, "total": 1200 },
+  "resumeable": true,
+  "result": { "records": 800, "mediaMissing": 3 },
+  "error": null
+}
+```
+
+任务输出应区分“已完成”“部分完成”和“失败”。部分完成不能返回成功状态，也不能删除已生成的可用结果。
+
+### 5.3 用户体验
+
+所有长任务至少提供：
+
+- 预览和预计影响；
+- 进度、当前阶段和耗时；
+- 暂停、恢复、取消；
+- 失败原因和可重试动作；
+- 人类可读输出与机器可读 JSON 输出。
+
+## 6. 搜索、引用和知识库
+
+### 6.1 混合检索流程
+
+```text
+用户查询
+  → 查询解析（关键词、日期、联系人、会话、消息类型）
+  → 全文检索 + 向量检索
+  → 元数据过滤
+  → 去重和重排
+  → 片段裁剪
+  → 引用生成
+  → AI 回答或结构化结果
+```
+
+关键词检索负责精确命中姓名、编号和原句；向量检索负责语义相近内容。两者都必须受到日期、会话和结果数量限制。
+
+### 6.2 引用对象
+
+每条引用至少包含：
+
+```json
+{
+  "sourceType": "wechat-message",
+  "sourceId": "messageKey",
+  "talker": "示例联系人",
+  "createdAt": "2026-09-19T08:30:00+08:00",
+  "snippet": "经脱敏或用户允许的原文片段",
+  "locator": { "export": "示例联系人", "part": 1 }
+}
+```
+
+AI 输出中的事实性结论应能回到一个或多个引用；没有引用的内容应标记为推断或建议。原始消息和 AI 生成文本必须分开保存。
+
+### 6.3 索引更新
+
+- 只对新增或变更记录建立索引；
+- 内容哈希变化时重建对应条目；
+- 删除或失效记录进入 tombstone，避免旧结果继续出现；
+- 向量模型变化时支持新旧索引并行切换；
+- 建立不含真实聊天内容的评估集，测试召回率、引用准确率和重复率。
+
+## 7. 导出资料包和媒体覆盖
+
+### 7.1 导出配置
+
+导出应从单一命令扩展为可保存的配置：
+
+- 会话或联系人范围；
+- 日期范围；
+- 输出格式；
+- 是否包含图片、表情、视频、语音和远程封面；
+- 是否脱敏；
+- 每页条数和媒体大小上限；
+- 离线模式或允许远程读取。
+
+### 7.2 媒体清单
+
+每个媒体项应记录状态，而不是只在页面中显示占位符：
+
+```json
+{
+  "mediaKey": "content-or-message-identity",
+  "kind": "image",
+  "status": "embedded",
+  "mime": "image/jpeg",
+  "bytes": 123456,
+  "sha256": "redacted-example",
+  "reason": null
+}
+```
+
+推荐状态：`embedded`、`cached`、`remote-fetched`、`missing`、`untrusted-match`、`unsupported`。无法可靠匹配时必须保留缺失原因，不能用相邻消息或裸 `localId` 猜测媒体。
+
+### 7.3 离线资料包
+
+资料包建议包含：
+
+```text
+manifest.json
+messages.json
+index.html
+media/
+attachments/
+README.txt
+```
+
+`manifest.json` 保存数据范围、生成时间、版本、覆盖统计和脱敏选项；不得保存数据库密钥、完整本地路径或未授权的配置内容。
+
+## 8. 日报和本地阅读器
+
+### 8.1 来源状态
+
+每个公众号或文章来源应有本地状态：启用、停用、最近成功时间、最近失败原因、连续失败次数和最后抓取文章时间。状态用于提醒用户，不应自动扩大抓取范围。
+
+### 8.2 文章去重
+
+优先使用文章 URL，其次使用来源、标题、发布时间和正文哈希组合判断重复。重复文章应保留来源关系，但不重复生成日报和向量索引。
+
+### 8.3 阅读状态
+
+阅读器可以增加未读、已读、稍后阅读、收藏和笔记关联。所有状态保存在本地，刷新、重新生成 HTML 或重启服务后仍能恢复。
+
+## 9. 受控 AI 执行层
+
+统一 AI 配置应至少包含：
+
+| 配置 | 作用 |
+| --- | --- |
+| provider/model | 选择云端或本地模型 |
+| privacyMode | `strict`、`balanced`、`local` |
+| inputLimit | 限制消息数量、字符数或 token 数 |
+| timeLimit | 限制单任务耗时 |
+| budget | 限制调用次数或费用 |
+| outputSchema | 约束结构化输出 |
+| citationRequired | 要求返回引用 |
+
+AI 调用前应生成不含正文的预览，说明数据范围、是否联网、预计规模和写入位置。云端调用失败时，保留本地抓取和无 AI 结果，不把整个工作流判定为不可用。
+
+## 10. MCP 和助手功能
+
+### 10.1 MCP 只读扩展
+
+优先扩展以下只读能力：
+
+- 会话发现和唯一名称解析；
+- 分页读取消息和覆盖状态；
+- 联系人、收藏、日报和知识条目查询；
+- 导出任务创建、查询和结果摘要；
+- 能力、契约和限制发现。
+
+分页建议使用不透明游标，响应带 `nextCursor`、`returnedCount`、`mayHaveMore` 和请求范围。错误响应使用稳定错误码，避免让客户端解析中文错误文本。
+
+### 10.2 Bot 助手收发队列
+
+助手只围绕已验证的 Bot 通道增强，不扩展为个人微信账号自动化。建议引入：
+
+- 入站事件 ID 和去重表；
+- 出站消息队列；
+- `queued`、`sent`、`delivered`、`failed` 状态；
+- 重试次数和最后失败原因；
+- 会话级记忆开关和数据范围；
+- 外发前的预览和确认。
+
+## 11. 验收指标
+
+每个阶段至少记录以下指标：
+
+| 指标 | 目标 |
+| --- | --- |
+| 增量同步重复率 | 重复读取可被本地去重，不产生重复索引 |
+| 分片覆盖率 | 可报告成功、失败和未扫描分片 |
+| 媒体错配率 | 可靠匹配失败时宁缺毋滥，禁止跨会话错配 |
+| 导出可恢复率 | 中断后从最近检查点继续，不必从头开始 |
+| 搜索引用准确率 | 引用能定位到实际返回片段 |
+| 日报重复率 | 同一文章重复运行不重复生成内容 |
+| AI 数据边界 | 每次云端调用均可说明输入范围和隐私模式 |
+| MCP 响应边界 | 结果数量、时间范围和字段均受限制 |
+
+## 12. 风险和明确不做的事
+
+- 不使用裸 `localId`、相邻记录或模糊名称猜测消息和媒体身份。
+- 不把数据库路径、密钥、完整聊天正文或任意本地目录暴露给 MCP 客户端或合作应用。
+- 不在默认工作流中加入个人微信账号自动发消息、拉群、群管理或未验证的客户端自动化。
+- 不把云端 AI 作为日报、导出和本地搜索的必需依赖。
+- 不在没有迁移方案、兼容性测试和回滚方式时修改现有 JSON 数据契约。
+
+## 13. 建议的首轮开发任务
+
+1. 定义 `weflow-sync/v1` 和 `weflow-job/v1` 两个内部状态契约。
+2. 为消息同步增加检查点、重叠时间窗和覆盖摘要。
+3. 为 HTML/JSON 导出增加媒体覆盖报告和部分完成状态。
+4. 将导出、日报和索引任务接入统一任务状态查询。
+5. 为搜索结果增加消息/文章引用对象，不改变现有原始数据字段。
+6. 为 MCP 增加不透明游标和稳定错误码。
+7. 使用合成数据建立同步、搜索、导出和 MCP 的端到端验收样例。
+
+首轮完成后，再根据实际失败记录决定是否进入阅读状态、AI 执行层和助手收发队列，避免在数据边界尚未稳定时继续扩大功能面。
+
+## 14. 关联文档
+
+- [整体路线图](ROADMAP.md)
+- [项目当前状态](PROJECT_STATE.md)
+- [消息数据契约](DATA_CONTRACT.md)
+- [MCP 接口说明](MCP.md)
+- [AI 接口和确认协议](AI_INTERFACE.md)
+- [技术决策记录](DECISIONS.md)
+- [安全说明](../SECURITY.md)

package/docs/PROJECT_STATE.md

@@ -1,6 +1,6 @@
 # Project State
 
-> Last reviewed: 2026-09-19. This is the current maintenance snapshot, not a release note. Keep it factual and update it with meaningful project changes.
+> Last reviewed: 2026-09-19 (sync and media coverage added). This is the current maintenance snapshot, not a release note. Keep it factual and update it with meaningful project changes.
 
 ## Purpose
 
@@ -25,14 +25,16 @@ WeFlow CLI is a local-first command-line tool and MCP server for user-authorized
 | Initialization | Verify and reuse existing local database access by default; refresh only when needed. Missing-key tests can run without changing saved configuration. | `init`, `init --refresh`, `init --test-missing-keys`, `config forget-keys`, `check` |
 | Official-account daily | Filter configured sources, preserve source categories, backfill incomplete yesterday output before an unqualified today run, fetch articles, create summaries, generate a local HTML reader, and synchronize reader favorites into local files. | `daily`, `daily favorites`, `daily-stats`, `daily-server` |
 | Knowledge workflows | Wiki compilation, semantic search, RAG, WeRead sync, reviews, reading notes, and staged Vault promotion. | `wiki`, `vault`, `search`, `chat`, `weread`, `review` |
+| Incremental read | `sync run` reads a time window, deduplicates against the previous checkpoint and writes coverage state; `sync status` reports it without touching the database; `sync verify` re-reads the recorded window and compares bounds and counts. Every run reports `coverage` as `complete`, `unverified` or `partial`, and a partial run never advances `lastSuccessfulRun`. It does **not** offer a stable cursor - see D-027. | `sync run`, `sync status`, `sync verify` |
+| Media coverage | HTML export writes `<prefix>_media.json` with a status and reason per media item, and reports the remote-fetch budget it used. A media miss is recorded rather than shown as a bare placeholder. | `export <talker> html` |
 | MCP | Local stdio MCP server exposes bounded read and local transformation tools, including the `wechat.export_messages` versioned message contract. Publishing, messaging, memory writes, todo mutation, configuration changes, and deletion are excluded. | `mcp-config`, `mcp-server/index.ts` |
 | Assistant | Optional WeChat Bot-channel assistant with local memory and privacy gates. | `login-wechat`, `assistant` |
 
-The 67-test TypeScript regression suite covers home-path expansion, custom NT data-root discovery, bounded daily-favorites synchronization, confirmed no-AI daily generation, no-AI Vault promotion, Vault content mutation previews, Vault initialization and synchronization confirmation, MCP configuration write confirmation, source/compiled Python resource lookup, outbound PII redaction, local-inference bypass, strict message-body masking, MCP path/date/URL validation and live tool discovery, message-contract preservation, local-date export bounds, export result metadata, evidence-package safety, assistant routing and lifecycle confirmation, message-channel authentication confirmation, todo and access-control mutation confirmation, message-send preview/confirmation, local-reader port validation, redacted configuration status, access-list JSON, database-key reset confirmation, human-gated initialization and key capture, content-free account-scan and assistant-log diagnostics, confirmed Vault RAG, confirmed semantic search and RAG chat, structured todo reminders, strict knowledge limits, report previews, and cover-image signature validation. Core automation entry points now include `capabilities --json`, `config show --json`, `whitelist list --json`, `blacklist list --json`, `check --json`, `init --dry-run --json`, `scan --json`, `dbkey --dry-run --json`, `sessions --json`, `messages --json`, `contacts --json`, `export ... --json`, `fav export ... --json-result`, `sns ... --json`, `daily-stats --json`, `daily --no-ai --dry-run --json`, `daily-server --status --json`, `assistant status --json`, `assistant log --json`, `todos list --json`, `todos remind --json`, `evidence --json`, `evidence-review --dry-run --json`, Vault mutation previews, confirmed `vault rag`, confirmed `search` and `chat`, daily-favorite previews, `search-index --dry-run --json`, `pipeline run --dry-run --json`, report-generator previews, login/logout previews, and `mcp-config --output <file> --dry-run --json-result`. CI runs both the build and this suite on Node 20 with Python 3.10 available for path-discovery coverage.
+The 67-test TypeScript regression suite covers home-path expansion, custom NT data-root discovery, bounded daily-favorites synchronization, confirmed no-AI daily generation, no-AI Vault promotion, Vault content mutation previews, Vault initialization and synchronization confirmation, MCP configuration write confirmation, source/compiled Python resource lookup, outbound PII redaction, local-inference bypass, strict message-body masking, MCP path/date/URL validation and live tool discovery, message-contract preservation, local-date export bounds, export result metadata, evidence-package safety, assistant routing and lifecycle confirmation, message-channel authentication confirmation, todo and access-control mutation confirmation, message-send preview/confirmation, local-reader port validation, redacted configuration status, access-list JSON, database-key reset confirmation, human-gated initialization and key capture, content-free account-scan and assistant-log diagnostics, confirmed Vault RAG, confirmed semantic search and RAG chat, structured todo reminders, strict knowledge limits, report previews, and cover-image signature validation. Core automation entry points now include `capabilities --json`, `config show --json`, `whitelist list --json`, `blacklist list --json`, `check --json`, `init --dry-run --json`, `scan --json`, `dbkey --dry-run --json`, `sessions --json`, `messages --json`, `contacts --json`, `export ... --json`, `fav export ... --json-result`, `sns ... --json`, `daily-stats --json`, `daily --no-ai --dry-run --json`, `daily-server --status --json`, `assistant status --json`, `assistant log --json`, `todos list --json`, `todos remind --json`, `evidence --json`, `sync run --dry-run --json`, `sync run --yes --json`, `sync status --json`, `sync verify --json`, `evidence-review --dry-run --json`, Vault mutation previews, confirmed `vault rag`, confirmed `search` and `chat`, daily-favorite previews, `search-index --dry-run --json`, `pipeline run --dry-run --json`, report-generator previews, login/logout previews, and `mcp-config --output <file> --dry-run --json-result`. CI runs three jobs: `node` (build plus the TypeScript suite on Node 22.13), `python` (the Python suites on 3.11), and `release-consistency` (package.json and package-lock.json version agreement, plus a check that the npm package carries no outputs, models, databases or keys). The jobs are separate because a Node failure previously stopped the Python tests from running at all, which let them fail unnoticed.
 
 The daily workflow supports `dailyAiEnabled=false` for a persistent no-AI mode, or `daily --no-ai` for a single run. Both the CLI and direct Python entry points honor the setting. Fetching, HTML generation, and local indexes remain available in that mode. Machine execution requires `daily --yes --json`; it keeps progress logs on stderr and returns a machine-readable completion result on stdout after checking the required local artifacts.
 
-Date-bounded message exports and `wechat.export_messages` page through the selected conversation before applying the result limit. Older matching dates are therefore not hidden by a newer, nonmatching first page. Versioned envelopes report requested bounds, returned count, and conservative `mayHaveMore` metadata; a stable incremental cursor is not yet exposed.
+Date-bounded message exports and `wechat.export_messages` page through the selected conversation before applying the result limit. Older matching dates are therefore not hidden by a newer, nonmatching first page. Versioned envelopes report requested bounds, returned count, and conservative `mayHaveMore` metadata. `sync` adds a local checkpoint on top of the same overlapping-window approach, but **a stable incremental cursor is still not exposed** - it must be supported by every relevant database backend before it is advertised (D-027), and `capabilities --json` reports `stableCursor: false` for both.
 
 ## Security Baseline
 

package/docs/SYNC_CONTRACT.md

@@ -0,0 +1,152 @@
+# 同步与任务状态契约
+
+本文冻结两个内部状态 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 }
+    ]
+  },
+  "coverage": "complete",
+  "mayHaveMore": false,
+  "warnings": [],
+  "updatedAt": "2026-09-19T09:02:10+08:00"
+}
+```
+
+### 两个时间戳必须分开
+
+| 字段 | 何时推进 |
+| --- | --- |
+| `lastAttempt` | **每次尝试都推进**，无论结果 |
+| `lastSuccessfulRun` | **仅在 `coverage !== 'partial'` 时推进** |
+
+只有一个的话，"跑了但部分完成"会和"跑成功了"混为一谈——而这正是方案 §5.2 明令禁止的
+（部分完成不能返回成功状态）。
+
+### `coverage` 三档
+
+| 值 | 含义 |
+| --- | --- |
+| `complete` | 扫到的分片全部打开、打开的全读成功，且 `mayHaveMore` 为 false |
+| `unverified` | 有分片**打不开**，但打开的都读成功。已读部分是可信的，未打开的分片是否含本会话消息**无法判断** |
+| `partial` | 某个**已打开**的分片读失败，或 `mayHaveMore` 为 true，或分页在到达窗口起点前就短页结束 |
+
+`unverified` 不是失败：`connect_message_shards` 一直把打不开的分片当作可跳过的（这是有意设计），
+CLI 无法知道那个分片里有没有本会话的消息。如实标成 `unverified` + `warnings` 比直接失败更有用，
+也让自动化不至于卡死。
+
+`partial` 则**必须失败**（`code: 'SYNC_PARTIAL'`，退出码 1）：状态文件照写（方案 §5.2 要求
+部分完成不得删除已生成的可用结果），但 `lastSuccessfulRun` 不推进。
+
+### 身份
+
+按方案 §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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weflow-cli",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "让 AI 读懂你的微信 — 公众号日报·聊天导出·知识库搜索·MCP Server",
   "type": "module",
   "bin": {