@tunnelbox/cursor 0.1.0 → 0.1.3
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.
- package/README.md +86 -79
- package/dist/index.mjs +1147 -24
- package/package.json +10 -1
package/README.md
CHANGED
|
@@ -1,79 +1,86 @@
|
|
|
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 |
|
|
52
|
-
| permission | **false** | `agent -p`
|
|
53
|
-
| commands | true | `/new` `/help` |
|
|
54
|
-
| abort | true | kill 子进程（SIGTERM → SIGKILL） |
|
|
55
|
-
|
|
56
|
-
##
|
|
57
|
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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。
|