Claude Code 源码解读 08:实战构建自己的 Code Agent

mini-agent/├── src/│   ├── main.ts           # CLI 入口│   ├── agent.ts          # Agent 循环核心│   ├── tools/│   │   ├── index.ts      # 工具注册表│   │   ├── Tool.ts       # Tool 接口定义│   │   ├── FileReadTool.ts│   │   ├── FileWriteTool.ts│   │   └── BashTool.ts│   ├── permissions/│   │   ├── rules.ts      # 权限规则匹配│   │   └── modes.ts      # 权限模式│   ├── hooks/│   │   ├── registry.ts   # Hook 注册表│   │   └── types.ts      # Hook 类型定义│   ├── mcp/│   │   └── client.ts     # MCP 客户端│   └── api/│       └── anthropic.ts  # API 调用封装├── package.json└── tsconfig.json

// src/tools/Tool.tsexport interface Tool<Input extends Record<string, unknown>, Output> {  name: string  description: string  // 输入校验  inputSchema: z.ZodType<Input>  // 执行  call(    args: Input,    context: ToolUseContext  ): Promise<ToolResult<Output>>  // 权限检查  checkPermissions(args: Input): PermissionResult  // 安全属性  isReadOnly(args: Input): boolean  isConcurrencySafe(args: Input): boolean  // 是否启用  isEnabled(): boolean}export interface ToolUseContext {  cwd: string  messages: Message[]  abortSignal: AbortSignal  permissions: PermissionMode  hooks: HookRegistry}export interface ToolResult<T> {  data: T  newMessages?: Message[]  error?: string}export type PermissionResult =   | { allowed: true }  | { allowed: false; reason: string }

// src/tools/FileReadTool.tsexport class FileReadTool implements Tool<FileReadInput, FileReadOutput> {  name = 'Read'  description = 'Read contents of a file'  inputSchema = z.object({    file_path: z.string().describe('Path to the file to read')  })  isReadOnly = () => true  isConcurrencySafe = () => true  isEnabled = () => true  checkPermissions(args: FileReadInput): PermissionResult {    // 权限规则检查    if (isDenied(this.name, args.file_path, 'read')) {      return { allowed: false, reason: 'Path is in denied list' }    }    return { allowed: true }  }  asynccall(args: FileReadInput, ctx: ToolUseContext): Promise<ToolResult<FileReadOutput>> {    try {      const content = await fs.readFile(args.file_path, 'utf-8')      return { data: { content, path: args.file_path } }    } catch (e) {      return { data: { content: '', path: args.file_path }, error: String(e) }    }  }}

// src/tools/BashTool.tsexport class BashTool implements Tool<BashInput, BashOutput> {  name = 'Bash'  description = 'Execute a bash command'  inputSchema = z.object({    command: z.string().describe('The bash command to execute'),    timeout: z.number().optional().default(30000)  })  // 已知的安全命令（只读）  private readonly READ_COMMANDS = new Set(['ls', 'cat', 'grep', 'find', 'git', 'head', 'tail', 'wc'])  isReadOnly(args: BashInput): boolean {    const cmd = args.command.trim().split(/\s+/)[0]    return this.READ_COMMANDS.has(cmd)  }  isConcurrencySafe = () => false  // Bash 默认不安全，不并行执行  checkPermissions(args: BashInput): PermissionResult {    // 检查危险命令    if (/sudo|rm\s+-rf|dd\s+of=/.test(args.command)) {      return { allowed: false, reason: 'Dangerous command blocked' }    }    return { allowed: true }  }  async call(args: BashInput, ctx: ToolUseContext): Promise<ToolResult<BashOutput>> {    return new Promise((resolve) => {      const child = spawn('/bin/bash', ['-c', args.command], {        cwd: ctx.cwd,        signal: ctx.abortSignal      })      let stdout = ''      let stderr = ''      child.stdout.on('data', (data) => { stdout += data.toString() })      child.stderr.on('data', (data) => { stderr += data.toString() })      const timeout = setTimeout(() => {        child.kill()        resolve({ data: { stdout, stderr, exitCode: 124 }, error: 'Command timed out' })      }, args.timeout)      child.on('close', (code) => {        clearTimeout(timeout)        resolve({           data: { stdout, stderr, exitCode: code ?? 0 },          error: code !== 0 ? `Exit code: {toolCall.name}`    const args = tool.inputSchema.parse(toolCall.arguments)    const context: ToolUseContext = {      cwd: process.cwd(),      messages: this.messages,      abortSignal: new AbortController().signal,      permissions: 'default',      hooks: this.hooks    }    // PreToolUse Hook（可修改输入或拒绝）    const hookResult = await this.hooks.emit('PreToolUse', {      tool_name: tool.name,      tool_input: args    })    if (hookResult.blocked) {      return `Blocked: {permResult.reason}`    }    // 执行工具    const result = await tool.call(args, context)    // PostToolUse Hook    await this.hooks.emit('PostToolUse', {      tool_name: tool.name,      tool_input: args,      tool_result: result    })    return result.error ?? JSON.stringify(result.data)  }  private getToolsDescription(): string {    return Array.from(this.tools.values())      .filter(t => t.isEnabled())      .map(t => `{t.description}`)      .join('\n')  }}

// src/mcp/client.tsexport class MCPClient {  private process: ChildProcess | null = null  private id = 0  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: any) => void }>()  async connect(command: string, args: string[]): Promise<void> {    this.process = spawn(command, args)    this.process.stdout?.on('data', (data) => {      const lines = data.toString().split('\n').filter(Boolean)      for (const line of lines) {        const msg = JSON.parse(line)        if (msg.id && this.pending.has(msg.id)) {          const { resolve, reject } = this.pending.get(msg.id)!          this.pending.delete(msg.id)          if (msg.error) reject(msg.error)          else resolve(msg.result)        }      }    })    // 初始化    await this.send('initialize', { protocolVersion: '2024-11-05', capabilities: {} })    await this.send('notifications/initialized', {})  }  async listTools(): Promise<MCPTool[]> {    const res = await this.send('tools/list', {})    return res.tools ?? []  }  async callTool(name: string, args: Record<string, unknown>) {    const result = await this.send('tools/call', { name, arguments: args })    return result  }  private send(method: string, params: any): Promise<any> {    return new Promise((resolve, reject) => {      const id = ++this.id      this.pending.set(id, { resolve, reject })      this.process?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')    })  }}

// src/main.tsasync functionmain() {  const agent = new MiniAgent(anthropicModel, `    You are a helpful coding assistant.    You have access to tools: Read, Write, Bash.    Always be concise and practical.`)  // 注册内置工具  agent.registerTool(new FileReadTool())  agent.registerTool(new FileWriteTool())  agent.registerTool(new BashTool())  // 设置权限  agent.setPermissions({    allow: [      { tool: 'Read', pattern: '^/home/.*\\.(ts|js|md){tool_name}" >&2'  })  // 连接 MCP（如果有的话）  const mcp = new MCPClient()  try {    await mcp.connect('npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])    const mcpTools = await mcp.listTools()    for(const t of mcpTools) {      agent.registerTool(new MCPToolAdapter(t, mcp))    }    console.log(`Connected  npx ts-node src/main.tsMiniAgent ready. Type your request (Ctrl+C to exit):> Read the package.json fileTool: ReadPermission: allowed{  "name": "mini-agent",  "version": "1.0.0"}> Run git statusTool: BashPermission: allowedOn branch mainnothing to commit, working tree clean> sudo rm -rf /Permission denied: Matched deny rule