# @codeany/open-agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40codeany/open-agent-sdk/

版本：0\.2\.4
npm 元数据更新时间：2026-07-26T03:23:21.614Z
中文译文更新时间：2026-11-10T06:07:18.400Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codeany/open-agent-sdk
原文对照：https://npmcn.com/package/%40codeany/open-agent-sdk/?lang=original
项目主页：https://github.com/codeany-ai/open-agent-sdk-typescript
源码仓库：https://github.com/codeany-ai/open-agent-sdk-typescript

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

- 包体积（解压后）：503 kB，215 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- 首次发布：2026-04-01T10:09:23.350Z
- 最新版本发布：2026-07-26T03:23:21.442Z
- 近 30 天下载量：6142（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

开源代理SDK. 运行全代理循环进程——不需要本地CLI. 任何地方部署:云,无服务器,多克,CI/CD.

## 安装

```sh
npm install @codeany/open-agent-sdk
```

也可以使用：`pnpm add @codeany/open-agent-sdk`、`yarn add @codeany/open-agent-sdk`、`bun add @codeany/open-agent-sdk`

## README

# 打开代理 SDK (TypeScript)

[![npm version](https://img.shields.io/npm/v/@codeany/open-agent-sdk)](https://www.npmjs.com/package/@codeany/open-agent-sdk) [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://npmcn.com/package/%40codeany/open-agent-sdk/LICENSE)

运行全代理循环的开源代理 SDK **正在处理** ——不需要子进程或CLI. 支持两者 **安东尼** 财务报告和审定财务报表 **OpenAI 兼容** APIs (英语). 任何地方部署:云,无服务器,多克,CI/CD.

也可查阅 **走开**数字 : [打开代理服务器 sdk-go](https://github.com/codeany-ai/open-agent-sdk-go)

## 开始吧

```bash
npm install @codeany/open-agent-sdk
```

设置您的 API 密钥 :

```bash
export CODEANY_API_KEY=your-api-key
```

### OpenAI 兼容模型

与 OpenAI, DeepSeek, Quen, Mistral 或任何 OpenAI 兼容端点合作 :

```bash
export CODEANY_API_TYPE=openai-completions
export CODEANY_API_KEY=sk-...
export CODEANY_BASE_URL=https://api.openai.com/v1
export CODEANY_MODEL=gpt-4o
```

### 第三方兼容供应商

```bash
export CODEANY_BASE_URL=https://openrouter.ai/api
export CODEANY_API_KEY=sk-or-...
export CODEANY_MODEL=anthropic/claude-sonnet-4
```

## 快开始

### 一发查询( 流出)

```typescript
import { query } from "@codeany/open-agent-sdk";

for await (const message of query({
  prompt: "Read package.json and tell me the project name.",
  options: {
    allowedTools: ["Read", "Glob"],
    permissionMode: "bypassPermissions",
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
}
```

### 简单的屏蔽提示

```typescript
import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({ model: "claude-sonnet-4-6" });
const result = await agent.prompt("What files are in this project?");

console.log(result.text);
console.log(
  `Turns: ${result.num_turns}, Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`,
);
```

### OpenAI / GBT 模型

```typescript
import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({
  apiType: "openai-completions",
  model: "gpt-4o",
  apiKey: "sk-...",
  baseURL: "https://api.openai.com/v1",
});

const result = await agent.prompt("What files are in this project?");
console.log(result.text);
```

这个 `apiType` 自动从模型名称中检测到的模型 `gpt-`, (中文(简体) ), `o1`, (中文(简体) ), `o3`, (中文(简体) ), `deepseek`, (中文(简体) ), `qwen`, (中文(简体) ), `mistral`等自动使用 `openai-completions`。 。 。 .

### 多回合对话

```typescript
import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({ maxTurns: 5 });

const r1 = await agent.prompt(
  'Create a file /tmp/hello.txt with "Hello World"',
);
console.log(r1.text);

const r2 = await agent.prompt("Read back the file you just created");
console.log(r2.text);

console.log(`Session messages: ${agent.getMessages().length}`);
```

### 自定义工具( Zod schema)

```typescript
import { z } from "zod";
import { query, tool, createSdkMcpServer } from "@codeany/open-agent-sdk";

const getWeather = tool(
  "get_weather",
  "Get the temperature for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city}: 22°C, sunny` }],
  }),
);

const server = createSdkMcpServer({ name: "weather", tools: [getWeather] });

for await (const msg of query({
  prompt: "What is the weather in Tokyo?",
  options: { mcpServers: { weather: server } },
})) {
  if (msg.type === "result")
    console.log(`Done: $${msg.total_cost_usd?.toFixed(4)}`);
}
```

### 自定义工具( 低级)

```typescript
import {
  createAgent,
  getAllBaseTools,
  defineTool,
} from "@codeany/open-agent-sdk";

const calculator = defineTool({
  name: "Calculator",
  description: "Evaluate a math expression",
  inputSchema: {
    type: "object",
    properties: { expression: { type: "string" } },
    required: ["expression"],
  },
  isReadOnly: true,
  async call(input) {
    const result = Function(`'use strict'; return (${input.expression})`)();
    return `${input.expression} = ${result}`;
  },
});

const agent = createAgent({ tools: [...getAllBaseTools(), calculator] });
const r = await agent.prompt("Calculate 2**10 * 3");
console.log(r.text);
```

### 技能

技能是可重复使用的可扩展代理能力的即时模板. 包括五个捆绑的技能: `simplify`, (中文(简体) ), `commit`, (中文(简体) ), `review`, (中文(简体) ), `debug`, (中文(简体) ), `test`。 。 。 .

```typescript
import {
  createAgent,
  registerSkill,
  getAllSkills,
} from "@codeany/open-agent-sdk";

// Register a custom skill
registerSkill({
  name: "explain",
  description: "Explain a concept in simple terms",
  userInvocable: true,
  async getPrompt(args) {
    return [
      {
        type: "text",
        text: `Explain in simple terms: ${args || "Ask what to explain."}`,
      },
    ];
  },
});

console.log(`${getAllSkills().length} skills registered`);

// The model can invoke skills via the Skill tool
const agent = createAgent();
const result = await agent.prompt('Use the "explain" skill to explain git rebase');
console.log(result.text);
```

### 虎克(生命周期事件)

```typescript
import { createAgent, createHookRegistry } from "@codeany/open-agent-sdk";

const hooks = createHookRegistry({
  PreToolUse: [
    {
      handler: async (input) => {
        console.log(`About to use: ${input.toolName}`);
        // Return { block: true } to prevent tool execution
      },
    },
  ],
  PostToolUse: [
    {
      handler: async (input) => {
        console.log(`Tool ${input.toolName} completed`);
      },
    },
  ],
});
```

20起生命周期事件: `PreToolUse`, (中文(简体) ), `PostToolUse`, (中文(简体) ), `PostToolUseFailure`, (中文(简体) ), `SessionStart`, (中文(简体) ), `SessionEnd`, (中文(简体) ), `Stop`, (中文(简体) ), `SubagentStart`, (中文(简体) ), `SubagentStop`, (中文(简体) ), `UserPromptSubmit`, (中文(简体) ), `PermissionRequest`, (中文(简体) ), `PermissionDenied`, (中文(简体) ), `TaskCreated`, (中文(简体) ), `TaskCompleted`, (中文(简体) ), `ConfigChange`, (中文(简体) ), `CwdChanged`, (中文(简体) ), `FileChanged`, (中文(简体) ), `Notification`, (中文(简体) ), `PreCompact`, (中文(简体) ), `PostCompact`, (中文(简体) ), `TeammateIdle`。 。 。 .

### MCP 服务器集成

```typescript
import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    },
  },
});

const result = await agent.prompt("List files in /tmp");
console.log(result.text);
await agent.close();
```

### 副剂

```typescript
import { query } from "@codeany/open-agent-sdk";

for await (const msg of query({
  prompt: "Use the code-reviewer agent to review src/index.ts",
  options: {
    agents: {
      "code-reviewer": {
        description: "Expert code reviewer",
        prompt: "Analyze code quality. Focus on security and performance.",
        tools: ["Read", "Glob", "Grep"],
      },
    },
  },
})) {
  if (msg.type === "result") console.log("Done");
}
```

### 权限

```typescript
import { query } from "@codeany/open-agent-sdk";

// Read-only agent — can only analyze, not modify
for await (const msg of query({
  prompt: "Review the code in src/ for best practices.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk",
  },
})) {
  // ...
}
```

### 网络用户界面

包含一个内置的网络聊天界面用于测试:

```bash
npx tsx examples/web/server.ts
# Open http://localhost:8081
```

## API 参考

### 高级职能

| 函数 | 说明 |
| --- | --- |
| `query({ prompt, options })` | 一发流查询, 返回 `AsyncGenerator<SDKMessage>` |
| `createAgent(options)` | 创建一个具有会话持久性的可重复使用的代理 |
| `tool(name, desc, schema, handler)` | 用 Zod schema 验证创建工具 |
| `createSdkMcpServer({ name, tools })` | 装入进程内 MCP 服务器的工具 |
| `defineTool(config)` | 低级工具定义助手 |
| `getAllBaseTools()` | 获取全部 35+ 内置工具 |
| `registerSkill(definition)` | 注册自定义技能 |
| `getAllSkills()` | 获得所有注册技能 |
| `createProvider(apiType, opts)` | 直接创建 LLM 提供者 |
| `createHookRegistry(config)` | 为生命周期事件创建钩子注册 |
| `listSessions()` | 连续会议清单 |
| `forkSession(id)` | 为分枝分叉会话 |

### 代理方法

| 方法 | 说明 |
| --- | --- |
| `agent.query(prompt)` | 流转查询、返回 `AsyncGenerator<SDKMessage>` |
| `agent.prompt(text)` | 屏蔽查询, 返回 `Promise<QueryResult>` |
| `agent.getMessages()` | 获取对话历史 |
| `agent.clear()` | 重设会话 |
| `agent.interrupt()` | 中止当前查询 |
| `agent.setModel(model)` | 更改模式会议中期 |
| `agent.setPermissionMode(mode)` | 更改权限模式 |
| `agent.getApiType()` | 获取当前 API 类型 |
| `agent.close()` | 关闭 MCP 连接, 持续会话 |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiType` | `string` | 自动检测 | `'anthropic-messages'` 或者说 `'openai-completions'` |
| `model` | `string` | `claude-sonnet-4-6` | LLM 型号 ID |
| `apiKey` | `string` | `CODEANY_API_KEY` | API 密钥 |
| `baseURL` | `string` | —— 说 | 自定义 API 端点 |
| `cwd` | `string` | `process.cwd()` | 工作目录 |
| `systemPrompt` | `string` | —— 说 | 系统即时覆盖 |
| `appendSystemPrompt` | `string` | —— 说 | 附加到默认系统提示 |
| `tools` | `ToolDefinition[]` | 全部内置 | 可用工具 |
| `allowedTools` | `string[]` | —— 说 | 工具允许列表 |
| `disallowedTools` | `string[]` | —— 说 | 工具拒绝列表 |
| `permissionMode` | `string` | `bypassPermissions` | `default` 编号 : `acceptEdits` 编号 : `dontAsk` 编号 : `bypassPermissions` 编号 : `plan` |
| `canUseTool` | `function` | —— 说 | 自定义权限回调 |
| `maxTurns` | `number` | `10` | 最大代理转弯 |
| `maxBudgetUsd` | `number` | —— 说 | 支出上限 |
| `thinking` | `ThinkingConfig` | `{ type: 'adaptive' }` | 扩展思维 |
| `effort` | `string` | `high` | 合理努力: `low` 编号 : `medium` 编号 : `high` 编号 : `max` |
| `mcpServers` | `Record<string, McpServerConfig>` | —— 说 | MCP 服务器连接 |
| `agents` | `Record<string, AgentDefinition>` | —— 说 | 亚剂定义 |
| `hooks` | `Record<string, HookCallbackMatcher[]>` | —— 说 | 生命周期钩 |
| `resume` | `string` | —— 说 | 通过 ID 恢复会话 |
| `continue` | `boolean` | `false` | 继续最近的会话 |
| `persistSession` | `boolean` | `true` | 坚持到磁盘 |
| `sessionId` | `string` | 自动 | 明确会话编号 |
| `outputFormat` | `{ type: 'json_schema', schema }` | —— 说 | 结构化产出 |
| `sandbox` | `SandboxSettings` | —— 说 | 文件系统/网络沙盒 |
| `settingSources` | `SettingSource[]` | —— 说 | 装入 AGENT.md, 项目设置 |
| `env` | `Record<string, string>` | —— 说 | 环境变量 |
| `abortController` | `AbortController` | —— 说 | 取消控制器 |

### 环境变量

| 变量 | 说明 |
| --- | --- |
| `CODEANY_API_KEY` | API 密钥( 需要) |
| `CODEANY_API_TYPE` | `anthropic-messages` (违约)或 `openai-completions` |
| `CODEANY_MODEL` | 默认模式覆盖 |
| `CODEANY_BASE_URL` | 自定义 API 端点 |
| `CODEANY_AUTH_TOKEN` | 替代认证符 |

## 内建工具

| 工具 | 说明 |
| --- | --- |
| **巴许** | 执行 shell 命令 |
| **读取** | 读取有行号的文件 |
| **写入** | 创建/ 覆盖文件 |
| **编辑** | 文件精确字符串替换 |
| **光环** | 按模式查找文件 |
| **Grep 读取** | 以 regex 搜索文件内容 |
| **Web ưμ㼯A** | 获取和剖析网页内容 |
| **网络搜索** | 搜索网络 |
| **笔记本编辑** | 编辑 Jupyter 笔记本单元格 |
| **探员** | 用于并行工作的后继剂 |
| **技能** | 启动注册技能 |
| **任务创建/列表/更新/获取/停止/输出** | 任务管理系统 |
| **团队创建/删除** | 多代理人小组协调 |
| **发送消息** | 代理通讯 |
| **EnterWorktree/出厂树** | Git 工作树隔离 |
| **输入 Plan 模式/ 退出 Plan 模式** | 结构化规划工作流程 |
| **询问用户问题** | 询问用户输入 |
| **工具搜索** | 发现懒惰工具 |
| **ListMcp 资源/读取Mcp 资源** | MCP 资源访问 |
| **创造/删除/列表** | 计划任务管理 |
| **远程调试器** | 远程代理触发器 |
| **LSP 软件** | 语言服务器协议(代码智能) |
| **配置** | 动态配置 |
| **写入** | 会话待办事宜列表 |

## 包扎技能

| 技能 | 说明 |
| --- | --- |
| `simplify` | 审查更改的再利用代码、质量和效率 |
| `commit` | 以精心设计的信息创建 git 承诺 |
| `review` | 审查代码更改的正确性、安全和性能 |
| `debug` | 利用结构化调查系统调试 |
| `test` | 运行测试和分析失败 |

注册自定义技能 `registerSkill()`。 。 。 .

## 建筑

```
┌──────────────────────────────────────────────────────┐
│                   Your Application                    │
│                                                       │
│   import { createAgent } from '@codeany/open-agent-sdk' │
└────────────────────────┬─────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │       Agent         │  Session state, tool pool,
              │  query() / prompt() │  MCP connections, hooks
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │    QueryEngine      │  Agentic loop:
              │   submitMessage()   │  API call → tools → repeat
              └──────────┬──────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
   ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
   │  Provider  │  │  35 Tools │  │    MCP     │
   │ Anthropic  │  │ Bash,Read │  │  Servers   │
   │  OpenAI    │  │ Edit,...  │  │ stdio/SSE/ │
   │ DeepSeek   │  │ + Skills  │  │ HTTP/SDK   │
   └───────────┘  └───────────┘  └───────────┘
```

**关键内部:**

| 构成部分 | 说明 |
| --- | --- |
| **提供者层** | 抽象 Anthropic / OpenAI API 差异 |
| **查询引擎** | 具有自动压缩、重试、工具管弦的核心代理循环 |
| **技能系统** | 可重用具有5个捆绑技能的快速模板 |
| **钩子系统** | 20起生命周期事件纳入引擎 |
| **自动压缩** | 上下文窗口填充时摘要对话框 |
| **微协议** | 截断过大的工具结果 |
| **重试** | 利率限制和瞬间出错的指向后退 |
| **托肯估计** | Claude、GPT、DeepSeek模型的定价 |
| **文件缓存** | 文件读取的 LRU 缓存( 100个条目, 25 MB) |
| **会话存储** | 磁盘上坚持/恢复/分叉会话 |
| **上下文注射** | Git 状态 + AGENT.md 自动注入系统提示 |

## 实例

| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 文件 | 说明 |
| --- | --- | --- |
| 01号 | `examples/01-simple-query.ts` | 用事件处理来流转查询 |
| 第02条 | `examples/02-multi-tool.ts` | 多工具管弦乐( Glob + Bash) |
| 03号 | `examples/03-multi-turn.ts` | 多回合持续 |
| 04号 | `examples/04-prompt-api.ts` | 封锁 `prompt()` API 密码 |
| 05号 | `examples/05-custom-system-prompt.ts` | 自定义系统提示 |
| 06号 | `examples/06-mcp-server.ts` | MCP 服务器集成 |
| 07号 | `examples/07-custom-tools.ts` | 自定义工具 `defineTool()` |
| 08号 | `examples/08-official-api-compat.ts` | `query()` API 模式 |
| 09个 | `examples/09-subagents.ts` | 副代表代表团 |
| 10个 | `examples/10-permissions.ts` | 带有工具限制的只读代理 |
| 第11个 | `examples/11-custom-mcp-tools.ts` | `tool()` + 键 `createSdkMcpServer()` |
| 第12条 | `examples/12-skills.ts` | 技能系统使用情况 |
| 第13条 | `examples/13-hooks.ts` | 生命周期钩 |
| 页:1 | `examples/14-openai-compat.ts` | OpenAI / 深搜索模式 |
| 网络 | `examples/web/` | 用于测试的网络聊天 UI |

运行任意示例 :

```bash
npx tsx examples/01-simple-query.ts
```

启动网络用户界面 :

```bash
npx tsx examples/web/server.ts
```

## 恒星历史

[![Star History Chart](https://api.star-history.com/image?repos=codeany-ai/open-agent-sdk-typescript&type=timeline&legend=top-left)](https://www.star-history.com/?repos=codeany-ai%2Fopen-agent-sdk-typescript&type=timeline&legend=top-left)

## 许可证

麻省理工学院

## 常见问题

### @codeany/open-agent-sdk 是什么？

开源代理SDK\. 运行全代理循环进程——不需要本地CLI\. 任何地方部署:云,无服务器,多克,CI/CD\.

### 如何安装 @codeany/open-agent-sdk？

在项目目录运行 npm install @codeany/open-agent-sdk，或使用 pnpm add / yarn add / bun add。

### @codeany/open-agent-sdk 支持 TypeScript 吗？

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

### @codeany/open-agent-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @codeany/open-agent-sdk 需要什么版本的 Node\.js？

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

### @codeany/open-agent-sdk 可以商用吗？

@codeany/open-agent-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codeany/open-agent-sdk 的下载量有多少？

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

### @codeany/open-agent-sdk 还在维护吗？

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