可类型检查的 Worker API 示例

学习目录见 examples。完整入口参见接入指南、Runtime 和数据库接入。

graph-loop-worker.ts、runtime/graph-loop.ts、runtime/placement.ts 在导入时执行。下表逐 API 文件只导出示例函数，导入不发起请求。模型、数据库与 MCP 参数都是应用提供的已配置资源；按需调用函数，模型可能消耗供应商额度，写入/更新/删除会执行实际操作。

文件	参考	所需资源
context.ts	CONTEXT	显式 Context、Redis 或 ContextStateStore
memory.ts	MEMORY	MemoryResources；过滤、游标与排序由插件定义
infer.ts	INFER · Provider	InferClient/ModelConfig 或 setupInfer 加载的配置
interaction.ts	INTERACTION	工作目录权限；MCP 使用已连接客户端与允许的绝对路径
retrieval.ts	RETRIEVAL · Provider	搜索、embedding、rerank 后端；完整 MemoryItem 或 mapOutput

在仓库根目录运行 npm run typecheck。tsconfig 包含这些文件，但发布构建不包含它们。这些是 API 调用示例，不是另一套 SDK，也不会自动执行真实集成测试。// example: 区域会出现在对应 API 文档，修改签名时需保持两者一致。

完整本地任务可用 npm run example:agent 或 npm run example:tools。MCP 配置见接入指南。使用 Node --env-file=.env 或应用加载器显式读取环境文件；loadRuntimeConfigFile 读取 YAML 并使用传入的环境，不自行读取 .env。

函数说明

对象和构造函数不会自动运行 Graph。调用者按签名注入已经配置好的资源。

memory.ts

函数 / 对象	用途与实际行为
setupMemory	加载配置，同时创建 MEMORY Worker/Runtime 与直接 SDK；两者使用应用提供的存储与检索资源。
getMemory	按 ID 和 key 精确读取，展示重复 ID 去重与 NodeResult 成功检查。
queryMemory	按 id 排序读取最多两页，传递 nextCursor 并合并 items；插件须支持示例排序字段。
searchMemory	使用数据库插件的默认检索策略，读取完整记忆及可选 score。
writeMemory	写入一条语言偏好，返回数据库分配的 id；重复 key 的行为由插件决定。
updateMemory	按已有 id 替换内容并清空 metadata，展示 partial update 的字段语义。
deleteMemory	删除指定 id，查看实际删除列表；重复 id 不会重复报告。
executeMemory	用统一 execute 入口调用 MEMORY.QUERY。
adaptDatabase	将已符合 Memory 契约的应用数据库适配器包装为 store/search，保留方法的 this 绑定。
memoryErrors	演示非法 limit 与应用 MemoryError 如何返回结构化失败。
memoryGraph	将 MEMORY.GET 放入 Graph，通过 Runtime 执行后关闭。
customGet	通过节点描述符定义一个显式 NOT_CONFIGURED 失败处理器；展示 define 用法，不读数据库。

infer.ts

函数 / 对象	用途与实际行为
setupInfer	加载 YAML/env 配置，创建共享缓存的 Worker、Runtime 与直接 SDK。
sample	单次模型采样，读取 Message、finishReason 和 usage。
sampleActions	向模型声明 read_text 动作；只生成动作请求，不实际执行文件读取。
trajectory	执行 CoT 轨迹，同时检查外层 success 与内层 completed。
strategyRequests	只构造 CoT、Long CoT、ToT、GoT、Self-consistency 五种请求，不调用模型。
reflectModes	根据传入的 critique/verify/revise 模式评估或修正候选答案。
deliberateModes	根据 select/merge/consensus/debate 模式处理候选；只有 select 设置 selectCount。
cacheApis	演示缓存写入、命中读取，以及按 key/tag/namespace 失效。
executeInfer	通过统一 execute 入口采样，并设置单次调用 timeoutMs。
streamApis	依次消费四类 reasoning 流，展示各自终态输出；运行该函数会发起多次模型调用。
cancelInfer	传入预先取消的 AbortSignal，演示不发起模型请求的 cancelled 返回。
cacheProviderApi	直接调用缓存后端的 write/lookup/invalidate；返回原始输出，不套 NodeResult。
refineStrategy	自定义策略函数：生成初稿、修订、审议选择，再记录公开决策步骤；注入后才能按名称使用。
providerRegistryApis	注册模型 Provider、按名称解析、调用原始 invoke，并在结束时注销。
providerStream	直接消费 Provider 流；不支持 stream 时回退到 invoke。
httpModelProvider	按传入配置创建 HTTP 模型适配器；构造本身不发请求。
sampleDescriptor	将现有 SDK 的 sample 方法包装为一个 NodeDefinition，不自动注册或执行。

interaction.ts

函数 / 对象	用途与实际行为
readTextTool	定义读取工作区文件的工具，包括参数校验、能力描述和 Sandbox 文件读取。
consoleSink	定义控制台输出接收端，打印消息并返回 accepted 回执。
setupInteraction	将文件工具、已连接 MCP 客户端和输出接收端注册进同一个 Worker/Runtime。
interactionNodes	使用注册表、createInteractionNodes 与 defineWorker 组装 Worker。
interactionHandlers	分别用各 handler 工厂组装四个 Interaction 节点。
toolRegistryApis	在真实 WorkerContext 中注册工具、列出允许的定义、调用工具并注销。
invokeTool	通过 Runtime 真实读取 README.md，展示 ExternalResult 不含 output 包装。
mcpRegistryApis	直接使用 McpRegistry 发现工具、调用 read_text_file，并注销客户端绑定。
invokeMcp	通过 Runtime 调用 MCP 发现与文件读取，区分两种响应形状。
observeApis	对比纯函数与 OBSERVE 节点的标准化结果；使用本地给定结果，不调用外部服务。
outputApi	向控制台接收端提交结构化消息与 artifact 引用，返回交付回执；不创建 artifact 文件。
missingRecordTool	定义返回 NOT_FOUND 的示例工具，用于说明业务失败结果。
rejectedSink	定义返回 rejected 的接收端，用于说明交付失败回执。
interactionGraph	通过 Graph + Loop 读取 README.md 和 package.json，并输出两次观察结果。
observationDefinition	用节点描述符定义 OBSERVE handler，不自动注册或执行。
mcpClientAdapter	包装中立 MCP 客户端，保留方法的 this 绑定和可选响应字段。

retrieval.ts

函数 / 对象	用途与实际行为
request	公共示例请求：查询 agent memory、逻辑目标 kb、limit=5；只是数据。
setupRetrieval	显式注册可选 Worker 与逻辑 target/strategy，并创建直接检索 SDK。
retrievalSearch	用同一个后端分别执行 SDK 和 Runtime 检索，展示候选输出。
registryResolve	按目标选择默认策略 Provider，直接读取原始结果。
cancelRetrieval	演示 search 第三个参数中的 AbortSignal，以及第二个参数的后备默认值。
embeddingApis	比较直接 embed 与分批 embedContents，并用 validateVector 检查维度。
httpEmbedding	从 env 创建真实 HTTP embedding Provider，使用 YAML 批次配置生成查询向量。
externalVector	先调用外部 embedding，再将向量交给数据库后端检索。
nativeVector	将原始查询交给具备内置 embedding 的数据库后端。
precomputedVector	直接使用已有向量检索，并校验向量维度。
textSearch	包装数据库的原生文本检索，不进行 embedding。
hybridSearch	并行调用 vector 与 keyword 分支，再通过加权 RRF 融合候选。
rerankApis	使用 embedding 创建 cosine 重排器，对比原始 index/score 与映射后的候选结果。
rerankSearch	扩大召回池后使用注入的 reranker 重排，截取请求数量。
sqlSearch	创建使用 PostgreSQL 全文 SQL 的检索适配器；注入 query 回调，绑定文本和租户参数。
milvusSearch	创建 Milvus 请求/响应适配器；注入 SDK search，映射 namespace 与完整 MemoryItem。
nativeMemoryInRetrieval	把数据库原生 MemorySearchProvider 转成 Retrieval Provider，再映射回 Memory 结果。
nativeMemoryWithNamespace	将 Retrieval namespace 显式转换为插件的 tenant filter；不替代鉴权。
localMemoryPipeline	在 MEMORY 内直接复用检索 pipeline，不启动 RETRIEVAL Worker。
delegatedMemory	将 MEMORY.SEARCH 委托给 Runtime 中的 RETRIEVAL.SEARCH；示例采用同进程路由。
mapTextCandidates	把候选中的完整业务内容映射为 MemoryItem；片段/ID 索引需要改成批量补全。
retrievalDescriptor	将检索 SDK 包装为单个 NodeDefinition，保留 SDK 校验与 NodeResult。

context.ts

函数 / 对象	用途与实际行为
setupContext	创建 SDK 与 Worker；详见 CONTEXT。
loadContext	LOAD：消息、条目与引用；详见 CONTEXT。
selectContext	SELECT：推理与记忆用途；详见 CONTEXT。
updateContext	UPDATE：增量与来源；详见 CONTEXT。
compressContext	COMPRESS：预算；详见 CONTEXT。
executeContext	execute：通用调用；详见 CONTEXT。
cachedContext	四个节点的缓存调用；详见 CONTEXT。
redisStore	Redis 存储与显式版本；详见 CONTEXT。
contextServices	注入自定义服务；详见 CONTEXT。
ragContext	RAG 策略；详见 CONTEXT。
contextRetrieval	复用 RETRIEVAL Provider；详见 CONTEXT。
contextToInfer	传入 INFER；详见 CONTEXT。
memoryToContext	MEMORY 与 Context Graph；详见 CONTEXT。
contextFlows	RAG 与 Skill 流程；详见 CONTEXT。
contextErrors	错误分支；详见 CONTEXT。
directStrategies	复用内置策略；详见 CONTEXT。
customContextLoad	自定义节点描述符；详见 CONTEXT。
contextToMemory	写入长期 MEMORY。
toolToCachedContext	工具观察写入缓存。
remoteContextRetrieval	委托独立 RETRIEVAL。

建议顺序

1. 无外部依赖时先运行完整入门示例。
2. 按 Worker 选择函数、注入资源。setupMemory/setupInfer/setupInteraction/setupRetrieval 返回的 Runtime 由调用者关闭。
3. 修改后运行 npm run typecheck；仅运行 node docs/worker-api/examples/memory.ts 不会执行导出的函数。

数据库接入提供 Redis Context 和 SQL/Milvus Memory。Runtime 示例涵盖首次 Graph、自定义 Worker、事件、Artifact、资源关闭以及 RAG/Skill/Tool/MCP/ReAct；各目录说明区分直接执行入口和可安全导入的函数模块。