@fengye404/termpilot 0.1.0

package/docs/architecture.md

@@ -0,0 +1,148 @@
+# TermPilot 当前代码架构
+
+## 1. 当前产品形态
+
+- 一个 npm 包：`termpilot`
+- 一个服务器命令：`termpilot relay`
+- 一个电脑命令：`termpilot agent`
+- 手机端不安装，直接打开 relay 域名
+- relay 同时负责 WebSocket 中继和 Web UI 托管
+
+对应拓扑：
+
+```text
+手机浏览器  --https/ws-->  relay  <--ws-->  PC 端 agent
+                              |
+                     配对、设备权限、消息路由、
+                     输出缓冲、审计日志、会话元数据、
+                     静态网页托管
+```
+
+## 2. 目录结构
+
+```text
+src/
+  cli.ts
+agent/
+  src/
+app/
+  src/
+    components/
+relay/
+  src/
+packages/
+  protocol/
+scripts/
+docs/
+```
+
+### `src/cli.ts`
+
+统一 CLI 入口，负责把内部多模块收敛成外部单命令产品：
+
+- `termpilot relay`
+- `termpilot agent`
+- `termpilot pair/create/list/attach/kill/...`
+
+### `agent/`
+
+PC 端常驻进程和本地命令实现：
+
+- `src/cli.ts`：agent 侧命令实现
+- `src/index.ts`：开发态入口包装
+- `src/daemon.ts`：常驻连接、轮询 `tmux`、同步输出与状态
+- `src/tmux-backend.ts`：`tmux` 会话创建、输入、关闭、附着、抓屏
+- `src/relay-admin.ts`：agent 调用 relay 管理接口的轻量客户端
+- `src/state-store.ts`：本地 JSON 状态文件
+
+### `relay/`
+
+中继和网页托管层：
+
+- `src/server.ts`：WebSocket 路由、HTTP 接口、消息转发、静态网页托管
+- `src/index.ts`：开发态入口包装
+- `src/session-store.ts`：会话元数据存储
+- `src/auth-store.ts`：配对码与访问令牌存储
+- `src/audit-store.ts`：审计事件存储
+- `src/config.ts`：环境变量配置
+
+### `app/`
+
+手机端 PWA：
+
+- `src/App.tsx`：状态、副作用、WebSocket 协调
+- `src/components/ConnectionPanel.tsx`：连接与配对 UI
+- `src/components/CreateSessionPanel.tsx`：创建会话 UI
+- `src/components/SessionListPanel.tsx`：会话搜索、筛选、置顶、关闭
+- `src/components/TerminalWorkspace.tsx`：终端区域、快捷键和粘贴发送
+- `src/components/chrome.tsx`：通用面板与字段组件
+
+### `packages/protocol/`
+
+三端共享协议类型：
+
+- 会话消息
+- 配对与令牌数据结构
+- 审计事件结构
+
+## 3. 运行时数据流
+
+### 启动链路
+
+1. 服务器执行 `termpilot relay`
+2. relay 监听 HTTP/WebSocket，并托管 `app/dist`
+3. 电脑执行 `termpilot agent --relay ...`
+4. 手机上直接打开 relay 域名
+
+### 会话创建
+
+1. 手机端或电脑端发起 `session.create`
+2. relay 把请求转发给对应 device 的 agent
+3. agent 在本地创建 `tmux` 会话
+4. agent 回推 `session.created`
+5. relay 广播给有权限的 client
+
+### 输出同步
+
+1. agent 周期性 `capture-pane`
+2. 如果缓冲变化，生成新的 `session.output`
+3. relay 缓冲最近一段输出帧
+4. app 渲染最新快照
+5. client 重连后可用 `session.replay` 补拉
+
+### 配对与访问控制
+
+1. 电脑端执行 `termpilot pair`
+2. relay 创建一次性配对码
+3. 手机端输入配对码，兑换设备访问令牌
+4. client WebSocket 以后携带设备令牌
+5. relay 只向该 client 暴露允许访问的设备和会话
+
+## 4. 当前实现边界
+
+- 当前终端同步策略仍是“快照替换”，不是字节级增量流
+- relay 输出缓冲只保留最近一段，不做长期日志归档
+- 不接管 TermPilot 体系外的历史终端
+- 手机端定位是“查看、轻输入、轻控制”，不追求桌面级重度编辑体验
+
+## 5. 当前代码取舍
+
+- 对外形态已经统一成单一 CLI，但仓库内部仍保留 `agent/app/relay` 三个目录，方便独立开发
+- `app` 的状态和副作用仍集中在 `App.tsx`，但渲染层已经拆到独立组件
+- `relay` 已从单文件脚本式入口拆成 `server.ts + index.ts`
+- `agent` 已从单文件 CLI 拆成 `cli.ts + index.ts + daemon.ts + tmux-backend.ts`
+
+## 6. 当前验证方式
+
+最有价值的检查命令：
+
+- `pnpm typecheck`
+- `pnpm build`
+- `pnpm test:ui-smoke`
+- `pnpm check:stability`
+
+它们覆盖的重点是：
+
+- `termpilot relay` 和 `termpilot agent` 主链路
+- 输出缓冲与重连一致性
+- 手机端配对、切会话、关会话、清除绑定

package/docs/protocol.md

@@ -0,0 +1,216 @@
+# TermPilot 当前协议
+
+## 1. 连接入口
+
+手机端和 agent 都通过 relay 的同一个 WebSocket 入口连接：
+
+```text
+ws(s)://<relay-host>/ws?role=<agent|client>&token=<token>&deviceId=<deviceId?>
+```
+
+- `role=agent`：PC 端 agent
+- `role=client`：手机端或浏览器端
+- `token`：agent 固定令牌或 client 访问令牌
+- `deviceId`：agent 连接时必须带；client 在业务消息里指定
+
+## 2. 当前消息类型
+
+系统消息：
+
+- `auth.ok`
+- `error`
+- `relay.state`
+
+会话消息：
+
+- `session.list`
+- `session.list.result`
+- `session.create`
+- `session.created`
+- `session.input`
+- `session.resize`
+- `session.kill`
+- `session.replay`
+- `session.output`
+- `session.state`
+- `session.exit`
+
+## 3. 会话模型
+
+当前会话对象字段：
+
+- `sid`
+- `deviceId`
+- `name`
+- `backend`
+- `shell`
+- `cwd`
+- `status`
+- `startedAt`
+- `lastSeq`
+- `lastActivityAt`
+- `tmuxSessionName`
+
+当前 `backend` 固定为 `tmux`。
+
+## 4. 输入与快捷键
+
+当前支持的特殊按键：
+
+- `enter`
+- `tab`
+- `ctrl_c`
+- `ctrl_d`
+- `escape`
+- `arrow_up`
+- `arrow_down`
+- `arrow_left`
+- `arrow_right`
+
+普通输入仍走：
+
+```json
+{
+  "type": "session.input",
+  "deviceId": "pc-main",
+  "sid": "s_123",
+  "payload": {
+    "text": "echo hello\n"
+  }
+}
+```
+
+## 5. 输出同步策略
+
+当前不是字节级终端流，而是“快照替换”：
+
+```json
+{
+  "type": "session.output",
+  "deviceId": "pc-main",
+  "sid": "s_123",
+  "seq": 12,
+  "payload": {
+    "data": "...当前 pane 快照...",
+    "mode": "replace"
+  }
+}
+```
+
+对应实现：
+
+- agent 轮询 `tmux capture-pane`
+- 只有缓冲变化时才推新帧
+- relay 保留最近一段输出帧
+- client 重连后用 `session.replay` 补拉
+
+## 6. HTTP 接口
+
+### 创建一次性配对码
+
+`POST /api/pairing-codes`
+
+- 需要 `Authorization: Bearer <agent-token>`
+- 请求体：`{ "deviceId": "pc-main" }`
+
+### 兑换配对码
+
+`POST /api/pairings/redeem`
+
+- 请求体：`{ "pairingCode": "ABC-234" }`
+
+### 查看当前设备已发出的访问令牌
+
+`GET /api/devices/:deviceId/grants`
+
+### 撤销访问令牌
+
+`DELETE /api/devices/:deviceId/grants/:accessToken`
+
+### 查看审计事件
+
+`GET /api/devices/:deviceId/audit-events?limit=20`
+
+### 健康检查
+
+`GET /health`
+
+返回：
+
+- `ok`
+- `storeMode`
+- `agentsOnline`
+- `clientsOnline`
+- `webUiReady`
+
+## 7. 当前产品入口与协议的关系
+
+- `termpilot relay` 对外暴露 HTTP + WebSocket
+- 手机端直接访问 relay 域名，再走 `/ws`
+- `termpilot agent` 始终只和 `/ws`、`/api/*` 交互
+- 手机端网页不再要求单独部署
+
+当前审计动作包括：
+
+- `pairing.code_created`
+- `pairing.redeemed`
+- `grant.revoked`
+- `session.create_requested`
+- `session.kill_requested`
+
+## 8. 当前协议边界
+
+- client 侧仍直接处理较多状态拼装，没有事件聚合接口
+- 输出补拉依赖最近缓冲，不是完整历史回放
+- 审计目前只记录关键控制动作，不记录每一次普通输入
+
+字段说明：
+
+- `seq`：输出序号，递增
+- `data`：当前终端快照
+- `mode=replace`：客户端收到后直接替换当前渲染内容
+
+## 9. 会话状态消息
+
+会话状态变化时发送：
+
+```json
+{
+  "type": "session.state",
+  "deviceId": "pc-main",
+  "sid": "s_123",
+  "payload": {
+    "session": {}
+  }
+}
+```
+
+会话退出时发送：
+
+```json
+{
+  "type": "session.exit",
+  "deviceId": "pc-main",
+  "sid": "s_123",
+  "payload": {
+    "reason": "用户主动关闭会话",
+    "exitCode": null
+  }
+}
+```
+
+## 10. 输出补拉
+
+手机端重连或重新进入会话时，可以请求补拉最近输出：
+
+```json
+{
+  "type": "session.replay",
+  "reqId": "req_replay_001",
+  "deviceId": "pc-main",
+  "sid": "s_123",
+  "payload": {
+    "afterSeq": 8
+  }
+}
+```

package/docs/tech-selection-2026.md

@@ -0,0 +1,77 @@
+# TermPilot 全栈技术选型（2026 版）
+
+## 最终方案
+
+这次技术选型只保留已经拍板的方案，不再保留多余备选。
+
+- 语言：TypeScript
+- 运行时：Node.js 24 LTS
+- 包管理：pnpm workspace
+
+手机端 `app/`：
+
+- React
+- Vite
+- Tailwind CSS v4
+- xterm.js
+- PWA
+
+中继服务 `relay/`：
+
+- Fastify
+- WebSocket
+- PostgreSQL
+
+PC 端 `agent/`：
+
+- Node.js
+- tmux
+
+## 为什么是这套
+
+这套方案最重要的优点不是“技术多”，而是“统一且克制”：
+
+- 三端尽量共享同一种语言和同一种工程习惯
+- 前端走最主流的 React + Vite 路线，AI 最容易写对
+- relay 不引入重框架，Fastify 足够轻也足够成熟
+- agent 不引入多余框架，直接围绕 `tmux` 做就够了
+- 仓库层面用 pnpm workspace，把多模块项目管清楚
+
+## 为什么不再加别的
+
+这次我刻意把一些名字收掉了，因为它们不是当前必须项：
+
+- 不加 `Next.js`
+- 不加 `React Native`
+- 不加 `Flutter`
+- 不加 `shadcn/ui`
+- 不加 `Zustand`
+- 不加 `Drizzle`
+- 不加 `Zod`
+
+这些技术不是不好，而是对当前目标来说不是最小必要集合。
+
+TermPilot 现在要的不是“技术看起来完整”，而是：
+
+- AI 最容易持续参与开发
+- 三端结构统一
+- 尽量少配置、少概念、少框架
+
+## 当前代码与选型的对应关系
+
+当前仓库已经按这套方案开始收敛：
+
+- `app/`：React + Vite + Tailwind CSS + xterm.js
+- `relay/`：Fastify + WebSocket
+- `agent/`：Node.js + tmux
+- `packages/protocol/`：共享协议类型
+- 根目录：pnpm workspace
+
+其中 PostgreSQL 采用的是“正式栈默认使用、开发时允许内存回退”的策略：
+
+- 设置 `DATABASE_URL` 时使用 PostgreSQL
+- 未设置时，为了本地开发效率，relay 会退回内存模式
+
+## 一句话总结
+
+**TermPilot 当前最合理、最 AI 友好的全栈方案，就是 `TypeScript + Node.js 24 LTS + pnpm workspace`，在此基础上，手机端用 `React + Vite + Tailwind CSS + xterm.js`，中继服务用 `Fastify + WebSocket + PostgreSQL`，PC 端围绕 `tmux`。**

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fengye404/termpilot",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@10.31.0",
+  "description": "一个基于 tmux 的终端会话跨端查看与控制原型。",
+  "bin": {
+    "termpilot": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "app/dist",
+    "README.md",
+    "docs",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm -r typecheck && tsc --noEmit -p tsconfig.json && pnpm --filter @termpilot/app build && tsup",
+    "build:web": "pnpm --filter @termpilot/app build",
+    "typecheck": "pnpm -r typecheck && tsc --noEmit -p tsconfig.json",
+    "dev:app": "pnpm --filter @termpilot/app run dev",
+    "dev:relay": "pnpm --filter @termpilot/relay run dev",
+    "dev:agent": "pnpm --filter @termpilot/agent run dev",
+    "cli": "node dist/cli.js",
+    "agent:create": "pnpm --filter @termpilot/agent run create",
+    "agent:list": "pnpm --filter @termpilot/agent run list",
+    "agent:kill": "pnpm --filter @termpilot/agent run kill",
+    "agent:attach": "pnpm --filter @termpilot/agent run attach",
+    "agent:pair": "pnpm --filter @termpilot/agent run pair",
+    "agent:grants": "pnpm --filter @termpilot/agent run grants",
+    "agent:audit": "pnpm --filter @termpilot/agent run audit",
+    "agent:revoke": "pnpm --filter @termpilot/agent run revoke",
+    "agent:doctor": "pnpm --filter @termpilot/agent run doctor",
+    "check:stability": "pnpm build && node scripts/check-relay-agent-stability.mjs",
+    "test:ui-smoke": "pnpm build && TERMPILOT_APP_URL=http://127.0.0.1:18787 TERMPILOT_RELAY_URL=ws://127.0.0.1:18787/ws python3 /Users/fengye/.agents/skills/webapp-testing/scripts/with_server.py --server \"PORT=18787 node dist/cli.js relay\" --port 18787 -- python3 scripts/ui_smoke.py",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@fastify/websocket": "^11.2.0",
+    "fastify": "^5.6.1",
+    "pg": "^8.16.3",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}