[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-coleam00--Archon":3,"tool-coleam00--Archon":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,2,"2026-04-06T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":78,"owner_email":78,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":112,"forks":113,"last_commit_at":114,"license":115,"difficulty_score":116,"env_os":117,"env_gpu":118,"env_ram":118,"env_deps":119,"category_tags":127,"github_topics":78,"view_count":32,"oss_zip_url":78,"oss_zip_packed_at":78,"status":17,"created_at":128,"updated_at":129,"faqs":130,"releases":159},4492,"coleam00\u002FArchon","Archon","Beta release of Archon OS - the knowledge and task management backbone for AI coding assistants.","Archon 是一款专为 AI 编程助手打造的“指挥中心”，旨在成为连接开发者与智能代理的知识与任务管理核心。它解决了当前 AI 编码工具普遍存在的痛点：缺乏对项目专属文档、上下文背景及复杂任务的持久化记忆与管理能力，导致 AI 在长周期开发中容易“失忆”或偏离目标。\n\n通过 Archon，开发者可以构建个性化的知识库（支持爬取网站、上传 PDF 等），并利用先进的 RAG（检索增强生成）策略实现智能搜索。更重要的是，它作为一个标准的 MCP（模型上下文协议）服务器，能够无缝对接 Claude Code、Cursor、Windsurf 等主流 AI 编程工具。这意味着你的 AI 助手不仅能读取代码，还能实时访问项目文档、理解任务进度，并在你更新内容时同步感知，从而实现真正的人机协同开发。\n\nArchon 特别适合软件开发者、技术团队以及希望提升 AI 编码效率的研究人员使用。无论你是维护旧项目还是从零构建新系统，Archon 都能通过统一的上下文工程环境，显著提升 AI 输出代码的准确性和逻辑连贯性。目前该项目处于 Beta 阶段，由社区驱动迭代，是探索下一代 AI 辅助开发工作流的理","Archon 是一款专为 AI 编程助手打造的“指挥中心”，旨在成为连接开发者与智能代理的知识与任务管理核心。它解决了当前 AI 编码工具普遍存在的痛点：缺乏对项目专属文档、上下文背景及复杂任务的持久化记忆与管理能力，导致 AI 在长周期开发中容易“失忆”或偏离目标。\n\n通过 Archon，开发者可以构建个性化的知识库（支持爬取网站、上传 PDF 等），并利用先进的 RAG（检索增强生成）策略实现智能搜索。更重要的是，它作为一个标准的 MCP（模型上下文协议）服务器，能够无缝对接 Claude Code、Cursor、Windsurf 等主流 AI 编程工具。这意味着你的 AI 助手不仅能读取代码，还能实时访问项目文档、理解任务进度，并在你更新内容时同步感知，从而实现真正的人机协同开发。\n\nArchon 特别适合软件开发者、技术团队以及希望提升 AI 编码效率的研究人员使用。无论你是维护旧项目还是从零构建新系统，Archon 都能通过统一的上下文工程环境，显著提升 AI 输出代码的准确性和逻辑连贯性。目前该项目处于 Beta 阶段，由社区驱动迭代，是探索下一代 AI 辅助开发工作流的理想选择。","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_97814319171e.png\" alt=\"Archon Main Graphic\" width=\"853\" height=\"422\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n   \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F13964\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_4a68feb902da.png\" alt=\"coleam00%2FArchon | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>Power up your AI coding assistants with your own custom knowledge base and task management as an MCP server\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa> •\n  \u003Ca href=\"#upgrading\">Upgrading\u003C\u002Fa> •\n  \u003Ca href=\"#whats-included\">What's Included\u003C\u002Fa> •\n  \u003Ca href=\"#architecture\">Architecture\u003C\u002Fa> •\n  \u003Ca href=\"#troubleshooting\">Troubleshooting\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## 🎯 What is Archon?\n\n> Archon is currently in beta! Expect things to not work 100%, and please feel free to share any feedback and contribute with fixes\u002Fnew features! Thank you to everyone for all the excitement we have for Archon already, as well as the bug reports, PRs, and discussions. It's a lot for our small team to get through but we're committed to addressing everything and making Archon into the best tool it possibly can be!\n\nArchon is the **command center** for AI coding assistants. For you, it's a sleek interface to manage knowledge, context, and tasks for your projects. For the AI coding assistant(s), it's a **Model Context Protocol (MCP) server** to collaborate on and leverage the same knowledge, context, and tasks. Connect Claude Code, Kiro, Cursor, Windsurf, etc. to give your AI agents access to:\n\n- **Your documentation** (crawled websites, uploaded PDFs\u002Fdocs)\n- **Smart search capabilities** with advanced RAG strategies\n- **Task management** integrated with your knowledge base\n- **Real-time updates** as you add new content and collaborate with your coding assistant on tasks\n- **Much more** coming soon to build Archon into an integrated environment for all context engineering\n\nThis new vision for Archon replaces the old one (the agenteer). Archon used to be the AI agent that builds other agents, and now you can use Archon to do that and more.\n\n> It doesn't matter what you're building or if it's a new\u002Fexisting codebase - Archon's knowledge and task management capabilities will improve the output of **any** AI driven coding.\n\n## 🔗 Important Links\n\n- **[GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fdiscussions)** - Join the conversation and share ideas about Archon\n- **[Contributing Guide](CONTRIBUTING.md)** - How to get involved and contribute to Archon\n- **[Introduction Video](https:\u002F\u002Fyoutu.be\u002F8pRc_s2VQIo)** - Getting started guide and vision for Archon\n- **[Archon Kanban Board](https:\u002F\u002Fgithub.com\u002Fusers\u002Fcoleam00\u002Fprojects\u002F1)** - Where maintainers are managing issues\u002Ffeatures\n- **[Dynamous AI Mastery](https:\u002F\u002Fdynamous.ai)** - The birthplace of Archon - come join a vibrant community of other early AI adopters all helping each other transform their careers and businesses!\n\n## Quick Start\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fyoutu.be\u002FDMXyDpnzNpY\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_36a332979842.jpg\" alt=\"Archon Setup Tutorial\" width=\"640\" \u002F>\n  \u003C\u002Fa>\n  \u003Cbr\u002F>\n  \u003Cem>📺 Click to watch the setup tutorial on YouTube\u003C\u002Fem>\n  \u003Cbr\u002F>\n  \u003Ca href=\".\u002Farchon-example-workflow\">-> Example AI coding workflow in the video \u003C-\u003C\u002Fa>\n\u003C\u002Fp>\n\n### Prerequisites\n\n- [Docker Desktop](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F)\n- [Node.js 18+](https:\u002F\u002Fnodejs.org\u002F) (for hybrid development mode)\n- [Supabase](https:\u002F\u002Fsupabase.com\u002F) account (free tier or local Supabase both work)\n- [OpenAI API key](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys) (Gemini and Ollama are supported too!)\n- (OPTIONAL) [Make](https:\u002F\u002Fwww.gnu.org\u002Fsoftware\u002Fmake\u002F) (see [Installing Make](#installing-make) below)\n\n### Setup Instructions\n\n1. **Clone Repository**:\n   ```bash\n   git clone -b stable https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Farchon.git\n   ```\n   ```bash\n   cd archon\n   ```\n   \n   **Note:** The `stable` branch is recommended for using Archon. If you want to contribute or try the latest features, use the `main` branch with `git clone https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Farchon.git`\n2. **Environment Configuration**:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your Supabase credentials:\n   # SUPABASE_URL=https:\u002F\u002Fyour-project.supabase.co\n   # SUPABASE_SERVICE_KEY=your-service-key-here\n   ```\n\n   IMPORTANT NOTES:\n   - For cloud Supabase: They recently introduced a new type of service role key but use the legacy one (the longer one).\n   - For local Supabase: Set `SUPABASE_URL` to http:\u002F\u002Fhost.docker.internal:8000 (unless you have an IP address set up). To get `SUPABASE_SERVICE_KEY` run `supabase status -o env`.\n\n3. **Database Setup**: In your [Supabase project](https:\u002F\u002Fsupabase.com\u002Fdashboard) SQL Editor, copy, paste, and execute the contents of `migration\u002Fcomplete_setup.sql`\n\n4. **Start Services** (choose one):\n\n   **Full Docker Mode (Recommended for Normal Archon Usage)**\n\n   ```bash\n   docker compose up --build -d\n   ```\n\n   This starts all core microservices in Docker:\n   - **Server**: Core API and business logic (Port: 8181)\n   - **MCP Server**: Protocol interface for AI clients (Port: 8051)\n   - **UI**: Web interface (Port: 3737)\n\n   Ports are configurable in your .env as well!\n\n5. **Configure API Keys**:\n   - Open http:\u002F\u002Flocalhost:3737\n   - You'll automatically be brought through an onboarding flow to set your API key (OpenAI is default)\n\n## ⚡ Quick Test\n\nOnce everything is running:\n\n1. **Test Web Crawling**: Go to http:\u002F\u002Flocalhost:3737 → Knowledge Base → \"Crawl Website\" → Enter a doc URL (such as https:\u002F\u002Fai.pydantic.dev\u002Fllms.txt)\n2. **Test Document Upload**: Knowledge Base → Upload a PDF\n3. **Test Projects**: Projects → Create a new project and add tasks\n4. **Integrate with your AI coding assistant**: MCP Dashboard → Copy connection config for your AI coding assistant \n\n## Installing Make\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🛠️ Make installation (OPTIONAL - For Dev Workflows)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n### Windows\n\n```bash\n# Option 1: Using Chocolatey\nchoco install make\n\n# Option 2: Using Scoop\nscoop install make\n\n# Option 3: Using WSL2\nwsl --install\n# Then in WSL: sudo apt-get install make\n```\n\n### macOS\n\n```bash\n# Make comes pre-installed on macOS\n# If needed: brew install make\n```\n\n### Linux\n\n```bash\n# Debian\u002FUbuntu\nsudo apt-get install make\n\n# RHEL\u002FCentOS\u002FFedora\nsudo yum install make\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚀 Quick Command Reference for Make\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr\u002F>\n\n| Command           | Description                                             |\n| ----------------- | ------------------------------------------------------- |\n| `make dev`        | Start hybrid dev (backend in Docker, frontend local) ⭐ |\n| `make dev-docker` | Everything in Docker                                    |\n| `make stop`       | Stop all services                                       |\n| `make test`       | Run all tests                                           |\n| `make lint`       | Run linters                                             |\n| `make install`    | Install dependencies                                    |\n| `make check`      | Check environment setup                                 |\n| `make clean`      | Remove containers and volumes (with confirmation)       |\n\n\u003C\u002Fdetails>\n\n## 🔄 Database Reset (Start Fresh if Needed)\n\nIf you need to completely reset your database and start fresh:\n\n\u003Cdetails>\n\u003Csummary>⚠️ \u003Cstrong>Reset Database - This will delete ALL data for Archon!\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n1. **Run Reset Script**: In your Supabase SQL Editor, run the contents of `migration\u002FRESET_DB.sql`\n\n   ⚠️ WARNING: This will delete all Archon specific tables and data! Nothing else will be touched in your DB though.\n\n2. **Rebuild Database**: After reset, run `migration\u002Fcomplete_setup.sql` to create all the tables again.\n\n3. **Restart Services**:\n\n   ```bash\n   docker compose --profile full up -d\n   ```\n\n4. **Reconfigure**:\n   - Select your LLM\u002Fembedding provider and set the API key again\n   - Re-upload any documents or re-crawl websites\n\nThe reset script safely removes all tables, functions, triggers, and policies with proper dependency handling.\n\n\u003C\u002Fdetails>\n\n## 📚 Documentation\n\n### Core Services\n\n| Service                    | Container Name             | Default URL           | Purpose                                    |\n| -------------------------- | -------------------------- | --------------------- | ------------------------------------------ |\n| **Web Interface**          | archon-ui                  | http:\u002F\u002Flocalhost:3737 | Main dashboard and controls                |\n| **API Service**            | archon-server              | http:\u002F\u002Flocalhost:8181 | Web crawling, document processing          |\n| **MCP Server**             | archon-mcp                 | http:\u002F\u002Flocalhost:8051 | Model Context Protocol interface           |\n| **Agents Service**         | archon-agents              | http:\u002F\u002Flocalhost:8052 | AI\u002FML operations, reranking                |\n| **Agent Work Orders** *(optional)* | archon-agent-work-orders | http:\u002F\u002Flocalhost:8053 | Workflow execution with Claude Code CLI    |  \n\n## Upgrading\n\nTo upgrade Archon to the latest version:\n\n1. **Pull latest changes**:\n   ```bash\n   git pull\n   ```\n\n2. **Rebuild and restart containers**:\n   ```bash\n   docker compose up -d --build\n   ```\n   This rebuilds containers with the latest code and restarts all services.\n\n3. **Check for database migrations**:\n   - Open the Archon settings in your browser: [http:\u002F\u002Flocalhost:3737\u002Fsettings](http:\u002F\u002Flocalhost:3737\u002Fsettings)\n   - Navigate to the **Database Migrations** section\n   - If there are pending migrations, the UI will display them with clear instructions\n   - Click on each migration to view and copy the SQL\n   - Run the SQL scripts in your Supabase SQL editor in the order shown\n\n## What's Included\n\n### 🧠 Knowledge Management\n\n- **Smart Web Crawling**: Automatically detects and crawls entire documentation sites, sitemaps, and individual pages\n- **Document Processing**: Upload and process PDFs, Word docs, markdown files, and text documents with intelligent chunking\n- **Code Example Extraction**: Automatically identifies and indexes code examples from documentation for enhanced search\n- **Vector Search**: Advanced semantic search with contextual embeddings for precise knowledge retrieval\n- **Source Management**: Organize knowledge by source, type, and tags for easy filtering\n\n### 🤖 AI Integration\n\n- **Model Context Protocol (MCP)**: Connect any MCP-compatible client (Claude Code, Cursor, even non-AI coding assistants like Claude Desktop)\n- **MCP Tools**: Comprehensive yet simple set of tools for RAG queries, task management, and project operations\n- **Multi-LLM Support**: Works with OpenAI, Ollama, and Google Gemini models\n- **RAG Strategies**: Hybrid search, contextual embeddings, and result reranking for optimal AI responses\n- **Real-time Streaming**: Live responses from AI agents with progress tracking\n\n### 📋 Project & Task Management\n\n- **Hierarchical Projects**: Organize work with projects, features, and tasks in a structured workflow\n- **AI-Assisted Creation**: Generate project requirements and tasks using integrated AI agents\n- **Document Management**: Version-controlled documents with collaborative editing capabilities\n- **Progress Tracking**: Real-time updates and status management across all project activities\n\n### 🔄 Real-time Collaboration\n\n- **WebSocket Updates**: Live progress tracking for crawling, processing, and AI operations\n- **Multi-user Support**: Collaborative knowledge building and project management\n- **Background Processing**: Asynchronous operations that don't block the user interface\n- **Health Monitoring**: Built-in service health checks and automatic reconnection\n\n## Architecture\n\n### Microservices Structure\n\nArchon uses true microservices architecture with clear separation of concerns:\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Frontend UI   │    │  Server (API)   │    │   MCP Server    │    │ Agents Service  │\n│                 │    │                 │    │                 │    │                 │\n│  React + Vite   │◄──►│    FastAPI +    │◄──►│    Lightweight  │◄──►│   PydanticAI    │\n│  Port 3737      │    │    SocketIO     │    │    HTTP Wrapper │    │   Port 8052     │\n│                 │    │    Port 8181    │    │    Port 8051    │    │                 │\n└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘\n         │                        │                        │                        │\n         └────────────────────────┼────────────────────────┼────────────────────────┘\n                                  │                        │\n                         ┌─────────────────┐               │\n                         │    Database     │               │\n                         │                 │               │\n                         │    Supabase     │◄──────────────┘\n                         │    PostgreSQL   │\n                         │    PGVector     │\n                         └─────────────────┘\n```\n\n### Service Responsibilities\n\n| Service                  | Location                       | Purpose                          | Key Features                                                       |\n| ------------------------ | ------------------------------ | -------------------------------- | ------------------------------------------------------------------ |\n| **Frontend**             | `archon-ui-main\u002F`              | Web interface and dashboard      | React, TypeScript, TailwindCSS, Socket.IO client                   |\n| **Server**               | `python\u002Fsrc\u002Fserver\u002F`           | Core business logic and APIs     | FastAPI, service layer, Socket.IO broadcasts, all ML\u002FAI operations |\n| **MCP Server**           | `python\u002Fsrc\u002Fmcp\u002F`              | MCP protocol interface           | Lightweight HTTP wrapper, MCP tools, session management            |\n| **Agents**               | `python\u002Fsrc\u002Fagents\u002F`           | PydanticAI agent hosting         | Document and RAG agents, streaming responses                       |\n| **Agent Work Orders** *(optional)* | `python\u002Fsrc\u002Fagent_work_orders\u002F` | Workflow execution engine | Claude Code CLI automation, repository management, SSE updates |\n\n### Communication Patterns\n\n- **HTTP-based**: All inter-service communication uses HTTP APIs\n- **Socket.IO**: Real-time updates from Server to Frontend\n- **MCP Protocol**: AI clients connect to MCP Server via SSE or stdio\n- **No Direct Imports**: Services are truly independent with no shared code dependencies\n\n### Key Architectural Benefits\n\n- **Lightweight Containers**: Each service contains only required dependencies\n- **Independent Scaling**: Services can be scaled independently based on load\n- **Development Flexibility**: Teams can work on different services without conflicts\n- **Technology Diversity**: Each service uses the best tools for its specific purpose\n\n## 🔧 Configuring Custom Ports & Hostname\n\nBy default, Archon services run on the following ports:\n\n- **archon-ui**: 3737\n- **archon-server**: 8181\n- **archon-mcp**: 8051\n- **archon-agents**: 8052 (optional)\n- **archon-agent-work-orders**: 8053 (optional)\n\n### Changing Ports\n\nTo use custom ports, add these variables to your `.env` file:\n\n```bash\n# Service Ports Configuration\nARCHON_UI_PORT=3737\nARCHON_SERVER_PORT=8181\nARCHON_MCP_PORT=8051\nARCHON_AGENTS_PORT=8052\nAGENT_WORK_ORDERS_PORT=8053\n```\n\nExample: Running on different ports:\n\n```bash\nARCHON_SERVER_PORT=8282\nARCHON_MCP_PORT=8151\n```\n\n### Configuring Hostname\n\nBy default, Archon uses `localhost` as the hostname. You can configure a custom hostname or IP address by setting the `HOST` variable in your `.env` file:\n\n```bash\n# Hostname Configuration\nHOST=localhost  # Default\n\n# Examples of custom hostnames:\nHOST=192.168.1.100     # Use specific IP address\nHOST=archon.local      # Use custom domain\nHOST=myserver.com      # Use public domain\n```\n\nThis is useful when:\n\n- Running Archon on a different machine and accessing it remotely\n- Using a custom domain name for your installation\n- Deploying in a network environment where `localhost` isn't accessible\n\nAfter changing hostname or ports:\n\n1. Restart Docker containers: `docker compose down && docker compose --profile full up -d`\n2. Access the UI at: `http:\u002F\u002F${HOST}:${ARCHON_UI_PORT}`\n3. Update your AI client configuration with the new hostname and MCP port\n\n## 🔧 Development\n\n### Quick Start\n\n```bash\n# Install dependencies\nmake install\n\n# Start development (recommended)\nmake dev        # Backend in Docker, frontend local with hot reload\n\n# Alternative: Everything in Docker\nmake dev-docker # All services in Docker\n\n# Stop everything (local FE needs to be stopped manually)\nmake stop\n```\n\n### Development Modes\n\n#### Hybrid Mode (Recommended) - `make dev`\n\nBest for active development with instant frontend updates:\n\n- Backend services run in Docker (isolated, consistent)\n- Frontend runs locally with hot module replacement\n- Instant UI updates without Docker rebuilds\n\n#### Full Docker Mode - `make dev-docker`\n\nFor all services in Docker environment:\n\n- All services run in Docker containers\n- Better for integration testing\n- Slower frontend updates\n\n### Testing & Code Quality\n\n```bash\n# Run tests\nmake test       # Run all tests\nmake test-fe    # Run frontend tests\nmake test-be    # Run backend tests\n\n# Run linters\nmake lint       # Lint all code\nmake lint-fe    # Lint frontend code\nmake lint-be    # Lint backend code\n\n# Check environment\nmake check      # Verify environment setup\n\n# Clean up\nmake clean      # Remove containers and volumes (asks for confirmation)\n```\n\n### Viewing Logs\n\n```bash\n# View logs using Docker Compose directly\ndocker compose logs -f              # All services\ndocker compose logs -f archon-server # API server\ndocker compose logs -f archon-mcp    # MCP server\ndocker compose logs -f archon-ui     # Frontend\n```\n\n**Note**: The backend services are configured with `--reload` flag in their uvicorn commands and have source code mounted as volumes for automatic hot reloading when you make changes.\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Port Conflicts\n\nIf you see \"Port already in use\" errors:\n\n```bash\n# Check what's using a port (e.g., 3737)\nlsof -i :3737\n\n# Stop all containers and local services\nmake stop\n\n# Change the port in .env\n```\n\n#### Docker Permission Issues (Linux)\n\nIf you encounter permission errors with Docker:\n\n```bash\n# Add your user to the docker group\nsudo usermod -aG docker $USER\n\n# Log out and back in, or run\nnewgrp docker\n```\n\n#### Windows-Specific Issues\n\n- **Make not found**: Install Make via Chocolatey, Scoop, or WSL2 (see [Installing Make](#installing-make))\n- **Line ending issues**: Configure Git to use LF endings:\n  ```bash\n  git config --global core.autocrlf false\n  ```\n\n#### Frontend Can't Connect to Backend\n\n- Check backend is running: `curl http:\u002F\u002Flocalhost:8181\u002Fhealth`\n- Verify port configuration in `.env`\n- For custom ports, ensure both `ARCHON_SERVER_PORT` and `VITE_ARCHON_SERVER_PORT` are set\n\n#### Docker Compose Hangs\n\nIf `docker compose` commands hang:\n\n```bash\n# Reset Docker Compose\ndocker compose down --remove-orphans\ndocker system prune -f\n\n# Restart Docker Desktop (if applicable)\n```\n\n#### Hot Reload Not Working\n\n- **Frontend**: Ensure you're running in hybrid mode (`make dev`) for best HMR experience\n- **Backend**: Check that volumes are mounted correctly in `docker-compose.yml`\n- **File permissions**: On some systems, mounted volumes may have permission issues\n\n## 📈 Progress\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#coleam00\u002FArchon&Date\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_04b98cc51736.png\" width=\"500\" alt=\"Star History Chart\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n## 📄 License\n\nArchon Community License (ACL) v1.2 - see [LICENSE](LICENSE) file for details.\n\n**TL;DR**: Archon is free, open, and hackable. Run it, fork it, share it - just don't sell it as-a-service without permission.\n","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_97814319171e.png\" alt=\"Archon 主图\" width=\"853\" height=\"422\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n   \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F13964\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_4a68feb902da.png\" alt=\"coleam00%2FArchon | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>通过自定义知识库和任务管理，将您的 AI 编码助手升级为 MCP 服务器\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#quick-start\">快速入门\u003C\u002Fa> •\n  \u003Ca href=\"#upgrading\">升级\u003C\u002Fa> •\n  \u003Ca href=\"#whats-included\">包含内容\u003C\u002Fa> •\n  \u003Ca href=\"#architecture\">架构\u003C\u002Fa> •\n  \u003Ca href=\"#troubleshooting\">故障排除\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## 🎯 Archon 是什么？\n\n> Archon 目前处于测试阶段！请做好部分功能可能无法正常工作的准备，并随时提出反馈或贡献修复与新功能！感谢大家对 Archon 的热情支持，以及提交的错误报告、拉取请求和讨论。虽然对我们小团队来说工作量很大，但我们致力于解决所有问题，让 Archon 成为尽可能优秀的工具！\n\nArchon 是 AI 编码助手的**指挥中心**。对于您而言，它是一个简洁的界面，用于管理项目的知识、上下文和任务；对于 AI 编码助手来说，它则是一个**模型上下文协议（MCP）服务器**，可以协同使用并共享相同的知识、上下文和任务。您可以连接 Claude Code、Kiro、Cursor、Windsurf 等工具，让您的 AI 助手访问以下内容：\n\n- **您的文档**（爬取的网站、上传的 PDF\u002F文档）\n- **智能搜索功能**，采用先进的 RAG 策略\n- **任务管理**，与您的知识库无缝集成\n- **实时更新**，当您添加新内容并与编码助手协作处理任务时\n- **更多功能**，即将推出，旨在将 Archon 打造成一个完整的上下文工程一体化环境\n\n这一全新的 Archon 架构取代了旧版本（agenteer）。过去，Archon 是用来构建其他 AI 助手的 AI 代理，而现在，您不仅可以利用 Archon 来完成这项任务，还能实现更多功能。\n\n> 无论您正在构建什么项目，无论是全新的代码库还是现有的代码库——Archon 的知识管理和任务管理能力都将提升**任何** AI 驱动编码工作的成果。\n\n## 🔗 重要链接\n\n- **[GitHub 讨论区](https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fdiscussions)** - 加入讨论，分享关于 Archon 的想法\n- **[贡献指南](CONTRIBUTING.md)** - 如何参与并为 Archon 做贡献\n- **[介绍视频](https:\u002F\u002Fyoutu.be\u002F8pRc_s2VQIo)** - Archon 的入门指南及愿景\n- **[Archon 看板](https:\u002F\u002Fgithub.com\u002Fusers\u002Fcoleam00\u002Fprojects\u002F1)** - 维护人员在此管理问题和功能\n- **[Dynamous AI Mastery](https:\u002F\u002Fdynamous.ai)** - Archon 的诞生地——加入这个充满活力的早期 AI 技术采用者社区，共同助力彼此的职业与业务转型！\n\n## 快速入门\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fyoutu.be\u002FDMXyDpnzNpY\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_36a332979842.jpg\" alt=\"Archon 设置教程\" width=\"640\" \u002F>\n  \u003C\u002Fa>\n  \u003Cbr\u002F>\n  \u003Cem>📺 点击观看 YouTube 上的设置教程\u003C\u002Fem>\n  \u003Cbr\u002F>\n  \u003Ca href=\".\u002Farchon-example-workflow\">-> 视频中的 AI 编码工作流程示例 \u003C-\u003C\u002Fa>\n\u003C\u002Fp>\n\n### 先决条件\n\n- [Docker Desktop](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F)\n- [Node.js 18+](https:\u002F\u002Fnodejs.org\u002F)（用于混合开发模式）\n- [Supabase](https:\u002F\u002Fsupabase.com\u002F) 账户（免费层级或本地 Supabase 均可）\n- [OpenAI API 密钥](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys)（也支持 Gemini 和 Ollama！）\n- （可选）[Make](https:\u002F\u002Fwww.gnu.org\u002Fsoftware\u002Fmake\u002F)（见下方【安装 Make】）\n\n### 设置步骤\n\n1. **克隆仓库**：\n   ```bash\n   git clone -b stable https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Farchon.git\n   ```\n   ```bash\n   cd archon\n   ```\n\n   **注意：** 推荐使用 `stable` 分支来运行 Archon。如果您想参与贡献或尝试最新功能，请使用 `main` 分支，执行 `git clone https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Farchon.git`。\n   \n2. **配置环境变量**：\n\n   ```bash\n   cp .env.example .env\n   # 编辑 .env 文件，添加您的 Supabase 凭证：\n   # SUPABASE_URL=https:\u002F\u002Fyour-project.supabase.co\n   # SUPABASE_SERVICE_KEY=your-service-key-here\n   ```\n\n   重要提示：\n   - 对于云端 Supabase：他们最近推出了新型服务角色密钥，但请使用旧版密钥（较长的那种）。\n   - 对于本地 Supabase：将 `SUPABASE_URL` 设置为 http:\u002F\u002Fhost.docker.internal:8000（除非您已设置 IP 地址）。要获取 `SUPABASE_SERVICE_KEY`，请运行 `supabase status -o env`。\n   \n3. **数据库设置**：在您的 [Supabase 项目](https:\u002F\u002Fsupabase.com\u002Fdashboard) SQL 编辑器中，复制并执行 `migration\u002Fcomplete_setup.sql` 中的内容。\n\n4. **启动服务**（任选其一）：\n\n   **完全 Docker 模式（推荐用于常规 Archon 使用）**\n\n   ```bash\n   docker compose up --build -d\n   ```\n\n   这将启动所有核心微服务：\n   - **服务器**：核心 API 和业务逻辑（端口：8181）\n   - **MCP 服务器**：AI 客户端的协议接口（端口：8051）\n   - **UI**：Web 界面（端口：3737）\n\n   您也可以在 `.env` 文件中自定义这些端口！\n\n5. **配置 API 密钥**：\n   - 打开 http:\u002F\u002Flocalhost:3737\n   - 您将自动进入引导流程，以设置您的 API 密钥（默认为 OpenAI）。\n\n## ⚡ 快速测试\n\n一切运行正常后：\n\n1. **测试网页抓取**：前往 http:\u002F\u002Flocalhost:3737 → 知识库 → “抓取网站” → 输入一个文档 URL（例如 https:\u002F\u002Fai.pydantic.dev\u002Fllms.txt）\n2. **测试文档上传**：知识库 → 上传一个 PDF\n3. **测试项目**：项目 → 创建新项目并添加任务\n4. **与您的 AI 编码助手集成**：MCP 控制台 → 复制连接配置信息，供您的 AI 编码助手使用\n\n## 安装 Make\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🛠️ 安装 Make（可选——用于开发工作流）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n### Windows\n\n```bash\n# 方法 1：使用 Chocolatey\nchoco install make\n\n# 方法 2：使用 Scoop\nscoop install make\n\n# 方法 3：使用 WSL2\nwsl --install\n# 然后在 WSL 中：sudo apt-get install make\n```\n\n### macOS\n\n```bash\n# macOS 自带 Make\n# 如需安装：brew install make\n```\n\n### Linux\n\n```bash\n# Debian\u002FUbuntu\nsudo apt-get install make\n\n# RHEL\u002FCentOS\u002FFedora\nsudo yum install make\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚀 Make 快速命令参考\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr\u002F>\n\n| 命令           | 描述                                             |\n| ----------------- | ------------------------------------------------------- |\n| `make dev`        | 启动混合开发模式（后端在 Docker 中，前端本地） ⭐ |\n| `make dev-docker` | 所有服务都在 Docker 中运行                                    |\n| `make stop`       | 停止所有服务                                       |\n| `make test`       | 运行所有测试                                           |\n| `make lint`       | 运行代码检查工具                                             |\n| `make install`    | 安装依赖项                                                    |\n| `make check`      | 检查环境配置                                                 |\n| `make clean`      | 移除容器和数据卷（需确认）                                       |\n\n\u003C\u002Fdetails>\n\n## 🔄 数据库重置（如有需要从头开始）\n\n如果您需要完全重置数据库并从头开始：\n\n\u003Cdetails>\n\u003Csummary>⚠️ \u003Cstrong>重置数据库 - 这将删除 Archon 的所有数据！\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n1. **运行重置脚本**：在您的 Supabase SQL 编辑器中，执行 `migration\u002FRESET_DB.sql` 文件中的内容。\n\n   ⚠️ 警告：这将删除所有与 Archon 相关的表和数据！不过，您的数据库中其他内容不会受到影响。\n\n2. **重建数据库**：重置完成后，运行 `migration\u002Fcomplete_setup.sql` 以重新创建所有表。\n\n3. **重启服务**：\n\n   ```bash\n   docker compose --profile full up -d\n   ```\n\n4. **重新配置**：\n   - 选择您的 LLM\u002F嵌入模型提供商，并重新设置 API 密钥。\n   - 重新上传文档或重新抓取网站内容。\n\n重置脚本会安全地移除所有表、函数、触发器和策略，并妥善处理依赖关系。\n\n\u003C\u002Fdetails>\n\n## 📚 文档\n\n### 核心服务\n\n| 服务                    | 容器名称             | 默认 URL           | 用途                                    |\n| -------------------------- | -------------------------- | --------------------- | ------------------------------------------ |\n| **Web 界面**          | archon-ui                  | http:\u002F\u002Flocalhost:3737 | 主仪表板和控制界面                |\n| **API 服务**            | archon-server              | http:\u002F\u002Flocalhost:8181 | 网页爬取、文档处理          |\n| **MCP 服务器**             | archon-mcp                 | http:\u002F\u002Flocalhost:8051 | 模型上下文协议接口           |\n| **代理服务**         | archon-agents              | http:\u002F\u002Flocalhost:8052 | AI\u002FML 操作、结果重排序                |\n| **代理工作订单** *(可选)* | archon-agent-work-orders | http:\u002F\u002Flocalhost:8053 | 使用 Claude Code CLI 执行工作流    |  \n\n## 升级\n\n要将 Archon 升级到最新版本：\n\n1. **拉取最新更改**：\n   ```bash\n   git pull\n   ```\n\n2. **重建并重启容器**：\n   ```bash\n   docker compose up -d --build\n   ```\n   这将使用最新代码重建容器，并重启所有服务。\n\n3. **检查数据库迁移**：\n   - 在浏览器中打开 Archon 设置页面：[http:\u002F\u002Flocalhost:3737\u002Fsettings](http:\u002F\u002Flocalhost:3737\u002Fsettings)\n   - 导航到 **数据库迁移** 部分\n   - 如果有未完成的迁移，UI 会显示这些迁移，并提供清晰的操作说明\n   - 点击每条迁移记录查看并复制 SQL 语句\n   - 按照显示的顺序在您的 Supabase SQL 编辑器中执行这些 SQL 脚本\n\n## 包含内容\n\n### 🧠 知识管理\n\n- **智能网页爬取**：自动检测并爬取整个文档站点、站点地图以及单个页面。\n- **文档处理**：上传并处理 PDF、Word 文档、Markdown 文件和文本文件，支持智能分块。\n- **代码示例提取**：自动识别并索引文档中的代码示例，以增强搜索功能。\n- **向量搜索**：基于上下文嵌入的高级语义搜索，实现精准的知识检索。\n- **来源管理**：按来源、类型和标签组织知识，便于筛选。\n\n### 🤖 AI 集成\n\n- **模型上下文协议 (MCP)**：连接任何兼容 MCP 的客户端（Claude Code、Cursor，甚至非 AI 编程助手如 Claude Desktop）。\n- **MCP 工具集**：一套全面而简单的工具，用于 RAG 查询、任务管理和项目操作。\n- **多 LLM 支持**：兼容 OpenAI、Ollama 和 Google Gemini 模型。\n- **RAG 策略**：混合搜索、上下文嵌入和结果重排序，以获得最佳的 AI 回答。\n- **实时流式传输**：AI 代理的实时响应，并可跟踪处理进度。\n\n### 📋 项目与任务管理\n\n- **层次化项目结构**：通过项目、功能和任务构建结构化的流程。\n- **AI 辅助创建**：利用集成的 AI 代理生成项目需求和任务。\n- **文档管理**：支持版本控制的文档，并具备协作编辑能力。\n- **进度跟踪**：实时更新和管理所有项目活动的状态。\n\n### 🔄 实时协作\n\n- **WebSocket 更新**：实时跟踪爬取、处理和 AI 操作的进度。\n- **多用户支持**：支持协作式知识构建和项目管理。\n- **后台处理**：异步操作，不会阻塞用户界面。\n- **健康监测**：内置服务健康检查和自动重连机制。\n\n## 架构\n\n### 微服务架构\n\nArchon 采用真正的微服务架构，各服务职责分明：\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   前端 UI   │    │  服务器 (API)   │    │   MCP 服务器    │    │  代理服务  │\n│                 │    │                 │    │                 │    │                 │\n│  React + Vite   │◄──►│    FastAPI +    │◄──►│    轻量级  │◄──►│   PydanticAI    │\n│  端口 3737      │    │    SocketIO     │    │    HTTP 封装 │    │   端口 8052     │\n│                 │    │    端口 8181    │    │    端口 8051    │    │                 │\n└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘\n         │                        │                        │                        │\n         └────────────────────────┼────────────────────────┼────────────────────────┘\n                                  │                        │\n                         ┌─────────────────┐               │\n                         │    数据库     │               │\n                         │                 │               │\n                         │    Supabase     │◄──────────────┘\n                         │    PostgreSQL   │\n                         │    PGVector     │\n                         └─────────────────┘\n```\n\n### 服务职责\n\n| 服务                  | 位置                       | 目的                          | 关键特性                                                       |\n| ------------------------ | ------------------------------ | -------------------------------- | ------------------------------------------------------------------ |\n| **前端**             | `archon-ui-main\u002F`              | Web 界面和仪表板      | React、TypeScript、TailwindCSS、Socket.IO 客户端                   |\n| **服务器**               | `python\u002Fsrc\u002Fserver\u002F`           | 核心业务逻辑和 API     | FastAPI、服务层、Socket.IO 广播、所有 ML\u002FAI 操作                 |\n| **MCP 服务器**           | `python\u002Fsrc\u002Fmcp\u002F`              | MCP 协议接口           | 轻量级 HTTP 封装、MCP 工具、会话管理                            |\n| **代理**               | `python\u002Fsrc\u002Fagents\u002F`           | PydanticAI 代理托管         | 文档和 RAG 代理、流式响应                                       |\n| **代理工作订单** *(可选)* | `python\u002Fsrc\u002Fagent_work_orders\u002F` | 工作流执行引擎 | Claude Code CLI 自动化、仓库管理、SSE 更新                        |\n\n### 通信模式\n\n- **基于 HTTP**：所有服务间通信均使用 HTTP API\n- **Socket.IO**：服务器到前端的实时更新\n- **MCP 协议**：AI 客户端通过 SSE 或 stdio 连接到 MCP 服务器\n- **无直接导入**：服务之间完全独立，无共享代码依赖\n\n### 关键架构优势\n\n- **轻量级容器**：每个服务仅包含所需依赖\n- **独立扩展**：可根据负载独立扩展各服务\n- **开发灵活性**：团队可在不同服务上并行工作，互不干扰\n- **技术多样性**：每个服务都采用最适合其特定用途的技术\n\n## 🔧 配置自定义端口与主机名\n\n默认情况下，Archon 服务运行在以下端口：\n\n- **archon-ui**：3737\n- **archon-server**：8181\n- **archon-mcp**：8051\n- **archon-agents**：8052（可选）\n- **archon-agent-work-orders**：8053（可选）\n\n### 更改端口\n\n要使用自定义端口，请将以下变量添加到您的 `.env` 文件中：\n\n```bash\n# 服务端口配置\nARCHON_UI_PORT=3737\nARCHON_SERVER_PORT=8181\nARCHON_MCP_PORT=8051\nARCHON_AGENTS_PORT=8052\nAGENT_WORK_ORDERS_PORT=8053\n```\n\n示例：使用不同端口：\n\n```bash\nARCHON_SERVER_PORT=8282\nARCHON_MCP_PORT=8151\n```\n\n### 配置主机名\n\n默认情况下，Archon 使用 `localhost` 作为主机名。您可以通过在 `.env` 文件中设置 `HOST` 变量来配置自定义主机名或 IP 地址：\n\n```bash\n# 主机名配置\nHOST=localhost  # 默认\n\n# 自定义主机名示例：\nHOST=192.168.1.100     # 使用特定 IP 地址\nHOST=archon.local      # 使用自定义域名\nHOST=myserver.com      # 使用公共域名\n```\n\n这在以下情况下非常有用：\n\n- 在另一台机器上运行 Archon 并远程访问\n- 为您的安装使用自定义域名\n- 在无法访问 `localhost` 的网络环境中部署\n\n更改主机名或端口后：\n\n1. 重启 Docker 容器：`docker compose down && docker compose --profile full up -d`\n2. 访问 UI：`http:\u002F\u002F${HOST}:${ARCHON_UI_PORT}`\n3. 使用新的主机名和 MCP 端口更新您的 AI 客户端配置\n\n## 🔧 开发\n\n### 快速入门\n\n```bash\n# 安装依赖\nmake install\n\n# 启动开发（推荐）\nmake dev        # 后端在 Docker 中运行，前端本地热重载\n\n# 替代方案：全部在 Docker 中运行\nmake dev-docker # 所有服务都在 Docker 中运行\n\n# 停止所有服务（本地 FE 需手动停止）\nmake stop\n```\n\n### 开发模式\n\n#### 混合模式（推荐）- `make dev`\n\n适用于需要即时前端更新的活跃开发：\n\n- 后端服务在 Docker 中运行（隔离、一致）\n- 前端在本地运行，支持热模块替换\n- 无需重建 Docker 即可实现即时 UI 更新\n\n#### 全 Docker 模式 - `make dev-docker`\n\n适用于所有服务都在 Docker 环境中运行的情况：\n\n- 所有服务都在 Docker 容器中运行\n- 更适合集成测试\n- 前端更新速度较慢\n\n### 测试与代码质量\n\n```bash\n# 运行测试\nmake test       # 运行所有测试\nmake test-fe    # 运行前端测试\nmake test-be    # 运行后端测试\n\n# 运行 linter\nmake lint       # 检查所有代码\nmake lint-fe    # 检查前端代码\nmake lint-be    # 检查后端代码\n\n# 检查环境\nmake check      # 验证环境设置\n\n# 清理\nmake clean      # 删除容器和卷（需确认）\n```\n\n### 查看日志\n\n```bash\n# 使用 Docker Compose 直接查看日志\ndocker compose logs -f              # 所有服务\ndocker compose logs -f archon-server # API 服务器\ndocker compose logs -f archon-mcp    # MCP 服务器\ndocker compose logs -f archon-ui     # 前端\n```\n\n**注意**：后端服务在其 uvicorn 命令中配置了 `--reload` 标志，并将源代码以卷的形式挂载，以便在您进行更改时自动热重载。\n\n## 故障排除\n\n### 常见问题及解决方案\n\n#### 端口冲突\n\n如果出现“端口已被占用”的错误：\n\n```bash\n# 检查哪个进程正在使用端口（例如 3737）\nlsof -i :3737\n\n# 停止所有容器和本地服务\nmake stop\n\n# 在 .env 中更改端口\n```\n\n#### Docker 权限问题（Linux）\n\n如果遇到 Docker 权限错误：\n\n```bash\n# 将您的用户添加到 docker 组\nsudo usermod -aG docker $USER\n\n# 注销并重新登录，或运行\nnewgrp docker\n```\n\n#### Windows 特定问题\n\n- **未找到 Make**：通过 Chocolatey、Scoop 或 WSL2 安装 Make（参见 [安装 Make](#installing-make)）\n- **换行符问题**：将 Git 配置为使用 LF 结尾：\n  ```bash\n  git config --global core.autocrlf false\n  ```\n\n#### 前端无法连接到后端\n\n- 检查后端是否正在运行：`curl http:\u002F\u002Flocalhost:8181\u002Fhealth`\n- 验证 .env 中的端口配置\n- 对于自定义端口，确保同时设置了 `ARCHON_SERVER_PORT` 和 `VITE_ARCHON_SERVER_PORT`\n\n#### Docker Compose 卡住\n\n如果 `docker compose` 命令卡住：\n\n```bash\n# 重置 Docker Compose\ndocker compose down --remove-orphans\ndocker system prune -f\n\n# 重启 Docker Desktop（如适用）\n```\n\n#### 热重载不起作用\n\n- **前端**：确保您处于混合模式（`make dev`）以获得最佳 HMR 体验\n- **后端**：检查 `docker-compose.yml` 中卷是否正确挂载\n- **文件权限**：在某些系统上，挂载的卷可能存在权限问题\n\n## 📈 进展\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#coleam00\u002FArchon&Date\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_readme_04b98cc51736.png\" width=\"500\" alt=\"Star History Chart\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n## 📄 许可证\n\nArchon 社区许可证 (ACL) v1.2 - 详情请参阅 [LICENSE](LICENSE) 文件。\n\n**简而言之**：Archon 是免费、开源且可随意修改的。您可以运行它、分叉它、分享它，但未经许可不得将其作为服务出售。","# Archon 快速上手指南\n\nArchon 是一个专为 AI 编程助手（如 Claude Code、Cursor、Windsurf 等）打造的**指挥中心**。它通过 Model Context Protocol (MCP) 服务器，让 AI 代理能够访问你的私有知识库（文档、代码库）、执行智能搜索并管理开发任务。\n\n## 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **Docker Desktop**: 必须安装并运行（用于编排微服务）。\n*   **Node.js 18+**: 仅在进行混合开发模式时需要，普通用户可不安装。\n*   **Supabase 账户**: \n    *   可使用免费云端版 ([supabase.com](https:\u002F\u002Fsupabase.com))。\n    *   也可使用本地部署版。\n*   **LLM API Key**: \n    *   默认支持 **OpenAI**。\n    *   同时也支持 Google Gemini 和 Ollama（本地模型）。\n*   **(可选) GNU Make**: 用于简化开发命令，非必须但推荐。\n\n## 安装步骤\n\n### 1. 克隆仓库\n推荐使用 `stable` 分支以获得最稳定的体验：\n\n```bash\ngit clone -b stable https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Farchon.git\ncd archon\n```\n\n### 2. 配置环境变量\n复制示例配置文件并根据你的环境进行编辑：\n\n```bash\ncp .env.example .env\n```\n\n使用编辑器打开 `.env` 文件，填入以下关键信息：\n\n*   **Supabase 配置**:\n    *   `SUPABASE_URL`: 你的项目地址。\n        *   云端版：`https:\u002F\u002F\u003C你的项目 ID>.supabase.co`\n        *   本地版：`http:\u002F\u002Fhost.docker.internal:8000`\n    *   `SUPABASE_SERVICE_KEY`: 服务角色密钥。\n        *   **注意**：如果是云端版，请使用旧的 legacy key（较长的那个），不要使用新类型的 key。\n        *   如果是本地版，运行 `supabase status -o env` 获取。\n*   **LLM 配置**: 后续可在 Web 界面中设置，也可在此预填。\n\n### 3. 初始化数据库\n登录你的 [Supabase Dashboard](https:\u002F\u002Fsupabase.com\u002Fdashboard)，进入 **SQL Editor**：\n1. 打开项目根目录下的 `migration\u002Fcomplete_setup.sql` 文件。\n2. 复制全部内容。\n3. 在 SQL Editor 中粘贴并执行，以创建所需的表结构。\n\n### 4. 启动服务\n使用 Docker Compose 启动所有核心微服务（包括 API、MCP 服务器和 Web 界面）：\n\n```bash\ndocker compose up --build -d\n```\n\n启动完成后，主要服务端口如下：\n*   **Web 界面**: http:\u002F\u002Flocalhost:3737\n*   **API 服务**: http:\u002F\u002Flocalhost:8181\n*   **MCP 服务器**: http:\u002F\u002Flocalhost:8051\n\n### 5. 完成初始化配置\n1. 浏览器访问 `http:\u002F\u002Flocalhost:3737`。\n2. 跟随引导流程输入你的 LLM API Key（OpenAI\u002FGemini\u002FOllama）。\n3. 配置完成后即可进入主界面。\n\n## 基本使用\n\n### 1. 构建知识库 (Knowledge Base)\n让 Archon 学习你的项目文档：\n*   **爬取网站**: 进入 `Knowledge Base` -> `Crawl Website`，输入文档 URL（例如 `https:\u002F\u002Fai.pydantic.dev\u002Fllms.txt`），系统将自动抓取并索引内容。\n*   **上传文档**: 直接上传 PDF、Word 或 Markdown 文件，系统会自动分块处理。\n\n### 2. 管理项目与任务\n*   进入 `Projects` 创建新项目。\n*   添加具体任务（Tasks），你可以利用内置的 AI 代理辅助生成需求或拆解任务。\n\n### 3. 连接 AI 编程助手\n这是 Archon 的核心功能，让你的 IDE 插件拥有“记忆”：\n1. 在 Archon 界面进入 `MCP Dashboard`。\n2. 复制对应客户端的连接配置（Connection Config）。\n3. 在你的 AI 工具中配置 MCP：\n    *   **Cursor \u002F Windsurf \u002F Claude Code**: 在设置的 MCP 部分粘贴配置。\n    *   配置成功后，这些 AI 助手即可调用 Archon 的工具进行 RAG 搜索、读取项目任务和上下文。\n\n### 4. 验证测试\n*   在 AI 聊天窗口中询问关于你刚才上传的文档或网站的内容。\n*   请求 AI 根据 Archon 中的任务列表更新代码。\n*   观察 Archon 界面中的实时状态更新。\n\n---\n*提示：如需升级 Archon，只需执行 `git pull` 然后重新运行 `docker compose up -d --build` 即可。如有数据库迁移更新，系统会在 Web 界面的 Settings 中提示。*","某全栈开发者正在接手一个遗留的电商系统重构项目，需要同时处理分散的技术文档、复杂的业务逻辑代码以及大量的待办任务。\n\n### 没有 Archon 时\n- **上下文割裂严重**：开发者需手动在 Notion 文档、PDF 规范和 GitHub Issues 之间反复切换，AI 助手因缺乏项目专属知识，经常产生“幻觉”或给出通用但不适用的代码建议。\n- **知识检索低效**：每次询问业务规则（如“优惠券叠加逻辑”），都要重新复制粘贴大段文档给 AI，不仅耗时且容易超出模型的上下文窗口限制。\n- **任务与代码脱节**：AI 生成的代码片段往往无法直接关联到具体的任务卡片，导致进度追踪困难，容易出现“代码写完了但不知道对应哪个需求”的混乱局面。\n- **协作同步滞后**：当团队更新了接口文档后，AI 助手无法实时感知变化，仍基于旧版本文档提供建议，引发潜在的集成错误。\n\n### 使用 Archon 后\n- **统一知识中枢**：Archon 将爬虫抓取的官网文档、上传的 PDF 及现有代码库整合为专属知识库，作为 MCP 服务器直接赋能 Cursor 或 Claude Code，让 AI 瞬间“懂”项目。\n- **智能语义搜索**：开发者只需自然语言提问，Archon 利用高级 RAG 策略精准定位“优惠券逻辑”相关片段并自动注入上下文，AI 输出的代码准确率显著提升。\n- **任务驱动开发**：在 Archon 界面创建的任务会自动同步给 AI 助手，生成的代码变更直接关联具体任务 ID，实现从需求到实现的闭环追踪。\n- **实时动态更新**：一旦团队上传新文档或修改任务状态，Archon 立即刷新上下文，确保 AI 助手始终基于最新信息工作，彻底消除信息差导致的返工。\n\nArchon 通过构建私有的知识与任务管理骨干，将分散的开发要素转化为 AI 可理解的统一上下文，极大提升了人机协作的深度与效率。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcoleam00_Archon_b7e0c21a.png","coleam00","Cole Medin","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fcoleam00_92be4757.png","Generative AI specialist with a wide range of experience developing AI Agents, RAG solutions, local AI deployments, generative AI libraries\u002Fpackages, and more.","Dynamous",null,"https:\u002F\u002Fdynamous.youcanbook.me\u002F","https:\u002F\u002Fgithub.com\u002Fcoleam00",[82,86,90,94,98,102,105,109],{"name":83,"color":84,"percentage":85},"Python","#3572A5",54.3,{"name":87,"color":88,"percentage":89},"TypeScript","#3178c6",42.8,{"name":91,"color":92,"percentage":93},"PLpgSQL","#336790",2.3,{"name":95,"color":96,"percentage":97},"CSS","#663399",0.3,{"name":99,"color":100,"percentage":101},"JavaScript","#f1e05a",0.2,{"name":103,"color":104,"percentage":101},"Makefile","#427819",{"name":106,"color":107,"percentage":108},"Dockerfile","#384d54",0,{"name":110,"color":111,"percentage":108},"HTML","#e34c26",13881,2378,"2026-04-06T11:22:42","NOASSERTION",4,"Linux, macOS, Windows","未说明",{"notes":120,"python":121,"dependencies":122},"该工具主要基于 Docker 部署，无需手动配置 Python 环境。核心依赖包括 Docker Desktop、Node.js 18+（仅混合开发模式需要）以及 Supabase 数据库（支持云端或本地部署）。支持 OpenAI、Gemini 和 Ollama 作为模型提供商。Windows 用户可通过 WSL2、Chocolatey 或 Scoop 安装 Make 以使用开发命令。","未说明 (后端运行于 Docker 容器中)",[123,124,125,126],"Docker Desktop","Node.js 18+","Supabase","Make (可选)",[14,13],"2026-03-27T02:49:30.150509","2026-04-07T00:04:38.441699",[131,136,141,146,151,155],{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},20444,"为什么爬虫完成后 `crawled_pages` 和 `code_examples` 表仍然是空的？","这通常是由于嵌入维度（Embedding Dimensions）配置不匹配导致的。`.env` 文件中设置了 `EMBEDDING_DIMENSIONS` 变量，但数据库迁移脚本（`migration\u002Fcomplete_setup.sql`）中硬编码了 1536 的尺寸。\n\n解决方案：\n1. 使用 `migration\u002FRESET_DB.sql` 重置数据库。\n2. 手动编辑 `migration\u002Fcomplete_setup.sql` 文件，将其中所有引用 1536 的地方修改为你在 `.env` 中设置的 `EMBEDDING_DIMENSIONS` 值（例如 3072）。\n3. 重新运行设置流程。\n\n此外，如果你使用的是 Gemini 免费层级，当超出限制时嵌入创建会静默失败，请检查 API 用量。","https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fissues\u002F388",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},20445,"启动后端服务时出现循环报错或 ConfigurationError，无法输入 API Key 怎么办？","这个问题通常是因为本地环境变量中残留了无效的 OpenAI Key（即使是占位符）或配置冲突导致的。\n\n解决步骤：\n1. 检查并删除操作系统环境变量中任何名为 `OPENAI_API_KEY` 的旧值或无效值（即使是只有几个字母的占位符）。\n2. 删除所有现有的 Docker 容器：`docker compose down -v`（可选，用于清理卷）或手动删除容器。\n3. 重启计算机以确保环境变量生效。\n4. 重新构建并启动服务：`docker compose up --build -d`。\n\n如果问题依旧，可以尝试回滚到 8 月 18 日左右的提交版本，该版本尚未引入此环境检测逻辑。","https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fissues\u002F324",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},20446,"知识库中网页爬取的文档没有保存或无法查看，该如何排查？","请按照以下步骤逐一检查配置：\n1. **嵌入维度匹配**：确保 `.env` 中的 `EMBEDDING_DIMENSIONS` 与你使用的模型（如 Gemini embedding-001 通常为 3072）一致，并且数据库表结构已按此维度重建。\n2. **Supabase API Key 类型**：必须使用 Supabase 项目设置中的 `service_role` key（服务角色密钥），而不是 `anon` key。`.env` 文件中通常会有注释提示这一点。\n3. **Supabase URL**：确认 URL 填写正确且可访问。\n4. **模型提供商**：确认选择的 LLM 和 Embedding 模型与提供的 API Key 对应（例如 Gemini 模型需配合 Gemini Key）。\n\n如果以上配置均正确但问题仍存在，请尝试拉取最新的 main 分支代码，因为相关 Bug 可能已被修复。","https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fissues\u002F243",{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},20447,"Archon 是否支持通过配置文件自动管理项目 ID，以避免每次手动输入？","目前原生 Python\u002FMCP 版本主要依赖显式指定 project_id，但社区提出了在仓库根目录添加 `.archon.json` 或在 `mcp.json` 中配置的建议方案。\n\n推荐的变通做法（基于社区讨论）：\n- 在项目根目录创建配置文件（如 `.archon.json` 或整合进 `mcp.json`），存储 `project_id` 和项目元数据。\n- 配置可以支持全局范围访问所有项目，也可以定义本地作用域（数组形式包含多个 project_id）以适应 Monorepo 结构。\n- 注意：原 Python 代码库正在被归档，新的 Archon (TypeScript 工作流引擎) 可能会原生支持此类功能。建议关注新版本发布或在新版本中提交该功能请求。","https:\u002F\u002Fgithub.com\u002Fcoleam00\u002FArchon\u002Fissues\u002F423",{"id":152,"question_zh":153,"answer_zh":154,"source_url":135},20448,"为什么知识库爬取过程看起来成功了，但实际上没有生成嵌入数据？","这很可能是因为触发了 AI 模型提供商（如 Gemini）的免费层级限制，导致嵌入生成步骤静默失败。系统虽然完成了网页爬取，但在创建向量嵌入时因配额不足而停止，且未抛出明显错误。\n\n建议：\n1. 检查你的 API Key 用量是否已超限。\n2. 当前流程缺乏对嵌入深度的可见性。理想情况下应将“爬取”和“生成嵌入”分为两个独立步骤，以便先审查爬取内容再执行嵌入，但这需要等待后续版本更新或自行修改代码实现分离处理。",{"id":156,"question_zh":157,"answer_zh":158,"source_url":150},20449,"如何在 Monorepo（多项目仓库）结构中管理不同的 Archon 项目？","虽然目前官方尚未完全自动化支持，但根据社区讨论，最佳实践是利用局部配置文件来区分不同子项目的上下文。\n\n实施方案：\n- 在不同的子目录（如 `\u002Fbackend`, `\u002Ffrontend`）中分别创建配置文件（例如 `.archon.json` 或在 `mcp.json` 中定义局部作用域）。\n- 在这些文件中分别指定对应的 `project_id`。\n- 这样可以让 Archon 根据当前工作目录自动识别关联的项目 ID，从而支持单体仓库中多个独立项目的并行开发和管理，无需每次手动切换上下文。",[]]