weflow-cli 1.6.4 → 1.8.0

package/docs/EXTENDING.md

@@ -0,0 +1,187 @@
+# Extending WeFlow CLI
+
+**Status: this is a checklist, not a plugin system.** There is no plugin loader, no third-party import surface,
+and no `exports` field in `package.json` (`bin` is the only entry point). So "extending" this project today means
+one of two things, and they are not equivalent:
+
+1. **In-repo** - add the capability to this source tree (fork + PR). Every recipe below is about this path, and each
+   one lists the places you must touch **and the test that will catch you if you miss one**.
+2. **Out-of-process** - call the project from a program you keep elsewhere, through **MCP** (`mcp-server/`, 27 tools)
+   or the CLI's `--json` surface. This is the only boundary that exists for code that does not live in this repository.
+
+## Why there is no plugin loader
+
+A plugin that runs inside this process would get, by construction, the same reach as the code it joins: the decrypted
+database path, the config (including every API key), the filesystem, and the message channel. The project's standing
+constraint is that **sending, assistant, MCP and cloud AI all keep an explicit permission boundary** - so the boundary
+that must be crossed to extend this thing is a process boundary, not a function call. MCP is that boundary: it is
+enumerable (`capabilities --json` lists what is exposed), scoped (per-tool confirmation for anything that leaves the
+machine), and can be turned off without touching this repository.
+
+A plugin/adapter mechanism is on the roadmap on purpose, with its constraint written down: third-party extensions must
+not read configuration, databases or arbitrary files directly, and must be disableable individually
+(`docs/ROADMAP.md`, "插件/适配器机制"). It is not implemented.
+
+## Recipe A - a new assistant tool
+
+The most common extension. All of it is in `src/services/assistantTools.ts` unless noted.
+
+| Step | Where | If you skip it |
+| --- | --- | --- |
+| 1. Declare it | `TOOL_DEFS` | The model never sees it - dead code. A test fails. |
+| 2. Implement it | `executeTool`, one `case '<name>':` | The model sees it, calls it, and gets `(未知工具: <name>)`. A test fails. |
+| 3. Config prerequisite (only if it cannot run without a key) | `TOOL_REQUIREMENTS` - one entry, `{ key, why }` | The tool is offered on machines where it cannot work. That is the failure this project already measured once: a model tried both search tools, both errored, and the answer said "both search tools are broken". |
+| 4. Cloud egress (only if user data leaves the machine) | In the handler: `if (ctx.requiresConfirm && args.confirm !== true) return confirmPreview(...)`; then claim it in `bin/weflow-cli.ts` under `safety.mcpSurface.callsCloudModels` **and** `requiresConfirm` | An external MCP caller sends the user's data with no preview. Tests fail - the assertion counts `ctx.requiresConfirm` occurrences in the source, so it cannot drift from the field. |
+| 5. Keep it off MCP (only if it cannot do its job over that transport) | `MCP_EXCLUDED` - one entry whose **value is the reason** | It is advertised on a transport where it silently cannot work (`look_at_image` is the worked example). |
+| 6. Coverage note | The header of `test/assistant-tools-branches.test.ts` states how many tools are executed; update it | The coverage claim becomes false while still reading as true. |
+
+Notes that are easy to get wrong:
+
+- **The description is the interface.** The model decides whether to call the tool from the description alone - keep it
+  a sentence about *when* to use it, not a restatement of the name.
+- **`parameters` must be a JSON-schema `object`.** An empty `properties` is fine for a no-argument tool.
+- **Failures are `(...)`**, successes are not. `producedContent()` in the same file reads that convention, and the
+  trace uses it. A success message that starts with a bracket has to be added to `PAREN_SUCCESS_PREFIXES` or it will be
+  reported as "no content".
+- **MCP needs no change.** The MCP surface is *derived* from `TOOL_DEFS` (`MCP_TOOL_DEFS`) - adding a tool adds it to
+  both paths at once. That is deliberate, and it is also why the surface is not read-only: see `docs/MCP.md`.
+
+## Recipe B - a new config key
+
+A key must appear in **five** places, and each one fails differently:
+
+| Where | Failure if missing |
+| --- | --- |
+| `src/services/configService.ts` - the `CliConfig` interface | Type errors elsewhere; the compiler catches this one. |
+| same file - the default literal | - |
+| same file - the `load()` mapping | The value silently disappears on the next start. The user sees "I set that already". |
+| same file - the `clear()` reset | `config reset` **loses** the old value and `getAll()` then reports it as never set. |
+| `bin/weflow-cli.ts` - `configurableKeys` | `config set` refuses the key outright. This one happened: `dashscopeApiKey`. |
+
+`test/config-keys.test.ts` reads all five and fails if a key is missing from any of them. It is a static text
+assertion, so changing the *format* of those literals turns it red - which is the intent, not a nuisance.
+
+Keys that hold secrets belong in `ENCRYPTED_KEYS` in the same file (they are stored encrypted at rest; reading the raw
+file shows ciphertext, not the value).
+
+## Recipe C - a new CLI command
+
+Two places in `bin/weflow-cli.ts`: the `program.command('...')` registration, and - if it should appear in the
+interactive menu - `showInteractiveMenu()` plus the `switch (action)` that maps a menu choice back to the command.
+
+`test/cli-menu.test.ts` keeps those in sync: menu entries and `switch` cases must match **in both directions**, and
+every `runCmd('x')` / `runSubCmd('p','c')` the menu calls must name a command that actually exists (that test asks the
+CLI's own `--help`, because the source cannot tell top-level commands from subcommands - 99 `.command('...')` call sites
+as of 2026-09-28, against however many real commands `--help` reports). This matters because both failure modes are silent: a menu entry with no `case` does nothing
+when picked, and `runCmd` is written as `if (cmd) await ...`, so a renamed command makes the entry do nothing too.
+
+Two conventions that hold across the command surface: every command that a script or an AI might drive has a `--json`
+mode, and anything destructive is two-phase (`--dry-run` preview, then `--yes`).
+
+## Recipe D - a new hand-written MCP tool
+
+Three places: the `ListTools` table in `mcp-server/index.ts`, a `case` in its `CallTool` switch, and the table in
+`docs/MCP.md`. `test/tool-registry.test.ts` compares the doc table against the actually-served set (hand-written +
+derived) and fails on a missing row, an extra row, or a duplicate - all three have happened or nearly happened.
+
+Prefer a **derived** tool (Recipe A) unless it needs something the assistant layer cannot provide. The hand-written
+list exists for tools with no assistant counterpart (article fetching, the versioned `weflow-message/v1` export).
+
+## Recipe E - a new Python workflow
+
+Scripts live in `scripts/` and are invoked through `src/services/pythonBridge.ts` (`runPythonJson` when the script
+prints JSON). Three rules that this project has been bitten by:
+
+- **Encoding: the bridge handles it, your hand-run does not.** Every script spawned through the bridge gets
+  `PYTHONIOENCODING=utf-8` (`src/utils/pythonProcessEnv.ts`), so stdout is UTF-8 there and `json.dumps(...,
+  ensure_ascii=False)` - what the scripts use - round-trips correctly. Running the same script by hand on this machine
+  gives a **GBK** stdout: Chinese comes out as GBK bytes (mojibake if you were expecting UTF-8) and a character
+  outside GBK (`✓`, an emoji) raises `UnicodeEncodeError` and kills the run. 34 of the 55 scripts call
+  `sys.stdout.reconfigure(encoding='utf-8', errors='replace')` in `main()` so both paths behave the same; if you add a
+  script you intend to run by hand, do the same. A probe that forgets to set that env var will show you a decoding bug
+  that does not exist in the real path.
+- **Fail loudly.** Exit non-zero, or return a JSON object whose `success` is false with an `error` string. "No JSON on
+  stdout" must never be read as "no results" - that conflation is why `get_todos` distinguishes "no pending todos" from
+  "extraction has never been run".
+- **State goes in over stdin, not argv.** Command lines are visible in the process list; the drafting tool passes the
+  conversation over stdin for exactly that reason, and `semantic_search.py` takes the query through the environment.
+
+Tests for Python live in `test/*_test.py` and run on the same filesystem as everything else (`npm test` covers
+TypeScript; `python -m unittest discover -s test -p '*_test.py'` covers these).
+
+## Recipe F - a new knowledge source
+
+The knowledge base is fed by "material that carries `[[wikilinks]]`": `compile_wiki` scans a source directory
+(`--source`, already a flag - no code change needed to add a source), aggregates every wikilink into concepts, and
+writes concept pages into the Vault. There are four producers today, all writing the same card shape into
+`output/*-notes/`: `article_notes.py` (concepts extracted from the Vault's article notes - it exists because
+those notes, measured over the whole corpus, carry **no** concept links), `chat_notes.py` (conversation cards),
+`fav_notes.py` (WeChat favourites, whose article bodies come from the daily line's cached fetcher rather than a
+second downloader) and `user_notes.py` (the user's own hand-written notes, read-only, whose summaries are marked
+as the model's reading). Adding a fifth means writing one producer that satisfies the table below; the
+aggregator, the lint and the assistant-facing search do not change - the lint finds card directories with an
+`output/*-notes` glob for exactly that reason.
+
+To add another, the producer must satisfy the consumer's contract exactly:
+
+| The consumer (`scan_articles`) needs | Notes |
+| --- | --- |
+| `*.md` under the source dir, with frontmatter | `title`, `source`, `topic`, `tags` are read; `README.md` is skipped |
+| A `## AI 摘要` (or `## 深度解析`) section | the paragraph after it becomes the note's summary |
+| `[[name]] — description` lines | anywhere in the body; the description is what gets fed to page generation, so keep it clean (no trailing labels) |
+
+**Two rules that are not obvious from that table.** Links should be rendered by your code, not written by a model -
+the consumer collects *every* wikilink in a body and cannot tell who wrote it, so a stray one invents a concept
+(this is why `chat_notes.plain()` strips `[[...]]` from model-authored free text). And a wikilink whose description
+is polluted - a trailing `（话题）`, a stray marker - silently degrades every concept page it feeds, because that
+description is the material for the page.
+
+**A new source also has to pick a line.** Since 2026-09-27 the concept pages live in two directories -
+`Wiki/Concepts` for the article line, `Chat/Concepts` for the conversation line - so a source that writes into a
+directory nobody reads is invisible, and `compile_wiki` writes whichever line you point `--output` at (one line per
+run, by design). If your source belongs to an existing line, you are done; if it deserves its own, it goes into
+`_utils.CONCEPT_DIRS` and into every other declaration that `test/concept-dirs-agreement.test.ts` pins (that test
+counts the sites itself rather than trusting a number written here) - that test
+fails until every reader of concept pages knows about the new directory, which is the point.
+
+The guard to copy: `test/chat_notes_test.py` writes a card and then runs the **real consumer**
+(`compile_wiki.scan_articles`) over it, asserting the links and descriptions come back. That is the shape of every
+producer/consumer pair in this project - do not assert on the markdown text, assert that the other side reads it.
+
+## What will catch you
+
+| Invariant | Test |
+| --- | --- |
+| Declaration table and `executeTool` cases match, **both directions**, names unique, every declaration usable | `test/tool-registry.test.ts` |
+| Availability rules and the MCP exclusion table name real tools | `test/tool-registry.test.ts` |
+| `docs/MCP.md`'s table equals the served MCP surface, no duplicates | `test/tool-registry.test.ts` |
+| Every inbound-egress tool carries the `confirm` gate, and `capabilities --json` agrees | `test/assistant-tools.test.ts` |
+| A config key exists in all five places | `test/config-keys.test.ts` |
+| The MCP subset contains no write/send/publish tool | `test/assistant-tools.test.ts` |
+| Panel IPC surface is exactly the declared method list | `test/panel-packaging.test.ts` |
+| Interactive-menu entries match `switch` cases, and the commands they call exist | `test/cli-menu.test.ts` |
+| A knowledge source's output is readable by the wiki aggregator, links and descriptions intact | `test/chat_notes_test.py`, `test/compile_wiki_test.py` |
+| Every declaration of the concept directories agrees, and nothing that imports the constant stops iterating it | `test/concept-dirs-agreement.test.ts` |
+
+## Red lines
+
+These hold for any extension, and the full statements live in `AGENTS.md` and `CLAUDE.md`:
+
+- Local data is the user's. Never put database paths, keys, tokens, account identifiers, chat content, exports or real
+  local paths into source, docs, fixtures, issues, commits or command output.
+- **Sending is structurally unreachable from a model-driven path.** No extension may add a path that sends a message,
+  fills an input box, or drives another application's UI on the model's behalf.
+- Anything that leaves the machine goes through `privacyGate`. Redaction, not discretion.
+- Do not widen an assertion or a test to make a number look better. A static check that has to be relaxed is usually
+  reporting a real change.
+- Do not record a guess as a verified fact. When something has not been measured, say so where the claim is made.
+
+## What does not exist yet
+
+Named here so that the gaps are not mistaken for omissions:
+
+- **A plugin loader / adapter interface.** Roadmap, not implemented (see above).
+- **A public import surface.** No `exports`, `main` or `types`; the published package is a CLI, and `src/` is shipped
+  without a stability promise.
+- **A versioned extension contract.** The versioned contracts that exist are data contracts (`weflow-message/v1`,
+  `weflow-sync/v1`), not code contracts.

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)