{"_id":"@amigo-llm/backend","name":"@amigo-llm/backend","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.3":{"name":"@amigo-llm/backend","version":"1.0.3","description":"`@amigo-llm/backend` 是 Amigo 的后端 SDK，提供会话运行时、任务编排、工具系统、sandbox 能力和 conversation WebSocket runtime。","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"bun":"./src/index.ts","types":"./dist/index.d.ts","default":"./dist/index.js"},"./sdk":{"bun":"./src/sdk.ts","types":"./dist/sdk.d.ts","default":"./dist/sdk.js"},"./package.json":"./package.json"},"scripts":{"test":"bun test","build":"bun run build:js && bun run build:types","build:js":"bun build ./src/index.ts ./src/sdk.ts --outdir ./dist --target='bun'","build:types":"tsc -p ./tsconfig.declarations.json"},"keywords":[],"author":"","license":"ISC","dependencies":{"@amigo-llm/types":"workspace:*","dockerode":"^4.0.9","dotenv":"^17.2.3","p-wait-for":"^6.0.0","uuid":"^13.0.0","zod":"^4.1.13"},"devDependencies":{"@types/bun":"^1.3.3","@types/dockerode":"^4.0.0","fast-check":"^4.3.0"},"peerDependencies":{"typescript":"^5"},"_id":"@amigo-llm/backend@1.0.3","gitHead":"810d7e1464b914703310d80367082a4774a2a99f","_nodeVersion":"20.11.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-1blSRp85BI3QRuSD1mQVzJOaf9/p+vMw72paV1d77UkTK+6VqJrVVoQXjFCeReqsrCskf9sRCGb8iZrzfIbgzw==","shasum":"c653535eb063b536dfab8cd335bc4dbfbe9daf68","tarball":"https://registry.npmjs.org/@amigo-llm/backend/-/backend-1.0.3.tgz","fileCount":141,"unpackedSize":6391659,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDzXVD+xfyw/aR4ZDYXunHi9TIIK0rVGSUYjjJmAhE1YAIhAIVXE/XZSXvYA4j/tfR6p5K1c4sf/Hv/58wF3julXGy9"}]},"_npmUser":{"name":"kb666","email":"kaiqingliu6@gmail.com"},"directories":{},"maintainers":[{"name":"kb666","email":"kaiqingliu6@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/backend_1.0.3_1773737231788_0.7411678255091925"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-17T08:47:11.719Z","1.0.3":"2026-03-17T08:47:11.945Z","modified":"2026-03-17T08:47:12.111Z"},"maintainers":[{"name":"kb666","email":"kaiqingliu6@gmail.com"}],"description":"`@amigo-llm/backend` 是 Amigo 的后端 SDK，提供会话运行时、任务编排、工具系统、sandbox 能力和 conversation WebSocket runtime。","keywords":[],"license":"ISC","readme":"# @amigo-llm/backend\n\n`@amigo-llm/backend` 是 Amigo 的后端 SDK，提供会话运行时、任务编排、工具系统、sandbox 能力和 conversation WebSocket runtime。\n\n它适合用来构建：\n\n- headless agent 服务\n- benchmark / batch runner\n- 带自定义工具和消息协议的 coding agent\n- 由应用自己托管 HTTP 路由和页面壳层的完整产品\n\n如果你是在外部项目里扩展 Amigo，优先使用：\n\n```ts\nimport {\n  AmigoServerBuilder,\n  defineMessage,\n  defineTool,\n  type SandboxManager,\n} from \"@amigo-llm/backend/sdk\";\n```\n\n## 安装\n\n```bash\nbun add @amigo-llm/backend @amigo-llm/types zod\n```\n\n运行时基于 Bun，建议直接在 Bun 环境下使用。\n\n## 快速开始\n\n```ts\nimport { AmigoServerBuilder } from \"@amigo-llm/backend/sdk\";\n\nconst server = new AmigoServerBuilder()\n  .port(10013)\n  .cachePath(\"./.amigo\")\n  .loggerConfig({ enableTimestamp: true })\n  .build();\n\nserver.start();\n```\n\n同时提供 `server.init()`，推荐统一使用 `server.start()`。\n\n这会启动一个 headless conversation WebSocket runtime。应用可以在自己的 `Bun.serve(...)` 里接入这个 runtime，再补充自己的 HTTP 路由、鉴权和页面壳层。\n\n`editor` 跳转、`preview` 路由、preview HTTP / WebSocket 反代都属于应用层能力，不属于 backend SDK 本身。\n\n例如：\n\n```ts\nimport Bun from \"bun\";\nimport { AmigoServerBuilder } from \"@amigo-llm/backend/sdk\";\n\nconst runtime = new AmigoServerBuilder()\n  .port(10013)\n  .cachePath(\"./.amigo\")\n  .build();\n\nBun.serve({\n  port: 10013,\n  fetch(req, server) {\n    const url = new URL(req.url);\n\n    if (url.pathname === \"/healthz\") {\n      return new Response(\"ok\");\n    }\n\n    if (\n      (req.headers.get(\"upgrade\") || \"\").toLowerCase() === \"websocket\" &&\n      runtime.tryUpgradeConversationWebSocket(req, server)\n    ) {\n      return;\n    }\n\n    return new Response(\"Not Found\", { status: 404 });\n  },\n  websocket: {\n    open: (ws) => runtime.handleWebSocketOpen(ws),\n    message: (ws, message) => runtime.handleWebSocketMessage(ws, message),\n    close: (ws, code, reason) => runtime.handleWebSocketClose(ws, code, reason),\n    drain: () => {},\n  },\n});\n```\n\n## Builder API\n\n`AmigoServerBuilder` 是 SDK 的主入口。\n\n### 基础配置\n\n```ts\nnew AmigoServerBuilder().port(10013).cachePath(\"./.amigo\");\n```\n\n也可以显式配置日志：\n\n```ts\nnew AmigoServerBuilder().loggerConfig({ enableTimestamp: false });\n```\n\n### 注册工具\n\n```ts\nimport { AmigoServerBuilder, defineTool } from \"@amigo-llm/backend/sdk\";\n\nconst echoTool = defineTool({\n  name: \"echoText\",\n  description: \"回显输入文本\",\n  params: [{ name: \"text\", optional: false, description: \"输入内容\" }],\n  async invoke({ params, context }) {\n    context.postMessage?.({ type: \"tool-progress\", data: { stage: \"running\" } });\n\n    return {\n      message: `echo 完成：${String(params.text)}`,\n      toolResult: {\n        ok: true,\n        text: params.text,\n      },\n    };\n  },\n});\n\nconst server = new AmigoServerBuilder().registerTool(echoTool).build();\n```\n\n工具执行上下文里最常用的字段是：\n\n- `context.taskId`\n- `context.parentId`\n- `context.signal`\n- `context.postMessage()`\n- `context.getSandbox()`\n- `context.getToolByName()`\n\n### 注册自定义消息\n\n```ts\nimport { z } from \"zod\";\nimport { AmigoServerBuilder, defineMessage } from \"@amigo-llm/backend/sdk\";\n\nconst pingCustom = defineMessage({\n  type: \"pingCustom\",\n  dataSchema: z.object({\n    traceId: z.string(),\n    payload: z.string().optional(),\n  }),\n  async handler(data) {\n    console.log(\"收到自定义消息\", data.traceId, data.payload);\n  },\n});\n\nconst server = new AmigoServerBuilder().registerMessage(pingCustom).build();\n```\n\n行为边界：\n\n- 内置消息优先走内置 resolver\n- 只有未命中内置消息时，才会尝试匹配你注册的消息\n- 消息会先经过 schema 校验，再执行 `handler`\n\n### 模型工厂注入\n\n默认情况下，服务端会从环境变量里创建模型实例。你也可以接管这一步：\n\n```ts\nimport { AmigoServerBuilder } from \"@amigo-llm/backend/sdk\";\n\nconst server = new AmigoServerBuilder()\n  .modelProvider(() => {\n    return {\n      async completion() {\n        throw new Error(\"demo\");\n      },\n    } as any;\n  })\n  .build();\n```\n\n适合：\n\n- 多模型路由\n- mock / test\n- 对接自定义 provider\n\n### 模型配置与自动压缩\n\n如果你希望按模型统一配置 provider、baseURL、上下文窗口，并在接近阈值时自动压缩历史上下文：\n\n```ts\nnew AmigoServerBuilder().modelConfigs({\n  \"qwen3-coder\": {\n    provider: \"openai-compatible\",\n    baseURL: \"https://openrouter.ai/api/v1\",\n    contextWindow: 262144,\n    compressionThreshold: 0.8,\n    targetRatio: 0.5,\n  },\n});\n```\n\n如果你希望在配置时拿到更好的类型提示，可以从 SDK 导入 `MODEL_PROVIDERS`、`KnownModelProvider` 和 `ModelConfig`。\n\n`modelConfigs()` 是推荐入口。旧的 `modelContextConfigs()` 仍兼容，但后续建议统一迁移到 `modelConfigs`。\n\n行为说明：\n\n- 当前任务的上下文占比会同步到 `taskStatusMapUpdated.data.contextUsage`\n- 当占比达到 `compressionThreshold` 时，服务端会先总结较早的会话，再只携带“压缩摘要锚点及其之后”的上下文继续调用模型\n- 压缩开始 / 完成 / 失败会通过 `alert` 消息同步到前端\n- provider 解析优先读取 `modelConfigs[model].provider`；未配置时，仍会回退到 SDK 内置的默认 provider 规则\n\n### 自动批准工具\n\n```ts\nnew AmigoServerBuilder()\n  .autoApproveTools([\"readFile\", \"browserSearch\"])\n  .addAutoApproveTools([\"bash\"]);\n```\n\n如果你要完全覆盖 core 默认自动批准列表，也可以：\n\n```ts\nnew AmigoServerBuilder()\n  .defaultAutoApproveTools([])\n  .autoApproveTools([\"readFile\", \"editFile\", \"bash\"]);\n```\n\n### 追加系统提示词\n\n```ts\nnew AmigoServerBuilder()\n  .appendSystemPrompt(\"你是一个 coding agent，先搜索定位，再修改并验证。\");\n```\n\n### 覆盖默认 system prompt\n\n如果你不希望在默认 prompt 后追加，而是希望按 `main` / `sub` 完整替换：\n\n```ts\nnew AmigoServerBuilder()\n  .mainSystemPrompt(\"你是一个 benchmark agent，只做仓库修复。\")\n  .subSystemPrompt(\"你是一个子任务修复代理，只返回执行结果。\");\n```\n\n也可以一次性传入：\n\n```ts\nnew AmigoServerBuilder().systemPrompts({\n  main: \"main prompt\",\n  sub: \"sub prompt\",\n});\n```\n\n说明：\n\n- `mainSystemPrompt()` / `subSystemPrompt()` / `systemPrompts()` 用于覆盖默认 prompt\n- `appendSystemPrompt()` 也可用于在覆盖后的 prompt 末尾继续追加内容\n\n### 覆盖基础工具集合\n\n如果你要做 benchmark app、batch app，通常不希望沿用默认基础工具集合。此时可以直接覆盖：\n\n```ts\nimport { AmigoServerBuilder, defineTool } from \"@amigo-llm/backend/sdk\";\n\nconst repoSearch = defineTool({\n  name: \"repoSearch\",\n  description: \"在仓库内搜索文本\",\n  params: [{ name: \"query\", optional: false, description: \"搜索关键词\" }],\n  async invoke() {\n    return {\n      message: \"not implemented\",\n      toolResult: {},\n    };\n  },\n});\n\nnew AmigoServerBuilder().baseTools({\n  main: [repoSearch],\n  sub: [repoSearch],\n});\n```\n\n也可以分别设置：\n\n```ts\nnew AmigoServerBuilder().mainBaseTools([repoSearch]).subBaseTools([repoSearch]);\n```\n\n说明：\n\n- `baseTools()` 会覆盖默认 `main` / `sub` 基础工具集合\n- 不配置时，仍然使用 core 默认基础工具\n\n### 注入 sandbox manager\n\n如果你希望沿用 `context.getSandbox()` 这套调用方式，但把 sandbox 生命周期、镜像、容器后端或仓库挂载逻辑换掉，可以注入自定义 manager：\n\n```ts\nimport { AmigoServerBuilder, type SandboxManager } from \"@amigo-llm/backend/sdk\";\n\nconst sandboxManager: SandboxManager = {\n  get(taskId) {\n    return undefined;\n  },\n  async getOrCreate(taskId) {\n    return {} as any;\n  },\n  has(taskId) {\n    return false;\n  },\n  async destroy(taskId) {},\n};\n\nnew AmigoServerBuilder().sandboxManager(sandboxManager);\n```\n\n### 配置默认 sandbox 镜像\n\nSDK 本身没有 `sandboxImage()` 这类 app 配置入口。要自定义镜像，应该通过你自己的 sandbox manager 注入：\n\n```ts\nimport { AmigoServerBuilder, SandboxRegistry } from \"@amigo-llm/backend\";\n\nconst sandboxManager = new SandboxRegistry({\n  imageName: \"my_custom_sandbox\",\n});\n\nnew AmigoServerBuilder().sandboxManager(sandboxManager);\n```\n\n适合：\n\n- 自定义 Docker / VM / remote sandbox\n- benchmark 专用 repo checkout / patch 导出逻辑\n- 需要与现有 CI、评测机或沙箱平台打通的场景\n\n### 会话创建钩子\n\n应用层如果需要在创建任务后做初始化，可以使用：\n\n```ts\nnew AmigoServerBuilder().onConversationCreate(async ({ taskId, context }) => {\n  console.log(\"new task\", taskId, context);\n});\n```\n\n仓库内置应用就是通过这个钩子做 GitHub 仓库绑定和 sandbox 预创建的。\n\n## 调试与检查\n\n构建前可以读取：\n\n- `builder.toolRegistry`\n- `builder.messageRegistry`\n\n构建后可以读取：\n\n- `server.isRunning`\n- `server.serverHandle`\n- `server.toolRegistry`\n- `server.messageRegistry`\n\n也支持：\n\n```ts\nserver.stop();\n```\n\n## 完整应用示例\n\n仓库里的 [`packages/amigo`](../amigo) 展示了一个完整应用的组装方式，其中包括：\n\n- design doc 读写工具\n- Penpot 同步\n- GitHub 仓库预热\n- sandbox / bash / 文件编辑 / dev server 工具\n- coding agent 专用系统提示词\n\n对应入口在 [`packages/amigo/src/server/app.ts`](../amigo/src/server/app.ts)。其中 `editor` / `preview` 路由以及 preview HTTP / WebSocket 反代，都是 `packages/amigo` 这一层 app HTTP 额外补上的能力。如果你要做自己的应用，可以复用 backend runtime，并在自己的服务端入口里自行实现这些路由与暴露策略。\n\n## 运行时配置\n\n完整应用运行时的环境变量说明见：\n\n- [`../../README.md`](../../README.md)\n- [`packages/amigo/.env.example`](../amigo/.env.example)\n","readmeFilename":"README.md","_rev":"1-02523359e2cc743b519dfa877f08db0e"}