Agent Catalog：从真实注册结果生成 Tool 菜单

Tool、范围和工具菜单由真实目录投影，不单独维护一份提示词 Tool 清单。

defineAgentCatalog 接受结构化端口。goalIds/goals/scopes 从真实注册结果读取；tools 提供 values、has、supportsGoal、describe；currentTask 返回本次已接受任务 { goalId, scopeId } 或 undefined。

modelCatalog(app) 返回 availableGoalIds、availableGoals、availableScopes、availableTools。默认 restrictToTask=true，任务接受后限制到该 Tool 及范围；配置 false 才保留完整菜单。goalDelegates 汇总 Tool delegates 与工具 invocation.id。运行时可用条件仍由 App 端口确定，菜单不代替执行授权。

由简到繁的同业务示例

把已有 Tool 与范围投影成模型菜单

入门 · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'] }]);
const catalog = defineAgentCatalog({
  goalIds: () => tools.ids(), goals: ids => tools.describe(ids), scopes: ids => scopes.describe(ids), currentTask: () => undefined,
  tools: { values: () => [], has: () => false, supportsGoal: () => true, describe: () => [] },
});
console.log(catalog.modelCatalog(undefined));

JavaScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'] }]);
const catalog = defineAgentCatalog({
    goalIds: () => tools.ids(), goals: ids => tools.describe(ids), scopes: ids => scopes.describe(ids), currentTask: () => undefined,
    tools: { values: () => [], has: () => false, supportsGoal: () => true, describe: () => [] },
});
console.log(catalog.modelCatalog(undefined));

相同菜单接上实际工具声明和当前任务

配置 · Node.js

此例的 tools 是一个结构化投影端口；实际应用应直接连接真实工具注册器的对应方法，避免平行维护。

TypeScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const goals = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'], toolIds: ['read-source'] }]);
const tools = [{ id: 'read-source', kind: 'read', description: '读取允许的说明资料', audience: 'model', effect: 'read', goalIds: ['explain'], lifecycle: { id: 'read' } }];
type App = { current?: { goalId: string; scopeId: string } };
const catalog = defineAgentCatalog<App, string, ReturnType<typeof goals.describe>[number], ReturnType<typeof scopes.describe>[number]>({
  goalIds: () => goals.ids(), goals: ids => goals.describe(ids), scopes: ids => scopes.describe(ids), currentTask: app => app.current,
  tools: { values: () => tools, has: id => tools.some(tool => tool.id === id), supportsGoal: () => true, describe: audience => tools.filter(tool => !audience || tool.audience === audience) },
});
console.log(catalog.modelCatalog({ current: { goalId: 'explain', scopeId: 'sdk' } }));

JavaScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const goals = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'], toolIds: ['read-source'] }]);
const tools = [{ id: 'read-source', kind: 'read', description: '读取允许的说明资料', audience: 'model', effect: 'read', goalIds: ['explain'], lifecycle: { id: 'read' } }];
const catalog = defineAgentCatalog({
    goalIds: () => goals.ids(), goals: ids => goals.describe(ids), scopes: ids => scopes.describe(ids), currentTask: app => app.current,
    tools: { values: () => tools, has: id => tools.some(tool => tool.id === id), supportsGoal: () => true, describe: audience => tools.filter(tool => !audience || tool.audience === audience) },
});
console.log(catalog.modelCatalog({ current: { goalId: 'explain', scopeId: 'sdk' } }));

策略与实现

• 从真实目录生成任务范围内的菜单