ArtifactResolver

KIT · interface · 类型合同

App-registered resolver that turns a reference into an App value.

导入

TypeScript

import type { ArtifactResolver } from '@jangts/agent-core/kits/artifacts';

JavaScript

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

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

定义

interface ArtifactResolver<Value, App>

泛型参数

类型参数	约束	默认类型
Value	—	—
App	—	—

字段结构

字段	类型	必需	说明
id	string	必需	只读。见类型定义及调用场景。
resolve	(reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>	必需	Resolves the reference; throws when the artifact is unknown or not accessible.

成员目录

成员	用途
resolve	Resolves the reference; throws when the artifact is unknown or not accessible.

成员详情

resolve

Resolves the reference; throws when the artifact is unknown or not accessible.

ArtifactResolver.resolve(reference: ArtifactReference, context: OperationContext<App>): MaybePromise<Value>

Resolves the reference; throws when the artifact is unknown or not accessible.

参数	类型	传递	说明
reference	ArtifactReference	必需	—
context	OperationContext<App>	必需	—

reference 的字段

字段	类型	必需	说明
resolverId	string	必需	只读。Resolver that owns the artifact namespace.
artifactId	string	必需	只读。Artifact identity inside that namespace; never blank.
revision	string | undefined	可省略	只读。Optional pinned revision; omission asks the resolver for its current revision.

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： MaybePromise<Value>。

等待后的值： Awaited<Value>。

使用示例

• Artifacts：按引用解析真实产物：引用只包含 resolverId、artifactId 和可选 revision，真实内容由 App 的解析器提供。

先解析一个明确的内存产物

入门 · Node.js

TypeScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const content = new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]);
const artifacts = Artifacts.defineArtifactCatalog([
  { id: 'document', resolve(reference) { const value = content.get(reference.artifactId); if (!value) throw new Error('产物不存在'); return value; } },
]);
const result = await artifacts.resolve({ resolverId: 'document', artifactId: 'manual' }, { app: {}, signal: new AbortController().signal });
console.log(result.text);

JavaScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const content = new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]);
const artifacts = Artifacts.defineArtifactCatalog([
    { id: 'document', resolve(reference) { const value = content.get(reference.artifactId); if (!value)
            throw new Error('产物不存在'); return value; } },
]);
const result = await artifacts.resolve({ resolverId: 'document', artifactId: 'manual' }, { app: {}, signal: new AbortController().signal });
console.log(result.text);

相同 resolve 增加真实权限与版本核对

配置 · Node.js

TypeScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
type Value = { text: string; revision: string };
type App = { canRead: boolean; documents: Map<string, Value> };
const artifacts = Artifacts.defineArtifactCatalog<Value, App>([
  { id: 'document', async resolve(reference, { app, signal }) {
    signal.throwIfAborted();
    if (!app.canRead) throw new Error('没有产物读取权限');
    const value = app.documents.get(reference.artifactId);
    if (!value) throw new Error('产物不存在或已到期');
    if (reference.revision && reference.revision !== value.revision) throw new Error('产物版本已变化');
    return structuredClone(value);
  } },
]);
const app = { canRead: true, documents: new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]) };
console.log(await artifacts.resolve({ resolverId: 'document', artifactId: 'manual', revision: '1' }, { app, signal: new AbortController().signal }));

JavaScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const artifacts = Artifacts.defineArtifactCatalog([
    { id: 'document', async resolve(reference, { app, signal }) {
            signal.throwIfAborted();
            if (!app.canRead)
                throw new Error('没有产物读取权限');
            const value = app.documents.get(reference.artifactId);
            if (!value)
                throw new Error('产物不存在或已到期');
            if (reference.revision && reference.revision !== value.revision)
                throw new Error('产物版本已变化');
            return structuredClone(value);
        } },
]);
const app = { canRead: true, documents: new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]) };
console.log(await artifacts.resolve({ resolverId: 'document', artifactId: 'manual', revision: '1' }, { app, signal: new AbortController().signal }));

相关策略源码

• 引用快照、解析器登记和取消

相关定义

• ArtifactReference
• MaybePromise
• OperationContext