AiCode

🎯 项目概述

AiCode 是一个基于claude code开源代码的，C++ 开发的智能编码助手 CLI 工具，采用"思考 - 行动 - 观察"闭环的 Agent 架构，通过 MCP 工具集直接操作终端与文件系统，调用 Claude/Qwen/Ollama API 完成自主代码开发与调试。

核心定位

架构分层

┌─────────────────────────────────────────────────────────────┐
│ CLI 交互层 → 原生终端输入输出、信号处理（Ctrl+C）             │
├─────────────────────────────────────────────────────────────┤
│ 意图解析层 → 指令解析、上下文加载（文件/目录/Git）            │
├─────────────────────────────────────────────────────────────┤
│ Agent 调度层 → 理解 → 规划 → 工具调用 → 观察 → 验证 → 迭代    │
├─────────────────────────────────────────────────────────────┤
│ 工具执行层 → 文件系统、Shell 命令、网络搜索 (30+ 工具)         │
├─────────────────────────────────────────────────────────────┤
│ 环境反馈层 → 捕获命令输出、错误、状态更新                     │
├─────────────────────────────────────────────────────────────┤
│ 输出验证层 → 代码校验、测试执行、任务终止                     │
└─────────────────────────────────────────────────────────────┘

🆚 相比 Claude Code 的优势

核心优势详解

1. 多 LLM 提供者支持 🔄

AiCode 不绑定单一模型，支持：

• Anthropic (Claude) - 通过官方 API 或兼容接口
• Qwen (通义千问) - 阿里云 DashScope
• Ollama - 本地模型部署
• 易于扩展新的提供者（继承 LLMProvider 接口即可）

2. 完全本地可控 🔒

• 配置文件存储在 ~/.aicode/config.json，完全可控
• 支持自定义 API 端点（包括本地代理）
• 可配置路径白名单/黑名单，精细控制文件访问
• 可配置命令白名单/黑名单，精细控制命令执行

3. 灵活的权限系统 ⚖️

{
  "permission_rules": [
    {
      "tool_name": "bash",
      "command_pattern": "git *",
      "default_level": "allow"
    },
    {
      "tool_name": "read_file",
      "path_pattern": "/etc/*",
      "default_level": "deny"
    }
  ]
}

4. 可扩展技能系统 🧩

通过 SKILL.md 文件定义技能，支持：

• 环境门控（二进制、环境变量、OS 限制）
• 自动安装依赖
• 自定义命令注册

5. 高性能 C++ 实现 ⚡

• 原生编译，无 Node.js 运行时依赖
• 更低的内存占用
• 更快的启动速度

6. 完善的 LSP 支持 💻

• 多语言服务器并发管理
• 诊断、跳转定义、查找引用、悬停信息
• 文档符号、工作区符号、格式化

7. 开源许可 📄

• Apache License 2.0 - 可商用、可修改、可分发
• 社区驱动，透明开发

✨ 核心特性

🏃 REACT 范式 - "思考 - 行动 - 观察"闭环

理解 → 规划 → 工具调用 → 观察 → 验证 → 迭代/终止

AiCode 采用 REACT（Reason + Act）范式，自主生成任务序列（如：读文件 → 改代码 → 运行测试 → 修复报错），支持多轮迭代。

🛠️ 工具系统 - 30+ 内置工具

🧠 技能系统

技能通过 SKILL.md 文件定义，支持环境门控和自动安装：

---
name: git
description: Git version control operations
required_bins: [git]
required_envs: []
any_bins: []
config_files: []
os_restrict: []
always: false
emoji: 🦆
---

# Git Skill

You are a git expert. Help users with git operations...

🔐 权限管理

三种权限级别：

• Allow - 自动批准
• Deny - 自动拒绝
• Ask - 需要用户确认

规则匹配支持工具名、命令模式、路径模式，失败回退逻辑（3 次拒绝后自动批准）。

💾 上下文压缩

三种压缩策略：

• Summary - 生成旧消息的 AI 摘要
• Truncate - 仅保留最近 N 条消息
• Hybrid - 摘要 + 保留最近消息（默认）

🧩 MCP 协议

支持 MCP (Model Context Protocol) 服务器集成：

• stdio 传输
• SSE/WebSocket 传输
• 工具发现和执行
• 资源读取

🚀 快速开始

环境要求

构建

# 克隆仓库
git clone https://github.com/your-repo/aicode.git
cd aicode

# 创建构建目录
mkdir -p build && cd build

# 配置
cmake .. -DCMAKE_BUILD_TYPE=Release

# 编译
make -j8

# 安装
make install

运行

# 使用 Makefile
make run

# 或直接运行
./build/install/bin/aicode

配置

首次运行时，配置文件将生成在 ~/.aicode/config.json：

{
  "log_level": "info",
  "default_provider": "anthropic",
  "default_agent": "default",
  
  "providers": {
    "anthropic": {
      "api_key": "YOUR_API_KEY",
      "base_url": "https://api.anthropic.com",
      "api_type": "anthropic-messages",
      "timeout": 30,
      "agents": {
        "default": {
          "model": "claude-sonnet-4-6",
          "temperature": 0.7,
          "max_tokens": 8192
        }
      }
    },
    "qwen": {
      "api_key": "YOUR_DASHSCOPE_KEY",
      "base_url": "https://dashscope.aliyuncs.com",
      "api_type": "openai-completions",
      "timeout": 60,
      "agents": {
        "default": {
          "model": "qwen-max",
          "temperature": 0.7,
          "max_tokens": 8192
        }
      }
    }
  },
  
  "security": {
    "permission_level": "auto",
    "allow_local_execute": true
  },
  
  "tools": {
    "enabled": true,
    "timeout": 60
  },
  
  "skills": {
    "path": "~/.aicode/skills",
    "auto_approve": ["read_file", "grep"]
  }
}

环境变量

可通过以下环境变量覆盖配置：

📋 使用方式

基本交互

启动 AiCode 后，可以直接输入自然语言指令：

$ aicode
AiCode v1.0.0

> 帮我查看当前目录的文件结构
> 创建一个计算斐波那契数列的函数
> 运行测试并修复失败的用例

内置命令

会话管理

# 保存当前会话
/session save my-session

# 列出所有会话
/session list

# 加载会话
/session load my-session

# 删除会话
/session delete my-session

🏗️ 架构设计

系统架构图

┌─────────────────────────────────────────────────────────┐
│                    CLI Layer (cli/)                      │
│   CommandRegistry  │  InputHandler  │  UI               │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 AgentCommander (core/)                   │
│           用户交互、命令处理、Agent 执行编排               │
└─────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   AgentCore     │ │ MemoryManager   │ │  SkillLoader    │
│ 消息处理/工具   │ │ 工作空间文件/   │ │ 技能加载/解析   │
│ 执行/LLM 交互   │ │ 会话管理        │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
            │               │               │
            ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  ToolRegistry   │ │ LspManager      │ │ McpClient       │
│  工具注册/执行  │ │ LSP 语言服务    │ │ MCP 协议客户端  │
└─────────────────┘ └─────────────────┘ └─────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│              LLM Providers (providers/)                  │
│   AnthropicProvider  │  QwenProvider  │  LLMProvider   │
└─────────────────────────────────────────────────────────┘

核心模块

设计模式

📁 项目结构

AiCode/
├── main_src/
│   ├── cli/                    # CLI 交互层
│   │   ├── command_registry.*  # 命令注册和执行
│   │   └── input_handler.*     # 终端输入处理
│   ├── common/                 # 通用工具
│   │   ├── config.*            # 配置系统
│   │   ├── constants.h         # 常量定义
│   │   ├── curl_client.*       # HTTP 客户端
│   │   └── log_wrapper.h       # 日志封装
│   ├── core/                   # 核心业务逻辑
│   │   ├── agent_commander.*   # 主入口/编排器
│   │   ├── agent_core.*        # Agent 核心循环
│   │   ├── compact_service.*   # 上下文压缩
│   │   ├── memory_manager.*    # 文件/记忆管理
│   │   ├── permission_manager.*# 权限管理
│   │   ├── plan_mode.*         # 计划模式
│   │   ├── skill_loader.*      # 技能加载
│   │   ├── system_prompt.*     # 系统提示构建
│   │   └── session_manager.*   # 会话管理
│   ├── providers/              # LLM 提供者
│   │   ├── llm_provider.*      # 抽象接口
│   │   ├── anthropic_provider.*# Anthropic API
│   │   └── qwen_provider.*     # Qwen API
│   ├── tools/                  # 工具实现
│   │   ├── tool_registry.*     # 工具注册表
│   │   ├── glob_tool.*
│   │   ├── grep_tool.*
│   │   ├── lsp_tool.*
│   │   └── ...
│   ├── mcp/                    # MCP 协议
│   │   └── mcp_client.*        # MCP 客户端
│   ├── managers/               # 管理器
│   │   ├── buddy_manager.*     # Buddy 系统
│   │   └── token_tracker.*     # Token 追踪
│   └── services/               # 外部服务
│       ├── lsp_manager.*       # LSP 管理
│       └── cron_scheduler.*    # 定时任务
├── config/                     # 配置文件
├── tests/                      # 测试代码
├── docs/                       # 技术文档
├── CMakeLists.txt              # 构建配置
└── Makefile                    # 快捷构建脚本

📚 配置详解

顶层配置

Agent 配置

Security 配置

Tools 配置

📖 文档

🔧 故障排查

常见问题

1. API 密钥错误

• 检查 api_key 是否正确
• 确认环境变量优先级

2. 工具执行失败

• 检查 allowed_cmds 白名单
• 确认路径在 allowed_paths 内

3. 技能未加载

• 检查 required_bins 是否存在
• 确认 os_restrict 匹配当前系统

4. LSP 无法启动

• 确认语言服务器已安装
• 检查 command 路径是否正确

📄 许可证

Licensed under the Apache License, Version 2.0.

See LICENSE for details.

🙏 致谢

• Anthropic - Claude 大模型的创造者
• C++ 社区 - 优秀的系统编程语言和工具链
• 所有贡献者 - 感谢每一位为项目做出贡献的开发者