其余可选 Kit

共同类型 · 返回首页。每个 Kit 从自己的子路径导入具名函数／构造器，静态声明与每次运行上下文分离。

Domain Tools、Scope、Interaction、Tools

IntentRegistry 注册继承 ModelTool 的 IntentTool，保留 scopePolicy、targetPolicy 和任务约束。asIntent.delegates 可覆盖推导结果；delegates 是可选允许集合，不是顺序。不存在独立 Intent 实体或 Intent ID；Scope 的 goalIds 引用真实 Tool ID。可选注册辅助从 @jangts/agent-core/kits/domains 导入。

能力	首选接口／关键合同
IntentRegistry	定义主键 id，使用 scopePolicy/targetPolicy，实现共同 Registry 合同
ScopeRegistry	id、goalIds、toolIds、queryScopeIds、knowledgeTopicIds；aliases保留，查询方法使用scopeId
defineAgentCatalog	由实际登记投影关系；当前任务为{ goalId, scopeId? }，不能同时用scope指策略和引用
defineInteractionProtocol	一份commands声明编译协议，commandField由App拥有，不强制其wire字段叫type或kind
defineCommandCatalog	commands闭集可用Record书写；公开definitions为数组，toRecord()为明确映射
bindInteraction	对齐协议与具名handler；dispatch(input, context)，不执行未登记命令
ToolLifecycleRegistry	真正执行委托 Core 工具；assertDecision 检查决策，authorize 通过返回 void、拒绝抛错

注册器的声明和查询结果使用同一套字段。ID 清单使用 ids()，命名规则使用 idPattern，自定义断言使用 assertDefinition。Scope 的 aliases 用于业务名称代指，由 normalize 解析。

构造时已有完整清单，可用 IntentRegistry.create(definitions, policy) 或 ScopeRegistry.create(definitions, policy)，一次建立并封存目录。需要分阶段装配时，用 new Registry(policy).registerAll(definitions).seal()；二者沿用同一注册合同。

InteractionProtocol、CommandCatalog 是公开构造器；Interaction 与 Interaction.Commands 分别提供它们的命名空间入口。

Tools Kit 保留全局检查→授权→resume/execute→完成→finalize 的真实次序。每个工具只声明一个 lifecycle 块：inspect、finalize 等钩子对全部工具运行，id/protocol/call 与 authorize/resume/complete 只由被选中的工具运行。接收者字段叫receiver，不与OutputField.owner混用；请求内journal沿用Core分配的invocationId。

Evidence 与 Retrieval

defineEvidenceChecklist(providers): EvidenceChecklist
checklist.isSatisfied({ observations, requirement }): boolean
checklist.missing({ observations, requirements }): readonly EvidenceRequirement[]
checklist.isComplete({ observations, requirements }): boolean

defineEvidenceProjection(definition): EvidenceProjection
projection.project({ observations, sourceIds }): readonly Observation[]

defineRetrieval(definition): Retrieval
retrieval.run(input, context): RetrievalReceipt

EvidenceRequirement描述需求，不是已存在资源；不能因与ArtifactReference同含ID而合并权限合同。Projection对无选择、未知选择及完整候选的处理保留当前证据边界。

Retrieval定义使用assertInput、authorize、execute、assertResult和具名effects。RetrievalSource.sourceId是本次请求的引用标识，可与资料实体自身的id并存；它不是另一种实体主键拼写。Receipt使用startedAtMs，检索计数使用queryCount。定义中不得绑定请求状态，state/budget从本次context.app取得，errors.duplicate/budget集中声明拒绝原因。同步运行保持同步，误返Promise明确拒绝。

Retrieval 提供 run(input, OperationContext)，定义中的 assertInput 为必需断言，结果断言使用 assertResult，错误工厂放在 errors.duplicate／errors.budget。limit 与 queryCount 必须为非负安全整数，0 额度不会发起读取。去重优先于预算；拒绝授权不预占，读取失败保留 seen key。来源绑定完成后再次检查取消再提交证据；提交后的 effect 顺序执行，取消或失败停止后续项，不伪造回滚。

Policies、Normalization、Delivery、Candidates

Kit	首选创建与执行	终止／错误语义
Policies	definePolicySet；assess(input)	全量匹配原因，不是首个命中
Recovery	defineRecoveryChain；tryRecover(input)	首个明确接管，不能误吞错误；终值可含undefined时用显式handled判别
Normalization	defineNormalization；normalize(input, context)	顺序转换，when条件及isComplete判定；保留0/false/空串
Delivery	defineDelivery；deliver(input, context)	阶段hook与handler交错；显式continue/complete，支持合法undefined终值
Candidates	defineCandidateSelection；parse({ value, allowed })	minCandidates/maxCandidates，顺序和数量受真实声明限制

候选解析中 value 是待解析值，allowed 表示本次任务是否允许候选信封。maxCandidates 必须明确配置，minCandidates 省略时为 1；普通单值仍返回单元素数组，不能在任务接管后提交新候选，也不能嵌套候选。

交付阶段使用 id；beforeStage 接收 { stageId, state } 和 OperationContext，handle 接收 state 和同一个上下文。deliver 的第二个参数提供真实 signal 和可选 diagnostics，进入阶段及 handler 前后均检查取消；同步 hook 或 handler 不接受 Promise。ContentProjection 使用命名请求，TreeProjection 使用 visit 遍历。

每个策略定义用id、description、when和具名handler。普通单条件不需要变成阶段类；顺序pipeline、首项匹配、归并和拒绝检查仍是不同流程。

Projection、Aggregation、TextSkills

Kit	统一合同
ContentProjection	defineContentProjection；project({ value, maxChars })，返回{ text, truncated }；兜底文本也须满足预算，无法满足时拒绝；数据不可伪造
TreeProjection	defineTreeProjection；visit(input, context)，maxDepth和omit有明确同步语义
QueryAggregation	defineQueryAggregation；collect(inputs, context)，保留串行顺序、去重键、覆盖和计数口径
TextSkills	defineTextSkillLoader；load(input, context)，真实文件读取由App端口提供

TextSkill 定义使用 id、entry、toolIds 和 kind=text-workflow。目录项的结构与正文说明分开，ID 及工具引用来自同一登记源。

TextSkillLoader 接受 load({ entries }, { read })。注册 ID、路径、工具引用和重复项检查先于对应文件读取，read 与自定义解析器均须同步。读取端口、注册项和错误工厂可以由类实现，原型 getter 与原方法接收者保留。工具回执的 App 自有字段由 App 显式投影。

TextBlocks

interface TextBlock {
  readonly number: number
  readonly text: string
  readonly start: number
  readonly end: number
}
TextBlocks.split(text, { targetChars }): readonly TextBlock[]

split 只切分已解码的纯文本：标题与分隔线起新块，空行结束当前块，其余在换行处按 targetChars 断开。超过目标长度的单行保留为一个块，由分页读取再切片段，避免同一行被拆成互不相关的两段。各块按顺序拼回与原文逐字一致，保留全部空白与 CRLF；number 从 1 开始，start／end 是原文 UTF-16 偏移。targetChars 必须为正整数，空文本返回空数组。

Kit 不读写文件、不分页、不访问模型或存储；分页窗口、索引、摘要与提示词由 App 决定。块边界是结构边界，不与固定字符窗口对齐，需要覆盖范围时使用 start／end。

TextSearch、VectorSearch、RRF、ModelCalls

interface SearchHit<Document> {
  readonly id: string;
  readonly score: number;
  readonly document: Readonly<Document>;
}
new TextSearch({ indexRevision, fields, storedFields, ...options })
new VectorSearch({ identity, dimensions })
textSearch.search({ query, limit, filter }): readonly TextSearchHit<Document>[]
vectorSearch.search({ vector, limit, filter, minScore?, groupBy? }): readonly VectorSearchHit<Document>[]
vectorSearch.upsert({ document, vector }): void
reciprocalRankFusion(lists, options): readonly FusedRank[]

TextSearch的Payload仍是已声明存储字段的Partial<Document>，VectorSearch可返回完整文档；不能因统一document字段就声称全文数据已读取。额外terms/contributions按各算法扩展。三者score不是相同置信度，RRF不能直接混合原始分数。

TextSearch 只复制已声明的索引及存储字段，输入原件、过滤回调和返回结果不共享嵌套元数据。VectorSearch 的过滤与分组回调各自取得独立文档副本；修改这些副本不会改写索引或影响另一回调。索引元数据须可 structuredClone，向量必须完整提供每一维数值，稀疏数组拒绝。

TextSearch.snapshot() 返回 version=2、engine、configurationFingerprint 和 serializedIndex；restore 接受 version=2。指纹和公开构造参数均使用 indexRevision／storedFields。remove 会等待索引 vacuum 后再返回，保证删除内容不残留在下一次序列化中。

new ModelCalls(bindings)
models.invoke({ modelId, input, timeoutMs }, context): Promise<ModelResult<Output>>

绑定使用 id、identity、invoke、assertInput/assertOutput。绑定回调返回业务值，ModelCalls 公开边界包装为 { value, invocation }。id 为登记键，identity 为实际模型身份；context.signal 与 timeoutMs 共同约束外部 I/O。异构模型按登记 ID 推断 I/O，动态 ID 保持 unknown。

输入检查通过后，ModelCalls 在当前调用栈中交接给 invoke，不额外排入微任务。任意 App 输入可保留类实例和原型；handler 内部若跨 await 使用可变数据，由该 handler 明确快照所需字段。

const attemptBudget = new AttemptBudget(2);
await models.invoke({ modelId, input, timeoutMs: 1000 }, { signal, attemptBudget });

attemptBudget 是当前请求的可选调用尝试端口，可直接使用 Core 的 AttemptBudget。解析／前置取消不扣额度；实际接纳尝试在 I/O 前原子取得一次，失败不退回。一次批量调用仍计一次，向量条目、token 和聊天调用次数分别由 App 定义与计量；没有传入预算时，不应声称外部推理已受统一额度约束。复用模型目录不会自动创建用户问答的业务额度。上下游绑定可传递同一预算端口，Core 不内置供应商、模型角色或跨业务总额度。

Artifacts

interface ArtifactReference {
  readonly resolverId: string;
  readonly artifactId: string;
  readonly revision?: string;
}
interface ArtifactResolver<Output, App> {
  readonly id: string;
  resolve(reference: ArtifactReference, context: OperationContext<App>): MaybePromise<Output>;
}
defineArtifactCatalog(resolvers): ArtifactCatalog
catalog.resolve(reference, context): Promise<Output>

resolverId指向登记的解析器，artifactId指向资源，两者不复用含义不清的id/kind。Resolver负责真实账号、存在性、版本和生命周期校验；额外URL／路径字段不选择实际资源。取消中断等待并消费迟到拒绝，不证明外部读取已停止。

执行入口接受 ArtifactReference 与 OperationContext。实现可携带自己的额外成员，执行时读取接口定义的字段。

Durable

defineDurableTask(definition, options?): DurableTask
interface DurableTaskDefinition<State, App> {
  readonly id: string;
  readonly revision: string;
  readonly steps: readonly DurableStep<State, App>[];
  isState(input: unknown): input is State;
  authorize?(checkpoint, context): void | Promise<void>;
}
task.run({ taskId, store }, context): Promise<State>

Step仍有id、replayPolicy、run和可选reconcile；handler采用state在前、OperationContext在后。App提供store排他访问、load/save、用户归属、保留期及序列化验证；不添加SDK默认数据库或自动调度。

Checkpoint v2使用definitionId、revision、nextStepIndex、attemptCount、maxAttempts、deadlineAtMs、status、state。status是本Kit状态，不能成为Core所有应用的必需字段。

执行前先保存尝试与running；中断的safe步骤可由App保证安全重跑，reconcile步骤只走对账，没有对账实现就拒绝。恢复不重置次数或期限，handler返回副本状态后先检查signal/期限/形状，再保存确认。保存中的取消不能假装已撤回写入。

DurableStore 接口包含 exclusive(taskId, operation)、load(taskId)、save(taskId, checkpoint)。load/save 使用 version=2；进入执行前检查 definitionId/revision、state、索引、次数和期限。未知版本拒绝，不回退成新任务。恢复任务不会获得额外预算或授权。

Durable 使用 isState 校验状态，使用 replayPolicy 决定重放方式，通过 run({ taskId, store }, OperationContext) 执行。进入排他操作、读取后、状态校验与克隆后、每次保存前后均检查取消或期限；保存始终在锁内等待，不能通过取消竞速假装撤销已经提交的写入。handler 接收当前 Loop 子作用域的诊断。

完整导出、精确重载和声明源码见公开符号参考。示例中的签名用于阅读，不能据省略字段推断任意扩展选项。

局部协议与纯算法的有意差异

PolicySet／RecoveryChain 提供 definitions/ids/values/entries/has/get/require，直接处理调用方输入。纯谓词／恢复链不需要执行 signal；Normalization、TreeProjection、Aggregation 的第二个 Context 是调用方声明的算法上下文，没有外部执行生命周期。读取、工具执行和持久任务使用 OperationContext。

Interaction 的协议接收者与 handler 均按接口接入，独立对象或类实例无需转换成普通对象。bindInteraction 在绑定时固定命令处理函数及原接收者；私有状态和原型方法继续有效。协议类提供的选择错误与 envelope 回调也保留原接收者。

Interaction 的 ProtocolField 使用 jsonSchema；compiled command 公开 inputJsonSchema（完整必需字段）、modelJsonSchema（模型可提交投影）与 fieldSchemas（各字段描述），assert 负责断言、parse 负责转换。when 必须是同步 boolean；occur 是同步拒绝谓词或 OR 谓词数组。refine 返回 void、format 返回已转换值；所有回调固定原方法及原接收者。

ToolLifecycle的composition选择结构化模板提供者，保留其既有falsey拒绝语义，不视为任意泛型终值；Delivery、Recovery及AnswerFlow中可能合法返回undefined的控制协议则必须显式判别。其余同步hook拒绝thenable，authorize/inspect必须返回void。绑定的执行signal与诊断通过真实调用context下传。

RRF 每条输入排名及贡献明细均用 sourceId。Text/VectorSearch 中的 filter 由 App 提供，必须同步返回 boolean。VectorSearch.upsert 使用 { document, vector }，search 使用命名请求。两者命中都用 document，分数含义分别为词法权重和余弦相似度；RRF 只融合名次，不能直接比较它们的 score。

ModelCalls 绑定使用 assertInput／assertOutput 检查输入与输出。timeoutMs 必须是 1 到 2147483647 的安全整数，非法值在调用前拒绝。

DurableTask 的第二个构造 options 可绑定 store 和 now；run 的命名请求可提供本次 store。authorize 在每次恢复及已完成结果返回前检查当前身份、来源版本和授权。

Checkpoint 可包含 modelBudget: { maxCalls, reservedCalls, maxCallsPerAttempt }。每次执行前先持久预留整次额度，再交给 handler 的 maxModelCalls；App 用它约束真实 runner。中断或未用完的预留不退还，因此崩溃后恢复也不能重置累计额度。State 谓词同步 boolean，steps 具有明确 replayPolicy；时钟、保存中取消和对账沿用相同生命周期。完整示例见持久任务。

Reflection、Family 与知识发布

复盘、分支和资料发布介绍 defineReflection、defineAgentFamily 和 Knowledge.defineKnowledgePublication 的配置及使用。它们是 App 可选的 Kit，身份、真实存储和发布决定由 App 提供。

MockGPT

模拟模型 Kit 从 @jangts/agent-core/mock 使用；Node 服务和网页来源分别由 /mock/node、/mock/web 提供。可直接生成 JSON 值，也可测试模型客户端的 HTTP/SSE 及故障处理。完整输入、返回、预算与 TS/JS 示例见 MockGPT API。