架构总览

分层结构

┌─────────────────────────────────────────────────────┐
│                   cmd/claude (入口)                   │
├─────────────────────────────────────────────────────┤
│              internal/cli (启动编排)                  │
├──────────────┬──────────────────────────────────────┤
│  internal/   │  internal/query                       │
│  repl        │  (Engine + 查询循环)                   │
│  (交互层)    │                                        │
├──────────────┴──────────────────────────────────────┤
│              internal/api (API 客户端)                │
│     Anthropic / OpenAI / Bedrock / Vertex            │
├─────────────────────────────────────────────────────┤
│           Tool 层（internal/tools/*）                 │
│  Bash / FileRead / FileEdit / Skill / Agent / ...    │
├───────────────────┬─────────────────────────────────┤
│  internal/skills  │  internal/mcp                    │
│  (Skill 注册)     │  (MCP server 连接)               │
├───────────────────┴─────────────────────────────────┤
│         基础设施层                                    │
│  settings / permissions / hooks / compact / session  │
└─────────────────────────────────────────────────────┘

核心数据流

用户输入
  → REPL.handleInput()
  → engine.Run(RunParams{Messages, SystemPrompt, ...})
    → context.BuildSystemPrompt()      // 组装 system prompt
    → query.Run(ctx, client, params)   // 驱动 tool-use 循环
      → api.Stream()                   // 调用 LLM
      → 处理流式事件
      → 遇到 tool_use block:
          → permissions.HasPermissionsToUseToolFull()
          → hooks.RunHooksForEvent(PreToolUse)
          → tool.Execute(input)
          → hooks.RunHooksForEvent(PostToolUse)
          → 将 tool_result 追加到 messages
          → 继续下一轮 API 调用
      → 遇到 stop_reason=end_turn: 退出循环
  → 更新 REPL messages

依赖注入

所有 tool 的外部依赖通过 tools.Deps 在启动时注入（internal/cli/runner.go:116）：

tools.RegisterAllWithDeps(tools.Deps{
    SkillRegistry: skillRegistry,
    MCPManager:    mcpManager,
    TaskManager:   taskManager,
    AgentRunner:   engine,
    SkillRunner:   engine,
})

这使得 Engine 既是顶层查询器，也作为 AgentRunner/SkillRunner 接口被 Agent tool 和 Skill tool 调用，实现递归子 agent。

关键接口

toolbase.Tool

所有 built-in tool 必须实现的接口（internal/toolbase/toolbase.go）：

type Tool interface {
    Name() string
    Description() string
    IsEnabled() bool
    Prompt() string
    RequiresUserInteraction() bool
    CheckPermissions(input map[string]interface{}, ctx *PermissionContext) types.PermissionResult
    Execute(ctx context.Context, input map[string]interface{}, toolCtx ToolContext) (string, error)
}

PermissionMode

权限模式枚举（pkg/types/permission.go）：

模式	说明
`default`	默认，需用户交互确认危险操作
`bypassPermissions`	跳过所有权限检查
`dontAsk`	遇到 ask 时自动 deny（headless）
`plan`	Plan mode，部分权限豁免

Wiki AI

目录