Claw Code 架构解析：Rust 如何重塑 AI Agent 的可靠性边界

ConversationRuntime
  ├── ClaudeApiClient (硬编码)
  ├── BashToolExecutor (硬编码)
  └── FileToolExecutor (硬编码)

// 运行时是泛型的，C 和 T 是类型参数
pub struct ConversationRuntime<C: ApiClient, T: ToolExecutor> {
    client: C,
    executor: T,
    permission: PermissionPolicy,
    hooks: HookRunner,
}

// 生产环境：注入真实客户端
let runtime = ConversationRuntime::new(
    ClawApiClient::new("claude-opus-4-6"),
    LocalToolExecutor::new(),
    PermissionPolicy::default()
);

// 测试环境：注入 mock 客户端
let runtime = ConversationRuntime::new(
    MockApiClient::with_responses(vec!["response 1", "response 2"]),
    MockToolExecutor::new(),
    PermissionPolicy::read_only()
);

// 多提供商场景：运行时保持不变，只换客户端
let gpt_runtime = ConversationRuntime::new(
    OpenAiClient::new("gpt-4o"),
    LocalToolExecutor::new(),
    PermissionPolicy::default()
);

// 阶段 1：使用 Claude 生成代码骨架（擅长理解需求）
let code_runtime = ConversationRuntime::new(
    ClawApiClient::new("claude-opus-4-6"),
    LocalToolExecutor::new(),
    PermissionPolicy::workspace_write()
);
let skeleton = code_runtime.execute("生成认证模块的代码骨架").await?;

// 阶段 2：使用 GPT-4 进行代码审查（擅长代码分析）
let review_runtime = ConversationRuntime::new(
    OpenAiClient::new("gpt-4o"),
    ReadOnlyToolExecutor::new(),   // 审查阶段只读
    PermissionPolicy::read_only()
);
let review = review_runtime.execute(&format!("审查：{}", skeleton)).await?;

// 每个阶段的核心逻辑相同，只有注入的 client 不同
// 运行时代码零修改

let registry = GlobalToolRegistry::new();

// 白名单模式：只暴露安全的工具
registry.set_visibility_policy(VisibilityPolicy::Whitelist(vec![
    "read_file", "write_file", "grep", "glob",
    // bash 和危险命令默认不在白名单
]));

// 工具调用前拦截：审计 + 安全检查
registry.on_pre_tool_call(|tool_name, input| {
    audit_logger.log(tool_name, input, timestamp())?;
    security_policy.check(tool_name, input)?;
    Ok(())
});

// 工具调用后拦截：记录输出、成本核算
registry.on_post_tool_call(|tool_name, output, duration| {
    cost_tracker.record(tool_name, duration);
    Ok(output)
});

hooks:
  PreToolUse:
    - name: budget_check
      match:
        tool: bash
      type: command
      command: |
        # 检查本次任务累计调用次数
        if [ $TOTAL_BASH_CALLS -gt 100 ]; then
          echo "BUDGET_EXCEEDED: bash calls limit reached" >&2
          exit 1
        fi

    - name: security_gate
      match:
        tool: bash
      type: command
      command: /etc/claw/hooks/security_check.sh

  PostToolUse:
    - name: auto_lint
      match:
        tool: Write
        path: '**/*.py'
      type: command
      command: ruff check {path} --fix

    - name: audit_logger
      match:
        tool: '*'
      type: command
      command: |
        echo "[$(date)] tool=${CLAW_TOOL_NAME} path=${CLAW_TOOL_PATH}" >> /var/log/claw_audit.log

mcp_servers:
  # 本地开发工具
  - name: 'git-mcp'
    type: 'stdio'
    command: 'uvx mcp-server-git'
    args: ['--repo', '${WORKSPACE}']

  # 企业内部文档（远程服务）
  - name: 'enterprise-docs'
    type: 'sse'
    url: 'https://docs.internal.company.com/mcp'
    headers:
      Authorization: 'Bearer ${DOCS_API_KEY}'

  # Jira 工单系统
  - name: 'jira'
    type: 'stdio'
    command: 'npx @company/jira-mcp'
    env:
      JIRA_TOKEN: '${JIRA_API_TOKEN}'

必须保留：
  工具调用记录（Agent 执行了什么操作）
  错误和回滚记录（哪些尝试失败了，为什么）
  关键决策（选择了什么方案，理由是什么）
  用户明确表达的意图和约束

可以压缩：
  中间讨论过程（保留结论，丢弃推导过程）
  已完成任务的细节（保留摘要，丢弃步骤）
  重复的确认消息（合并为一条）

应该丢弃：
  已被覆盖的计划草稿
  重复性工具输出（如多次 ls 的结果）
  过时的状态描述

const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
    SlashCommandSpec {
        name: "help",
        aliases: &["h", "?"],
        description: "显示帮助信息",
        category: General,
    },
    SlashCommandSpec {
        name: "compact",
        aliases: &["compress"],
        description: "手动触发会话压缩",
        category: Context,
    },
    SlashCommandSpec {
        name: "branch",
        aliases: &["branches"],
        description: "查看和切换 Git 分支",
        category: Git,
    },
    SlashCommandSpec {
        name: "test",
        description: "运行测试套件",
        category: Development,
    },
    // ... 20+ 命令
];

# 项目约定

## 技术栈

- Python 3.12，使用 uv 管理依赖
- FastAPI + SQLAlchemy ORM
- PostgreSQL，使用 Alembic 做迁移
- pytest + hypothesis 做测试

## 代码规范

- 使用 ruff 做 lint 和格式化
- 函数参数必须有类型注解
- 数据库操作必须在事务中进行

## 常用命令

- 运行测试：`uv run pytest tests/`
- 数据库迁移：`uv run alembic upgrade head`
- 启动开发服务器：`uv run uvicorn app.main:app --reload`

## 注意事项

- 不要直接修改 migrations/ 下的已提交文件
- 所有外部 API 调用必须有超时设置