wezard 1.1.5 → 1.2.0

package/CLAUDE.md

@@ -29,6 +29,13 @@ npm run build && ./cli/wezard.sh reload    # rebuild, then bounce the resident d
 
 When the user says **"reload"** in this repo, it means exactly: `npm run build && ./cli/wezard.sh reload`. The global `wezard` binary may not be on `$PATH` in dev shells — always invoke `./cli/wezard.sh` from the repo root.
 
+## Release / changelog
+
+Every version bump **must** update `CHANGELOG.md` — no release without a changelog entry. Follow [Keep a Changelog](https://keepachangelog.com/) + [SemVer](https://semver.org/):
+- Newest version on top; collect in-flight work under `## [Unreleased]` and rename it to `## [x.y.z] - YYYY-MM-DD` at tag time.
+- Group changes under `Added` / `Changed` / `Deprecated` / `Removed` / `Fixed` / `Security`; label breaking changes **BREAKING**.
+- Keep the compare-link footer in sync (add the new `[x.y.z]` link, repoint `[Unreleased]`).
+
 ## High-level architecture
 
 Three processes, all coordinating via 127.0.0.1:17890 and `~/.wezard/`:

package/README.md

@@ -1,24 +1,60 @@
-# wezard
+<div align="center">
 
-**把 Claude Code 装进企业微信。** 在地铁上、被窝里、开会摸鱼时，照样能跟你电脑上的 Claude 干活。
+<img src="images/icon.png" alt="wezard" width="176" height="176" />
+
+<h1>wezard</h1>
+
+<p><b>把 Claude Code 装进企业微信。</b><br/>在地铁上、被窝里、开会摸鱼时，照样能跟你电脑上的 Claude 干活。</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/wezard"><img src="https://img.shields.io/npm/v/wezard?style=flat-square&color=07C160&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/wezard"><img src="https://img.shields.io/npm/dm/wezard?style=flat-square&color=07C160&label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/guxi11/wezard/stargazers"><img src="https://img.shields.io/github/stars/guxi11/wezard?style=flat-square&color=E8825C" alt="GitHub stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/wezard?style=flat-square&color=E8825C" alt="license" /></a>
+  <img src="https://img.shields.io/node/v/wezard?style=flat-square&color=339933" alt="node version" />
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555?style=flat-square" alt="platform" />
+</p>
+
+</div>
 
 ![demo](images/demo.png)
 
-- 🛎 **远程审批** — Claude 要跑 `Bash` / `Edit`？审批卡片直推 IM，点 ✅/❌/⏱（放行 N 分钟）。
-- 📋 **计划审批** — Claude 在 plan mode 结束（`ExitPlanMode`）时，把计划摘要 + 审批卡推到 IM：点 ✅同意 让它退出 plan mode 开始执行，或 ✏️继续改 让它留在 plan mode 继续完善。同 `AskUserQuestion` 多选题也镜像为投票卡。
-- 🪞 **会话镜像** — 你电脑上跑的 Claude 流式打字、tool_use、思考过程，实时同步到企业微信；IM 里发消息原样落进 CLI 输入框。
-- 🖼 **图片直贴** — 企业微信发图，自动走 macOS 剪贴板 + tmux 粘贴，Claude 当贴图处理（不走 Read，不耗 token）。
-- 🔍 **细节页** — 工具调用 / 审批请求都生成本地 HTML 详情页，IM 里点链接看完整 input / result / git diff。
-- 📡 **MCP 主动推送** — Claude 通过 `wecom__send_markdown` / `wecom__send_card` / `wecom__ask_user` 主动汇报或问询。
-- 📄 **文档读写** — Claude 通过 `wecom_doc_list_tools` / `wecom_doc_call` 直接调企业微信智能机器人的 doc / smartsheet / smartpage MCP，新建在线文档、写 Markdown、读链接、操作智能表格——全程在内网，不需要 corp access_token。
-- 🗂 **多会话发现/切换** — Claude 通过 `list_claude_sessions` / `switch_claude_session` / `new_claude_session` 列出本机 tmux 内所有在跑的 Claude 会话（带摘要 + 稳定动物 emoji 标签）、把 IM 镜像切到其中任一个、或在指定路径新开一个会话。审批卡标题也带同一枚 emoji，多个会话兜底到同一 IM 时一眼区分。
-- 🔄 **重启即续** — 电脑重启 / tmux 全没了 / daemon 崩了都不掉档：IM ↔ 会话绑定持久化在 `~/.wezard/mirror-attachments.json`，下一条 IM 消息自动 `claude --resume` 拉起新 tmux pane，历史完整继承；`tmux attach -t wezard` 接管即可。
+| 功能<img width="160"> | 说明 |
+| --- | --- |
+| 🛎 **远程审批** | Claude 要跑 `Bash` / `Edit`？审批卡片直推 IM，点 ✅/❌/⏱（放行 N 分钟）。 |
+| 📋 **计划审批** | Claude 在 plan mode 结束（`ExitPlanMode`）时，把计划摘要 + 审批卡推到 IM：点 ✅同意 退出 plan mode 开始执行，或 ✏️继续改 留在 plan mode 继续完善。`AskUserQuestion` 多选题也镜像为投票卡。 |
+| 🪞 **会话镜像** | 你电脑上跑的 Claude 流式打字、tool_use、思考过程，实时同步到企业微信；IM 里发消息原样落进 CLI 输入框。 |
+| 🖼 **图片直贴** | 企业微信发图，自动走 macOS 剪贴板 + tmux 粘贴，Claude 当贴图处理（不走 Read，不耗 token）。 |
+| 🔍 **细节页** | 工具调用 / 审批请求都生成本地 HTML 详情页，IM 里点链接看完整 input / result / git diff。 |
+| 📡 **MCP 主动推送** | Claude 通过 `wecom__send_markdown` / `wecom__send_card` / `wecom__ask_user` 主动汇报或问询。 |
+| 📄 **文档读写** | Claude 通过 `wecom_doc_list_tools` / `wecom_doc_call` 直接调企业微信智能机器人的 doc / smartsheet / smartpage MCP，新建在线文档、写 Markdown、读链接、操作智能表格——全程在内网，不需要 corp access_token。 |
+| 🗂 **多会话发现/切换** | Claude 通过 `list_claude_sessions` / `switch_claude_session` / `new_claude_session` 列出本机 tmux 内所有在跑的会话（带摘要 + 稳定动物 emoji 标签）、切换 IM 镜像、或在指定路径新开会话。审批卡标题也带同一枚 emoji，多会话兜底到同一 IM 时一眼区分。 |
+| 🔄 **重启即续** | 电脑重启 / tmux 全没了 / daemon 崩了都不掉档：IM ↔ 会话绑定持久化在 `~/.wezard/mirror-attachments.json`，下一条 IM 消息自动 `claude --resume` 拉起新 tmux pane，历史完整继承；`tmux attach -t wezard` 接管即可。 |
+
+<details>
+<summary><b>目录</b></summary>
+
+- [快速开始](#快速开始)
+- [镜像模式](#镜像模式)
+- [体验是什么样](#体验是什么样)
+- [文档 / 智能表格 / 智能文档](#文档--智能表格--智能文档)
+- [事件订阅 / 定时广播](#事件订阅--定时广播)
+- [一个聊天里跑多个会话（`#tag` 路由）](#一个聊天里跑多个会话tag-路由)
+- [多 CLI 后端](#多-cli-后端claude--claude-internal--codebuddy)
+- [Prompt-cache 保活（省钱心跳）](#prompt-cache-保活省钱心跳)
+- [常用命令](#常用命令)
+- [常见问题](#常见问题)
+- [深入了解](#深入了解)
+- [参与贡献](#参与贡献)
+- [License](#license)
+
+</details>
 
 ---
 
 ## 快速开始
 
-**前置**：macOS / Linux、Node ≥ 20、PATH 里能找到 `claude` 或 `claude-internal`、企业微信「智能机器人」的 `botId` + `secret`。镜像模式额外需要 `tmux`。
+**前置**：macOS / Linux、Node ≥ 20、`tmux`、PATH 里能找到 `claude` 或 `claude-internal`、企业微信「智能机器人」的 `botId` + `secret`。
 
 ```bash
 npm install -g wezard
@@ -31,7 +67,6 @@ wezard init
 | --- | --- |
 | botId / secret | `~/.wezard/secrets.json` |
 | 用哪个 Claude（`claude` / `claude-internal` / 自定义路径） | `~/.wezard/config.jsonc` |
-| 用哪种模式（`headless` / `mirror`，见下文） | `~/.wezard/config.jsonc` |
 | 是否开启 PreToolUse 远程审批 | `~/.wezard/config.jsonc` |
 
 然后自动：编译 → 注入 hook/MCP → 装常驻 daemon（macOS launchd / Linux systemd --user）→ 等 WebSocket 鉴权。
@@ -44,74 +79,13 @@ wezard init
 
 这是**唯一**绕过白名单的入口，10 分钟窗口，消费完立刻关。后续所有消息都按白名单鉴权。
 
-### 其它安装方式 / 内网与无 systemd 环境
-
-**从某个 fork / 分支装（自带改动的版本）**：`dist/` 不入库，但 `prepare` 脚本会在 git 安装时自动编译，所以可以直接：
-
-```bash
-npm i -g github:<你的用户名>/wezard          # 默认分支
-npm i -g github:<你的用户名>/wezard#<分支名>   # 指定分支
-```
-
-**内网 / 需要正向代理**：wezard 的出站（WeCom WebSocket、智能机器人文档 MCP）会读环境变量里的代理。安装与运行都带上 `HTTPS_PROXY`：
-
-```bash
-HTTPS_PROXY=http://your-proxy:port npm i -g github:<你的用户名>/wezard
-# 也可在 config.jsonc 写死: bot.proxy = "http://your-proxy:port"（优先级高于环境变量）
-```
-
-daemon 进程同样需要能读到代理变量（见下方守护脚本里 `export HTTPS_PROXY`）。
-
-**无 systemd 的环境（容器等）**：`init` 装 daemon 这步在 macOS 走 launchd、Linux 走 `systemd --user`。若机器没有 systemd user session（很多容器：PID 1 非 systemd、无 `XDG_RUNTIME_DIR`），这步会失败——其余配置（hook / MCP / 插件）已生效，只差 daemon 没被托管。用一个简单的重启循环守护即可，存成 `~/.wezard/daemonctl.sh`：
-
-```bash
-#!/usr/bin/env bash
-# 无 systemd 时的 wezard daemon 守护：setsid 脱离终端的重启循环。
-set -uo pipefail
-REPO="$(npm root -g)/wezard"
-NODE="$(command -v node)"
-WC="$HOME/.wezard"; PIDFILE="$WC/supervisor.pid"; LOG="$WC/daemon.log"
-mkdir -p "$WC"
-# 内网：daemon 出站要走代理。按需改成你的代理地址，或删掉这两行。
-export HTTPS_PROXY="${HTTPS_PROXY:-http://your-proxy:port}"; export https_proxy="$HTTPS_PROXY"
-export NO_PROXY="${NO_PROXY:-127.0.0.1,localhost}"; export no_proxy="$NO_PROXY"
-is_running(){ [[ -f "$PIDFILE" ]] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; }
-case "${1:-start}" in
-  start)   is_running && { echo "already running"; exit 0; }
-           setsid bash "$0" __loop </dev/null >>"$LOG" 2>&1 & echo $! >"$PIDFILE"
-           sleep 2; echo "[daemonctl] started (pid $(cat "$PIDFILE"))" ;;
-  __loop)  while [[ -f "$PIDFILE" ]]; do "$NODE" "$REPO/dist/daemon/index.js" >>"$LOG" 2>&1
-             [[ -f "$PIDFILE" ]] || break; sleep 5; done ;;
-  stop)    [[ -f "$PIDFILE" ]] && { pid=$(cat "$PIDFILE"); rm -f "$PIDFILE"
-             pkill -P "$pid" 2>/dev/null||true; kill "$pid" 2>/dev/null||true; }
-           pkill -f "$REPO/dist/daemon/index.js" 2>/dev/null||true; echo "[daemonctl] stopped" ;;
-  restart) bash "$0" stop; sleep 1; bash "$0" start ;;
-  status)  is_running && echo "running (pid $(cat "$PIDFILE"))" || echo "stopped"
-           curl -sS -m2 http://127.0.0.1:17890/status 2>/dev/null && echo || echo "(HTTP :17890 无响应)" ;;
-esac
-```
-
-```bash
-chmod +x ~/.wezard/daemonctl.sh
-~/.wezard/daemonctl.sh start    # 起 daemon（自带崩溃重启）
-~/.wezard/daemonctl.sh status   # 看状态
-```
-
-容器重启不会自动拉起 daemon——把 `~/.wezard/daemonctl.sh start` 加进 shell profile 或容器入口即可（幂等，已在跑就 no-op）。
-
 ---
 
-## 两种模式怎么选
+## 镜像模式
 
-|  | `headless` | `mirror` 🌟 |
-| --- | --- | --- |
-| **怎么跑** | IM 来消息 → 后台 `claude -p` 跑一轮 | IM 来消息 → tmux 粘进活的 TUI |
-| **CLI 看得见吗** | 看不见（headless 子进程） | 看得见（IM 消息像你自己敲进去的） |
-| **状态续接** | 靠 `--resume <sid>` 续 session | 一对一绑定 IM 聊天 ↔ tmux 窗口，原地累计 |
-| **流式输出** | 转发 assistant 文本块 | 完整流式：打字机、tool_use、思考过程都看得到 |
-| **适合谁** | 简单单轮问答 / CI 类自动化 | 真·远程结对编程 |
+IM 来消息 → tmux 粘进活的 TUI，CLI 里像你自己敲进去的一样；Claude 的回应、调用了哪些工具、思考过程都逐字流式推回 IM。一对一绑定 IM 聊天 ↔ tmux 窗口，原地累计上下文——真·远程结对编程。
 
-镜像模式下，IM 里发 `/new` 直接开新 tmux 窗口 + 新 Claude 会话；`/clear` 清当前上下文；带图消息自动注入剪贴板。所有 IM 聊天共享一个 tmux session（默认名 `wezard`），每个聊天一个独立 window，**关 tmux / daemon 崩了 / 整机重启都能自愈**：IM↔会话绑定 write-through 落到 `~/.wezard/mirror-attachments.json`，daemon 起来就 eager restore；重启后 pane 全死，下一条 IM 消息触发 `claude --resume <sid>` 拉起新 pane，`--resume` fork 出的新 jsonl 由 watcher 从 EOF 无缝接管（不会把整段历史再推一遍到 IM）。中途在别处 `/clear` 把 jsonl rotate 掉也不丢绑定，会自愈到同项目目录下最新的 jsonl。
+IM 里发 `/new` 直接开新 tmux 窗口 + 新 Claude 会话；`/clear` 清当前上下文；带图消息自动注入剪贴板。所有 IM 聊天共享一个 tmux session（默认名 `wezard`），每个聊天一个独立 window，**关 tmux / daemon 崩了 / 整机重启都能自愈**：IM↔会话绑定 write-through 落到 `~/.wezard/mirror-attachments.json`，daemon 起来就 eager restore；重启后 pane 全死，下一条 IM 消息触发 `claude --resume <sid>` 拉起新 pane，`--resume` fork 出的新 jsonl 由 watcher 从 EOF 无缝接管（不会把整段历史再推一遍到 IM）。中途在别处 `/clear` 把 jsonl rotate 掉也不丢绑定，会自愈到同项目目录下最新的 jsonl。
 
 > 💡 **mirror 不要求你必须先在 CLI 里开 tmux**：在企业微信里直接发 `/new` 就能从零起一个新 tmux 窗口 + Claude 会话；甚至首次发任意消息都会自动 spawn + 绑定（首条消息既是绑定信号也是第一句 prompt）。回家打开终端 `tmux attach -t wezard` 接管即可。
 
@@ -119,89 +93,50 @@ chmod +x ~/.wezard/daemonctl.sh
 
 ## 体验是什么样
 
-**审批场景**：
+**审批场景**：你正在地铁上，电脑上的 Claude 想 `rm -rf node_modules` 重装。企业微信叮一声弹卡片：
 
-> 你正在地铁上，电脑上的 Claude 想 `rm -rf node_modules` 重装。企业微信叮一声弹卡片：
->
-> > 🛎 授权请求: Bash
-> > `rm -rf node_modules`
-> > [✅ 允许] [❌ 拒绝] [⏱ 5 分钟内自动允许]
->
-> 你点 ✅，卡片立刻刷新成 `✅ Bash · 已允许`，电脑上的 Claude 解除阻塞继续跑。
+> 🛎 授权请求: Bash
+> `rm -rf node_modules`
+> [✅ 允许] [❌ 拒绝] [⏱ 5 分钟内自动允许]
 
-**镜像场景**：
+你点 ✅，卡片立刻刷新成 `✅ Bash · 已允许`，电脑上的 Claude 解除阻塞继续跑。
 
-> 你 tmux 里开着 Claude 在写代码。出门后给机器人发：
->
-> > 把刚才那个函数改成异步的
->
-> 这条消息自动粘进 CLI 输入框 + 回车提交。Claude 的回应、调用了哪些工具、改了哪些文件，逐字流式推回你 IM。回家打开终端，对话一字不少都在那里。
+**镜像场景**：你 tmux 里开着 Claude 在写代码。出门后给机器人发：
+
+> 把刚才那个函数改成异步的
 
-**文档场景**：
+这条消息自动粘进 CLI 输入框 + 回车提交。Claude 的回应、调用了哪些工具、改了哪些文件，逐字流式推回你 IM。回家打开终端，对话一字不少都在那里。
 
-> 你给 Claude 说："周报给我整理成一篇企业微信文档"。Claude 自己调 `wecom_doc_list_tools` 看可用方法，再调 `wecom_doc_call` 走 `create_doc` 新建文档、`edit_doc_content` 写入 Markdown，最后把链接贴回会话——全程不离开 Claude，文档归属到你的 userid，每日 20 篇限额按 userid 计。
+**文档场景**：你给 Claude 说："周报给我整理成一篇企业微信文档"。Claude 自己调 `wecom_doc_list_tools` 看可用方法，再调 `wecom_doc_call` 走 `create_doc` 新建文档、`edit_doc_content` 写入 Markdown，最后把链接贴回会话——全程不离开 Claude，文档归属到你的 userid，每日 20 篇限额按 userid 计。
 
 ---
 
 ## 文档 / 智能表格 / 智能文档
 
-`wezard` 把企业微信智能机器人的远端 MCP（doc / smartsheet / contact 等）桥接到本地 Claude，**不走 corp access_token**：daemon 直接复用 botId+secret 的 WS 长连，通过 `aibot_get_mcp_config` 命令拉到每个 category 的 Streamable HTTP MCP URL，再以 JSON-RPC 调 `tools/list` / `tools/call`，`x-openclaw-wecom-userid` header 透传文档归属人。
-
-**前置一次性授权**：在企业微信「工作台 - 智能机器人 - 你的机器人 - 可使用权限」里勾选「文档」「智能表格」对应能力。第一次调用如果未授权，远端会返回结构化错误（errcode 851013）+ 授权链接，原样转给 Claude，照着点同意即可。
+`wezard` 把企业微信智能机器人的远端 MCP（doc / smartsheet / contact）桥接到本地 Claude，**全程内网、不走 corp access_token**。Claude 先调 `wecom_doc_list_tools` 看某 category 有哪些方法，再调 `wecom_doc_call` 执行——新建在线文档、写 Markdown、读链接、操作智能表格。首次用需在「工作台 - 智能机器人 - 可使用权限」里勾选「文档」「智能表格」。
 
-**Claude 侧自动发现**：模型先调一次 `wecom_doc_list_tools(category="doc")` 拿到工具列表（`create_doc` / `edit_doc_content` / `smartpage_create` / `upload_doc_image` ...）和入参 schema，再用 `wecom_doc_call(category, method, args)` 执行。category 当前可选：
-
-| category | 能干嘛 |
-| --- | --- |
-| `doc` | 在线文档、智能文档、文档图片上传 |
-| `smartsheet` | 智能表格的字段 / 记录读写 |
-| `contact` | 通讯录查询（按需授权） |
-
-**curl 验证**：
-
-```bash
-# 列 doc 类目下所有可用工具
-curl -sS -X POST http://127.0.0.1:17890/wedoc/list \
-  -H 'content-type: application/json' \
-  -d '{"category":"doc"}'
-
-# 创建一篇文档
-curl -sS -X POST http://127.0.0.1:17890/wedoc/call \
-  -H 'content-type: application/json' \
-  -d '{"category":"doc","method":"create_doc","args":{"doc_type":3,"doc_name":"demo"}}'
-
-# 写入 Markdown
-curl -sS -X POST http://127.0.0.1:17890/wedoc/call \
-  -H 'content-type: application/json' \
-  -d '{"category":"doc","method":"edit_doc_content",
-       "args":{"docid":"<返回的 docid>","content_type":1,"content":"# 标题\n正文"}}'
-
-# 授权变更后清缓存
-curl -sS -X POST http://127.0.0.1:17890/wedoc/invalidate -H 'content-type: application/json' -d '{}'
-```
-
-`requesterUserId` 解析顺序：调用方显式传入 → `defaultChat` 的 `user:<id>` 部分 → 不传（远端会拒，错误原样回到 Claude，比 daemon 提前判更透明）。
+桥接机制、curl 验证、`requesterUserId` 解析规则见 [技术说明](技术说明.md#文档-mcp-如何桥接)。
 
 ---
 
 ## 事件订阅 / 定时广播
 
-一个轻量 pub/sub：任意群或单聊都能订阅一个 **topic**（自定义事件名），任何授权用户都能广播；daemon 内置分钟级调度器，每天定点自动推送。订阅关系与定时任务持久化到 `~/.wezard/config.jsonc` 的 `topics` 段，`wezard reload` 后自动恢复。
+一个轻量 pub/sub：任意群或单聊都能订阅一个 **topic**（自定义事件名），任何会话都能广播；daemon 内置分钟级调度器，每天定点自动推送。订阅关系与定时任务持久化到 `~/.wezard/config.jsonc` 的 `topics` 段，`wezard reload` 后自动恢复。
 
-**IM 命令**（在已授权的会话里说，中英文均可）：
+**全部由 MCP 工具驱动**——直接对 Claude 说人话，它自己调工具，不用记命令语法：
 
-```
-订阅 sync-daily                       # 当前会话订阅 topic（群里说→群订阅，单聊里说→个人订阅）
-退订 sync-daily
-广播 sync-daily 内容：xxx              # 立即广播给所有订阅者
-每天 08:00 广播 sync-daily 内容：xxx   # 定时（也接受「每天8点」「每天8:30」「每日 08:00」）
-广播列表 / 订阅列表                    # 查看当前状态
-取消广播 sync-daily                    # 删掉该 topic 的所有定时
-```
+| 说 | 工具 | 干什么 |
+| --- | --- | --- |
+| 「订阅 sync-daily」 | `subscribe_topic(topic)` | 把当前聊天加进某 topic 的订阅表 |
+| 「别再往这群发 sync-daily」 | `unsubscribe_topic(topic)` | 退订 |
+| 「广播 sync-daily：早会 10 分钟后开始」 | `broadcast_topic(topic, markdown)` | 立即扇出给所有订阅者，返回 `sent / failed / subs` |
+| 「每天 8 点广播 sync-daily：…」 | `schedule_broadcast(topic, hour, minute, content)` | 注册每日定时广播 |
+| 「取消 sync-daily 的定时」 | `cancel_broadcast(topic)` | 删掉该 topic 的所有定时 |
+| 「我订了什么 / 有哪些定时」 | `list_topics()` | 列出本聊天订阅 + 全部定时 |
 
-典型用法：在群 A 说 `订阅 sync-daily`，在群 B 说 `每天8点广播 sync-daily 内容：早会 10 分钟后开始`——第二天早 8 点群 A 自动收到。
+典型用法：在群 A 说「订阅 sync-daily」，在群 B 说「每天 8 点广播 sync-daily：早会 10 分钟后开始」——第二天早 8 点群 A 自动收到。一个 agent 也能在跑完任务后自己 `broadcast_topic` 汇报结果，无需人工敲命令。
 
-**外部触发**（CI / 监控 / 脚本）：
+**外部触发**（CI / 监控 / 脚本，无需 MCP）：daemon 在 loopback 暴露 `POST /publish`，广播给某 topic 的所有订阅者：
 
 ```bash
 curl -sS -X POST http://127.0.0.1:17890/publish \
@@ -209,66 +144,7 @@ curl -sS -X POST http://127.0.0.1:17890/publish \
   -d '{"topic":"ci-fail","markdown":"🔴 build #1234 failed on main"}'
 ```
 
-调用方只关心事件名，运维通过 IM 命令改订阅者，代码零改动。
-
----
-
-## 消息是怎么同步的
-
-**审批流**（`headless` / `mirror` 都走这条）：
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant CC as Claude Code
-    participant Hook as PreToolUse hook
-    participant D as wezard daemon
-    participant WS as WeCom WS
-    participant U as 你 (IM)
-
-    CC->>Hook: 触发 Bash "rm -rf foo"
-    Hook->>D: POST /approval (长轮询 ≤30min)
-    D->>WS: sendCard(按钮卡片)
-    WS->>U: 推送审批卡片
-    Note over D,U: daemon 在内存里 park 这个 HTTP 请求<br/>等 click 事件 / 自动窗口 / 超时三选一
-    U->>WS: 点 ✅
-    WS->>D: template_card_event
-    D->>WS: updateTemplateCard("已允许")
-    D-->>Hook: 200 {decision: allow}
-    Hook-->>CC: stdout 决策 JSON
-    CC->>CC: 放行 Bash
-```
-
-**镜像流**（`mirror` 模式，IM ↔ tmux 双向）：
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant U as 你 (IM)
-    participant WS as WeCom WS
-    participant D as wezard daemon
-    participant T as tmux + claude
-    participant J as session.jsonl
-
-    U->>WS: "改成异步的"
-    WS->>D: message.text
-    D->>D: allowFrom 鉴权
-    D->>T: load-buffer + paste-buffer + Enter
-    T->>J: assistant 流式追加
-    par tail
-        D->>J: fs.watch 增量读
-        J-->>D: 新 assistant / tool_use 块
-        D->>WS: replyStream(流式片段)
-        WS->>U: 推送流式回复
-    and 工具拦截
-        T->>D: PreToolUse hook (走上面的审批流)
-    end
-```
-
-要点：
-- daemon 是**唯一**和 WeCom 说话的进程，hook 和 MCP 都只是它的 HTTP 客户端
-- 审批是**长轮询 + 内存 park**，没有 webhook、不依赖外网回调
-- 镜像是**单向 paste + 单向 tail**：IM→tmux 走粘贴键，tmux→IM 走读 jsonl，两条管道独立、互不阻塞
+调用方只关心事件名，订阅者由 AI 通过 MCP 工具增删，代码零改动。
 
 ---
 
@@ -276,6 +152,8 @@ sequenceDiagram
 
 同一个 WeCom 聊天里可以同时挂多个并行 Claude session，靠消息里的 `#tag` 前缀路由。不带 tag 就是默认 session，与旧行为一致。
 
+![多会话](images/multi-session.png)
+
 **创建 & 切换**
 
 ```
@@ -346,6 +224,31 @@ daemon 同时挂载所有已安装的 CLI，不是二选一：你可以一个 tm
 
 ---
 
+## Prompt-cache 保活（省钱心跳）
+
+Anthropic 的 prompt cache 只活 ~5 分钟，且**写缓存 1.25x、读缓存 0.1x**。一个 pane 一旦空闲（agent 在等 peer 回复、或后台任务在跑），整份上下文就会掉出缓存——下一轮真实对话得按 1.25x 把整个上下文重写一遍。保活机制会在缓存**即将过期前**往 pane 注入一次极小的 ping，逼模型发起一次廉价请求（命中缓存前缀走 0.1x 读）并把 5 分钟 TTL 往前滑，真实那轮就只需写增量。
+
+- **只在「缓存还命中得到」的窗口内保活**：空闲落在 `[ttlSec - marginSec, ttlSec)`（默认 `[255s, 300s)`）才 ping。**过了 TTL 就绝不出手**——那时缓存已经没了，ping 反而要付整份上下文的冷写，为一轮 no-op 白烧钱。daemon reload 后挂着的老会话、长时间无人理的 pane，都直接放过，等下一次真实操作自然承担。
+- **零污染**：ping 文案默认 `keepalive — reply with just "pong", take no other action`，逼出一个约 1 token 的极短回复且禁止任何工具动作。这轮 ping/pong **不进聊天**（群里只有一条 `❤️ 保活 · context ~85k tokens · 3/6`），但会 **记入 chat detail 时间线**：记录的是**真实的心跳对话**——注入的 ping 原文 + 模型的真实回复（预期就一个 `pong`）+ 那次真实的 cache-read usage，留痕、可审计，证明它确实只是一次廉价读缓存。
+- **预算封顶 + 会终止**：每个 pane 连续保活 `maxPings`（默认 6）次后就停手让它冷掉；一旦观察到真实活动（新一轮对话），预算自动重置、重新计数。两道终止保险叠加——超过 TTL 的会话本就不 ping，加上 6 次封顶，不会无限保活下去。
+- **`/stop` 手动暂停**：在 IM 里发 `/stop`（Esc 打断当前生成）同时会暂停该会话的保活；等下次有新对话（IM 消息或 CLI 里新起一轮）自动恢复。
+- **只针对 mirror 模式的活 pane**：spawn 模式无 TTY、pane 已死、正在流式输出或会话轮换中的，一律跳过。
+
+全部可配（`wrc.mirror.keepalive`）：
+
+```jsonc
+"keepalive": {
+  "enabled": true,   // 总开关
+  "ttlSec": 300,     // 缓存 TTL，Anthropic 默认 5min
+  "marginSec": 45,   // 提前多少秒 ping（留出注入落地的余量）
+  "maxPings": 6,     // 单次空闲连续保活上限
+  "ping": "keepalive — reply with just \"pong\", take no other action",
+  "notify": true     // 是否往聊天推 context size 心跳
+}
+```
+
+---
+
 ## 常用命令
 
 IM 里发 `/help` 可随时拉出完整命令表；每次 `/new`、`/clear` 之后，回执会随机附一条功能提示，用来慢慢摊开命令面。
@@ -364,11 +267,17 @@ IM 里发 `/help` 可随时拉出完整命令表；每次 `/new`、`/clear` 之
 wezard status              # 看 daemon + WS 健康
 wezard logs -f             # 实时日志
 wezard send <chat> <text>  # 主动推消息
+wezard sync                # 重写 hook/MCP/env 进各 settings.json
 wezard reload              # 重启 daemon（改了配置后用）
+wezard migrate             # 一次性：从旧名 weclaude 迁移到 wezard
 wezard unsync              # 卸载 hook/MCP（保留 daemon）
 wezard uninstall           # 完整卸载（先于 npm uninstall）
 ```
 
+> ⬆️ **升级**：`npm i -g wezard@latest` 装新版二进制，再 `wezard sync && wezard reload` 刷新 hook/MCP 注入并重启 daemon（幂等，`~/.wezard/` 的 config/secrets 原样保留）。
+>
+> `wezard migrate` 只用于从**旧包名 `weclaude`** 迁移（搬 `~/.weclaude` → `~/.wezard`、重装 daemon/插件），普通版本升级用不到。
+>
 > ⚠️ **卸载顺序**：先 `wezard uninstall` 再 `npm uninstall -g wezard`。否则 launchd/systemd 会一直尝试拉起已删除的二进制。`~/.wezard/` 下的 config/secrets 不会被清，二次安装可无缝复用。
 
 ---
@@ -389,22 +298,30 @@ wezard uninstall           # 完整卸载（先于 npm uninstall）
 
 ---
 
-## 架构一瞥
+## 深入了解
 
-三个进程走 `127.0.0.1:17890` + `~/.wezard/`：
+- [技术说明](技术说明.md) — 架构、消息双向同步流程、文档 MCP 桥接机制
+- [CLAUDE.md](CLAUDE.md) — 模块级职责与代码约定
+- [CHANGELOG.md](CHANGELOG.md) — 各版本变更
 
-```
- WeCom ── WebSocket ──► daemon (常驻, launchd/systemd)
-                          │
-                          ├── HTTP :17890 ◄── hook (pre-tool-use.sh, 长轮询)
-                          ├── HTTP :17890 ◄── MCP server (claude 的 stdio 子进程)
-                          └── spawn `claude -p` (headless)  或  tail jsonl + tmux paste (mirror)
-```
+---
 
-daemon 是**唯一**持有 WeCom WS 连接的进程，hook 和 MCP 都是它的薄 HTTP 客户端。
+## 参与贡献
+
+欢迎 issue / PR。本地开发：
+
+```bash
+git clone https://github.com/guxi11/wezard.git
+cd wezard && npm install
+npm run build          # tsc → dist/
+npm run typecheck      # tsc --noEmit
+npm run dev:daemon     # tsx 直跑 daemon，热迭代不用装
+./cli/wezard.sh reload # 重编译并重启常驻 daemon
+./cli/wezard.sh logs -f
+```
 
-详情看 [CLAUDE.md](CLAUDE.md)。
+架构与模块职责见 [CLAUDE.md](CLAUDE.md)。提交前跑一遍 `npm run typecheck`；无测试套件，别伪造测试命令。
 
 ## License
 
-MIT
+[MIT](LICENSE) © [guxi11](https://github.com/guxi11)

package/dist/daemon/inbound.js

@@ -11,7 +11,6 @@ import { computeAuditReport } from "./audit.js";
 import { syncProjectConfig, renderSyncReport } from "./cfg-sync.js";
 import { captureQuota, renderQuotaReport } from "./quota.js";
 import { tagOfKey, withTagHeader } from "../shared/session-label.js";
-import { parseSubscribe, parseUnsubscribe, parseBroadcast, parseDailySchedule, parseCancelSchedule, isListSchedules, isListSubs, subscribe, unsubscribe, addSchedule, removeSchedulesByTopic, publish, renderSubs, renderSchedules, } from "./topics.js";
 // Chat-binding key: stable id for "this conversation thread". Used as
 // session-map key, mirror target, defaultChat. NOT used for auth.
 const chatPrincipal = (msg) => msg.chattype === "group" && msg.chatid ? `chat:${msg.chatid}` : `user:${msg.from.userid}`;
@@ -114,7 +113,6 @@ const isStopCommand = (text) => text.trim() === "/stop";
 const isEnterCommand = (text) => text.trim() === "/n";
 const isRevealCommand = (text) => text.trim() === "/reveal";
 const isHelpCommand = (text) => /^\/(?:help|\?|h)$/i.test(text.trim());
-const isSkillBCommand = (text) => text.trim() === "/skill-b";
 // Static command reference. Grouped: session control, usage/info, topic
 // broadcast (natural-language, zh+en). Anything not matching a command is a
 // prompt forwarded to the bound Claude session.
@@ -155,14 +153,10 @@ const renderHelp = () => [
     "`/audit` 本会话 token/成本明细 (含 subagent) · `/audit <tag>` 指定标签会话",
     "`/cfgsync` 预演跨 CLI 项目配置同步 · `/cfgsync apply` 执行 (需授权)",
     "`/help` 本帮助",
-    "`/skill-b` 广播接口用法 (贴给 Claude)",
     "",
-    "▎广播订阅",
-    "`订阅 <topic>` · `退订 <topic>`",
-    "`广播 <topic> <内容>`",
-    "`每天 08:30 广播 <topic> <内容>`",
-    "`取消广播 <topic>`",
-    "`订阅列表` · `广播列表`",
+    "▎事件订阅 / 广播",
+    "已迁到 MCP:直接对 AI 说「订阅 xxx」「广播 xxx: …」「每天8点广播 xxx: …」,",
+    "它会调 `subscribe_topic` / `broadcast_topic` / `schedule_broadcast` 等工具处理。",
     "",
     "▎引用 (quote)",
     "引用消息 + 新文字：被引用内容作为上下文前缀附在你的话前。",
@@ -171,27 +165,6 @@ const renderHelp = () => [
     "",
     "其余文本直接转发给已绑定的 Claude 会话。",
 ].join("\n");
-// /skill-b — 回执一段 prompt,告诉 Claude 如何调用本 daemon 的 /publish 广播接口。
-// 用围栏代码块包裹便于用户在 WeCom 长按 copy 后贴给上游 Claude。
-const renderSkillBroadcast = () => [
-    "把下面这段贴给 Claude,它就知道怎么广播:",
-    "```",
-    "本机 daemon 在 127.0.0.1:17890 暴露 POST /publish,用来向已订阅某 topic 的会话广播消息。",
-    "",
-    "调用示例:",
-    "curl -sS -X POST http://127.0.0.1:17890/publish \\",
-    "  -H 'Content-Type: application/json' \\",
-    "  -d '{\"topic\":\"daily-report\",\"markdown\":\"# 标题\\n正文...\"}'",
-    "",
-    "请求体:",
-    "- topic (必填):订阅表里的 key",
-    "- markdown 或 text (二选一):消息内容,markdown 语法",
-    "",
-    "返回: { ok, topic, sent, failed, subs }。ws_disconnected=true 表示 daemon 与 WeCom WS 断开。",
-    "",
-    "长消息用 --data-binary @file.json,避免 shell 转义踩坑。",
-    "```",
-].join("\n");
 // /session(s) [arg] — list live Claude sessions, or switch the mirror to one.
 // Bare "/sessions" (or "/session") lists; an arg (animal emoji, sessionId, or
 // sessionId prefix) switches. Tolerates an optional trailing "s" and any spacing.
@@ -473,69 +446,6 @@ export const installInboundRouter = (client, cfg, log, bridge, sourcePath) => {
     // 隐式建会话(裸 `#tag` 第一条消息):轮到自己时若前一条已经把会话建好,直接
     // 复用,不再 respawn —— 否则先到的消息会被注入进一个刚被杀掉的 pane。
     const ensureSession = (who) => serializeSpawn(who, async () => "hasMirrorTarget" in bridge && bridge.hasMirrorTarget(who) ? "✅ 复用已建立的会话" : await spawnSession(who));
-    // 事件订阅 / 广播命令。授权后调用,不再走 bridge dispatch。返回 true 表示已处理。
-    const topicLog = log.child({ mod: "topics" });
-    const handleTopicCommand = async (frame, msg, who, text) => {
-        // 订阅/广播回执同样按会话 tag 标注 —— `#docs /subs` 的回执必须落在 `#docs`
-        // 的视觉通道里, 否则同一聊天并行会话时分不清是谁的回执。
-        const reply = async (t) => {
-            try {
-                await client.replyStream(frame, msg.msgid, withTagHeader(who, t), true);
-            }
-            catch { /* ignore */ }
-        };
-        const sub = parseSubscribe(text);
-        if (sub) {
-            const r = subscribe(cfg, sourcePath, sub.topic, who);
-            await reply(r.added
-                ? `✅ 已订阅 \`${sub.topic}\` (会话: \`${who}\`)`
-                : `ℹ️ 已在 \`${sub.topic}\` 订阅列表中`);
-            return true;
-        }
-        const unsub = parseUnsubscribe(text);
-        if (unsub) {
-            const r = unsubscribe(cfg, sourcePath, unsub.topic, who);
-            await reply(r.removed ? `✅ 已退订 \`${unsub.topic}\`` : `ℹ️ 未订阅 \`${unsub.topic}\``);
-            return true;
-        }
-        const daily = parseDailySchedule(text);
-        if (daily) {
-            addSchedule(cfg, sourcePath, {
-                topic: daily.topic,
-                hour: daily.hour,
-                minute: daily.minute,
-                content: daily.content,
-                createdBy: who,
-                createdAt: Date.now(),
-            });
-            const hh = String(daily.hour).padStart(2, "0");
-            const mm = String(daily.minute).padStart(2, "0");
-            const subCount = (cfg.topics.subs[daily.topic] ?? []).length;
-            await reply(`✅ 定时已添加: 每天 ${hh}:${mm} 广播 \`${daily.topic}\` (当前 ${subCount} 订阅者)`);
-            return true;
-        }
-        const bcast = parseBroadcast(text);
-        if (bcast) {
-            const r = await publish(client, cfg, topicLog, bcast.topic, bcast.content);
-            await reply(`📣 已广播到 \`${r.topic}\`: 送达 ${r.sent} / ${r.subs.length}${r.failed ? `,失败 ${r.failed}` : ""}`);
-            return true;
-        }
-        const cancel = parseCancelSchedule(text);
-        if (cancel) {
-            const n = removeSchedulesByTopic(cfg, sourcePath, cancel.topic);
-            await reply(n > 0 ? `✅ 已删除 \`${cancel.topic}\` 的 ${n} 条定时` : `ℹ️ \`${cancel.topic}\` 无定时任务`);
-            return true;
-        }
-        if (isListSubs(text)) {
-            await reply(renderSubs(cfg, who));
-            return true;
-        }
-        if (isListSchedules(text)) {
-            await reply(renderSchedules(cfg));
-            return true;
-        }
-        return false;
-    };
     // Prefix user-visible daemon replies with `<emoji> #tag` when the routed
     // session is tagged, so a chat hosting multiple concurrent tagged sessions
     // stays visually disambiguated. Untagged (default) session passes through
@@ -572,11 +482,6 @@ export const installInboundRouter = (client, cfg, log, bridge, sourcePath) => {
             await replyText(frame, msg, who, renderPwd(who));
             return { stop: true };
         }
-        // /skill-b — 静态 prompt 回执,教 Claude 调用 /publish 广播接口。纯文本,bypass allowFrom。
-        if (isSkillBCommand(text)) {
-            await replyText(frame, msg, who, renderSkillBroadcast());
-            return { stop: true };
-        }
         // /cost — token / cost ESTIMATE pulled from ~/.claude(-internal)?/projects
         // jsonl transcripts (ccusage-style). Read-only, no session state, so it
         // bypasses allowFrom like /id and /pwd. Real subscription %: use /usage.
@@ -698,12 +603,8 @@ export const installInboundRouter = (client, cfg, log, bridge, sourcePath) => {
             await replyText(frame, msg, who, reply);
             return { stop: true };
         }
-        // 事件订阅 / 广播 / 定时。授权后即可使用,任意 principal 可对本会话订阅/退订,
-        // 广播权限同 allowFrom(已过上面的 auth 门)。命令不进入 bridge dispatch,
-        // 用轻量 replyStream 回执。
-        const topicHandled = await handleTopicCommand(frame, msg, who, text);
-        if (topicHandled)
-            return { stop: true };
+        // 事件订阅 / 广播 / 定时已全部迁移到 MCP 工具(subscribe_topic /
+        // broadcast_topic / schedule_broadcast …),不再有 IM 文本命令。
         // Authorized `/stop` — Esc the live pane to interrupt whatever Claude is
         // currently doing. Mirror-mode only; bails cleanly when no attachment.
         if (isStopCommand(text)) {
@@ -712,7 +613,7 @@ export const installInboundRouter = (client, cfg, log, bridge, sourcePath) => {
             }
             else {
                 const r = await bridge.interruptPane(who);
-                await replyText(frame, msg, who, r.ok ? "✅ Esc sent" : `[wezard] /stop failed: ${r.reason ?? "unknown"}`);
+                await replyText(frame, msg, who, r.ok ? "✅ Esc sent · 保活已暂停（下次对话自动恢复）" : `[wezard] /stop failed: ${r.reason ?? "unknown"}`);
             }
             return { stop: true };
         }