AgentCatalogPorts

KIT · interface · 类型合同

Ports the catalog reads from the App's registries.

导入

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/kits/domains').AgentCatalogPorts} AgentCatalogPorts */

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

定义

interface AgentCatalogPorts<App, Id, Intent, Scope>

泛型参数

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

字段结构

字段	类型	必需	说明
goalIds	(app: App) => readonly Id[]	必需	All registered Tool ids, before availability filtering.
goals	(ids?: readonly Id[]) => readonly Intent[]	必需	Registered domain Tools, optionally narrowed to ids.
scopes	(ids?: readonly Id[]) => 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): readonly DescribedTool[]; }	必需	只读。见类型定义及调用场景。

成员目录

成员	用途
goalIds	All registered Tool ids, before availability filtering.
goals	Registered domain Tools, optionally narrowed to ids.
scopes	Registered scopes for the given Tool ids (all scopes when omitted).
currentTask	Task accepted for this request, if any.

成员详情

goalIds

All registered Tool ids, before availability filtering.

AgentCatalogPorts.goalIds(app: App): readonly Id[]

All registered Tool ids, before availability filtering.

参数	类型	传递	说明
app	App	必需	—

返回： readonly Id[]。

goals

Registered domain Tools, optionally narrowed to ids.

AgentCatalogPorts.goals(ids?: readonly Id[]): readonly Intent[]

Registered domain Tools, optionally narrowed to ids.

参数	类型	传递	说明
ids	readonly Id[] | undefined	可省略	—

返回： readonly Intent[]。

scopes

Registered scopes for the given Tool ids (all scopes when omitted).

AgentCatalogPorts.scopes(ids?: readonly Id[]): readonly Scope[]

Registered scopes for the given Tool ids (all scopes when omitted).

参数	类型	传递	说明
ids	readonly Id[] | undefined	可省略	—

返回： readonly Scope[]。

currentTask

Task accepted for this request, if any.

AgentCatalogPorts.currentTask(app: App): CatalogTask<Id> | undefined

Task accepted for this request, if any.

参数	类型	传递	说明
app	App	必需	—

返回： CatalogTask<Id> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
goalId	Id	必需	只读。见类型定义及调用场景。
scopeId	string | null | undefined	可省略	只读。Selected scope; null or undefined means a scope has not been chosen yet.

使用示例

• 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' } }));

相关策略源码

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

相关定义

• CatalogGoal
• CatalogScope
• CatalogTask
• CatalogTool
• DescribedTool