claude-codex-wechat 0.1.0 → 0.1.6

package/README.md

@@ -1,100 +1,50 @@
 # claude-codex-wechat
 
-`claude-codex-wechat` 是一个本地桥接服务，用来把：
+`claude-codex-wechat` 是一个本地 bridge daemon。它把：
 
-- 微信 bot 通道
-- 本地原生 `Claude Code`
-- 本地原生 `Codex CLI`
+- WeChat direct 通道
+- 本机原生 `Claude Code`
+- 本机原生 `Codex CLI`
 
-接起来，让你可以直接在微信里和本机上的 `Claude Code` / `Codex` 对话，并保留本地原生会话恢复能力。
+接起来，让 WeChat 用户可以直接驱动本机上的原生 CLI 会话，并尽量保留原生 resume 能力。
 
-这个项目的定位是：
+这个仓库的定位不是另起一套 agent runtime，也不是 ACP bridge。它的目标一直是：
 
-- **本地运行**
-- **微信 -> 本地原生 CLI**
-- **Native Provider Bridge**
-- **不是 ACP bridge**
+- WeChat 作为人类控制面
+- 本地原生 CLI 作为真实执行面
+- 两边尽量共享同一条原生会话恢复链路
 
----
+## 当前能力
 
-## 项目做什么
+当前实现覆盖的主能力：
 
-这个仓库当前已经实现的主能力有：
+- WeChat direct 模式接入
+- WeChat 轮询收消息与主动回消息
+- 本地原生 `Claude Code` / `Codex CLI` 会话桥接
+- 会话持久化与当前会话恢复
+- 原生 Claude / Codex recoverable session 列表与 attach
+- 本地管理页
+- npm 全局安装与生产 CLI 入口
+- 本地发布 npm 包
 
-- 微信 direct 模式接入，走官方 `getupdates` / `sendmessage`
-- 微信扫码登录与 bot token 获取
-- 微信消息路由到本地 `Claude Code` / `Codex CLI`
-- 会话持久化到 SQLite
-- 原生 Claude / Codex 会话扫描
-- 原生会话手动接入
-- 原生会话自动接入
-- 桥接会话与原生会话绑定持久化
-- 管理页支持：
-  - pairing 审批
-  - 授权用户管理
-  - provider 切换
-  - 会话停止 / 归档
-  - 权限审批
-  - 原生恢复修复
-- Claude 原生恢复能力：
-  - `claude --resume <sessionId>`
-  - `claude -r '<完整标题>'`
-- Codex 原生恢复能力：
-  - `codex resume <sessionId>`
-  - `codex resume '<thread_name>'`
-
----
-
-## 当前实现目标
-
-这个仓库的核心目标不是“做一个微信聊天 UI”，而是：
-
-1. 把微信消息稳定接进本地 bridge
-2. 把 bridge 会话稳定映射到本地原生 Claude / Codex 会话
-3. 让微信侧会话尽可能和本地原生会话恢复链路对齐
-
-其中 Claude 这条链路尤其强调：
-
-- bridge session 有自己的 `resumeTitle`
-- 原生会话文件里有对应标题
-- `~/.claude/history.jsonl` 里也有对应标题
-
-只有这几层都对齐，`claude -r '<完整标题>'` 才真正可用。
-
----
-
-## 目录说明
+## 项目结构
 
 主要目录：
 
 - `src/`
-  - bridge 主实现
-  - 微信通道
-  - provider 接入
-  - daemon / admin routes / web
+  - daemon、provider、session、channel、web 主实现
 - `tests/`
-  - 单元测试
-  - bridge 运行态测试
-  - 微信 direct 流程测试
-  - 前端交互测试
+  - 单元测试、运行态测试、前端测试
 - `scripts/`
-  - 正式恢复入口
-  - 联调启动脚本
-  - 诊断脚本
+  - 诊断与辅助脚本
 - `docs/`
-  - 详细运行说明
-  - 对齐过程文档
-  - 参考实现文档
-
-脚本分层索引见：
-
-- [scripts/README.md](./scripts/README.md)
+  - 设计说明、对齐文档、参考资料
 
----
+脚本说明见 [scripts/README.md](./scripts/README.md)。
 
 ## 安装
 
-### 方式 A：作为 npm 包全局安装（推荐普通用户）
+### 作为 npm 包安装
 
 ```bash
 npm install -g claude-codex-wechat
@@ -102,55 +52,50 @@ npm install -g claude-codex-wechat
 pnpm add -g claude-codex-wechat
 ```
 
-> 该包依赖原生模块 `better-sqlite3`，安装时会优先下载预编译二进制；少数环境（非主流架构 / 离线）可能需要本地编译工具链（Node ≥ 20、Python、C++ 编译器）。
-
-安装后会得到一个全局命令 `claude-codex-wechat`：
+安装后会得到全局命令：
 
 ```bash
-claude-codex-wechat init      # 在 ~/.claude-codex-wechat/ 写入默认配置
-claude-codex-wechat doctor    # 检查配置、前端产物、claude/codex 可执行文件
-claude-codex-wechat start     # 前台启动 daemon（默认命令）
-claude-codex-wechat print-config   # 打印当前配置
-claude-codex-wechat help      # 查看全部命令
+claude-codex-wechat help
+claude-codex-wechat init
+claude-codex-wechat doctor
+claude-codex-wechat start
+claude-codex-wechat print-config
 ```
 
-启动后访问 `http://127.0.0.1:8787`（端口由 `BRIDGE_PORT` 控制）。
+说明：
 
-前置条件：本机已安装并登录好 `Claude Code` / `Codex CLI`，且准备好微信 bot 的 `token` / `accountId`。
+- 该包依赖 `better-sqlite3`
+- 大多数常见平台会直接下载预编译二进制
+- 少数环境可能需要本地编译工具链
+- Node 版本要求：`>=20`
 
-### 方式 B：从源码开发
+### 从源码安装
 
 ```bash
-cd /path/to/claude-codex-wechat
+cd /Users/liuyuhua/github/claude-codex-wechat
 pnpm install
 ```
 
----
-
-## 本地启动（开发模式）
-
-一条命令同时启动后端与前端管理页（前端以 Vite middleware 模式嵌入同一进程，含热更新）：
-
-```bash
-pnpm dev
-```
-
-启动后访问 `http://127.0.0.1:8787`（端口由 `BRIDGE_PORT` 控制）。
+## CLI 命令
 
-基础校验与构建：
+生产态 CLI 入口在 `dist/server/cli.js`，通过 `bin` 暴露为 `claude-codex-wechat`。
 
-```bash
-pnpm typecheck
-pnpm test
-pnpm build        # = vite build（前端 -> dist/web）+ esbuild（server -> dist/server/cli.js）
-```
+可用命令：
 
-构建产物：
+- `claude-codex-wechat start`
+  - 前台启动 daemon
+- `claude-codex-wechat init`
+  - 写默认配置到 `~/.claude-codex-wechat/config.json`
+- `claude-codex-wechat doctor`
+  - 检查配置、前端产物、`claude`/`codex` 可执行文件
+- `claude-codex-wechat print-config`
+  - 打印当前配置文件
+- `claude-codex-wechat help`
+  - 显示帮助
 
-- `dist/web/` —— 前端静态资源（生产态由 `@fastify/static` 服务）
-- `dist/server/cli.js` —— CLI / daemon 入口（对应 `bin` 字段）
+默认监听地址：
 
----
+- `http://127.0.0.1:8787`
 
 ## 配置
 
@@ -160,18 +105,16 @@ pnpm build        # = vite build（前端 -> dist/web）+ esbuild（server -> di
 ~/.claude-codex-wechat/config.json
 ```
 
-可以从示例复制：
+推荐先初始化：
 
 ```bash
-mkdir -p ~/.claude-codex-wechat
-cp config.example.json ~/.claude-codex-wechat/config.json
+claude-codex-wechat init
 ```
 
 最小配置示例：
 
 ```json
 {
-  "databasePath": "/Users/you/.claude-codex-wechat/bridge.sqlite",
   "wechat": {
     "enabled": true,
     "baseUrl": "https://ilinkai.weixin.qq.com",
@@ -185,11 +128,15 @@ cp config.example.json ~/.claude-codex-wechat/config.json
     "codex": {
       "command": "/opt/homebrew/bin/codex"
     }
+  },
+  "bridge": {
+    "defaultProvider": "claude-code",
+    "defaultWorkspace": "/absolute/path/to/workspace"
   }
 }
 ```
 
-常用环境变量：
+环境变量：
 
 - `BRIDGE_PORT`
 - `BRIDGE_CONFIG`
@@ -200,31 +147,94 @@ cp config.example.json ~/.claude-codex-wechat/config.json
 - `BRIDGE_CLAUDE_COMMAND`
 - `BRIDGE_CODEX_COMMAND`
 
----
+## 本地开发
+
+开发模式启动：
+
+```bash
+pnpm dev
+```
 
-## 常驻运行（守护进程）
+这会：
 
-`claude-codex-wechat start` 默认前台运行。npm 本身不负责守护，长期常驻建议交给成熟的进程管理器。下面三种任选其一。
+- 启动 daemon
+- 在同一进程里挂 Vite middleware
+- 提供本地管理页与前端热更新
 
-### 方式一：pm2（跨平台，最简单）
+开发检查：
 
 ```bash
-npm install -g pm2
-pm2 start claude-codex-wechat --name ccwx -- start
-pm2 logs ccwx          # 看日志
-pm2 restart ccwx       # 重启
-pm2 startup && pm2 save # 开机自启
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+构建产物：
+
+- `dist/web/`
+  - 前端静态资源
+- `dist/server/cli.js`
+  - 生产 CLI / daemon 入口
+
+## 生产运行
+
+生产态通常按下面方式运行：
+
+```bash
+claude-codex-wechat start
 ```
 
-如需自定义端口 / 配置：
+注意：
+
+- 这是前台进程
+- npm 本身不负责守护
+- 长期常驻建议交给进程管理器
+- 如果默认端口已被本程序的后台服务占用，`start` 会先停掉后台服务，再以前台模式启动
+- 如果端口被别的进程占用，`start` 会直接报出占用 PID 和命令，不会强杀陌生进程
+
+### 安装后后台运行
+
+参考 `happier` 的方式，这个仓库现在提供 `service` 命令，把当前 CLI 注册成操作系统服务，而不是在 Node 进程里自己 daemonize。
+
+常用命令：
 
 ```bash
-BRIDGE_PORT=8787 pm2 start claude-codex-wechat --name ccwx -- start
+claude-codex-wechat service install
+claude-codex-wechat service start
+claude-codex-wechat service restart
+claude-codex-wechat service status
+claude-codex-wechat service logs
+claude-codex-wechat service tail
+claude-codex-wechat service stop
+claude-codex-wechat service uninstall
 ```
 
-### 方式二：systemd（Linux）
+当前支持：
 
-创建 `/etc/systemd/system/claude-codex-wechat.service`（把 `User` 和 `ExecStart` 路径换成你的实际值，`which claude-codex-wechat` 可查路径）：
+- macOS：`launchd`（`~/Library/LaunchAgents/`）
+- Linux：`systemd --user`（`~/.config/systemd/user/`）
+
+推荐安装后直接这样：
+
+```bash
+claude-codex-wechat init
+claude-codex-wechat service install
+claude-codex-wechat service status
+```
+
+### pm2
+
+```bash
+npm install -g pm2
+pm2 start claude-codex-wechat --name ccwx -- start
+pm2 logs ccwx
+pm2 restart ccwx
+pm2 startup && pm2 save
+```
+
+### systemd
+
+示例：
 
 ```ini
 [Unit]
@@ -235,7 +245,6 @@ After=network.target
 Type=simple
 User=youruser
 Environment=BRIDGE_PORT=8787
-# 如需指定配置文件：Environment=BRIDGE_CONFIG=/home/youruser/.claude-codex-wechat/config.json
 ExecStart=/usr/bin/claude-codex-wechat start
 Restart=on-failure
 RestartSec=5
@@ -244,17 +253,9 @@ RestartSec=5
 WantedBy=multi-user.target
 ```
 
-启用：
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now claude-codex-wechat
-sudo journalctl -u claude-codex-wechat -f   # 看日志
-```
-
-### 方式三：launchd（macOS）
+### launchd
 
-创建 `~/Library/LaunchAgents/com.claude-codex-wechat.plist`（把 `ProgramArguments` 第一项换成 `which claude-codex-wechat` 的实际路径）：
+示例：
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -277,282 +278,147 @@ sudo journalctl -u claude-codex-wechat -f   # 看日志
   <true/>
   <key>KeepAlive</key>
   <true/>
-  <key>StandardOutPath</key>
-  <string>/tmp/claude-codex-wechat.out.log</string>
-  <key>StandardErrorPath</key>
-  <string>/tmp/claude-codex-wechat.err.log</string>
 </dict>
 </plist>
 ```
 
-加载：
+## 发布 npm 包
 
-```bash
-launchctl load ~/Library/LaunchAgents/com.claude-codex-wechat.plist
-launchctl list | grep claude-codex-wechat   # 确认在跑
-# 卸载：launchctl unload ~/Library/LaunchAgents/com.claude-codex-wechat.plist
-```
+当前仓库只保留本地发布流，不再使用 GitHub Action 自动发布。
 
----
+### 发布行为
 
-## 正常使用路径
+本地执行 `npm publish` 时，会自动触发：
 
-### 1. 首次使用或微信 token 失效后恢复
+- `npm version patch --no-git-tag-version`
 
-最推荐的正式入口：
+也就是说：
 
-```bash
-bash ./scripts/recover-weixin-runtime.sh
-```
+- 每次成功发布都会自动把版本加一位 `patch`
+- 版本 bump 发生在真正 publish 之前
 
-如果你要直接做 Codex 验收模式：
+完整的发布前校验定义在 [release.sh](./release.sh)，`prepublishOnly` 只负责自动递增版本，避免在 `npm publish` 阶段重复再跑一遍测试和构建。
 
-```bash
-BRIDGE_DEFAULT_PROVIDER=codex bash ./scripts/recover-weixin-runtime.sh
-```
+### 直接发布
 
-这条命令会自动完成：
+如果不需要自动提交版本变更：
 
-1. 拉取新的微信登录二维码
-2. 生成并自动打开二维码 SVG
-3. 等待扫码确认
-4. 写出新的微信凭据文件
-5. 启动最新 bridge runtime
+```bash
+cd /Users/liuyuhua/github/claude-codex-wechat
+npm publish --access public --registry=https://registry.npmjs.org/
+```
 
-如果设置了：
+如果必须走代理：
 
 ```bash
-BRIDGE_DEFAULT_PROVIDER=codex
+cd /Users/liuyuhua/github/claude-codex-wechat
+HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 npm publish --access public --registry=https://registry.npmjs.org/
 ```
 
-那么 runtime 启动后会自动把默认 provider 切到 `codex`。
+### 使用 release.sh
 
-二维码文件默认路径：
+如果希望：
 
-```text
-/tmp/bridge-weixin-login-qr.svg
-```
+- 发布前先提交当前工作区
+- 发布后把自动 bump 的版本提交回当前分支
+- 自动 `git push`
 
-扫码状态文件默认路径：
+使用：
 
-```text
-/tmp/bridge-weixin-login-state.json
+```bash
+cd /Users/liuyuhua/github/claude-codex-wechat
+chmod +x release.sh
+./release.sh
 ```
 
-凭据文件默认路径：
+脚本默认会使用本地代理：
 
 ```text
-/tmp/bridge-weixin-credentials.json
-/tmp/bridge-weixin.env
+http://127.0.0.1:7890
 ```
 
-注意：
-
-- 这两个 `/tmp` 文件仍然会生成，方便联调和显式 `source`
-- 扫码成功后，helper 现在也会自动把新凭据回写到 `~/.claude-codex-wechat/config.json`
-- 之后直接执行 `pnpm dev`，默认就会继续读取这份正式配置
-
-最少要同步这几个字段：
-
-- `wechat.baseUrl`
-- `wechat.token`
-- `wechat.accountId`
-
-否则你会看到一种典型现象：
-
-- 扫码后当前 runtime 能用
-- 重启 `pnpm dev` 后又读不到刚才的新凭据
-- 看起来像“每次重启都要重新扫码”
-
-### 2. 启动成功后检查 bridge 是否真的连通
+如果你要覆盖默认代理：
 
 ```bash
-BRIDGE_PORT=8788 bash ./scripts/check-runtime-readiness.sh
+cd /Users/liuyuhua/github/claude-codex-wechat
+chmod +x release.sh
+HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ./release.sh
 ```
 
-重点看：
-
-- `weixin_connected`
-- `weixin_status`
-- `weixin_last_error`
-
-如果是正常连通，通常应该看到：
-
-- `weixin_connected=true`
-- `weixin_status=connected`
-
-### 3. 发微信消息开始对话
-
-给当前 bot 账号发一条文本消息。
-
-bridge 收到消息后会：
-
-- 自动授权用户（如果设置中开启）
-- 创建或接入 bridge session
-- 默认用当前设置的 provider 对话
-
----
-
-## 管理页有哪些功能
-
-当前管理页主要分成 4 块：
-
-### 1. Dashboard
-
-- daemon 状态
-- provider 状态
-- 活跃会话数
-- 待处理权限数
+这个脚本会：
 
-### 2. WeChatPanel
+- 先检查 `npm whoami`
+- 先执行 `pnpm typecheck`
+- 再执行 `pnpm build`
+- 提交当前改动
+- 以默认参数执行 `npm publish --access public --registry=https://registry.npmjs.org/`
+- 提交自动 bump 后的 `package.json`
+- 推送到当前分支
 
-- 微信扫码登录
-- pairing 待审批列表
-- 批准 / 拒绝 pairing
-- 已授权用户管理
-- 撤销授权
-- 扫描可恢复原生会话
-- 手动接入原生会话
-- 自动接入原生会话
-- Claude recoverable session 修复
-
-### 3. SessionsPanel
-
-- 查看 bridge 会话
-- 查看推荐恢复命令
-- 查看 provider resume 命令
-- 停止会话
-- 归档会话
-- 查看原生可达路径
-- 查看绑定来源
-- 单个 / 批量修复 Claude 原生恢复元数据
-
-### 4. PermissionsPanel
-
-- 批准 / 拒绝 / 中止高风险权限请求
-
----
-
-## 原生恢复能力
-
-### Claude
-
-当前仓库支持两种恢复方式：
-
-按原生 session id：
+### 发布前建议检查
 
 ```bash
-claude --resume <providerSessionId>
+cd /Users/liuyuhua/github/claude-codex-wechat
+npm whoami
+npm config get registry
+npm pack --dry-run
+pnpm typecheck
+pnpm build
 ```
 
-按 bridge 标题：
+如果包名是否可用要先确认：
 
 ```bash
-claude -r '<完整标题>'
+npm view claude-codex-wechat
 ```
 
-要让 `claude -r` 真正可用，通常至少要满足：
+## 常见问题
 
-- `providerResumeTitleSynced = true`
-- `providerResumeHistorySynced = true`
+### `npm publish` 报 `EPERM scandir ~/.Trash`
 
-### Codex
+一般是因为你不在项目目录，而是在家目录执行了 `npm publish`。
 
-按 session id：
+先确认：
 
 ```bash
-codex resume <providerSessionId>
+pwd
 ```
 
-按 bridge thread name：
+应该在：
 
 ```bash
-codex resume '<thread_name>'
+/Users/liuyuhua/github/claude-codex-wechat
 ```
 
----
-
-## 脚本怎么分
-
-### 正式使用入口
+### `Public registration is not allowed`
 
-- `scripts/recover-weixin-runtime.sh`
-  最推荐的恢复入口
-- `scripts/weixin-login-helper.ts`
-  单独扫码与落盘凭据
-- `scripts/start-runtime-check.sh`
-  启动最新 runtime 并打印关键状态
+通常是下面几类问题：
 
-### 诊断 / 验收工具
+- `registry` 不是官方 npm
+- 正在往私有 registry 发包
+- scoped package 没带 `--access public`
+- 账号没有该包名或 scope 的发布权限
 
-- `scripts/check-runtime-readiness.sh`
-  看 bridge 是否真的连通
-- `scripts/check-runtime-recovery.sh`
-  看 bridge session 恢复字段
-- `scripts/check-weixin-updates.ts`
-  直接打微信官方 `getupdates`
-
-如果只想记一个命令：
+检查：
 
 ```bash
-bash ./scripts/recover-weixin-runtime.sh
+npm config get registry
+npm whoami
+node -p "require('./package.json').name"
 ```
 
-如果要直接推进 Codex 的真实闭环验收，建议用这一组：
+### 本地必须走代理
+
+临时发布可直接这样：
 
 ```bash
-BRIDGE_DEFAULT_PROVIDER=codex bash ./scripts/recover-weixin-runtime.sh
-BRIDGE_PORT=8788 WAIT_SECONDS=120 bash ./scripts/check-codex-wechat-flow.sh
+HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 npm publish --access public --registry=https://registry.npmjs.org/
 ```
 
----
-
-## 当前已知边界
-
-这个仓库当前已经把工程内能做的链路基本铺平了，但仍有一个非常现实的边界：
-
-- 微信 bot 新授权出来的 token 可能会很快再次 `session timeout`
-
-也就是说，即使：
-
-- 扫码成功
-- 新 token 落盘成功
-- 最新 runtime 能启动
-
-微信官方 `getupdates` 会话本身仍可能在很短时间后再次失效。
-
-如果出现：
-
-- `weixin_connected=false`
-- `weixin_status=session_timeout`
-- `weixin_last_error=weixin_get_updates_failed:-14:session timeout`
-
-这更像是微信侧登录 / updates 会话稳定性问题，而不一定是这个 bridge 的业务逻辑问题。
-
----
-
-## 怎么判断真正成功
-
-一个最小闭环应至少满足：
-
-1. `check-runtime-readiness.sh` 显示：
-   - `weixin_connected=true`
-   - `weixin_status=connected`
-2. 给 bot 发一条真实微信消息后：
-   - `/api/channel/sessions` 出现新会话
-3. Claude 会话里看到：
-   - `providerResumeTitleSynced=true`
-   - `providerResumeHistorySynced=true`
-4. `claude -r '<完整标题>'` 真能恢复
-
-如果要验 Codex，则再满足：
-
-5. `codex resume '<thread_name>'` 真能恢复
-
----
-
-## 更多文档
+## 相关文件
 
-- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) —— 架构总览：整体架构、数据流、目录结构
-- [docs/README.md](./docs/README.md)
+- [package.json](./package.json)
+- [release.sh](./release.sh)
 - [scripts/README.md](./scripts/README.md)
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+- [docs/wechatbot-usage-guide.md](./docs/wechatbot-usage-guide.md)

package/dist/server/cli.js

@@ -2,8 +2,8 @@
 import { createRequire as __cjsCreateRequire } from 'node:module'; const require = __cjsCreateRequire(import.meta.url);
 
 // src/cli.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname10, join as join10 } from "node:path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname11, join as join11 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/daemon/bootstrap.ts
@@ -3989,6 +3989,27 @@ async function resolveProviderCommands(providers) {
   };
 }
 
+// src/daemon/portGuard.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+async function findListeningProcess(port) {
+  if (process.platform === "win32") return null;
+  try {
+    const { stdout } = await execFileAsync("lsof", ["-n", "-P", `-iTCP:${port}`, "-sTCP:LISTEN"]);
+    const lines = stdout.trim().split(/\r?\n/).filter(Boolean);
+    const record = lines.slice(1)[0];
+    if (!record) return null;
+    const parts = record.trim().split(/\s+/);
+    const command = parts[0] ?? "";
+    const pid = Number(parts[1] ?? "");
+    if (!command || !Number.isFinite(pid)) return null;
+    return { pid, command };
+  } catch {
+    return null;
+  }
+}
+
 // src/daemon/staticFrontend.ts
 import { readFileSync as readFileSync6 } from "node:fs";
 import { join as join9 } from "node:path";
@@ -4010,9 +4031,318 @@ function attachStaticFrontend(webRoot2) {
   };
 }
 
+// src/daemon/service.ts
+import { existsSync as existsSync8, statSync } from "node:fs";
+import { mkdir as mkdir4, readFile as readFile6, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname10, join as join10 } from "node:path";
+import { createReadStream } from "node:fs";
+import { execFile as execFile2, spawn as spawn6 } from "node:child_process";
+import { createInterface } from "node:readline";
+import { promisify as promisify2 } from "node:util";
+var execFileAsync2 = promisify2(execFile2);
+async function installService(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    await mkdir4(dirname10(spec.plistPath), { recursive: true });
+    await mkdir4(dirname10(spec.stdoutPath), { recursive: true });
+    await writeFile5(spec.plistPath, renderLaunchdPlist(spec), "utf8");
+    await runLaunchctl(["unload", spec.plistPath]).catch(() => void 0);
+    await runLaunchctl(["load", spec.plistPath]);
+    await runLaunchctl(["kickstart", "-k", `gui/${process.getuid?.() ?? 0}/${spec.label}`]);
+    return await readServiceStatus(context);
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    await mkdir4(dirname10(spec.unitPath), { recursive: true });
+    await mkdir4(dirname10(spec.stdoutPath), { recursive: true });
+    await writeFile5(spec.unitPath, renderSystemdUnit(spec), "utf8");
+    await runSystemctl(["--user", "daemon-reload"]);
+    await runSystemctl(["--user", "enable", "--now", spec.unitName]);
+    return await readServiceStatus(context);
+  }
+  throw new Error("service_install_not_supported_on_this_platform");
+}
+async function startService(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    await ensureFileExists(spec.plistPath, "service_not_installed");
+    await runLaunchctl(["load", spec.plistPath]).catch(() => void 0);
+    await runLaunchctl(["kickstart", "-k", `gui/${process.getuid?.() ?? 0}/${spec.label}`]);
+    return await readServiceStatus(context);
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    await ensureFileExists(spec.unitPath, "service_not_installed");
+    await runSystemctl(["--user", "start", spec.unitName]);
+    return await readServiceStatus(context);
+  }
+  throw new Error("service_start_not_supported_on_this_platform");
+}
+async function stopService(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    if (!existsSync8(spec.plistPath)) return await readServiceStatus(context);
+    await runLaunchctl(["bootout", `gui/${process.getuid?.() ?? 0}`, spec.plistPath]).catch(() => void 0);
+    return await readServiceStatus(context);
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    if (!existsSync8(spec.unitPath)) return await readServiceStatus(context);
+    await runSystemctl(["--user", "stop", spec.unitName]).catch(() => void 0);
+    return await readServiceStatus(context);
+  }
+  throw new Error("service_stop_not_supported_on_this_platform");
+}
+async function uninstallService(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    if (existsSync8(spec.plistPath)) {
+      await runLaunchctl(["bootout", `gui/${process.getuid?.() ?? 0}`, spec.plistPath]).catch(() => void 0);
+      await rm2(spec.plistPath, { force: true });
+    }
+    return await readServiceStatus(context);
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    if (existsSync8(spec.unitPath)) {
+      await runSystemctl(["--user", "disable", "--now", spec.unitName]).catch(() => void 0);
+      await rm2(spec.unitPath, { force: true });
+      await runSystemctl(["--user", "daemon-reload"]).catch(() => void 0);
+    }
+    return await readServiceStatus(context);
+  }
+  throw new Error("service_uninstall_not_supported_on_this_platform");
+}
+async function restartService(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    await ensureFileExists(spec.plistPath, "service_not_installed");
+    await runLaunchctl(["kickstart", "-k", `gui/${process.getuid?.() ?? 0}/${spec.label}`]);
+    return await readServiceStatus(context);
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    await ensureFileExists(spec.unitPath, "service_not_installed");
+    await runSystemctl(["--user", "restart", spec.unitName]);
+    return await readServiceStatus(context);
+  }
+  throw new Error("service_restart_not_supported_on_this_platform");
+}
+async function readServiceLogs(context, lines = 120) {
+  const status = await readServiceStatus(context);
+  const stdoutTail = await tailFile(status.stdoutPath, lines);
+  const stderrTail = await tailFile(status.stderrPath, lines);
+  return [
+    `[stdout] ${status.stdoutPath}`,
+    stdoutTail || "(empty)",
+    "",
+    `[stderr] ${status.stderrPath}`,
+    stderrTail || "(empty)"
+  ].join("\n");
+}
+async function tailServiceLogs(context) {
+  const status = await readServiceStatus(context);
+  await tailFiles([status.stdoutPath, status.stderrPath]);
+}
+async function readServiceStatus(context) {
+  if (process.platform === "darwin") {
+    const spec = buildLaunchdSpec(context);
+    const installed = existsSync8(spec.plistPath);
+    const running = installed ? await runLaunchctl(["print", `gui/${process.getuid?.() ?? 0}/${spec.label}`]).then(() => true, () => false) : false;
+    return {
+      manager: "launchd",
+      installed,
+      running,
+      serviceFilePath: spec.plistPath,
+      label: spec.label,
+      stdoutPath: spec.stdoutPath,
+      stderrPath: spec.stderrPath
+    };
+  }
+  if (process.platform === "linux") {
+    const spec = buildSystemdUserSpec(context);
+    const installed = existsSync8(spec.unitPath);
+    const running = installed ? await runSystemctl(["--user", "is-active", "--quiet", spec.unitName]).then(() => true, () => false) : false;
+    return {
+      manager: "systemd-user",
+      installed,
+      running,
+      serviceFilePath: spec.unitPath,
+      label: spec.unitName,
+      stdoutPath: spec.stdoutPath,
+      stderrPath: spec.stderrPath
+    };
+  }
+  throw new Error("service_status_not_supported_on_this_platform");
+}
+function buildLaunchdSpec(context) {
+  const stateDir = join10(homedir7(), ".claude-codex-wechat");
+  return {
+    label: "com.claude-codex-wechat",
+    plistPath: join10(homedir7(), "Library", "LaunchAgents", "com.claude-codex-wechat.plist"),
+    programArgs: [context.nodePath ?? process.execPath, context.cliEntrypointPath, "start"],
+    workingDirectory: homedir7(),
+    stdoutPath: join10(stateDir, "logs", "service.stdout.log"),
+    stderrPath: join10(stateDir, "logs", "service.stderr.log"),
+    environment: buildServiceEnvironment(context)
+  };
+}
+function buildSystemdUserSpec(context) {
+  const stateDir = join10(homedir7(), ".claude-codex-wechat");
+  return {
+    unitName: "claude-codex-wechat.service",
+    unitPath: join10(homedir7(), ".config", "systemd", "user", "claude-codex-wechat.service"),
+    execStart: [context.nodePath ?? process.execPath, context.cliEntrypointPath, "start"],
+    workingDirectory: homedir7(),
+    stdoutPath: join10(stateDir, "logs", "service.stdout.log"),
+    stderrPath: join10(stateDir, "logs", "service.stderr.log"),
+    environment: buildServiceEnvironment(context)
+  };
+}
+function buildServiceEnvironment(context) {
+  const env = {
+    PATH: process.env.PATH ?? "",
+    HOME: process.env.HOME ?? homedir7()
+  };
+  const configPath = context.configPath ?? process.env.BRIDGE_CONFIG;
+  const port = context.port ?? Number(process.env.BRIDGE_PORT ?? 8787);
+  if (configPath) env.BRIDGE_CONFIG = configPath;
+  if (Number.isFinite(port)) env.BRIDGE_PORT = String(port);
+  for (const key of [
+    "BRIDGE_WECHAT_ENABLED",
+    "BRIDGE_WECHAT_BASE_URL",
+    "BRIDGE_WECHAT_TOKEN",
+    "BRIDGE_WECHAT_ACCOUNT_ID",
+    "BRIDGE_CLAUDE_COMMAND",
+    "BRIDGE_CODEX_COMMAND",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "http_proxy",
+    "https_proxy"
+  ]) {
+    const value = process.env[key];
+    if (value) env[key] = value;
+  }
+  return env;
+}
+function renderLaunchdPlist(spec) {
+  const programArgs = spec.programArgs.map((arg) => `    <string>${escapeXml(arg)}</string>`).join("\n");
+  const envEntries = Object.entries(spec.environment).map(([key, value]) => `    <key>${escapeXml(key)}</key>
+    <string>${escapeXml(value)}</string>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${escapeXml(spec.label)}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    programArgs,
+    "  </array>",
+    "  <key>WorkingDirectory</key>",
+    `  <string>${escapeXml(spec.workingDirectory)}</string>`,
+    "  <key>EnvironmentVariables</key>",
+    "  <dict>",
+    envEntries,
+    "  </dict>",
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${escapeXml(spec.stdoutPath)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${escapeXml(spec.stderrPath)}</string>`,
+    "</dict>",
+    "</plist>",
+    ""
+  ].join("\n");
+}
+function renderSystemdUnit(spec) {
+  const envEntries = Object.entries(spec.environment).map(([key, value]) => `Environment=${quoteSystemdEnv(`${key}=${value}`)}`).join("\n");
+  return [
+    "[Unit]",
+    "Description=claude-codex-wechat bridge daemon",
+    "After=network.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${spec.workingDirectory}`,
+    `ExecStart=${spec.execStart.map(quoteSystemdArg).join(" ")}`,
+    envEntries,
+    `StandardOutput=append:${spec.stdoutPath}`,
+    `StandardError=append:${spec.stderrPath}`,
+    "Restart=on-failure",
+    "RestartSec=5",
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    ""
+  ].join("\n");
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function quoteSystemdArg(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function quoteSystemdEnv(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+async function runLaunchctl(args) {
+  await execFileAsync2("launchctl", args);
+}
+async function runSystemctl(args) {
+  await execFileAsync2("systemctl", args);
+}
+async function ensureFileExists(path, errorCode) {
+  if (!existsSync8(path)) throw new Error(errorCode);
+  await readFile6(path, "utf8");
+}
+async function tailFile(path, lines) {
+  if (!existsSync8(path)) return "";
+  const content = await readFile6(path, "utf8");
+  return content.split(/\r?\n/).slice(-lines).join("\n").trim();
+}
+async function tailFiles(paths) {
+  const readers = paths.filter((path) => existsSync8(path)).map((path) => {
+    const rl = createInterface({
+      input: createReadStream(path, { encoding: "utf8", start: Math.max(0, fileSizeHint(path) - 8192) }),
+      crlfDelay: Infinity
+    });
+    rl.on("line", (line) => {
+      process.stdout.write(`[${path}] ${line}
+`);
+    });
+    return rl;
+  });
+  if (process.platform !== "linux" && process.platform !== "darwin") {
+    return;
+  }
+  const child = spawn6("tail", ["-f", ...paths.filter((path) => existsSync8(path))], { stdio: ["ignore", "pipe", "inherit"] });
+  child.stdout.on("data", (chunk) => {
+    process.stdout.write(String(chunk));
+  });
+  await new Promise((resolve, reject) => {
+    child.on("exit", () => resolve());
+    child.on("error", reject);
+  }).finally(() => {
+    for (const reader of readers) reader.close();
+  });
+}
+function fileSizeHint(path) {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
 // src/cli.ts
-var here = dirname10(fileURLToPath(import.meta.url));
-var webRoot = join10(here, "..", "web");
+var here = dirname11(fileURLToPath(import.meta.url));
+var webRoot = join11(here, "..", "web");
 async function main() {
   const command = process.argv[2];
   switch (command) {
@@ -4026,6 +4356,9 @@ async function main() {
     case "doctor":
       await cmdDoctor();
       return;
+    case "service":
+      await cmdService(process.argv.slice(3));
+      return;
     case "print-config":
       cmdPrintConfig();
       return;
@@ -4042,21 +4375,36 @@ async function main() {
   }
 }
 async function cmdStart() {
-  if (!existsSync8(webRoot)) {
+  if (!existsSync9(webRoot)) {
     console.error(`\u627E\u4E0D\u5230\u524D\u7AEF\u6784\u5EFA\u4EA7\u7269: ${webRoot}`);
     console.error("\u8BF7\u5148\u8FD0\u884C\u6784\u5EFA (pnpm build) \u540E\u518D\u542F\u52A8\uFF0C\u6216\u91CD\u65B0\u5B89\u88C5\u5B8C\u6574\u7684 npm \u5305\u3002");
     process.exitCode = 1;
     return;
   }
+  const context = createServiceContext();
+  const port = context.port ?? 8787;
+  const occupiedBy = await findListeningProcess(port);
+  if (occupiedBy) {
+    const serviceStatus = await readServiceStatus(context).catch(() => null);
+    if (serviceStatus?.installed && serviceStatus.running) {
+      console.log(`\u7AEF\u53E3 ${port} \u5DF2\u88AB\u540E\u53F0\u670D\u52A1\u5360\u7528\uFF0C\u5148\u505C\u6B62\u670D\u52A1\u518D\u4EE5\u524D\u53F0\u6A21\u5F0F\u542F\u52A8\u3002`);
+      await stopService(context);
+    } else {
+      console.error(`\u7AEF\u53E3 ${port} \u5DF2\u88AB\u5360\u7528: PID=${occupiedBy.pid} COMMAND=${occupiedBy.command}`);
+      console.error("\u8BF7\u5148\u505C\u6B62\u5360\u7528\u8FDB\u7A0B\uFF0C\u6216\u6539\u7528 `claude-codex-wechat service stop` \u505C\u6389\u540E\u53F0\u670D\u52A1\u3002");
+      process.exitCode = 1;
+      return;
+    }
+  }
   await startDaemon({
     attachFrontend: attachStaticFrontend(webRoot)
   });
 }
 function cmdInit() {
   const configPath = process.env.BRIDGE_CONFIG ?? defaultConfigPath();
-  const dir = dirname10(configPath);
+  const dir = dirname11(configPath);
   mkdirSync6(dir, { recursive: true });
-  if (existsSync8(configPath)) {
+  if (existsSync9(configPath)) {
     console.log(`\u914D\u7F6E\u5DF2\u5B58\u5728\uFF0C\u672A\u8986\u76D6: ${configPath}`);
     return;
   }
@@ -4081,13 +4429,13 @@ function cmdInit() {
 async function cmdDoctor() {
   const configPath = process.env.BRIDGE_CONFIG ?? defaultConfigPath();
   console.log("claude-codex-wechat doctor\n");
-  report("\u914D\u7F6E\u6587\u4EF6", existsSync8(configPath) ? configPath : `\u7F3A\u5931 (${configPath})\uFF0C\u8FD0\u884C init \u521B\u5EFA`);
-  report("\u524D\u7AEF\u4EA7\u7269", existsSync8(webRoot) ? webRoot : `\u7F3A\u5931 (${webRoot})`);
+  report("\u914D\u7F6E\u6587\u4EF6", existsSync9(configPath) ? configPath : `\u7F3A\u5931 (${configPath})\uFF0C\u8FD0\u884C init \u521B\u5EFA`);
+  report("\u524D\u7AEF\u4EA7\u7269", existsSync9(webRoot) ? webRoot : `\u7F3A\u5931 (${webRoot})`);
   const claude = await findExecutable("claude");
   report("claude \u53EF\u6267\u884C", claude ?? "\u672A\u627E\u5230\uFF0C\u9700\u5148\u5B89\u88C5\u5E76\u767B\u5F55 Claude Code");
   const codex = await findExecutable("codex");
   report("codex \u53EF\u6267\u884C", codex ?? "\u672A\u627E\u5230\uFF08\u4EC5\u4F7F\u7528 Claude \u65F6\u53EF\u5FFD\u7565\uFF09");
-  if (existsSync8(configPath)) {
+  if (existsSync9(configPath)) {
     const config = loadBridgeConfig(configPath);
     const wechat = config.wechat;
     report("\u5FAE\u4FE1\u542F\u7528", wechat?.enabled ? "\u662F" : "\u5426");
@@ -4097,16 +4445,84 @@ async function cmdDoctor() {
 }
 function cmdPrintConfig() {
   const configPath = process.env.BRIDGE_CONFIG ?? defaultConfigPath();
-  if (!existsSync8(configPath)) {
+  if (!existsSync9(configPath)) {
     console.error(`\u914D\u7F6E\u4E0D\u5B58\u5728: ${configPath}\uFF08\u8FD0\u884C init \u521B\u5EFA\uFF09`);
     process.exitCode = 1;
     return;
   }
   console.log(readFileSync7(configPath, "utf8"));
 }
+async function cmdService(args) {
+  const action = args[0] ?? "status";
+  const context = createServiceContext();
+  switch (action) {
+    case "install": {
+      const status = await installService(context);
+      printServiceStatus("service installed", status);
+      return;
+    }
+    case "start": {
+      const status = await startService(context);
+      printServiceStatus("service started", status);
+      return;
+    }
+    case "stop": {
+      const status = await stopService(context);
+      printServiceStatus("service stopped", status);
+      return;
+    }
+    case "restart": {
+      const status = await restartService(context);
+      printServiceStatus("service restarted", status);
+      return;
+    }
+    case "logs": {
+      console.log(await readServiceLogs(context));
+      return;
+    }
+    case "tail": {
+      await tailServiceLogs(context);
+      return;
+    }
+    case "uninstall": {
+      const status = await uninstallService(context);
+      printServiceStatus("service uninstalled", status);
+      return;
+    }
+    case "status": {
+      const status = await readServiceStatus(context);
+      printServiceStatus("service status", status);
+      return;
+    }
+    default:
+      console.error(`\u672A\u77E5 service \u5B50\u547D\u4EE4: ${action}
+`);
+      printUsage();
+      process.exitCode = 1;
+  }
+}
+function createServiceContext() {
+  return {
+    cliEntrypointPath: fileURLToPath(import.meta.url),
+    nodePath: process.execPath,
+    configPath: process.env.BRIDGE_CONFIG ?? defaultConfigPath(),
+    port: Number(process.env.BRIDGE_PORT ?? 8787)
+  };
+}
 function report(label, value) {
   console.log(`  ${label.padEnd(14)}: ${value}`);
 }
+function printServiceStatus(title, status) {
+  console.log(`claude-codex-wechat ${title}
+`);
+  report("service manager", status.manager);
+  report("installed", status.installed ? "yes" : "no");
+  report("running", status.running ? "yes" : "no");
+  report("label", status.label);
+  report("service file", status.serviceFilePath);
+  report("stdout log", status.stdoutPath);
+  report("stderr log", status.stderrPath);
+}
 function printUsage() {
   console.log(`claude-codex-wechat \u2014 \u672C\u5730 WeChat \u2194 Claude/Codex bridge daemon
 
@@ -4117,6 +4533,7 @@ function printUsage() {
   start          \u542F\u52A8 daemon\uFF08\u9ED8\u8BA4\u547D\u4EE4\uFF0C\u524D\u53F0\u8FD0\u884C\uFF09
   init           \u5728 ~/.claude-codex-wechat/ \u521B\u5EFA\u9ED8\u8BA4\u914D\u7F6E
   doctor         \u68C0\u67E5\u914D\u7F6E\u3001\u524D\u7AEF\u4EA7\u7269\u4E0E claude/codex \u53EF\u6267\u884C\u6587\u4EF6
+  service        \u7BA1\u7406\u540E\u53F0\u670D\u52A1\uFF08install/start/stop/restart/status/logs/tail/uninstall\uFF09
   print-config   \u6253\u5370\u5F53\u524D\u914D\u7F6E\u6587\u4EF6\u5185\u5BB9
   help           \u663E\u793A\u672C\u5E2E\u52A9
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-codex-wechat",
-  "version": "0.1.0",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "build:web": "vite build",
     "build:server": "node scripts/build-server.mjs",
     "build": "vite build && node scripts/build-server.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm version patch --no-git-tag-version"
   },
   "dependencies": {
     "@fastify/static": "^9.1.3",