weflow-cli 1.7.0 → 1.8.0

package/README.en.md

@@ -11,7 +11,7 @@
 > Bring your chat history, official-account reading, and personal knowledge workflows back to your own computer.
 
 [![npm](https://img.shields.io/npm/v/weflow-cli)](https://www.npmjs.com/package/weflow-cli)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22.13%2B-339933)](https://nodejs.org/)
 [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB)](https://www.python.org/)
 [![WeChat](https://img.shields.io/badge/WeChat-4.x%20tested-07C160?logo=wechat&logoColor=white)](https://github.com/zhuobichen/weflow-cli/releases)
 [![Local-first](https://img.shields.io/badge/local--first-zero%20telemetry-8A2BE2)](./SECURITY.md)
@@ -52,7 +52,7 @@ $ weflow-cli fav list -n 3
 ```text
 weflow-cli sessions                    # list chat sessions
 weflow-cli messages "contact" -n 20    # query chat messages
-weflow-cli export "contact" html       # export HTML / Excel / Markdown / JSON
+weflow-cli export "contact" html       # export HTML / Excel / TXT / JSON
 weflow-cli fav list -t article -k AI   # favorites: type filter + keyword search
 weflow-cli daily --date 2026-08-21     # official-account digest + AI summary
 weflow-cli daily-server                # local reader http://localhost:8765
@@ -60,11 +60,39 @@ weflow-cli chat "How does RAG work?"   # knowledge-base RAG Q&A
 weflow-cli mcp-config                  # one-shot MCP client integration
 ```
 
+## Platform Support
+
+| Capability | Windows | macOS | Linux |
+| --- | --- | --- | --- |
+| Data-directory discovery | ✅ | ✅ | ✅ |
+| Local data initialization | ✅ auto-discover/verify | ❌ credentials must be supplied manually | ⚠️ depends on distro and permissions |
+| Chat history query (NT / local databases) | ✅ | ✅ | ✅ |
+| WCDB data service (contact nicknames, etc.) | ✅ | ⚠️ needs the native library | ⚠️ needs the native library |
+| Official-account digest / knowledge base / MCP | ✅ | ✅ | ✅ |
+
+macOS: there is no automatic initialization today. If you already have local data access through official or otherwise authorized means, follow the help of `weflow-cli init --path` and `config` to finish setup.
+
+### Linux Quick Start (native WeChat 4.x for Linux)
+
+```bash
+# 1. sqlcipher development libraries (needed to build sqlcipher3)
+sudo apt install libsqlcipher-dev
+
+# 2. Python dependencies
+pip3 install --user sqlcipher3 cryptography html2text zstandard
+
+# 3. Install the CLI and initialize
+npm install -g weflow-cli
+weflow-cli init    # follow the prompts
+```
+
+Automatic initialization on Linux depends on the WeChat distribution, the Python dependencies, and your user's permissions. Run `weflow-cli check` first and configure within your system's security policy; do not lower machine-wide permissions just to troubleshoot.
+
 ## What You Can Do
 
 | Scenario | Capability |
 | --- | --- |
-| Chat history | Query sessions, contacts, and messages; export to JSON, TXT, Markdown, HTML, Excel. |
+| Chat history | Query sessions, contacts, and messages; export to JSON, TXT, HTML, Excel. An HTML export also writes a media coverage report saying which images and stickers could not be embedded, and why. |
 | Official-account digest | Crawl articles, AI summarization and classification, generate a local reading page, keep favorites and read states. |
 | Personal knowledge base | Sync WeRead notes, build an Obsidian vault, semantic search, RAG Q&A, and a concept wiki. |
 | AI collaboration | Expose article crawling, knowledge-base retrieval, digests, and selected local-data tools to MCP-compatible clients. The inventory follows the current code and `docs/MCP.md`. |
@@ -78,6 +106,8 @@ weflow-cli mcp-config                  # one-shot MCP client integration
 
 ### 1. Install and Check
 
+> npm packages and GitHub releases are published separately; if you need the newest fixes, check the npm package version first, or use the GitHub `master` branch directly.
+
 Requires Node.js 22.13+, Python 3.10+, and a signed-in Windows WeChat. After installation, check your environment first:
 
 ```powershell
@@ -138,6 +168,34 @@ weflow-cli daily --date 2026-08-12 --dry-run
 
 # Generate without any AI calls; fetching, HTML, and local indexes remain enabled
 weflow-cli daily --date 2026-08-12 --no-ai
+
+# Push and digest-processing frequency per official account over the last 30 days
+weflow-cli daily-stats --days 30 --limit 30
+
+# Only include the given official accounts (repeatable, or comma-separated)
+weflow-cli daily --source "AccountA" --source "AccountB"
+weflow-cli daily --source "AccountA,AccountB"
+
+# Persist digest sources; leave empty to restore "all accounts"
+weflow-cli config set dailySources "AccountA,AccountB"
+
+# Persist AI off for digests; set it back to true to re-enable
+weflow-cli config set dailyAiEnabled false
+weflow-cli config set dailyAiEnabled true
+
+# Topics kept out of the digest (a display-layer switch: they are still fetched and
+# archived, just not shown, so changing your mind needs no re-crawl). Focus topics
+# cannot be excluded, and unknown topic names are ignored with a WARN.
+weflow-cli config set dailyExcludeTopics "news,investing,academic"
+
+# Pin a category for a source; a categorized source gets a summary only, and its tags
+# come from the category you set rather than from the article.
+weflow-cli config set dailySourceCategories '<JSON: source name or gh_ ID -> category>'
+
+# Optional: decide article topic and relevance with TypeSafe's Jev decision model
+# instead of parsing it out of generated text. Without the key the previous
+# LLM-parse path is used unchanged.
+weflow-cli config set typesafeApiKey "..."
 ```
 
 The reader serves at `http://localhost:8765/` by default.
@@ -148,7 +206,7 @@ The reader serves at `http://localhost:8765/` by default.
 weflow-cli export "contact" json --contract weflow-v1 --output ./output
 ```
 
-The generated envelope keeps message fields stable and includes conservative `coverage` metadata. For incremental reads, use an overlapping `--from` time window and deduplicate locally by conversation plus `localId`/`serverId`; a stable cursor is not exposed yet. The legacy JSON export remains a top-level array.
+The generated envelope keeps message fields stable and includes conservative `coverage` metadata. For incremental reads, use an overlapping `--from` time window and deduplicate locally by conversation plus `localId`/`serverId`, or let `sync` keep the checkpoint and report what it covered. A stable cursor is still not exposed: it has to be backed by every database backend before it can be advertised. The legacy JSON export remains a top-level array.
 
 **Connect an AI editor**
 
@@ -158,7 +216,7 @@ weflow-cli mcp-config > .mcp.json
 
 Place the generated configuration wherever your MCP client expects it and restart the client. See `weflow-cli mcp-config` output for the tool list and configuration details.
 
-Beyond the knowledge-base tools, the MCP server also exposes selected local WeChat data capabilities (sessions, chat history, favorites, Moments, digests, WeRead, todos, knowledge base, and assistant memory). See the [MCP Integration Guide](./docs/MCP.md) for the current inventory and security boundaries.
+Beyond the knowledge-base tools, the MCP server also exposes selected local WeChat data capabilities (sessions, chat history, favorites, Moments, digests, WeRead, todos, knowledge base, and assistant memory). By default MCP sends no messages, publishes no articles, and modifies no todos, memory, or configuration. See the [MCP Integration Guide](./docs/MCP.md) for the current inventory and security boundaries.
 
 **Host a local AI assistant in WeChat (second brain)**
 
@@ -166,8 +224,13 @@ Beyond the knowledge-base tools, the MCP server also exposes selected local WeCh
 weflow-cli config set deepseekApiKey "sk-..."   # or any OpenAI-compatible endpoint: aiBaseUrl + aiModel
 weflow-cli login-wechat        # scan the QR code to bind the messaging channel (a ClawBot contact appears in WeChat)
 weflow-cli assistant start     # run the agent as a background daemon
+weflow-cli panel               # open the on-device panel window (usable without scanning a QR code)
 ```
 
+`weflow-cli panel` opens a small always-on window that talks to **the same brain as the WeChat side** — the same memory, the same daily quota. **No WeChat login is required**: the messaging channel is optional. The window is only a client; its messages go to the daemon's entry point on `127.0.0.1`, so the two entry points never keep separate copies of memory.
+
+The floating ball needs Electron (`npm i -g electron`); without it the panel degrades to an Edge/Chrome `--app` window — same UI, but no frameless always-on-top ball, no tray, no global shortcut. With the ball (a 96px mascot): **click it and the chat bubble opens beside it (the ball itself stays put; click again to collapse)**. The bubble opens to the left of the ball by default, flips to the right when there is no room on the left, and top-aligns when vertical space runs short; drag the ball to move it, and the position is remembered. The ball doubles as a status light — busy, offline, and quota-exhausted are three real states, each with its own face and glow colour, while an idle ball shows no glow at all. **Right-click anywhere in the panel** to draft a reply for someone on your list (`weflow-cli config set quickReplyContacts "Alice,Bob"` — a click sends that conversation to two cloud models and returns text only, never sending for you). The last item in that menu tucks the ball away; the tray icon brings it back.
+
 Then just talk to ClawBot on your phone. The assistant queries local chats and favorites to answer, with memory that survives across sessions:
 
 - "What have I been busy with lately?" — synthesizes recent sessions and messages
@@ -179,6 +242,7 @@ Then just talk to ClawBot on your phone. The assistant queries local chats and f
 - "What am I reading?" / "My notes on XX" — WeRead shelf and notebooks
 - "Any pending todos? Anything urgent?" — todo list sorted by urgency
 - "How does my knowledge base explain RAG?" — concept-wiki lookup
+- "Draft a reply to Lao Wang" — first judges what the other side wants, the risk, and whether substance should be given, then offers a few candidates. **Text only, never sent for you**; when money or high risk is involved it withholds drafts and only says what to confirm first
 - "Remember: my project is called weflow-cli" — writes to long-term memory
 
 How it works: the daemon long-polls WeChat's official bot channel (iLink); the agent loop, three-tier memory (working window / rolling summary / long-term facts), and all database queries run on your machine. Only the final question and reply texts go to the configured LLM; phone numbers, emails, and links in tool output are redacted by default (`config set assistantPrivacy strict` for stronger masking; a local `ollama` engine keeps everything offline). Sessions expire after 24h of inactivity, and proactive replies per window are capped by official limits.
@@ -189,6 +253,15 @@ Cost guardrails: a built-in daily cap of 100 processed messages (send "记忆" i
 weflow-cli config set assistantWhitelist "your-@im.wechat-ID"   # unset = deny everyone
 ```
 
+Group chat currently depends on whether WeChat's official bot channel actually delivers explicit group events; this project never joins groups through client automation or unofficial protocols. Should upstream ever provide group IDs, sender IDs, and @-mention fields, group messages still default to deny — you must set the group whitelist, keep the member whitelist, and leave the @ requirement on:
+
+```powershell
+weflow-cli config set assistantGroupWhitelist "group-id"
+weflow-cli config set assistantGroupRequireMention true
+```
+
+This only takes effect once the official channel really delivers group events; ClawBot direct messages are unaffected today.
+
 Management: `weflow-cli assistant status` / `log` / `stop`; send "帮助" in WeChat for in-chat commands.
 
 ## Common Commands
@@ -198,14 +271,19 @@ Management: `weflow-cli assistant status` / `log` / `stop`; send "帮助" in WeC
 | Check environment & config | `weflow-cli check` · `weflow-cli config show` |
 | Initialize or specify paths | `weflow-cli init [--path <dir>]` |
 | Browse chat data | `weflow-cli sessions` · `weflow-cli messages <contact>` · `weflow-cli contacts` |
-| Export chat history | `weflow-cli export <contact> <json\|txt\|md\|html\|excel>` |
+| Who is waiting on a reply | `weflow-cli awaiting --dry-run` · `weflow-cli awaiting --yes` |
+| Draft a reply (text only, never sent) | `weflow-cli draft <contact> --dry-run` · `--yes` |
+| Local judgement primitive | `weflow-cli decide --request <file> --dry-run` · `--yes` |
+| Export chat history | `weflow-cli export <contact> <json\|txt\|html\|excel>` |
+| Sync checkpoint | `weflow-cli sync run <contact> --since <date>` · `sync status` · `sync verify` |
 | Digest & reader | `weflow-cli daily` · `weflow-cli daily-server` · `weflow-cli review` |
 | Moments cache | `weflow-cli sns timeline` · `weflow-cli sns users` · `weflow-cli sns stats` |
 | WeChat favorites | `weflow-cli fav list` · `weflow-cli fav export markdown` · `weflow-cli fav set-key` |
 | WeRead | `weflow-cli weread shelf` · `notes` · `search` · `stats` |
-| Knowledge base | `weflow-cli vault` · `weflow-cli wiki` · `weflow-cli search <query>` · `weflow-cli chat` |
+| Knowledge base | `weflow-cli vault` · `weflow-cli wiki` · `weflow-cli search <query>` · `weflow-cli chat` (semantic search needs `config set dashscopeApiKey` first) |
 | Reports & tasks | `weflow-cli report` · `annual-report` · `todos` |
 | Second-brain assistant | `weflow-cli assistant start` · `status` · `log` · `stop` |
+| On-device panel | `weflow-cli panel` — floating window; `--status` reads state only, `--ask "…"` asks from the command line |
 | AI editor integration | `weflow-cli mcp-config` |
 
 Run `weflow-cli <command> --help` for the full options of any command. For example:
@@ -260,6 +338,9 @@ For a more complete view of modules and data flow, read [ARCHITECTURE.md](./ARCH
 - Network requests involving DeepSeek, article crawling, WeRead, or MCP happen only when you run the corresponding workflow.
 - Use `whitelist`, `blacklist`, and `audit` to manage or audit message sending; always confirm the target contact and content before sending.
 - After upgrading WeChat, switching accounts, or migrating computers, you may need to re-initialize or re-scan NT keys.
+- `init` validates existing local configuration first and does not re-capture keys when that validation passes. Use `weflow-cli init --refresh` only after a migration, an account switch, or an access failure.
+- To test a first-time initialization or a failed key, prefer `weflow-cli init --test-missing-keys`; it simulates missing keys for that run only and leaves the saved configuration untouched. When keys really have failed, `weflow-cli config forget-keys` clears the database access keys only and asks for confirmation.
+- Running `weflow-cli daily` without a date checks yesterday's artifacts first: if yesterday's `README.md`, article index, or `index.html` is missing, it backfills yesterday and only generates today once that succeeds. Passing `--date` or `--dry-run` skips the backfill.
 
 ## Documentation & Feedback
 
@@ -269,6 +350,11 @@ For a more complete view of modules and data flow, read [ARCHITECTURE.md](./ARCH
 - [Detailed Architecture](./ARCHITECTURE.md): modules, data flow, implementation boundaries.
 - [Project State](./docs/PROJECT_STATE.md): current capabilities, constraints, priorities, and handoff entry point.
 - [Technical Decisions](./docs/DECISIONS.md): durable design rationale for long-term maintenance.
+- [Extending Guide](./docs/EXTENDING.md): what to touch to add a tool, config key, command, MCP tool, or Python script — and which test will stop you. **There is no plugin loader today**; this document says why, and how to extend anyway.
+- [Branches & Merges](./docs/BRANCHES.md): branch purposes, merge timeline, and conventions for parallel work.
+- [Release Checklist](./docs/RELEASING.md): version numbers, packaging checks for sensitive content, npm credentials, and mirror sync.
+- [npm Publish FAQ](./docs/NPM-PUBLISH.md): whether 404 / 409 / ETARGET means failure or propagation — look it up by symptom.
+- [Scheduled Health Check](./docs/HEALTH-CHECK.md): one command for version drift, missed shards, stale sessions, and failed exports.
 - [Electronic Evidence Guide](./docs/EVIDENCE_GUIDE.md): preservation workflow, legal boundaries, and usage notes.
 - [Contributing Guide](./CONTRIBUTING.md) and [Security Policy](./SECURITY.md): development, feedback, and sensitive issues.
 - [Changelog](./CHANGELOG.md): release summaries.

package/README.md

@@ -11,7 +11,7 @@
 > 让聊天记录、公众号阅读和个人知识工作流回到你的本地电脑。
 
 [![npm](https://img.shields.io/npm/v/weflow-cli)](https://www.npmjs.com/package/weflow-cli)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22.13%2B-339933)](https://nodejs.org/)
 [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB)](https://www.python.org/)
 [![WeChat](https://img.shields.io/badge/WeChat-4.x%20tested-07C160?logo=wechat&logoColor=white)](https://github.com/zhuobichen/weflow-cli/releases)
 [![Local-first](https://img.shields.io/badge/local--first-zero%20telemetry-8A2BE2)](./SECURITY.md)
@@ -52,7 +52,7 @@ $ weflow-cli fav list -n 3
 ```text
 weflow-cli sessions                    # 会话列表
 weflow-cli messages "联系人" -n 20      # 查询聊天消息
-weflow-cli export "联系人" html         # 导出 HTML / Excel / Markdown / JSON
+weflow-cli export "联系人" html         # 导出 HTML / Excel / TXT / JSON
 weflow-cli fav list -t article -k AI   # 微信收藏: 类型过滤 + 关键词搜索
 weflow-cli daily --date 2026-08-21     # 公众号日报 + AI 摘要与分类
 weflow-cli daily-server                # 本地阅读器 http://localhost:8765
@@ -92,7 +92,7 @@ Linux 的自动初始化能力取决于微信发行版、Python 依赖和当前
 
 | 场景 | 能力 |
 | --- | --- |
-| 聊天记录 | 查询会话、联系人和消息；导出 JSON、TXT、Markdown、HTML、Excel。 |
+| 聊天记录 | 查询会话、联系人和消息；导出 JSON、TXT、HTML、Excel。HTML 导出会同时给出一份媒体覆盖报告，说明哪些图片/表情没能嵌入以及原因。 |
 | 公众号日报 | 抓取文章、AI 摘要与分类、生成本地阅读页，保留收藏和已读状态。 |
 | 个人知识库 | 同步微信读书笔记、构建 Obsidian Vault、语义搜索、RAG 问答和概念 Wiki。 |
 | AI 协作 | 通过 MCP 把文章、知识库、日报和受控的本地数据能力交给兼容客户端；工具清单以 `weflow-cli mcp-config` 和 `docs/MCP.md` 为准。 |
@@ -183,8 +183,15 @@ weflow-cli config set dailySources "公众号A,公众号B"
 weflow-cli config set dailyAiEnabled false
 weflow-cli config set dailyAiEnabled true
 
-# 为来源设置固定类别；已分类来源只生成摘要，不再调用文章主题分类
+# 不在日报里出现的主题（展示层开关：照常抓取归档，只是不展示；改主意不用重抓）
+# 焦点主题 AI 不能排除，写错的主题名会被忽略并打 WARN
+weflow-cli config set dailyExcludeTopics "新闻,投资,学术"
+
+# 为来源设置固定类别；已分类来源只生成摘要，主题用你配的、标签取该类别（不会有真标签）
 weflow-cli config set dailySourceCategories '<JSON object: source name or gh_ ID -> AI/政治/学术/新闻/文学/投资>'
+
+# 文章主题与相关度改由 Jev 决策模型判断（可选；不配则沿用 LLM 解析路径）
+weflow-cli config set typesafeApiKey "..."
 ```
 
 阅读器默认在 `http://localhost:8765/` 提供服务。
@@ -205,8 +212,18 @@ weflow-cli mcp-config > .mcp.json
 weflow-cli config set deepseekApiKey "sk-..."   # 或任意 OpenAI 兼容端点: aiBaseUrl + aiModel
 weflow-cli login-wechat        # 扫码绑定消息通道 (微信里会出现 ClawBot 联系人)
 weflow-cli assistant start     # 后台守护进程常驻
+weflow-cli panel               # 打开本机面板窗口 (不扫码也能用)
 ```
 
+`weflow-cli panel` 打开的是一个常驻小窗，它跟微信里问的**是同一个大脑**（同一份记忆、
+同一条每日配额）。**不登录微信也能用**——消息通道是可选的。窗口只是客户端：消息走守护进程
+开在 `127.0.0.1` 上的入口，所以两个入口不会各写一份记忆。
+
+悬浮球需要 Electron（`npm i -g electron`）；没装的话会降级成 Edge/Chrome 的 `--app` 小窗，
+界面一样，但没有无边框置顶、没有托盘与快捷键。有球时：**点一下它在旁边展开对话气泡
+（球不动，再点一下收起）**；气泡默认开在球的左边，左边放不下会自己翻到右边，上方不够就
+改成顶对齐；拖动球可以换位置（位置会记住）。**在面板里点右键**可以给名单上的人快速起草回复（`weflow-cli config set quickReplyContacts "某人,另一人"`；点一下就是把那段对话发给两个云端模型，只产出文本、不会替你发送），菜单最后一项能把球收起来（点托盘图标叫回来）。
+
 之后在手机微信的 ClawBot 对话里直接说话，助手会自动查询本地聊天记录和收藏作答，并具备跨会话记忆：
 
 - 「我最近都在忙什么？」— 自动检索会话与聊天记录综合回答
@@ -218,6 +235,8 @@ weflow-cli assistant start     # 后台守护进程常驻
 - 「我在读什么书？」「XX 这本书的笔记」— 微信读书书架与笔记本
 - 「我有什么待办？有急事吗？」— 待办清单（按紧急度排序）
 - 「知识库里怎么讲 RAG 的？」— 概念 Wiki 检索
+- 「帮我回老王那句话」— 起草回复：先判断对方要什么、风险和该不该给实质内容，再给几条候选。
+  **只产出文本，不会替你发送**；涉钱或风险很高时不给草稿，只说明该先确认什么
 - 「记住：我的项目叫 weflow-cli」— 写入长期记忆
 
 运行机制：守护进程通过微信官方 Bot 通道（iLink）长轮询收发消息，Agent 循环、三层记忆（工作窗口 / 滚动摘要 / 长期事实）、数据库查询全部在本机执行；仅最终提问与回复文本会发送给所配置的 LLM，工具输出中的电话/邮箱/链接等 PII 默认自动脱敏（`config set assistantPrivacy strict` 可加强，`ollama` 本地引擎则完全不出网）。会话 24 小时未活跃需重新扫码，单窗口内主动回复有官方条数限制。
@@ -246,14 +265,19 @@ weflow-cli config set assistantGroupRequireMention true
 | 检查环境与配置 | `weflow-cli check` · `weflow-cli config show` |
 | 初始化或手动指定路径 | `weflow-cli init [--path <目录>]` |
 | 浏览聊天数据 | `weflow-cli sessions` · `weflow-cli messages <联系人>` · `weflow-cli contacts` |
-| 导出聊天记录 | `weflow-cli export <联系人> <json\|txt\|md\|html\|excel>` |
+| 谁在等我回话 | `weflow-cli awaiting --dry-run` · `weflow-cli awaiting --yes` |
+| 帮我起草回复（只出文字，不发送） | `weflow-cli draft <联系人> --dry-run` · `--yes` |
+| 本机判断层 | `weflow-cli decide --request <file> --dry-run` · `--yes` |
+| 导出聊天记录 | `weflow-cli export <联系人> <json\|txt\|html\|excel>` |
+| 同步检查点 | `weflow-cli sync run <联系人> --since <日期>` · `sync status` · `sync verify` |
 | 公众号日报与阅读器 | `weflow-cli daily` · `weflow-cli daily-server` · `weflow-cli review` |
 | 朋友圈缓存 | `weflow-cli sns timeline` · `weflow-cli sns users` · `weflow-cli sns stats` |
 | 微信收藏 | `weflow-cli fav list` · `weflow-cli fav export markdown` · `weflow-cli fav set-key` |
 | 微信读书 | `weflow-cli weread shelf` · `notes` · `search` · `stats` |
-| 知识库 | `weflow-cli vault` · `weflow-cli wiki` · `weflow-cli search <query>` · `weflow-cli chat` |
+| 知识库 | `weflow-cli vault` · `weflow-cli wiki` · `weflow-cli search <query>` · `weflow-cli chat`（语义检索需先 `config set dashscopeApiKey`）|
 | 总结与任务 | `weflow-cli report` · `annual-report` · `todos` |
 | 第二大脑助手 | `weflow-cli assistant start` · `status` · `log` · `stop` |
+| 本机面板 | `weflow-cli panel`（悬浮窗；`--status` 只看状态，`--ask "…"` 在命令行里问）|
 | AI 编辑器集成 | `weflow-cli mcp-config` |
 
 运行 `weflow-cli <命令> --help` 可以查看某个命令的完整参数。例如：
@@ -320,6 +344,7 @@ python scripts/fav_server.py --date YYYY-MM-DD
 - [详细架构说明](./ARCHITECTURE.md)：模块、数据流与实现边界。
 - [项目维护状态](./docs/PROJECT_STATE.md)：当前能力、限制、优先级与交接入口。
 - [技术决策记录](./docs/DECISIONS.md)：长期维护中的关键设计取舍。
+- [扩展指南](./docs/EXTENDING.md)：加一个工具/配置键/命令/MCP 工具/Python 脚本要改哪几处，以及哪条测试会拦你。**目前没有插件加载器**，这份文档说的就是"为什么没有"和"现在怎么加"。
 - [分支与合并记录](./docs/BRANCHES.md)：分支用途、合并时间线与并行开发的对齐约定。
 - [发布清单](./docs/RELEASING.md)：版本号、打包敏感内容检查、npm 凭据、国内镜像同步。
 - [npm 发布速查](./docs/NPM-PUBLISH.md)：404 / 409 / ETARGET 是失败还是在传播，按症状查表。