Policy

KIT · interface · 类型合同

Registration policy shared by every tool in the registry.

导入

TypeScript

import type { Policy } from '@jangts/agent-core/kits/tools';

JavaScript

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

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

定义

interface Policy<Tool>

泛型参数

类型参数	约束	默认类型
Tool	—	—

字段结构

字段	类型	必需	说明
kinds	readonly string[]	必需	只读。Accepted values of a tool's kind.
isValidId	(tool: Tool) => boolean	必需	只读。Identity and shape predicate; must be synchronous boolean.
audiences	readonly string[]	必需	只读。Accepted audience values.
effects	readonly string[]	必需	只读。Accepted effect values.
goalExists	(goal: string) => boolean	必需	只读。Reports whether a goal id exists, for validating goalIds references.
protocolVersion	number | undefined	可省略	只读。When set, every lifecycle protocol must declare this version.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to registration rejections.
invalidTool	BreakReason | undefined	可省略	只读。Rejection wording for an invalid tool definition.
invalidInvocation	BreakReason | undefined	可省略	只读。Rejection wording for an invalid or duplicate invocation id.

成员目录

成员	用途
isValidId	Identity and shape predicate; must be synchronous boolean.
goalExists	Reports whether a goal id exists, for validating goalIds references.

成员详情

isValidId

Identity and shape predicate; must be synchronous boolean.

Policy.isValidId(tool: Tool): boolean

参数	类型	传递	说明
tool	Tool	必需	—

返回： boolean。

goalExists

Reports whether a goal id exists, for validating goalIds references.

Policy.goalExists(goal: string): boolean

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

返回： boolean。

使用示例

• Tools：App 工具生命周期与内容贡献：对已有复杂 App 工具统一登记工具调用、输出规则、上下文贡献和交付处理。

为已有 App 登记一个只读工具

入门 · Node.js

TypeScript

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

JavaScript

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 影响真实工具可用性及描述；业务授权仍必须在实际调用边界核对服务端身份。

TypeScript

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

JavaScript

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

相关策略源码

• 注册策略、生命周期绑定和内容投影

相关定义

• BreakReason