{"_id":"@aipack-ai/agent","_rev":"7-6fe9de2b44102eb4da948a65dc2137fd","name":"@aipack-ai/agent","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@aipack-ai/agent","version":"0.0.1","keywords":["agent","ai","framework","llm"],"license":"MIT","_id":"@aipack-ai/agent@0.0.1","maintainers":[{"name":"luoguoxiong2021","email":"luoguoxiong2021@163.com"}],"dist":{"shasum":"7f958a8dcfde79b416eecd9c077074b013226e5e","tarball":"https://registry.npmjs.org/@aipack-ai/agent/-/agent-0.0.1.tgz","fileCount":12,"integrity":"sha512-DJI64Q2ZwexsPpt+Hir1PouwSpl40IiIwzhDbgQKntOuJuezHmVzGgdc8jNKJgvRdgHBEOJgROhqKV7PUQt2TA==","signatures":[{"sig":"MEUCIQD4S59iXtI0DnT4e2GYS4rfhoTABzYsdozi+wJ70XYGDgIgb4RK2W2dGhDgeUTqZLzpf/kPQbSSiKxazQR/FjNvMqI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":806444},"main":"./dist/index.js","type":"module","_from":"file:aipack-ai-agent-0.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ai":{"types":"./dist/ai/index.d.ts","import":"./dist/ai/index.js"},"./package.json":"./package.json"},"scripts":{"test":"node --import tsx --test test/*.test.ts","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"luoguoxiong2021","email":"luoguoxiong2021@163.com"},"_resolved":"/tmp/46b1490c7ec39dcbd6742d4dc004fcd1/aipack-ai-agent-0.0.1.tgz","_integrity":"sha512-DJI64Q2ZwexsPpt+Hir1PouwSpl40IiIwzhDbgQKntOuJuezHmVzGgdc8jNKJgvRdgHBEOJgROhqKV7PUQt2TA==","_npmVersion":"10.8.2","description":"Agent 框架：Runtime + Extension + Transformer，配置入口 + 执行入口","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","dependencies":{"partial-json":"^0.1.7","@sinclair/typebox":"^0.34.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.5.0","@types/node":"^20.12.0"},"_npmOperationalInternal":{"tmp":"tmp/agent_0.0.1_1786893985027_0.6239266830030303","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@aipack-ai/agent","version":"0.0.2","description":"Agent 框架：Runtime + Extension + Transformer，配置入口 + 执行入口","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ai":{"types":"./dist/ai/index.d.ts","import":"./dist/ai/index.js"},"./package.json":"./package.json"},"sideEffects":false,"keywords":["agent","ai","framework","llm"],"license":"MIT","engines":{"node":">=18.19.0"},"dependencies":{"@sinclair/typebox":"^0.34.0","partial-json":"^0.1.7"},"devDependencies":{"@types/node":"^20.12.0","tsup":"^8.5.1","typescript":"^5.5.0"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","test":"node --import tsx --test test/*.test.ts"},"_id":"@aipack-ai/agent@0.0.2","_integrity":"sha512-wdslipAEpsHjCMNsXjQT64g6a91sKtR4syaBUOPPg0ges8cJn7j4CaYk1aLjFJZqrBxYGBIFOMQweuv/kZfXTg==","_resolved":"/tmp/249abef843bfb47ffe5752f6e7d092a4/aipack-ai-agent-0.0.2.tgz","_from":"file:aipack-ai-agent-0.0.2.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-wdslipAEpsHjCMNsXjQT64g6a91sKtR4syaBUOPPg0ges8cJn7j4CaYk1aLjFJZqrBxYGBIFOMQweuv/kZfXTg==","shasum":"2bc8fec58efd5d731977a0635ea6a56bb86fd87b","tarball":"https://registry.npmjs.org/@aipack-ai/agent/-/agent-0.0.2.tgz","fileCount":12,"unpackedSize":811651,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGBaeguNnxLLJnU1jJS2M37sYXHm1746FxP/MaZYJWpMAiEA4CZ8IvUTXeSQ34mH/hEkKDDncvb2NjWerqn1fbkH5cI="}]},"_npmUser":{"name":"luoguoxiong2021","email":"luoguoxiong2021@163.com"},"directories":{},"maintainers":[{"name":"luoguoxiong2021","email":"luoguoxiong2021@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent_0.0.2_1787062982882_0.8232136452218308"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-16T15:26:24.873Z","modified":"2026-08-18T14:23:03.272Z","0.2.0":"2026-08-16T05:09:10.991Z","0.2.1":"2026-08-16T06:01:54.727Z","0.3.0":"2026-08-16T14:03:42.288Z","0.0.1":"2026-08-16T15:26:25.179Z","0.0.2":"2026-08-18T14:23:03.029Z"},"license":"MIT","keywords":["agent","ai","framework","llm"],"description":"Agent 框架：Runtime + Extension + Transformer，配置入口 + 执行入口","maintainers":[{"name":"luoguoxiong2021","email":"luoguoxiong2021@163.com"}],"readme":"# aipack\n\nAgent 框架：`Runtime + Extension + Transformer`，配置入口 + 执行入口。\n核心调度、会话持久化、工具执行、上下文转换均自研实现，不依赖任何外部 Agent 框架。\n\n## 特性\n\n- **Runtime 核心调度器**：接收请求 → 构建任务图 → 链式转换上下文 → 调用模型 → 执行工具 → 产出结果\n- **扩展机制**：`Extension`（插件）通过 Tapable 钩子挂载生命周期，`ContextTransformer` 按数组顺序链式转换上下文\n- **会话持久化**：内存 / 文件两种 `SessionStorage` 适配器，`maxAge` 过期惰性清理\n- **流式与同步双入口**：`runtime.run()` 一次性返回，`runtime.stream()` 流式返回增量事件\n- **工具循环**：模型输出 tool call → 自动执行工具 → 结果回填上下文，直到无工具调用或终止\n- **可选 AI 模型层**：子模块 `aipack/ai` 提供模型目录、多提供商流式实现与图片生成；根路径 re-export `adaptAiModel`/`createStreamFnFromAi` 一键适配，无需手写 streamFn\n\n## 安装\n\n```bash\nnpm install aipack\n# 或\npnpm add aipack\n```\n\n## 快速开始\n\n最小示例（推荐：与内置模型层配合，无需手写 streamFn）：\n\n```ts\nimport {\n  createRuntime,\n  createRequest,\n  createFileSessionStorage,\n  getBuiltinModel,\n  adaptAiModel,\n  createStreamFnFromAi,\n} from 'aipack';\n\nconst aiModel = getBuiltinModel('deepseek', 'deepseek-chat'); // 需配置 DEEPSEEK_API_KEY\n\nconst runtime = createRuntime({\n  model: adaptAiModel(aiModel),\n  streamFn: createStreamFnFromAi(aiModel),\n  systemPrompt: '你是一个简洁的 AI 助手',\n  sessionKey: 's1', // 单会话标识（多会话请创建多个 Runtime 实例）\n  // 启用会话持久化后，同一 Runtime 的历史会自动恢复为上下文\n  sessionStorage: createFileSessionStorage({\n    baseDir: './sessions',\n    maxAge: 30 * 24 * 60 * 60 * 1000, // 毫秒\n  }),\n});\n\n// 同步调用\nconst result = await runtime.run(createRequest('你好'));\nconsole.log(result.content);\n\n// 流式调用\nfor await (const chunk of runtime.stream(createRequest('写一首诗'))) {\n  if (chunk.type === 'text') process.stdout.write(chunk.content ?? '');\n}\n\nawait runtime.close();\n```\n\n## 核心概念\n\n| 模块                 | 说明                                           |\n| -------------------- | ---------------------------------------------- |\n| `Runtime`            | 核心调度器（`AgentRuntime` / `createRuntime`） |\n| `Request`            | 请求入口（`createRequest`）                    |\n| `ContextResource`    | 上下文资源单元                                 |\n| `TaskGraph`          | 任务依赖图                                     |\n| `ContextTransformer` | 上下文转换器（按数组顺序链式执行）             |\n| `Extension`          | 扩展插件                                       |\n| `Result`             | 运行结果                                       |\n| `Tapable`            | 事件钩子系统                                   |\n\n## 主入口 API（`aipack`）\n\n### 核心类型（core）\n\n消息模型：\n\n```ts\ntype Message =\n  | UserMessage\n  | AssistantMessage\n  | ToolResultMessage\n  | SystemMessage;\n\ninterface BaseMessage {\n  role: string;\n  content: string | ContentBlock[]; // ContentBlock: text | image | toolCall | thinking\n  timestamp: number;\n}\n```\n\n- 内容块：`TextContent` / `ImageContent` / `ToolCallContent` / `ThinkingContent`\n- 模型：`Model`（id / name / provider / contextWindow / maxTokens / reasoning）\n- 工具：`Tool`（name / description / parameters / execute / prepareArguments?）\n- 上下文：`Context`（systemPrompt / messages / tools?）\n- 用量：`Usage`（input / output / total / cost）\n- 流事件：`StreamEvent`（start / text*delta / thinking_delta / done / error / tool_call*\\*）\n- 工具函数：`extractText`、`extractToolCalls`、`createTextContent`、`createEmptyUsage`\n\n### Runtime\n\n工厂：`createRuntime(options?: RuntimeOptions): Runtime`\n\n```ts\ninterface RuntimeOptions {\n  config?: Record<string, unknown>;\n  workspace?: string;\n  systemPrompt?: string;\n  model?: Model;\n  streamFn?: StreamFn; // 模型提供者（若不使用 adapters/ai 则必须提供）\n  tools?: Tool[]; // 初始工具列表\n  extensions?: Extension[]; // 预注册扩展\n  transformers?: ContextTransformer[]; // 预注册转换器（按数组顺序链式执行）\n  sessionStorage?: SessionStorage; // 启用后会话自动持久化\n}\n```\n\n方法：\n\n| 方法                                           | 说明                                     |\n| ---------------------------------------------- | ---------------------------------------- |\n| `run(request): Promise<Result>`                | 执行请求（同步返回结果）                 |\n| `stream(request): AsyncGenerator<ResultChunk>` | 执行请求（流式返回增量）                 |\n| `registerTool / registerTools`                 | 注册工具                                 |\n| `setModel / setSystemPrompt / setStreamFn`     | 运行时切换模型 / 系统提示词 / 模型提供者 |\n| `registerExtension / useTransformer`           | 注册扩展 / 转换器                        |\n| `getMessages()`                                | 获取当前会话消息列表                     |\n| `abort / isBusy / waitForIdle`                 | 会话中止与状态查询                       |\n| `clearSession()`                               | 清除内存会话（不影响已持久化数据）       |\n| `deleteSession()`                              | 删除会话（内存 + 存储）                  |\n| `close()`                                      | 关闭运行时，释放资源                     |\n\n> **单会话架构**：每个 `Runtime` 绑定一个 `sessionKey`（默认 `'default'`），通过 `createRuntime({ sessionKey })` 指定。多会话场景请创建多个 `Runtime` 实例。\n\n### Request（入口）\n\n- `createRequest(message, options?)` — 构建请求\n- `RequestBuilder` — 链式构建器（`.message()` / `.channel()` / `.model()` 等）\n- `validateRequest(request)` — 校验（message 非空、长度限制）\n- `normalizeRequest(request)` — 标准化（补齐默认 channel/chatId/senderId 等）\n\n### 上下文资源 / 任务图\n\n- `ContextResourceBuilder`、`createMessageResource`、`createToolCallResource`、`createToolResultResource`\n- `messageToResource(s)` / `messagesToResources` / `resourceToMessage` / `resourcesToMessages`\n- `extractToolCallsFromResource` / `extractTextFromResource`\n- `TaskGraphBuilder` / `createTaskGraph` / `buildTaskGraph` / `graphToMessages` / `analyzeToolChains` / `findOrphanedToolCalls` / `getGraphStats`\n\n### Transformer\n\n- `BaseTransformer` 基类，实现 `ContextTransformer` 接口（transform/transformBatch）\n- 内置转换器：`ToolPairingTransformer`、`StateSnapshotTransformer`、`TruncationTransformer`、`SystemMessageCleanerTransformer`、`ensureToolPairing`、`createDefaultTransformers`\n- 执行顺序由 `transformers` 数组顺序决定（含 `RuntimeOptions.transformers` 与 `useTransformer()` 追加），上一个转换器的输出作为下一个的输入；单个转换器失败会被跳过并告警，不影响后续转换器\n\n### Extension\n\n- `ExtensionManager` / `createExtensionManager` — 注册与应用扩展，管理 `RuntimeHooks`（beforeInitialize / beforeRun / done / failed 等）\n- 内置扩展：`LoggingExtension`、`EventCaptureExtension`、`RequestInterceptorExtension`、`ResultPostProcessorExtension`、`SharedStateExtension`、`createDefaultExtensions`\n\n### Result\n\n```ts\ninterface Result {\n  content: string; // 最终回复文本\n  toolsUsed: string[]; // 使用的工具\n  usage: Record<string, number>; // Token 用量\n  stopReason: string;\n  error?: string; // 失败原因\n  success: boolean;\n  resources?: ContextResource[]; // 运行结束时的资源快照\n}\n```\n\n- 构建器：`ResultBuilder` / `createResult` / `createErrorResult` / `ResultAggregator` / `buildResultFromMessages` / `buildResultFromAssistantMessage` / `buildResultWithResources`\n\n### Session（会话持久化）\n\n- `SessionStorage` 契约：`load` / `save` / `delete` / `list`\n- `createFileSessionStorage({ baseDir?, maxAge? })` — 文件存储（每会话一个 JSON 文件，`temp + rename` 原子写入）\n  - **`maxAge` 单位为毫秒**：超过 `updatedAt + maxAge` 的会话在加载时惰性清理\n- `createMemorySessionStorage({ maxAge? })` — 内存存储\n\n## AI 模型层（`aipack/ai`）\n\n标准化模型层（内置子模块，独立于核心框架类型）：\n\n- **类型重导出**：`Type` / `Static` / `TSchema`（来自 `@sinclair/typebox`），以及 `Model`、`Message`、`StreamEvent`、`ImagesModel`、`Provider`、`CredentialStore` 等\n- **模型目录**：`Models` / `createModels(options?)`\n  - `getModels(providerId?)` / `getModel(providerId, modelId)` — 查询模型\n  - `stream(model, context, options)` / `complete(model, context, options)` — 流式 / 完整调用\n  - `streamSimple` / `completeSimple` — 简化调用（无需预解析认证）\n  - `setProvider` / `getProviders` / `getAuth` — 提供者管理\n- **内置模型**：`builtinModels`、`builtinProviders`、`builtinImagesModels`、`getBuiltinModel(provider, model)`、`getBuiltinModels()`、`getBuiltinProviders()`、`BUILTIN_MODELS`、`BUILTIN_IMAGES_MODELS`、`BUILTIN_PROVIDERS`、`getEnvApiKey(provider)`、`hasProviderConfigured`\n- **图片生成**：`ImagesModels` / `createImagesModels`、`generateImages(model, input, options?)`\n- **工具函数**：`hasApi`、`createEmptyUsage`、`createEmptyAssistantMessage`\n\n支持多提供商：OpenAI、Anthropic、DeepSeek、Google、Mistral、Bedrock 等（按 `model.api` 自动分派 `streamOpenAI` / `streamAnthropic` / ...）。\n\n常用符号（`getBuiltinModel` / `getEnvApiKey` / `hasProviderConfigured` / `BUILTIN_PROVIDERS` / `AiModel` 类型）已从根路径 `aipack` re-export；完整 surface 见 `aipack/ai` 子路径。\n\n## AI 适配器（`adaptAiModel` / `createStreamFnFromAi`）\n\n把 `aipack/ai` 的标准化模型接入核心框架（从根路径 `aipack` 导入）：\n\n- `adaptAiModel(aiModel)` — `aipack/ai` 的 `Model` → 框架 `Model`\n- `createStreamFnFromAi(aiModel, options?)` — 生成框架 `StreamFn`，内部自动对接 OpenAI / Anthropic 流式实现，并转换事件与内容块\n\n```ts\nimport {\n  createRuntime,\n  getBuiltinModel,\n  adaptAiModel,\n  createStreamFnFromAi,\n} from 'aipack';\n\nconst aiModel = getBuiltinModel('openai', 'gpt-4o-mini');\nconst runtime = createRuntime({\n  model: adaptAiModel(aiModel),\n  streamFn: createStreamFnFromAi(aiModel),\n});\n```\n\n## 会话持久化与多轮对话\n\n同一 `Runtime` 下多次 `run` / `stream` 会自动恢复历史并追加结果：\n\n```ts\nconst runtime = createRuntime({\n  model,\n  streamFn,\n  sessionKey: 'u1',\n  sessionStorage: createFileSessionStorage({ baseDir: './sessions' }),\n});\n\nawait runtime.run(createRequest('记住我的名字是张三'));\nconst r2 = await runtime.run(createRequest('我叫什么？'));\nconsole.log(r2.content); // 输出：张三\n```\n\n跨会话场景（如不同用户的独立上下文）请创建多个 `Runtime` 实例，各自持有不同的 `sessionKey`：\n\n```ts\nconst runtime1 = createRuntime({\n  model,\n  streamFn,\n  sessionKey: 'user-a',\n  sessionStorage,\n});\nconst runtime2 = createRuntime({\n  model,\n  streamFn,\n  sessionKey: 'user-b',\n  sessionStorage,\n});\n```\n\n- `maxAge` 单位为**毫秒**；需要按天配置时请自行换算（如 30 天 = `30 * 24 * 60 * 60 * 1000`）\n- 存储格式：`StoredSession`（key / version / messages / model / usage / createdAt / updatedAt）\n\n## 工具注册示例\n\n```ts\nimport { Type } from 'aipack/ai';\n\nconst runtime = createRuntime({\n  model: adaptAiModel(aiModel),\n  streamFn: createStreamFnFromAi(aiModel),\n  tools: [\n    {\n      name: 'get_weather',\n      description: '查询城市天气',\n      parameters: Type.Object({ city: Type.String() }),\n      execute: async (id, args) => ({\n        content: [{ type: 'text', text: `${args.city}: 晴，25°C` }],\n        details: {},\n      }),\n    },\n  ],\n});\n```\n\n## 相关项目\n\n- [aipack-cli](../aipack-cli/README.md) — 基于本框架的命令行工具（交互式聊天、会话回放、继续会话等）\n","readmeFilename":"README.md"}