@fengye404/termpilot 0.1.6 → 0.1.8

package/README.md

@@ -1,66 +1,60 @@
 # TermPilot
 
-TermPilot 是一个终端优先的远程控制工具。电脑上跑 `tmux` 会话，手机直接打开 relay 域名查看和控制同一批会话。
+[![npm version](https://img.shields.io/npm/v/%40fengye404%2Ftermpilot)](https://www.npmjs.com/package/@fengye404/termpilot)
+[![npm downloads](https://img.shields.io/npm/dm/%40fengye404%2Ftermpilot)](https://www.npmjs.com/package/@fengye404/termpilot)
+[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/fengye404/TermPilot/docs.yml?branch=main&label=docs)](https://github.com/fengye404/TermPilot/actions)
 
-## 产品形态
+TermPilot 是一个终端优先的远程控制工具。它把电脑上的 `tmux` 会话暴露给手机浏览器，让你在电脑和手机之间无缝切换，同步查看和控制同一批任务。
+
+## 为什么是它
 
 - 一个 npm 包：`@fengye404/termpilot`
 - 一个服务器命令：`termpilot relay`
 - 一个电脑命令：`termpilot agent`
 - 手机端不安装，直接打开 relay 域名
-- relay 同时负责消息中继和网页托管
+- relay 同时负责 Web UI 托管和 WebSocket 中继
 
-## 5 分钟快速上手
+## 30 秒理解工作流
 
-### 1. 启动 relay
+1. 在服务器执行 `termpilot relay`
+2. 在电脑执行 `termpilot agent`
+3. 手机上打开 relay 域名并输入配对码
+4. 在电脑直接执行 `termpilot claude code`
+5. 手机和电脑同时看到同一个会话输出
+
+## 快速开始
 
-在云服务器或一台能被手机访问到的机器上执行：
+### 1. 启动 relay
 
 ```bash
 npm install -g @fengye404/termpilot
 termpilot relay
 ```
 
-如果你只是先本地体验，也可以直接在自己电脑上跑 relay，然后让手机走局域网访问。
-
-### 2. 启动电脑 agent
-
-在你的电脑上执行：
+### 2. 启动 agent
 
 ```bash
 npm install -g @fengye404/termpilot
-termpilot agent --relay ws://your-domain.com:8787/ws
+termpilot agent
 ```
 
-这条命令会直接：
+第一次运行时，`termpilot agent` 会交互式询问：
 
-- 后台启动 agent
-- 复用已有本地 agent（如果已经在跑）
-- 输出一次性配对码
+1. relay 域名或 IP
+2. 端口，默认 `8787`
 
-常用管理命令：
-
-```bash
-termpilot agent status
-termpilot agent stop
-```
+然后它会自动保存配置、后台启动 agent，并打印一次性配对码。
 
 ### 3. 手机完成配对
 
-手机浏览器直接打开 relay 域名：
+手机浏览器打开：
 
 - `http://your-domain.com:8787`
-- 或反代后的 `https://your-domain.com`
-
-然后：
+- 或 `https://your-domain.com`
 
-1. 输入电脑端刚打印出来的配对码
-2. 点“配对”
-3. 成功后直接进入会话列表
+输入配对码后，直接进入会话列表。
 
-### 4. 直接跑一个可同步的任务
-
-日常最短路径是：
+### 4. 直接启动任务
 
 ```bash
 termpilot claude code
@@ -72,164 +66,60 @@ termpilot claude code
 termpilot open code
 ```
 
-这会直接：
-
-- 创建一个受 TermPilot 管理的 `tmux` 会话
-- 把命令写进这个会话
-- 当前终端自动 attach 进去
-- 手机端同步看到同一个会话
-
-### 5. 你现在应该能做到什么
-
-此时你可以：
-
-- 在电脑上看 `claude code` / `open code` 的流式输出
-- 在手机上看同一份输出
-- 在手机上补一条命令、发快捷键、关闭会话
-- 随时在电脑和手机之间切换
-
-### 服务器
-
-发布后：
-
-```bash
-npm install -g @fengye404/termpilot
-termpilot relay
-```
-
-当前仓库内本地验证：
-
-```bash
-pnpm install
-pnpm build
-npm install -g .
-termpilot relay
-```
+这会直接创建一个受 TermPilot 管理的 `tmux` 会话并 attach 到当前终端，手机端会同步看到同一个会话。
 
-常用参数：
+## 常用命令
 
 ```bash
 termpilot relay
-DATABASE_URL=postgresql://user:pass@127.0.0.1:5432/termpilot termpilot relay
-```
-
-### 电脑
-
-```bash
-npm install -g @fengye404/termpilot
-termpilot agent --relay ws://your-domain.com/ws
-```
-
-如果你只是想看调试日志，可以显式前台运行：
-
-```bash
-termpilot agent --relay ws://your-domain.com/ws --foreground
-```
-
-查看后台状态：
-
-```bash
+termpilot relay stop
+termpilot relay run
+termpilot agent
+termpilot agent --pair
 termpilot agent status
-```
-
-停止后台 agent：
-
-```bash
 termpilot agent stop
-```
-
-本地测试：
-
-```bash
-termpilot agent --relay ws://127.0.0.1:8787/ws
-```
-
-### 手机
-
-直接打开 relay 域名：
-
-- `https://your-domain.com`
-
-首次使用时，直接执行上面的 `termpilot agent --relay ...` 就会拿到配对码；`termpilot pair` 现在只是补充入口，用于你已经有后台 agent、但想重新生成一次配对码的场景。
-
-配对成功后：
-
-- 访问令牌会自动写回页面
-- 手机端默认先显示会话列表
-- 点进一个会话后才进入终端详情页
-- 连接信息和设备设置都在页面底部折叠区
-
-## 日常使用
-
-### 直接把命令交给 TermPilot
-
-```bash
 termpilot claude code
 termpilot open code
-```
-
-如果你想跑别的命令，也可以直接：
-
-```bash
-termpilot npm run dev
-termpilot python worker.py
-```
-
-### 手动管理会话
-
-创建会话并进入：
-
-```bash
-termpilot create --name claude-main --cwd /path/to/project
+termpilot create --name my-task --cwd /path/to/project
 termpilot list
 termpilot attach --sid <sid>
+termpilot kill --sid <sid>
 ```
 
-进入会话以后，你仍然可以自己手动运行：
+## 文档
 
-```bash
-claude code
-# 或
-open code
-```
+- [文档首页](./docs/index.md)
+- [快速开始](./docs/getting-started.md)
+- [部署与运维指南](./docs/operations-guide.md)
+- [当前架构](./docs/architecture.md)
+- [当前协议](./docs/protocol.md)
+- [开发文档](./docs/development.md)
 
-此时手机和电脑看到的是同一个会话，输出会同步刷新。
+## 最佳实践
 
-## 常用命令
+1. 需要跨端同步的任务，一开始就用 `termpilot claude code`、`termpilot open code` 或 `termpilot create` 启动，不要先在普通终端里跑再想着接管。
+2. `termpilot agent` 适合作为长期后台入口。第一次配置完之后，日常只需要记住这一条命令。
+3. relay 长期使用时，优先挂到 HTTPS/WSS 域名后面；本地演示再用裸 IP 和 `8787`。
+4. 手机更适合看输出、发短命令和轻控制；电脑前的重输入仍然建议在本地终端完成。
+
+## 本地开发
 
 ```bash
-termpilot relay
-termpilot agent --relay ws://127.0.0.1:8787/ws
-termpilot agent status
-termpilot agent stop
-termpilot pair
-termpilot create --name claude-main
-termpilot list
-termpilot attach --sid <sid>
-termpilot kill --sid <sid>
-termpilot grants
-termpilot audit --limit 30
-termpilot revoke --token <accessToken>
-termpilot doctor
+pnpm install
+pnpm build
+pnpm docs:dev
+pnpm test:ui-smoke
+pnpm check:stability
 ```
-
-## 最佳实践
-
-1. 需要跨端同步的任务，一开始就用 `termpilot create` 创建，不要先在普通终端里跑再想着接管。
-2. 如果只是想“开一个会话然后立刻跑起来”，优先用 `termpilot claude code` 这类直达命令，不必手动 `create + attach`。
-3. 一个长期任务用一个独立会话，名称直接写任务语义，比如 `claude-main`、`deploy-watch`、`batch-fix`。
-4. 电脑前重操作优先 `termpilot attach`；手机更适合看进度、发短命令、补快捷键和关闭会话。
-5. 普通 iTerm / Terminal 标签页不是 TermPilot 管理对象，不要指望后面“无缝接管”进来。
-6. 手机优先走一次性配对码，不要长期传播访问令牌。
-7. 要长期使用 relay，优先放到 HTTPS/WSS 域名后面，并接 PostgreSQL；本地演示可以先用内存模式。
-8. 换手机或访问权变更时，先 `termpilot grants`，再 `termpilot revoke --token ...`。
-9. 想排查控制历史时先看 `termpilot audit --limit 30`。
+10. 想排查控制历史时先看 `termpilot audit --limit 30`。
+11. 服务器上日常用 `termpilot relay` 后台运行；只有排查问题时才用 `termpilot relay run`。
 
 ## 常见坑
 
-- `termpilot agent --relay ...` 不会停在前台，这是正常的；它默认就是后台守护进程。
+- `termpilot agent` 不会停在前台，这是正常的；它默认就是后台守护进程。
+- `termpilot relay` 默认也不会停在前台；想看日志请用 `termpilot relay run`。
 - 手机上看不到任务时，先确认这个任务是不是通过 `termpilot ...` 或 `termpilot create` 启动的。
-- 首次配对优先用 `termpilot agent --relay ...` 拿配对码；`termpilot pair` 只是补充命令。
+- 首次配对优先用 `termpilot agent` 拿配对码；重新给手机配对时用 `termpilot agent --pair`。
 - 外网正式使用时，不要长期直接裸奔 `ws://IP:8787/ws`，最好上域名和反代。
 
 ## 本地开发