Evidence

KIT · constant · 运行时值

导入

TypeScript

import { Evidence } from '@jangts/agent-core/kits/evidence';

JavaScript

import { Evidence } from '@jangts/agent-core/kits/evidence';

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

定义

成员目录

成员	用途
defineEvidenceChecklist	完整输入输出见下方重载。
defineEvidenceProjection	完整输入输出见下方重载。

成员详情

defineEvidenceChecklist

Evidence.defineEvidenceChecklist<Observation, Requirement extends EvidenceRequirement>(definitions: readonly EvidenceProvider<Observation, Requirement>[]): Readonly<{ isSatisfied: (request: { observations: readonly Observation[]; requirement: Requirement; }) => boolean; isComplete: (request: { observations: readonly Observation[]; requirements: readonly Requirement[]; }) => boolean; missing({ observations, requirements, }: { observations: readonly Observation[]; requirements: readonly Requirement[]; }): Requirement[]; }>

Compile a reusable completion checklist over actual observations.

A requirement is satisfied when at least one observation satisfies the provider registered for its kind; isComplete requires every requirement to be satisfied, and missing returns those that are not. Hosts define evidence semantics.

类型参数	约束	默认类型
Observation	—	—
Requirement	EvidenceRequirement	—

参数	类型	传递	说明
definitions	readonly EvidenceProvider<Observation, Requirement>[]	必需	—

返回： Readonly<{ isSatisfied: (request: { observations: readonly Observation[]; requirement: Requirement; }) => boolean; isComplete: (request: { observations: readonly Observation[]; requirements: readonly Requirement[]; }) => boolean; missing({ observations, requirements, }: { observations: readonly Observation[]; requirements: readonly Requirement[]; }): Requirement[]; }>。

返回值结构

字段	类型	必需	说明
isSatisfied	(request: { observations: readonly Observation[]; requirement: Requirement; }) => boolean	必需	见类型定义及调用场景。
isComplete	(request: { observations: readonly Observation[]; requirements: readonly Requirement[]; }) => boolean	必需	见类型定义及调用场景。
missing	({ observations, requirements, }: { observations: readonly Observation[]; requirements: readonly Requirement[]; }) => Requirement[]	必需	见类型定义及调用场景。

defineEvidenceProjection

Evidence.defineEvidenceProjection<Observation, Source>(definition: EvidenceProjectionDefinition<Observation, Source>): Readonly<{ project({ observations, sourceIds, }: { observations: Observation[]; sourceIds?: readonly string[]; }): Observation[]; }>

Compile a projection that keeps only the sources a caller asked to see.

No selection retains the complete evidence; a selection narrows registered source-bearing results. Observations whose tool has no provider pass through untouched, so the projection can only ever remove sources it knows how to name.

类型参数	约束	默认类型
Observation	—	—
Source	—	—

参数	类型	传递	说明
definition	EvidenceProjectionDefinition<Observation, Source>	必需	—

definition 的字段

字段	类型	必需	说明
providers	Readonly<Record<string, EvidenceProjectionProvider<Observation, Source>>>	必需	只读。One provider per tool id; observations without a provider pass through unchanged.
sourceId	(source: Source) => string	必需	只读。Stable citation id for a source.
toolId	((observation: Observation) => string) | undefined	可省略	只读。Selects the tool id of an observation; defaults to its toolId (or legacy tool) field.

返回： Readonly<{ project({ observations, sourceIds, }: { observations: Observation[]; sourceIds?: readonly string[]; }): Observation[]; }>。

返回值结构

字段	类型	必需	说明
project	({ observations, sourceIds, }: { observations: Observation[]; sourceIds?: readonly string[]; }) => Observation[]	必需	见类型定义及调用场景。

使用示例

• Evidence：用真实观察检查完成性：用 App 定义的证据语义检查需求，避免把模型的“完成了”当成真实回执。

检查真实资料是否已读取

入门 · Node.js

TypeScript

import { Evidence } from '@jangts/agent-core/kits/evidence';
type Observation = { sourceId: string; read: boolean };
type Requirement = { id: string; kind: 'source-read'; sourceId: string };
const checklist = Evidence.defineEvidenceChecklist<Observation, Requirement>([
  { kind: 'source-read', description: '资料读取已成功', isSatisfied: (seen, need) => seen.read && seen.sourceId === need.sourceId },
]);
console.log(checklist.isComplete({ observations: [{ sourceId: 'manual', read: true }], requirements: [{ id: 'need-manual', kind: 'source-read', sourceId: 'manual' }] }));

JavaScript

import { Evidence } from '@jangts/agent-core/kits/evidence';
const checklist = Evidence.defineEvidenceChecklist([
    { kind: 'source-read', description: '资料读取已成功', isSatisfied: (seen, need) => seen.read && seen.sourceId === need.sourceId },
]);
console.log(checklist.isComplete({ observations: [{ sourceId: 'manual', read: true }], requirements: [{ id: 'need-manual', kind: 'source-read', sourceId: 'manual' }] }));

相同清单返回缺口，再限定审查所用来源

配置 · Node.js

TypeScript

import { Evidence } from '@jangts/agent-core/kits/evidence';
type Observation = { sourceId: string; read: boolean };
type Requirement = { id: string; kind: 'source-read'; sourceId: string };
const checklist = Evidence.defineEvidenceChecklist<Observation, Requirement>([
  { kind: 'source-read', description: '资料读取已成功', isSatisfied: (seen, need) => seen.read && seen.sourceId === need.sourceId },
]);
console.log(checklist.missing({ observations: [], requirements: [{ id: 'need-manual', kind: 'source-read', sourceId: 'manual' }] }));
type ToolObservation = { toolId: string; sources: { id: string; text: string }[] };
const projection = Evidence.defineEvidenceProjection<ToolObservation, { id: string; text: string }>({
  sourceId: source => source.id,
  providers: { search: { sources: row => row.sources, withSources: (row, sources) => ({ ...row, sources }) } },
});
console.log(projection.project({ observations: [{ toolId: 'search', sources: [{ id: 'manual', text: '使用指南' }, { id: 'faq', text: '常见问题' }] }], sourceIds: ['manual'] }));

JavaScript

import { Evidence } from '@jangts/agent-core/kits/evidence';
const checklist = Evidence.defineEvidenceChecklist([
    { kind: 'source-read', description: '资料读取已成功', isSatisfied: (seen, need) => seen.read && seen.sourceId === need.sourceId },
]);
console.log(checklist.missing({ observations: [], requirements: [{ id: 'need-manual', kind: 'source-read', sourceId: 'manual' }] }));
const projection = Evidence.defineEvidenceProjection({
    sourceId: source => source.id,
    providers: { search: { sources: row => row.sources, withSources: (row, sources) => ({ ...row, sources }) } },
});
console.log(projection.project({ observations: [{ toolId: 'search', sources: [{ id: 'manual', text: '使用指南' }, { id: 'faq', text: '常见问题' }] }], sourceIds: ['manual'] }));

相关策略源码

• 完成性与证据投影规则

相关定义

• defineEvidenceChecklist
• defineEvidenceProjection
• EvidenceProjectionDefinition
• EvidenceProvider