/** 工具注册表与 Agent Loop(Harness 运行时)测试。 */ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { ToolRegistry, defineTool } from '../src/harness/registry.js'; import { EmbeddedHarness } from '../src/harness/runtime.js'; import { ReplayLlmClient } from '../src/harness/llm.js'; import { presetFromObject } from '../src/harness/preset.js'; import type { HarnessEvent } from '../src/harness/types.js'; const preset = presetFromObject({ name: 'test-agent', model: { provider: 'deepseek', name: 'deepseek-flash' }, tools: ['echo'], systemPrompt: '测试用系统提示', limits: { maxSteps: 4 }, }); function makeRegistry(calls: Array> = []): ToolRegistry { const registry = new ToolRegistry(); registry.register( defineTool({ name: 'echo', description: '回显并返回一行数据', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] }, async execute(args, context) { calls.push({ args, callId: context.callId }); return { content: { ok: true, echo: args.text }, rows: [ { values: { text: String(args.text ?? ''), amount: '123.45' }, _trace: { object_id: 'obj_1', table: 't', row_index: 0, row_hash: 'sha256:row' }, }, ], objectIds: ['obj_1'], }; }, }), ); return registry; } function resolve() { return { provider: { id: 'deepseek', displayName: 'x', baseUrl: 'http://x', apiKey: 'k', api: 'openai-completions' as const, models: ['deepseek-flash'], supportsTools: true }, model: 'deepseek-flash', temperature: 0.1, maxOutputTokens: 1024, }; } async function collect(stream: AsyncGenerator): Promise { const events: HarnessEvent[] = []; for await (const event of stream) events.push(event); return events; } test('defineTool 校验命名与 schema', () => { assert.throws(() => defineTool({ name: 'Bad Name', description: 'x', parameters: { type: 'object' }, execute: async () => ({ content: {} }) })); assert.throws(() => defineTool({ name: 'ok', description: '', parameters: { type: 'object' }, execute: async () => ({ content: {} }) })); assert.throws(() => defineTool({ name: 'ok', description: 'x', parameters: {}, execute: async () => ({ content: {} }) })); }); test('注册表拒绝重复注册,只暴露允许的工具', () => { const registry = makeRegistry(); assert.throws(() => registry.register(defineTool({ name: 'echo', description: 'x', parameters: { type: 'object' }, execute: async () => ({ content: {} }) })), ); const schemas = registry.schemas(['echo', 'not_exists']); assert.equal(schemas.length, 1); assert.equal(schemas[0]?.function.name, 'echo'); }); test('执行工具时 finalizeContent 注入 call_id 与行哈希', async () => { const registry = makeRegistry(); const outcome = await registry.execute('echo', { text: 'hi' }, { callId: 'call_x', sessionId: 's', workspaceId: 'ws' }); assert.equal(outcome.ok, true); const content = outcome.content as Record; assert.equal(content.verification_context.call_id, 'call_x'); assert.equal(content.verification_context.rows[0].row_hash, 'sha256:row'); assert.equal(content.verification_context.row_count, 1); }); test('工具抛错时返回结构化错误而不是崩溃', async () => { const registry = new ToolRegistry(); registry.register( defineTool({ name: 'boom', description: 'x', parameters: { type: 'object' }, async execute() { throw new Error('炸了'); } }), ); const outcome = await registry.execute('boom', {}, { callId: 'c', sessionId: 's', workspaceId: 'w' }); assert.equal(outcome.ok, false); assert.match(outcome.error ?? '', /炸了/); }); test('未知工具返回可用工具列表', async () => { const registry = makeRegistry(); const outcome = await registry.execute('nope', {}, { callId: 'c', sessionId: 's', workspaceId: 'w' }); assert.equal(outcome.ok, false); assert.deepEqual((outcome.content as any).available, ['echo']); }); test('Agent Loop:工具调用 → 结果回灌 → 产出最终答案', async () => { const calls: Array> = []; const registry = makeRegistry(calls); const ledgerRecords: any[] = []; const ledger = { record(input: any) { ledgerRecords.push(input); return { resultHash: 'sha256:x', rowCount: input.rows.length }; }, } as any; const llm = new ReplayLlmClient([ { text: '我先查一下。', toolCalls: [{ name: 'echo', arguments: { text: '你好' } }] }, { text: '查询结果金额为 123.45 美元。' }, ]); const harness = new EmbeddedHarness({ registry, llm, ledger, resolve }); const events = await collect( harness.run({ sessionId: 's1', workspaceId: 'ws1', messages: [{ role: 'user', content: '查一下' }], preset, }), ); const types = events.map((event) => event.type); assert.equal(types[0], 'started'); assert.ok(types.includes('tool_call')); assert.ok(types.includes('tool_result')); const final = events.find((event) => event.type === 'final') as Extract; assert.match(final.text, /123\.45/); assert.equal(final.toolCalls, 1); assert.equal(calls.length, 1); assert.equal(ledgerRecords.length, 1); assert.equal(ledgerRecords[0].callId, calls[0].callId); // 第二次请求必须带上工具结果(含溯源令牌) const secondCall = llm.seen[1]; const toolMessage = secondCall.messages.find((message) => message.role === 'tool'); assert.ok(toolMessage, '第二次调用缺少 tool 消息'); assert.match(toolMessage.content ?? '', /verification_context/); assert.match(toolMessage.content ?? '', /call_replay_1_0/); }); test('Agent Loop:多次工具调用的参数被正确累加解析', async () => { const registry = makeRegistry(); const llm = new ReplayLlmClient([ { toolCalls: [{ name: 'echo', arguments: { text: 'a' } }, { name: 'echo', arguments: { text: 'b' } }] }, { text: '完成' }, ]); const harness = new EmbeddedHarness({ registry, llm, resolve }); const events = await collect(harness.run({ sessionId: 's', workspaceId: 'w', messages: [], preset })); const toolCalls = events.filter((event) => event.type === 'tool_call'); assert.equal(toolCalls.length, 2); }); test('Agent Loop:非法 JSON 参数不会让整个对话失败', async () => { const registry = makeRegistry(); const llm = new ReplayLlmClient([{ toolCalls: [{ name: 'echo', arguments: { text: 'x' } }] }, { text: 'ok' }]); const harness = new EmbeddedHarness({ registry, llm, resolve }); const events = await collect(harness.run({ sessionId: 's', workspaceId: 'w', messages: [], preset })); assert.ok(events.some((event) => event.type === 'final')); }); test('Agent Loop:达到最大步数后强制给出结论', async () => { const registry = makeRegistry(); const steps = Array.from({ length: preset.limits.maxSteps }, () => ({ toolCalls: [{ name: 'echo', arguments: { text: 'loop' } }], })); const llm = new ReplayLlmClient([...steps, { text: '被迫总结:没有更多数据。' }]); const harness = new EmbeddedHarness({ registry, llm, resolve }); const events = await collect(harness.run({ sessionId: 's', workspaceId: 'w', messages: [], preset })); const final = events.find((event) => event.type === 'final') as Extract; assert.equal(final.steps, preset.limits.maxSteps); assert.match(final.text, /被迫总结/); // 最后一次调用禁用了工具 assert.equal(llm.seen.at(-1)?.tools.length, 0); }); test('collectScalars 只收标量,且跳过 rows / 令牌', async () => { const { collectScalars } = await import('../src/harness/runtime.js'); const scalars = collectScalars({ object_id: 'obj_1', total_matching_rows: 20, exhausted: true, stats: { included: 1057, seconds: 11.8 }, rows: [{ a: 1 }], verification_context: { call_id: 'x', row_count: 1 }, }); assert.equal(scalars['total_matching_rows'], 20); assert.equal(scalars['stats.included'], 1057); assert.equal(scalars['stats.seconds'], 11.8); assert.equal(scalars['exhausted'], undefined); assert.equal(scalars['rows'], undefined); assert.equal(scalars['verification_context'], undefined); // 数字字符串也收(Python/JS 之间数量可能以字符串传递) assert.equal(collectScalars({ total: '18695479' })['total'], '18695479'); }); test('Agent Loop:工具返回的标量也会写进台账(供核验反查)', async () => { const registry = new ToolRegistry(); registry.register( defineTool({ name: 'stat', description: '返回带标量的结果', parameters: { type: 'object' }, async execute() { return { content: { total_matching_rows: 42, stats: { included: 1057 } }, rows: [], objectIds: ['obj_1'] }; }, }), ); const records: any[] = []; const ledger = { record: (input: any) => records.push(input) } as any; const llm = new ReplayLlmClient([{ toolCalls: [{ name: 'stat', arguments: {} }] }, { text: '共 42 行' }]); const harness = new EmbeddedHarness({ registry, llm, ledger, resolve }); await collect(harness.run({ sessionId: 's', workspaceId: 'w', messages: [], preset })); assert.equal(records.length, 1); assert.equal(records[0].extraValues.total_matching_rows, 42); assert.equal(records[0].extraValues['stats.included'], 1057); }); test('Agent Loop:LLM 报错时产出 error 事件', async () => { const registry = makeRegistry(); const broken: any = { name: 'broken', async *stream() { throw new Error('模型连接失败'); }, }; const harness = new EmbeddedHarness({ registry, llm: broken, resolve }); const events = await collect(harness.run({ sessionId: 's', workspaceId: 'w', messages: [], preset })); const error = events.find((event) => event.type === 'error') as Extract; assert.match(error.message, /模型连接失败/); });