@tunnelbox/cursor 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +127 -86
  2. package/README.zh-CN.md +127 -0
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,86 +1,127 @@
1
- # @tunnelbox/cursor
2
-
3
- tunnelbox 的 **Cursor 适配器**（独立进程，驱动 **Cursor CLI** 的 headless 模式）：手机远程驱动电脑上的 Cursor agent（会话/流式/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
4
-
5
- ```
6
- 手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
7
- └─ agent -p --output-format stream-json --stream-partial-output
8
- ```
9
-
10
- > 说明：Cursor 官方提供了 headless CLI（`agent -p`，见 https://cursor.com/docs/cli ），
11
- > 本适配器即其"CLI 外部驱动"桥接（仓库原列为 C 类/IDE 型，落地路径取官方 agent CLI）。
12
-
13
- ## 前置条件
14
-
15
- - Node.js ≥ 22；
16
- - 已安装 **Cursor CLI** 并登录/配置 API key：
17
- - macOS/Linux：`curl https://cursor.com/install -fsS | bash`
18
- - Windows：`irm 'https://cursor.com/install?win32=true' | iex`
19
- - `agent -p "hello"` 可正常输出（headless 走 Cursor 计费，需在计划内）。
20
-
21
- ## 构建与运行
22
-
23
- ```bash
24
- cd plugin && npm install # workspaces 根（含 cursor）
25
- cd cursor && npm run build
26
- node dist/index.mjs # 或 npm start
27
- ```
28
-
29
- ## 配置
30
-
31
- | 环境变量 | 默认 | 说明 |
32
- |---|---|---|
33
- | `TUNNELBOX_RELAY_URL` | state 保存地址 | 中继地址 |
34
- | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区（agent 在该目录跑） |
35
- | `TUNNELBOX_CURSOR_MODE` | `agent` | `agent` / `plan` / `ask`（`--mode`） |
36
- | `TUNNELBOX_CURSOR_MODEL` | Cursor 默认 | `--model` |
37
- | `TUNNELBOX_CURSOR_FORCE` | 关 | 加 `--force`：允许直接改文件（无确认） |
38
- | `TUNNELBOX_CURSOR_YOLO` | 关 | 加 `--yolo`（更强放行，危险，慎用） |
39
- | `TUNNELBOX_CURSOR_SANDBOX` | `enabled` | `--sandbox enabled/disabled` |
40
- | `TUNNELBOX_CURSOR_BIN` | `agent` | Cursor CLI 可执行名/绝对路径 |
41
-
42
- ```bash
43
- TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_CURSOR_MODE=plan TUNNELBOX_CURSOR_FORCE=1 node dist/index.mjs
44
- ```
45
-
46
- ## 能力位
47
-
48
- | 能力 | 值 | 说明 |
49
- |---|---|---|
50
- | streaming | true | stream-json：assistant 增量行（timestamp_ms）→ delta；整块行（model_call_id）→ 收尾 |
51
- | thinking | **false** | 官方文档：print 模式**抑制 thinking**（"thinking events are suppressed in print mode"，见 cursor.com/docs/cli/reference/output-format），headless 拿不到推理流 |
52
- | permission | **false** | 官方口径（见「审批与权限」）：Cursor hooks 可 `allow/deny/ask` 门控，但仅面向 IDE/Cmd+K 与 Cloud agents；headless `agent -p` **无外部审批中继通道** → 手机审批不可行。放行由 `--force/--yolo` + `--sandbox` + `permissions` allow/deny 决定 |
53
- | commands | true | `/new` `/help` |
54
- | abort | true | kill 子进程（SIGTERM → SIGKILL） |
55
-
56
- ## 审批与权限（官方口径）
57
-
58
- - Cursor 官方插件/钩子（[cursor/plugins](https://github.com/cursor/plugins)、[cursor.com/docs/hooks](https://cursor.com/docs/hooks)）提供 `preToolUse` / `beforeShellExecution` / `beforeMCPExecution` 等 hook，可返回 `permission: allow | deny`（`preToolUse` 的 `ask` 不生效；shell/MCP 的 `ask` 会向**本地用户**弹审批）。
59
- - 但 hooks 面向 **Cmd+K / Agent Chat（IDE）与 Cloud agents**；官方文档**未说明本地 headless `agent -p` 会加载 hooks**，也没有"外部驱动等待手机决定后回填"的中继通道（对比：Codex 有 `PermissionRequest` hook + 外部审批 UI 用例；Cursor 暂无）。
60
- - 因此 **`capability.permission=false`**：手机审批对 Cursor headless **不可行**；放行由 `permissions.allow/deny`（`~/.cursor/cli-config.json` 或 `<project>/.cursor/cli.json`）+ `--force/--yolo`（隐含信任工作区、跳过 MCP 确认）+ `--sandbox` 决定。默认不传 `--force`（只出方案不改文件）并开 `--sandbox=enabled`。
61
- - 若未来 Cursor 为 CLI 暴露 hooks/审批事件中继（当前为开放功能请求），再评估恢复手机审批。
62
-
63
- ## 会话模型
64
-
65
- - 会话 = 本地镜像（`~/.tunnelbox/cursor-sessions/<uuid>/`）：每个流式部件/用户消息即时落一行，供列表/历史/删除。
66
- - 续聊：尽力从流中采集 Cursor chat id（`meta.resumeId`）→ 后续消息用 `--resume=<id>`；采集不到则该会话每次为独立问答（连续上下文受限）。
67
- - 状态文件：`~/.tunnelbox/remote-state.cursor.json`。
68
-
69
- ## 目录结构
70
-
71
- ```
72
- plugin/cursor/
73
- ├── package.json / tsconfig.json
74
- ├── scripts/build.mjs / smoke.mjs
75
- └── src/
76
- ├── index.ts # env 解析 + 连接中继
77
- ├── bridge.ts # relay/配对/消息路由/回合/镜像写入
78
- ├── runner.ts # agent -p stream-json 子进程（增量解析 + tool_call + kill）
79
- ├── mirror.ts # 会话镜像存储（列表/历史/删除/meta）
80
- └── globals.d.ts
81
- ```
82
-
83
- ## 备注
84
-
85
- - 未验证项（需装有 Cursor CLI 实测校正）：stream-json 行的确切字段（assistant 增量/整块、tool_call 形态、可 resume 的 chat id 出现在哪个事件）、`--force/--yolo` 与 `--sandbox` 组合的放行语义、`--mode` 参数名、headless `agent -p` 是否加载 hooks（官方文档未说明，倾向不支持）。解析集中在 `runner.ts`，便于按实际输出调整。
86
- - 安全：默认不传 `--force`（agent 不改文件、只出方案），并开 `--sandbox=enabled`；要实际改代码需显式 `TUNNELBOX_CURSOR_FORCE=1`。请勿在不受信目录启用 yolo。
1
+ # @tunnelbox/cursor
2
+
3
+ [English](README.md) · [简体中文](README.zh-CN.md)
4
+
5
+ **Official website:** [www.tunnelbox.top](https://www.tunnelbox.top)
6
+
7
+ **tunnelbox Cursor adapter (standalone daemon):** drive the Cursor agent on your computer from your phone — sessions, streaming, abort, delete. It drives the Cursor CLI headless mode and dials **out** to a relay only (no public IP, no port forwarding).
8
+
9
+ ```
10
+ Phone app ──WSS──► relay ──WSS──► tunnelbox-cursor (this adapter)
11
+ └─ agent -p --output-format stream-json --stream-partial-output
12
+ ```
13
+
14
+ ## Quick start (install → run → pair → use)
15
+
16
+ Follow these steps once on a computer that has Cursor CLI installed and signed in.
17
+
18
+ ### Step 0 — Prepare your phone
19
+
20
+ Install the tunnelbox App (Android & iOS) from the official website: **https://www.tunnelbox.top**
21
+
22
+ - Sign in / create an account when prompted.
23
+
24
+ ### Step 1 — Install the adapter on your computer
25
+
26
+ Prerequisites: Node.js ≥ 22, and **Cursor CLI** installed & configured (`agent -p "hello"` works). Headless mode bills against your Cursor plan.
27
+
28
+ ```bash
29
+ npm install -g @tunnelbox/cursor
30
+ ```
31
+
32
+ ### Step 2 — Run it
33
+
34
+ ```bash
35
+ tunnelbox-cursor
36
+ ```
37
+
38
+ On first start the adapter connects to the relay and prints a **pairing QR code + pairing code** in the terminal.
39
+
40
+ ### Step 3 — Pair with your phone
41
+
42
+ In the phone app tap **Scan to pair** and scan the terminal QR code (or type the pairing code manually). The code is single-use and valid for about 10 minutes.
43
+
44
+ - Once bound, the adapter prints "connected account — open the app and pick this computer" on later starts and does not refresh the code.
45
+ - Want a fresh code any time? Run `tunnelbox-cursor --pair`.
46
+
47
+ ### Step 4 — Use it from your phone
48
+
49
+ In the app, open this computer and you can start new sessions, send messages, watch streaming output, and abort a running session.
50
+
51
+ ## Configuration
52
+
53
+ | Env var | Default | Description |
54
+ |---|---|---|
55
+ | `TUNNELBOX_RELAY_URL` | saved relay URL | Relay address |
56
+ | `TUNNELBOX_CWD` | `process.cwd()` | Default workspace (agent runs there) |
57
+ | `TUNNELBOX_CURSOR_MODE` | `agent` | `agent` / `plan` / `ask` (`--mode`) |
58
+ | `TUNNELBOX_CURSOR_MODEL` | Cursor default | `--model` |
59
+ | `TUNNELBOX_CURSOR_FORCE` | off | Add `--force`: allow direct file edits (no confirmation) |
60
+ | `TUNNELBOX_CURSOR_YOLO` | off | Add `--yolo` (broader permissions — dangerous) |
61
+ | `TUNNELBOX_CURSOR_SANDBOX` | `enabled` | `--sandbox enabled/disabled` |
62
+ | `TUNNELBOX_CURSOR_BIN` | `agent` | Cursor CLI executable name / absolute path |
63
+
64
+ ```bash
65
+ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_CURSOR_MODE=plan tunnelbox-cursor
66
+ ```
67
+
68
+ ## Capabilities
69
+
70
+ | Capability | Value | Notes |
71
+ |---|---|---|
72
+ | streaming | ✅ | stream-json: assistant delta lines → live deltas |
73
+ | thinking | ❌ | Cursor suppresses thinking in print mode (headless has no reasoning stream) |
74
+ | permission | ❌ | Cursor's hooks target IDE / Cmd+K / Cloud agents; headless `agent -p` has no external approval channel — **no phone approval**. Gating is decided by `--force/--yolo` + `--sandbox` + `permissions` allow/deny |
75
+ | commands | ✅ | `/new`, `/help` |
76
+ | abort | ✅ | kill subprocess (SIGTERM → SIGKILL) |
77
+ | workspaces | ✅ | session `cwd` |
78
+
79
+ ## Permissions & approvals (official constraints)
80
+
81
+ - Cursor official hooks can `allow/deny/ask`, but they serve **IDE / Cmd+K / Cloud agents**; the docs do not state that local headless `agent -p` loads hooks, and there is no relay channel to await a phone decision.
82
+ - Therefore `capability.permission=false`: **phone approval is not available for Cursor headless**. Gating comes from `permissions.allow/deny` (`~/.cursor/cli-config.json` or `<project>/.cursor/cli.json`) + `--force/--yolo` + `--sandbox`.
83
+ - Defaults are safe: no `--force` (agent only proposes, doesn't edit) and `--sandbox=enabled`.
84
+
85
+ ## Sessions
86
+
87
+ - Sessions are local mirrors (`~/.tunnelbox/cursor-sessions/<uuid>/`): each streamed part/user message is written immediately for list/history/delete.
88
+ - Continuation: the adapter tries to capture the Cursor chat id (`meta.resumeId`) from the stream and resumes with `--resume=<id>`; if it can't be captured, each session is an independent Q&A (limited context continuity).
89
+ - State file: `~/.tunnelbox/remote-state.cursor.json`.
90
+
91
+ ## Security notes
92
+
93
+ - By default no `--force` is passed (the agent doesn't edit files, it only proposes) and `--sandbox=enabled` is on.
94
+ - To actually change code you must explicitly set `TUNNELBOX_CURSOR_FORCE=1`. Don't enable yolo in untrusted directories.
95
+ - Don't expose sensitive projects to an untrusted phone.
96
+
97
+ ## Multilingual
98
+
99
+ User-visible output supports 8 languages (`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`). Resolution order: `TUNNELBOX_LANG` > saved `remote-state.cursor.json.lang` > system locale > `en-US`.
100
+
101
+ ## Troubleshooting
102
+
103
+ | Problem | Fix |
104
+ |---|---|
105
+ | No QR / pairing code on screen | Run `tunnelbox-cursor --pair` to print a fresh one |
106
+ | Need to pair a different phone | Unbind in the app settings, then run with `--pair` again |
107
+ | Already bound but phone doesn't connect | Confirm both use the same relay; check `~/.tunnelbox/tunnelbox.log` |
108
+ | Use your own relay | Start with `TUNNELBOX_RELAY_URL=wss://<your-relay>` |
109
+
110
+ ## State files
111
+
112
+ - `~/.tunnelbox/remote-state.cursor.json` — agentID / relay / bound state / language
113
+ - `~/.tunnelbox/cursor-sessions/` — local session mirrors
114
+ - `~/.tunnelbox/remote-pairing.cursor.txt` + `remote-pairing.json` — latest pairing info
115
+ - `~/.tunnelbox/tunnelbox.log` — adapter log
116
+
117
+ ## Uninstall
118
+
119
+ ```bash
120
+ npm uninstall -g @tunnelbox/cursor
121
+ ```
122
+
123
+ Remove `~/.tunnelbox` (all adapters' shared state) only if you no longer use any tunnelbox adapter.
124
+
125
+ ## Development
126
+
127
+ Implementation details (protocol mapping, source layout, design decisions, untested items) are kept in the source repository as `DEV.md` next to this package, plus the protocol spec under the repo's `docs/`.
package/README.zh-CN.md ADDED
@@ -0,0 +1,127 @@
1
+ # @tunnelbox/cursor
2
+
3
+ [English](README.md) · [简体中文](README.zh-CN.md)
4
+
5
+ **官网：** [www.tunnelbox.top](https://www.tunnelbox.top)
6
+
7
+ **tunnelbox Cursor 适配器（独立进程）**：用手机远程驱动电脑上的 Cursor agent——会话 / 流式 / 中止 / 删除。它驱动 Cursor CLI 的 headless 模式，只向中继发出站连接（无需公网 IP / 端口映射）。
8
+
9
+ ```
10
+ 手机 App ──WSS──► relay ──WSS──► tunnelbox-cursor（本适配器）
11
+ └─ agent -p --output-format stream-json --stream-partial-output
12
+ ```
13
+
14
+ ## 快速上手（安装 → 运行 → 配对 → 使用）
15
+
16
+ 在装有 Cursor CLI 并已配置的电脑上，按以下步骤操作一次即可。
17
+
18
+ ### 第 0 步 — 准备手机
19
+
20
+ 在官网下载并安装 tunnelbox App（Android / iOS 均已上架）：**https://www.tunnelbox.top**
21
+
22
+ - 按提示登录/注册账号。
23
+
24
+ ### 第 1 步 — 电脑上安装适配器
25
+
26
+ 前置条件：Node.js ≥ 22，且本机已安装并登录 **Cursor CLI**（`agent -p "hello"` 可正常输出）。headless 走 Cursor 计费，需在你的套餐计划内。
27
+
28
+ ```bash
29
+ npm install -g @tunnelbox/cursor
30
+ ```
31
+
32
+ ### 第 2 步 — 运行
33
+
34
+ ```bash
35
+ tunnelbox-cursor
36
+ ```
37
+
38
+ 首次启动会连接中继，并在终端打印**配对二维码 + 配对码**。
39
+
40
+ ### 第 3 步 — 与手机配对
41
+
42
+ 在手机 App 点「扫一扫配对」，扫描终端二维码（或手动输入配对码）。配对码一次性有效，约 10 分钟。
43
+
44
+ - 绑定后再次启动会打印「已绑定账号，从手机「我的电脑」直接连接」，不再刷新码；
45
+ - 随时需要新码：运行 `tunnelbox-cursor --pair`。
46
+
47
+ ### 第 4 步 — 在手机上使用
48
+
49
+ 在 App 里打开这台电脑，即可新建会话、发消息、看流式输出、中止运行中的会话。
50
+
51
+ ## 配置
52
+
53
+ | 环境变量 | 默认 | 说明 |
54
+ |---|---|---|
55
+ | `TUNNELBOX_RELAY_URL` | state 保存的地址 | 中继地址 |
56
+ | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区（agent 在该目录跑） |
57
+ | `TUNNELBOX_CURSOR_MODE` | `agent` | `agent` / `plan` / `ask`（`--mode`） |
58
+ | `TUNNELBOX_CURSOR_MODEL` | Cursor 默认 | `--model` |
59
+ | `TUNNELBOX_CURSOR_FORCE` | 关 | 加 `--force`：允许直接改文件（无确认） |
60
+ | `TUNNELBOX_CURSOR_YOLO` | 关 | 加 `--yolo`（更强放行，危险，慎用） |
61
+ | `TUNNELBOX_CURSOR_SANDBOX` | `enabled` | `--sandbox enabled/disabled` |
62
+ | `TUNNELBOX_CURSOR_BIN` | `agent` | Cursor CLI 可执行名/绝对路径 |
63
+
64
+ ```bash
65
+ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_CURSOR_MODE=plan tunnelbox-cursor
66
+ ```
67
+
68
+ ## 能力位
69
+
70
+ | 能力 | 值 | 说明 |
71
+ |---|---|---|
72
+ | streaming | ✅ | stream-json：assistant 增量行 → 实时增量 |
73
+ | thinking | ❌ | Cursor 在 print 模式**抑制思考流**，headless 拿不到推理流 |
74
+ | permission | ❌ | Cursor hooks 面向 IDE / Cmd+K / Cloud agents；headless `agent -p` **无外部审批中继通道** → 无手机审批。放行由 `--force/--yolo` + `--sandbox` + `permissions` allow/deny 决定 |
75
+ | commands | ✅ | `/new`、`/help` |
76
+ | abort | ✅ | kill 子进程（SIGTERM → SIGKILL） |
77
+ | workspaces | ✅ | 会话 `cwd` |
78
+
79
+ ## 审批与权限（官方口径）
80
+
81
+ - Cursor 官方 hooks 可 `allow/deny/ask`，但面向 **IDE / Cmd+K / Cloud agents**；文档未说明 headless `agent -p` 会加载 hooks，也没有"等待手机决定后回填"的中继通道。
82
+ - 因此 **`capability.permission=false`**：Cursor headless **不支持手机审批**。放行由 `permissions.allow/deny`（`~/.cursor/cli-config.json` 或 `<项目>/.cursor/cli.json`）+ `--force/--yolo` + `--sandbox` 决定。
83
+ - 默认安全：不传 `--force`（agent 只出方案不改文件），并开启 `--sandbox=enabled`。
84
+
85
+ ## 会话模型
86
+
87
+ - 会话 = 本地镜像（`~/.tunnelbox/cursor-sessions/<uuid>/`）：每个流式部件/用户消息即时落盘，供列表/历史/删除。
88
+ - 续聊：尽力从流中采集 Cursor chat id（`meta.resumeId`）→ 用 `--resume=<id>`；采集不到则该会话为独立问答（连续上下文受限）。
89
+ - 状态文件：`~/.tunnelbox/remote-state.cursor.json`。
90
+
91
+ ## 安全说明
92
+
93
+ - 默认不传 `--force`（agent 不改文件、只出方案），并开 `--sandbox=enabled`；
94
+ - 要实际改代码需显式 `TUNNELBOX_CURSOR_FORCE=1`；请勿在不受信目录启用 yolo；
95
+ - 请勿把敏感工程目录暴露给不受信手机。
96
+
97
+ ## 多语言
98
+
99
+ 用户可见输出支持 8 种语言（`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`）。解析顺序：`TUNNELBOX_LANG` > `remote-state.cursor.json` 的 `lang` > 系统 locale > 默认 `en-US`。
100
+
101
+ ## 故障排查
102
+
103
+ | 问题 | 解决 |
104
+ |---|---|
105
+ | 终端没有二维码/配对码 | 运行 `tunnelbox-cursor --pair` 打印新码 |
106
+ | 需要换手机配对 | 在 App 设置里解绑，再带 `--pair` 运行 |
107
+ | 已绑定但手机连不上 | 确认两端同一中继；查看 `~/.tunnelbox/tunnelbox.log` |
108
+ | 使用自建中继 | 启动时带 `TUNNELBOX_RELAY_URL=wss://<你的中继>` |
109
+
110
+ ## 状态文件
111
+
112
+ - `~/.tunnelbox/remote-state.cursor.json` — agentID / 中继地址 / 绑定状态 / 语言
113
+ - `~/.tunnelbox/cursor-sessions/` — 本地会话镜像
114
+ - `~/.tunnelbox/remote-pairing.cursor.txt` + `remote-pairing.json` — 最新配对信息
115
+ - `~/.tunnelbox/tunnelbox.log` — 适配器日志
116
+
117
+ ## 卸载
118
+
119
+ ```bash
120
+ npm uninstall -g @tunnelbox/cursor
121
+ ```
122
+
123
+ 仅当不再使用任何 tunnelbox 适配器时，才删除 `~/.tunnelbox`（各适配器共享状态）。
124
+
125
+ ## 开发
126
+
127
+ 实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tunnelbox/cursor",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "tunnelbox 的 Cursor 适配器（C 类/B2 头less）：手机远程驱动本机 Cursor CLI（agent -p stream-json，会话/流式/中止/删除）",
5
5
  "type": "module",
6
6
  "main": "./dist/index.mjs",
@@ -9,7 +9,8 @@
9
9
  },
10
10
  "files": [
11
11
  "dist",
12
- "README.md"
12
+ "README.md",
13
+ "README.zh-CN.md"
13
14
  ],
14
15
  "publishConfig": {
15
16
  "access": "public"