weflow-cli 1.5.0 → 1.6.1

package/docs/AI_INTERFACE.md

@@ -0,0 +1,189 @@
+# AI 接口
+
+WeFlow CLI 的 AI 接入分为三层：
+
+1. **能力探测**：先运行 `weflow-cli capabilities --json`，确认当前版本支持的读取、导出和分析入口。
+2. **结构化 CLI**：读取型命令优先使用 `--json`，避免解析表格、颜色和自然语言日志。
+3. **MCP**：本地 Agent 可使用 stdio MCP；消息数据优先使用 `wechat.export_messages`，返回 `weflow-message/v1`。
+
+默认 MCP 仅提供有界读取和本地转换能力，不提供消息发送、公众号发布、长期记忆写入、待办修改、配置变更或删除。需要副作用的自动化必须改用具备项目自身预览和确认协议的显式 CLI 工作流。
+Agent 可先调用 `capabilities --json`，并检查 `safety.mcpDefaultReadOnly`，再决定是否使用 MCP。
+
+## 推荐调用顺序
+
+```powershell
+weflow-cli capabilities --json
+weflow-cli config show --json
+weflow-cli whitelist list --json
+weflow-cli blacklist list --json
+weflow-cli sessions --json --limit 30
+weflow-cli messages "<session-id>" --json --limit 100
+weflow-cli check --json
+weflow-cli daily-stats --json
+weflow-cli daily --no-ai --dry-run --json
+weflow-cli daily --no-ai --yes --json
+weflow-cli sns timeline --json --limit 20
+weflow-cli sns users --json
+weflow-cli sns stats --json
+weflow-cli daily-server --status --json
+weflow-cli evidence "<session-id>" --json --non-interactive --limit 100
+weflow-cli evidence-review "<session-id>" --dry-run --json --limit 100
+weflow-cli export "<session-id>" json --contract weflow-v1 --output "<local-output>"
+```
+
+Add `--json` to an export command when the caller needs a machine-readable operation result. This changes only stdout status reporting, not the selected export file format. The result contains `success`, `format`, `contract`, `path`, and `count`. The `weflow-v1` file additionally includes conservative `coverage` metadata (`requestedFrom`, `requestedTo`, `requestedLimit`, `returned`, `mayHaveMore`, and returned time bounds); it does not expose a stable incremental cursor yet. `--date` applies to every export format using the machine's local calendar day; `--date` cannot be combined with `--from` or `--to`.
+
+Favorite exports use `--json-result` because `json` is already a positional file format: `fav export json --json-result --output <local-file>`. The result reports only status, path, format, and count; exported favorite content remains in the local file.
+
+## Two-phase todo mutations
+
+Agents must preview a todo mutation before asking the user to approve it. The preview is read-only. Execution requires the explicit `--yes` flag; JSON mode without it returns `CONFIRMATION_REQUIRED` and leaves the todo file unchanged.
+
+```powershell
+weflow-cli todos done <id> --dry-run --json
+weflow-cli todos done <id> --yes --json
+weflow-cli todos undone <id> --dry-run --json
+weflow-cli todos rm <id> --dry-run --json
+```
+
+These todo commands authorize only the previewed todo mutation. Messaging, access control, configuration, assistant lifecycle, publishing, and other side effects require their own explicit protocol.
+
+Access-control changes use the same preview/confirm pattern and return local sensitive identifiers:
+
+```powershell
+weflow-cli whitelist add <target> --dry-run --json
+weflow-cli whitelist add <target> --yes --json
+weflow-cli whitelist rm <session-id> --dry-run --json
+weflow-cli blacklist add <target> --dry-run --json
+weflow-cli blacklist rm <session-id> --yes --json
+```
+
+Message sending is available only through the existing official Bot channel and also requires two phases:
+
+```powershell
+weflow-cli send <session-id> <message> --dry-run --json
+weflow-cli send <session-id> <message> --yes --json
+```
+
+The preview contains message content and local identifiers, so it must remain local. This command cannot initiate a personal-account message or send into an ordinary personal WeChat group.
+Image and file previews contain only the base file name and byte size, not the full local path. The selected media must be a readable, non-empty regular file, and `--image` cannot be combined with `--file`.
+
+Starting the assistant may create a background process, handle incoming Bot-channel messages, and consume AI quota. Agents must use `assistant start --dry-run --json` before a user-approved `assistant start --yes --json`. Stopping follows the same protocol. Status remains read-only through `assistant status --json`.
+
+The local daily reader follows the same lifecycle pattern. `daily-server --status --json` only checks loopback status. Starting it requires `daily-server --dry-run --json` followed by user-approved `daily-server --yes --json`; the confirmed JSON startup waits for the loopback service to report the requested date and returns a failure code if the date output is missing or the process does not become ready. Add `--open` only when the user also wants a browser window opened. Human-oriented non-JSON startup remains compatible. The older `fav-server` command is a compatibility entry and applies the same machine-mode confirmation rule.
+
+Message-channel authentication is human-gated. Agents may inspect `login-wechat --dry-run --json`, but actual login uses `login-wechat --yes` in an interactive terminal because the user must scan a QR code. `login-wechat --yes --json` returns `INTERACTIVE_REQUIRED` without starting login. Logout uses `logout-wechat --dry-run --json` followed by user-approved `logout-wechat --yes --json`.
+
+Initialization is also human-gated because it may verify private databases, search local disks, capture keys, and update encrypted configuration. Agents may call `init --dry-run --json`; `init --json` returns `INTERACTIVE_REQUIRED` without scanning or writing. Actual initialization remains the interactive `init` command.
+
+朋友圈密钥捕获同样需要用户在微信客户端中触发。Agent 只能调用 `sns capture-key --dry-run --json` 查看要求；实际捕获使用交互终端中的 `sns capture-key --yes`，JSON 执行会返回 `INTERACTIVE_REQUIRED`，不会扫描进程。
+
+`listen` 和 `assistant run` 会在当前终端持续运行并处理消息内容，因此也属于人工前台流程。Agent 可调用对应的 `--dry-run --json` 预览，但实际启动必须使用非 JSON 的 `--yes`，常驻自动化应优先使用已确认的 `assistant start --yes --json`。
+
+Vault Git synchronization also uses two phases because it commits local files and pushes them to a remote repository:
+
+```powershell
+weflow-cli vault sync --dry-run --json
+weflow-cli vault sync --yes --json
+```
+
+The preview reports only the number of changed file states and whether the Vault is already a Git repository. It does not return file names or the remote URL.
+
+Vault initialization can create directories and overwrite its four managed template files. Agents must inspect the overwrite count before execution:
+
+```powershell
+weflow-cli vault init --path <local-directory> --dry-run --json
+weflow-cli vault init --path <local-directory> --yes --json
+```
+
+Knowledge indexing, pipelines, and generated reports also use two phases. Their previews do not read chat data, call AI services, or write files:
+
+```powershell
+weflow-cli search-index --dry-run --json
+weflow-cli search-index --yes --json
+weflow-cli pipeline run --no-ai --source <source-name> --dry-run --json
+weflow-cli pipeline run --no-ai --source <source-name> --yes --json
+weflow-cli report --no-ai --dry-run --json
+weflow-cli annual-report YYYY --skip-ai --dry-run --json
+weflow-cli review --dry-run --json
+weflow-cli evidence-review "<session-id>" --dry-run --json
+```
+
+Remove `--no-ai` or `--skip-ai` only after the user approves sending the described content to the configured provider. `search-index` always sends collected text to the configured embedding provider. After approval, `evidence-review` uses `--yes --json`; cloud processing additionally requires `--allow-cloud`. JSON results omit selected conversation names, report content, and local output paths.
+
+Vault enrichment, reading-note creation, AI tagging, WeRead synchronization, promotion workflows, consumption statistics, and daily-favorite changes follow the same rule:
+
+```powershell
+weflow-cli vault enrich --date YYYY-MM-DD --dry-run --json
+weflow-cli vault notes --date YYYY-MM-DD --dry-run --json
+weflow-cli vault tag --date YYYY-MM-DD --dry-run --json
+weflow-cli vault sync-weread --dry-run --json
+weflow-cli vault promote ideas --dry-run --json
+weflow-cli wiki compile --dry-run --json
+weflow-cli chat-stats --dry-run --json
+weflow-cli todos extract --days 7 --dry-run --json
+weflow-cli daily favorites add <article> --dry-run --json
+```
+
+After approval, replace `--dry-run` with `--yes`. Multiple daily-favorite articles use repeated `--article <path>`. Preview and result JSON report counts and behavior only, not article names, book names, report data, or paths.
+
+Writing an MCP client configuration follows the same protocol. Reading the generated configuration needs no confirmation; writing a file does:
+
+```powershell
+weflow-cli mcp-config
+weflow-cli mcp-config --output .mcp.json --dry-run --json-result
+weflow-cli mcp-config --output .mcp.json --yes --json-result
+```
+
+Secrets should be persisted from an existing environment variable so their values do not appear in command arguments:
+
+```powershell
+weflow-cli config set-env deepseekApiKey DEEPSEEK_API_KEY --dry-run --json
+weflow-cli config set-env deepseekApiKey DEEPSEEK_API_KEY --yes --json
+weflow-cli fav set-key --from-env WEFLOW_FAV_KEY --dry-run --json
+weflow-cli fav set-key --from-env WEFLOW_FAV_KEY --yes --json
+```
+
+Human-oriented configuration commands keep their direct behavior. JSON configuration writes require explicit `--yes`; their preview and result contain the key and environment-variable name but never the value.
+
+Bulk deletion is destructive and follows the same two-phase protocol: preview `config clear`, `whitelist clear`, `blacklist clear`, or `audit clear` with `--dry-run --json`, then execute the approved command with `--yes --json`. Previews return only counts or impact flags, never entries or log content. A JSON-mode call without confirmation returns `CONFIRMATION_REQUIRED`. Individual whitelist and blacklist additions or removals also require `--yes` in JSON mode.
+
+Database-key reset follows the same rule: preview with `config forget-keys --dry-run --json`; `config forget-keys --json` returns `CONFIRMATION_REQUIRED`; only a user-approved `config forget-keys --yes --json` clears saved database access keys. `config show --json` is intentionally redacted and reports status flags and counts rather than paths, account identifiers, or secret values. Access-list JSON contains local identifiers and must remain local.
+
+Process-memory key capture is human-gated. An Agent may inspect `dbkey --force --dry-run --json`, but JSON execution returns `INTERACTIVE_REQUIRED`; actual capture requires `dbkey --force --yes` in an interactive terminal. `scan --json` reports only whether candidates exist and their count. `assistant log --json` reports log availability and line counts without returning log text.
+
+Vault RAG can send selected local knowledge to the configured AI provider, so it also uses two phases:
+
+```powershell
+weflow-cli vault rag "<question>" --dry-run --json
+weflow-cli vault rag "<question>" --yes --json
+```
+
+The preview does not read the Vault or call AI and does not echo the question. Execution passes the question to the bundled worker without placing it in child-process arguments. `todos remind --json` is the structured read form of local todo reminders.
+
+Semantic search and chat-backed RAG also require explicit approval because they may send a query or selected local context to cloud services:
+
+```powershell
+weflow-cli search "<query>" --dry-run --json
+weflow-cli search "<query>" --yes --json
+weflow-cli chat "<question>" --talker "<session-id>" --dry-run --json
+weflow-cli chat "<question>" --talker "<session-id>" --yes --json
+```
+
+Previews omit the query, question, and conversation restriction. These values are inherited by the Python worker rather than placed in process arguments. `chat --yes --json` without a question returns `INTERACTIVE_REQUIRED`; interactive chat must be started by a person in a terminal.
+
+AI 应优先使用会话 ID，不应依赖昵称猜测。`messages --json` 默认采用非交互解析；`messages`、`export` 和 `evidence` 也支持显式 `--non-interactive`，名称匹配不唯一时会返回错误而不是等待人工选择。
+`messages --start` and `--end` accept Unix timestamps in seconds and are applied before offset and limit. Core read pagination rejects negative, fractional, nonnumeric, or excessive values with `INVALID_ARGUMENT`.
+
+## 数据与权限
+
+- 读取和导出默认在本地完成，不自动调用 AI。
+- `daily --no-ai` 可生成不含 AI 处理的日报。
+- `daily --json` 需要用户批准后的 `--yes`，将流水线日志写到 stderr，只在 stdout 输出最终状态，并逐项报告日报、文章索引和 HTML 阅读器产物是否完整。
+- `evidence-review`、`report`、`review`、`annual-report`、`search-index`、`pipeline`、`chat` 和其他分析任务需要显式选择 AI，并遵守隐私设置。报告、索引和流水线的 JSON 写操作还需要 `--yes`；预览不会读取本地内容或调用 AI。
+- `send`、配置修改、密钥捕获、发布和删除属于副作用操作，AI 不应在没有用户确认时执行。
+- 任何下游项目都不得接收数据库路径、解密密钥、完整配置或无限制文件系统权限。
+
+## 当前边界
+
+并非所有命令都已经提供 JSON 输出。目前已结构化的基础入口包括能力探测、脱敏配置状态、访问控制列表、环境检查、会话、消息、联系人、朋友圈时间线与统计、阅读器状态、证据包、收藏、待办、日报频率、Vault 初始化和同步、语义索引、知识流水线及报告生成。尚未结构化的命令应通过 MCP 或现有文本接口临时调用，并将其列为兼容性限制，而不是猜测文本格式。未知消息类型必须保留原始类型码并安全降级为 `other`。

package/docs/BRANCHES.md

@@ -0,0 +1,87 @@
+# 分支与合并记录
+
+本文件记录分支的用途、合并时间与合并内容，以及并行开发时的对齐约定。
+每次把工作分支并入 `master` 后，请在「合并记录」中追加一行。
+
+## 分支一览
+
+| 分支 | 用途 | 状态 |
+| --- | --- | --- |
+| `master` | 主线，随时可发布 | 受保护 |
+| `trae/*` | 早期 AI 协作产生的分支 | 部分已合并，部分搁置 |
+| `draft/*` | 探索性草稿，允许与主线脱节 | 按需清理 |
+| `feat/*`、`fix/*` | 从**当前** `master` 切出的工作分支 | 合并后删除 |
+
+> **约定**：`feat/*` 与 `fix/*` 必须从最新的 `master` 切出。`draft/*` 无此要求，
+> 但**合并前必须先把 `master` 合进来**（见下方「并行开发」）。
+
+## 合并记录
+
+| 日期 | 来源分支 | 目标 | 方式 | 说明 |
+| --- | --- | --- | --- | --- |
+| 2026-06-30 | `trae/solo-agent-Xl3Lhb` | `master` | 合并提交 `bc44e93` | 优化消息与朋友圈功能 |
+| 2026-09-01 | `Mandark6/master` | `master` | PR #6，合并提交 `2d3005c` | 外部贡献 |
+| 2026-09-10 | `feat/export-enhancements` | `master` | 快进至 `64dcf2f` | 表情原版图、`--per-page` 分页、表情包本地解密、图片缩放；并修复跨分片未生效 |
+| 2026-09-10 | `draft/weflow-cli-improvements` | — | **未合并，已作废** | 基于过期 master；独有功能已移植，见下方「2026-09-10」条目 |
+
+### 2026-09-10 · `draft/weflow-cli-improvements`
+
+该分支产出了导出链路的若干增强，但**基于过期的 `master`**（共同祖先 `cbec736`），
+当时 `master` 已领先 78 个提交。因此**没有直接合并**，改为把其中的独有功能移植到
+从最新 `master` 切出的 `feat/export-enhancements`。
+
+分支仍保留在本地与远端，标签 `backup/my-export-work` 指向其顶端 `c181afb`。
+
+移植与放弃的清单：
+
+| 项 | 处理 | 原因 |
+| --- | --- | --- |
+| 跨分片读取 | **改修为接线修复** | `master` 有 `fetch_messages_from_shards`，但见下方「附带修复」 |
+| 主密钥派生 | **放弃** | `master` 已有 `derive_database_key`，算法与草稿一致 |
+| 图片按 `(local_id, create_time)` 配对 | **放弃** | `master` 已有 |
+| `.dat` 图片解密与资源映射 | **放弃** | `master` 已有 `decode_wechat_v2`、`load_resource_media_map` |
+| zstd 解压、CDATA 解析、名片渲染 | **放弃** | `master` 已有 |
+| 会话列表改读 `session.db` | 待定 | 需与 `master` 现有实现比对 |
+| **微信原版表情图（109 张）** | **移植** | `master` 仅 9 张 |
+| **表情按 CSS 类去重** | **移植** | `master` 每个出现都重复内嵌 base64 |
+| **`--per-page` 按条数分页** | **移植** | `master` 只有 `--parts`（按份数） |
+| **表情包本地解密** | **移植** | `master` 走 CDN，需联网 |
+| **图片缩放管线** | **移植** | `master` 按原始尺寸内嵌 |
+
+### 附带修复：跨分片合并默认未生效
+
+移植过程中发现 `master` 的跨分片能力实际处于休眠状态：`derive_database_key()` 需要
+`passphrase` 才会派生分片密钥，而 `exportService.ts` 只从配置的 `favPassphrase` 读取，
+`init` 写入的却是 `decryptKey`。两者本是同一个值，但字段名不同，于是口令为空、派生
+退回单库密钥，导出静默地停在第一个分片的最后一条消息。
+
+实测：某会话只导出 10 条（止于 2026-04-23），而该会话实际有 20 条（到 2026-09-10）。
+已在 `exportService.ts` 增加 `favPassphrase || decryptKey` 回退。
+
+## 并行开发
+
+本次出现的问题：本地克隆停在 `cbec736`，之后主线积累了 78 个提交，导致在旧基线上
+从零实现了主线已有的功能，白做一遍。
+
+**动手前先对齐：**
+
+```bash
+git fetch origin
+git status -sb          # 看 ahead / behind
+git log --oneline HEAD..origin/master | wc -l    # 主线领先多少
+```
+
+若 `behind` 不为 0，先 `git checkout master && git pull --ff-only`，再切工作分支。
+
+**合并前自检：**
+
+```bash
+git fetch origin
+git log --oneline HEAD..origin/master            # 应尽量为空
+git merge-tree --write-tree origin/master HEAD   # 预看冲突
+```
+
+## 强推与清理
+
+- **禁止对 `master` 强推。** 若推送被拒，一律先 `git fetch` 查明主线新增内容。
+- 工作分支合并后应删除本地与远端副本；`draft/*` 保留至内容确认无用为止。

package/docs/DATA_CONTRACT.md

@@ -0,0 +1,74 @@
+# Data Contract
+
+This document defines the stable, local export boundary for downstream tools such as `she-love-me`.
+
+## First Integration
+
+The first downstream consumer is `she-love-me`. It should continue to invoke the existing command:
+
+```powershell
+weflow-cli export "<contact>" json --output "<local-output>"
+```
+
+The command remains a local, user-authorized export. It does not upload messages or grant another application direct access to the WeChat database.
+
+## JSON Contract
+
+The JSON output is a message array. A downstream consumer must tolerate both a top-level array and an object containing a `messages` array.
+
+For new integrations, request the versioned envelope:
+
+```powershell
+weflow-cli export "<contact>" json --contract weflow-v1 --output "<local-output>"
+```
+
+The envelope contains `schema: "weflow-message/v1"`, `source`, `generatedAt`, and `messages`. Versioned exports also include optional `coverage` metadata: `requestedFrom`, `requestedTo`, `requestedLimit`, `returned`, `mayHaveMore`, and the oldest/newest returned `createTime`. `mayHaveMore` is deliberately conservative: it is true when the result reaches the requested positive limit, and false only when it does not. The default `raw` contract remains unchanged for existing consumers.
+
+The currently supported message fields are:
+
+| Field | Meaning | Consumer guidance |
+| --- | --- | --- |
+| `localId` | Local database message identifier | Display or trace only; it is not globally unique. |
+| `isSend` | Whether the message was sent by the local account | Prefer this field for `me`/`them` mapping when present. |
+| `createTime` | Unix timestamp in seconds | Normalize and validate before analysis. |
+| `localType` | WeChat message type code | Map unknown values to `other`; do not discard the message. |
+| `messageType` | Stable type name in `weflow-v1` | One of `text`, `image`, `voice`, `card`, `video`, `emoji`, `location`, `link`, `call`, `system`, `quote`, or `other`. |
+| `senderUsername` | Sender identifier when available | Treat as sensitive and do not expose in public reports. |
+| `parsedContent` | Parsed, human-readable content | Prefer over `rawContent` for analysis. |
+| `rawContent` | Original or fallback content | Preserve locally for traceability; do not assume it is display-safe. |
+| `transcript` / `voiceTranscript` | Optional voice transcription | Treat as user content and keep local. |
+
+Downstream tools must not assume that local IDs are unique across conversations or database shards. Ordering should use `createTime` and a stable local tie-breaker.
+
+## Incremental Reads Before A Cursor Exists
+
+Until a stable cursor is available, a downstream reader can use an overlapping time window:
+
+1. Export with `--contract weflow-v1` and record `coverage.newestCreateTime` locally.
+2. On the next run, use `--from` at or slightly before that timestamp so messages sharing a second are not missed.
+3. Deduplicate within the downstream store using the conversation identifier plus `localId` and `serverId` when present.
+
+This is a best-effort synchronization recipe. It must not treat a timestamp as a globally unique message identifier, and it must retain the previous checkpoint if the export fails.
+
+## Compatibility Rules
+
+- Keep the existing `export <contact> json` command working.
+- Use `--from` and `--to` for bounded exports when available; dates are interpreted in local time for date-only values.
+- `--date YYYY-MM-DD` applies the same local calendar-day bound to JSON, TXT, HTML, and Excel exports. It cannot be combined with `--from` or `--to`.
+- Add `--json` for a machine-readable operation result containing the output path and exported message count; this flag does not change the file format selected by the positional `format` argument.
+- Use `--limit 0` for a complete export. With date filters, a positive limit applies to matching messages after the time range is evaluated.
+- Preserve unknown fields so new media and message metadata can be adopted without breaking consumers.
+- Treat `coverage` as query metadata, not proof that the underlying database is complete; database shards and concurrent writes can affect observed bounds.
+- Treat missing sender identity as `unknown`; never infer identity from a display name alone.
+- Keep conversion to a downstream application's internal schema in that application. `weflow-cli` remains a general data foundation.
+
+## Privacy Boundary
+
+- Data is read only from a user's own device or data they are authorized to access.
+- Export files, database paths, account identifiers, keys, logs, and raw message content stay local by default.
+- `she-love-me` should write its normalized bundle under its own local data directory and should not send raw exports to a model without explicit user consent and privacy filtering.
+- AI analysis is not part of the export contract. An export must work without an API key or model call.
+
+## 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.

package/docs/DECISIONS.md

@@ -0,0 +1,270 @@
+# Technical Decisions
+
+> Record decisions that affect long-term maintenance. Each entry explains the chosen direction and the reason, not every implementation detail.
+
+## D-001: Local-first data handling
+
+**Status:** Active
+
+Local WeChat data, configuration, exports, and knowledge outputs remain on the user's machine by default. Network access occurs only in explicitly selected workflows such as article retrieval, configured cloud AI, or WeRead integration.
+
+**Reason:** The project handles highly sensitive personal communications. A local default reduces unnecessary data exposure without claiming legal or platform safety.
+
+## D-002: Separate data access from higher-level agents
+
+**Status:** Active
+
+Database access, MCP integration, local assistant behavior, and external products are separate trust boundaries. External projects may use constrained, read-only interfaces; they must not receive direct database paths, keys, credentials, or unrestricted filesystem access.
+
+**Reason:** This keeps `weflow-cli` independently maintainable and limits the blast radius of an MCP client, agent, or collaboration.
+
+## D-003: Default-deny assistant access
+
+**Status:** Active
+
+The optional WeChat assistant denies incoming users unless `assistantWhitelist` is explicitly configured. A new or incomplete configuration defaults to strict cloud-inference privacy behavior.
+
+**Reason:** An empty allowlist must not accidentally expose local chats, favorites, or memories to an unexpected sender.
+
+## D-004: Reader stays loopback-only
+
+**Status:** Active
+
+The daily reader binds to `127.0.0.1`; mutation endpoints enforce local-origin checks. Reader path handling and image proxying are restricted to reduce path traversal, cross-origin access, and SSRF exposure.
+
+**Reason:** The reader serves personal reading history, notes, favorites, and locally generated article data. It is not a LAN service.
+
+## D-005: Configured sources take precedence over article classification
+
+**Status:** Active
+
+When an official-account source has a configured category, the daily workflow keeps that source category and only produces the required summary. Automatic article-topic classification remains a fallback for uncategorized sources.
+
+**Reason:** Source-level categories are more stable and prevent unnecessary model calls or conflicting article labels.
+
+## D-006: Documentation has separate roles
+
+**Status:** Active
+
+`README.md` and `CHANGELOG.md` describe the product and release-visible changes. `docs/PROJECT_STATE.md` records the current engineering baseline. This file records durable rationale. `AGENTS.md` is the entry point for automated contributors.
+
+**Reason:** Release notes, architecture descriptions, and current maintenance context change at different rates. Combining them caused stale plans to look current.
+
+## D-007: Group routing stays upstream-gated and default-deny
+
+**Status:** Active
+
+The assistant only recognizes a group when the upstream Bot payload explicitly identifies one. A recognized group requires an explicit group allowlist entry, an existing sender allowlist entry, and an @ mention by default. The project does not use client automation, injected code, or undocumented protocol bypasses to join groups.
+
+**Reason:** The current official OC/iLink integration is verified for direct sessions, not group invitations or group-message metadata. Treating ambiguous payloads as groups or adding non-official automation would broaden privacy and account risk without a reliable permission model.
+
+## D-008: Bot-channel send is not personal-account messaging
+
+**Status:** Active
+
+The current `send` implementation uses the official OC/iLink Bot channel. It may only send into a previously established Bot conversation with a valid context token. It is not a facility for operating the user's personal WeChat account, initiating a message to a personal contact, or posting into an ordinary personal WeChat group.
+
+**Reason:** Local contact lookup and the Bot transport are separate systems. Resolving a local contact ID does not grant the Bot channel permission or protocol context to message that contact. Presenting the command as generic personal-WeChat sending would be misleading and could lead users to assume unsupported access exists.
+
+**Consequences:** Future messaging work must retain this boundary in command names, help text, and diagnostics. Any personal-account automation or undocumented protocol route requires a separate security and platform review; it is not an implicit extension of `send`.
+
+## D-010: Reuse verified local access before initialization
+
+**Status:** Active
+
+`init` first verifies an existing local database configuration and exits without a new key-capture attempt when access works. A user must explicitly pass `--refresh` to reinitialize. `dbkey` similarly avoids duplicate capture unless `--force` is supplied. `init --test-missing-keys` provides a non-persistent missing-key test; `config forget-keys` is reserved for an actual, confirmed reset without clearing unrelated settings.
+
+**Reason:** Repeated capture depends on client lifecycle timing and is unnecessary when a valid local configuration already exists. A verification-first workflow reduces account disruption and makes recovery steps deliberate.
+
+## D-011: Backfill incomplete yesterday before today
+
+**Status:** Active
+
+An unqualified `daily` run checks yesterday's required local artifacts and completes yesterday first when `README.md`, `.articles.json`, or `index.html` is missing or empty. Explicit-date and dry-run invocations remain single-date operations.
+
+**Reason:** A daily reader should not silently leave a gap when a previous scheduled run was interrupted. The required-artifact check is local, deterministic, and does not treat a directory alone as proof of a complete report.
+
+## D-012: Staged data-directory discovery
+
+**Status:** Active
+
+Initialization checks common user locations by default. Cross-drive searches for standard directory names require `init --search-drives`; deep structural searches require `init --full-scan`.
+
+**Reason:** Broad recursive scans can block the CLI for a long time and unnecessarily enumerate metadata from unrelated volumes. The staged commands retain recovery options for custom locations while making the cost and privacy scope explicit.
+
+**Consequences:** Support guidance should first request an explicit `--path`, then `--search-drives`, and only finally `--full-scan`. Diagnostic output must not include account identifiers, salts, keys, or full local paths unless a user intentionally inspects them locally.
+
+## D-013: Explicit AI for Vault promotion
+
+**Status:** Active
+
+`vault promote ideas` and `vault promote all` generate deterministic local indexes by default. AI generation is available only through explicit `--with-ai` plus a supplied API key or environment variable.
+
+**Reason:** Knowledge-promotion outputs can be created locally, while AI promotion has monetary and privacy implications. An opt-in avoids an unexpected network request when a user is organizing notes.
+
+**Consequences:** `vault init` must include the structured reading-note directories used by promotion. The promotion scripts must safely handle an empty or newly initialized Vault.
+
+## D-014: Match exported media using reliable message identity
+
+**Status:** Active
+
+HTML export selects message-resource records by nonzero server message ID. It does not use unscoped local message IDs or server ID zero to associate media. Content MD5 and source URL lookup remain available when a server mapping is absent.
+
+**Reason:** Local IDs can repeat across conversations and database shards. An ambiguous fallback can attach unrelated media to a chat message.
+
+**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-016: Establish a stable downstream data boundary
+
+**Status:** Active
+
+The first integration with `she-love-me` uses the existing local `export <contact> json` interface. Its field meanings and privacy requirements are documented in `docs/DATA_CONTRACT.md`. A future MCP interface may expose the same read-only contract, but must not bypass the local authorization and privacy boundary.
+
+**Reason:** Reusing the existing interface gives the first downstream consumer immediate compatibility while keeping `weflow-cli` general-purpose. A documented contract lets future tools build on the data layer without coupling their internal analysis schema to database implementation details.
+
+**Consequences:** Changes to exported field semantics require a compatibility review. Downstream consumers must preserve unknown fields, handle missing identities, and keep raw exports local unless the user explicitly authorizes a privacy-filtered cloud workflow.
+
+## D-017: Expose the data contract through read-only MCP
+
+**Status:** Active
+
+The MCP server exposes `wechat.export_messages` as a bounded, read-only transport for the same `weflow-message/v1` envelope used by CLI exports. It accepts a session ID or an unambiguous display name, validates inclusive date filters, and caps the result size.
+
+**Reason:** External projects need a stable integration boundary without receiving database paths, keys, configuration, or direct database access. Keeping MCP and CLI on the same contract avoids divergent message semantics.
+
+**Consequences:** MCP clients must handle unknown message types and missing identities. The tool does not invoke AI or provide write/messaging operations. Any future broader access requires a separate security review.
+
+## D-018: Add machine-readable capability discovery
+
+**Status:** Active
+
+The CLI exposes `capabilities --json` as the first call for automation. Read-oriented commands progressively provide `--json` output, while interactive initialization and side-effect operations remain explicitly marked as requiring user participation or confirmation.
+
+**Reason:** An AI client needs to discover the current implementation and safety limits before choosing a command. A capability document is more reliable than inferring support from human-oriented help text.
+
+**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
+
+Machine-facing write operations use a two-phase protocol: first return a read-only preview, then execute only after explicit user approval. Todo completion, reopening, and deletion are the first commands implementing this rule.
+
+**Reason:** An agent needs structured write access without gaining silent authority to alter local state. A stable preview and `CONFIRMATION_REQUIRED` response lets clients present the exact action before requesting approval.
+
+**Consequences:** JSON-mode todo, access-control, message-send, configuration, destructive clear, assistant lifecycle, and local-reader startup operations require `--yes`; `--dry-run --json` never writes, deletes, or starts a process. Clear previews expose counts or impact flags rather than entries. Human access-control removals also ask for confirmation. Publishing and future side-effect interfaces must define equivalent confirmation boundaries before being advertised as agent-ready.
+
+## D-020: Keep secrets out of child-process arguments
+
+**Status:** Active
+
+The TypeScript CLI and Python pipeline pass AI credentials, database credentials, account or conversation identifiers, private queries and filters, export locations and display names, and sensitive scan roots to worker processes through environment variables. They do not append these values to child-process argument arrays.
+
+**Reason:** Command-line arguments can be visible in process inspection tools and can be repeated in runtime errors. Environment inheritance narrows accidental exposure while preserving existing CLI, environment, and encrypted-configuration workflows.
+
+**Consequences:** Python entry points keep explicit arguments for direct compatibility but also accept the internal `WEFLOW_*` environment variables. Long-lived workers clear unrelated internal variables before startup. New subprocess wrappers require a regression check before they may accept credentials, account identifiers, private questions, or local data roots.
+
+## D-021: Keep the default MCP surface read-only
+
+**Status:** Active
+
+The default MCP server exposes bounded read and local transformation tools only. It does not expose assistant-memory writes, official-account publishing, message sending, todo mutation, configuration changes, or deletion.
+
+**Reason:** MCP clients can autonomously select tools and inherit the user's local permissions. Client-side approval prompts are not a stable substitute for the project's own preview and confirmation protocol.
+
+**Consequences:** Write capabilities remain available only through explicit CLI or assistant workflows that implement an appropriate confirmation boundary. Conversation names must resolve uniquely, and MCP-facing limits reject invalid or excessive values instead of silently selecting or coercing them.
+
+## D-022: Keep source and compiled resource lookup equivalent
+
+**Status:** Active
+
+CLI, MCP, database, export, and assistant services resolve scripts, native resources, generated-output roots, and runtime entries from one shared package-root resolver rather than assuming a fixed source or `dist` directory depth.
+
+**Reason:** Development runs execute `bin/weflow-cli.ts`, while installed and packaged runs execute `dist/bin/weflow-cli.js` through `cli.cjs`. Relative traversal that works in one layout can point at the parent repository or `dist/scripts` in the other layout.
+
+**Consequences:** New commands and services must use the shared package-root resolver for bundled scripts, native libraries, runtime entries, and package-owned output. Both source and compiled module layouts require regression coverage when resource lookup changes.
+
+## D-023: Bound Agent-initiated network reads
+
+**Status:** Active
+
+MCP article fetching accepts only credential-free HTTPS URLs on the exact `mp.weixin.qq.com` host. Redirects are followed manually only while every destination remains allowed, with a finite redirect count, request timeout, and response-size limit. Public article search also validates its result limit and bounds the downloaded response.
+
+**Reason:** Read-only tools can still reach external networks. Substring host checks, unrestricted redirects, and unbounded response bodies can enable SSRF, unexpected internal access, hangs, or memory exhaustion.
+
+**Consequences:** New network-facing Agent tools must define an allowlist or equivalent public-network validation, finite time and size budgets, and tests that reject crafted URLs before network access.
+
+## D-024: Confirm Vault publication
+
+**Status:** Active
+
+`vault sync` uses `--dry-run --json` for a content-free preview and requires explicit `--yes --json` for machine execution. Preview and result JSON omit file names and remote URLs.
+
+**Reason:** A Git push discloses local files outside the machine even when the Vault itself is local. The old change check also ignored untracked files, making first-run behavior unreliable.
+
+**Consequences:** The command detects tracked and untracked changes with `git status --porcelain`, does not initialize a repository during preview, and does not expose credential-bearing remote URLs in output.
+
+## D-025: Confirm local generation and cloud analysis
+
+**Status:** Active
+
+Commands that create or replace local knowledge artifacts, build semantic indexes, or send selected content to an AI provider use a read-only preview followed by explicit confirmation. This applies even when no remote publication occurs.
+
+**Reason:** Local file writes can overwrite user-managed material, while AI and embedding workflows can disclose selected content and consume quota. Treating only network publication as a side effect leaves Agent-driven local generation insufficiently controlled.
+
+**Consequences:** Vault content mutations, Vault RAG, semantic search, RAG chat, evidence review, Wiki compilation, todo extraction, daily-favorite changes, semantic indexing, knowledge pipelines, and report generators expose `--dry-run --json` and require `--yes --json` for machine execution. Interactive key capture and interactive RAG chat expose previews but reject JSON execution. Preview mode does not read private content, call external services, scan processes, or write files; structured status results omit local paths, selected names, logs, and generated content. Queries, questions, and conversation restrictions passed to Python workers use environment inheritance instead of process arguments.
+
+## D-026: Reject unsupported WCDB query parameters
+
+**Status:** Active
+
+The bundled WCDB DLL exposes a raw SQL query ABI without parameter binding. `execQuery` rejects non-empty parameter arrays until the native interface can be upgraded and verified.
+
+**Reason:** Silently ignoring parameters and executing the original SQL would create a misleading and unsafe API contract for future callers.
+
+**Consequences:** Existing fixed internal queries are unchanged. A future parameterized implementation requires a native ABI change, compatibility testing, and a separate security review.
+
+## D-027: Add conservative coverage metadata to the versioned message contract
+
+**Status:** Active
+
+`weflow-message/v1` may include query coverage metadata such as requested bounds, returned count, returned time bounds, and a conservative `mayHaveMore` flag. The legacy `raw` export remains a top-level message array and does not gain this metadata.
+
+**Reason:** Downstream data consumers need enough information to checkpoint time-window synchronization without treating a timestamp as a globally unique cursor or assuming that a database shard is complete.
+
+**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.
+
+## Decision Template
+
+
+```markdown
+## D-XXX: Short title
+
+**Status:** Proposed | Active | Superseded
+
+State the decision in one or two sentences.
+
+**Reason:** Explain the constraint, trade-off, and why alternatives were not selected.
+
+**Consequences:** List compatibility, migration, security, or documentation follow-up when relevant.
+```