第 66 章：你的 Agent 框架

// → src/my-agent/framework.ts
import { ApiClient, type ApiClientConfig } from "./api-client";
import { AgentLoop, type AgentConfig } from "./agent-loop";
import { ToolRouter, type ToolDescriptor } from "./tools/router";
import { ParallelScheduler } from "./tools/scheduler";
import { SubAgentSpawner } from "./subagent/spawner";
import { SkillLoader, SkillInjector } from "./skills";
import { ConfigLoader, type AgentConfig as AppConfig } from "./config";
import { McpClient } from "./mcp/client";

export class AgentFramework {
  // 核心组件
  readonly config: AppConfig;
  readonly client: ApiClient;
  readonly router: ToolRouter;
  readonly scheduler: ParallelScheduler;
  readonly skills: { loader: SkillLoader; injector: SkillInjector };
  readonly subAgents: SubAgentSpawner;

  // MCP 连接
  private mcpClients = new Map<string, McpClient>();

  constructor(config: AppConfig) {
    this.config = config;

    // 1. API Client
    this.client = new ApiClient({
      apiKey: config.apiKey!,
      baseUrl: config.baseUrl,
    });

    // 2. Tool Router
    this.router = new ToolRouter();

    // 3. Parallel Scheduler
    this.scheduler = new ParallelScheduler(this.router);

    // 4. Skill System
    this.skills = {
      loader: new SkillLoader(),
      injector: new SkillInjector(new SkillLoader()),
    };

    // 5. SubAgent Spawner
    this.subAgents = new SubAgentSpawner(this.client);
  }

  // === 初始化 ===

  async initialize(): Promise<void> {
    // 加载 Skills
    await this.skills.loader.loadFromDirectory("./skills");

    // 连接 MCP Servers
    if (this.config.mcpServers) {
      for (const [name, serverConfig] of Object.entries(this.config.mcpServers)) {
        if (serverConfig.type === "stdio") {
          const mcpClient = new McpClient(serverConfig.command!, serverConfig.args!);
          await mcpClient.initialize();
          await mcpClient.listTools();
          this.router.registerMcp(mcpClient);
          this.mcpClients.set(name, mcpClient);
        }
      }
    }
  }

  // === 创建 Agent ===

  createAgent(options?: {
    systemPrompt?: string;
    tools?: ToolDescriptor[];
    skills?: string[];
    model?: string;
  }): AgentLoop {
    // 注册额外工具
    if (options?.tools) {
      for (const tool of options.tools) {
        this.router.register(tool);
      }
    }

    // 构建 system prompt（注入 Skill）
    let systemPrompt = options?.systemPrompt ?? "";
    if (options?.skills) {
      const skillDefs = options.skills
        .map(name => this.skills.loader.get(name))
        .filter(Boolean) as SkillDefinition[];
      systemPrompt = this.skills.injector.buildSystemPrompt(
        systemPrompt,
        skillDefs
      );
    }

    return new AgentLoop(
      this.client,
      this.router,
      {
        model: options?.model ?? this.config.model,
        maxTokens: this.config.maxTokens ?? 4096,
        maxIterations: this.config.maxIterations ?? 25,
        maxContextTokens: 180_000,
        tools: this.router.getToolDefinitions(),
        systemPrompt,
        outputConfig: { effort: this.config.effort ?? "high" },
      }
    );
  }

  // === 工具注册便捷方法 ===

  registerTool(descriptor: ToolDescriptor): void {
    this.router.register(descriptor);
  }

  registerMcpServer(name: string, config: McpServerConfig): void {
    this.config.mcpServers ??= {};
    this.config.mcpServers[name] = config;
  }

  // === 清理 ===

  async shutdown(): Promise<void> {
    for (const [name, mcpClient] of this.mcpClients) {
      mcpClient.close();
    }
    this.mcpClients.clear();
  }
}

// → examples/cli-chatbot.ts
import { AgentFramework } from "my-agent";
import { createInterface } from "node:readline";

async function main() {
  // 加载配置
  const configLoader = new ConfigLoader();
  await configLoader.loadAll(process.cwd());
  const config = configLoader.resolve();

  // 初始化框架
  const framework = new AgentFramework(config);
  await framework.initialize();

  // 注册内置工具
  framework.registerTool({
    source: "builtin",
    definition: {
      name: "read_file",
      description: "读取文件",
      input_schema: {
        type: "object",
        properties: { path: { type: "string" } },
        required: ["path"],
      },
    },
    handler: async ({ path }) => {
      const fs = await import("node:fs/promises");
      return fs.readFile(path as string, "utf-8");
    },
  });

  // 创建 Agent
  const agent = framework.createAgent({
    systemPrompt: "你是一个终端里的编程助手。",
  });

  // 交互循环
  const rl = createInterface({ input: process.stdin, output: process.stdout });

  console.log("Agent 已就绪。输入消息，Ctrl+C 退出。\n");

  const askQuestion = () => {
    rl.question("> ", async (input) => {
      console.log("");
      for await (const event of agent.run(input)) {
        if (event.type === "response") {
          const response = event.data as { response: MessageResponse };
          const text = response.response.content
            .filter(b => b.type === "text")
            .map(b => b.text)
            .join("\n");
          console.log(text);
        } else if (event.type === "tool_call") {
          const data = event.data as { toolCalls: ToolUseBlock[] };
          console.log(`[执行工具: ${data.toolCalls.map(t => t.name).join(", ")}]`);
        }
      }
      console.log("");
      askQuestion();
    });
  };

  askQuestion();

  // 优雅关闭
  process.on("SIGINT", async () => {
    console.log("\n正在关闭...");
    await framework.shutdown();
    process.exit(0);
  });
}

main().catch(console.error);

// → examples/api-server.ts
import express from "express";
import { AgentFramework } from "my-agent";

const app = express();
app.use(express.json());

const framework = new AgentFramework(/* config */);
await framework.initialize();

app.post("/agent/run", async (req, res) => {
  const { message } = req.body;
  const agent = framework.createAgent();

  res.setHeader("Content-Type", "text/event-stream");

  for await (const event of agent.run(message)) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
    if (event.type === "response") {
      res.end();
      break;
    }
  }
});

app.listen(3000, () => console.log("Agent API on :3000"));