# @burtson-labs/agent-core 中文文档

规范地址：https://npmcn.com/package/%40burtson-labs/agent-core/

版本：1\.6\.96
npm 元数据更新时间：2026-11-08T03:15:26.091Z
中文译文更新时间：2026-11-08T20:50:40.692Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40burtson-labs/agent-core
原文对照：https://npmcn.com/package/%40burtson-labs/agent-core/?lang=original
项目主页：https://github.com/Burtson-Labs/bandit-agent-framework/tree/main/packages/agent-core#readme
源码仓库：https://github.com/Burtson-Labs/bandit-agent-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，263 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-05T02:31:19.675Z
- 最新版本发布：2026-11-08T03:15:25.941Z
- 近 30 天下载量：2099（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 81 个）

## 中文简介

土匪代理框架的核心推理和规划引擎.

## 安装

```sh
npm install @burtson-labs/agent-core
```

也可以使用：`pnpm add @burtson-labs/agent-core`、`yarn add @burtson-labs/agent-core`、`bun add @burtson-labs/agent-core`

## README

[![Burtson Labs](https://cdn.burtson.ai/logos/burtson-labs-logo.png)](https://burtson.ai/)

# @ burtson-labs/ 代理核心

**土匪特工框架的核心推理与规划引擎.**

拥有 `ToolUseLoop` ——在VS代码扩展和CLI主机中,驱动每个匪徒代理运行的迭代控制器,母或子代理.

* * *

## ![](https://icons.burtson.ai/svg-accent/download.svg) 安装

```bash
pnpm add @burtson-labs/agent-core
```

## ![](https://icons.burtson.ai/svg-accent/zap.svg) 快开始

`agent-core` 是提供者不可知的——与提供者客户端对齐(`@burtson-labs/agent-adapters-provider` 包装 Ollama, OpenAI 兼容的端点,以及主机"盗贼"网关)和主机侧式工具集(`@burtson-labs/host-kit` 将额外CLI和扩展用途的船载。 最小形状 :

```ts
import { createAgentRuntime } from "@burtson-labs/agent-core";

const runtime = createAgentRuntime({
  providerClient,                    // satisfies ProviderClient
  systemPrompt: "You are a helpful coding agent.",
  tools: [/* built-ins + your own */]
});

const plan = await runtime.plan("Summarize this repo");
const result = await runtime.execute();
const report = await runtime.report();
```

主机在提供者上电线向上接通流线+auth;循环拥有迭代,重试/倒置,收缩,输出-预算序列化,以及探测器合同.

### 典型配对

| 惠璶 | 添加 |
| --- | --- |
| LLM 提供者( Ollama / OpenAI / 云) | [`@burtson-labs/agent-adapters-provider`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-provider) |
| 在节点上运行( shell + 文件系统) | [`@burtson-labs/agent-adapters-node`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-node) |
| 在浏览器中运行 | [`@burtson-labs/agent-adapters-web`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-web) |
| 在 VS 代码扩展内运行 | [`@burtson-labs/agent-adapters-vscode`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-vscode) |
| 从 GitHub 动作中运行 | [`@burtson-labs/agent-adapters-github`](https://www.npmjs.com/package/@burtson-labs/agent-adapters-github) |
| 记忆/钩子 / `@`\-mentions/额外工具 | [`@burtson-labs/host-kit`](https://www.npmjs.com/package/@burtson-labs/host-kit) |
| 预建运行时间( CLI + 扩展平价) | [`@burtson-labs/stealth-core-runtime`](https://www.npmjs.com/package/@burtson-labs/stealth-core-runtime) |
| 对应计划/ 聊天/ diff/ 遥测的 UI | [`@burtson-labs/agent-ui`](https://www.npmjs.com/package/@burtson-labs/agent-ui) |

## ![](https://icons.burtson.ai/svg-accent/blocks.svg) 里面的东西

| 路径 | 目的 |
| --- | --- |
| `src/tools/tool-use-loop.ts` | 循环本身。 管弦乐 LLM调用 → 响应解析 → 探测器通过 → 工具执行 → 重复. |
| `src/tools/tool-use-parser.ts` | 摘录 `<tool_call>` 信封(XML、栅栏、赤色JSON、烟花倒置). |
| `src/tools/tool-registry.ts` | 工具注册+ Ollama 本地- schema 生成 `tools` 字段. |
| `src/tools/core-tools.ts` | 内置工具 : `read_file`, (中文(简体) ), `apply_edit`, (中文(简体) ), `apply_patch`, (中文(简体) ), `run_command`, (中文(简体) ), `git_*`等 (中文(简体) ). |
| `src/tools/compactMessages.ts` | 当信息输入预算时, 贪婪地压缩了陈旧的工具结果信息 . |
| `src/tools/post-edit-checks.ts` | TS/TSX编辑后自动打字检查. |
| `src/security/secretPatterns.ts` | 秘密检测+ `redactSecretsString` (随处使用用户/工具文本被浮出). |
| `src/telemetry/otlpExporter.ts` | 缩入,无 SDK OTLP 出口国(`TelemetryExporter`, (中文(简体) ), `resolveTelemetryConfig`) 主机不可知(Web Crypto +) `fetch`; 将一个转动图绘制为跟踪+指使/TTFT/期限度量衡。 由CLI和IDE主机共享. |

## ![](https://icons.burtson.ai/svg-accent/beaker.svg) 正在测试

```bash
pnpm --filter @burtson-labs/agent-core test
```

套房是分开的 **合成合同测试** (每个探测器集群一个文件)和 **实时重播测试** (从 `.bandit/turns/` 通过新循环重放 :

| 关切 | 文件 |
| --- | --- |
| 构造器选项合并为运行时间 | [试验/建造者](https://npmcn.com/package/%40burtson-labs/agent-core/test/constructorOptionsContract.test.ts) |
| "要求不做"探测器(假的完成,部分完成,宣布当时的安装) | [测试/要求,不做探测器. test.ts](https://npmcn.com/package/%40burtson-labs/agent-core/test/claimWithoutDoingDetectors.test.ts) |
| "Structured expert 代替工具"探测器(代码-fence,JSON-todo自动促进) | [测试/结构化输出检测器. test.ts](https://npmcn.com/package/%40burtson-labs/agent-core/test/structuredOutputDetectors.test.ts) |
| 循环探测器(反弹出声、去声出声) | [测试/探测器. test.ts](https://npmcn.com/package/%40burtson-labs/agent-core/test/loopDetectors.test.ts) |
| 修复/空修复(空修复、思考后修复、剖析后修复) | [测试/成型](https://npmcn.com/package/%40burtson-labs/agent-core/test/malformedEmptyDetectors.test.ts) |
| 迷幻剂 `<tool_result>` 恢复 | [试验/卤化探测器](https://npmcn.com/package/%40burtson-labs/agent-core/test/hallucinationDetectors.test.ts) |
| 副代理人协调(被烧毁被遗忘) | [试验/增殖剂 协调探测器. test.ts](https://npmcn.com/package/%40burtson-labs/agent-core/test/subagentCoordinationDetectors.test.ts) |
| 工具执行边缘大小写( dedup, 上限, 重复破解器, 未发现, 出错, 待办事宜进度) | [测试/工具](https://npmcn.com/package/%40burtson-labs/agent-core/test/toolExecutionDetectors.test.ts) |
| 取消合同 | [测试/取消](https://npmcn.com/package/%40burtson-labs/agent-core/test/cancellationContract.test.ts) |
| 压缩+瞄准器合同 | [试验/合同](https://npmcn.com/package/%40burtson-labs/agent-core/test/compactionContract.test.ts) |
| 真实追踪重放 | [测试/回放 Replay.test.ts](https://npmcn.com/package/%40burtson-labs/agent-core/test/turnReplay.test.ts) |

### 从真实的故障跟踪中添加回归固定

当你在真实运行中看到一个怪异的代理行为时,将转动日志固定器放下去测试套件,这样未来的循环变化就不能默默地倒退. **见 [测试/固定/转弯/README.md](https://npmcn.com/package/%40burtson-labs/agent-core/test/fixtures/turns/README.md)** 用于完整指南——重放-完成性限制,命名惯例,断言什么,以及复制-复制测试模板.

## ![](https://icons.burtson.ai/svg-accent/book-open.svg) 公约

-   **每个探测器每转一发.** 每个 `tool_loop:*_nudge` 在循环终止或模型恢复之前,事件起火最多一次。 添加新的探测器意味着添加出门旗+合同测试.
-   **构造器选项必须流到运行时间 .** `ToolUseLoopOptions` 适用于每个 `runWithMessages` 电话 合并发生于 `runWithMessages` 看到了吗 `effectiveOptions = { ...defaultOptions, ...perCall }`新选项需要相应的条目 [试验/建造者](https://npmcn.com/package/%40burtson-labs/agent-core/test/constructorOptionsContract.test.ts) (文件的详尽性检查失败, 如果你忘了的话) .
-   **帮手进去 `test/_helpers.ts`; 重新播放带入 `test/_replay.ts`。 。 。 .** 两个文件名称从 `_` 所以他们被排除在vitest的之外 `test/**/*.test.ts` glo.

## ![](https://icons.burtson.ai/svg-accent/network.svg) 框架中的立场

```
[host: VS Code extension or CLI]
              │
              ▼
       ┌──────────────┐
       │ ToolUseLoop  │  ← this package
       └──────┬───────┘
              │
        ┌─────┴─────┐
        ▼           ▼
 [tool registry]   [chat function]
        │              │
        ▼              ▼
  [host-kit tools]   [Ollama / Bandit cloud / etc.]
```

循环是主机不可知. 主机连接聊天功能(使用自己的监听/流出/认证),并提供一个工具注册;循环拥有迭代,重试/倒置政策,收缩,输出-预算序列化,以及检测器合同.

## 许可证

[Apache 许可证 2.0](https://npmcn.com/package/LICENSE) ——版权2026 Burtson Labs.

## 常见问题

### @burtson-labs/agent-core 是什么？

土匪代理框架的核心推理和规划引擎\.

### 如何安装 @burtson-labs/agent-core？

在项目目录运行 npm install @burtson-labs/agent-core，或使用 pnpm add / yarn add / bun add。

### @burtson-labs/agent-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @burtson-labs/agent-core 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @burtson-labs/agent-core 可以商用吗？

@burtson-labs/agent-core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @burtson-labs/agent-core 的下载量有多少？

根据 npm 官方下载统计，@burtson-labs/agent-core 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,099 次，日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @burtson-labs/agent-core 还在维护吗？

最新版本 1\.6\.96 发布于 2026/11/08（今天）；至今共发布 81 个版本，其中过去 12 个月发布了 81 个；首次发布于 2026/06/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。