defineAgentCatalog

KIT · function · 运行时值

Compile a catalog projection over the App's live registries.

The actual registries determine availability and relationships. No parallel capability list exists: goalIds filters by tool support, modelCatalog narrows to the currently accepted task when restrictToTask is enabled, and scope tool ids are filtered to tools that exist.

导入

TypeScript

import { defineAgentCatalog } from '@jangts/agent-core/kits/domains';

JavaScript

import { defineAgentCatalog } from '@jangts/agent-core/kits/domains';

其他公开入口：@jangts/agent-core、@jangts/agent-core/types、@jangts/agent-core/kits/domains、@jangts/agent-core/kits。

定义

泛型参数

类型参数	约束	默认类型
App	—	—
Id	string	—
Goal	CatalogGoal<Id>	—
Scope	CatalogScope	—

调用

defineAgentCatalog<App, Id extends string, Goal extends CatalogGoal<Id>, Scope extends CatalogScope>(ports: AgentCatalogPorts<App, Id, Goal, Scope>): Readonly<{ goalIds: (app: App) => Id[]; goalDelegates: (app?: App) => Map<Id, string[]>; goalCatalog: (app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; scopeCatalog: (app: App) => (Scope & { toolIds: string[]; })[]; modelCatalog(app: App): { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }; }>

Compile a catalog projection over the App's live registries.

The actual registries determine availability and relationships. No parallel capability list exists: goalIds filters by tool support, modelCatalog narrows to the currently accepted task when restrictToTask is enabled, and scope tool ids are filtered to tools that exist.

类型参数	约束	默认类型
App	—	—
Id	string	—
Goal	CatalogGoal<Id>	—
Scope	CatalogScope	—

参数	类型	传递	说明
ports	AgentCatalogPorts<App, Id, Goal, Scope>	必需	—

ports 的字段

字段	类型	必需	说明
goalIds	(app: App) => readonly Id[]	必需	All registered Tool ids, before availability filtering.
goals	(ids?: readonly Id[] | undefined) => readonly Goal[]	必需	Registered domain Tools, optionally narrowed to ids.
scopes	(ids?: readonly Id[] | undefined) => readonly Scope[]	必需	Registered scopes for the given Tool ids (all scopes when omitted).
restrictToTask	boolean | undefined	可省略	只读。When not false, the catalog is narrowed to currentTask; defaults to restriction on.
currentTask	(app: App) => CatalogTask<Id> | undefined	必需	Task accepted for this request, if any.
tools	{ values(): Iterable<CatalogTool<App>>; has(id: string): boolean; supportsGoal(id: Id, app: App): boolean; describe(audience?: string, app?: App | undefined): readonly DescribedTool[]; }	必需	只读。见类型定义及调用场景。

返回： Readonly<{ goalIds: (app: App) => Id[]; goalDelegates: (app?: App) => Map<Id, string[]>; goalCatalog: (app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" \| "inputSchema" \| "active" \| "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string \| undefined; })[]; scopeCatalog: (app: App) => (Scope & { toolIds: string[]; })[]; modelCatalog(app: App): { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" \| "inputSchema" \| "active" \| "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string \| undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }; }>。

返回值结构

字段	类型	必需	说明
goalIds	(app: App) => Id[]	必需	见类型定义及调用场景。
goalDelegates	(app?: App) => Map<Id, string[]>	必需	见类型定义及调用场景。
goalCatalog	(app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]	必需	见类型定义及调用场景。
scopeCatalog	(app: App) => (Scope & { toolIds: string[]; })[]	必需	见类型定义及调用场景。
modelCatalog	(app: App) => { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }	必需	见类型定义及调用场景。

使用示例

• Agent Catalog：从真实注册结果生成 Tool 菜单：Tool、范围和工具菜单由真实目录投影，不单独维护一份提示词 Tool 清单。

把已有 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' } }));

相关策略源码

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

相关定义

• AgentCatalogPorts
• CatalogGoal
• CatalogScope