前置条件

• Python 3.12 或更高版本
• Git

分步指南

1. 克隆 FastCode

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. 安装依赖

   选项 A：使用 uv（推荐）

   # 安装 uv
   pip install uv
   # 使用 uv 创建新虚拟环境
   uv venv --python=3.12
   source .venv/bin/activate
   
   # 使用 uv 安装依赖
   uv pip install -r requirements.txt
   

   选项 B：使用 pip

   pip install -r requirements.txt
   

3. 配置环境

   cp env.example .env
   nano .env  # 或使用您喜欢的编辑器
   

   添加您的 API 密钥：

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=gpt-5.2
   BASE_URL=https://api.openai.com/v1
   

4. 启动 FastCode

   # Web UI（推荐）
   python web_app.py --host 0.0.0.0 --port 5000
   
   # 或使用命令行界面
   python main.py query --repo-path /path/to/your/repo --query "Your question here"
   

前置条件

• Python 3.12 或更高版本
• Git

分步指南

1. 克隆 FastCode

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. 安装依赖

   选项 A：使用 uv（推荐）

   # 安装 uv
   pip install uv
   # 使用 uv 创建新虚拟环境
   uv venv --python=3.12
   source .venv/bin/activate
   
   # 使用 uv 安装依赖
   uv pip install -r requirements.txt
   

   选项 B：使用 pip

   pip install -r requirements.txt
   

3. 配置环境

   cp env.example .env
   nano .env  # 或使用：open -e .env
   

   添加您的 API 密钥：

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=gemini-3-flash
   BASE_URL=https://...
   

4. 启动 FastCode

   # Web UI（推荐）
   python web_app.py --host 0.0.0.0 --port 5000
   
   # 或使用命令行界面
   python main.py query --repo-path /path/to/your/repo --query "Your question here"
   

Apple Silicon (M1/M2/M3) 注意事项： 所有依赖项均兼容 ARM 架构。

前置条件

• Python 3.12 或更高版本
• Git

分步指南

1. 克隆 FastCode

   git clone https://github.com/HKUDS/FastCode.git
   cd FastCode
   

2. 安装依赖

   选项 A：使用 uv（推荐）

   # 安装 uv
   pip install uv
   # 使用 uv 创建新虚拟环境
   uv venv --python=3.12
   .venv\Scripts\activate
   
   # 使用 uv 安装依赖
   uv pip install -r requirements.txt
   

   选项 B：使用 pip

   pip install -r requirements.txt
   

3. 配置环境

   copy env.example .env
   notepad .env
   

   添加您的 API 密钥：

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL=qwen/qwen3-coder-30b-a3b-instruct
   BASE_URL=https://api.openai.com/v1
   

4. 启动 FastCode

   # Web UI（推荐）
   python web_app.py --host 0.0.0.0 --port 5000
   
   # 或使用命令行界面
   python main.py query --repo-path C:\path\to\your\repo --query "Your question here"
   

故障排除：

• 如果出现 SSL 错误：pip install --upgrade certifi
• 如果遇到权限错误，请以管理员身份运行命令提示符。
• 如果 faiss-cpu 无法安装：pip install faiss-cpu --no-cache-dir
• 如果在 Windows 上运行 ./run_nanobot.sh（bash 脚本），请使用 Git Bash 或 WSL，并确保 .sh 文件使用 LF 换行符。此仓库通过 .gitattributes 强制使用 LF 格式，但旧克隆可能需要重新检出一次。

通过功能全面的 REST API 将 FastCode 集成到您的工具中：

# 启动 API 服务器
python api.py --host 0.0.0.0 --port 8000

API 提供了 Web UI 中的所有功能。访问 http://localhost:8000/docs 可查看交互式的 API 文档。

关键 API 端点：

# 列出可用及已加载的代码库
GET /repositories

# 从 URL 或本地路径加载代码库
POST /load
{
  "source": "https://github.com/user/repo",
  "is_url": true
}

# 对已加载的代码库进行索引
POST /index?force=false

# 一次性加载并索引
POST /load-and-index
{
  "source": "/path/to/repo",
  "is_url": false
}

# 加载多个已索引的代码库
POST /load-repositories
{
  "repo_names": ["repo1", "repo2"]
}

# 一次性对多个代码库进行索引
POST /index-multiple
{
  "sources": [
    {"source": "https://github.com/user/repo1", "is_url": true},
    {"source": "/path/to/repo2", "is_url": false}
  ]
}

# 上传 ZIP 格式的代码库
POST /upload-zip
Content-Type: multipart/form-data
file: <zip_file>

# 上传并索引一次完成
POST /upload-and-index?force=false
Content-Type: multipart/form-data
file: <zip_file>

# 删除代码库及其索引
POST /delete-repos
{
  "repo_names": ["repo1", "repo2"],
  "delete_source": true
}

# 获取代码库摘要
GET /summary

# 查询代码库（单次响应）
POST /query
{
  "question": "认证是如何工作的？",
  "filters": null,
  "repo_filter": ["repo1"],
  "multi_turn": false,
  "session_id": null
}

# 带流式响应的查询（SSE）
POST /query-stream
{
  "question": "请解释数据库模式",
  "multi_turn": true,
  "session_id": "abc123"
}

# 开始一个新的对话会话
POST /new-session?clear_session_id=old_session

# 列出所有对话会话
GET /sessions

# 获取对话历史
GET /session/{session_id}

# 删除一个对话会话
DELETE /session/{session_id}

# 健康检查
GET /health

# 获取系统状态
GET /status?full_scan=false

# 清除缓存
POST /clear-cache

# 获取缓存统计信息
GET /cache-stats

# 刷新索引缓存
POST /refresh-index-cache

#  Entladen des aktuellen Repositorys
DELETE /repository

使用示例：

import requests

# 启动会话并查询
response = requests.post("http://localhost:8000/load-and-index", json={
    "source": "https://github.com/user/repo",
    "is_url": True
})

# 查询仓库
response = requests.post("http://localhost:8000/query", json={
    "question": "主入口在哪里？",
    "multi_turn": False
})

result = response.json()
print(result["answer"])
print(f"使用的 token 数量：{result['total_tokens']}")

FastCode 可以作为 MCP（模型上下文协议） 服务器运行，从而使像 Cursor、Claude Code 和 Windsurf 这样的 AI 编程助手能够直接使用 FastCode 的仓库级代码理解能力。

设置

在您的 MCP 配置中添加以下内容：

在配置 MCP 之前，请确保本地 uv 虚拟环境中已安装 FastCode 的依赖项：

git clone https://github.com/HKUDS/FastCode.git
cd FastCode
uv venv --python=3.12
source .venv/bin/activate
uv pip install -r requirements.txt

MCP 服务器应使用 .venv/bin/python 启动，并且需要设置 OPENAI_API_KEY、MODEL 和 BASE_URL。

Cursor (~/.cursor/mcp.json)：

{
  "mcpServers": {
    "fastcode": {
      "command": "/path/to/FastCode/.venv/bin/python",
      "args": ["/path/to/FastCode/mcp_server.py"],
      "env": {
        "MODEL": "gpt-5.2",
        "BASE_URL": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code (claude_desktop_config.json)：

{
  "mcpServers": {
    "fastcode": {
      "command": "/path/to/FastCode/.venv/bin/python",
      "args": ["/path/to/FastCode/mcp_server.py"],
      "env": {
        "MODEL": "gpt-5.2",
        "BASE_URL": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

或者通过 claude mcp add 命令（请确保您的 shell 中已设置相同的环境变量）：

claude mcp add fastcode -- /path/to/FastCode/.venv/bin/python /path/to/FastCode/mcp_server.py

SSE 传输方式（适用于远程或共享部署）：

OPENAI_API_KEY=sk-... MODEL=gpt-5.2 BASE_URL=https://api.openai.com/v1 \
/path/to/FastCode/.venv/bin/python /path/to/FastCode/mcp_server.py --transport sse --port 8080

可用工具

code_qa 参数

工作原理

1. 自动检测：对于 repos 中的每个仓库，FastCode 会检查其是否已被索引。如果已索引，则完全跳过索引过程。
2. 自动克隆：如果仓库是 URL 且尚未存在于磁盘上，FastCode 会将其克隆到 ./repos/ 并进行索引。
3. 多轮对话：当启用 multi_turn（默认）时，来自同一 session_id 的先前问答上下文将用于重写查询和生成答案。每次响应中都会返回 session_id——在后续调用中将其传回即可继续对话。
4. 多仓库查询：您可以将多个仓库传递给 repos 参数，FastCode 将在所有仓库中进行搜索，并利用 LLM 基于仓库选择最相关的代码。

使用示例

在 Cursor 或 Claude Code 中，只需输入：

使用 FastCode 分析一下位于 /path/to/repo_name 的这个仓库是用来做什么的。

或者

使用 FastCode 分析一下 https://github.com/user/my-project 中的认证流程。

AI 助手会调用 code_qa 接口并传入 URL，FastCode 会在必要时克隆并索引该仓库，然后返回包含源代码引用的详细答案。

对于后续问题，助手会自动重复使用同一个 session_id：

如果我修改 User 模型，哪些文件会受到影响？

OPENAI_API_KEY=sk-...
MODEL=gpt-4
BASE_URL=https://api.openai.com/v1

OPENAI_API_KEY=sk-or-...
MODEL=google/gemini-flash-1.5
BASE_URL=https://openrouter.ai/api/v1

OPENAI_API_KEY=ollama
MODEL=qwen3-coder-30b_fastcode
BASE_URL=http://localhost:11434/v1

1. 统一配置（.env）

所有 API 密钥和模型设置都集中在一个 .env 文件中，供两个服务共享：

# ===== 共享 API 配置 =====
OPENAI_API_KEY=sk-or-v1-xxx        # 两个服务共用
BASE_URL=https://openrouter.ai/api/v1

# ===== FastCode 模型（代码分析）=====
MODEL=google/gemini-3-flash-preview

# ===== Nanobot 模型（智能体推理 / 飞书对话）=====
NANOBOT_MODEL=minimax/minimax-m2.1

API 密钥会通过 docker-compose.yml 中的环境变量自动注入到 Nanobot 容器中——无需在 nanobot_config.json 中重复填写。

2. FastCode 核心配置

• config/config.yaml — FastCode 检索和索引设置

3. Nanobot 配置（nanobot_config.json）

run_nanobot.sh 会自动生成此文件。你只需在此处配置 飞书凭证和 systemPrompt；API 密钥和模型设置则由 .env 文件统一管理。

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxx",
      "appSecret": "your_app_secret"
    }
  }
}

Nanobot 通过 WebSocket 长连接接收飞书消息——无需公网 IP 或 Webhook。

1. 创建应用

前往 飞书开放平台 → 创建一个 自定义企业应用 → 记下 App ID（cli_xxx）和 App Secret。

2. 启用机器人功能

进入应用设置 → 应用功能 → 启用“机器人”功能。

3. 添加权限

在 权限管理 中添加以下权限：

4. 配置事件订阅

⚠️ 注意顺序：必须先启动 Nanobot 建立 WebSocket 连接，然后再在飞书管理后台配置事件订阅。

1. 在 nanobot_config.json 中填入 appId 和 appSecret，然后启动服务（./run_nanobot.sh）
2. 确认日志显示 connected to wss://msg-frontier.feishu.cn，表明连接成功
3. 返回飞书管理后台 → 事件与回调 → 选择“通过长连接接收事件” → 保存
4. 添加事件：im.message.receive_v1（接收消息）

5. 发布应用

进入 版本管理 → 创建版本 → 提交审核（企业内部应用可自行批准）→ 发布后，即可在飞书中与机器人聊天。

services:
  fastcode:          # FastCode API（端口 8001）
    build: .
    volumes:
      - ./.env:/app/.env:ro
      - ./config:/app/config:ro
      - ./data:/app/data
      - ./repos:/app/repos

  nanobot:           # Nanobot 网关（端口 18791 → 18790）
    build: ./nanobot
    command: ["gateway"]
    volumes:
      - ./nanobot_config.json:/root/.nanobot/config.json:ro
    environment:
      - FASTCODE_API_URL=http://fastcode:8001
      # API 密钥和模型从 .env 注入
      - NANOBOT_PROVIDERS__OPENROUTER__API_KEY=${OPENAI_API_KEY}
      - NANOBOT_AGENTS__DEFAULTS__MODEL=${NANOBOT_MODEL}
    depends_on:
      - fastcode

启动时，Nanobot 会通过 FASTCODE_API_URL 环境变量自动注册以下工具：