Archon项目配置指南：从环境搭建到多终端协同开发

项目概述

Archon是一个基于Python开发的智能代理构建框架，它整合了多种技术组件来实现文档爬取、知识图谱构建和智能代理交互功能。该项目支持两种主要使用模式：通过Streamlit提供的Web界面交互，以及作为MCP服务器与AI集成开发环境（如Cursor IDE）深度集成。

环境配置详解

基础环境准备

项目运行需要Python 3.7+环境，建议使用虚拟环境隔离依赖。创建并激活虚拟环境的命令如下：

python -m venv venv
source venv/bin/activate  # Linux/MacOS
venv\Scripts\activate  # Windows

依赖安装

项目依赖包括Playwright（用于网页爬取）、Supabase客户端、AI接口等，可通过以下命令一键安装：

pip install -r requirements.txt
playwright install  # 安装浏览器驱动

关键组件配置

数据库配置

项目使用Supabase作为后端存储，需要执行以下操作：

1. 将.env.example重命名为.env并填写实际参数
2. 在Supabase控制台执行提供的SQL脚本，该脚本会：
   • 启用pgvector扩展支持向量搜索
   • 创建site_pages表结构
   • 建立全文检索索引
   • 设置行级安全策略

验证数据库配置成功的命令示例：

-- 检查表结构
\d site_pages

-- 验证搜索函数
\df match_site_pages

MCP服务器配置（AI IDE集成）

MCP（Multi-Code Protocol）服务器使Archon能与Cursor等智能IDE深度集成。配置要点包括：

1. 生成MCP配置文件：

python setup_mcp.py

2. 在Cursor IDE中：
   • 进入设置 > Features > MCP
   • 添加新服务器，类型选择"command"
   • 命令路径应指向虚拟环境中的Python解释器
   • 参数指定为mcp_server.py的完整路径

常见问题处理：

• 端口冲突：检查8100端口使用情况（lsof -i :8100）
• 路径错误：确保配置中使用的是系统正确的路径分隔符
• 权限问题：虚拟环境目录需有执行权限

核心功能使用

文档爬取功能

通过集成Playwright实现自动化文档采集：

python crawl_pydantic_ai_docs.py

该脚本会自动：

• 模拟浏览器访问目标文档站点
• 提取结构化内容
• 将数据持久化到Supabase
• 生成文档向量嵌入

双模式运行方案

方案一：Web交互模式

启动Streamlit可视化界面：

streamlit run streamlit_ui.py

访问本地8501端口即可使用图形化操作界面。

方案二：MCP服务模式

1. 启动图谱服务：

python graph_service.py

2. 在IDE中刷新MCP连接
3. 通过自然语言指令调用Archon功能

架构设计亮点

1. 服务解耦：将图谱服务独立为API端点，避免与MCP协议冲突
2. 模型分层：
   • PRIMARY_MODEL：主代理模型处理核心逻辑
   • REASONER_MODEL：专用规划模型优化任务分解
3. 向量检索：集成pgvector实现语义搜索能力

最佳实践建议

1. 开发环境：

   • 为不同功能组件使用独立终端窗口
   • 按照固定顺序启动服务（数据库→图谱→MCP/UI）

2. 调试技巧：

   • 使用pkill -f python快速终止所有服务
   • 检查各服务端口监听状态（8100、8501等）

3. 性能优化：

   • 对高频查询字段建立复合索引
   • 考虑使用连接池管理数据库连接

该项目通过模块化设计和多种集成方式，为开发者构建智能代理系统提供了灵活的基础框架。其架构设计特别考虑了生产环境下的可维护性和扩展性需求，是研究AI代理系统的优质参考实现。