# @backendkit-labs/agent-coding 中文文档

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

版本：0\.28\.4
npm 元数据更新时间：2026-10-28T14:42:58.799Z
中文译文更新时间：2026-11-07T19:55:48.778Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40backendkit-labs/agent-coding
原文对照：https://npmcn.com/package/%40backendkit-labs/agent-coding/?lang=original
项目主页：https://github.com/BackendKit-labs/backendkit-agent-framework#readme
源码仓库：https://github.com/BackendKit-labs/backendkit-agent-framework

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

- 包体积（解压后）：647 kB，258 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：5 个
- 首次发布：2026-06-04T21:32:18.664Z
- 最新版本发布：2026-10-28T14:42:58.174Z
- 近 30 天下载量：2856（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

@ backendkit-labs/ agent-core 的编码代理配置和工具

## 安装

```sh
npm install @backendkit-labs/agent-coding
```

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

## README

# @ backendkit-labs/ 代理编码

生产准备编码代理引擎 `@backendkit-labs/agent-core`. Bundles 10个专业代理、文件系统工具、多供应商支持(DeepSeek、OpenAI、Anthropic、Ollama、Kimi、Grok)、自动堆栈检测、持续内存、QA审查、反射和管弦管——全部为单一 `createCodingEngine()` 电话.

[![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-coding)](https://www.npmjs.com/package/@backendkit-labs/agent-coding)

> **状态 : `stable`** ——保持并做好生产准备. 在试验阶段没有新的特点.

## 目录

-   [安装](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-installation)
-   [快开始](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-quick-start)
-   [创建编码引擎](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-createcodingengine)
-   [从配置创建编码引擎](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-createcodingenginefromconfig)
-   [供应商](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-providers)
-   [内设特工](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-built-in-agents)
-   [内建工具](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-built-in-tools)
-   [技术包](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-skill-packs)
-   [管弦管](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-orchestration-pipeline)
-   [反射引擎](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-reflection-engine)
-   [MCP 服务器集成](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-mcp-server-integration)
-   [多代理实例](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-multi-agent-examples)
-   [配置文件](https://npmcn.com/package/%40backendkit-labs/agent-coding/#readme-config-file)

* * *

## 安装

```bash
npm install @backendkit-labs/agent-coding
```

所有提供者适配器被捆绑——不需要单独的包.

* * *

## 快开始

```typescript
import { createCodingEngine } from '@backendkit-labs/agent-coding';

const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
  defaultProvider: 'deepseek',
});

await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
```

这个单调给你:10个专门的代理,文件系统工具(读/写/编辑/搜索),持续的项目内存,技能加载,和堆栈自动检测.

* * *

## 创建编码引擎

初等工厂. 返回配置齐全 `AgentEngine`。 。 。 .

### 选项参考

```typescript
interface CodingEngineOptions {
  // Required
  providers:       ProvidersConfig;
  defaultProvider: string;

  // Agents and engine
  defaultAgent?:          string;       // default: 'general'
  workingDir?:            string;       // default: process.cwd()
  maxIterations?:         number;       // default: 100
  maxParallelAgents?:     number;       // default: 6

  // I/O
  transport?:             Transport;    // default: StdoutTransport

  // App identity
  appName?:               string;       // default: 'bk-agent' — used for ~/.{appName}/

  // Persistence
  disablePersistence?:    boolean;      // skip ProjectStore (useful for testing)

  // MCP servers
  mcpServers?:            MCPServerConfig[];

  // Context sharing
  subAgentContextMessages?: number;    // messages visible to sub-agents (recommend 10-20)

  // Iteration control
  onToolApproval?:   (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
  onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
  onStep?:           (stats: IterationStats) => Promise<boolean>;

  // Orchestration
  orchestration?:    boolean | OrchestrationOptions;
}
```

### 最小设置

```typescript
const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: 'sk-...' } },
  defaultProvider: 'deepseek',
});
```

### 多个供应商

```typescript
const engine = createCodingEngine({
  providers: {
    deepseek:  { apiKey: process.env.DEEPSEEK_API_KEY! },
    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
    ollama:    { host: 'http://localhost:11434', model: 'llama3.2' },
  },
  defaultProvider: 'deepseek',
  // Each agent profile can specify a provider override
});
```

### 满腔乐曲

```typescript
const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: '...' } },
  defaultProvider: 'deepseek',
  orchestration:   true,
  // Enables:
  //   intent detection → domain detection → risk scoring
  //   policy engine → agent routing → QA auto-review → reflection
});
```

### 使用 MCP 服务器

```typescript
const engine = createCodingEngine({
  providers:       { openai: { apiKey: '...' } },
  defaultProvider: 'openai',
  mcpServers: [
    { name: 'github',   command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'],  env: { GITHUB_TOKEN: '...' } },
    { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
  ],
  subAgentContextMessages: 15,
});
```

### 手动批准工具

```typescript
const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: '...' } },
  defaultProvider: 'deepseek',
  onToolApproval:  async (toolName, agentId, argsPreview) => {
    const write = ['write_file', 'edit_file', 'run_command'];
    if (!write.includes(toolName)) return 'approve';
    console.log(`\n⚠  [${agentId}] ${toolName}:\n${argsPreview}\n`);
    const a = await prompt('Approve? (y/n/all): ');
    if (a === 'y')   return 'approve';
    if (a === 'all') return 'approve_all';
    return 'reject';
  },
});
```

* * *

## 从配置创建编码引擎

从 `~/.{appName}/config.json`。不需要更改代码以切换提供者 :

```typescript
import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';

const engine = createCodingEngineFromConfig();

// With overrides
const engine = createCodingEngineFromConfig({
  workingDir:    '/my-project',
  orchestration: true,
});
```

* * *

## 供应商

### 深层搜索

```typescript
providers: {
  deepseek: {
    apiKey:       process.env.DEEPSEEK_API_KEY!,
    model?:       'deepseek-chat',    // default
    maxTokens?:   8192,
    temperature?: 0.7,
  }
}
```

### 开放AI

```typescript
providers: {
  openai: {
    apiKey:   process.env.OPENAI_API_KEY!,
    model?:   'gpt-4o',
    baseUrl?: 'https://api.openai.com/v1',
  }
}
```

### Anthropic (克罗地亚)

```typescript
providers: {
  anthropic: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model?: 'claude-sonnet-4-6',    // default
  }
}
```

### Ollama( 本地- 无 API 密钥)

```bash
# Prerequisites
ollama serve
ollama pull llama3.2
```

```typescript
providers: {
  ollama: {
    host?:  'http://localhost:11434',
    model?: 'llama3.2',
  }
}
```

### OpenAI 兼容( Kimi, Grok, 任意端点)

```typescript
providers: {
  kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
  grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
  // Any OpenAI-compatible endpoint
  vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
}
```

* * *

## 内设特工

十个专家特工被捆绑起来。 Orchestration 路由自动任务;也可以明确选择.

| 代理身份证 | 专业 |
| --- | --- |
| `general` | 普通用途——默认起点 |
| `architect` | 系统设计、发展成果评估、架构决定 |
| `backend-agent` | API、服务器逻辑、数据库 |
| `frontend-agent` | 反应、 CSS、 无障碍、 UX |
| `devops-agent` | CI/CD、Docker、Kubernetes, 现列于下文 |
| `database-agent` | SQL, 索引, 迁移, 查询调试 |
| `security-reviewer` | 安全审计,OWASP,威胁模型制作 |
| `qa-engineer` | 测试策略、边缘案例、质量保证审查 |
| `documentation-agent` | 文档、 REDMEs、 API 文件、 更改日志 |
| `refactoring-agent` | 代码清理、技术债务、设计模式 |

### 选择代理

```typescript
await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
```

### 添加自定义代理

创建 `~/.bk-agent/agents/my-agent.json`数字 :

```json
{
  "id":           "my-agent",
  "name":         "My Custom Agent",
  "systemPrompt": "You are specialized in ...",
  "tools":        ["read_file", "run_command"],
  "provider":     "anthropic"
}
```

已自动装入——不需要更改代码 .

### 项目代理人和技能需要可信赖的项目

探员在 `{project}/.bk-agent/agents/` 和技能 `{project}/.bk-agent/skills/` 这是 **存储器** 内容,而不是你的:一个被克隆的回波可以运送一个代理,用它自己的即时和工具来取代内置的管弦乐器. 所以他们只为你信任的一个项目装上子弹 你自己的经纪人和技能 `~/.bk-agent/` 总是装入.

```text
/trust              # is this project trusted, and what would its project layer load
/trust add          # trust it (records the real path in ~/.bk-agent/trusted-projects.json)
/trust remove       # stop trusting it
/trust list
```

-   信任来自 **准确路径**: 信任 `~/code` 不相信里面克隆的仓库.
-   对于一个不值得信赖的项目,引擎发出警告,命名了被遗漏的东西. 技能负载紧接其后 `/trust add`; 代理下次开始时代理.
-   `BK_TRUST_PROJECT=1` 信任每个路径( CI, 容器) 。 自己决定的宿主可以通过 `trustedProject: true | false` 改为 `createCodingEngine`。 。 。 .
-   一个缺失或被损坏的信任文件意味着没有人被信任.

* * *

## 内建工具

所有特工都可以通过 `CODING_TOOLS`数字 :

| 工具 | 说明 |
| --- | --- |
| `read_file` | 通过路径读取文件 |
| `write_file` | 创建或覆盖文件 |
| `edit_file` | 对文件应用目标补丁 |
| `list_directory` | 在目录中列出文件 |
| `run_command` | 执行 shell 命令 |
| `search_files` | 递归内容搜索 |
| `save_context` | 写到 `session.md` (长篇注解) |
| `save_learning` | 附录 `lecciones-aprendidas.md` |
| `save_audit` | 写一个结构化的审计条目 |
| `get_latest_audit` | 阅读最新审计 |
| `list_audits` | 列表审计条目 |
| `save_user_preference` | 坚持用户偏好 |
| `update_session` | 更新正在取得进展的会议说明 |

* * *

## 技术包

根据检测到的项目堆栈激活内置包 :

| 包装 | 激活时间 |
| --- | --- |
| `GLOBAL_BUILTIN_SKILLS` | 所有项目 |
| `NODE_PACK_SKILLS` | 节点.js / TypeScript (`package.json`(中文(简体) ) |
| `GO_PACK_SKILLS` | 前进( G)`go.mod`(中文(简体) ) |
| `JAVA_PACK_SKILLS` | 爪哇语( Java)`pom.xml`, (中文(简体) ), `build.gradle`(中文(简体) ) |
| `KOTLIN_PACK_SKILLS` | 克特林/ Android (英语) |
| `PYTHON_PACK_SKILLS` | Py( 二`requirements.txt`, (中文(简体) ), `pyproject.toml`(中文(简体) ) |

* * *

## 管弦管

何时 `orchestration: true`在每次LLM呼叫之前,一个智能的路由层运行:

```
Input
  → Intent Detection (feature? bug? refactor? question?)
  → Domain Detection (backend? frontend? security? ops?)
  → Risk Scoring (reads only? writes files? runs commands?)
  → Policy Engine (enforce domain-level rules)
  → Agent Selection (best agent for detected domain + risk)
  → LLM Call
  → QA Review (auto-review code-heavy responses)
```

### 自定义管弦

```typescript
orchestration: {
  capabilityMatrix: {
    'my-specialist': {
      owns:       ['payments', 'billing'],
      skills:     ['typescript', 'stripe'],
      baseWeight: 0.95,
    },
  },
  customRules: [
    {
      if:   { domain: 'security' },
      then: { mustInclude: ['security-reviewer'] },
    },
  ],
  enableQA:   true,
  noQA:       false,
  onQAReview: (review) => logger.info('[QA]', review),
}
```

* * *

## 反射引擎

纵观失败

```typescript
orchestration: {
  reflection: true,
  // After each sprint:
  // 1. Failures logged to FailureCatalog
  // 2. Patterns with ≥3 occurrences promoted to PolicyRules
  // 3. lecciones-aprendidas.md updated
}
```

* * *

## MCP 服务器集成

```typescript
mcpServers: [
  {
    name:    'code-intelligence',
    command: 'bk-mcp',               // @backendkit-labs/mcp-server
    args:    [],
    env:     { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
  },
  {
    name:    'github',
    command: 'npx',
    args:    ['-y', '@modelcontextprotocol/server-github'],
    env:     { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
  },
],
subAgentContextMessages: 20,
```

* * *

## 多代理实例

### 特性实施

```typescript
await engine.run(`
  Implement JWT authentication middleware for Express:
  - Validate Bearer token in Authorization header
  - Attach decoded user to req.user
  - Return 401 with clear error messages
  - Include unit tests with valid/expired/malformed token cases
`);
// architect plans → backend-agent implements → qa-engineer writes tests
```

### 安保审计

```typescript
await engine.run(`
  Audit all routes in src/routes/ for:
  1. Missing auth middleware
  2. SQL injection vulnerabilities
  3. Exposed sensitive data
  Output a prioritized fix list.
`, { agentId: 'security-reviewer' });
```

### 数据库迁移

```typescript
await engine.run(`
  Write a zero-downtime migration: add NOT NULL column 
  'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
  Include rollback script and backfill strategy.
`, { agentId: 'database-agent' });
```

### 完整堆栈重构

```typescript
await engine.run(`
  Refactor auth from session cookies to JWT.
  Update both Express middleware and React login flow.
  Keep backward compatibility for 2 more sprints.
`);
// backend-agent + frontend-agent + security-reviewer
```

* * *

## 配置文件

`~/.bk-agent/config.json`数字 :

```json
{
  "defaultProvider": "deepseek",
  "providers": {
    "deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
    "anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
    "ollama":    { "host": "http://localhost:11434", "model": "llama3.2" }
  },
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxxx" }
    }
  ]
}
```

## 常见问题

### @backendkit-labs/agent-coding 是什么？

@ backendkit-labs/ agent-core 的编码代理配置和工具

### 如何安装 @backendkit-labs/agent-coding？

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

### @backendkit-labs/agent-coding 支持 TypeScript 吗？

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

### @backendkit-labs/agent-coding 支持 ESM 还是 CommonJS？

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

### @backendkit-labs/agent-coding 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @backendkit-labs/agent-coding 可以商用吗？

@backendkit-labs/agent-coding 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @backendkit-labs/agent-coding 的下载量有多少？

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

### @backendkit-labs/agent-coding 还在维护吗？

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