Potpie

Potpie 可以将您的整个代码库转换为一个知识图谱——即对每个文件、类和函数的结构化索引，捕捉它们之间的所有关系以及代码各部分在整体上下文中的作用。基于该图谱构建的 AI 代理能够像编写代码的人一样精确地理解并推理您的代码，从调试到功能开发都能胜任。

快速入门

前置条件

• 已安装并运行 Docker
• 已安装 Git
• 安装了 Python 3.11+，并配备 uv

安装步骤

1. 克隆仓库

   git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
   cd potpie
   

2. 配置环境变量

   cp .env.template .env
   

   编辑 .env 文件，填写以下必填项：

   # 应用与环境
   isDevelopmentMode=enabled
   ENV=development
   defaultUsername=defaultuser
   
   # AI / LLM 配置
   LLM_PROVIDER=openai                    # openai | ollama | anthropic | openrouter
   OPENAI_API_KEY=sk-proj-your-key
   CHAT_MODEL=gpt-4o
   INFERENCE_MODEL=gpt-4o-mini
   
   # 数据库
   POSTGRES_SERVER=postgresql://postgres:mysecretpassword@localhost:5432/momentum
   NEO4J_URI=bolt://127.0.0.1:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=mysecretpassword
   
   # Redis 与后台任务
   REDISHOST=127.0.0.1
   REDISPORT=6379
   BROKER_URL=redis://127.0.0.1:6379/0
   CELERY_QUEUE_NAME=dev
   
   # 项目与仓库管理
   PROJECT_PATH=projects
   

   CHAT_MODEL 和 INFERENCE_MODEL 分别用于代理推理和知识图谱生成。模型名称应遵循 LiteLLM 所要求的 provider/model_name 格式。

   💡 使用 Ollama？ 将 LLM_PROVIDER=ollama，并设置 CHAT_MODEL=ollama_chat/qwen2.5-coder:7b 和 INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b。

   您可以参考 .env.template 查看完整的可选配置列表（日志记录、功能开关、对象存储、邮件、分析等）。

3. 安装依赖

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync
   

4. 启动所有服务

   chmod +x scripts/start.sh
   ./scripts/start.sh
   

   这将启动 Docker 服务、应用数据库迁移、启动 FastAPI 应用程序以及 Celery 工作进程。

5. 健康检查

   curl -X GET 'http://localhost:8001/health'
   

6. 查看解析状态

   curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'
   

要停止所有服务：

./scripts/stop.sh

接下来设置 Potpie 前端

cd potpie-ui

cp .env.template .env

pnpm build && pnpm start

---

工作原理？

Potpie 会将您的代码仓库解析成一个存储在 Neo4j 中的知识图谱，其中包含每个文件、函数、类及其相互之间的关系。代理可以直接从该图谱中读取信息，从而根据您实际的代码回答问题或完成任务。

架构图

• FastAPI 作为 API 层——所有请求通过 localhost:8001 进入，支持 CORS、Logfire 跟踪，并可选集成 Sentry 错误监控。
• Firebase Auth 负责生产环境的身份验证。在开发模式下，本地会创建一个虚拟用户，无需 Firebase。
• Celery Worker 结合 Redis 作为消息代理，负责异步解析代码库——克隆、AST 提取和知识图谱构建都在后台进行。
• Conversation Service 管理多轮对话中的聊天会话及代理记忆。
• Agent Router 根据意图将提示分发给合适的预构建或自定义代理。
• Tool Service 向代理暴露可调用的功能——代码搜索、文件获取、知识图谱查询、网络工具等。
• Neo4j Knowledge Graph 以属性图的形式存储您的代码库——函数、类、文件、导入关系及调用关系，是所有代理上下文的核心。
• PostgreSQL 存储用户、项目、对话记录及消息历史。

GitHub 身份验证

方法	配置	适用场景
GitHub App	GITHUB_APP_ID, GITHUB_PRIVATE_KEY	生产环境
PAT 池	GH_TOKEN_LIST=ghp_token1,ghp_token2	开发环境 / 更高速率限制
未认证	无需配置	仅限公开仓库（60 请求/小时）

通过设置 GITHUB_AUTH_MODE 为 app、pat 或 none 来选择相应的方法。

---

自托管 Git 服务提供商

对于自托管的 Git 服务器（例如 GitBucket、GitLab 等），请进行如下配置：

  uv sync

这将创建一个 .venv 目录，并从 pyproject.toml 中安装所有依赖项。

GitHub 身份验证设置

Potpie 支持多种身份验证方法来访问 GitHub 仓库：

对于 GitHub.com 仓库：

选项 1：GitHub 应用程序（推荐用于生产环境）

• 在您的组织中创建一个 GitHub 应用程序
• 设置环境变量：

  GITHUB_APP_ID=your-app-id
  GITHUB_PRIVATE_KEY=your-private-key
  

选项 2：个人访问令牌池

• 创建一个或多个具有 repo 范围的 GitHub PAT
• 设置环境变量（多个令牌用逗号分隔）：

  GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3
  

• Potpie 将从令牌池中随机选择以实现负载均衡
• 速率限制：每个令牌每小时 5,000 次请求（已认证）

选项 3：未认证访问（仅限公共仓库）

• 无需配置
• 自动作为公共仓库的后备方案
• 速率限制：每个 IP 每小时 60 次请求（非常有限）

对于自托管 Git 服务器（GitBucket、GitLab 等）：

  设置以下环境变量：
  

  CODE_PROVIDER=github   # 选项：github、gitbucket
  CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
  CODE_PROVIDER_TOKEN=your-token

重要提示：无论 CODE_PROVIDER_BASE_URL 如何设置，GH_TOKEN_LIST 中的令牌始终用于 GitHub.com。

2. 启动 Potpie

   要启动所有 Potpie 服务：

   chmod +x scripts/start.sh
   ./scripts/start.sh
   

   这将：

   • 启动所需的 Docker 服务
   • 等待 PostgreSQL 准备就绪
   • 应用数据库迁移
   • 启动 FastAPI 应用程序
   • 启动 Celery 工作器

   可选：Logfire 追踪设置

   若要使用 Pydantic Logfire 监控 LLM 跟踪和代理操作：

   1. 从 https://logfire.pydantic.dev 获取 Logfire 令牌
   2. 将其添加到你的 .env 文件中：

   LOGFIRE_TOKEN=your_token_here
   

   3. Potpie 启动时会自动初始化追踪功能。你可以在 https://logfire.pydantic.dev 查看追踪记录。

   注意：在你的 .env 文件中设置 LOGFIRE_SEND_TO_CLOUD=false 可以禁用向 Logfire 云端发送追踪数据。

3. 停止 Potpie

   要停止所有 Potpie 服务：

   ./scripts/stop.sh
   

   Windows

   ./stop.ps1
   

   这将优雅地停止：

   • FastAPI 应用程序
   • Celery 工作器
   • 所有 Docker Compose 服务

Potpie 的预构建代理

Potpie 提供了一系列专门的代码库代理，用于自动化和优化软件开发的关键方面：

调试代理 自动分析堆栈跟踪，并根据您的代码库提供逐步调试指导——而不是通用建议。	代码库问答代理 回答有关您代码库的问题，并从基本原理出发解释函数、特性及架构。
代码生成代理 为新功能生成代码、重构现有代码，并基于您实际的代码库提出优化建议。	规格代理 根据您的代码库生成详细的软件规格说明、PRD 和架构文档。

自定义代理

借助自定义代理，您可以设计个性化的工具，以精确处理重复性任务。定义：

• 系统指令 - 代理的任务、目标和预期输出
• 任务 - 完成工作所需的各个步骤
• 工具 - 用于查询知识图谱或检索代码的函数

curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "一个以堆栈跟踪为输入，输出根本原因分析和解决方案的代理"}'

更多内容请参阅我们的文档。

使用场景

入职培训 让新开发者在数小时内就能高效工作，而不是几周。Potpie 会映射您的架构、入口点和设置流程，使任何人都能快速上手。	代码库问答 关于您的代码库，无论是函数、数据流还是设计决策，都可以随时提问。您将获得基于实际代码的精准答案，而非猜测。
调试 粘贴堆栈跟踪信息，即可获得针对您代码的根本原因分析和逐步修复方案——而不是通用的故障排除建议。	代码审查 在合并代码之前，了解您的更改可能带来的影响范围。Potpie 会展示受影响的 API、下游影响以及潜在的回归问题。
测试生成 生成能够理解您的代码结构的单元测试和集成测试——而不是千篇一律的模板。这些测试可以覆盖手动测试遗漏的边缘情况。	功能规划 将需求或开放问题转化为低层级的实施计划——包括组件分解、API 接口以及建议的代码结构。

扩展与集成

VSCode 扩展 直接在你的编辑器中使用 Potpie 的 AI 助手——无需切换标签页，也不用复制粘贴。在不离开 VSCode 的情况下，提问、获取解释并完成代码提交。 助手能够即时理解你当前打开的代码库 适用于任何本地或远程代码库

Slack 集成 将 Potpie 引入你团队的 Slack 工作区。在团队已有的聊天线程中进行代码调试、解答代码库相关问题以及获取项目洞察。 不到两分钟即可完成设置 支持你自定义配置的助手

API 访问 通过 API 密钥将 Potpie 集成到 CI/CD 流水线和自动化工作流中。以编程方式触发助手，以适应你现有的 DevOps 环境。

自定义工具集成 通过构建并注册你自己的工具来扩展 Potpie 的功能。将文件放入 app/modules/intelligence/tools/ 目录，并在 tool_service.py 中进行注册。

社区与支持

• GitHub Issues。适合：你在使用 Potpie 时遇到的 bug 和错误。
• Discord。适合：分享你的项目并与社区交流。
• 电子邮件支持。适合：关于你的设置或基础设施的问题。

更多详情请参阅 贡献指南。

许可证

本项目采用 Apache 2.0 许可证授权——详细信息请参阅 LICENSE 文件。

贡献者

感谢你抽出时间帮助构建 Potpie。继续加油 🥂

想参与贡献吗？请阅读 贡献指南，开始行动吧。

Potpie 快速上手指南

Potpie 能将你的整个代码库转化为知识图谱（Knowledge Graph），构建包含所有文件、类、函数及其相互关系的结构索引。基于此图谱，AI Agent 能够像代码作者一样精准地理解上下文，从而执行调试、功能开发等任务。

环境准备

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

• 操作系统：Linux / macOS / Windows (需支持 Docker)
• Docker：已安装并正在运行（用于启动数据库和中间件服务）
• Git：已安装
• Python：版本 3.11 或更高
• uv：Python 包管理工具（推荐用于快速安装依赖）
  • 安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh
• Node.js & pnpm：用于构建前端界面（可选，仅当需要运行 UI 时）

安装步骤

1. 克隆项目

git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
cd potpie

2. 配置环境变量

复制模板文件并编辑配置：

cp .env.template .env

使用编辑器打开 .env 文件，修改以下关键配置：

# 应用模式
isDevelopmentMode=enabled
ENV=development
defaultUsername=defaultuser

# AI / LLM 配置 (以 OpenAI 为例)
LLM_PROVIDER=openai                    # 支持：openai, ollama, anthropic, openrouter
OPENAI_API_KEY=sk-proj-your-key        # 填入你的 API Key
CHAT_MODEL=gpt-4o                      # 用于对话推理
INFERENCE_MODEL=gpt-4o-mini            # 用于知识图谱生成

# 如果使用 Ollama (本地模型)，配置如下：
# LLM_PROVIDER=ollama
# CHAT_MODEL=ollama_chat/qwen2.5-coder:7b
# INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b

# 数据库配置 (通常无需修改，除非端口冲突)
POSTGRES_SERVER=postgresql://postgres:mysecretpassword@localhost:5432/momentum
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=mysecretpassword

# Redis 配置
REDISHOST=127.0.0.1
REDISPORT=6379
BROKER_URL=redis://127.0.0.1:6379/0
CELERY_QUEUE_NAME=dev

# 项目路径
PROJECT_PATH=projects

3. 安装后端依赖

使用 uv 同步安装 Python 依赖：

uv sync

4. 启动服务

赋予脚本执行权限并启动所有服务（包括 Docker 容器、数据库迁移、FastAPI 应用和 Celery worker）：

chmod +x scripts/start.sh
./scripts/start.sh

注意：首次启动可能需要几分钟时间等待数据库就绪和完成迁移。

5. (可选) 启动前端界面

如果需要图形化界面，请进入前端目录并启动：

cd potpie-ui
cp .env.template .env
pnpm build && pnpm start

基本使用

1. 健康检查

确认后端服务是否正常运行：

curl -X GET 'http://localhost:8001/health'

如果返回正常响应，说明服务已就绪。

2. 配置 GitHub 访问权限

Potpie 需要访问你的代码仓库来构建图谱。根据需求在 .env 中选择一种认证方式：

• 方式 A：GitHub App (生产环境推荐) 设置 GITHUB_APP_ID 和 GITHUB_PRIVATE_KEY。
• 方式 B：Personal Access Token (开发推荐) 创建具有 repo 权限的 Token，并在 .env 中设置：

  GITHUB_AUTH_MODE=pat
  GH_TOKEN_LIST=ghp_your_token_here
  

• 方式 C：无认证 (仅限公开仓库) 无需配置，但速率限制为每小时 60 次请求。

对于自建 Git 服务器 (如 GitLab/GitBucket)，需额外设置：

CODE_PROVIDER=github
CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
CODE_PROVIDER_TOKEN=your-token

3. 检查解析状态

当你通过 API 或前端添加项目后，可以使用以下命令检查代码库的解析和图谱构建进度（将 your-project-id 替换为实际 ID）：

curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'

4. 开始对话

服务启动并解析完成后，你可以：

• 通过前端界面：访问 http://localhost:3000 (默认前端端口) 进行对话。
• 通过 API：调用预置 Agent 进行代码问答、调试分析或代码生成。

例如，创建一个自定义 Agent 进行堆栈跟踪分析：

curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "An agent that takes stacktrace as input and gives root cause analysis and proposed solution as output"}'

停止服务

如需停止所有服务：

./scripts/stop.sh

(Windows PowerShell 用户请使用 ./stop.ps1)