@wemind/cli 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# @wemind/cli — 命令 `wemind`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **你的 AI 大脑，挂在微信上。** 常驻微信 Bot 守护进程：自己长轮询 iLink 收消息 → 调常驻 **ACP 大脑**生成回复 → 自动回发。支持**远程任务（worker）**、**多账号**、收发图/文件。
+
+[WeMind](https://github.com/imwangpan/WeMind) monorepo 的完整应用包；只依赖内核 `@wemind/wechat-ilink-core`（构建时已内联进单文件产物），不碰 MCP 层，可独立运行。
+
+> **包名 `@wemind/cli` ≠ 命令名 `wemind`。** 与 `@modelcontextprotocol/*`、`@angular/cli`、`@openai/codex` 的惯例一致：包收在 scope 下，命令保持短名。因为包名与 bin 名不同，**`npx` 不会自动挑 bin，必须写全包名**。
+
+## 安装
+
+```bash
+npm i -g @wemind/cli     # 安装后得到 wemind 命令
+wemind version           # → wemind 1.0.0 (@wemind/cli, node 24.x, win32-x64)
+
+# 不安装、一次性运行（注意是包名 @wemind/cli，不是 wemind）
+npx -y @wemind/cli list
+```
+
+要求：**Node.js >= 20**；想让它真的会「思考」，需要 PATH 上有一个支持 **ACP** 的 agent CLI（`kiro-cli` / `opencode` / 桌面端 `dsh` / `qodercli` 等；未配置时自动探测 `kiro → opencode → gemini → deepseek → qoder`）。
+
+## 升级
+
+```bash
+npm i -g @wemind/cli@latest
+wemind stop <账号> && wemind start <账号>   # 已在运行的 daemon 不会自动加载新代码
+```
+
+## 三步上手
+
+```bash
+wemind login --label 主号 --start   # ① 终端里出二维码，微信扫码 → 自动归档 + 启动常驻
+wemind list                          # ② 看账号与运行状态
+wemind brain check                   # ③ 验证大脑能说 ACP（initialize + session/new 握手）
+```
+
+之后在微信里随便发一句话，就该收到回复。日志在 `~/.wemind/<账号>/daemon.log`。
+
+## 常用命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `wemind login [--label 名] [--start] [--runner builtin\|pm2]` | 扫码登录；`--start` 顺带拉起常驻 |
+| `wemind list` | 账号、别名、运行状态、当前大脑 |
+| `wemind start / stop <key\|label>` | 启停某账号的常驻 |
+| `wemind brain [show\|set\|unset\|check]` | 查看/切换/清除/自检大脑（`brain set deepseek --bin "<绝对路径>" --restart`） |
+| `wemind task "<描述>" [--cwd 目录]` | 本地派发远程任务给 worker |
+| `wemind task-status / task-reply / task-stop` | 任务状态、注入续跑（`task-reply 继续`）、结束 |
+| `wemind allow / revoke / allowlist` | 授权管理（谁能驱动这个 bot） |
+| `wemind logout / delete / label / set-default` | 账号运维 |
+| `wemind version` / `wemind help` | 版本、完整帮助 |
+
+`key` = 由微信 botId 派生的目录名；`label` = 人类可读别名，多数命令两者都能用。
+
+## 常驻怎么跑
+
+`wemind start` 默认用**自带的跨平台看门狗**（builtin）：detached 拉起 `wemind _watchdog`，它循环执行 `wemind daemon`，进程退出 5 秒后自动重拉；单实例靠 `wrapper.pid` + 进程身份校验。也可以用 `--runner pm2`（或 `WEMIND_RUNNER=pm2`）交给 pm2。
+
+开机自启：让系统在登录时执行一次 `wemind start <账号>` 即可（Windows 计划任务/启动文件夹、Linux systemd user service、macOS launchd）。**同一账号只用一套常驻方案**——两种 runner 同时跑会抢同一个 bot token。
+
+## 数据与安全
+
+- 所有状态在 `~/.wemind/<账号>/`（可用 `WEMIND_HOME` 改根目录）：`account.json` 登录凭证、`state.json` 游标、`allowFrom.json` 授权清单、`brain-home/` 大脑沙箱、`daemon.log` 日志。
+- ⚠️ **daemon 会让大脑免确认执行工具**（kiro 预设 `--trust-all-tools`；qoder 预设 `--yolo`）：能给这个 bot 发消息的人，即可让大脑在本机执行任意工具（shell / 写文件）。唯一安全闸是**发件人授权（allowFrom）**：扫码登录者自动授权，**勿清空**。
+- `account.json` 里 bot token 是明文（POSIX 上 chmod 600；Windows 请用目录权限或磁盘加密）。
+- 同一个 bot token **只能有一个消费者**：`wemind` daemon 与 `@wemind/wechat-mcp` 二选一，否则互相抢消息。
+
+## 环境变量（常用）
+
+| 变量 | 含义 |
+| --- | --- |
+| `WEMIND_HOME` | 数据根目录，默认 `~/.wemind` |
+| `WECHAT_ACCOUNT` / `WECHAT_DATA_DIR` | 指定账号 / 指定完整数据目录（多账号隔离） |
+| `WEMIND_RUNNER` | `builtin`（默认）或 `pm2` |
+| `WEMIND_BRAIN` / `WEMIND_BRAIN_BIN` / `WEMIND_BRAIN_ARGS` | 一次性覆盖大脑选择（持久化请用 `wemind brain set`） |
+| `WEMIND_ACP_AUTO_ALLOW=1` | 放行 ACP agent 的一次性权限请求（默认为拒绝） |
+
+## 与 MCP 形态的区别
+
+| | `@wemind/cli`（命令 `wemind`） | `@wemind/wechat-mcp` |
+| --- | --- | --- |
+| 驱动 | 自己常驻、自己调大脑 | 随 MCP 客户端生命周期，被动调工具 |
+| 大脑 | 独立 ACP agent 进程 | 就是 MCP 客户端背后的模型 |
+| 能力 | 收发图/文件、远程任务、多账号、7×24 | 文本收发为主 |
+
+## 文档
+
+- 完整文档：<https://github.com/imwangpan/WeMind>
+- 新手一步步教程：[docs/新手教程.md](https://github.com/imwangpan/WeMind/blob/main/docs/新手教程.md)
+- 发布与版本规则：[docs/发布-wemind-npm.md](https://github.com/imwangpan/WeMind/blob/main/docs/发布-wemind-npm.md)
+- AI 协作者入口：[AGENTS.md](https://github.com/imwangpan/WeMind/blob/main/AGENTS.md)
+- 接入其它 ACP agent：[docs/接入其它-ACP-Agent.md](https://github.com/imwangpan/WeMind/blob/main/docs/接入其它-ACP-Agent.md)
+- Qoder 接入：[docs/接入-Qoder.md](https://github.com/imwangpan/WeMind/blob/main/docs/接入-Qoder.md)
+- Daemon 常驻原理：[docs/repowiki/10-部署与运维.md](https://github.com/imwangpan/WeMind/blob/main/docs/repowiki/10-部署与运维.md)
+
+## 维护者：发布新版本
+
+本包（包名 `@wemind/cli`，命令 `wemind`）通过 GitHub Actions（[`.github/workflows/wemind-publish.yml`](../../.github/workflows/wemind-publish.yml)）发布到 npm。**下面的命令都在 WeMind 仓库根目录运行**，不是在 `packages/wechat-daemon` 子目录。
+
+> ⚠️ **本包比 `@wemind/wechat-mcp` 多一处要改**：版本号除了 `package.json` 和 `package-lock.json`，还有源码常量 `src/version.ts` 的 `CLI_VERSION`（`wemind version` 的输出就来自它）。漏改会让单测与 CI 直接失败——仓库自带 `npm run check:version` 专门挡这个。
+
+### 第一步：判断要不要发版
+
+| 你改了什么 | 需要发版吗 |
+| --- | --- |
+| `packages/wechat-daemon/src/**` 或 `packages/wechat-ilink-core/src/**`（内核会内联进来） | ✅ 要 |
+| 只改了 `*.md` 文档 | ❌ 不用（CI 仍跑检查，但版本没变会跳过发布） |
+| 只改了 `packages/wechat-mcp/**` | ❌ 与本包无关，发的是另一个包 |
+
+> 同一个版本号**不能重复发布**。所以「有没有改代码」不是关键，「有没有升版本号」才是——没升就只会跑检查、不发布。
+
+### 第二步：选版本号
+
+| 参数 | 示例 | 什么时候用 |
+| --- | --- | --- |
+| `patch` | `1.0.0` → `1.0.1` | Bug 修复、兼容性改动（**最常用**） |
+| `minor` | `1.0.0` → `1.1.0` | 新增向后兼容的能力（如新增内置大脑预设、新增子命令） |
+| `major` | `1.0.0` → `2.0.0` | 不兼容改动（如删子命令、改数据目录布局、改 CLI 参数） |
+
+### 第三步：升版本号（三处必须同步）
+
+**方式 A：用 npm 改 `package.json` + lock，再手改 `version.ts`（推荐）**
+
+```powershell
+# ① 改 package.json 与 package-lock.json
+npm version patch --workspace @wemind/cli --no-git-tag-version
+
+# ② 手工同步源码常量（npm 不会帮你改这个）
+#    编辑 packages/wechat-daemon/src/version.ts：
+#    export const CLI_VERSION = "1.0.1";   ← 与上一步的版本一致
+
+# ③ 自检三处是否一致（不一致会 exit 1）
+npm run check:version
+```
+
+- `--workspace @wemind/cli`：只动本包，不改根项目、mcp、core 的版本；
+- `--no-git-tag-version`：不自动创建 commit 或 tag，改完由你自己检查提交。
+
+**方式 B：全部手动**
+
+1. 编辑 `packages/wechat-daemon/package.json` 的 `"version"`；
+2. 编辑 `packages/wechat-daemon/src/version.ts` 的 `CLI_VERSION`；
+3. 回到仓库根目录刷新锁文件：
+
+```powershell
+npm install --package-lock-only --ignore-scripts
+```
+
+> 不要手动编辑 `package-lock.json`。上面这条只重算 lockfile 元数据，不重装 `node_modules`、不跑依赖的安装脚本。
+
+### 第四步：本地校验
+
+```powershell
+npm run check:version    # 包名 + 三处版本一致（package.json / version.ts / lock）
+npm run lint && npm run typecheck && npm run build && npm test
+npm pack --dry-run --workspace @wemind/cli    # 应看到 4 个文件：cli.js / cli.js.map / README.md / package.json
+```
+
+> ⚠️ **`npm publish` 不会自动 build**。CI 会 build，但本地 `npm pack` 前必须先 `npm run build`，否则打出来是旧产物（`dist/` 在 `.gitignore` 里）。
+>
+> `prepack` 守卫（`scripts/prepack-guard.mjs`）会兜底拒绝：产物目录为空、`bin` 缺失、或声明了 sourcemap 却没把 `.map` 带进包。
+
+### 第五步：提交并推送
+
+```powershell
+git add packages/wechat-daemon/package.json packages/wechat-daemon/src/version.ts package-lock.json
+git add packages/wechat-daemon/src packages/wechat-ilink-core/src   # 有源码改动时
+git commit -m "chore: release @wemind/cli 1.0.1"
+git push origin main
+```
+
+推送到 `main` 后，工作流依次执行：
+
+```
+check-version（三处一致）→ npm ci → lint → format:check → typecheck → build → test
+→ npm pack --dry-run（prepack 守卫确认包内容）
+→ 把 tarball 真装到临时目录跑 wemind version / help（装包冒烟）
+→ 检查 npm 上是否已存在该版本
+→ 不存在则 npm publish（带 provenance 来源证明）；已存在则跳过并输出 notice
+```
+
+**看到 `Publish to npm` 显示 skipped 是正常的**：说明这个版本已发过（比如你只改了文档、没升版本）。想真正发版，回到第二步升版本号。
+
+### 第六步：发布后验收
+
+```powershell
+npm view @wemind/cli version                        # 应显示新版本号
+npm i -g @wemind/cli@latest && wemind version       # → wemind <新版本> (@wemind/cli, node …, <platform>-<arch>)
+wemind list                                         # 应能正确识别在跑的账号与进程
+```
+
+已装用户升级：`npm i -g @wemind/cli@latest`，然后 `wemind stop <账号> && wemind start <账号>` ——**正在运行的 daemon 不会自动加载新代码**。
+
+### 常见坑
+
+| 现象 | 原因 | 处理 |
+| --- | --- | --- |
+| CI 在 `check-version` 就红了 | 只改了 `package.json`，没同步 `version.ts` | 改 `CLI_VERSION` 后重推 |
+| CI 绿了但 npm 上没新版本 | 版本号没升，被跳过 | 升版本号后再推 |
+| CI 报 lock 版本不一致 | 没跑 `npm install --package-lock-only` | 补跑第三步 |
+| `npm pack` 出来是空壳 | 没先 `npm run build` | 先 build 再 pack |
+| `prepack` 守卫拒绝发布 | 产物为空 / `bin` 缺失 / 声明了 sourcemap 但 `.map` 不在包里 | 按守卫提示补 build 或检查 `files` |
+| `npm publish` 报 403 / EOTP | 本地直发需要交互式 2FA | **不要本地发**，走 CI（Trusted Publisher 已配好） |
+
+## License
+
+MIT