ScopeRegistry

KIT · class · 运行时值

Generic scope relationships; categories, intent policy and extra fields belong to the host.

A scope is addressable by its id or by any of its aliases; aliases resolve to the declaring scope, and a name may be claimed only once across both namespaces.

导入

TypeScript

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

JavaScript

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

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

定义

class ScopeRegistry<Definition>

泛型参数

类型参数	约束	默认类型
Definition	ScopeDefinition	ScopeDefinition

构造函数

new ScopeRegistry<Definition extends ScopeDefinition = ScopeDefinition>(policy?: ScopeRegistryPolicy<Definition>): ScopeRegistry<Definition>

参数	类型	传递	说明
policy	ScopeRegistryPolicy<Definition>	可省略	—

policy 的字段

字段	类型	必需	说明
requireGoals	boolean | undefined	可省略	只读。Require at least one Tool id per scope.
requireSources	boolean | undefined	可省略	只读。Require at least one query scope or knowledge topic per scope.
requireTools	boolean | undefined	可省略	只读。Require at least one tool id per scope.
idPattern	RegExp | undefined	可省略	只读。Pattern every id and alias must match.
categories	readonly string[] | undefined	可省略	只读。Allowed category values; undefined accepts any value.
assertDefinition	((definition: Definition) => void) | undefined	可省略	只读。Extra App assertion, called after the built-in checks; must return void synchronously.
acceptsTool	((definition: Readonly<Definition>, goal: string) => boolean) | undefined	可省略	只读。Replaces the default intent membership test; must return boolean synchronously.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to registration rejections.
errors	{ readonly sealed?: BreakReason; readonly invalid?: BreakReason; } | undefined	可省略	只读。见类型定义及调用场景。

返回： ScopeRegistry<Definition>。

实例属性

字段	类型	必需	说明
definitions	readonly Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>[]	必需	只读。Registered scopes in registration order.

成员目录

成员	用途
create	静态。Create and seal a complete scope catalog in one call.
register	Validate, freeze and add one scope together with its aliases. Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.
registerAll	Register every scope in iteration order.
seal	Finalize the registry; no registration is accepted afterwards.
ids	Registered scope ids in registration order; aliases are not included.
values	Iterate the registered scopes.
entries	Iterate [id, scope] pairs.
require	Registered scope for an id or alias.
normalize	Resolve an alias to its scope id; unknown names are returned unchanged.
get	Registered scope for an id or alias, or undefined for a null/unknown name.
has	Whether the name resolves to a registered scope.
acceptsTool	Whether a scope accepts an intent. The App may override the declared goalIds through acceptsTool; without an override the membership check applies.
acceptsQuery	Whether the scope declares this query scope; a null scope accepts nothing.
is	Whether the scope belongs to the given App category.
queryScopeIds	Every query scope declared by any registered scope, deduplicated.
topics	Knowledge topic ids of one scope; copied so callers cannot mutate the registry.
evidence	Evidence declarations of one scope; copied so callers cannot mutate the registry.
contextTier	Declared context tier of one scope, if any.
describe	Copy the scopes that accept at least one of the given goals.

成员详情

create

静态成员。

Create and seal a complete scope catalog in one call.

ScopeRegistry.create<Definition extends ScopeDefinition>(definitions: Iterable<Definition>, policy?: ScopeRegistryPolicy<Definition>): ScopeRegistry<Definition>

Create and seal a complete catalog; use the constructor for incremental installation.

类型参数	约束	默认类型
Definition	ScopeDefinition	—

参数	类型	传递	说明
definitions	Iterable<Definition>	必需	—
policy	ScopeRegistryPolicy<Definition>	可省略	—

policy 的字段

字段	类型	必需	说明
requireGoals	boolean | undefined	可省略	只读。Require at least one Tool id per scope.
requireSources	boolean | undefined	可省略	只读。Require at least one query scope or knowledge topic per scope.
requireTools	boolean | undefined	可省略	只读。Require at least one tool id per scope.
idPattern	RegExp | undefined	可省略	只读。Pattern every id and alias must match.
categories	readonly string[] | undefined	可省略	只读。Allowed category values; undefined accepts any value.
assertDefinition	((definition: Definition) => void) | undefined	可省略	只读。Extra App assertion, called after the built-in checks; must return void synchronously.
acceptsTool	((definition: Readonly<Definition>, goal: string) => boolean) | undefined	可省略	只读。Replaces the default intent membership test; must return boolean synchronously.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to registration rejections.
errors	{ readonly sealed?: BreakReason; readonly invalid?: BreakReason; } | undefined	可省略	只读。见类型定义及调用场景。

返回： ScopeRegistry<Definition>。

register

实例方法。

Validate, freeze and add one scope together with its aliases.

Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.

register(input: Definition): ScopeRegistry<Definition>

Validate, freeze and add one scope together with its aliases.

Every name is checked for conflicts before any of them is stored, so a rejected scope leaves no partial alias entry behind.

参数	类型	传递	说明
input	Definition	必需	—

返回： ScopeRegistry<Definition>。

registerAll

实例方法。

Register every scope in iteration order.

registerAll(definitions: Iterable<Definition>): ScopeRegistry<Definition>

Register every scope in iteration order.

参数	类型	传递	说明
definitions	Iterable<Definition>	必需	—

返回： ScopeRegistry<Definition>。

seal

实例方法。

Finalize the registry; no registration is accepted afterwards.

seal(): ScopeRegistry<Definition>

Finalize the registry; no registration is accepted afterwards.

无调用参数。

返回： ScopeRegistry<Definition>。

ids

实例方法。

Registered scope ids in registration order; aliases are not included.

ids(): readonly string[]

Registered scope ids in registration order; aliases are not included.

无调用参数。

返回： readonly string[]。

values

实例方法。

Iterate the registered scopes.

values(): MapIterator<Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>>

Iterate the registered scopes.

无调用参数。

返回： MapIterator<Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>>。

entries

实例方法。

Iterate [id, scope] pairs.

entries(): MapIterator<[string, Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>]>

Iterate [id, scope] pairs.

无调用参数。

返回： MapIterator<[string, Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>]>。

require

实例方法。

Registered scope for an id or alias.

require(id: string): Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>

Registered scope for an id or alias.

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }>。

返回值结构

字段	类型	必需	说明
id	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["id"]	必需	Unique scope id, matched against the policy's idPattern when configured.
description	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["description"]	必需	Non-blank description.
category	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["category"]	必需	Scope category; validated against policy.categories when that is set.
contextTier	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["contextTier"] | undefined	可省略	App-declared context tier, passed through for the App's own policy.
evidence	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["evidence"]	必需	见类型定义及调用场景。

normalize

实例方法。

Resolve an alias to its scope id; unknown names are returned unchanged.

normalize(scope: string): string

Resolve an alias to its scope id; unknown names are returned unchanged.

参数	类型	传递	说明
scope	string	必需	—

返回： string。

get

实例方法。

Registered scope for an id or alias, or undefined for a null/unknown name.

get(scope?: string | null): RegisteredScope<Definition> | undefined

Registered scope for an id or alias, or undefined for a null/unknown name.

参数	类型	传递	说明
scope	string | null | undefined	可省略	—

返回： Readonly<Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" \| ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; }> \| undefined。

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

分支 1

undefined

分支 2

字段	类型	必需	说明
id	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["id"]	必需	Unique scope id, matched against the policy's idPattern when configured.
description	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["description"]	必需	Non-blank description.
category	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["category"]	必需	Scope category; validated against policy.categories when that is set.
contextTier	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["contextTier"] | undefined	可省略	App-declared context tier, passed through for the App's own policy.
evidence	(Omit<Readonly<ScopeDefinition & RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ScopeListKey> & RegisteredScopeLists<Definition> & { evidence: ScopeEvidenceList<Definition>; })["evidence"]	必需	见类型定义及调用场景。

has

实例方法。

Whether the name resolves to a registered scope.

has(scope?: string | null): boolean

Whether the name resolves to a registered scope.

参数	类型	传递	说明
scope	string | null | undefined	可省略	—

返回： boolean。

acceptsTool

实例方法。

Whether a scope accepts an intent.

The App may override the declared goalIds through acceptsTool; without an override the membership check applies.

acceptsTool(scope: string, goal: string): boolean

Whether a scope accepts an intent.

The App may override the declared goalIds through acceptsTool; without an override the membership check applies.

参数	类型	传递	说明
scope	string	必需	—
goal	string	必需	—

返回： boolean。

acceptsQuery

实例方法。

Whether the scope declares this query scope; a null scope accepts nothing.

acceptsQuery(scope: string | null, queryScope: string): boolean

Whether the scope declares this query scope; a null scope accepts nothing.

参数	类型	传递	说明
scope	string | null	必需	—
queryScope	string	必需	—

返回： boolean。

is

实例方法。

Whether the scope belongs to the given App category.

is(scope: string | null | undefined, category: Definition["category"]): boolean

Whether the scope belongs to the given App category.

参数	类型	传递	说明
scope	string | null | undefined	必需	—
category	Definition["category"]	必需	—

返回： boolean。

queryScopeIds

实例方法。

Every query scope declared by any registered scope, deduplicated.

queryScopeIds(): string[]

Every query scope declared by any registered scope, deduplicated.

无调用参数。

返回： string[]。

topics

实例方法。

Knowledge topic ids of one scope; copied so callers cannot mutate the registry.

topics(scope?: string | null): string[]

Knowledge topic ids of one scope; copied so callers cannot mutate the registry.

参数	类型	传递	说明
scope	string | null | undefined	可省略	—

返回： string[]。

evidence

实例方法。

Evidence declarations of one scope; copied so callers cannot mutate the registry.

evidence(scope?: string | null): RegisteredScopeEvidence<Definition>[]

Evidence declarations of one scope; copied so callers cannot mutate the registry.

参数	类型	传递	说明
scope	string | null | undefined	可省略	—

返回： Readonly<RegistrationData<NonNullable<Definition["evidence"]>[number]>>[]。

contextTier

实例方法。

Declared context tier of one scope, if any.

contextTier(scope?: string | null): Definition["contextTier"] | undefined

Declared context tier of one scope, if any.

参数	类型	传递	说明
scope	string | null | undefined	可省略	—

返回： Definition["contextTier"] \| undefined。

describe

实例方法。

Copy the scopes that accept at least one of the given goals.

describe(goals?: readonly string[]): ScopeDescription<Definition>[]

Copy the scopes that accept at least one of the given goals.

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

返回： ScopeDescription<Definition>[]。

使用示例

• Domain Tools：Tool 声明与范围关系：同一清单提供可用 Tool、允许 delegate、范围别名、来源和工具关系。

先登记一个接口说明 Tool

入门 · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([
  { id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: true },
]);
console.log(tools.ids(), tools.allows('explain', 'read'));
const scopes = ScopeRegistry.create([
  { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge' },
]);
console.log(scopes.require('sdk').knowledgeTopicIds);

JavaScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([
    { id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: true },
]);
console.log(tools.ids(), tools.allows('explain', 'read'));
const scopes = ScopeRegistry.create([
    { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge' },
]);
console.log(scopes.require('sdk').knowledgeTopicIds);

增加约束和范围关联，查询入口保持一致

配置 · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = new IntentRegistry({ idPattern: /^[a-z-]+$/, delegates: ['read', 'reply'] })
  .registerAll([{ id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: '用户希望了解 SDK 接口或用法。' }]).seal();
const scopes = ScopeRegistry.create([
  { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge', aliases: ['agent-core'], goalIds: ['explain'], knowledgeTopicIds: ['manual'], toolIds: ['read-source'] },
], { categories: ['knowledge'], requireGoals: true, requireSources: true });
console.log(tools.describe(), scopes.normalize('agent-core'));
console.log(scopes.acceptsTool('agent-core', 'explain'), scopes.topics('sdk'));

JavaScript

import { IntentRegistry, ScopeRegistry } from '@jangts/agent-core/kits/domains';
const tools = new IntentRegistry({ idPattern: /^[a-z-]+$/, delegates: ['read', 'reply'] })
    .registerAll([{ id: 'explain', description: '根据资料解释 SDK', delegates: ['read', 'reply'], asIntent: '用户希望了解 SDK 接口或用法。' }]).seal();
const scopes = ScopeRegistry.create([
    { id: 'sdk', description: 'SDK 说明资料', category: 'knowledge', aliases: ['agent-core'], goalIds: ['explain'], knowledgeTopicIds: ['manual'], toolIds: ['read-source'] },
], { categories: ['knowledge'], requireGoals: true, requireSources: true });
console.log(tools.describe(), scopes.normalize('agent-core'));
console.log(scopes.acceptsTool('agent-core', 'explain'), scopes.topics('sdk'));

相关策略源码

• Tool 校验与封存
• 范围关系与别名

相关定义

• createScopeRegistry
• RegisteredScope
• RegisteredScopeEvidence
• ScopeDefinition
• ScopeDescription
• ScopeRegistryPolicy