weflow-cli 1.5.0 → 1.6.1

package/docs/DEEPSEEK_V4_FLASH/346/226/275/345/267/245/346/226/207/346/241/243.md

@@ -0,0 +1,234 @@
+# DeepSeek V4 Flash 施工文档
+
+> 用途：交给 DeepSeek V4 Flash 或其他代码 Agent 执行 WeFlow CLI 的后续开发。  
+> 项目：WeFlow CLI  1.5.x  由于当前仓库可能存在尚未提交的维护者改动，施工前必须先检查工作区，不得覆盖或重置已有修改。
+
+## 1. 施工目标
+
+将 WeFlow CLI 继续建设为安全、可验证、可供 Agent 使用的本地数据底座，优先解决聊天记录 HTML 导出的可靠性，再逐步完善稳定数据契约、公众号日报、知识工作流和受控 AI 能力。
+
+本轮首要目标是：
+
+1. 图片、表情、转发文章和链接在 HTML 导出中尽可能完整显示。
+2. 媒体必须和正确的消息关联，不能为了提高显示数量而把其他消息或其他会话的图片配进来。
+3. 转发文章既要保留可用缩略图，也要保留标题、描述和原始跳转链接。
+4. 大会话导出不能因远程封面或网络请求无限等待。
+5. 所有改动都要能由测试或脱敏的本机验证证明，不能只凭代码推测已修复。
+
+完整的长期路线见 [ROADMAP.md](ROADMAP.md)。本文件是施工执行书，优先级高于路线图中的远期事项。
+
+## 2. 开工前检查
+
+在任何编辑前执行并记录结果：
+
+```powershell
+git status --short
+git log --oneline -12
+npm run build
+npm test
+python -m unittest discover -s test -p '*_test.py' -q
+```
+
+如果已有测试失败，先记录失败测试和原因，不能把既有失败归到本次施工，也不能为了变绿而删除或放宽测试。
+
+重点阅读：
+
+- `AGENTS.md`：仓库级规则和敏感数据要求。
+- `docs/PROJECT_STATE.md`：当前真实能力、限制和已验证状态。
+- `docs/DECISIONS.md`：已经确定的安全、数据契约和导出设计取舍。
+- `ARCHITECTURE.md`：模块边界和数据流。
+- `SECURITY.md`：隐私、云端 AI、日志和本地服务边界。
+- `docs/DATA_CONTRACT.md`：下游使用的消息契约。
+
+## 3. 不可违反的边界
+
+- 只能处理用户本人拥有或明确获授权的数据。
+- 不读取、提交、打印或上传真实数据库、密钥、令牌、完整本地路径、账号标识、真实聊天内容或真实导出文件。
+- 不重置、清理、覆盖或回滚维护者已有的工作区修改。
+- 不使用未经确认的全盘扫描、无界媒体扫描或无界网络请求作为默认流程。
+- 不用未经验证的 local ID 单独关联媒体；local ID 可能在分片或会话之间重复。
+- 不把远程 URL 当作本地图片已经成功显示的证明。
+- 不把“AI 分析完成”表述为法律意见、事实认定或安全保证。
+- 不新增个人微信自动发消息、拉群、群管理或未验证的客户端自动化能力。
+- 不将写操作、云端分析、发布或配置修改加入默认只读 MCP 工具。
+- 不运行 `npm audit fix --force`，除非维护者另行安排独立升级和完整验证。
+
+## 4. P0：聊天导出施工顺序
+
+### 4.1 先建立可观察的导出结果
+
+检查 `scripts/export_chat_html.py` 和 `src/services/exportService.ts`，确保导出结果能够区分：
+
+- 消息总数；
+- 图片/表情/转发卡片消息数；
+- 本地缓存命中数；
+- 远程资源成功数；
+- 无法可靠匹配而显示占位的数量；
+- 链接保留数量；
+- 是否因为超时、数据库错误或环境缺少依赖而降级。
+
+统计可以写入终端或机器可读结果，但必须只输出计数、状态和脱敏错误码。不要输出消息正文、图片内容、密钥、路径或账号标识。
+
+### 4.2 修复消息类型判断
+
+微信可能把图片或转发文章存成带高位编码的扩展类型。处理时：
+
+1. 保留原始类型值用于判断其是否为编码扩展类型。
+2. 使用规范化类型决定通用渲染类别。
+3. 对带 `title`、`url`、`type` 等 appmsg 元数据的消息，优先进入卡片渲染分支。
+4. 对同时拥有本地缩略图和文章元数据的消息，同时渲染图片和链接。
+5. 没有可靠媒体时仍保留标题、描述或原始链接，不把它变成空白气泡。
+
+任何新增分支都必须测试普通图片、表情、普通链接、转发文章、高位编码转发文章和缺失媒体。
+
+### 4.3 设计媒体匹配优先级
+
+建议按下列顺序匹配，并在代码和测试中保持一致：
+
+1. 资源库提供的非零 server message ID 到媒体 MD5 映射。
+2. 当前会话缓存中的 `local_id + timestamp` 精确组合。
+3. 当前会话中某个 local ID 只有唯一媒体候选时的保守兜底。
+4. 消息内容或文件名明确携带的媒体 MD5。
+5. 已验证的本地 V2 媒体解码路径。
+6. 消息自带的远程缩略图或 CDN 地址。
+
+以下情况必须拒绝匹配：
+
+- server ID 为零且没有其他可靠身份；
+- local ID 对应多个不同媒体；
+- 候选只来自其他会话目录；
+- 只有时间相近但没有消息身份；
+- 文件不是通过真实图片签名验证的图片。
+
+### 4.4 控制远程资源
+
+远程封面和表情只能作为补充。为单次导出设置请求超时、重试次数、总时间预算、响应大小上限和允许的协议/主机范围。预算耗尽后立即保留本地内容和链接，不得让整个导出失败或长时间挂起。
+
+优先顺序必须是：先读取当前会话本地缓存，再尝试账号媒体兜底，最后才访问远程地址。账号级扫描应有明确上限，并且不得把扫描到的无身份媒体直接绑定到消息。
+
+## 5. P1：数据底座施工
+
+在 P0 的导出结果稳定后，再处理数据接口：
+
+1. 检查 `docs/DATA_CONTRACT.md`、`src/services/messageContract.ts` 和 MCP 的消息工具是否语义一致。
+2. 补充媒体状态、来源、缺失原因和覆盖统计时，保持 `weflow-message/v1` 向后兼容。
+3. 新增字段必须允许缺失；未知消息类型必须原样保留或以明确的 unknown 类型返回。
+4. 日期范围、分页、数量上限和 `mayHaveMore` 语义必须在 CLI JSON 与 MCP 中一致。
+5. MCP 仍保持默认只读，不传递数据库路径、密钥、任意文件内容或无界聊天记录。
+6. 为合作项目提供合成数据示例，禁止把真实聊天记录当 fixture。
+
+## 6. P2：日报和阅读器施工
+
+只有在导出和契约没有回归后才进入日报工作：
+
+- 保持来源级分类优先；已有公众号类别时不重复进行文章主题分类。
+- `daily --no-ai` 必须不调用 AI，但仍能抓取、生成 HTML、写入本地索引和补齐必要的前一日报告。
+- 日报抓取需要去重、有限重试、失败状态和可重跑能力。
+- 阅读器继续只监听回环地址，读写接口保留路径校验和来源校验。
+- 定时任务必须能报告成功、失败或跳过，不能静默重复启动阅读器。
+
+## 7. P3：受控 AI 施工
+
+AI 功能必须满足以下顺序：
+
+1. 用户明确选择数据范围。
+2. 执行前提供预览，说明是否联网、使用哪个模型、输入规模和可能成本。
+3. 严格模式下过滤第三方聊天内容和常见个人信息。
+4. 本地模型优先作为可选路径；关闭 AI 后基础查询、导出和日报仍可用。
+5. 输出保留来源和引用；法律相关功能只能整理线索、时间线和材料清单，不得宣称法律结论。
+6. 云端调用和本地写入均要有可审计的脱敏状态，不记录原文和密钥。
+
+## 8. 必须补齐的测试
+
+### Python 导出测试
+
+至少覆盖：
+
+- 普通图片按精确会话缓存命中；
+- 同一 local ID 对应不同图片时拒绝唯一兜底；
+- 高位编码图片类型可以显示本地图片；
+- 高位编码转发文章同时显示图片、标题和链接；
+- 普通 appmsg 链接保留标题、描述和 URL；
+- 资源库 server ID 映射只接受非零且匹配的消息；
+- 缺失媒体时显示可读占位而不是错误图片；
+- 远程请求预算耗尽后本地媒体仍能导出；
+- 非图片文件不会生成 `<img>`；
+- 账号目录中的无关图片不会被绑定到当前会话。
+
+### TypeScript 回归
+
+涉及服务、CLI、MCP、配置或路径时，运行：
+
+```powershell
+npm run build
+npm test
+```
+
+### 脱敏本机验收
+
+在用户授权的本机环境运行完整导出后，只记录下列信息：
+
+- 导出是否成功；
+- 消息总数；
+- 图片/表情/链接命中数；
+- 占位数量；
+- 是否发生超时或降级。
+
+打开 HTML 人工抽查至少三类内容：普通图片、转发文章、无法恢复媒体的消息。抽查结果不得复制聊天文字或上传截图。
+
+## 9. 推荐验证命令
+
+开发源码布局：
+
+```powershell
+npm run build
+npm test
+python -m unittest discover -s test -p '*_test.py' -v
+git diff --check
+```
+
+导出真实数据时，使用用户已确认的会话选择方式和当前项目的 CLI，不要把密钥或数据库参数写进命令行。优先使用日期范围或单个会话进行验证，避免无边界导出。
+
+编译布局也必须验证资源解析：
+
+```powershell
+node cli.cjs capabilities --json
+node cli.cjs check --json
+node cli.cjs export <已授权会话> html --json
+```
+
+命令中的尖括号内容只表示本机交互时替换的占位符，不得写入文档、日志或提交记录。
+
+## 10. 施工完成标准
+
+DeepSeek V4 Flash 只有在以下条件全部满足时才能报告完成：
+
+- 改动前后工作区差异清晰，未覆盖维护者已有修改。
+- `npm run build` 通过。
+- `npm test` 全部通过。
+- Python 导出专项测试全部通过。
+- `git diff --check` 通过。
+- 至少一次脱敏本机导出证明图片和转发链接的实际渲染结果。
+- 导出统计能解释成功、缺失、降级和超时情况。
+- 文档已同步：需要时更新 `PROJECT_STATE.md`、`DECISIONS.md`、`CHANGELOG.md` 和相关契约文档。
+- 检查差异中没有真实隐私数据、密钥、令牌、账号标识、数据库、日志或导出文件。
+
+如果真实环境仍无法可靠关联某类媒体，应明确报告“无法验证”及阻断原因，保留安全占位，不得把推测结果写成修复完成。
+
+## 11. 提交规则
+
+施工 Agent 默认只修改代码、测试和必要文档，不自动提交或推送。提交前输出：
+
+1. 改动文件清单；
+2. 每个改动的目的；
+3. 测试命令和结果；
+4. 仍存在的限制；
+5. 敏感信息检查结果。
+
+提交信息应简短、准确、说明用户可见结果，例如：
+
+```text
+fix: preserve encoded forwarded media links in HTML export
+```
+
+不得在提交信息、Issue、PR 或公开文档中写入真实本地数据和调试输出。

package/docs/EVIDENCE_GUIDE.md

@@ -0,0 +1,96 @@
+# 电子数据证据指南
+
+> 本文是软件使用和证据保全说明，不是法律意见。不同案件、诉讼程序和地区的判断可能不同；准备提交前应咨询律师或向有权处理案件的机构核验。
+
+## 1. 项目能做什么
+
+WeFlow CLI 可以在用户本人设备上，对用户本人有权访问的本地聊天数据进行：
+
+- 按会话提取消息及其本地消息 ID、时间、发送方和消息类型。
+- 保存一份只读意义上的原始提取副本。
+- 计算 `SHA-256`，便于发现保全包生成后是否被改动。
+- 记录提取时间、数据范围、消息数量和用户授权声明。
+- 生成保全说明，提示保留原设备、原数据库、官方导出记录和完整上下文。
+
+工具不判断“这条消息一定有法律效力”，不替代公证、司法鉴定、律师意见或法院对证据的审查，也不应修改、补写或伪造消息。
+
+## 2. 中国大陆民事证据规则的基本框架
+
+根据《中华人民共和国民事诉讼法》关于电子数据的证据类型，以及最高人民法院《民事诉讼证据的若干规定》（法释〔2019〕19号）关于电子数据的规定，聊天记录、短信、电子邮件、即时通信、通信群组信息、登录和身份认证信息、电子交易记录，以及保存在终端设备中的文字、图片、音视频等，可能属于电子数据。
+
+能否被采信通常要结合案件审查，不能只看文件后缀或是否有截图。实际重点通常包括：
+
+1. **真实性**：是否确实来自相关账号、设备、平台或生成环境；账号由谁控制，消息是否可能被冒用。
+2. **完整性**：是否有连续上下文，是否存在删改、截取、拼接、转换或缺页。
+3. **关联性**：是否能证明争议事实，时间、人物、金额、承诺和事件之间是否对应。
+4. **合法来源**：取得和保存方式是否侵犯他人隐私、商业秘密或其他合法权益，是否违反程序要求。
+5. **可核验性**：能否回到原设备、原应用、原数据库、平台记录、备份或其他独立证据进行复核。
+
+电子数据由中立第三方平台保存、在正常业务活动中形成、由档案管理机构保存，或者与其他证据相互印证时，可能具有更强的证明力；这仍然不是自动采信。
+
+## 3. 哪些材料通常更有帮助
+
+以下材料应尽量组合保存，而不是只提交其中一张截图：
+
+- 原设备、原微信账号、原始数据库或官方备份/迁移记录。
+- 连续、完整的聊天上下文，包括会话名称、参与者、时间、前后消息和附件关系。
+- 可回溯的消息 ID、原始文件、导出时间、工具版本和操作记录。
+- 原始媒体文件及其文件哈希，不要只保存压缩后的截图。
+- 对方身份、账号归属、联系方式和实际履行情况等独立佐证。
+- 转账、订单、合同、邮件、物流、通话记录等与聊天内容相互印证的材料。
+- 必要时由公证、司法鉴定、平台出具记录或其他有权机构进行进一步固定和核验。
+
+截图可以帮助阅读和定位，但单独的截图通常难以证明完整来源和未被编辑。AI 摘要、主题分类、情绪判断和“法律证据提取结果”只能作为整理线索，不能当作原始证据。
+
+## 4. 使用证据保全命令
+
+先完成初始化，然后针对明确会话创建本地证据包：
+
+```powershell
+weflow-cli evidence "联系人或群聊" --output "./output/evidence" --case "争议事项说明"
+```
+
+证据包包括：
+
+- `messages.json`：从本地数据提取的消息副本。
+- `manifest.json`：消息数量、时间范围、消息 ID、生成时间和 SHA-256。
+- `README.md`：保全边界和后续建议。
+
+建议创建后立即：
+
+1. 记录谁在什么设备、什么时间、用什么版本创建了保全包。
+2. 保留原设备和原始数据库，不在原文件上编辑或覆盖。
+3. 只对副本做脱敏、标注、摘要和分析，并分别计算处理前后的哈希。
+4. 保留完整上下文，不要只导出对自己有利的片段。
+5. 限制证据包访问权限，不通过公开 Issue、网盘链接或未经审查的 MCP 发送。
+6. 交由律师、公证机构、司法鉴定机构或办案机构判断下一步固定方式。
+
+哈希只能证明某个文件在两个时间点之间是否发生变化，不能单独证明文件内容真实、账号属于谁、消息没有在更早之前被修改，也不能证明法院一定采信。
+
+## 5. AI 线索分析（可选）
+
+如果需要让 AI 帮助浏览某个会话，可以使用：
+
+```powershell
+weflow-cli evidence-review "联系人或群聊" --output "./output/evidence-review"
+```
+
+该命令只生成“疑似争议线索、待核验法律主题、材料缺口和保全建议”，要求每项尽量引用消息 ID；它不认定违法、不判断证据必然有效，也不替代律师、鉴定、公证或法院审查。
+
+- 默认拒绝把聊天正文发送到云端；建议配置 Ollama 或 LM Studio，在本机完成分析。
+- 只有明确确认后才使用 `--allow-cloud`；云端仍受 `assistantPrivacy` 隐私模式约束，`strict` 模式会屏蔽第三方聊天正文。
+- AI 输出只能作为整理线索，必须回看 `messages.json`、原设备和完整上下文，不得把 AI 生成内容当作原始证据。
+
+## 6. 隐私和授权边界
+
+本功能仅限用户本人设备和本人有权访问的数据。不得用它监控配偶、员工或其他第三方，不得在未获授权的设备上提取数据。聊天记录通常包含第三方个人信息，向律师、机构或云端服务提供前应先确认必要性、授权范围和脱敏方案。
+
+WeFlow CLI 默认在本机生成证据包，不会自动上传。使用云端 AI 分析时，证据原文可能离开本机，必须由用户单独确认；证据保全本身不需要调用 AI。
+
+## 7. 参考依据
+
+- 《中华人民共和国民事诉讼法》：国家法律法规数据库 https://flk.npc.gov.cn/
+- 《最高人民法院关于民事诉讼证据的若干规定》（法释〔2019〕19号）：最高人民法院 https://www.court.gov.cn/
+- 最高人民法院司法解释和诉讼指南：最高人民法院 https://www.court.gov.cn/
+
+官方条文、司法解释和案件规则可能更新。使用前应在国家法律法规数据库、最高人民法院官网或当地有权机构核对最新文本。

package/docs/MCP.md

@@ -0,0 +1,95 @@
+# MCP Integration
+
+## Read-only message export
+
+The local stdio MCP server provides `wechat.export_messages` for downstream projects that need the same versioned message contract as the CLI export.
+
+Example input:
+
+```json
+{
+  "contact": "wxid_example",
+  "limit": 100,
+  "from": "YYYY-MM-DD",
+  "to": "YYYY-MM-DD"
+}
+```
+
+The tool returns a JSON string with `schema: "weflow-message/v1"` and `coverage` metadata for the requested range, returned count, conservative `mayHaveMore` status, and returned time bounds. `limit` defaults to 100 and is capped at 1000. `from` and `to` are inclusive local dates. Use a session ID when a display name is ambiguous.
+
+This tool is read-only. It does not expose database paths, keys, configuration, or unrestricted filesystem access, and it does not invoke AI. Unknown WeChat message codes remain in the output with their original `localType` and `messageType: "other"`.
+
+WeFlow CLI exposes article, knowledge-base, and selected local-data functions through an MCP server over stdio. The server reads the project's local `output/` directory and only contacts external services when a requested tool requires it. The available inventory follows `mcp-server/index.ts`; do not hard-code a tool count in client documentation.
+
+External article fetching accepts only credential-free HTTPS URLs on the exact `mp.weixin.qq.com` host. Redirects must remain on that host and all network reads have finite timeout, redirect, result-count, and response-size limits.
+
+## Configure a client
+
+From the project root, generate the baseline configuration:
+
+```powershell
+weflow-cli mcp-config --output .mcp.json --dry-run --json-result
+weflow-cli mcp-config --output .mcp.json --yes
+```
+
+Without `--output`, `weflow-cli mcp-config` remains a read-only command that prints the configuration to stdout.
+
+The generated server starts with Node.js and `tsx`:
+
+```json
+{
+  "mcpServers": {
+    "weflow": {
+      "command": "npx",
+      "args": ["tsx", "mcp-server/index.ts"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+Copy this entry into your MCP client's configuration and ensure `cwd` points to the cloned WeFlow CLI directory. Restart the client after saving the configuration.
+
+## Available tools
+
+| Tool | Purpose | Local data required |
+| --- | --- | --- |
+| `wechat.search_articles` | Search captured official-account articles. | `output/biz-daily/` |
+| `wechat.get_daily` | Read a daily article collection. | `output/biz-daily/` |
+| `wechat.get_review` | Read an AI learning review. | `output/reviews/Daily/` |
+| `wechat.get_stats` | Show article, knowledge-base, and local WeChat data statistics. | Generated output |
+| `wechat.get_concepts` | List compiled concepts. | Vault Wiki output |
+| `wechat.get_concept` | Read one compiled concept. | Vault Wiki output |
+| `wechat.format_article` | Convert Markdown to WeChat-ready HTML. | None |
+| `wechat.list_themes` | List available article themes. | None |
+| `wechat.fetch_article` | Fetch and convert a public WeChat article. | Network access |
+| `wechat.search_public` | Search public WeChat articles. | Network access |
+| `wechat.list_sessions` | List recent chat sessions with last-message snippets. | Decrypted WeChat database |
+| `wechat.get_messages` | Read recent messages with one contact. | Decrypted WeChat database |
+| `wechat.search_favorites` | Search WeChat favorites (official-account articles, notes, links). | Decrypted WeChat database |
+| `wechat.read_favorite` | Fetch and read the body of a favorited article. | Decrypted WeChat database, network access |
+| `wechat.get_daily_report` | Filter daily reports by topic/keyword with AI summaries. | `output/biz-daily/` |
+| `wechat.get_sns` | Read the Moments timeline or statistics. | Decrypted WeChat database |
+| `wechat.get_weread` | Read WeRead shelf, notebooks, or search books. | `wereadApiKey` config |
+| `wechat.get_todos` | List todos extracted from chat history. | `scripts/extract_todos.py`, Python |
+| `wechat.search_knowledge` | Fuzzy-search concept pages in the knowledge base. | Vault Wiki output |
+| `wechat.search_memory` | Search long-term assistant memory. | `~/.weflow-cli/assistant_memory.json` |
+
+The chat-data tools share service code with the optional `weflow-cli assistant` WeChat bot, but access is still controlled by the MCP client's permissions and local configuration. The bot and MCP transport are not interchangeable message channels.
+
+## Safety boundary
+
+- The server inherits the permissions of the MCP client. Only add it to a client you trust.
+- Article and knowledge-base tools read files under the current project directory. Keep `cwd` scoped to your intended WeFlow CLI checkout.
+- Chat-data tools (`list_sessions`, `get_messages`, `search_favorites`, `get_sns`, `get_todos`) read your locally decrypted WeChat database. Only run this MCP server on machines where that is acceptable, and never expose the stdio server over a network.
+- `read_favorite`, `fetch_article`, and `search_public` make network requests; `read_favorite` rejects private/loopback URLs.
+- The default MCP surface is read-only. It does not publish drafts, save assistant memory, send messages, mutate todos, or change configuration. Side effects remain in explicit CLI or assistant workflows with their own confirmation boundary.
+- Do not place API keys in `.mcp.json`. Use environment variables where a client supports them.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Server fails to start | Run `npm install` in the configured `cwd`, then run `npx tsx mcp-server/index.ts`. |
+| No articles found | Generate a daily collection first, then confirm `output/biz-daily/` exists under `cwd`. |
+| Client cannot find `npx` | Configure an absolute Node.js command path or install Node.js 18+. |

package/docs/PARTNERS.md

@@ -0,0 +1,41 @@
+# 合作伙伴记录
+
+> 本文档记录 WeFlow CLI 与外部项目之间的技术协作边界。这里只记录公开的项目事实、接口约定和工程改进，不记录任何用户数据。
+
+## she-love-me
+
+### 感谢
+
+感谢 `she-love-me` 项目采用 WeFlow CLI 作为本地微信数据来源，并围绕真实使用场景反馈兼容性需求。对方的接入需求帮助我们发现：如果希望支持更多下游应用，数据导出格式、字段含义和版本兼容规则必须明确记录，而不能只依赖当前实现。
+
+### 我们完成的改进
+
+- 保留原有 `weflow-cli export <contact> json` 调用方式，避免影响已有使用者。
+- 新增可选的 `weflow-message/v1` 版本化 JSON 契约，为下游应用提供稳定的消息结构。
+- 增加 `messageType` 标准化字段，覆盖常见文本、图片、语音、视频、表情、链接等类型。
+- 对未知消息类型保留原始 `localType` 和原始字段，并归类为 `other`，避免因类型不认识而丢失消息。
+- 新增只读 MCP 工具 `wechat.export_messages`，支持会话、日期范围和数量限制。
+- MCP 默认限制返回数量，不暴露数据库路径、密钥、配置或任意文件系统访问，也不隐式调用 AI。
+- 将接口语义和隐私边界记录在 [DATA_CONTRACT.md](DATA_CONTRACT.md) 与 [MCP.md](MCP.md) 中，并加入构建和回归测试。
+
+### 合作边界
+
+`she-love-me` 是独立的外部项目，WeFlow CLI 只提供通用的本地只读数据接口，不直接维护对方的业务代码或内部数据转换逻辑。下游项目应自行完成：
+
+- 将公共消息契约转换为自身的业务模型；
+- 处理未知消息类型、缺失发送者和媒体不可用等情况；
+- 将导出数据和分析结果保存在用户本地；
+- 在把用户选择的数据发送到云端模型前取得明确授权并进行隐私处理。
+
+WeFlow CLI 不接收或提交真实微信数据库、密钥、聊天记录、账号标识、日志或其他个人信息作为合作材料。
+
+### 当前状态
+
+- 数据接口：`export ... json --contract weflow-v1` 已实现。
+- MCP 接口：`wechat.export_messages` 已实现为本地 stdio 只读工具。
+- 验证：TypeScript 构建和现有回归测试通过。
+- 兼容性：已规范化常见消息类型，但不宣称覆盖所有微信未来格式；未知类型必须由下游安全保留和降级处理。
+
+### 后续协作方式
+
+后续如需扩展接口，优先通过公开的字段契约、合成 fixtures、最小复现和版本化变更进行协作。涉及真实用户数据、云端 AI、写入操作、消息发送或平台自动化的需求，必须单独进行隐私和安全评审。

package/docs/PROJECT_STATE.md

@@ -0,0 +1,96 @@
+# Project State
+
+> Last reviewed: 2026-09-08. This is the current maintenance snapshot, not a release note. Keep it factual and update it with meaningful project changes.
+
+## Purpose
+
+WeFlow CLI is a local-first command-line tool and MCP server for user-authorized WeChat data workflows: local chat queries and exports, official-account daily reading, favorites, knowledge workflows, and an optional local assistant.
+
+## Current Baseline
+
+- Source package version: `1.5.1`. The npm registry may remain on an earlier version until a maintainer publishes a release.
+- Runtime: Node.js 18+; Python 3.10+ is required for database and daily-reading workflows.
+- Main development command: `npm run dev -- <command>`.
+- Compiled/package command: `node cli.cjs <command>`; CLI, MCP, database, export, and assistant services resolve resources from the same package root in both source and compiled layouts.
+- Build check: `npm run build`.
+- Regression check: `npm test`.
+- Downstream data contract: local JSON export is the first compatibility boundary for `she-love-me` and future consumers; see `docs/DATA_CONTRACT.md`.
+- Supported focus: Windows WeChat 4.x; Linux WeChat 4.x has an NT database path; macOS requires user-provided local access credentials for initialization.
+
+## Verified Capabilities
+
+| Area | Current state | Main entry points |
+| --- | --- | --- |
+| Local chat data | Query sessions, contacts, messages, favorites, Moments cache, and exports. HTML chat exports decode NT compressed media records, locally cached WeChat 4.x V2 image containers, entity-escaped emoji XML, and remote emoticons; app cards preserve links and embed available公众号/Bilibili covers. Media matching prefers server-message resources, exact local-message-ID plus timestamp pairs, and a unique local-ID fallback; high-bit encoded image rows are resolved through the same conversation cache. | `sessions`, `contacts`, `messages`, `export`, `fav`, `sns` |
+| 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` |
+| 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 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.
+
+## Security Baseline
+
+- Process only data the user owns or is explicitly authorized to access.
+- Sensitive configuration fields are encrypted at rest with machine- and user-bound AES-256-GCM.
+- The daily reader binds to `127.0.0.1`; its API rejects cross-origin mutations, validates local paths, and restricts image proxy requests.
+- The assistant denies all senders until `assistantWhitelist` is explicitly configured. Group routing is experimental and remains denied unless the upstream explicitly supplies group metadata, the group and sender are both allowlisted, and the bot is mentioned. New or incomplete configurations use `strict` privacy mode for cloud inference.
+- MCP path inputs are constrained to their expected data roots. MCP clients remain trusted local integrations and must be reviewed before configuration.
+- The default MCP tool list is read-only: it excludes publishing, messaging, assistant-memory writes, todo mutation, configuration changes, and deletion. Conversation display names must resolve uniquely before chat data is read.
+- Public reports and commits must not contain databases, keys, tokens, wxid values, real chat content, or unredacted logs.
+- Todo status changes and deletion use a preview/confirm protocol. Machine callers receive `CONFIRMATION_REQUIRED` unless the user-approved execution includes `--yes`.
+- AI and database credentials, selected-conversation identifiers, private queries and filters, export locations and display names, and NT scan roots are inherited by workers through environment variables and are not copied into child-process command arguments. Long-lived worker environments clear unrelated internal values before startup.
+- `config set-env` and `fav set-key --from-env` provide command-history-safe secret input. Their JSON workflows require a read-only preview followed by explicit `--yes`, and never return secret values or discovered database paths. Bulk clearing of configuration, access lists, or audit history requires interactive confirmation or explicit `--yes`.
+- Core JSON reads validate pagination before database access. `messages --start/--end` now applies its Unix-second time range before offset and limit instead of silently ignoring the options.
+- `scan --json` and `assistant log --json` return metadata only. They intentionally omit local paths, account identifiers, nicknames, and log content. `evidence-review` requires preview and confirmation, and its machine result omits both analysis text and the output path.
+- `init --dry-run --json` exposes a content-free plan. JSON execution returns `INTERACTIVE_REQUIRED`; database verification, directory discovery, key capture, and configuration writes remain an explicit terminal workflow.
+- `vault rag` requires a read-only preview and explicit confirmation before reading local knowledge or calling the configured AI provider. The question is inherited by the Python worker through the environment rather than copied into process arguments.
+- `search` and `chat` use the same preview/confirmation boundary. Queries, questions, and optional conversation restrictions are inherited through the worker environment instead of appearing in process arguments; machine callers cannot start interactive RAG chat.
+- `daily-server --status --json` remains read-only. Machine startup uses `daily-server --dry-run --json` followed by `daily-server --yes --json`; the confirmed process is detached and remains bound to loopback. The legacy `fav-server` compatibility entry enforces the same preview and confirmation rules.
+
+Documentation was synchronized with the `1.5.1` source baseline on 2026-09-09. Command behavior is defined by `bin/weflow-cli.ts`; detached reader startup waits for service readiness, and release packages can lag behind the GitHub source until published.
+
+## Active Constraints
+
+- Issue #7 remains open pending reporter verification. HTML emoji export preserves the emoji label and matches resource records only by nonzero server-message identity; local IDs are not unique across shards or conversations. WeChat 4.x V2 image containers are decoded with an account-specific media key derived from local `kvcomm` data and verified against a real cached V2 header. Remote emoticons use AES-CBC with the message key as both key and IV. Entity-escaped emoji XML is normalized before extracting MD5 and media URLs; failed encrypted downloads fall back across available thumbnail/CDN fields. Signature-only default `[打脸]` messages use the bundled official Facepalm asset when no message-specific resource is available. Forwarded app cards remain structured links with available covers, and Bilibili share pages can resolve covers through their BV metadata endpoint when no `og:image` is present. Thirteen synthetic Python regression tests cover these paths; run `python -m unittest discover -s test -p '*_test.py' -v`. CI also runs these tests. This does not establish compatibility with every real WeChat media format.
+
+- WeChat platform behavior, database formats, account restrictions, and terms can change without notice. Local operation is not a legal, account-safety, or platform-compatibility guarantee.
+- The daily workflow can take substantial time when many configured sources publish on the same day. It fetches article bodies sequentially to reduce upstream pressure.
+- The OC Bot channel is separate from a personal WeChat message stream. `send` can only reply through an already established Bot-channel conversation with a valid context token; it cannot initiate messages to existing personal contacts, post as the user's personal account, or send into ordinary personal WeChat groups.
+- The current official OC/iLink payload model has not been verified to support group events or group invitations. The project does not implement client automation or protocol bypasses to add a bot to groups.
+- Cloud AI workflows may transmit user-selected, privacy-filtered input to the configured provider. Local inference avoids that network transfer.
+- `vault promote ideas` and `vault promote all` run without AI by default. AI generation requires explicit `--with-ai` and an API key. CLI execution also requires preview and confirmation. `vault init` creates both the existing article-sync folders and the structured directories required by promotion workflows.
+- `vault init`, semantic-index construction, the knowledge pipeline, and report generators require preview and confirmation for machine execution. Preview JSON contains counts and behavior flags but omits local paths, conversation names, and generated content.
+- Automatic data-directory discovery checks common user locations only. Cross-drive name search requires `init --search-drives`; structural disk search requires `init --full-scan`. Both can be slow on large, removable, or network-attached volumes.
+- Dependency audit findings must be reviewed before dependency upgrades; do not run breaking `npm audit fix --force` without validation.
+- The WCDB native query entry point has no parameter-binding ABI. Calls that supply parameters are rejected rather than falling back to interpolated SQL; existing internal callers are unchanged.
+
+## Current Priorities
+
+1. Keep initialization and database access compatible with supported WeChat 4.x variants, with reproducible issue diagnostics that contain no secrets.
+2. Keep the daily reader reliable for configured sources and categories without widening access to local data.
+3. Maintain security boundaries around local servers, assistant access, MCP tools, and cloud AI disclosure.
+4. Evaluate external collaboration through read-only, synthetic-data, versioned interfaces before connecting real user data.
+5. Make Bot-channel send capability and its limitations unambiguous in CLI naming and help text before extending messaging features.
+
+## External Collaboration Position
+
+For projects such as Yance, WeFlow CLI remains an independent local data-access layer. Early collaboration may cover read-only schemas, anonymized fixtures, and controlled MCP adapters. It must not require sharing real databases, credentials, keys, full local directories, or direct database access by an external product.
+
+## Related Documents
+
+- Architecture and data flow: [ARCHITECTURE.md](../ARCHITECTURE.md)
+- Setup and troubleshooting: [OPERATIONS.md](../OPERATIONS.md)
+- Security and reporting: [SECURITY.md](../SECURITY.md)
+- MCP surface: [MCP.md](MCP.md)
+- Design rationale: [DECISIONS.md](DECISIONS.md)
+- Partner integration record: [PARTNERS.md](PARTNERS.md)
+- AI integration surface: [AI_INTERFACE.md](AI_INTERFACE.md)
+- Overall improvement and expansion plan: [ROADMAP.md](ROADMAP.md)
+- DeepSeek V4 Flash施工文档: [DEEPSEEK_V4_FLASH施工文档.md](DEEPSEEK_V4_FLASH施工文档.md)
+- User-visible releases: [CHANGELOG.md](../CHANGELOG.md)