工具总线 + Agent 开环:声明式工具、人类工具与 LLM 五件系统内化(Mastra tool 形状)
用户定:Agent 调用工具一律**声明式**;人类工具与 LLM 工具要系统内化;
工具总线基于 Mastra tool 设计。
**声明面**(`toolbox/internal/domain/tool-bus.ts`,纯逻辑零框架):
`compileToolBus(声明 × 目录) → 一张清单` —— 编译期定死这一单能调什么,
清单之外结构上调不到(白名单在缝里再把一次关);缺件/停用如实报不静默。
三路同一形状:
· `function` 功能工具:按活动白名单查目录,带出效应(read/write)
· `human` **人类工具**(系统内化、零声明即得):调人 = 发工单 + 立监听听人 ——
这是 Harness 给的能力,不进目录、不需白名单,每个活动天然可以调人
· `llm` **LLM 五件**(系统内化):extract/classify/summarize/judge/rewrite,
各有入参出参契约、经模型网关一缝;**仅当活动声明了模型用途名才上总线**
(没声明却会问模型 = 越权,用量也无从归因);提示词归系统,活动改不了
**装配面**(`app/tool-bus.ts`,Mastra `createTool`):清单 → 可调用工具,
JSON Schema 现译 zod(模型照它填参,填错当场被拦);三路各穿各的缝:
写类工具**过程中一律不落地**,只登记动作意向(骗 Agent 说已执行是最坏选项);
调人把卡号记进 trace,引擎据此把这一拍挂起。
**Agent 开环**(`app/mastra-agent-runner.ts`,M5-2 第二实现,用户选的路线):
Mastra `Agent` + 工具总线,拍内自主连环调工具,拍末交回结构化结论。
放开的是工具循环不是规矩:写类不落地、终局唯放行、调人即挂起(新增
`AgentAction.asked` 型 —— 卡已由总线发出,引擎只收尾,不重复发卡)、
用量按 usage 计入预算。`JCAI_AGENT_OPEN_LOOP=1` 开启,缺省仍是单拍版。
`ModelGateway.resolve` 新增:名 → 四元(密钥当场解出,只给 app 层装配用)。
代价如实记 debt M5-2:开环下模型**逐轮**调用不经录制回放(tool-calling 往返
`generate` 的 text-in/text-out 承载不了)—— 凭证隔离与工具调用一缝完整。
测试:tool-bus 六例(白名单/缺件/停用/人类工具恒在/LLM 按声明/五件契约);
四闸(typecheck/lint/depcruise/test)全过;spike 目录排除出 lint(验证性原型)。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* loop 的 Agent 回路(**开环**)—— `AgentPort` 的 Mastra 实现(M5-2;app 层装配 §5.2)。
|
||||
*
|
||||
* 与单拍版(`agent-runner.ts`)的分工:
|
||||
* · 单拍版:问一次模型、要一个行动,引擎替它执行 —— 保守、每步可拦;
|
||||
* · **开环版(此处)**:给它一张**工具总线**,让它在一拍内自主连环调工具
|
||||
* (读类真调、写类登记意向、LLM 五件、调人),拍末只交回**这一拍的结论**。
|
||||
*
|
||||
* 放开的是工具循环,**不是规矩**:
|
||||
* · 能调什么由活动声明定死(工具总线在编译期出清单,白名单在缝里再把一次关);
|
||||
* · 写类工具**过程中一律不落地**,只登记动作意向 —— 放行那一刻才由系统执行;
|
||||
* · 调人由总线执行(发卡 + 立监听),引擎收到 `asked` 就把这一拍挂起,不重复发卡;
|
||||
* · 终局唯放行:Agent 只能 `submit`(提交放行),不能自己宣布完成;
|
||||
* · 用量按 Mastra 回报的 usage 计入任务预算 —— 不计,预算熔断永远不会响。
|
||||
*
|
||||
* 代价(如实记 debt M5-2):开环下模型的**逐轮**调用不经模型网关的录制回放
|
||||
* (tool-calling 往返 `generate` 的 text-in/text-out 抽象承载不了)——
|
||||
* 四元绑定与凭证隔离照旧走网关 `resolve`;**工具调用一缝完整**,工具侧录制回放不破。
|
||||
*/
|
||||
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
|
||||
import { Agent } from '@mastra/core/agent';
|
||||
import { z } from 'zod';
|
||||
import type { TaskId } from '@contracts';
|
||||
import type { AgentAction, EnabledSet } from '@modules/loop-engine';
|
||||
import type { ModelGateway } from '@modules/llm';
|
||||
import type { BusTool } from '@modules/toolbox';
|
||||
import { buildMastraTools } from './tool-bus.ts';
|
||||
import type { ToolBusContext, ToolBusPorts } from './tool-bus.ts';
|
||||
|
||||
/** 拍末结论 —— Agent 干完活要说清「这一拍算什么」,不能只是聊完就走 */
|
||||
const TURN_RESULT = z.object({
|
||||
kind: z.enum(['start', 'plan', 'disable', 'judge', 'submit', 'idle']).describe('这一拍的结论'),
|
||||
itemId: z.string().optional().describe('start / plan / disable 针对哪个计划项'),
|
||||
reason: z.string().optional(),
|
||||
criterion: z.string().optional().describe('judge:评估的是哪条语义性前提'),
|
||||
satisfied: z.boolean().optional().describe('judge:满足与否'),
|
||||
rationale: z.string().optional().describe('结论理由 —— 留痕要看,写实'),
|
||||
});
|
||||
|
||||
export type MastraAgentRunnerDeps = {
|
||||
readonly gateway: ModelGateway;
|
||||
/** 活动声明的自定义模型名 */
|
||||
readonly modelOf: (taskId: TaskId) => Promise<string>;
|
||||
/** 这一单能调什么:工具总线清单(声明 × 目录编译而来) */
|
||||
readonly busOf: (taskId: TaskId) => Promise<readonly BusTool[]>;
|
||||
/** 三路缝 */
|
||||
readonly ports: ToolBusPorts;
|
||||
/** 拍内上下文:负责人与人工调用上限 */
|
||||
readonly contextOf: (taskId: TaskId) => Promise<Omit<ToolBusContext, 'model'>>;
|
||||
/** token 回报:计入任务预算 */
|
||||
readonly onUsage: (taskId: TaskId, tokens: number) => Promise<void>;
|
||||
/** 一拍内最多几轮工具调用 —— 环外还有 Harness 的预算硬闸,这只是拍内的礼貌上限 */
|
||||
readonly maxToolRounds?: number;
|
||||
};
|
||||
|
||||
export function createMastraAgentRunner(deps: MastraAgentRunnerDeps): {
|
||||
decide(input: { taskId: TaskId; narrative: string; enabled: EnabledSet; scope: Record<string, unknown> }): Promise<AgentAction>;
|
||||
} {
|
||||
return {
|
||||
async decide({ taskId, narrative, enabled, scope }) {
|
||||
const modelName = await deps.modelOf(taskId);
|
||||
const base = await deps.contextOf(taskId);
|
||||
const bus = await deps.busOf(taskId);
|
||||
const trace: { askedCardId?: string } = {};
|
||||
|
||||
const instructions = [
|
||||
'你是这一单任务的案例工作者。你有一组工具可用,可以连续调用它们把这一拍的活干完。',
|
||||
'',
|
||||
'规矩(硬约束,违反即被系统拦下):',
|
||||
'① **写类工具不会当场生效** —— 调了只是登记动作意向,放行那一刻系统才真执行。',
|
||||
' 所以不要假设世界已经改变,更不要因为「已经调过」就跳过必要的确认。',
|
||||
'② **调人(human.ask)会让这一拍就此挂起等回传** —— 只在真需要人裁断/补料时调,',
|
||||
' 而且必须把卡填实:title 一句话说清要什么、ask 写明具体问题、basis 给出判断依据。',
|
||||
' 一张只写「请处理」的卡等于白发。调完人就结束这一拍,别再调别的。',
|
||||
'③ **终局唯放行**:成果齐了就 submit(提交放行),由人验收 —— 你不能自己宣布完成。',
|
||||
'④ 干完活必须给出这一拍的结论(见输出格式);拿不准就 idle 并说清卡在哪。',
|
||||
'',
|
||||
`【案例说明书与记忆】\n${narrative}`,
|
||||
].join('\n');
|
||||
|
||||
const endpoint = await deps.gateway.resolve(modelName);
|
||||
const provider = createOpenAICompatible({
|
||||
name: endpoint.provider,
|
||||
apiKey: endpoint.apiKey,
|
||||
baseURL: endpoint.baseUrl,
|
||||
});
|
||||
|
||||
const agent = new Agent({
|
||||
id: `loop-${taskId}`,
|
||||
name: '案例工作者',
|
||||
instructions,
|
||||
model: provider.chatModel(endpoint.model),
|
||||
tools: buildMastraTools(bus, deps.ports, { ...base, model: modelName }, trace),
|
||||
});
|
||||
|
||||
const prompt = [
|
||||
`【当下可为(Enabled 集)】\n${
|
||||
enabled.entries
|
||||
.map((e) => `- ${e.id} ${e.name}(${e.type}${e.requiresManualStart ? ' · 须你启动' : ''}${e.discretionary ? ' · 裁量项' : ''})`)
|
||||
.join('\n') || '(空)'
|
||||
}`,
|
||||
`【目标缺口】\n${enabled.gaps.join('、') || '(无)'}`,
|
||||
enabled.judgements.length === 0
|
||||
? ''
|
||||
: `【待你评估的语义性前提】\n${enabled.judgements.map((j) => `- ${j.criterion}:${j.statement}`).join('\n')}`,
|
||||
enabled.entries.length === 0 ? '【注意】当下可为 ∩ 目标所需 = 空 —— 这是依赖断点,调人或说清卡在哪。' : '',
|
||||
`【任务数据】\n${JSON.stringify(scope).slice(0, 4000)}`,
|
||||
'',
|
||||
'干这一拍该干的活(可以连续调工具),最后给出结论。',
|
||||
]
|
||||
.filter((line) => line !== '')
|
||||
.join('\n');
|
||||
|
||||
try {
|
||||
const result = await agent.generate(prompt, {
|
||||
maxSteps: deps.maxToolRounds ?? 8,
|
||||
structuredOutput: { schema: TURN_RESULT },
|
||||
} as never);
|
||||
|
||||
const usage = (result as { usage?: { totalTokens?: number; inputTokens?: number; outputTokens?: number } }).usage;
|
||||
const tokens = usage?.totalTokens ?? (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0);
|
||||
if (tokens > 0) await deps.onUsage(taskId, tokens);
|
||||
|
||||
// 调过人就必须收在 asked:卡已发、监听已立,引擎只收尾挂起(再发一张就是重复调人)
|
||||
if (trace.askedCardId !== undefined) {
|
||||
return { kind: 'asked', cardId: trace.askedCardId, rationale: '本回合已调人,等回传' };
|
||||
}
|
||||
|
||||
return normalizeTurn((result as { object?: unknown }).object, enabled);
|
||||
} catch (error) {
|
||||
/*
|
||||
* 这一拍问不出结果(端点不可达、鉴权失败、超时、工具连环炸)——
|
||||
* **不是异常路径,是断点的一种**:机器当下决断不了就该调人。
|
||||
* 抛出去只会让任务空转:推进器每一拍重试、预算照烧,负责人却什么都看不到。
|
||||
*
|
||||
* 但**已经调过人**的那一拍例外:卡在世界上了,老老实实收成 asked,
|
||||
* 不要再叠一张「模型出错」的卡上去。
|
||||
*/
|
||||
if (trace.askedCardId !== undefined) {
|
||||
return { kind: 'asked', cardId: trace.askedCardId, rationale: '本回合已调人(其后模型出错)' };
|
||||
}
|
||||
const detail = error instanceof Error ? error.message : String(error);
|
||||
return {
|
||||
kind: 'human',
|
||||
itemId: enabled.entries[0]?.id ?? 'breakpoint',
|
||||
workOrder: 'execution',
|
||||
card: {
|
||||
title: '模型这一轮未能决断,转人裁断',
|
||||
reason: detail,
|
||||
basis: [
|
||||
{ k: '当下可为', v: enabled.entries.map((e) => e.name).join('、') || '(空)' },
|
||||
{ k: '目标缺口', v: enabled.gaps.join('、') || '(无)' },
|
||||
],
|
||||
ask: '请判断下一步:接着走哪一项,或补齐缺口后让环继续。',
|
||||
fields: ['decision'],
|
||||
},
|
||||
};
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** 拍末结论归一为 AgentAction;给不出结论就当空拍(idle → judge 留痕),绝不乱动世界 */
|
||||
function normalizeTurn(object: unknown, enabled: EnabledSet): AgentAction {
|
||||
const raw = (object ?? {}) as Record<string, unknown>;
|
||||
const kind = String(raw['kind'] ?? 'idle');
|
||||
const itemId = String(raw['itemId'] ?? enabled.entries[0]?.id ?? '');
|
||||
const rationale = String(raw['rationale'] ?? '');
|
||||
|
||||
switch (kind) {
|
||||
case 'start':
|
||||
case 'plan':
|
||||
return { kind: kind as 'start' | 'plan', itemId };
|
||||
case 'disable':
|
||||
return { kind: 'disable', itemId, reason: String(raw['reason'] ?? '此单不走这条') };
|
||||
case 'judge':
|
||||
return {
|
||||
kind: 'judge',
|
||||
criterion: String(raw['criterion'] ?? ''),
|
||||
satisfied: raw['satisfied'] === true,
|
||||
rationale,
|
||||
};
|
||||
case 'submit':
|
||||
return { kind: 'submit', rationale: rationale === '' ? '判定成果已齐' : rationale };
|
||||
default:
|
||||
/*
|
||||
* idle:这一拍干了活(工具调用已经落在总线上)但推不动局面。
|
||||
* 记成一条 judge 留痕 —— 空拍也要说清卡在哪,不然人看不见环在原地打转。
|
||||
*/
|
||||
return {
|
||||
kind: 'judge',
|
||||
criterion: '本回合是否推动了局面',
|
||||
satisfied: false,
|
||||
rationale: rationale === '' ? '模型未给出结论' : rationale,
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,219 @@
|
||||
/**
|
||||
* 工具总线的**装配面** —— 声明清单 → 可调用的 Mastra tools(编码规范 §6.2:
|
||||
* `@mastra` 只准出现在 adapter 与 app)。
|
||||
*
|
||||
* 声明面(纯逻辑,`toolbox/internal/domain/tool-bus.ts`)决定**能调什么**;
|
||||
* 这里决定**怎么调** —— 三路各自穿过它该穿的那道缝,一道都不许绕:
|
||||
* · `function` → **工具调用一缝**(`ToolInvoker`):白名单、录制回放、契约校验;
|
||||
* 写类**不当场落地**,只登记动作意向,放行那一刻才由系统执行;
|
||||
* · `human` → 人类工具:发工单到负责人工位 + 立监听听回传,本回合就此等待;
|
||||
* · `llm` → **模型网关一缝**(`ModelGateway`):四元绑定、录制回放、用量计预算。
|
||||
*
|
||||
* 每件工具的入参 schema 由清单里的 JSON Schema 现译成 zod —— 模型照它填参,
|
||||
* 填错当场被 Mastra 拦下,不会带着脏参数穿过缝。
|
||||
*/
|
||||
import { createTool } from '@mastra/core/tools';
|
||||
import type { ToolsInput } from '@mastra/core/agent';
|
||||
import { z } from 'zod';
|
||||
import type { StaffId, TaskId } from '@contracts';
|
||||
import type { BusTool } from '@modules/toolbox';
|
||||
|
||||
/** 三路缝的最小口子 —— 各自只要这一点点能力,不把整个服务拖进来 */
|
||||
export type ToolBusPorts = {
|
||||
/** 功能工具:读类当场调;写类先登记意向(放行才落地) */
|
||||
readonly invoke: (input: {
|
||||
taskId: TaskId;
|
||||
tool: string;
|
||||
input: Record<string, unknown>;
|
||||
}) => Promise<{ ok: boolean; output?: Record<string, unknown>; error?: { message: string } }>;
|
||||
readonly isWriteEffect: (tool: string) => Promise<boolean>;
|
||||
readonly registerIntent: (input: {
|
||||
taskId: TaskId;
|
||||
tool: string;
|
||||
input: Record<string, unknown>;
|
||||
label: string;
|
||||
}) => Promise<void>;
|
||||
/** 人类工具:发工单 */
|
||||
readonly issueCard: (input: {
|
||||
taskId: TaskId;
|
||||
ownerId: StaffId;
|
||||
humanCallCap: number;
|
||||
workOrder: 'execution' | 'acceptance';
|
||||
card: Record<string, unknown>;
|
||||
}) => Promise<{ id: string }>;
|
||||
/** 人类工具:立监听听人 */
|
||||
readonly listen: (input: {
|
||||
taskId: TaskId;
|
||||
eventType: 'data' | 'time' | 'human';
|
||||
keyFilter: Record<string, string>;
|
||||
deadline: string;
|
||||
}) => Promise<{ id: string }>;
|
||||
/** LLM 工具:经模型网关 */
|
||||
readonly generate: (input: {
|
||||
model: string;
|
||||
system?: string;
|
||||
prompt: string;
|
||||
outputSchema?: Record<string, unknown>;
|
||||
taskId: TaskId;
|
||||
label: string;
|
||||
}) => Promise<{ text: string; object?: unknown }>;
|
||||
};
|
||||
|
||||
export type ToolBusContext = {
|
||||
readonly taskId: TaskId;
|
||||
readonly ownerId: StaffId;
|
||||
readonly humanCallCap: number;
|
||||
/** 活动声明的模型用途名(第一个)—— LLM 工具用它,活动不见厂商型号 */
|
||||
readonly model: string;
|
||||
};
|
||||
|
||||
/** 本回合调人的痕:总线把它交回引擎,引擎据此把这一拍收成 awaiting */
|
||||
export type ToolBusTrace = {
|
||||
/** 调人发出的卡(有值即本回合要等人) */
|
||||
askedCardId?: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* JSON Schema → zod(仅译总线用得上的那一小撮:object/string/number/integer/
|
||||
* boolean/array/enum)。译不出的类型退化成 `z.unknown()` —— 宁可放宽,
|
||||
* 也不假装校验过:真正的契约校验在缝里(`ToolInvoker.validate`),这里只为让模型会填。
|
||||
*/
|
||||
function toZod(schema: Record<string, unknown> | undefined): z.ZodTypeAny {
|
||||
if (schema === undefined) return z.object({}).passthrough();
|
||||
const type = schema['type'];
|
||||
const describe = (t: z.ZodTypeAny) =>
|
||||
typeof schema['description'] === 'string' ? t.describe(schema['description']) : t;
|
||||
|
||||
if (Array.isArray(schema['enum'])) {
|
||||
const values = (schema['enum'] as unknown[]).map(String);
|
||||
return describe(values.length > 0 ? z.enum(values as [string, ...string[]]) : z.string());
|
||||
}
|
||||
if (type === 'string') return describe(z.string());
|
||||
if (type === 'number') return describe(z.number());
|
||||
if (type === 'integer') return describe(z.number().int());
|
||||
if (type === 'boolean') return describe(z.boolean());
|
||||
if (type === 'array') {
|
||||
const items = schema['items'];
|
||||
return describe(z.array(toZod(typeof items === 'object' && items !== null ? (items as Record<string, unknown>) : undefined)));
|
||||
}
|
||||
if (type === 'object') {
|
||||
const props = schema['properties'];
|
||||
if (typeof props !== 'object' || props === null) return describe(z.object({}).passthrough());
|
||||
const required = new Set(Array.isArray(schema['required']) ? (schema['required'] as string[]) : []);
|
||||
const shape: Record<string, z.ZodTypeAny> = {};
|
||||
for (const [key, value] of Object.entries(props as Record<string, unknown>)) {
|
||||
const field = toZod(typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined);
|
||||
shape[key] = required.has(key) ? field : field.optional();
|
||||
}
|
||||
return describe(z.object(shape));
|
||||
}
|
||||
return describe(z.unknown());
|
||||
}
|
||||
|
||||
/** LLM 五件的提示词:系统内化的能力,提示词也归系统 —— 活动不写、也改不了 */
|
||||
function llmPrompt(id: string, args: Record<string, unknown>): { system: string; prompt: string } {
|
||||
const j = (v: unknown) => JSON.stringify(v ?? null);
|
||||
switch (id) {
|
||||
case 'llm.extract':
|
||||
return {
|
||||
system: '你是抽取器。只从原文里抽,抽不到的字段留空 —— **不许编**。只回 JSON。',
|
||||
prompt: `字段:${j(args['fields'])}\n提示:${String(args['hint'] ?? '无')}\n原文:\n${String(args['text'] ?? '')}\n\n回 {"values": {字段: 值}}`,
|
||||
};
|
||||
case 'llm.classify':
|
||||
return {
|
||||
system: '你是归类器。只能从给定类目里选一个;判不了就回 "unknown"。只回 JSON。',
|
||||
prompt: `类目:${j(args['labels'])}\n提示:${String(args['hint'] ?? '无')}\n内容:\n${String(args['text'] ?? '')}\n\n回 {"label": "...", "rationale": "一句话理由"}`,
|
||||
};
|
||||
case 'llm.summarize':
|
||||
return {
|
||||
system: '你是摘要器。只压缩已有内容,不添事实、不作判断。只回 JSON。',
|
||||
prompt: `重点:${String(args['focus'] ?? '无')}\n字数上限:${String(args['maxWords'] ?? 200)}\n原文:\n${String(args['text'] ?? '')}\n\n回 {"summary": "..."}`,
|
||||
};
|
||||
case 'llm.judge':
|
||||
return {
|
||||
system: '你是裁断器。给出是/否与理由,并诚实给出把握度(0-1)。**你的结论只作参考,不代替人的放行裁决**。只回 JSON。',
|
||||
prompt: `问题:${String(args['question'] ?? '')}\n判据:\n${String(args['basis'] ?? '')}\n\n回 {"verdict": true/false, "confidence": 0-1, "rationale": "理由"}`,
|
||||
};
|
||||
default:
|
||||
return {
|
||||
system: '你是改写器。只改表达方式,**不添事实、不删事实**。只回 JSON。',
|
||||
prompt: `要求:${String(args['instruction'] ?? '')}\n原文:\n${String(args['text'] ?? '')}\n\n回 {"text": "改写后"}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 把总线清单装配成 Mastra tools。
|
||||
*
|
||||
* `trace` 是回传口:调人这件事在 Agent 眼里是「调了个工具」,在引擎眼里是
|
||||
* 「本回合要挂起等人」—— 工具执行时把卡号记进 trace,引擎读它收尾。
|
||||
*/
|
||||
export function buildMastraTools(
|
||||
bus: readonly BusTool[],
|
||||
ports: ToolBusPorts,
|
||||
context: ToolBusContext,
|
||||
trace: ToolBusTrace,
|
||||
): ToolsInput {
|
||||
const out: ToolsInput = {};
|
||||
|
||||
for (const tool of bus) {
|
||||
// Mastra 的 tool id 不收点号以外的怪字符,统一把点号换成双下划线,回调时换回来
|
||||
const key = tool.id.replace(/[^a-zA-Z0-9_]/g, '__');
|
||||
|
||||
out[key] = createTool({
|
||||
id: key,
|
||||
description: tool.description,
|
||||
inputSchema: toZod(tool.input) as never,
|
||||
execute: async (inputData: unknown) => {
|
||||
const args = (inputData ?? {}) as Record<string, unknown>;
|
||||
|
||||
if (tool.kind === 'human') {
|
||||
const card = await ports.issueCard({
|
||||
taskId: context.taskId,
|
||||
ownerId: context.ownerId,
|
||||
humanCallCap: context.humanCallCap,
|
||||
workOrder: 'execution',
|
||||
card: args,
|
||||
});
|
||||
await ports.listen({
|
||||
taskId: context.taskId,
|
||||
eventType: 'human',
|
||||
keyFilter: { cardId: card.id },
|
||||
deadline: 'P3D',
|
||||
});
|
||||
trace.askedCardId = card.id;
|
||||
return { asked: true, cardId: card.id };
|
||||
}
|
||||
|
||||
if (tool.kind === 'llm') {
|
||||
const { system, prompt } = llmPrompt(tool.id, args);
|
||||
const result = await ports.generate({
|
||||
model: context.model,
|
||||
system,
|
||||
prompt,
|
||||
...(tool.output === undefined ? {} : { outputSchema: tool.output }),
|
||||
taskId: context.taskId,
|
||||
label: tool.id,
|
||||
});
|
||||
return (result.object ?? { text: result.text }) as Record<string, unknown>;
|
||||
}
|
||||
|
||||
/*
|
||||
* 功能工具:**写类不当场落地**(OS 06「过程不落地」)——
|
||||
* 过程中只冻结入参登记为动作意向,放行那一刻由系统执行。
|
||||
* 骗 Agent 说「已执行」是最坏的选项:它会据此往下推,而世界上什么都没发生。
|
||||
*/
|
||||
if (await ports.isWriteEffect(tool.id)) {
|
||||
await ports.registerIntent({ taskId: context.taskId, tool: tool.id, input: args, label: tool.id });
|
||||
return { registered: true, note: '写类工具已登记为动作意向 —— 放行时才真正执行,现在世界上什么都没变' };
|
||||
}
|
||||
|
||||
const result = await ports.invoke({ taskId: context.taskId, tool: tool.id, input: args });
|
||||
if (!result.ok) return { ok: false, error: result.error?.message ?? '工具调用失败' };
|
||||
return { ok: true, ...(result.output ?? {}) };
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
return out;
|
||||
}
|
||||
@@ -9,6 +9,7 @@ import type { EventService } from '@modules/event';
|
||||
import type { LedgerService } from '@modules/ledger';
|
||||
import type { MemoryService } from '@modules/memory';
|
||||
import type { ToolboxService, ToolInvoker } from '@modules/toolbox';
|
||||
import { compileToolBus } from '@modules/toolbox';
|
||||
import type { HumanToolService } from '@modules/human-tool';
|
||||
import { renderView } from '@modules/interaction';
|
||||
import type { InteractionService } from '@modules/interaction';
|
||||
@@ -33,6 +34,7 @@ import { evaluate as evalSfeel, evaluateCondition, evaluateUnaryTest } from '@sf
|
||||
import type { StaffId, TaskId } from '@contracts';
|
||||
import { staffIdSchema } from '@contracts';
|
||||
import { createAgentRunner } from '../agent-runner.ts';
|
||||
import { createMastraAgentRunner } from '../mastra-agent-runner.ts';
|
||||
import type { Clock, IdGenerator } from '../runtime.ts';
|
||||
|
||||
export type EngineWiringDeps = {
|
||||
@@ -398,21 +400,93 @@ export function wireEngines(deps: EngineWiringDeps): EngineWiring {
|
||||
clock,
|
||||
});
|
||||
|
||||
/* ── Agent 回路:单拍 or 开环(工具总线)────────────────────────── */
|
||||
|
||||
/** 活动声明的自定义模型名 —— 活动只见用途名,不见厂商型号 */
|
||||
const modelOf = async (taskId: TaskId) => {
|
||||
const { activityId } = await taskContext.of(taskId);
|
||||
const manifest = await deps.registry.manifestOf(activityId);
|
||||
return manifest.declarations.models[0] ?? 'default';
|
||||
};
|
||||
const onAgentUsage = (taskId: TaskId, tokens: number) =>
|
||||
taskStore.addConsumption(taskId, { tokens }).then(() => undefined);
|
||||
|
||||
/**
|
||||
* 工具总线:**声明 × 目录**,编译期定死这一单能调什么(声明面在 toolbox/domain)。
|
||||
* 功能工具按活动白名单查目录;人类工具恒在(Harness 给的能力);
|
||||
* LLM 五件仅当活动声明了模型用途名才给 —— 没声明模型却会问模型,是越权也无从归因。
|
||||
*/
|
||||
const busOf = async (taskId: TaskId) => {
|
||||
const { activityId } = await taskContext.of(taskId);
|
||||
const manifest = await deps.registry.manifestOf(activityId);
|
||||
const catalog = new Map(
|
||||
(await deps.toolbox.list()).map((c) => [
|
||||
c.name,
|
||||
{
|
||||
name: c.name,
|
||||
description: c.description,
|
||||
input: c.input,
|
||||
...(c.output === undefined ? {} : { output: c.output }),
|
||||
effect: c.effect === 'read' ? ('read' as const) : ('write' as const),
|
||||
},
|
||||
]),
|
||||
);
|
||||
const report = compileToolBus({
|
||||
declaredTools: manifest.declarations.tools.map((t) => t.name),
|
||||
catalog,
|
||||
declaredModels: manifest.declarations.models,
|
||||
});
|
||||
// 声明了却查无此工具 / 已停用:如实记痕,不静默 —— Agent 手上少了件东西,得看得见
|
||||
if (report.missing.length > 0 || report.disabled.length > 0) {
|
||||
await memoryRecorder.append({
|
||||
taskId,
|
||||
kind: 'observation',
|
||||
title: `工具总线缺件:未装 ${report.missing.join('、') || '无'};已停用 ${report.disabled.join('、') || '无'}`,
|
||||
} as never);
|
||||
}
|
||||
return report.tools;
|
||||
};
|
||||
|
||||
/*
|
||||
* 开环 or 单拍:`JCAI_AGENT_OPEN_LOOP=1` 时用 Mastra Agent 放开拍内工具循环。
|
||||
* 缺省仍是单拍版 —— 开环把「一拍调几次模型」交给了模型自己,
|
||||
* 得有第一个真 loop 活动压着测过才好当缺省(见 debt M5-2)。
|
||||
*/
|
||||
const agentRunner =
|
||||
globalThis.process.env['JCAI_AGENT_OPEN_LOOP'] === '1'
|
||||
? createMastraAgentRunner({
|
||||
gateway: deps.modelGateway,
|
||||
modelOf,
|
||||
busOf,
|
||||
onUsage: onAgentUsage,
|
||||
contextOf: async (taskId) => {
|
||||
const ctx = await taskContext.of(taskId);
|
||||
return { taskId, ownerId: ctx.ownerId, humanCallCap: ctx.humanCallCap };
|
||||
},
|
||||
ports: {
|
||||
invoke: async (input) => {
|
||||
const { activityId } = await taskContext.of(input.taskId);
|
||||
return toolGateway.invoke({ ...input, activityId });
|
||||
},
|
||||
isWriteEffect: (tool) => toolGateway.isWriteEffect(tool),
|
||||
registerIntent: (input) => toolGateway.registerIntent(input),
|
||||
issueCard: (input) => cards.issue(input),
|
||||
listen: (input) => listeners.register(input),
|
||||
generate: async (input) => {
|
||||
const result = await deps.modelGateway.generate(input);
|
||||
await onAgentUsage(input.taskId, result.usage.inputTokens + result.usage.outputTokens);
|
||||
return { text: result.text, ...(result.object === undefined ? {} : { object: result.object }) };
|
||||
},
|
||||
},
|
||||
})
|
||||
: createAgentRunner({ gateway: deps.modelGateway, onUsage: onAgentUsage, modelOf });
|
||||
|
||||
/* ── loop-engine ──────────────────────────────────────────────── */
|
||||
const loop = createTurnRunner({
|
||||
state: createLoopStateStore(db),
|
||||
sfeel,
|
||||
data: taskData,
|
||||
agent: createAgentRunner({
|
||||
gateway: deps.modelGateway,
|
||||
// loop 的每一回合都要问模型 —— 不计 token,预算熔断就永远不会响
|
||||
onUsage: (taskId, tokens) => taskStore.addConsumption(taskId, { tokens }).then(() => undefined),
|
||||
modelOf: async (taskId) => {
|
||||
const { activityId } = await taskContext.of(taskId);
|
||||
const manifest = await deps.registry.manifestOf(activityId);
|
||||
return manifest.declarations.models[0] ?? 'default';
|
||||
},
|
||||
}),
|
||||
agent: agentRunner,
|
||||
tools: toolGateway,
|
||||
cards,
|
||||
listeners,
|
||||
|
||||
@@ -76,12 +76,27 @@ export type ModelResult = {
|
||||
readonly mode: GatewayMode;
|
||||
};
|
||||
|
||||
/** 解好的模型端点(四元 + 明文密钥)—— app 层装配专用,见 ModelGateway.resolve */
|
||||
export type ResolvedEndpoint = {
|
||||
readonly provider: LlmProvider;
|
||||
readonly baseUrl: string;
|
||||
readonly model: string;
|
||||
readonly apiKey: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* 模型网关 —— 活动基座六件里的「LLM 调用」。
|
||||
* 活动只见自定义模型名;解析、凭证、录制回放全在此。
|
||||
*/
|
||||
export type ModelGateway = {
|
||||
readonly mode: GatewayMode;
|
||||
/**
|
||||
* 解绑定:名 → 四元(含当场解出的密钥)—— **只给 app 层装配用**:
|
||||
* Mastra Agent 那类需要真模型对象做 tool-calling 往返的场合,
|
||||
* `generate` 的 text-in/text-out 抽象承载不了。
|
||||
* 密钥与 endpoint 仍不入 domain、不入包、不入留痕明文(OS 7.3 凭证隔离)。
|
||||
*/
|
||||
resolve(modelName: string): Promise<ResolvedEndpoint>;
|
||||
generate(call: ModelCall): Promise<ModelResult>;
|
||||
/** 换模式的网关 —— 回放审用 replay 模式重跑引擎(§7.3) */
|
||||
withMode(mode: GatewayMode): ModelGateway;
|
||||
|
||||
@@ -10,6 +10,7 @@ export type {
|
||||
ModelBinding,
|
||||
ModelCall,
|
||||
ModelGateway,
|
||||
ResolvedEndpoint,
|
||||
ModelResult,
|
||||
ModelUsage,
|
||||
UpsertLlmInstance,
|
||||
|
||||
@@ -26,6 +26,25 @@ export function createModelGateway(deps: ModelGatewayDeps): ModelGateway {
|
||||
const gateway: ModelGateway = {
|
||||
mode: deps.mode,
|
||||
|
||||
/**
|
||||
* 解绑定:名 → 四元(密钥当场解出)。给 app 层装 Mastra Agent 那种
|
||||
* 需要真模型对象的场合(tool-calling 往返,`generate` 的 text-in/text-out 承载不了);
|
||||
* `generate` 那条主路照旧全程在网关内部,录制回放不受影响。
|
||||
*/
|
||||
async resolve(modelName) {
|
||||
const binding = await deps.instances.findByName(modelName);
|
||||
if (binding === undefined) throw new ModelNotBoundError(modelName, [{ field: 'name', message: '实例不存在' }]);
|
||||
if (!binding.enabled) throw new ModelDisabledError(modelName);
|
||||
const violations = validateBinding(binding);
|
||||
if (violations.length > 0) throw new ModelNotBoundError(modelName, violations);
|
||||
return {
|
||||
provider: binding.provider,
|
||||
baseUrl: binding.baseUrl,
|
||||
model: binding.model,
|
||||
apiKey: deps.secrets.open(binding.apiKeyCipher!),
|
||||
};
|
||||
},
|
||||
|
||||
async generate(call: ModelCall): Promise<ModelResult> {
|
||||
const key = replayKey(call);
|
||||
|
||||
|
||||
@@ -70,7 +70,13 @@ export type AgentAction =
|
||||
/** 评估语义性前提(评估留痕,可回放可归因) */
|
||||
| { readonly kind: 'judge'; readonly criterion: string; readonly satisfied: boolean; readonly rationale: string }
|
||||
/** 判定成果已齐,提交放行 */
|
||||
| { readonly kind: 'submit'; readonly rationale: string };
|
||||
| { readonly kind: 'submit'; readonly rationale: string }
|
||||
/**
|
||||
* 本回合**已在工具循环里调过人**:卡已发、监听已立(工具总线执行的)。
|
||||
* 引擎只收尾把这一拍置 awaiting —— 不能再发一张,否则负责人工位上堆两张同样的卡。
|
||||
* 开环模式(Mastra Agent 自主连环调工具)专用;单拍模式给不出这一型。
|
||||
*/
|
||||
| { readonly kind: 'asked'; readonly cardId: string; readonly rationale: string };
|
||||
|
||||
export type TurnOutcome = {
|
||||
readonly runtime: CaseRuntime;
|
||||
|
||||
@@ -190,6 +190,20 @@ export function createTurnRunner(deps: TurnRunnerDeps): LoopEngineService {
|
||||
return { runtime, status: 'awaiting' };
|
||||
}
|
||||
|
||||
case 'asked': {
|
||||
/*
|
||||
* 开环模式:调人已由**工具总线**在拍内执行(发卡 + 立监听),引擎只收尾。
|
||||
* 再发一张就是重复调人 —— 工位上两张一模一样的卡,谁也不知道该答哪张。
|
||||
*/
|
||||
await deps.memory.append({
|
||||
taskId,
|
||||
kind: 'thought',
|
||||
title: `本回合调人待回(卡 ${action.cardId})`,
|
||||
detail: { rationale: action.rationale },
|
||||
});
|
||||
return { runtime, status: 'awaiting' };
|
||||
}
|
||||
|
||||
case 'submit': {
|
||||
// 终局唯放行:提交 = 发验收卡挂起等人裁决,不是自结(引擎不把案计划置为 Completed)
|
||||
return raiseAcceptance(taskId, runtime, action.rationale);
|
||||
|
||||
@@ -22,6 +22,13 @@
|
||||
app(治理台 · 工具管理)
|
||||
|
||||
不变量:
|
||||
- **工具总线是声明式的**(2026-07-28):Agent 能调什么由**活动声明 × 工具目录**在
|
||||
编译期定死(`compileToolBus`),不由 Agent 临场想、也不由活动代码自己决定;
|
||||
声明了却查无此工具 / 已停用如实报,不静默给空壳。三路同一张清单:
|
||||
`function`(功能工具,经工具调用一缝:白名单/录制回放/写类只登记意向)、
|
||||
`human`(**人类工具**,系统内化、零声明即得 —— 调人是 Harness 给的能力)、
|
||||
`llm`(**LLM 五件**:抽取/归类/摘要/裁断/改写,经模型网关一缝;
|
||||
仅当活动声明了模型用途名才上总线 —— 没声明却会问模型是越权,用量也无从归因)
|
||||
- **一切工具执行经 `ToolInvoker`** —— 绕过它,回放审就对它失明(§12.5#10)
|
||||
- `replay` 模式**绝不回退实调**:缺录即 `ToolReplayMissError`
|
||||
- **白名单在结构上拦截**:功能工具按活动白名单,纯工具按 `ownerActivityId` 私有作用域;
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
/**
|
||||
* 工具总线的声明面 —— **Agent 能调什么由声明定死**,不由它临场想(domain 测试零 mock)。
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { compileToolBus, HUMAN_TOOL, LLM_TOOLS } from '../internal/domain/tool-bus.ts';
|
||||
import type { CatalogEntry } from '../internal/domain/tool-bus.ts';
|
||||
|
||||
const entry = (over: Partial<CatalogEntry> & { name: string }): CatalogEntry => ({
|
||||
description: '一件工具',
|
||||
input: { type: 'object', properties: { pn: { type: 'string' } } },
|
||||
effect: 'read',
|
||||
...over,
|
||||
});
|
||||
|
||||
const catalog = new Map<string, CatalogEntry>([
|
||||
['crm.history-price-read', entry({ name: 'crm.history-price-read' })],
|
||||
['mail.send', entry({ name: 'mail.send', effect: 'write' })],
|
||||
['old.tool', entry({ name: 'old.tool', enabled: false })],
|
||||
]);
|
||||
|
||||
describe('compileToolBus —— 声明 × 目录', () => {
|
||||
it('只给声明过的功能工具;效应原样带出(写类下游不当场落地)', () => {
|
||||
const report = compileToolBus({
|
||||
declaredTools: ['crm.history-price-read', 'mail.send'],
|
||||
catalog,
|
||||
declaredModels: [],
|
||||
});
|
||||
const fn = report.tools.filter((t) => t.kind === 'function');
|
||||
expect(fn.map((t) => `${t.id}:${t.effect}`)).toEqual(['crm.history-price-read:read', 'mail.send:write']);
|
||||
expect(report.missing).toEqual([]);
|
||||
});
|
||||
|
||||
it('没声明的工具不在总线上 —— 白名单之外结构上调不到', () => {
|
||||
const report = compileToolBus({ declaredTools: ['crm.history-price-read'], catalog, declaredModels: [] });
|
||||
expect(report.tools.some((t) => t.id === 'mail.send')).toBe(false);
|
||||
});
|
||||
|
||||
it('声明了却查无此工具 / 已停用:如实报,不静默给一个空壳', () => {
|
||||
const report = compileToolBus({
|
||||
declaredTools: ['crm.history-price-read', 'ghost.tool', 'old.tool'],
|
||||
catalog,
|
||||
declaredModels: [],
|
||||
});
|
||||
expect(report.missing).toEqual(['ghost.tool']);
|
||||
expect(report.disabled).toEqual(['old.tool']);
|
||||
expect(report.tools.some((t) => t.id === 'ghost.tool' || t.id === 'old.tool')).toBe(false);
|
||||
});
|
||||
|
||||
/* 人类工具是 Harness 给的能力,不是活动自带的本事 —— 每个活动天然可以调人 */
|
||||
it('人类工具恒在:一件工具都没声明也能调人', () => {
|
||||
const report = compileToolBus({ declaredTools: [], catalog, declaredModels: [] });
|
||||
expect(report.tools).toHaveLength(1);
|
||||
expect(report.tools[0]).toEqual(HUMAN_TOOL);
|
||||
expect(report.tools[0]!.kind).toBe('human');
|
||||
});
|
||||
|
||||
/* 没声明模型的活动突然会「问模型」= 越权,且用量无从归因 */
|
||||
it('LLM 五件只在活动声明了模型用途名时才上总线', () => {
|
||||
const without = compileToolBus({ declaredTools: [], catalog, declaredModels: [] });
|
||||
expect(without.tools.filter((t) => t.kind === 'llm')).toHaveLength(0);
|
||||
|
||||
const with_ = compileToolBus({ declaredTools: [], catalog, declaredModels: ['quote-extractor'] });
|
||||
expect(with_.tools.filter((t) => t.kind === 'llm').map((t) => t.id)).toEqual(LLM_TOOLS.map((t) => t.id));
|
||||
expect(with_.tools.filter((t) => t.kind === 'llm')).toHaveLength(5);
|
||||
});
|
||||
|
||||
it('LLM 五件都是读类、都有入参契约 —— 模型照它填参', () => {
|
||||
for (const tool of LLM_TOOLS) {
|
||||
expect(tool.effect).toBe('read');
|
||||
expect(tool.input['type']).toBe('object');
|
||||
expect(Array.isArray(tool.input['required'])).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -43,6 +43,9 @@ export type { ToolboxServiceDeps } from './internal/usecase/toolbox-service.ts';
|
||||
export { createToolboxService } from './internal/usecase/toolbox-service.ts';
|
||||
|
||||
export { checkEvolution, dispositionOf, EFFECT_LEVEL_LABEL, EFFECT_LEVELS } from './internal/domain/tool-contract.ts';
|
||||
/* 工具总线的声明面(纯逻辑):声明 × 目录 → 一张清单;人类工具与 LLM 五件系统内化 */
|
||||
export type { BusTool, CatalogEntry, ToolBusInput, ToolBusReport } from './internal/domain/tool-bus.ts';
|
||||
export { compileToolBus, HUMAN_TOOL, LLM_TOOLS } from './internal/domain/tool-bus.ts';
|
||||
export { auditPassed, staticAudit } from './internal/domain/registration-audit.ts';
|
||||
|
||||
export type { ToolHandler } from './internal/adapter/toolbox-store.ts';
|
||||
|
||||
@@ -0,0 +1,213 @@
|
||||
/**
|
||||
* 工具总线的**声明面** —— 纯逻辑,零 IO、零框架(编码规范 §5.3 / §6.2)。
|
||||
*
|
||||
* 「Agent 调用工具都是声明式的」:一个活动**能调什么**,不由 Agent 临场想、也不由
|
||||
* 活动代码自己决定 —— 由活动清单的 `declarations` 与工具目录在**编译期**定死。
|
||||
* 这里就是那次编译:声明 × 目录 → 一张总线清单(`BusTool[]`),
|
||||
* 清单之外的调用在结构上不可能发生(白名单在 `ToolInvoker` 再把一次关)。
|
||||
*
|
||||
* 三路工具,同一张清单、同一套形状:
|
||||
* · `function` —— 功能工具:第一方 / 外部,经**工具调用一缝**(录制回放、白名单、
|
||||
* 写类先登记意向,放行时才落地);
|
||||
* · `human` —— **人类工具**(系统内化,零声明即得):调人 = 发工单 + 立监听听人。
|
||||
* 它是三型行动里的「调人」,不是外部工具,不需要注册也不进白名单;
|
||||
* · `llm` —— **LLM 工具**(系统内化,五件通用):抽取 / 归类 / 摘要 / 裁断 / 改写,
|
||||
* 经**模型网关一缝**(录制回放、四元绑定)。活动只声明用途名,不见厂商型号。
|
||||
*
|
||||
* 装配成具体可调用对象(Mastra `createTool`)是 app 层的事 —— 这里只出清单。
|
||||
*/
|
||||
|
||||
/** 总线上的一件工具:形状与三路无关,调用路由靠 `kind` */
|
||||
export type BusTool = {
|
||||
readonly id: string;
|
||||
readonly description: string;
|
||||
/** 入参契约(JSON Schema)—— 装配层据此生成 zod,模型据此填参 */
|
||||
readonly input: Record<string, unknown>;
|
||||
readonly output?: Record<string, unknown>;
|
||||
readonly kind: 'function' | 'human' | 'llm';
|
||||
/**
|
||||
* 效应:`read` 当场调当场回;`write` **不当场落地** ——
|
||||
* 过程中只登记动作意向,放行那一刻才由系统执行(OS 06「过程不落地」)。
|
||||
*/
|
||||
readonly effect: 'read' | 'write';
|
||||
};
|
||||
|
||||
/** 目录里的一条工具契约(取自 toolbox,只用得上这几个字段) */
|
||||
export type CatalogEntry = {
|
||||
readonly name: string;
|
||||
readonly description: string;
|
||||
readonly input: Record<string, unknown>;
|
||||
readonly output?: Record<string, unknown>;
|
||||
readonly effect: 'read' | 'write';
|
||||
readonly enabled?: boolean;
|
||||
};
|
||||
|
||||
/**
|
||||
* **人类工具**(系统内化):调人。
|
||||
*
|
||||
* 「AI 对世界只有触达与等待两种姿势」—— 调人属于等待:发一张工单到负责人工位,
|
||||
* 立一条监听听他的回传,本拍就此挂起。它不进工具目录、不需要白名单:
|
||||
* 每个活动天然可以调人,这是 Harness 给的能力,不是活动自带的本事。
|
||||
*/
|
||||
export const HUMAN_TOOL: BusTool = {
|
||||
id: 'human.ask',
|
||||
description: '调人:把一件事交到负责人工位上问他(发工单 + 立监听),本回合就此等待回传',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['title', 'ask'],
|
||||
properties: {
|
||||
title: { type: 'string', description: '工单标题:一句话说清要他做什么' },
|
||||
ask: { type: 'string', description: '问题正文:要他答什么、依据什么答' },
|
||||
basis: {
|
||||
type: 'array',
|
||||
description: '依据快照:给他看的事实(键值对),不要让人自己去翻',
|
||||
items: { type: 'object', properties: { k: { type: 'string' }, v: { type: 'string' } } },
|
||||
},
|
||||
fields: { type: 'array', description: '要他填的字段名', items: { type: 'string' } },
|
||||
},
|
||||
},
|
||||
output: {
|
||||
type: 'object',
|
||||
properties: { asked: { type: 'boolean' }, cardId: { type: 'string' } },
|
||||
},
|
||||
kind: 'human',
|
||||
effect: 'read',
|
||||
};
|
||||
|
||||
/**
|
||||
* **LLM 工具**(系统内化,五件通用):大模型驱动的通用能力,不是「一个模型实例」。
|
||||
*
|
||||
* 每件都是**有契约的工具**:入参出参定死、经模型网关一缝(录制回放可重放)、
|
||||
* 用量计入任务预算。活动声明模型用途名(`declarations.models`),换档只改绑定。
|
||||
* 五件之外要更专的能力,写成功能工具进目录 —— 不在这儿加。
|
||||
*/
|
||||
export const LLM_TOOLS: readonly BusTool[] = [
|
||||
{
|
||||
id: 'llm.extract',
|
||||
description: '抽取:从自由文本里按给定字段抽出结构化事实(抽不到的字段留空,不编)',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['text', 'fields'],
|
||||
properties: {
|
||||
text: { type: 'string', description: '原文' },
|
||||
fields: { type: 'array', items: { type: 'string' }, description: '要抽的字段名' },
|
||||
hint: { type: 'string', description: '可选:字段含义与格式提示' },
|
||||
},
|
||||
},
|
||||
output: { type: 'object', properties: { values: { type: 'object' } } },
|
||||
kind: 'llm',
|
||||
effect: 'read',
|
||||
},
|
||||
{
|
||||
id: 'llm.classify',
|
||||
description: '归类:把一段内容判进给定类目之一(类目必须穷举,判不了就回 unknown)',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['text', 'labels'],
|
||||
properties: {
|
||||
text: { type: 'string' },
|
||||
labels: { type: 'array', items: { type: 'string' }, description: '候选类目(穷举)' },
|
||||
hint: { type: 'string' },
|
||||
},
|
||||
},
|
||||
output: { type: 'object', properties: { label: { type: 'string' }, rationale: { type: 'string' } } },
|
||||
kind: 'llm',
|
||||
effect: 'read',
|
||||
},
|
||||
{
|
||||
id: 'llm.summarize',
|
||||
description: '摘要:把长文压成要点(叙述是视图不是事实 —— 结论不入事实库)',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['text'],
|
||||
properties: { text: { type: 'string' }, maxWords: { type: 'integer' }, focus: { type: 'string' } },
|
||||
},
|
||||
output: { type: 'object', properties: { summary: { type: 'string' } } },
|
||||
kind: 'llm',
|
||||
effect: 'read',
|
||||
},
|
||||
{
|
||||
id: 'llm.judge',
|
||||
description: '裁断:对一个语义性判据给出是/否与理由(**只作参考**,不得代替人的放行裁决)',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['question', 'basis'],
|
||||
properties: {
|
||||
question: { type: 'string', description: '要判的问题(是非题)' },
|
||||
basis: { type: 'string', description: '判据材料' },
|
||||
},
|
||||
},
|
||||
output: {
|
||||
type: 'object',
|
||||
properties: { verdict: { type: 'boolean' }, confidence: { type: 'number' }, rationale: { type: 'string' } },
|
||||
},
|
||||
kind: 'llm',
|
||||
effect: 'read',
|
||||
},
|
||||
{
|
||||
id: 'llm.rewrite',
|
||||
description: '改写:按语气/格式要求重写一段文字(只改表达,不添事实)',
|
||||
input: {
|
||||
type: 'object',
|
||||
required: ['text', 'instruction'],
|
||||
properties: { text: { type: 'string' }, instruction: { type: 'string' } },
|
||||
},
|
||||
output: { type: 'object', properties: { text: { type: 'string' } } },
|
||||
kind: 'llm',
|
||||
effect: 'read',
|
||||
},
|
||||
];
|
||||
|
||||
export type ToolBusInput = {
|
||||
/** 活动清单声明的功能工具白名单(`declarations.tools[].name`) */
|
||||
readonly declaredTools: readonly string[];
|
||||
/** 工具目录:名 → 契约 */
|
||||
readonly catalog: ReadonlyMap<string, CatalogEntry>;
|
||||
/** 活动声明了模型用途名才给 LLM 工具 —— 没声明模型的活动不该会「问模型」 */
|
||||
readonly declaredModels: readonly string[];
|
||||
};
|
||||
|
||||
export type ToolBusReport = {
|
||||
readonly tools: readonly BusTool[];
|
||||
/** 声明了却在目录里查无此工具 / 已停用 —— 如实报,不静默吞 */
|
||||
readonly missing: readonly string[];
|
||||
readonly disabled: readonly string[];
|
||||
};
|
||||
|
||||
/**
|
||||
* 编译总线清单:**声明是唯一入口**。
|
||||
*
|
||||
* 功能工具按活动白名单逐条查目录(查不到 / 已停用如实报,不给它);
|
||||
* 人类工具恒在(Harness 给的能力);LLM 五件仅当活动声明了模型用途名才给 ——
|
||||
* 一个没声明模型的活动突然会「问模型」,那是越权,也让用量无从归因。
|
||||
*/
|
||||
export function compileToolBus(input: ToolBusInput): ToolBusReport {
|
||||
const tools: BusTool[] = [];
|
||||
const missing: string[] = [];
|
||||
const disabled: string[] = [];
|
||||
|
||||
for (const name of input.declaredTools) {
|
||||
const entry = input.catalog.get(name);
|
||||
if (entry === undefined) {
|
||||
missing.push(name);
|
||||
continue;
|
||||
}
|
||||
if (entry.enabled === false) {
|
||||
disabled.push(name);
|
||||
continue;
|
||||
}
|
||||
tools.push({
|
||||
id: entry.name,
|
||||
description: entry.description,
|
||||
input: entry.input,
|
||||
...(entry.output === undefined ? {} : { output: entry.output }),
|
||||
kind: 'function',
|
||||
effect: entry.effect,
|
||||
});
|
||||
}
|
||||
|
||||
tools.push(HUMAN_TOOL);
|
||||
if (input.declaredModels.length > 0) tools.push(...LLM_TOOLS);
|
||||
|
||||
return { tools, missing, disabled };
|
||||
}
|
||||
Reference in New Issue
Block a user