@trans-ai/trans-code 0.2.4 → 0.3.0
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 +58 -17
- package/package.json +1 -1
- package/src/acp/session.ts +4 -1
- package/src/agent/loop.test.ts +245 -0
- package/src/agent/loop.ts +92 -2
- package/src/agent/system-prompt.test.ts +24 -1
- package/src/agent/system-prompt.ts +21 -0
- package/src/agent/tools/ask-model.test.ts +54 -0
- package/src/agent/tools/ask-model.ts +44 -0
- package/src/agent/tools/dispatch.test.ts +115 -0
- package/src/agent/tools/dispatch.ts +141 -0
- package/src/agent/tools/files.test.ts +96 -0
- package/src/agent/tools/files.ts +111 -29
- package/src/agent/tools/fs-utils.ts +40 -0
- package/src/agent/tools/index.ts +27 -2
- package/src/agent/tools/search.test.ts +55 -1
- package/src/agent/tools/search.ts +56 -8
- package/src/agent/tools/session.ts +9 -0
- package/src/agent/tools/todo.test.ts +54 -0
- package/src/agent/tools/todo.ts +47 -0
- package/src/agent/tools/types.ts +13 -1
- package/src/commands.ts +37 -2
- package/src/config.ts +21 -3
- package/src/main.tsx +4 -4
- package/src/provider/provider.test.ts +117 -0
- package/src/provider/provider.ts +278 -34
- package/src/provider/routing.test.ts +109 -0
- package/src/screens/REPL.tsx +199 -31
- package/src/version.ts +1 -1
package/README.md
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
多模型 AI 编码 Agent CLI。当前 MVP 的目标是:**作为本地 Agent 被 transonce、multica 等客户端通过 ACP 调用**。
|
|
4
4
|
|
|
5
|
-
- 终端侧:Ink REPL
|
|
5
|
+
- 终端侧:Ink REPL(命令:`help` / `models` / `mode` / `route` / `init` / `clear` / `exit`)
|
|
6
6
|
- Agent 侧:`transcode acp` 启动 ACP v1 stdio 服务,供 transonce、multica 等客户端调用
|
|
7
|
-
-
|
|
8
|
-
- 工具侧:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `bash`
|
|
7
|
+
- 模型侧:档案(Profile)+ 角色(Role)路由——一个模型 ID 对应一个地址,不同任务可派发不同模型(含子 Agent)
|
|
8
|
+
- 工具侧:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `bash` / `todo_write` / `ask_model` / `dispatch_agent`
|
|
9
9
|
|
|
10
10
|
## 环境要求
|
|
11
11
|
|
|
@@ -26,10 +26,12 @@ bun link
|
|
|
26
26
|
|
|
27
27
|
## 配置模型
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
三种方式,从简到繁:
|
|
30
|
+
|
|
31
|
+
**1. 环境变量**(注册表 id 或 `provider:model`):
|
|
30
32
|
|
|
31
33
|
```bash
|
|
32
|
-
# 注册表 id: opus | gpt | deepseek | glm | minimax | kimi
|
|
34
|
+
# 注册表 id: opus | gpt | deepseek | glm | glmc | minimax | kimi | custom
|
|
33
35
|
export ANTHROPIC_API_KEY=...
|
|
34
36
|
export DEEPSEEK_API_KEY=...
|
|
35
37
|
export TRANSCODE_MODEL=deepseek
|
|
@@ -39,6 +41,27 @@ export OPENAI_API_KEY=...
|
|
|
39
41
|
export TRANSCODE_MODEL=openai:gpt-4o
|
|
40
42
|
```
|
|
41
43
|
|
|
44
|
+
**2. REPL 交互配置**(`/models`):三级流程——选厂商 → 选模型(常用列表 + 自定义模型名)→ 输入 key(已存的可回车沿用)。key 确认后**自动测试连通性**,失败显示 API 原始报错并可重输。`custom` 支持任意 OpenAI 兼容网关(输入 base URL + 模型名)。
|
|
45
|
+
|
|
46
|
+
**3. 档案 + 角色路由**(`~/.transcode.json`,任务级模型分派):
|
|
47
|
+
|
|
48
|
+
```jsonc
|
|
49
|
+
{
|
|
50
|
+
"apiKeys": { "glm": "…", "deepseek": "…" },
|
|
51
|
+
"profiles": {
|
|
52
|
+
"glm-coding": { "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", "model": "glm-4.6", "keyId": "glm" },
|
|
53
|
+
"glm-vision": { "baseUrl": "https://open.bigmodel.cn/api/paas/v4", "model": "glm-4.6v", "keyId": "glm" }
|
|
54
|
+
},
|
|
55
|
+
"routing": { "default": "glm-coding", "analysis": "glm-coding", "vision": "glm-vision" }
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
- **Profile**:命名档案 = 地址 + 模型名 + keyId(智谱普通端点 / CodePlan 端点各一个档案,共用一把 key;同名覆盖内置注册表)
|
|
60
|
+
- **Role**:任意命名的角色 → 档案,`/route analysis glmc` 设置、`/route` 查看、`/route design -` 删除
|
|
61
|
+
- ACP `session/set_model` 直接收档案名,宿主可按任务指派不同模型
|
|
62
|
+
|
|
63
|
+
> **GLM Coding Plan 用户**:套餐只在 Coding 专用端点生效,请用 `glmc` 档案(`https://open.bigmodel.cn/api/coding/paas/v4`);普通 `glm` 端点会报"429 余额不足"。
|
|
64
|
+
|
|
42
65
|
### 复用 Claude Code 的 Anthropic 兼容配置
|
|
43
66
|
|
|
44
67
|
如果你已经有一个 Anthropic 兼容网关(例如 DeepSeek 的 `/anthropic` 端点),可以直接沿用 Claude Code 的环境变量,不需要改 `TRANSCODE_MODEL`:
|
|
@@ -70,15 +93,18 @@ bun run test:acp:real # 完整 ACP + 工具调用(会创建临时 works
|
|
|
70
93
|
|
|
71
94
|
| 变量 | 说明 |
|
|
72
95
|
| --- | --- |
|
|
73
|
-
| `TRANSCODE_MODEL` | 默认模型。注册表 id
|
|
96
|
+
| `TRANSCODE_MODEL` | 默认模型。注册表 id、档案名、`provider:model`,或裸模型名 |
|
|
74
97
|
| `TRANSCODE_DEFAULT_PROVIDER` | 裸模型名走哪个 provider,默认 `openai` |
|
|
75
|
-
| `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly` |
|
|
98
|
+
| `TRANSCODE_PERMISSION_MODE` | `ask`(默认) / `auto` / `readonly`;REPL 里可用 `/mode` 运行时切换 |
|
|
76
99
|
| `TRANSCODE_ALLOW_OUTSIDE_CWD` | 设为 `1` 才允许读写工作区之外的路径 |
|
|
77
100
|
| `TRANSCODE_BASE_URL` | 覆盖当前模型的 base URL(所有 provider) |
|
|
78
101
|
| `TRANSCODE_MAX_TOKENS` | 单次回复的 `max_tokens`,默认 `8192` |
|
|
102
|
+
| `TRANSCODE_MAX_TURNS` | Agent 工具回合上限,默认 `200`;触顶会明确提示并写入对话 |
|
|
103
|
+
| `TRANSCODE_SUBAGENT_MAX_TURNS` | 子 Agent 回合上限,默认 `25` |
|
|
104
|
+
| `TRANSCODE_SKIP_MODEL_CHECK` | 设为 `1` 跳过 /models 的连通性测试 |
|
|
79
105
|
| `TRANSCODE_MOCK` | 设为 `1` 使用本地 mock 模型(仅用于协议测试) |
|
|
80
106
|
|
|
81
|
-
`provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`minimax`、`kimi`、`moonshot`。
|
|
107
|
+
`provider:model` 支持的前缀:`openai`、`anthropic`、`deepseek`、`glm`、`glmc`、`minimax`、`kimi`、`moonshot`。
|
|
82
108
|
裸模型名会使用 `TRANSCODE_DEFAULT_PROVIDER`;`openai` 前缀和裸模型名可以用 `OPENAI_BASE_URL` 指向兼容网关,`TRANSCODE_BASE_URL` 则可以覆盖任意 provider。
|
|
83
109
|
|
|
84
110
|
## 本地运行
|
|
@@ -167,18 +193,33 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
|
|
|
167
193
|
|
|
168
194
|
| 工具 | 说明 | 是否需要授权 |
|
|
169
195
|
| --- | --- | --- |
|
|
170
|
-
| `read_file` |
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `bash` |
|
|
196
|
+
| `read_file` | 文本文件(带行号、offset/limit、超长行截断);PNG/JPG/GIF/WebP 以多模态图片返回 | 否 |
|
|
197
|
+
| `write_file` | 创建/覆盖文件(已存在的文件需先 read 过;返回新文件/变更 diff) | 是 |
|
|
198
|
+
| `edit_file` | 精确替换,支持单次多处编辑(`edits[]` 原子应用);弯/直引号自动归一化 | 是 |
|
|
199
|
+
| `glob` | 按 glob 查文件(git 仓库内遵循 `.gitignore`) | 否 |
|
|
200
|
+
| `grep` | 正则搜索:上下文行(`context`)、跨行匹配(`multiline`)、`.gitignore` 感知 | 否 |
|
|
201
|
+
| `bash` | 用户 shell 执行;**cd 跨调用持久**、登录环境快照、进程组 kill、头尾截断 | 是(只读命令免确认) |
|
|
202
|
+
| `todo_write` | 任务清单(`[x]/[~]/[ ]`),多步任务防漂移 | 否 |
|
|
203
|
+
| `ask_model` | 单次问答式分派:把子问题发给某角色的模型,答案回入对话 | 否 |
|
|
204
|
+
| `dispatch_agent` | 派发子 Agent:独立模型 + 工具白名单 + 自己的回合循环,只回传最终报告 | 是 |
|
|
205
|
+
|
|
206
|
+
**bash 免确认规则**:`ls`/`cat`/`grep`/`git status` 等只读命令(含管道、`2>/dev/null` 等无害重定向)自动放行并在结果行标注 `(read-only)`;写入重定向、命令替换、危险参数(`find -delete`、`sed -i`…)照常逐次确认。连续重复调用(含 A-B-A-B 振荡)会被熔断并引导换路子。
|
|
176
207
|
|
|
177
208
|
所有路径默认限制在任务 workspace(`cwd`)内;`..` 越界会被拒绝,除非显式设置 `TRANSCODE_ALLOW_OUTSIDE_CWD=1`。
|
|
178
209
|
|
|
210
|
+
## 子任务分派
|
|
211
|
+
|
|
212
|
+
主 Agent 可以把工作派给不同角色的模型(角色经 `/route` 配置,见上文档案与路由):
|
|
213
|
+
|
|
214
|
+
- **`ask_model`**:单次专家问答(分析、设计取舍、审查、看图),无工具、一次调用
|
|
215
|
+
- **`dispatch_agent`**:多步研究型子任务 —— 子 Agent 用角色档案的模型 + 工具白名单(默认只读三件套)跑自己的循环。上下文契约是**任务进、报告出**:子 Agent 看不到主对话,任务描述必须自包含;只有最终报告回入主对话。派发本身需用户 y/n 授权,子 Agent 禁止递归派发,回合上限 25
|
|
216
|
+
- **图片自动代理**:配置了 `routing.vision` 时,工具产生的图片自动经视觉模型转文字描述,主模型无需多模态能力
|
|
217
|
+
|
|
218
|
+
主对话有防护栏:探索停滞(30 次零写入)自动催促、无视则强制终止(`stalled`);交付后长尾钻探会被收尾提醒。
|
|
219
|
+
|
|
179
220
|
## 上下文
|
|
180
221
|
|
|
181
|
-
每次 turn
|
|
222
|
+
每次 turn 按优先级加载 workspace 下的 `TRANS.md`、`AGENTS.md`、`CLAUDE.md`、`TRANSCODE.md`、`.transcode/AGENTS.md`(存在时)注入系统提示。REPL 里 `/init` 可让 Agent 自行探索仓库并生成 `TRANS.md`(项目背景 / 命令 / 架构 / 约定)。
|
|
182
223
|
|
|
183
224
|
## ACP 协议
|
|
184
225
|
|
|
@@ -188,8 +229,8 @@ ACP 默认权限模式是 `ask`:写文件、改文件、执行命令前会向
|
|
|
188
229
|
|
|
189
230
|
- 不支持 MCP(会忽略 `mcpServers` 并在 stderr 提示)
|
|
190
231
|
- 不支持 ACP session 持久化:`loadSession: false`,进程内 session 在进程退出后丢失
|
|
191
|
-
-
|
|
192
|
-
- 没有 Web
|
|
232
|
+
- prompt 仍以文本为主;图片只支持 `read_file` 读取(≤3MB,多模态模型直读,其余经 vision 角色转述)
|
|
233
|
+
- 没有 Web 搜索、hooks、自动压缩;子 Agent 为隔离式(fork 继承上下文模式规划中)
|
|
193
234
|
- 工具输出有长度上限,避免单次上下文爆炸
|
|
194
235
|
- `TRANSCODE_MOCK=1` 仅用于协议 smoke test,不会调用真实模型
|
|
195
236
|
|
package/package.json
CHANGED
package/src/acp/session.ts
CHANGED
|
@@ -145,7 +145,10 @@ export class AcpSession {
|
|
|
145
145
|
});
|
|
146
146
|
|
|
147
147
|
this.trimHistory();
|
|
148
|
-
|
|
148
|
+
// 'stalled' has no ACP counterpart; report it as the closest reason.
|
|
149
|
+
const stopReason =
|
|
150
|
+
result.stopReason === 'stalled' ? 'max_turn_requests' : result.stopReason;
|
|
151
|
+
return { stopReason: stopReason as AcpStopReason };
|
|
149
152
|
} catch (error) {
|
|
150
153
|
if (signal.aborted) return { stopReason: 'cancelled' };
|
|
151
154
|
|
package/src/agent/loop.test.ts
CHANGED
|
@@ -119,6 +119,90 @@ describe('runAgentLoop', () => {
|
|
|
119
119
|
.toBe(true);
|
|
120
120
|
});
|
|
121
121
|
|
|
122
|
+
test('tool images flow into the ToolMessage as multimodal blocks', async () => {
|
|
123
|
+
const imageTool: AgentTool = {
|
|
124
|
+
...fakeTool,
|
|
125
|
+
async execute() {
|
|
126
|
+
return {
|
|
127
|
+
output: 'here is the screenshot',
|
|
128
|
+
images: [{ data: 'aW1hZ2U=', mediaType: 'image/png' }],
|
|
129
|
+
};
|
|
130
|
+
},
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
const result = await runAgentLoop({
|
|
134
|
+
model: stubModel(),
|
|
135
|
+
cwd: '/tmp',
|
|
136
|
+
messages: [],
|
|
137
|
+
systemPrompt: 'test',
|
|
138
|
+
tools: [imageTool],
|
|
139
|
+
onEvent: () => {},
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
143
|
+
const content = toolMessage?.content as unknown;
|
|
144
|
+
expect(Array.isArray(content)).toBe(true);
|
|
145
|
+
const blocks = content as Array<{ type: string; image_url?: { url: string } }>;
|
|
146
|
+
expect(blocks.some((block) => block.type === 'text')).toBe(true);
|
|
147
|
+
const image = blocks.find((block) => block.type === 'image_url');
|
|
148
|
+
expect(image?.image_url?.url).toBe('data:image/png;base64,aW1hZ2U=');
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
test('images are auto-described through the vision proxy when provided', async () => {
|
|
152
|
+
const imageTool: AgentTool = {
|
|
153
|
+
...fakeTool,
|
|
154
|
+
async execute() {
|
|
155
|
+
return {
|
|
156
|
+
output: 'screenshot captured',
|
|
157
|
+
images: [{ data: 'aW1n', mediaType: 'image/png' }],
|
|
158
|
+
};
|
|
159
|
+
},
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
const result = await runAgentLoop({
|
|
163
|
+
model: stubModel(),
|
|
164
|
+
cwd: '/tmp',
|
|
165
|
+
messages: [],
|
|
166
|
+
systemPrompt: 'test',
|
|
167
|
+
tools: [imageTool],
|
|
168
|
+
onEvent: () => {},
|
|
169
|
+
describeImages: async () => '截图显示 429 余额不足报错',
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
173
|
+
expect(Array.isArray(toolMessage?.content)).toBe(false);
|
|
174
|
+
expect(String(toolMessage?.content)).toContain('截图显示 429 余额不足报错');
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
test('vision proxy failure falls back to raw image blocks', async () => {
|
|
178
|
+
const imageTool: AgentTool = {
|
|
179
|
+
...fakeTool,
|
|
180
|
+
async execute() {
|
|
181
|
+
return {
|
|
182
|
+
output: 'screenshot captured',
|
|
183
|
+
images: [{ data: 'aW1n', mediaType: 'image/png' }],
|
|
184
|
+
};
|
|
185
|
+
},
|
|
186
|
+
};
|
|
187
|
+
|
|
188
|
+
const result = await runAgentLoop({
|
|
189
|
+
model: stubModel(),
|
|
190
|
+
cwd: '/tmp',
|
|
191
|
+
messages: [],
|
|
192
|
+
systemPrompt: 'test',
|
|
193
|
+
tools: [imageTool],
|
|
194
|
+
onEvent: () => {},
|
|
195
|
+
describeImages: async () => {
|
|
196
|
+
throw new Error('vision model offline');
|
|
197
|
+
},
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
const toolMessage = result.messages.find((message) => message.getType() === 'tool');
|
|
201
|
+
const content = toolMessage?.content as Array<{ type: string }>;
|
|
202
|
+
expect(Array.isArray(content)).toBe(true);
|
|
203
|
+
expect(content[1]?.type).toBe('image_url');
|
|
204
|
+
});
|
|
205
|
+
|
|
122
206
|
test('mutating tools without isReadOnly still request permission', async () => {
|
|
123
207
|
let permissionAsked = 0;
|
|
124
208
|
await runAgentLoop({
|
|
@@ -353,4 +437,165 @@ describe('runAgentLoop', () => {
|
|
|
353
437
|
);
|
|
354
438
|
expect(nudge).toBeUndefined();
|
|
355
439
|
});
|
|
440
|
+
|
|
441
|
+
test('nudges the model to wrap up when exploring long after a real file write', async () => {
|
|
442
|
+
const reader: AgentTool = {
|
|
443
|
+
...fakeTool,
|
|
444
|
+
name: 'reader',
|
|
445
|
+
isMutating: false,
|
|
446
|
+
async execute() {
|
|
447
|
+
return 'ok';
|
|
448
|
+
},
|
|
449
|
+
};
|
|
450
|
+
const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
|
|
451
|
+
|
|
452
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
453
|
+
{ tool: 'write_file', args: '{"n":-1}' },
|
|
454
|
+
...Array.from({ length: 44 }, (_, i) => ({
|
|
455
|
+
tool: 'reader',
|
|
456
|
+
args: JSON.stringify({ n: i }),
|
|
457
|
+
})),
|
|
458
|
+
];
|
|
459
|
+
|
|
460
|
+
const result = await runAgentLoop({
|
|
461
|
+
model: scriptedModel(steps),
|
|
462
|
+
cwd: '/tmp',
|
|
463
|
+
messages: [],
|
|
464
|
+
systemPrompt: 'test',
|
|
465
|
+
tools: [reader, writeFile],
|
|
466
|
+
onEvent: () => {},
|
|
467
|
+
});
|
|
468
|
+
|
|
469
|
+
const nudges = result.messages.filter(
|
|
470
|
+
(message) =>
|
|
471
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
472
|
+
);
|
|
473
|
+
expect(nudges.length).toBe(1);
|
|
474
|
+
});
|
|
475
|
+
|
|
476
|
+
test('mutating bash does not count as a delivered file — no wrap-up nudge', async () => {
|
|
477
|
+
const result = await runAgentLoop({
|
|
478
|
+
model: scriptedModel(
|
|
479
|
+
Array.from({ length: 45 }, (_, i) => ({
|
|
480
|
+
tool: 'fake' as const,
|
|
481
|
+
args: JSON.stringify({ n: i }),
|
|
482
|
+
})),
|
|
483
|
+
),
|
|
484
|
+
cwd: '/tmp',
|
|
485
|
+
messages: [],
|
|
486
|
+
systemPrompt: 'test',
|
|
487
|
+
tools: [fakeTool], // mutating, but not a file write
|
|
488
|
+
onEvent: () => {},
|
|
489
|
+
});
|
|
490
|
+
|
|
491
|
+
const wrapUp = result.messages.find(
|
|
492
|
+
(message) =>
|
|
493
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
494
|
+
);
|
|
495
|
+
expect(wrapUp).toBeUndefined();
|
|
496
|
+
});
|
|
497
|
+
|
|
498
|
+
test('force-stops when the model keeps exploring after an ignored stall nudge', async () => {
|
|
499
|
+
const reader: AgentTool = {
|
|
500
|
+
...fakeTool,
|
|
501
|
+
isMutating: false,
|
|
502
|
+
async execute() {
|
|
503
|
+
return 'ok';
|
|
504
|
+
},
|
|
505
|
+
};
|
|
506
|
+
|
|
507
|
+
const result = await runAgentLoop({
|
|
508
|
+
model: scriptedModel(
|
|
509
|
+
Array.from({ length: 60 }, (_, i) => ({
|
|
510
|
+
tool: 'fake' as const,
|
|
511
|
+
args: JSON.stringify({ n: i }),
|
|
512
|
+
})),
|
|
513
|
+
),
|
|
514
|
+
cwd: '/tmp',
|
|
515
|
+
messages: [],
|
|
516
|
+
systemPrompt: 'test',
|
|
517
|
+
tools: [reader],
|
|
518
|
+
onEvent: () => {},
|
|
519
|
+
});
|
|
520
|
+
|
|
521
|
+
// Stall nudge at 30 calls, grace of 15 more, then a hard stop.
|
|
522
|
+
expect(result.stopReason).toBe('stalled');
|
|
523
|
+
const notice = result.messages.find(
|
|
524
|
+
(message) =>
|
|
525
|
+
message.getType() === 'ai' && message.content.toString().includes('ignored the earlier reminder'),
|
|
526
|
+
);
|
|
527
|
+
expect(notice).toBeDefined();
|
|
528
|
+
});
|
|
529
|
+
|
|
530
|
+
test('starting the deliverable during the grace window cancels the hard stop', async () => {
|
|
531
|
+
const reader: AgentTool = {
|
|
532
|
+
...fakeTool,
|
|
533
|
+
isMutating: false,
|
|
534
|
+
async execute() {
|
|
535
|
+
return 'ok';
|
|
536
|
+
},
|
|
537
|
+
};
|
|
538
|
+
const writeFile: AgentTool = { ...fakeTool, name: 'write_file' };
|
|
539
|
+
|
|
540
|
+
// 32 reads (past the nudge), then write, then a few more reads.
|
|
541
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
542
|
+
...Array.from({ length: 32 }, (_, i) => ({
|
|
543
|
+
tool: 'fake',
|
|
544
|
+
args: JSON.stringify({ n: i }),
|
|
545
|
+
})),
|
|
546
|
+
{ tool: 'write_file', args: '{"content":"x"}' },
|
|
547
|
+
...Array.from({ length: 10 }, (_, i) => ({
|
|
548
|
+
tool: 'fake',
|
|
549
|
+
args: JSON.stringify({ m: i }),
|
|
550
|
+
})),
|
|
551
|
+
];
|
|
552
|
+
|
|
553
|
+
const result = await runAgentLoop({
|
|
554
|
+
model: scriptedModel(steps),
|
|
555
|
+
cwd: '/tmp',
|
|
556
|
+
messages: [],
|
|
557
|
+
systemPrompt: 'test',
|
|
558
|
+
tools: [reader, writeFile],
|
|
559
|
+
onEvent: () => {},
|
|
560
|
+
});
|
|
561
|
+
|
|
562
|
+
expect(result.stopReason).not.toBe('stalled');
|
|
563
|
+
});
|
|
564
|
+
|
|
565
|
+
test('a single mutating bash followed by reads does not trigger the wrap-up nudge', async () => {
|
|
566
|
+
const reader: AgentTool = {
|
|
567
|
+
...fakeTool,
|
|
568
|
+
name: 'reader',
|
|
569
|
+
isMutating: false,
|
|
570
|
+
async execute() {
|
|
571
|
+
return 'ok';
|
|
572
|
+
},
|
|
573
|
+
};
|
|
574
|
+
const bashLike: AgentTool = { ...fakeTool, name: 'bash' }; // mutating, not a file write
|
|
575
|
+
|
|
576
|
+
const steps: Array<{ tool: string; args: string }> = [
|
|
577
|
+
{ tool: 'bash', args: '{"n":-1}' },
|
|
578
|
+
...Array.from({ length: 44 }, (_, i) => ({
|
|
579
|
+
tool: 'reader',
|
|
580
|
+
args: JSON.stringify({ n: i }),
|
|
581
|
+
})),
|
|
582
|
+
];
|
|
583
|
+
|
|
584
|
+
const result = await runAgentLoop({
|
|
585
|
+
model: scriptedModel(steps),
|
|
586
|
+
cwd: '/tmp',
|
|
587
|
+
messages: [],
|
|
588
|
+
systemPrompt: 'test',
|
|
589
|
+
tools: [reader, bashLike],
|
|
590
|
+
onEvent: () => {},
|
|
591
|
+
});
|
|
592
|
+
|
|
593
|
+
const wrapUp = result.messages.find(
|
|
594
|
+
(message) =>
|
|
595
|
+
message.getType() === 'ai' && message.content.toString().includes('reply with a summary'),
|
|
596
|
+
);
|
|
597
|
+
// Regression: a misjudged "mutating" bash used to falsely announce
|
|
598
|
+
// "the deliverable has already been written" and abort honest work.
|
|
599
|
+
expect(wrapUp).toBeUndefined();
|
|
600
|
+
});
|
|
356
601
|
});
|
package/src/agent/loop.ts
CHANGED
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
type ToolKind,
|
|
18
18
|
type ToolSession,
|
|
19
19
|
} from './tools/index.js';
|
|
20
|
+
import { askRole, getRouting } from '../provider/provider.js';
|
|
20
21
|
|
|
21
22
|
export type AgentEvent =
|
|
22
23
|
| { type: 'text'; text: string }
|
|
@@ -56,6 +57,7 @@ export type StopReason =
|
|
|
56
57
|
| 'end_turn'
|
|
57
58
|
| 'cancelled'
|
|
58
59
|
| 'max_turn_requests'
|
|
60
|
+
| 'stalled'
|
|
59
61
|
| 'refusal';
|
|
60
62
|
|
|
61
63
|
export interface AgentLoopOptions {
|
|
@@ -70,6 +72,8 @@ export interface AgentLoopOptions {
|
|
|
70
72
|
requestPermission?: RequestPermission;
|
|
71
73
|
/** Session state shared across tool calls (shell cwd, read files). Created when absent. */
|
|
72
74
|
toolSession?: ToolSession;
|
|
75
|
+
/** Vision proxy override (tests). Default: routing.vision → askRole('vision'). */
|
|
76
|
+
describeImages?: (images: Array<{ data: string; mediaType: string }>) => Promise<string>;
|
|
73
77
|
}
|
|
74
78
|
|
|
75
79
|
export interface AgentLoopResult {
|
|
@@ -205,6 +209,7 @@ async function runMockTurn(
|
|
|
205
209
|
cwd: toolSession.cwd,
|
|
206
210
|
signal: options.signal,
|
|
207
211
|
session: toolSession,
|
|
212
|
+
requestPermission: options.requestPermission,
|
|
208
213
|
})
|
|
209
214
|
: { ok: false, output: 'Permission denied.' };
|
|
210
215
|
|
|
@@ -277,9 +282,18 @@ export async function runAgentLoop(
|
|
|
277
282
|
// the model is drilling instead of delivering (observed with DeepSeek:
|
|
278
283
|
// 272 read-only calls to "update a README"). Nudge it once mid-run.
|
|
279
284
|
const EXPLORE_STALL_THRESHOLD = 30;
|
|
285
|
+
// Hard rail: when the stall nudge is ignored, stop burning turns.
|
|
286
|
+
const STALL_GRACE_CALLS = 15;
|
|
287
|
+
// Wrap-up detection: the deliverable was already written, but the model
|
|
288
|
+
// keeps exploring instead of summarizing and ending its turn.
|
|
289
|
+
const WRAP_UP_GAP = 20;
|
|
280
290
|
let totalToolCalls = 0;
|
|
291
|
+
let callsSinceAction = 0;
|
|
281
292
|
let hasActed = false;
|
|
293
|
+
let hasDelivered = false; // a real file write happened (write_file/edit_file)
|
|
282
294
|
let stallNudged = false;
|
|
295
|
+
let callsAtStallNudge = 0;
|
|
296
|
+
let wrapUpNudged = false;
|
|
283
297
|
|
|
284
298
|
for (let turn = 0; turn < maxTurns; turn++) {
|
|
285
299
|
if (options.signal?.aborted) return { stopReason: 'cancelled', messages };
|
|
@@ -333,7 +347,7 @@ export async function runAgentLoop(
|
|
|
333
347
|
input,
|
|
334
348
|
});
|
|
335
349
|
|
|
336
|
-
let result: { ok: boolean; output: string; diff?: string };
|
|
350
|
+
let result: { ok: boolean; output: string; diff?: string; images?: Array<{ data: string; mediaType: string }> };
|
|
337
351
|
let skippedPermission = false;
|
|
338
352
|
|
|
339
353
|
// Circuit breaker (windowed): see recentKeys declaration.
|
|
@@ -366,14 +380,22 @@ export async function runAgentLoop(
|
|
|
366
380
|
cwd: toolSession.cwd,
|
|
367
381
|
signal: options.signal,
|
|
368
382
|
session: toolSession,
|
|
383
|
+
requestPermission: options.requestPermission,
|
|
369
384
|
})
|
|
370
385
|
: { ok: false, output: 'Permission denied by the client.' };
|
|
371
386
|
|
|
372
387
|
if (allowed && tool.isMutating && tool.isReadOnly?.(input) !== true) {
|
|
373
388
|
hasActed = true;
|
|
389
|
+
callsSinceAction = 0;
|
|
390
|
+
// "Delivered" means a file write; mutating bash is not a deliverable
|
|
391
|
+
// and must not trigger the wrap-up message.
|
|
392
|
+
if (tool.name === 'write_file' || tool.name === 'edit_file') {
|
|
393
|
+
hasDelivered = true;
|
|
394
|
+
}
|
|
374
395
|
}
|
|
375
396
|
}
|
|
376
397
|
totalToolCalls++;
|
|
398
|
+
callsSinceAction++;
|
|
377
399
|
|
|
378
400
|
await options.onEvent({
|
|
379
401
|
type: 'tool_result',
|
|
@@ -385,9 +407,50 @@ export async function runAgentLoop(
|
|
|
385
407
|
skippedPermission,
|
|
386
408
|
});
|
|
387
409
|
|
|
410
|
+
// Image auto-proxy: when a vision role is routed (or a test describer
|
|
411
|
+
// is injected), images are converted to a text description so the
|
|
412
|
+
// primary model does not need multimodal support.
|
|
413
|
+
let toolContent:
|
|
414
|
+
| string
|
|
415
|
+
| Array<{ type: string; text?: string; image_url?: { url: string } }> = result.output;
|
|
416
|
+
if (result.images?.length) {
|
|
417
|
+
const describer =
|
|
418
|
+
options.describeImages ??
|
|
419
|
+
(getRouting().vision
|
|
420
|
+
? (images: Array<{ data: string; mediaType: string }>) =>
|
|
421
|
+
askRole(
|
|
422
|
+
'vision',
|
|
423
|
+
'简要描述图片的关键信息;如果是报错/截图,逐字给出其中文本。',
|
|
424
|
+
images,
|
|
425
|
+
)
|
|
426
|
+
: undefined);
|
|
427
|
+
if (describer) {
|
|
428
|
+
try {
|
|
429
|
+
const description = await describer(result.images);
|
|
430
|
+
toolContent = `${result.output}\n\n[vision] ${description}`;
|
|
431
|
+
} catch {
|
|
432
|
+
toolContent = [
|
|
433
|
+
{ type: 'text', text: `${result.output}\n[vision 转述失败,原图已直接传入]` },
|
|
434
|
+
...result.images.map((image) => ({
|
|
435
|
+
type: 'image_url',
|
|
436
|
+
image_url: { url: `data:${image.mediaType};base64,${image.data}` },
|
|
437
|
+
})),
|
|
438
|
+
];
|
|
439
|
+
}
|
|
440
|
+
} else {
|
|
441
|
+
toolContent = [
|
|
442
|
+
{ type: 'text', text: result.output },
|
|
443
|
+
...result.images.map((image) => ({
|
|
444
|
+
type: 'image_url',
|
|
445
|
+
image_url: { url: `data:${image.mediaType};base64,${image.data}` },
|
|
446
|
+
})),
|
|
447
|
+
];
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
|
|
388
451
|
messages.push(
|
|
389
452
|
new ToolMessage({
|
|
390
|
-
content:
|
|
453
|
+
content: toolContent,
|
|
391
454
|
tool_call_id: toolCallId,
|
|
392
455
|
name: call.name,
|
|
393
456
|
}),
|
|
@@ -396,6 +459,7 @@ export async function runAgentLoop(
|
|
|
396
459
|
|
|
397
460
|
if (!hasActed && !stallNudged && totalToolCalls >= EXPLORE_STALL_THRESHOLD) {
|
|
398
461
|
stallNudged = true;
|
|
462
|
+
callsAtStallNudge = totalToolCalls;
|
|
399
463
|
const nudge =
|
|
400
464
|
`You have made ${totalToolCalls} tool calls without producing any edits or output. ` +
|
|
401
465
|
'Stop exploring: synthesize what you already have and complete the task now ' +
|
|
@@ -403,6 +467,32 @@ export async function runAgentLoop(
|
|
|
403
467
|
'read_file returns up to 2000 lines in one call — do not paginate with grep/sed windows.';
|
|
404
468
|
messages.push(new AIMessage({ content: nudge }));
|
|
405
469
|
await options.onEvent({ type: 'text', text: `\n⚠ ${nudge}\n` });
|
|
470
|
+
} else if (
|
|
471
|
+
!hasActed &&
|
|
472
|
+
stallNudged &&
|
|
473
|
+
totalToolCalls - callsAtStallNudge >= STALL_GRACE_CALLS
|
|
474
|
+
) {
|
|
475
|
+
// Hard rail: the nudge was ignored. Fail fast and loudly instead of
|
|
476
|
+
// burning the remaining turns.
|
|
477
|
+
const notice =
|
|
478
|
+
`The agent made ${totalToolCalls} tool calls without starting the deliverable and ` +
|
|
479
|
+
'ignored the earlier reminder. Stopping to avoid wasting turns. Re-prompt with a more ' +
|
|
480
|
+
'specific instruction (name the exact file and what to change) or switch to a stronger model.';
|
|
481
|
+
messages.push(new AIMessage({ content: notice }));
|
|
482
|
+
await options.onEvent({ type: 'text', text: `\n⚠ ${notice}\n` });
|
|
483
|
+
return { stopReason: 'stalled', messages };
|
|
484
|
+
} else if (
|
|
485
|
+
hasDelivered &&
|
|
486
|
+
!wrapUpNudged &&
|
|
487
|
+
callsSinceAction >= WRAP_UP_GAP
|
|
488
|
+
) {
|
|
489
|
+
wrapUpNudged = true;
|
|
490
|
+
const nudge =
|
|
491
|
+
`The deliverable has already been written, but you have made ${callsSinceAction} ` +
|
|
492
|
+
'more tool calls since. Run any final verification now if truly needed, then ' +
|
|
493
|
+
'reply with a summary of what changed and stop — further exploration is not needed.';
|
|
494
|
+
messages.push(new AIMessage({ content: nudge }));
|
|
495
|
+
await options.onEvent({ type: 'text', text: `\n⚠ ${nudge}\n` });
|
|
406
496
|
}
|
|
407
497
|
}
|
|
408
498
|
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { afterEach, describe, expect, test } from 'bun:test';
|
|
2
|
-
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { mkdtempSync, promises as fs, rmSync, writeFileSync } from 'node:fs';
|
|
3
3
|
import { tmpdir } from 'node:os';
|
|
4
4
|
import path from 'node:path';
|
|
5
5
|
import { INIT_PROMPT, buildSystemPrompt, loadProjectContext } from './system-prompt.js';
|
|
6
|
+
import { setRouting } from '../provider/provider.js';
|
|
6
7
|
|
|
7
8
|
describe('buildSystemPrompt', () => {
|
|
8
9
|
test('steers file inspection away from whole-file cat/sed dumps', () => {
|
|
@@ -14,6 +15,28 @@ describe('buildSystemPrompt', () => {
|
|
|
14
15
|
expect(prompt).toContain('offset');
|
|
15
16
|
expect(prompt.toLowerCase()).toContain('do not cat');
|
|
16
17
|
});
|
|
18
|
+
|
|
19
|
+
test('warns that grep -c counts definition lines too', () => {
|
|
20
|
+
const prompt = buildSystemPrompt({ cwd: '/tmp', projectFiles: [] });
|
|
21
|
+
expect(prompt).toContain('grep -c');
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
test('advertises configured role routing for ask_model delegation', async () => {
|
|
25
|
+
const configDir = await fs.mkdtemp(path.join(tmpdir(), 'transcode-prompt-route-'));
|
|
26
|
+
process.env.TRANSCODE_CONFIG_PATH = path.join(configDir, 'config.json');
|
|
27
|
+
try {
|
|
28
|
+
setRouting('analysis', 'glmc');
|
|
29
|
+
setRouting('design', 'opus');
|
|
30
|
+
const prompt = buildSystemPrompt({ cwd: '/tmp', projectFiles: [] });
|
|
31
|
+
expect(prompt).toContain('ask_model');
|
|
32
|
+
expect(prompt).toContain('dispatch_agent');
|
|
33
|
+
expect(prompt).toContain('analysis→glmc');
|
|
34
|
+
expect(prompt).toContain('design→opus');
|
|
35
|
+
} finally {
|
|
36
|
+
delete process.env.TRANSCODE_CONFIG_PATH;
|
|
37
|
+
await fs.rm(configDir, { recursive: true, force: true });
|
|
38
|
+
}
|
|
39
|
+
});
|
|
17
40
|
});
|
|
18
41
|
|
|
19
42
|
const cleanups: Array<() => void> = [];
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { promises as fs } from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
|
+
import { getRouting } from '../provider/provider.js';
|
|
3
4
|
|
|
4
5
|
const CONTEXT_FILES = ['TRANS.md', 'AGENTS.md', 'CLAUDE.md', 'TRANSCODE.md', '.transcode/AGENTS.md'];
|
|
5
6
|
const MAX_CONTEXT_CHARS = 40_000;
|
|
@@ -32,6 +33,21 @@ async function readOptional(file: string): Promise<string | null> {
|
|
|
32
33
|
}
|
|
33
34
|
}
|
|
34
35
|
|
|
36
|
+
/** Advertises configured role routing so the model knows it can delegate. */
|
|
37
|
+
function roleRoutingLines(): string[] {
|
|
38
|
+
const entries = Object.entries(getRouting()).filter(([role]) => role !== 'default');
|
|
39
|
+
if (entries.length === 0) return [];
|
|
40
|
+
const roles = entries.map(([role, profile]) => `${role}→${profile}`).join(', ');
|
|
41
|
+
return [
|
|
42
|
+
`- Sub-task delegation. Configured roles: ${roles}. Three tiers — ` +
|
|
43
|
+
'do it yourself for simple lookups; ask_model({role, prompt}) for one-shot expert ' +
|
|
44
|
+
'questions (analysis, design trade-offs, reviews, image description); ' +
|
|
45
|
+
'dispatch_agent({role, task, tools}) for multi-step research that needs file access — ' +
|
|
46
|
+
'the sub-agent runs its own tool loop and returns a final report (it cannot see this ' +
|
|
47
|
+
'conversation, so the task must be fully self-contained; dispatch asks the user first).',
|
|
48
|
+
];
|
|
49
|
+
}
|
|
50
|
+
|
|
35
51
|
async function gitBranch(cwd: string): Promise<string | undefined> {
|
|
36
52
|
try {
|
|
37
53
|
const { execFile } = await import('node:child_process');
|
|
@@ -95,6 +111,11 @@ export function buildSystemPrompt(
|
|
|
95
111
|
'grep/sed window commands — that wastes dozens of turns; read the file once instead.',
|
|
96
112
|
'- For synthesis tasks (update docs/README): explore briefly (aim for ~15 tool calls), ' +
|
|
97
113
|
'then state a short plan and write the result. Exploration is not the deliverable.',
|
|
114
|
+
'- Multi-step tasks (3+ steps): create the list with todo_write first, keep exactly one ' +
|
|
115
|
+
'step in_progress, and mark steps completed as you finish them.',
|
|
116
|
+
...roleRoutingLines(),
|
|
117
|
+
'- Reporting counts (tests, checks, matches): grep -c counts matching LINES, including ' +
|
|
118
|
+
'definitions like `def check(` — read the actual item list instead of trusting a raw count.',
|
|
98
119
|
'- The bash working directory persists across calls; you do not need to cd again each time.',
|
|
99
120
|
'- Never repeat an identical tool call; refine it or switch tools.',
|
|
100
121
|
'- Use edit_file for targeted changes and write_file for new files.',
|