通过自定义知识库和任务管理，将您的 AI 编码助手升级为 MCP 服务器

快速入门 • 升级 • 包含内容 • 架构 • 故障排除

🎯 Archon 是什么？

Archon 目前处于测试阶段！请做好部分功能可能无法正常工作的准备，并随时提出反馈或贡献修复与新功能！感谢大家对 Archon 的热情支持，以及提交的错误报告、拉取请求和讨论。虽然对我们小团队来说工作量很大，但我们致力于解决所有问题，让 Archon 成为尽可能优秀的工具！

Archon 是 AI 编码助手的指挥中心。对于您而言，它是一个简洁的界面，用于管理项目的知识、上下文和任务；对于 AI 编码助手来说，它则是一个模型上下文协议（MCP）服务器，可以协同使用并共享相同的知识、上下文和任务。您可以连接 Claude Code、Kiro、Cursor、Windsurf 等工具，让您的 AI 助手访问以下内容：

• 您的文档（爬取的网站、上传的 PDF/文档）
• 智能搜索功能，采用先进的 RAG 策略
• 任务管理，与您的知识库无缝集成
• 实时更新，当您添加新内容并与编码助手协作处理任务时
• 更多功能，即将推出，旨在将 Archon 打造成一个完整的上下文工程一体化环境

这一全新的 Archon 架构取代了旧版本（agenteer）。过去，Archon 是用来构建其他 AI 助手的 AI 代理，而现在，您不仅可以利用 Archon 来完成这项任务，还能实现更多功能。

无论您正在构建什么项目，无论是全新的代码库还是现有的代码库——Archon 的知识管理和任务管理能力都将提升任何 AI 驱动编码工作的成果。

🔗 重要链接

• GitHub 讨论区 - 加入讨论，分享关于 Archon 的想法
• 贡献指南 - 如何参与并为 Archon 做贡献
• 介绍视频 - Archon 的入门指南及愿景
• Archon 看板 - 维护人员在此管理问题和功能
• Dynamous AI Mastery - Archon 的诞生地——加入这个充满活力的早期 AI 技术采用者社区，共同助力彼此的职业与业务转型！

快速入门

📺 点击观看 YouTube 上的设置教程
-> 视频中的 AI 编码工作流程示例 <-

先决条件

• Docker Desktop
• Node.js 18+（用于混合开发模式）
• Supabase 账户（免费层级或本地 Supabase 均可）
• OpenAI API 密钥（也支持 Gemini 和 Ollama！）
• （可选）Make（见下方【安装 Make】）

设置步骤

1. 克隆仓库：

   git clone -b stable https://github.com/coleam00/archon.git
   

   cd archon
   

   注意： 推荐使用 stable 分支来运行 Archon。如果您想参与贡献或尝试最新功能，请使用 main 分支，执行 git clone https://github.com/coleam00/archon.git。

2. 配置环境变量：

   cp .env.example .env
   # 编辑 .env 文件，添加您的 Supabase 凭证：
   # SUPABASE_URL=https://your-project.supabase.co
   # SUPABASE_SERVICE_KEY=your-service-key-here
   

   重要提示：

   • 对于云端 Supabase：他们最近推出了新型服务角色密钥，但请使用旧版密钥（较长的那种）。
   • 对于本地 Supabase：将 SUPABASE_URL 设置为 http://host.docker.internal:8000（除非您已设置 IP 地址）。要获取 SUPABASE_SERVICE_KEY，请运行 supabase status -o env。

3. 数据库设置：在您的 Supabase 项目 SQL 编辑器中，复制并执行 migration/complete_setup.sql 中的内容。

4. 启动服务（任选其一）：

   完全 Docker 模式（推荐用于常规 Archon 使用）

   docker compose up --build -d
   

   这将启动所有核心微服务：

   • 服务器：核心 API 和业务逻辑（端口：8181）
   • MCP 服务器：AI 客户端的协议接口（端口：8051）
   • UI：Web 界面（端口：3737）

   您也可以在 .env 文件中自定义这些端口！

5. 配置 API 密钥：

   • 打开 http://localhost:3737
   • 您将自动进入引导流程，以设置您的 API 密钥（默认为 OpenAI）。

⚡ 快速测试

一切运行正常后：

1. 测试网页抓取：前往 http://localhost:3737 → 知识库 → “抓取网站” → 输入一个文档 URL（例如 https://ai.pydantic.dev/llms.txt）
2. 测试文档上传：知识库 → 上传一个 PDF
3. 测试项目：项目 → 创建新项目并添加任务
4. 与您的 AI 编码助手集成：MCP 控制台 → 复制连接配置信息，供您的 AI 编码助手使用

安装 Make

# 方法 1：使用 Chocolatey
choco install make

# 方法 2：使用 Scoop
scoop install make

# 方法 3：使用 WSL2
wsl --install
# 然后在 WSL 中：sudo apt-get install make

# macOS 自带 Make
# 如需安装：brew install make

# Debian/Ubuntu
sudo apt-get install make

# RHEL/CentOS/Fedora
sudo yum install make

🔄 数据库重置（如有需要从头开始）

如果您需要完全重置数据库并从头开始：

📚 文档

核心服务

升级

要将 Archon 升级到最新版本：

1. 拉取最新更改：

   git pull
   

2. 重建并重启容器：

   docker compose up -d --build
   

   这将使用最新代码重建容器，并重启所有服务。

3. 检查数据库迁移：

   • 在浏览器中打开 Archon 设置页面：http://localhost:3737/settings
   • 导航到 数据库迁移 部分
   • 如果有未完成的迁移，UI 会显示这些迁移，并提供清晰的操作说明
   • 点击每条迁移记录查看并复制 SQL 语句
   • 按照显示的顺序在您的 Supabase SQL 编辑器中执行这些 SQL 脚本

包含内容

🧠 知识管理

• 智能网页爬取：自动检测并爬取整个文档站点、站点地图以及单个页面。
• 文档处理：上传并处理 PDF、Word 文档、Markdown 文件和文本文件，支持智能分块。
• 代码示例提取：自动识别并索引文档中的代码示例，以增强搜索功能。
• 向量搜索：基于上下文嵌入的高级语义搜索，实现精准的知识检索。
• 来源管理：按来源、类型和标签组织知识，便于筛选。

🤖 AI 集成

• 模型上下文协议 (MCP)：连接任何兼容 MCP 的客户端（Claude Code、Cursor，甚至非 AI 编程助手如 Claude Desktop）。
• MCP 工具集：一套全面而简单的工具，用于 RAG 查询、任务管理和项目操作。
• 多 LLM 支持：兼容 OpenAI、Ollama 和 Google Gemini 模型。
• RAG 策略：混合搜索、上下文嵌入和结果重排序，以获得最佳的 AI 回答。
• 实时流式传输：AI 代理的实时响应，并可跟踪处理进度。

📋 项目与任务管理

• 层次化项目结构：通过项目、功能和任务构建结构化的流程。
• AI 辅助创建：利用集成的 AI 代理生成项目需求和任务。
• 文档管理：支持版本控制的文档，并具备协作编辑能力。
• 进度跟踪：实时更新和管理所有项目活动的状态。

🔄 实时协作

• WebSocket 更新：实时跟踪爬取、处理和 AI 操作的进度。
• 多用户支持：支持协作式知识构建和项目管理。
• 后台处理：异步操作，不会阻塞用户界面。
• 健康监测：内置服务健康检查和自动重连机制。

架构

微服务架构

Archon 采用真正的微服务架构，各服务职责分明：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端 UI   │    │  服务器 (API)   │    │   MCP 服务器    │    │  代理服务  │
│                 │    │                 │    │                 │    │                 │
│  React + Vite   │◄──►│    FastAPI +    │◄──►│    轻量级  │◄──►│   PydanticAI    │
│  端口 3737      │    │    SocketIO     │    │    HTTP 封装 │    │   端口 8052     │
│                 │    │    端口 8181    │    │    端口 8051    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │                        │
         └────────────────────────┼────────────────────────┼────────────────────────┘
                                  │                        │
                         ┌─────────────────┐               │
                         │    数据库     │               │
                         │                 │               │
                         │    Supabase     │◄──────────────┘
                         │    PostgreSQL   │
                         │    PGVector     │
                         └─────────────────┘

服务职责

通信模式

• 基于 HTTP：所有服务间通信均使用 HTTP API
• Socket.IO：服务器到前端的实时更新
• MCP 协议：AI 客户端通过 SSE 或 stdio 连接到 MCP 服务器
• 无直接导入：服务之间完全独立，无共享代码依赖

关键架构优势

• 轻量级容器：每个服务仅包含所需依赖
• 独立扩展：可根据负载独立扩展各服务
• 开发灵活性：团队可在不同服务上并行工作，互不干扰
• 技术多样性：每个服务都采用最适合其特定用途的技术

🔧 配置自定义端口与主机名

默认情况下，Archon 服务运行在以下端口：

• archon-ui：3737
• archon-server：8181
• archon-mcp：8051
• archon-agents：8052（可选）
• archon-agent-work-orders：8053（可选）

更改端口

要使用自定义端口，请将以下变量添加到您的 .env 文件中：

# 服务端口配置
ARCHON_UI_PORT=3737
ARCHON_SERVER_PORT=8181
ARCHON_MCP_PORT=8051
ARCHON_AGENTS_PORT=8052
AGENT_WORK_ORDERS_PORT=8053

示例：使用不同端口：

ARCHON_SERVER_PORT=8282
ARCHON_MCP_PORT=8151

配置主机名

默认情况下，Archon 使用 localhost 作为主机名。您可以通过在 .env 文件中设置 HOST 变量来配置自定义主机名或 IP 地址：

# 主机名配置
HOST=localhost  # 默认

# 自定义主机名示例：
HOST=192.168.1.100     # 使用特定 IP 地址
HOST=archon.local      # 使用自定义域名
HOST=myserver.com      # 使用公共域名

这在以下情况下非常有用：

• 在另一台机器上运行 Archon 并远程访问
• 为您的安装使用自定义域名
• 在无法访问 localhost 的网络环境中部署

更改主机名或端口后：

1. 重启 Docker 容器：docker compose down && docker compose --profile full up -d
2. 访问 UI：http://${HOST}:${ARCHON_UI_PORT}
3. 使用新的主机名和 MCP 端口更新您的 AI 客户端配置

🔧 开发

快速入门

# 安装依赖
make install

# 启动开发（推荐）
make dev        # 后端在 Docker 中运行，前端本地热重载

# 替代方案：全部在 Docker 中运行
make dev-docker # 所有服务都在 Docker 中运行

# 停止所有服务（本地 FE 需手动停止）
make stop

开发模式

混合模式（推荐）- make dev

适用于需要即时前端更新的活跃开发：

• 后端服务在 Docker 中运行（隔离、一致）
• 前端在本地运行，支持热模块替换
• 无需重建 Docker 即可实现即时 UI 更新

全 Docker 模式 - make dev-docker

适用于所有服务都在 Docker 环境中运行的情况：

• 所有服务都在 Docker 容器中运行
• 更适合集成测试
• 前端更新速度较慢

测试与代码质量

# 运行测试
make test       # 运行所有测试
make test-fe    # 运行前端测试
make test-be    # 运行后端测试

# 运行 linter
make lint       # 检查所有代码
make lint-fe    # 检查前端代码
make lint-be    # 检查后端代码

# 检查环境
make check      # 验证环境设置

# 清理
make clean      # 删除容器和卷（需确认）

查看日志

# 使用 Docker Compose 直接查看日志
docker compose logs -f              # 所有服务
docker compose logs -f archon-server # API 服务器
docker compose logs -f archon-mcp    # MCP 服务器
docker compose logs -f archon-ui     # 前端

注意：后端服务在其 uvicorn 命令中配置了 --reload 标志，并将源代码以卷的形式挂载，以便在您进行更改时自动热重载。

故障排除

常见问题及解决方案

端口冲突

如果出现“端口已被占用”的错误：

# 检查哪个进程正在使用端口（例如 3737）
lsof -i :3737

# 停止所有容器和本地服务
make stop

# 在 .env 中更改端口

Docker 权限问题（Linux）

如果遇到 Docker 权限错误：

# 将您的用户添加到 docker 组
sudo usermod -aG docker $USER

# 注销并重新登录，或运行
newgrp docker

Windows 特定问题

• 未找到 Make：通过 Chocolatey、Scoop 或 WSL2 安装 Make（参见 安装 Make）
• 换行符问题：将 Git 配置为使用 LF 结尾：

  git config --global core.autocrlf false
  

前端无法连接到后端

• 检查后端是否正在运行：curl http://localhost:8181/health
• 验证 .env 中的端口配置
• 对于自定义端口，确保同时设置了 ARCHON_SERVER_PORT 和 VITE_ARCHON_SERVER_PORT

Docker Compose 卡住

如果 docker compose 命令卡住：

# 重置 Docker Compose
docker compose down --remove-orphans
docker system prune -f

# 重启 Docker Desktop（如适用）

热重载不起作用

• 前端：确保您处于混合模式（make dev）以获得最佳 HMR 体验
• 后端：检查 docker-compose.yml 中卷是否正确挂载
• 文件权限：在某些系统上，挂载的卷可能存在权限问题

📈 进展

📄 许可证

Archon 社区许可证 (ACL) v1.2 - 详情请参阅 LICENSE 文件。

简而言之：Archon 是免费、开源且可随意修改的。您可以运行它、分叉它、分享它，但未经许可不得将其作为服务出售。

Archon 快速上手指南

Archon 是一个专为 AI 编程助手（如 Claude Code、Cursor、Windsurf 等）打造的指挥中心。它通过 Model Context Protocol (MCP) 服务器，让 AI 代理能够访问你的私有知识库（文档、代码库）、执行智能搜索并管理开发任务。

环境准备

在开始之前，请确保你的系统满足以下要求：

• Docker Desktop: 必须安装并运行（用于编排微服务）。
• Node.js 18+: 仅在进行混合开发模式时需要，普通用户可不安装。
• Supabase 账户:
  • 可使用免费云端版 (supabase.com)。
  • 也可使用本地部署版。
• LLM API Key:
  • 默认支持 OpenAI。
  • 同时也支持 Google Gemini 和 Ollama（本地模型）。
• (可选) GNU Make: 用于简化开发命令，非必须但推荐。

安装步骤

1. 克隆仓库

推荐使用 stable 分支以获得最稳定的体验：

git clone -b stable https://github.com/coleam00/archon.git
cd archon

2. 配置环境变量

复制示例配置文件并根据你的环境进行编辑：

cp .env.example .env

使用编辑器打开 .env 文件，填入以下关键信息：

• Supabase 配置:
  • SUPABASE_URL: 你的项目地址。
    • 云端版：https://<你的项目 ID>.supabase.co
    • 本地版：http://host.docker.internal:8000
  • SUPABASE_SERVICE_KEY: 服务角色密钥。
    • 注意：如果是云端版，请使用旧的 legacy key（较长的那个），不要使用新类型的 key。
    • 如果是本地版，运行 supabase status -o env 获取。
• LLM 配置: 后续可在 Web 界面中设置，也可在此预填。

3. 初始化数据库

登录你的 Supabase Dashboard，进入 SQL Editor：

1. 打开项目根目录下的 migration/complete_setup.sql 文件。
2. 复制全部内容。
3. 在 SQL Editor 中粘贴并执行，以创建所需的表结构。

4. 启动服务

使用 Docker Compose 启动所有核心微服务（包括 API、MCP 服务器和 Web 界面）：

docker compose up --build -d

启动完成后，主要服务端口如下：

• Web 界面: http://localhost:3737
• API 服务: http://localhost:8181
• MCP 服务器: http://localhost:8051

5. 完成初始化配置

1. 浏览器访问 http://localhost:3737。
2. 跟随引导流程输入你的 LLM API Key（OpenAI/Gemini/Ollama）。
3. 配置完成后即可进入主界面。

基本使用

1. 构建知识库 (Knowledge Base)

让 Archon 学习你的项目文档：

• 爬取网站: 进入 Knowledge Base -> Crawl Website，输入文档 URL（例如 https://ai.pydantic.dev/llms.txt），系统将自动抓取并索引内容。
• 上传文档: 直接上传 PDF、Word 或 Markdown 文件，系统会自动分块处理。

2. 管理项目与任务

• 进入 Projects 创建新项目。
• 添加具体任务（Tasks），你可以利用内置的 AI 代理辅助生成需求或拆解任务。

3. 连接 AI 编程助手

这是 Archon 的核心功能，让你的 IDE 插件拥有“记忆”：

1. 在 Archon 界面进入 MCP Dashboard。
2. 复制对应客户端的连接配置（Connection Config）。
3. 在你的 AI 工具中配置 MCP：
   • Cursor / Windsurf / Claude Code: 在设置的 MCP 部分粘贴配置。
   • 配置成功后，这些 AI 助手即可调用 Archon 的工具进行 RAG 搜索、读取项目任务和上下文。

4. 验证测试

• 在 AI 聊天窗口中询问关于你刚才上传的文档或网站的内容。
• 请求 AI 根据 Archon 中的任务列表更新代码。
• 观察 Archon 界面中的实时状态更新。

提示：如需升级 Archon，只需执行 git pull 然后重新运行 docker compose up -d --build 即可。如有数据库迁移更新，系统会在 Web 界面的 Settings 中提示。