cwm-assistant 0.1.1 → 0.2.1

package/README.md

@@ -1,14 +1,14 @@
-# CWM 助手
+# Workspace 助手
 
 Code Workspace Manager（CWM）的本机助手。运行在打开工作台网页的电脑上，为网页提供本机
-Git、Workspace 目录和工具命令操作，并在登录电脑时自动启动。
+Git、Workspace 目录和工具命令操作。
 
 助手只监听 `127.0.0.1:46322`，不上传仓库内容；中心服务保存账号、需求与版本，助手保存设备
 路径、工具配置和本地任务。
 
 ## 运行要求
 
-- Node.js 22 或更高版本（推荐 24 LTS）
+- Node.js 22.13 或更高版本（推荐 24 LTS）
 - Git 2.38 或更高版本（Windows 使用 Git for Windows）
 - macOS 或 Windows 上的 Chrome / Edge
 
@@ -18,59 +18,59 @@ Git、Workspace 目录和工具命令操作，并在登录电脑时自动启动
 npm install -g cwm-assistant
 ```
 
-从 npm 安装不会注册自启动，需要运行 `setup` 完成初始化。
+装完即可用：安装钩子会在后台启动助手，并注册登录自启动（macOS 用户 LaunchAgent，
+Windows 当前用户计划任务）。不需要再执行 `setup`。
 
-## 初始化
+安装钩子只在真正的全局安装时动作；仓库内 `npm ci`、`--workspace` 安装、`npm pack` 都不会
+触发它。使用 `sudo npm install -g` 时钩子会跳过自启动注册——root 的 HOME 没有登录项可写。
 
-```sh
-cwm-assistant setup
-```
-
-`setup` 依次完成：
+首次在浏览器打开工作台时，助手的顶栏状态会显示「已连接」，只差选一个工作目录。助手接受任何
+CWM 工作台接入，无需预先登记地址。
 
-1. 输入可信工作台地址（HTTPS；同机开发可用 `http://127.0.0.1:46321`）
-2. 选择工作目录，用于保存仓库和 Git worktree
-3. 确认登录电脑时自动启动（macOS 写入用户 LaunchAgent，Windows 创建当前用户计划任务）
-4. 启动助手并生成一次性配对码
+## 工作目录与自启动
 
-回到工作台网页，点击顶部的「本机助手」完成连接并确认本机目录。配对码 5 分钟内有效。
+装完只需要在工作台网页里选一次工作目录，也可以直接点「使用默认位置」创建
+`~/Documents/code-workspace`。登录自启动在安装时已注册，不需要额外设置。
 
-非交互安装（脚本或远程动手）：
+需要脚本化配置时：
 
 ```sh
-cwm-assistant setup --workbench http://127.0.0.1:46321 --root ~/code-workspace --yes --autostart
+cwm-assistant setup --root ~/code-workspace --yes
 ```
 
-`--workbench` 可重复，每次授权一个工作台来源；`--root` 必须是已存在的绝对路径；
-`--port` 可覆盖默认端口（1024–65535）。
+`--root` 必须是已存在的绝对路径。
 
 ## 命令
 
 | 命令                       | 说明                                 |
 | -------------------------- | ------------------------------------ |
-| `setup`                    | 首次初始化，写入配置并启动           |
 | `start`                    | 启动助手（已运行则直接返回）         |
 | `stop`                     | 停止助手并关闭自启动                 |
 | `restart`                  | 重启助手，保留自启动设置             |
-| `status`                   | 查询运行状态、版本和端口             |
+| `status`                   | 查询运行状态和版本                   |
 | `--version`                | 打印助手版本号                       |
 | `doctor`                   | 检查 Node、Git、入口文件、目录和配置 |
+| `setup`                    | 设置工作目录、启动助手               |
 | `pair`                     | 生成新的配对码，用于更换浏览器       |
 | `logs`                     | 查看最近 100 行日志                  |
 | `autostart enable/disable` | 单独切换登录自启动（需先 `stop`）    |
 | `uninstall`                | 停止助手并撤销全部配对，保留项目文件 |
 
+`install` 由安装钩子内部调用（重启到新版本并注册自启动），不需要手动执行。
+
 所有命令都接受 `--state-dir`，用于指定状态目录（默认 `~/.cwm-assistant`，
-可用环境变量 `CWM_ASSISTANT_HOME` 覆盖）。
+可用环境变量 `CWM_ASSISTANT_HOME` 覆盖）。端口固定为 `46322`，不可更改。
 
-## 更新与卸载
+## 工作台接入
 
-升级前先运行 `cwm-assistant stop`，确认没有正在运行的本地任务，再执行：
+助手接受任何工作台的接入请求，判定依据是身份而非地址：每个来源首次连接时，助手会请求该来源
+的 `/api/assistant/identity`，只有拿到合法公钥才会记录，因此记录下来的地址只能接受由该地址
+签发的授权。每次本机操作仍会回推中心校验绑定，撤销浏览器配对后该浏览器立即失去本机能力。
 
-```sh
-npm install -g cwm-assistant@latest
-cwm-assistant start
-```
+## 更新与卸载
+
+升级时直接安装新版本即可，安装钩子会把运行中的助手重启到新代码；若有本地任务尚未完成，
+它会保留旧进程并提示稍后运行 `cwm-assistant restart`。
 
 卸载前运行 `cwm-assistant uninstall` 撤销配对并移除自启动，再执行：
 
@@ -82,11 +82,10 @@ npm uninstall -g cwm-assistant
 
 ## 常见问题
 
-- 网页提示「需要更新」：工作台与助手协议版本不一致，升级助手到最新版本。
-- 网页提示「待配对」：工作台不在助手授权列表内，运行 `setup` 补充地址，或运行 `pair`
-  后重新连接。
+- 网页提示「需要更新」：工作台与助手协议版本不一致，安装最新版本即可。
+- 网页提示「待连接」：当前浏览器尚未配对，在对话框里点击「连接助手」。
 - 浏览器提示访问本地网络：允许当前工作台访问 `127.0.0.1:46322`，再重新检测。
-- 诊断端口占用或启动失败：运行 `cwm-assistant doctor` 和 `cwm-assistant logs`。
+- 启动失败：运行 `cwm-assistant logs` 查看日志。
 
 ## 许可证