Tools：App 工具生命周期与内容贡献
对已有复杂 App 工具统一登记工具调用、输出规则、上下文贡献和交付处理。
Tools 是 ToolLifecycleRegistry 的别名，面向拥有 delegate、GoalTool、展示及交付阶段的 App。只需执行普通工具时，可直接使用 Core ToolRegistry；此 Kit 不要求每个 Agent 配置这一整套生命周期。
构造时配置 registration、invocationId、outputs、goalIds、contextFragment 和可选调用端口；批量 registerAll 后 seal。invoke 返回统一 ToolResult；call(next,context) 通过已登记 invocation 同步执行。可选 contribution 提供 inspect、rules、modelFields、visibleText、reviewDraft、recoveryContext、composition、finalize 等局部行为。调用和最终提交仍应经过 App 编排中的实际授权。
rules 按 order 排序，composition 最多一个贡献者拥有本次模板。normalizer/finalizer 各只允许登记一次。copyTo 复制已编译声明，不能绕过目标注册策略；运行时服务依赖仍由原实现拥有。该 Kit 的阶段、GoalTool 和上下文字段不是 Core 的必需合同。
由简到繁的同业务示例
为已有 App 登记一个只读工具
入门 · Node.js
ts
import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));js
import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));同一注册方式增加 App 规则和展示贡献
配置 · Node.js
active 影响真实工具可用性及描述；业务授权仍必须在实际调用边界核对服务端身份。
ts
import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
}]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));js
import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
}]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));