quick-acp 0.0.0-stage → 0.1.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 quick-acp contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,406 @@
1
- # Temporary Holding Version
1
+ # quick-acp
2
+
3
+ 一个 **ACP agent**,把 AWS Quick(Quickwork)的 Claude 额度接进任何支持 ACP 的客户端(codeg、T3Code、Zed…),并补上本机 shell 执行能力。
4
+
5
+ ```
6
+ codeg / T3Code ──ACP (JSON-RPC over stdio)──▶ quick-acp ──Quick bidi (WSS)──▶ Quick 网关
7
+ │
8
+ └── 本机执行 shell / 文件工具
9
+ ```
10
+
11
+ **不需要安装 Quick 桌面客户端。** 一次浏览器登录即可。
12
+
13
+ ---
14
+
15
+ ## 它能给你什么
16
+
17
+ 1. **在 codeg 里用 Quick 的 Claude 额度**——Quick 变成 codeg 里的一个 agent,Smart 档位可命中 Opus
18
+ 2. **补上本机 shell 执行**——Quick 自己不给客户端这个能力
19
+ 3. **思考流和图片都保留**——`thinking_delta` → `agent_thought_chunk`,图片附件透传
20
+ 4. **支持多开**——codeg 里开两个对话 = 两条独立 WSS + 两个独立 Quick thread,互不干扰
21
+
22
+ > **免责声明**:本项目通过逆向分析实现与 Quick 服务的互通,仅用于个人学习与自用。使用它可能违反 Quick 的服务条款,风险自负。请勿用于商业分发。
23
+
24
+ ---
25
+
26
+ ## 验证状态(哪些测过,哪些没有)
27
+
28
+ | 项目 | 状态 | 依据 |
29
+ |---|---|---|
30
+ | 编解码 / 工具 / ACP 接线 | ✅ 已测 | `npm run verify`(39 项) |
31
+ | 从 Windows 凭据库读登录态 | ✅ **实测** | 读出 refresh_token/client_id/client_secret |
32
+ | **WSS 连接握手** | ✅ **实测** | 收到 `session_established` |
33
+ | **网关鉴权方式** | ✅ **实测** | query 可行、header 401 |
34
+ | **长连接保活** | ✅ **实测** | 发 ping 后 60s 无 `IDLE_TIMEOUT` |
35
+ | **`user_message` → 真实回复** | ✅ **实测** | `resolved_model_id: us.anthropic.claude-opus-5-5` |
36
+ | **端到端 ACP → Quick → 模型 → ACP** | ✅ **实测** | `npm run e2e` |
37
+ | **自己刷新 token** | ✅ **实测** | `oidc.us-east-1.api.aws` + Basic auth → 200 |
38
+ | **完全不用 outpost** | ✅ **实测** | `npm run e2e:no-outpost` |
39
+ | **无官方客户端的真实登录** | ✅ **实测** | `npm run e2e:fresh`:浏览器登录 → 直连 → 模型回复 |
40
+ | **`inject` 工具循环** | ✅ **实测** | `npm run test:tools`:模型发工具调用 → 本地执行 → 最终答案 |
41
+ | **多轮连续对话** | ✅ **实测** | 连续 3 轮全部正确(曾是真 bug) |
42
+ | **思考转发** | ✅ **实测** | `thinking_delta` → `agent_thought_chunk`(曾完全失效) |
43
+ | **图片附件** | ✅ **实测** | 发一张 crimson PNG,模型答「红色」 |
44
+ | **并发多会话** | ✅ **实测** | 两个 session 同时提问,各自答对,无串话 |
45
+ | 原生 MCP 工具通道 | ⚠️ **需桌面端** | 见「MCP 分支」 |
46
+
47
+ **关键实测:** 全链路已打通,**并且不需要官方桌面客户端**。
48
+
49
+ ```
50
+ *** FRESH MACHINE END-TO-END SUCCESS ***
51
+ *** browser sign-in -> OIDC refresh -> gateway -> model -> text ***
52
+ *** no Quick install, no outpost, no Electron, no keychain entry ***
53
+ ```
54
+
55
+
56
+
57
+ ---
58
+
59
+ ## 安装
60
+
61
+ 需要 Node ≥ 22。
62
+
63
+ ```bash
64
+ npm install
65
+ npm run build
66
+ npm run verify # 38 项检查
67
+ ```
68
+
69
+ ---
70
+
71
+ ## 登录:两条路,都不用手抄 token
72
+
73
+ ### 路线 A:已经装过 Quick 桌面端并登录过
74
+
75
+ **什么都不用做。** 直接跑,quick-acp 自己读:
76
+
77
+ ```
78
+ LegacyGeneric:target=quickwork-social-<profileId> ← 元信息(块数、校验)
79
+ LegacyGeneric:target=quickwork-social-<profileId>_chunk_0 ← 含 refresh_token 的 JSON
80
+ LegacyGeneric:target=quickwork-social-<profileId>_chunk_1
81
+ ```
82
+
83
+ 读完自己刷新 token,然后直连网关。**不需要 outpost,不需要 instance token,不需要 Electron。**
84
+
85
+ ### 路线 B:从没装过官方客户端
86
+
87
+ ```bash
88
+ node dist/login-cli.js --start-url https://ssoins-xxxxx.awsapps.com/start
89
+ ```
90
+
91
+ `--start-url` 是你的 **AWS access portal 地址**。从哪来:
92
+
93
+ 1. 打开 `https://quicksight.aws.amazon.com`(或任意 AWS 控制台)登录
94
+ 2. 浏览器会落到你的 access portal,地址栏形如 `https://ssoins-1a2b3c4d5e6f.awsapps.com/start`
95
+ 3. 把整个地址复制过来
96
+
97
+ 然后浏览器会打开 AWS 登录页,登录完写 `~/.quick-acp/login.json`(0600 权限)。之后直接跑,不用再登录。
98
+
99
+ ### 这条登录链是怎么打通的
100
+
101
+ Quick 自己的客户端就是个**标准 OAuth 授权码 + PKCE 公共客户端**。证据是它存在凭据库里的 `client_secret` —— 那东西其实是个明文 JWT,解开就是:
102
+
103
+ ```json
104
+ {"clientType":"PUBLIC",
105
+ "enabledGrants":{
106
+ "AUTH_CODE":{"redirectUris":["http://127.0.0.1:18080"]},
107
+ "REFRESH_TOKEN":{...}},
108
+ "scopes":[{"fullScope":"quicksight:read_write"}]}
109
+ ```
110
+
111
+ 所以就照标准流程走:
112
+
113
+ | 步骤 | 端点 | 实测结果 |
114
+ |---|---|---|
115
+ | 动态注册客户端 | `POST oidc.us-east-1.api.aws/client/register` | ✅ 200,返回 `clientId` + `clientSecret` |
116
+ | 授权(PKCE S256) | `GET /authorize` | ✅ 302 → AWS 登录页,带 `identitystore_id` |
117
+ | 浏览器回调 | `http://127.0.0.1:18080?code=...` | ✅ 拿到 code |
118
+ | 换 token | `POST /token`(**表单字段**) | ✅ 200,拿到 access + refresh |
119
+ | 刷新 token | `POST /token`(**Basic auth**) | ✅ 200 |
120
+
121
+ **两处必须记牢,弄反就 400:**
122
+
123
+ | 操作 | `client_secret` 放哪 |
124
+ |---|---|
125
+ | `authorization_code` 换 token | **表单字段**(和 `client_id` 一起放 body)|
126
+ | `refresh_token` 刷新 | **HTTP Basic**(`client_id:client_secret` 放 header)|
127
+
128
+ 放反了两边都是 400,而且报错只说 "Invalid request",什么都不告诉你。这个坑我在开发时踩了两次。
129
+
130
+ ### 更正:之前报告里说"自己刷新 token 不行"是错的
131
+
132
+ 那份报告的结论基于这两次失败:
133
+
134
+ | 端点 | 结果 |
135
+ |---|---|
136
+ | `identitycenter.amazonaws.com/<instance>/token` | 403 |
137
+ | `oidc.<region>.amazonaws.com/token`(表单) | 400 |
138
+ | `oidc.<region>.amazonaws.com/token`(JSON) | 401 invalid_client |
139
+ | `<instance>.<region>.portal.amazonaws.com/token` | 404 |
140
+
141
+ **原因是查询的域名全是旧的。** 正确的是 `oidc.<region>.api.aws`。而且 `client_secret` 要放 Basic auth 而不是 body。
142
+
143
+ 换成正确域名 + Basic auth,一次就 200。所以 outpost 不是必需的——它现在只是 B 计划。
144
+
145
+ ### 环境变量
146
+
147
+ | 变量 | 默认 | 说明 |
148
+ |---|---|---|
149
+ | `QUICK_ACP_WORKSPACE` | 当前目录 | 所有工具被禁锢在这个目录里 |
150
+ | `QUICK_ACP_ALLOW_SHELL` | `0` | 开 shell 执行。默认关 |
151
+ | `QUICK_ACP_TOOL_MODE` | 忽略 | 原生 MCP 在 `mcp-native` 分支,这里始终用 prompt 注入 |
152
+ | `QUICK_ACP_FRAMING` | `json-base64` | 帧格式。**默认就是对的**,别乱改:`cbor` 会让服务端静默丢消息 |
153
+ | `QUICK_ACP_START_URL` | unset | 登录用的 portal 地址,等价于 `--start-url` |
154
+ | `QUICK_ACP_TENANT_URL` | 自动发现 | 网关 host。登录后自动从 `profiles.json` / outpost 找回 |
155
+ | `QUICK_ACP_NO_AUTOSTART` | unset | 设为 `1` 则不自动启动 outpost |
156
+ | `QUICK_ACP_AGENT_BIN` | 自动查找 | outpost 可执行文件路径 |
157
+ | `QUICK_ACP_DEBUG` | `0` | 详细日志到 stderr |
158
+
159
+ ### 自检
160
+
161
+ ```bash
162
+ node dist/doctor.js # 看凭据状态
163
+ node dist/no-outpost-e2e.js # 不用 outpost 跑一轮真实对话
164
+ ```
165
+
166
+ ---
167
+
168
+ ## 接入 codeg / T3Code
169
+
170
+ ACP 客户端通过 stdio 启动 agent。注册成这样:
171
+
172
+ ```json
173
+ {
174
+ "quick": {
175
+ "command": "node",
176
+ "args": ["D:/vscode_project/quick_rea/quick_acp/dist/main.js"],
177
+ "env": {
178
+ "QUICK_ACP_WORKSPACE": "D:/your/project",
179
+ "QUICK_ACP_ALLOW_SHELL": "1"
180
+ }
181
+ }
182
+ }
183
+ ```
184
+
185
+ **不需要 `QUICK_ACP_INSTANCE_TOKEN`。** 登录态来自凭据库或 `~/.quick-acp/login.json`,走直连路径。
186
+
187
+ **诊断信息只走 stderr。** stdout 是 JSON-RPC 通道,一行 `console.log` 就会把协议搞坏。
188
+
189
+ ---
190
+
191
+ ## 模式映射(这就是"选模型")
192
+
193
+ Quick 不让人直接选模型,只有档位。ACP 的 mode 直接映射过去:
194
+
195
+ | codeg 里选 | 实际发给 Quick | 效果 |
196
+ |---|---|---|
197
+ | **Fast** | `agent_mode: fast` | 最快,不思考 |
198
+ | **Balanced** | `agent_mode: balanced` | 平衡 |
199
+ | **Smart** | `agent_mode: smart` | 最高质量 + 深度思考,**最容易命中 Opus** |
200
+
201
+ 想用 Opus 就选 **Smart**。具体用哪个模型由 Quick 服务端决定,会在 `token_usage.resolved_model_id` 里回报。
202
+
203
+ `session/set_model` 会被明确拒绝——因为 Quick 不支持,假装成功等于骗你。
204
+
205
+ ---
206
+
207
+ ## 工具
208
+
209
+ ### 为什么不重复造文件工具
210
+
211
+ Quick 自己**已经有**文件读写/搜索/`apply_patch`(`desktop_windows.yaml` 是 `default_available: true`)。**真正缺的是本机 shell。**
212
+
213
+ 所以这里提供的工具:
214
+
215
+ | 工具 | 理由 |
216
+ |---|---|
217
+ | `shell_run` | **真空缺**。Quick 的 `device_shell` 卡在 `code_mode_enabled` + `deviceShell` + `sandbox.available` 三重门上 |
218
+ | `file_read` / `file_write` / `file_list` / `file_search` | 保留:本机执行比绕 Quick 的 agent 循环省一整轮 |
219
+
220
+ ### 安全边界
221
+
222
+ - `shell_run` **默认关闭**,要 `QUICK_ACP_ALLOW_SHELL=1` 才开
223
+ - 开了也会拦:`rm -rf /`、`mkfs`、`dd of=/dev/`、`sudo`、`curl | sh` 等
224
+ - 所有路径被禁锢在 `QUICK_ACP_WORKSPACE` 内,`../` 或绝对路径越界一律拒绝
225
+ - 输出有大小上限,写入有大小上限,命令有超时
226
+
227
+ ### 工作方式
228
+
229
+ 把工具定义写进 prompt,让模型输出带标记的代码块,本地执行后把结果当下一轮用户消息喂回去:
230
+
231
+ ```quick-tool-call
232
+ {"name": "shell_run", "arguments": {"command": "dir"}}
233
+ ```
234
+
235
+ - ✅ **不需要 outpost、不需要 instance token、不需要桌面端**
236
+ - ✅ 全新机器登录完就能用
237
+ - ❌ 每次工具调用多一整轮对话
238
+ - ❌ 靠模型遵守格式,不是协议保证
239
+
240
+ 实测(`npm run test:tools`):模型会规范输出这个块,工具本地执行,然后给出最终答案。
241
+
242
+ ### 关于原生 MCP
243
+
244
+ 理论上可以让模型**原生调用**工具(零额外轮次、不依赖模型写 JSON)。这条路实现在 **`mcp-native` 分支**,没有合并进来,原因很实在:启用本地 MCP server 要过两道门,**都在 Quick 桌面端**。
245
+
246
+ 参考:想自己研究的话,`mcp-native` 分支里有完整的逆向记录和待解决的三个环节。
247
+
248
+ ---
249
+
250
+ ## 已知局限
251
+
252
+ 这些是架构决定的,不是 bug:
253
+
254
+ 1. **不能重放历史。** Quick 服务端按 thread 存上下文,客户端只发增量。所以 `loadSession: false`,新会话就是新 thread。
255
+ 2. **不能指定模型。** 只能选档位。`session/set_model` 明确拒绝。
256
+ 3. **额度按 `agent_hours` 计。** 不是按 token。长时间输出会快速消耗月度额度。
257
+ 4. **同一会话内串行。** Quick thread 是一问一答的流。但**多个会话可以并行**——每个 ACP session 一条独立 WSS。
258
+ 5. **音频不支持。** 图片和文本可以。`promptCapabilities.audio: false`。
259
+
260
+ ---
261
+
262
+ ## 目录结构
263
+
264
+ ```
265
+ src/
266
+ quick/
267
+ codec.ts CBOR + event-stream + Quick 帧(两种模式)
268
+ auth.ts 会话获取(直连 → outpost → 明确报错)
269
+ credstore.ts Windows 凭据库读取(分块重组)
270
+ login.ts 真实登录:动态注册 + PKCE + 换 token + 刷新
271
+ session-direct.ts 不用 outpost,从登录态直接拼会话
272
+ transport.ts WSS 拨号、握手、看门狗、token 刷新
273
+ session.ts thread 模型、增量流、附件
274
+ gateway-contract.ts 实测出来的网关常量(有测试断言)
275
+ tools/
276
+ registry.ts 工具定义、工作区禁锢、执行
277
+ strategies.ts prompt 注入式工具循环
278
+ acp/agent.ts ACP Agent 实现
279
+ main.ts ACP 入口
280
+ login-cli.ts 登录命令行
281
+ probe.ts 编解码 / 工具 / 工具契约检查
282
+ acp-smoke.ts 5 项 ACP 接线检查
283
+ e2e.ts 端到端(ACP → Quick → 模型 → ACP)
284
+ no-outpost-e2e.ts 端到端(不走 outpost)
285
+ fresh-machine-e2e.ts 端到端(模拟全新机器,纯浏览器登录)
286
+ inject-turn-test.ts 多轮对话 + 工具循环回归(这两个都曾是真 bug)
287
+ concurrent-test.ts 两个会话并发,检查不串话
288
+ ```
289
+
290
+ ---
291
+
292
+ ## 已知未完成
293
+
294
+ **原生 MCP 工具通道需要 Quick 桌面端。** 不开桌面端也能用(走 `inject`),只是每次工具调用多一轮。
295
+
296
+ 这不是"技术不可能",而是**当前桥接没有实现独立的权限初始化与确认链**。要让 MCP 完全不依赖桌面端,需要补三样东西:
297
+
298
+ 1. 自己触发组织策略解析(`admin controls`),让 `permissions_pending` 解除
299
+ 2. 自己实现命令确认的用户交互(替代 Electron 的原生对话框)
300
+ 3. 走通工具发布到云端的环节
301
+
302
+ 前两步是工程问题,第三步还没找到接口。所以现状是:**MCP 保留为可选增强,`inject` 作为默认。**
303
+
304
+ 顺带记一个容易误判的点:`permissions_pending` 和 `Invalid or missing confirmation nonce` 是**两道独立的门**,通常先撞前者。桌面端日志证明前者确实会自己解除:
305
+
306
+ ```
307
+ 18:37:29 [OutpostServer] admin controls unresolved after 30.0s; MCP mutations remain pending
308
+ 18:37:47 [OutpostBoot] local_mcp_connect gate=resolved gate_wait_ms=0
309
+
310
+
311
+ ---
312
+
313
+ ## 实测出的协议真相(和代码里写的不一样)
314
+
315
+ 逆向读到的和网关实际接受的**有三处不一致**,不实测根本发现不了:
316
+
317
+ ### 1. 鉴权必须在 query,不能在 header
318
+
319
+ | 方式 | 结果 |
320
+ |---|---|
321
+ | `Authorization: Bearer <jwt>` | **401** |
322
+ | `?token=<jwt>` | **OPEN** |
323
+
324
+ 渲染层 `IZe()` 确实往 header 里塞 Bearer,但那是走主进程 IPC 代理的路径。用裸 `ws` 客户端发同样的 header 会被拒。
325
+
326
+ **这是最容易踩的坑:拿着有效 token 却一直 401。**
327
+
328
+ ### 2. `surfaceType` 是必填 query 参数
329
+
330
+ 没有它,即使 token 正确也是 401。加上 `?surfaceType=QUICK_WORK_DESKTOP_WINDOWS` 才通过。
331
+
332
+ ### 3. 路径是 `/streaming/...` 不是 `/ws/service/...`
333
+
334
+ | 路径 | 结果 |
335
+ |---|---|
336
+ | `/streaming/quickwork-chat-bidirectional-stream` | 401(路径对,鉴权错)→ 修好鉴权后 OPEN |
337
+ | `/ws/service/SpaceNeedleConversationService/operation/...` | **404** |
338
+
339
+ ### 4. 服务端 95 秒无帧就断
340
+
341
+ ```
342
+ {"type":"error","code":"IDLE_TIMEOUT","message":"Client sent no frames for >95 seconds"}
343
+ ```
344
+
345
+ 必须定时发 `ping`。代码里用 45 秒。
346
+
347
+ ### 5. `connected` 帧不是对话前置条件
348
+
349
+ 它属于 WebRTC 语音路径(`LiveConversationWebRtcClient*`),聊天不等它。没有它不代表有问题。
350
+
351
+ ### 6. **不能用 `turn_usage` 判断一轮结束**(这条坑最隐蔽)
352
+
353
+ `turn_usage` 比真正的结束早到几百毫秒。如果拿它当结束信号、立刻发下一条消息,服务端还在收尾,会把新消息当成上一轮的回显吞掉:
354
+
355
+ ```json
356
+ {"type":"message_complete","payload":{"text":"","initiator":"user"}}
357
+ ```
358
+
359
+ 实测对照(同一条 socket):
360
+
361
+ | 场景 | 结果 |
362
+ |---|---|
363
+ | 连续发两轮 | 第 2 轮空 |
364
+ | 连续发三轮 | 第 2 轮空,**第 3 轮拿到第 2 轮的答案** |
365
+ | 两轮之间等 2.5 秒 | 两轮都正常 |
366
+
367
+ 第 3 轮拿到 T2 这说明消息**只是排队,没有丢**。正确做法是等 `message_complete` 才关流,`turn_usage` 只用来报告用量。
368
+
369
+ 这个 bug 影响每一次多轮对话,不只是工具调用,但单轮 e2e 测试完全测不出来。
370
+
371
+ ### 7. 服务端工具事件叫 `tool_result`,不是 `tool_end`
372
+
373
+ `tool_end` 在这个协议里根本不存在——那是第一版猜的名字,会静默匹配不到任何东西。真实名字见渲染层 `case 'tool_result'`。
374
+
375
+ 这些都写进了 `src/quick/gateway-contract.ts`,并有测试断言。
376
+
377
+ ---
378
+
379
+ ## 跑通它
380
+
381
+ **不需要复制任何 token。** 直接:
382
+
383
+ ```bash
384
+ set QUICK_ACP_ALLOW_SHELL=1
385
+ set QUICK_ACP_DEBUG=1
386
+ node dist/main.js
387
+ ```
388
+
389
+ `main.js` 会自动完成:读凭据 → 刷新 token → 直连网关 → 接 ACP。
390
+
391
+ 看 stderr:
392
+
393
+ - `[quick-acp:ws] connecting to …` 然后 `open` → 网关通了
394
+ - `[quick-acp] MCP server registered and enabled (id …)` → 原生工具通道通了
395
+ - `[quick-acp] falling back to prompt-injected tools …` → 没桌面端,工具走 inject
396
+ - `[quick-acp] outpost not available: …` → 明确告诉你缺什么
397
+
398
+ ### 只想看它到底能不能跑
399
+
400
+ ```bash
401
+ node dist/e2e.js # 端到端:ACP prompt → Quick → 模型 → ACP chunk
402
+ node dist/inject-turn-test.js # 多轮对话 + 工具循环回归
403
+ ```
404
+
405
+ 看到 `*** END-TO-END SUCCESS ***` 和 `all multi-turn checks passed` 就是全链路通了。
2
406
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.