cwm-assistant 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tangzhijie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

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