npm - @unlinearity/cli-wechat-bridge - Versions diffs - 1.0.5 → 1.0.7 - Mend

@unlinearity/cli-wechat-bridge 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +124 -362
package/dist/bridge/bridge-adapters.claude.js +127 -6
package/dist/bridge/bridge-adapters.codex.js +219 -7
package/dist/bridge/bridge-adapters.core.js +13 -5
package/dist/bridge/bridge-adapters.opencode.js +143 -24
package/dist/bridge/bridge-adapters.shared.js +217 -6
package/dist/bridge/bridge-process-reaper.js +40 -1
package/dist/bridge/bridge-state.js +6 -3
package/dist/bridge/bridge-utils.js +49 -2
package/dist/bridge/claude-hooks.js +64 -3
package/dist/bridge/wechat-bridge.js +69 -3
package/dist/commands/check-update.js +1 -1
package/dist/companion/local-companion-start.js +27 -2
package/dist/companion/local-companion.js +21 -4
package/dist/daemon/wechat-daemon.js +277 -21
package/package.json +60 -100
package/dist/companion/codex-panel-link.js +0 -72
package/dist/companion/codex-panel.js +0 -179
package/dist/media/media-types.js +0 -1
package/dist/wechat/standalone-bot.js +0 -355

package/README.md CHANGED Viewed

@@ -1,34 +1,44 @@
 # CLI WeChat Bridge
-<p align='center'><img src='docs/images/logo.png' width=90%></p>
+<p align='center'><img src='docs/images/logo.png' width=90%></p>
 <p align="center"><img alt="Typing SVG" src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&amp;weight=600&amp;duration=4000&amp;pause=500&amp;color=06C763&amp;center=true&amp;vCenter=true&amp;width=660&amp;lines=CLI+WeChat+Bridge+%E5%BE%AE%E4%BF%A1%E6%A1%A5%E6%8E%A5;%E7%9C%9F%E6%AD%A3%E7%9A%84%E2%80%9C%E7%BB%88%E7%AB%AF-%E5%BE%AE%E4%BF%A1%E2%80%9D%E5%8E%9F%E7%94%9F%E5%8F%8C%E5%90%91%E4%BA%A4%E4%BA%92"></p>
 <p align="center">
   <a href="https://github.com/UNLINEARITY/CLI-WeChat-Bridge"><img alt="GitHub stars" src="https://img.shields.io/github/stars/UNLINEARITY/CLI-WeChat-Bridge?label=Stars&amp;style=for-the-badge&amp;logo=github&amp;color=0891b2&amp;labelColor=1c1917"></a>
-  <a href="https://www.npmjs.com/package/@unlinearity/cli-wechat-bridge"><img alt="npm version" src="https://img.shields.io/npm/v/@unlinearity/cli-wechat-bridge?label=npm&amp;style=for-the-badge&amp;logo=npm&amp;color=cb3837&amp;labelColor=1c1917"></a>
-  <a href="https://www.npmjs.com/package/@unlinearity/cli-wechat-bridge"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@unlinearity/cli-wechat-bridge?label=Downloads&amp;style=for-the-badge&amp;logo=npm&amp;color=16a34a&amp;labelColor=1c1917"></a>
-  <a href="https://github.com/UNLINEARITY/CLI-WeChat-Bridge/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/UNLINEARITY/CLI-WeChat-Bridge?label=License&amp;style=for-the-badge&amp;color=7c3aed&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/cli-wechat-bridge"><img alt="npm version" src="https://img.shields.io/npm/v/cli-wechat-bridge?label=npm&amp;style=for-the-badge&amp;logo=npm&amp;color=cb3837&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/cli-wechat-bridge"><img alt="npm downloads" src="https://img.shields.io/npm/dm/cli-wechat-bridge?label=Downloads&amp;style=for-the-badge&amp;logo=npm&amp;color=16a34a&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/@unlinearity/cli-wechat-bridge"><img alt="scoped npm downloads" src="https://img.shields.io/npm/dm/@unlinearity/cli-wechat-bridge?label=Scoped%20downloads&amp;style=for-the-badge&amp;logo=npm&amp;color=15803d&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/cli-wechat-bridge">
+  <img alt="License" src="https://img.shields.io/npm/l/cli-wechat-bridge?label=License&style=for-the-badge&color=7c3aed&labelColor=1c1917">
+</a>
 </p>
-**命令行工具的微信桥接**：本项目用于桥接微信消息与本地运行的 [`Codex`](https://github.com/openai/codex)、[`Claude Code`](https://code.claude.com/docs/en/overview)、`OpenCode` 或持久化 `powershell.exe` 会话，并将本地输出、审批请求与运行状态同步回微信。
+**命令行工具的微信桥接**：本项目将微信消息桥接到本地运行的 [`Codex`](https://github.com/openai/codex)、[`Claude Code`](https://code.claude.com/docs/en/overview) 和 [`OpenCode`](https://github.com/anomalyco/opencode)，同时把本地输出、审批请求与运行状态同步回微信。
-当前实现以本地工作流为中心展开，重点是保留**本地原生终端体验**，支持原生使用以及高级参数注入，并在此基础上提供微信侧的远程输入、结果回流与状态同步能力。
+项目围绕本地工作流设计，重点是保留**本地原生终端体验**：你仍然在本地使用原生 CLI 和高级启动参数，微信负责远程输入、结果回流与状态同步。
-<p align='center'><img src='docs/images/animation.webp' width=90%></p>
+<p align='center'><img src='docs/images/animation.webp' width=90%></p>
-## 这个项目解决什么问题
+## 文档导航
-本项目面向这样一类使用场景：
+- [问题排查](docs/troubleshooting.md)：上下文 token、网络代理、本地 endpoint、已知限制等常见问题。
+- [运行配置](docs/configuration.md)：数据目录、上传大小限制、调试开关等环境变量。
+- [开发说明](docs/development.md)：源码运行、测试、构建、打包和全局 smoke 验证。
+- [发布说明](docs/releases/README.md)：各版本变更与升级说明。
+## 这个项目解决什么问题？
+本项目适合这样的使用场景：
 - 你的主工作流仍在本地终端中进行；
-- 你希望继续使用原生 `codex` 或其他 CLI 工具，而不是迁移到网页或托管机器人；
-- 你希望在离开电脑时，仍能通过微信向本地会话发送请求，并接收必要的输出、与状态同步。
+- 你希望继续使用 Codex、Claude Code、OpenCode 等原生 CLI，而不是迁移到网页或托管机器人；
+- 你希望离开电脑后，仍能通过微信向本地会话发送请求，并接收必要输出和状态更新。
-当前项目并不试图把微信变成新的主工作界面。相反，它的定位是：
+本项目不试图把微信变成新的主工作界面。它的定位是：
 - 本地 CLI 仍然是主工作界面，并保持原生的使用逻辑；
-- 微信是远程入口，允许远程接入；
+- 微信是远程入口，用来接入本地会话；
 - 会话一致性、线程状态和审批流仍以**本地会话为中心**。
 ## 快速开始
@@ -36,109 +46,86 @@
 ### 1. 环境要求
 - [Node.js](https://nodejs.org/en/download) `>= 24.0.0`（建议直接安装官网 LTS 版本）
-- [Bun](https://bun.sh/docs/installation) `>= 1.0.0` （开发者需要，普通用户无需安装）
-- 已安装以下至少一种本地 CLI：（最好更新至最新版本）
+- 已安装以下任意一种本地 CLI，并尽量保持最新版本：
   - [Codex](https://github.com/openai/codex)
   - [Claude Code](https://code.claude.com/docs/en/overview)
-  - OpenCode
-  - powershell.exe
+  - [OpenCode](https://github.com/anomalyco/opencode)
 ### 2. 安装
-正式版本可以直接从 npm 安装：
+发布版本可以直接从 npm 安装：
 ```bash
-npm install -g @unlinearity/cli-wechat-bridge@latest
+npm install -g cli-wechat-bridge@latest
 ```
-安装后可在任意项目目录中直接使用 `wechat-daemon`、`wechat-codex-start`、`wechat-claude-start`、`wechat-opencode-start` 等命令。
+安装后，可以在任意项目目录中使用 `wechat-daemon`、`wechat-codex-start`、`wechat-claude-start`、`wechat-opencode-start` 等命令。
-如果你希望从源码运行或参与开发，也可以克隆仓库并安装依赖：
+兼容性说明：旧包名 `@unlinearity/cli-wechat-bridge` 会继续同步发布，已经安装旧包名的用户可以正常升级；新用户优先使用更短的 `cli-wechat-bridge`。
-```bash
-git clone https://github.com/UNLINEARITY/CLI-WeChat-Bridge
-cd CLI-WeChat-Bridge
-bun install
-```
+### 3. 完成微信登录
-如果使用源码仓库，希望将当前工作区安装为全局命令：
+全局安装后运行：
 ```bash
-npm install -g .
+wechat-setup
 ```
-开发阶段也可以使用：
+登录流程会：
-```bash
-npm link
-```
-说明：
+1. 获取微信登录二维码；
+2. 在终端打印二维码；
+3. 等待你在微信中扫码并确认；
+4. 保存本地登录凭据。
-- `npm link` 会让全局命令直接指向当前仓库源码；
-- `npm install -g .` 会安装一份当前仓库的复制版本；后续代码更新后需要重新执行一次。
+![微信登录二维码](docs/images/image-0.png)
-如果你想把当前本地源码构建出的包安装到真实全局环境，并在任意目录人工验证，可以直接运行：
+登录成功后，程序会清理旧的同步游标和上下文 token，避免旧会话状态污染新的登录状态。数据目录、状态文件和旧版本迁移说明见 [问题排查](docs/troubleshooting.md#数据目录与状态文件)。
-```bash
-npm run smoke:global
-```
+首次安装或微信登录过期时，`wechat-codex-start`、`wechat-claude-start`、`wechat-opencode-start` 也会在前台提示扫码登录。
-这个脚本会先用当前源码打出真实 npm tarball，再执行 `npm install -g <tarball>` 安装到真实全局环境；脚本结束后，你可以离开仓库目录运行 `wechat-codex-start` 等命令。如果你想先清理缓存、卸载当前全局包，或者顺便跑完整质量门禁，可以加上这些参数：
+### 4. 先从微信发一条同步消息（重要）
-```bash
-npm run smoke:global -- --purge-global --clean-cache --full
-```
+启动 bridge 后，建议先在微信里向 Bot 发送一条消息，例如 `hello`、你要执行的任务，或任意一句话。这样 bridge 能拿到最新的微信会话 `context_token`，之后本地终端中的输入、最终回复和审批提示才能稳定同步回微信。
-- `--clean-cache`：先执行 `npm cache clean --force`
-- `--purge-global`：先卸载当前真实全局包
-- `--full`：额外执行 `npm run quality`
-- `--keep-tarball`：保留生成的 tarball，方便排查
+如果冷启动或长时间闲置后直接从本地终端先发消息，bridge 通常仍会捕获这条本地输入并交给 Codex / Claude Code / OpenCode 处理，但回发到微信时可能因为旧的 `context_token` 失效而失败。表现是：本地已经有回复，微信暂时收不到；等你先从微信发来一条消息后，后续双向同步就能恢复正常。
-### 3. 完成微信登录
+### 5. 单命令启动桥接（兼容模式）
-npm 全局安装后可以直接运行：
+先进入需要操作的项目目录：
 ```bash
-wechat-setup
-```
-如果是在 clone 的仓库目录下，也可以运行：
-```bash
-bun run setup # 绑定微信 ClawBot
-```
-该流程会：
-1. 获取微信登录二维码；
-2. 在终端打印二维码；
-3. 等待你在微信中扫码并确认；
-4. 将 bot 凭据写入本地数据目录。
-![alt text](docs/images/image-0.png)
-默认凭据文件路径：
-```text
-~/.cli-bridge/account.json
+cd D:\work\your-project
 ```
-登录成功后会清理旧的 `sync_buf.txt` 和 `context_tokens.json`，避免旧会话状态污染新的登录状态。
+然后选择一个单命令入口：
-从旧版本升级时，bridge 会自动从旧的 `~/.claude/channels/wechat` 迁移数据到 `~/.cli-bridge`，包括登录凭据、同步游标、上下文 token、工作区状态和已接收附件；已有的新目录文件不会被覆盖，旧目录也会原样保留。旧运行锁不会迁移，旧 `bridge.log` 会保存为 `legacy-bridge.log`，避免覆盖新的运行日志。
+| 使用的本地 CLI | 启动命令 |
+| --- | --- |
+| Codex | `wechat-codex-start` |
+| Claude Code | `wechat-claude-start` |
+| OpenCode | `wechat-opencode-start` |
-如果是首次安装或微信登录已过期，`wechat-codex-start`、`wechat-claude-start`、`wechat-opencode-start` 也会在前台提示扫码登录。
+这些启动器会自动完成以下动作：
-### 4. 先从微信发一条同步消息（重要）
+1. 校验或刷新微信登录凭据；
+2. 如果当前目录已有 `wechat-daemon`，则委托 daemon 切换到对应 CLI；
+3. 如果没有 daemon，则复用当前目录中已运行的 bridge，或在当前目录启动新的 bridge；
+4. 如果已有独立 bridge 正在服务其他目录，则停止旧 bridge 并切换到当前目录；
+5. 等待当前目录对应的本地 companion endpoint 就绪；
+6. 打开可见的本地 CLI 会话。
-启动 bridge 后，建议先在微信里向 Bot 发送一条消息，例如 `hello`、你要执行的任务或任意一句话。这样 bridge 能拿到最新的微信会话 `context_token`，之后本地终端里的输入、最终回复和审批提示才能稳定同步回微信。
+没有 daemon 时，`wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 仍按**单活工作区切换器**工作：
-如果冷启动或长时间闲置后直接从本地终端先发消息，bridge 通常仍会捕获这条本地输入并交给 Codex / Claude Code / OpenCode 处理，但微信侧出站发送可能因为旧的 `context_token` 失效而失败。表现就是：本地已经有回复，微信暂时收不到；等你先从微信发来一条消息后，后续双向同步就能恢复正常。
+- 同一时间只有一个项目与微信对话；
+- 在当前目录重复执行是幂等的；
+- 如果当前目录已经有可见 companion / panel 在运行，则不会重复打开第二个窗口；
+- 如果检测到可见端仍在运行但 worker 状态异常（如 `stopped` / `error`），会自动重启 bridge 再重新打开可见端；
+- 在其他目录执行会显式切换活动工作区。
-### 5. 常驻 daemon 模式（推荐用于多 CLI 切换）
+### 6. 常驻 daemon 模式（支持多 CLI 切换）
-如果你希望微信连接长期保持在线，并在 Codex / Claude Code / OpenCode 之间来回切换，推荐在项目目录启动一个统一 daemon：
+如果你希望微信连接长期保持在线，并在 Codex / Claude Code / OpenCode 之间来回切换，可以在项目目录启动统一 daemon：
 ```bash
 cd D:\work\your-project
@@ -150,12 +137,14 @@ wechat-daemon
 | 指令 | 行为 |
 | --- | --- |
 | `/codex` | 切换到 Codex |
-| `/claude` | 切换到 Claude Code |
-| `/opencode` | 切换到 OpenCode |
-daemon 启动后，后续切换都可以直接从微信发起；如果对应 CLI 还没有可见窗口，daemon 会自动打开或复用它，不需要再手动运行 `wechat-codex`、`wechat-claude` 或 `wechat-opencode`。
-daemon 的 v1 行为是：
+| `/claude` | 切换到 Claude Code |
+| `/opencode` | 切换到 OpenCode |
+daemon 启动后，后续切换都可以直接从微信发起；如果对应 CLI 还没有可见窗口，daemon 会自动打开或复用它，不需要再手动运行 `wechat-codex`、`wechat-claude` 或 `wechat-opencode`。
+![多CLI 示例](docs/images/image-9.png)
+当前 daemon 行为如下：
 - daemon 绑定启动时的工作目录；暂不支持在微信里切换工作目录；
 - 启动时会自动接管并清理旧的单 bridge 进程、失效 lock 和旧 endpoint；
@@ -163,53 +152,20 @@ daemon 的 v1 行为是：
 - 如果对应适配器已经有可见 CLI 在运行，则直接复用；
 - 如果还没有对应 CLI，daemon 会自动打开一个新的可见终端；
 - Codex / Claude / OpenCode 的重要输出都会带上 `[codex]`、`[claude]`、`[opencode]` 标签再发回微信；
-- 可以在微信发送 `/daemon-stop` 停止 daemon。
+- 可以在微信里发送 `/daemon-stop` 停止 daemon。
-也可以启动时直接打开某个初始 CLI：
+也可以在启动时指定初始 CLI：
 ```bash
 wechat-daemon --adapter codex
 wechat-daemon --adapter claude --profile work
 ```
-当同一工作目录已有 `wechat-daemon` 在运行时，`wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 会自动委托给 daemon：请求 daemon 切到对应 CLI，并在需要时打开可见终端，而不是停止 daemon 或关闭其他 CLI。
-### 6. 单命令启动桥接（兼容模式）
-先进入你要操作的项目目录：
-```bash
-cd D:\work\your-project
-```
-推荐直接选择一个单命令入口：
-| 使用的本地 CLI | 启动命令 |
-| --- | --- |
-| Codex | `wechat-codex-start` |
-| Claude Code | `wechat-claude-start` |
-| OpenCode | `wechat-opencode-start` |
+当同一工作目录已有 `wechat-daemon` 在运行时，`wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 会自动委托给 daemon：请求 daemon 切到对应 CLI，并在需要时打开可见终端，不会停止 daemon 或关闭其他 CLI。
-三者会自动完成以下动作：
-1. 校验或刷新微信登录凭据；
-2. 如果当前目录已有 `wechat-daemon`，则委托 daemon 切换到对应 CLI；
-3. 如果没有 daemon，则复用当前目录已运行的 bridge，或在当前目录启动新的 bridge；
-4. 如果独立 bridge 正在服务其他目录，则停止旧 bridge 并切换到当前目录；
-5. 等待当前目录对应的本地 companion endpoint 就绪；
-6. 打开可见的本地 CLI 会话。
+### 7. 手动双终端模式（高级调试）
-在没有 daemon 时，`wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 仍按**单活工作区切换器**工作：
-- 同一时间只有一个项目与微信对话；
-- 在当前目录重复执行是幂等的；
-- 如果当前目录已经有可见 companion / panel 在运行，则不会重复打开第二个窗口；
-- 如果检测到可见端仍在但 worker 状态异常（如 `stopped` / `error`），会自动重启 bridge 再重新打开可见端；
-- 在其他目录执行会显式切换活动工作区。
-### 7. 手动双终端模式（调试开发）
-如果你希望明确观察 bridge 与本地 CLI companion，也可以分两个终端启动。
+如果你希望明确观察 bridge 与本地 CLI companion，也可以用两个终端分别启动。
 | 适配器 | 终端 A：bridge | 终端 B：本地 companion |
 | --- | --- | --- |
@@ -219,56 +175,30 @@ cd D:\work\your-project
 ## 适配器支持情况
-> 目前支持将本地文件传输至微信
+> 目前支持将本地文件发送到微信,微信也允许发送文件给本地 cli 解析 （注意模型本身要具备处理对应文件的能力！）
 ![文件传输](docs/images/image-8.png)
-微信发来的图片和普通文件也会被接收并保存到本地数据目录：
+微信发来的图片和普通文件也会被接收并保存到本地：
-- 保存位置：`~/.cli-bridge/inbound-attachments/<日期>/`
-- bridge 会把本地路径追加到转发给 Codex / Claude Code / OpenCode 的 prompt 中，模型可按需读取或解析这些文件；
-- 当前不会自动 OCR 图片，也不会自动抽取 PDF / DOCX 正文；解析动作由本地 CLI 根据路径完成。
+- bridge 会将本地路径追加到转发给 Codex / Claude Code / OpenCode 的 prompt 中，模型可按需读取或解析这些文件；
+- 当前不会自动 OCR 图片，也不会自动抽取 PDF / DOCX 正文；如需解析，由本地 CLI 根据路径完成。
+- 具体保存位置见 [问题排查](docs/troubleshooting.md#数据目录与状态文件)。
 | 适配器 | 当前状态 | 说明 |
 | --- | --- | --- |
-| `codex` | 已接入 | 双终端模式；本地 companion 为线程权威；微信跟随本地线程 |
-| `claude` | 已接入 | `wechat-bridge-claude` + `wechat-claude` 的双终端 companion 模式；会话切换、最终回复与审批元数据已按 Claude session 语义同步 |
-| `opencode` | 已接入 | `wechat-bridge-opencode` + `wechat-opencode` 的双终端 companion 模式；支持本地 session 切换跟随，微信侧支持 `/new` / `/new-session` |
-| `shell` | 可用 | 持久 `powershell.exe` 会话；高风险命令支持审批 |
+| `codex` | 已接入 | 双终端模式；本地 companion 作为线程权威；微信跟随本地线程 |
+| `claude` | 已接入 | `wechat-bridge-claude` + `wechat-claude` 的双终端 companion 模式；会话切换、最终回复与审批元数据按 Claude session 语义同步 |
+| `opencode` | 已接入 | [`OpenCode`](https://github.com/anomalyco/opencode) 适配器；`wechat-bridge-opencode` + `wechat-opencode` 的双终端 companion 模式；支持本地 session 切换跟随，微信侧支持 `/new` / `/new-session` |
 ### Codex 示例
-终端 A：
-```bash
-wechat-bridge-codex
-```
-![alt text](docs/images/image-1.png)
-终端 B：
-```bash
-wechat-codex
-```
-![alt text](docs/images/image-2.png)
-然后即可：
-- 在微信中发送普通文本；
-- 在本地 `wechat-codex` 中继续原生交互；
-- 在本地执行 `/resume` 切线程；
-- 让微信自动跟随当前本地线程。
 ![Codex windows](docs/images/image-3.png)
 ![Codex Linux](docs/images/image-4.png)
 ### Claude Code 示例
-Claude Code 支持通过微信完成远程审批确认。
 ![Claude Windows](docs/images/image-6.png)
 ![Claude Linux](docs/images/image-7.png)
@@ -279,7 +209,7 @@ OpenCode 模式下，微信侧支持 `/new` 或 `/new-session` 创建新 session
 ## 命令说明
-### 推荐全局命令
+### 常用全局命令
 | 类型 | 命令 |
 | --- | --- |
@@ -288,27 +218,6 @@ OpenCode 模式下，微信侧支持 `/new` 或 `/new-session` 创建新 session
 | Codex | `wechat-bridge-codex`、`wechat-codex`、`wechat-codex-start` |
 | Claude Code | `wechat-bridge-claude`、`wechat-claude`、`wechat-claude-start` |
 | OpenCode | `wechat-bridge-opencode`、`wechat-opencode`、`wechat-opencode-start` |
-| Shell | `wechat-bridge-shell` |
-### 仓库内开发入口
-```bash
-bun run setup
-bun run daemon
-bun run bridge:codex
-bun run codex:panel
-bun run codex:start
-bun run bridge:claude
-bun run claude:companion
-bun run claude:start
-bun run bridge:opencode
-bun run opencode:panel
-bun run opencode:start
-bun run bridge:shell
-bun run bridge:bun -- --adapter codex
-bun run check
-bun run test
-```
 ### Daemon CLI 参数
@@ -328,7 +237,7 @@ wechat-daemon --adapter claude --profile work
 - `--cwd <path>`：指定 daemon 绑定的工作目录；
 - `--adapter <codex|claude|opencode>`：启动 daemon 后立即切换到指定 CLI；
-- `--profile <name-or-path>`：传给 daemon 创建的适配器；
+- `--profile <name-or-path>`：传给 daemon 创建的对应适配器；
 - `--no-open`：只创建 bridge slot，不自动打开可见 CLI。
 ### Bridge CLI 参数
@@ -339,7 +248,6 @@ wechat-daemon --adapter claude --profile work
 - `wechat-bridge-codex`
 - `wechat-bridge-claude`
 - `wechat-bridge-opencode`
-- `wechat-bridge-shell`
 示例：
@@ -348,15 +256,13 @@ wechat-bridge --adapter codex --cwd D:\work\my-project
 wechat-bridge-codex --cwd D:\work\my-project
 wechat-bridge-claude --profile work
 wechat-bridge-opencode --cwd D:\work\my-project
-wechat-bridge-shell --cmd pwsh.exe
 wechat-bridge-codex --lifecycle companion_bound
 ```
 支持参数：
-- `--adapter <codex|claude|opencode|shell>`：通用入口 `wechat-bridge` 需要显式指定适配器；
+- `--adapter <codex|claude|opencode>`：通用入口 `wechat-bridge` 需要显式指定适配器；
 - `--cwd <path>`：指定工作目录；
-- `--cmd <executable>`：覆盖默认命令；
 - `--profile <name-or-path>`：向适配器传入 profile；
 - `--lifecycle <persistent|companion_bound>`：指定 bridge 生命周期；`wechat-*-start` 会使用 `companion_bound`。
@@ -376,7 +282,7 @@ wechat-opencode-start --cwd D:\work\my-project
 - `--profile <name-or-path>`：转发给后台启动的 `wechat-bridge-codex` / `wechat-bridge-claude` / `wechat-bridge-opencode`；
 - `--timeout-ms <ms>`：等待当前目录 endpoint 的最长时间，默认 `15000`。
-高级用法：除上述启动器参数外，未知参数会继续透传给可见的底层 CLI。这样可以在保留微信登录、工作区切换与 bridge 生命周期管理的同时，启用 Codex / Claude Code 自己的高级启动模式。
+高级用法：除上述启动器参数外，未知参数会继续透传给可见的底层 CLI。这样既能保留微信登录、工作区切换与 bridge 生命周期管理，也能启用 Codex / Claude Code 自己的高级启动模式。
 ```bash
 wechat-codex-start --yolo
@@ -385,22 +291,22 @@ wechat-claude-start --dangerously-skip-permissions
 wechat-claude-start --model sonnet --dangerously-skip-permissions
 ```
-其中 `--yolo` 会传给 Codex；`--dangerously-skip-permissions` 会传给 Claude Code。它们只影响本地可见 CLI，不会覆盖 bridge 托管的 Codex remote 连接参数、Claude settings、微信登录状态或当前工作区锁。由于这两类参数会降低审批保护，建议只在可信工作区中使用。
+其中，`--yolo` 会传给 Codex；`--dangerously-skip-permissions` 会传给 Claude Code。它们只影响本地可见 CLI，不会覆盖 bridge 托管的 Codex remote 连接参数、Claude settings、微信登录状态或当前工作区锁。由于这两类参数会降低审批保护，建议只在可信工作区中使用。
 ## 微信侧支持的指令
 | 指令 | 说明 |
 | --- | --- |
-| 普通文本 | 发送给当前活动会话 |
+| 普通文本 | 发送到当前活动会话 |
 | `/codex` / `/claude` / `/opencode` | daemon 模式下切换活动 CLI；已有 CLI 会复用，没有则自动打开 |
 | `/status` | 查看 bridge 当前状态 |
 | `/stop` | 中断当前任务 |
 | `/reset` | 重建当前本地会话 |
 | `/new` 或 `/new-session` | OpenCode 模式下新建 session |
-| `/confirm` / `/deny` | 处理 Claude Code 权限请求；shell 等需要一次性 code 的请求会在消息中提示具体确认格式 |
+| `/confirm` / `/deny` | 处理 CLI 权限请求；需要一次性 code 的请求会在消息中提示具体确认格式 |
 | `/daemon-stop` | daemon 模式下停止常驻进程 |
-说明：微信侧 `/resume` 目前仍保持禁用；需要切换 Codex / Claude / OpenCode 会话时，优先在本地 companion 中使用原生 `/resume`、`/new` 或对应 CLI 命令，微信会跟随本地活动会话。
+说明：微信侧 `/resume` 目前暂时保持禁用；需要切换 Codex / Claude / OpenCode 会话时，优先在本地 companion 中使用原生 `/resume`、`/new` 或对应 CLI 命令，微信会跟随本地活动会话。
 ## 工作区模型
@@ -408,9 +314,9 @@ wechat-claude-start --model sonnet --dangerously-skip-permissions
 - 从哪个目录启动 `wechat-bridge-codex` / `wechat-bridge-claude` / `wechat-bridge-opencode`，哪个目录就是当前工作区；
 - 对应的本地 companion 必须连接同一工作区；
-- 不同工作区的状态文件相互隔离。
+- 不同工作区的运行状态相互隔离。
-当前支持两种运行模型：
+目前支持两种运行模型：
 - 独立 bridge：单 owner、单 bridge、单活动工作区；
 - `wechat-daemon`：单 owner、单 daemon、绑定一个启动工作区，但可在这个工作区内同时保留 Codex / Claude Code / OpenCode 三个 CLI slot。
@@ -418,48 +324,9 @@ wechat-claude-start --model sonnet --dangerously-skip-permissions
 对 `wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 来说，这意味着：
 - 如果同一工作区已有 daemon，它们会委托 daemon 切换 CLI；
-- 如果没有 daemon，它们是**单活工作区切换器**；
+- 如果没有 daemon，它们会作为**单活工作区切换器**工作；
 - 当前目录重复执行是幂等的；
-- 其他目录重复执行会触发工作区切换，而不是并行多开。
-## 数据目录与状态文件
-默认数据目录：
-```text
-~/.cli-bridge
-```
-主要文件如下：
-| 路径 | 作用 |
-| --- | --- |
-| `account.json` | 微信凭据 |
-| `sync_buf.txt` | iLink 增量同步游标 |
-| `context_tokens.json` | 微信上下文 token 缓存 |
-| `bridge.log` | bridge 运行日志 |
-| `bridge.lock.json` | bridge 运行锁 |
-| `daemon-endpoint.json` | `wechat-daemon` 本地 IPC endpoint |
-| `inbound-attachments/` | 微信入站图片和普通文件的本地保存目录 |
-| `workspaces/<workspace-key>/bridge-state.json` | 当前工作区状态 |
-| `workspaces/<workspace-key>/codex-panel-endpoint.json` | 当前工作区 companion endpoint；文件名保留历史兼容 |
-| `workspaces/<workspace-key>/<adapter>-companion-endpoint.json` | daemon / 多适配器模式下的适配器独立 companion endpoint |
-### 环境变量
-| 变量名 | 说明 |
-| --- | --- |
-| `WECHAT_ILINK_BASE_URL` | 覆盖默认 iLink API 地址 |
-| `CLI_BRIDGE_DATA_DIR` | 覆盖默认数据目录 |
-| `WECHAT_MAX_IMAGE_MB` | 覆盖图片上传大小限制，默认 20 MB |
-| `WECHAT_MAX_FILE_MB` | 覆盖普通文件上传大小限制，默认 50 MB |
-| `WECHAT_MAX_VOICE_MB` | 覆盖语音上传大小限制，默认 20 MB |
-| `WECHAT_MAX_VIDEO_MB` | 覆盖视频上传大小限制，默认 100 MB |
-| `WECHAT_MAX_INBOUND_IMAGE_MB` | 覆盖微信入站图片下载大小限制，默认 20 MB |
-| `WECHAT_MAX_INBOUND_FILE_MB` | 覆盖微信入站普通文件下载大小限制，默认 50 MB |
-| `WECHAT_OPENCODE_DEBUG` | 开启 OpenCode 适配器调试输出 |
-旧版 `CLAUDE_WECHAT_CHANNEL_DATA_DIR` 不再作为活动数据目录配置项；如旧环境中设置过该变量，它只会被视为一次性旧数据迁移来源。新的自定义目录请使用 `CLI_BRIDGE_DATA_DIR`。
+- 在其他目录执行会触发工作区切换，而不是并行多开。
 ## 版本更新
@@ -481,155 +348,50 @@ wechat-check-update
 ### 获取最新版本
-如果你使用 npm 全局安装，当前推荐直接执行：
+如果你使用 npm 全局安装，建议直接执行：
 ```bash
-npm install -g @unlinearity/cli-wechat-bridge@latest
+npm install -g cli-wechat-bridge@latest
 ```
 升级后请重启正在运行的 bridge 和 companion 终端，确保它们加载同一版本。
-如果你使用源码仓库，可以使用以下命令更新：
-```bash
-cd CLI-WeChat-Bridge
-git pull
-bun install
-npm install -g .
-```
-## 常见问题
-### 1. `wechat-codex` / `wechat-claude` / `wechat-opencode` 提示找不到 bridge
-通常原因如下：
-- 还没有先启动对应的 `wechat-bridge-*`；
-- bridge 与 companion 不在同一个目录；
-- 当前工作区 endpoint 文件不存在或来自旧进程。
-建议先确认两个终端在同一目录；如果不想手动分两个终端，可以改用对应的 `wechat-codex-start`、`wechat-claude-start` 或 `wechat-opencode-start`。
-### 2. 全局命令不存在
-请确认已经执行以下之一：
-```bash
-npm install -g @unlinearity/cli-wechat-bridge@latest
-npm install -g .
-npm link
-```
-如果命令仍不存在，请检查 npm 全局 bin 目录是否已加入 `PATH`。
-### 3. Windows 下出现 `codex.ps1` 或 PowerShell profile 警告
-项目已经尽量规避 `codex.ps1`：
-- 优先查找 vendor `codex.exe`；
-- 必要时通过 `cmd.exe` 包装 `codex.cmd`。
-如果本机 PowerShell profile 本身受执行策略限制，终端仍可能打印相关警告。这通常不是 bridge 本身故障。
-### 4. 微信上提示没有 context token
-通常表示当前联系人还没有建立可用的 iLink 上下文。一般先由 owner 账号发送一条普通消息即可建立上下文。
-### 5. `codex is still working...`
-该提示只应在当前确实存在活动任务时出现。
-如果偶发出现：
-1. 先确认本地 `wechat-codex` 是否真的仍在执行任务；
-2. 必要时使用 `/stop`；
-3. 检查：
-```text
-~/.cli-bridge/bridge.log
-```
-### 6. 本地 `/resume` 后微信不同步
-请优先确认：`wechat-bridge-codex` 与 `wechat-codex` 是否都已重启到同一版本。
-部分设备可能存在第一次本地输入不同步到微信的情况，可以先微信发送指令来建立连接。
-### 7. `wechat_send_failed` 或 `UND_ERR_CONNECT_TIMEOUT`
-如果 `bridge-state.json` 看起来正常，但微信仍然没有收到回复，优先检查：
-```text
-~/.cli-bridge/bridge.log
-```
-如果日志中出现 `wechat_send_failed`、`UND_ERR_CONNECT_TIMEOUT` 或 `ilinkai.weixin.qq.com:443`，通常是 bridge 到 iLink 的出站网络或代理问题，而不是本地 CLI 没有完成任务。请确认当前终端是否继承 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`，以及 Node 是否需要 `NODE_OPTIONS=--use-env-proxy`。
-## 已知限制
-- 微信 `/resume` 暂时被禁用（可能导致对话双向不稳定）
-- Codex 不支持底层任务的远程审批！建议给好权限，正常使用，几乎不会主动请求较为低级的远程审批；Claude Code 支持远程审批，但是测试的不够，如有问题可以提 issue。
-- `wechat-daemon` v1 绑定启动工作区；暂不支持从微信切换到另一个本地目录。
-## 开发说明
-### 主要入口
-| 文件 | 作用 |
-| --- | --- |
-| `src/bridge/wechat-bridge.ts` | bridge 主事件循环 |
-| `src/daemon/wechat-daemon.ts` | 常驻 WeChat daemon 与多 CLI slot 管理 |
-| `src/daemon/daemon-link.ts` | daemon 本地 IPC endpoint 与请求协议 |
-| `src/bridge/bridge-adapters.ts` | `codex` / `claude` / `opencode` / `shell` 适配器入口 |
-| `src/bridge/bridge-adapters.opencode.ts` | OpenCode 适配器实现 |
-| `src/companion/local-companion.ts` | `wechat-claude` / `wechat-opencode` 本地 companion 入口 |
-| `src/companion/codex-remote-client.ts` | `wechat-codex` 本地客户端入口 |
-| `src/companion/local-companion-start.ts` | `wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 单命令启动入口 |
-| `src/wechat/wechat-transport.ts` | iLink 消息收发 |
-| `src/bridge/bridge-state.ts` | bridge 状态、锁与日志 |
-| `src/wechat/setup.ts` | 登录与凭据初始化 |
-### 测试
-```bash
-bun test
-```
-也可以按目录运行：
+## 致谢
-```bash
-bun run test:bridge
-bun run test:companion
-bun run test:wechat
-```
+### 感谢支持
-当前测试主要覆盖：
+> 感谢 issue 反馈者和 PR 贡献者。
-- Windows 启动解析
-- Codex 线程跟随
-- session log fallback
-- panel / busy / completion recovery
-- 工作区路径与状态隔离
+创作不易，如果觉得它有帮助或有意思，可以请喝杯奶茶。❤️
-## 致谢
+<p align='center'><img src='docs/images/wechat-tip.png' width=60%></p>
 ### 相关链接
-- [Linux DO](https://linux.do/)：学AI，上L站！
-- [openclaw-weixin](https://github.com/hao-ji-xing/openclaw-weixin)：支持Claude Code Channel,感谢如此迅速的开源。
-- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)：TypeScript 版 MCP SDK
+主要依赖：
+- [@opencode-ai/sdk](https://www.npmjs.com/package/@opencode-ai/sdk)：OpenCode session 和事件流客户端
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)：MCP server 入口使用的 TypeScript SDK
 - [node-pty](https://github.com/microsoft/node-pty)：本地 PTY / ConPTY 进程桥接
-- [@anthropic-ai/sdk](https://github.com/anthropics/anthropic-sdk-typescript)：Anthropic TypeScript SDK
 - [qrcode-terminal](https://github.com/gtanner/qrcode-terminal)：终端二维码输出
-### 感谢支持
+运行与开发基础：
-> 感谢 issue 反馈者 和 pr 贡献者。
+- [Node.js](https://nodejs.org/)：运行发布包和 CLI 入口
+- [TypeScript](https://www.typescriptlang.org/)：源码语言和构建工具链
+- [Bun](https://bun.sh/)：源码模式运行与测试工具
+- [ESLint](https://eslint.org/)：代码检查
-创作不易，如感觉对您有帮助、觉得有意思，可以请喝杯奶茶。❤️
+社区与参考：
-<p align='center'><img src='docs\images\wechat-tip.png' width=60%></p>
+- [Linux DO](https://linux.do/)：学 AI，上 L 站！
+- [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)：腾讯微信团队发布的 OpenClaw Weixin channel npm 包
+- [openclaw-weixin](https://github.com/hao-ji-xing/openclaw-weixin)：早期 WeChat / Claude Code Channel 参考项目。
 ## License
 [MIT](LICENSE.txt)
+<p align="center">
+  <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=UNLINEARITY/CLI-WeChat-Bridge&type=timeline&legend=top-left">
+</p>