zerodiff-agent

English | 简体中文

zerodiff-agent 是一个用于构建 LLM Agent 的 TypeScript 库。你创建一个 Agent，传入 LLM 运行时和工具，然后调用 agent.run(...)。

能力总览

• LLM 后端：OpenAI 兼容 Chat Completions、OpenAI Responses API、Anthropic Messages API
• Agent 运行时：有状态会话、流式输出、reasoning 输出、详细运行结果、取消运行、上下文压缩
• 工具：Zod schema、自定义工具注册表、默认本地代码工具、hook 控制
• 模型：模型档案、运行时切换、按模型配置 endpoint、thinking 控制、reasoning effort 控制、计费元数据
• 配置：通过 loadAppConfig() 读取文件配置，并转换成 AgentConfig
• 可观测性：token 用量、缓存用量、上下文窗口用量、成本统计和回调 hooks
• Skills：从 data/skills 发现和加载
• 可选 CLI：基于 Ink 的本地交互式 Agent UI

安装

npm install zerodiff-agent openai

如果使用 Anthropic：

npm install zerodiff-agent @anthropic-ai/sdk

需要 Node.js 20+。

创建 Agent

import OpenAI from "openai";
import { Agent } from "zerodiff-agent";

const agent = new Agent({
  llm: {
    provider: "openai",
    client: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  },
  model: "gpt-4o-mini",
});

提问

const answer = await agent.run("读取 package.json 并总结这个项目。");
console.log(answer);

流式输出：

await agent.run("解释源码目录结构。", {
  onChunk: (text) => process.stdout.write(text),
});

观察 reasoning、工具和用量事件：

await agent.run("检查工作区。", {
  onThinkingChunk: (text) => console.error(text),
  onToolCall: (name, args) => console.log("tool", name, args),
  onToolResult: (name, result) => console.log("result", name, result),
  onTurnCost: (cost) => console.log(cost),
  onContextUsage: (usage) => console.log(usage),
});

保留会话状态：

const session = agent.createSession();

await agent.run("找出主入口文件。", { session });
await agent.run("现在解释为什么它是入口。", { session });

主动压缩会话：

const result = await agent.compressSession({
  session,
  keepRecent: 4,
  onContextCompression: (phase) => console.log(phase),
});

console.log(result.compressed, result.summaryTokens);

读取运行结果：

const result = await agent.run("准备发布检查清单。", {
  onTurnCost: (cost) => console.log(cost),
  onContextUsage: (usage) => console.log(usage),
});

取消运行：

const controller = new AbortController();

await agent.run("分析这个仓库。", {
  signal: controller.signal,
});

配置模型

简单使用时，model 可以只是模型 id：

const agent = new Agent({ llm, model: "gpt-4o-mini" });

多个模型时，把完整档案放在 models[]，model 只负责选择当前 id：

const agent = new Agent({
  llm,
  model: "gpt-5.5",
  models: [
    {
      id: "gpt-5.5",
      provider: "openai",
      baseUrl: "https://api.openai.com/v1/responses",
      controls: { reasoningEffort: "high" },
      capabilities: {
        thinking: true,
        reasoningEfforts: ["high", "xhigh"],
      },
    },
    {
      id: "claude-sonnet-4-5",
      provider: "anthropic",
    },
  ],
});

const session = agent.createSession();
agent.switchModel("claude-sonnet-4-5", session);

OpenAI 兼容模型的 baseUrl 以 /responses 结尾时使用 Responses API，否则使用 Chat Completions。

模型档案可以包含 provider、apiKey、baseUrl、stream、contextWindowTokens、controls、capabilities 和 billing。

使用配置文件

如果更适合用文件配置，可以使用 loadAppConfig()：

import { createAgentConfig, createLlmRuntime, loadAppConfig } from "zerodiff-agent";

const appConfig = loadAppConfig(process.cwd());
const llm = createLlmRuntime(appConfig);
const agent = new Agent(createAgentConfig(appConfig, llm));

最小 data/config/config.json：

{
  "llm": {
    "provider": "openai",
    "apiKey": "REPLACE_WITH_YOUR_LLM_API_SECRET",
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "models": [
      {
        "id": "gpt-4o-mini",
        "provider": "openai",
        "baseUrl": "https://api.openai.com/v1"
      }
    ],
    "maxOutputTokens": 8192,
    "stream": true,
    "controls": {}
  },
  "agent": {
    "maxSteps": 25
  }
}

旧的顶层配置字段会直接报错。请使用嵌套的 llm 和 agent 字段。

调用 loadAppConfig() 时，也会写入当前结构的 data/config/config.example.json。

工具

默认 Agent 包含本地代码工具：shell、glob、grep、文件读写编辑 diff、todo、Skill 加载。

需要更小权限面时替换工具集：

import { Agent, defineTool } from "zerodiff-agent";
import { z } from "zod";

const getIssue = defineTool({
  name: "get_issue",
  description: "根据 id 获取 issue。",
  schema: z.strictObject({
    id: z.number().int().positive(),
  }),
  async execute({ id }) {
    return { success: true, issue: await issueClient.get(id) };
  },
});

const agent = new Agent({
  llm,
  model: "gpt-4o-mini",
  toolsOverride: [getIssue],
});

工具返回值必须可 JSON 序列化。预期失败用 success: false 和 error 表达。

运行 hook：

const session = agent.createSession();

await agent.run("检查仓库。", {
  session,
  onPreToolUse: ({ toolName, args }) => {
    if (toolName === "shell" && String((args as { command?: unknown }).command).includes("rm -rf")) {
      return { action: "block", reason: "拒绝危险命令" };
    }
  },
  onPreCompact: ({ messages }) => {
    saveFullContext(messages);
  },
  onPostCompact: ({ messagesAfter }) => ({
    messages: [
      { role: "user", content: "继续遵守项目约束。" },
      ...messagesAfter,
    ],
  }),
});

session.enqueueUserGuidance("上一轮完成后，优先解释风险。");

Skills

Skill 是 data/skills 下的指令包。目录中需要有 SKILL.md 或 skill.md，且 YAML frontmatter 包含 description。

默认 skill provider 会把 skill 目录注入系统提示词。内置 list_skills 和 load_skill 工具可让 Agent 查看并加载 Skill 指令。

const agent = new Agent({
  llm,
  model: "gpt-4o-mini",
  listSkillsInPrompt: false,
});

可选 CLI

包也导出了基于 Ink 的 CLI：

import { createAgentConfig, createLlmRuntime, loadAppConfig } from "zerodiff-agent";
import { startCLI } from "zerodiff-agent/cli";

const appConfig = loadAppConfig(process.cwd());
startCLI(createAgentConfig(appConfig, createLlmRuntime(appConfig)));

CLI 命令包括 /models、/model <id>、/tokens、/messages、/prompt、/thinking 和 /effort。

公共 API

• Agent、AgentSession、runLoop
• defineTool、createToolRegistry、createDefaultToolRegistry、coreTools
• loadAppConfig、createAgentConfig、createLlmRuntime
• discoverSkills、loadSkill、loadSkillByName
• AgentAbortError、isAbortError、throwIfAborted
• startCLI 从 zerodiff-agent/cli 导入