GPT Pilot：让 AI 像真程序员一样分步写完整 App 的开源全栈助手｜部署与使用全指南
适用读者：想研究"LLM 到底能在多大程度上自动写完整应用"的开发者、想在本机跑一个多 Agent 协作代码生成器做学习参考的人。本文必须先读下面这条官方安全警告，再决定是否在本机
git clone && python main.py。
⚠️ 开篇必读：官方安全通告（原样摘自仓库 README）
仓库 README 顶部挂着一条 CAUTION 级别的警告，原文要点：
- 2025-08-24 一个被伪装成"Revert 'Implemented weekend
discount'"的恶意提交（commit
065ee8eb）被推到本仓库； - 该提交在
core/telemetry/目录下藏了一个凭证窃取器（supply-chain worm，被称作 Shai-Hulud 级别），程序一旦运行就自动下载 Bun 运行时并执行混淆 payload（core/telemetry/_runtime.bin），窃取 AWS/云 Key、GitHub/npm Token、SSH Key 等，并可能借机扩散到其他项目； - 外部安全研究员于 2026-06-08 公开报告，恶意文件于 2026-06-11 被移除；
- 仓库同时声明：本仓库已不再积极维护，这次清理只是安全善后，不代表恢复开发。
如果你在 2025 年 8 月到 2026-06-11 之间从源码 clone
并真正运行过 GPT
Pilot，官方要求：轮换该机上所有凭证；检查是否存在
core/telemetry/_runtime.bin、core/telemetry/_hooks.py、core/telemetry/.loader.lock、意外的
bun 二进制或 rt-*
临时目录；在确认干净之前把这台机器当作已失陷处理。只是 clone
下来没运行过的机器不受影响。
也就是说：这是一份历史/研究向部署指南。新生产环境请优先选择仍在维护的同类项目；本文仅在你理解风险、并在隔离环境（容器/虚拟机、无任何凭证的干净机器）中复现官方流程时才推荐照做。
一、项目简介
GPT Pilot 是 Pythagora 开源的一个命令行工具，目标是研究"LLM 能在多大程度上写出可上线的完整应用，而不是只补全一行代码"。它的核心思路写在 README 里：AI 能写大约 95% 的代码，但剩下 5% 在 AGI 到来之前仍需要人盯着。背后的团队是 YC 系的 Pythagora，README 上挂着 YC 的 Logo，并引导用户去 https://www.pythagora.ai/ 了解后续商业化产品。
它不是一次吐给你整个代码库，而是模拟一个软件团队：Product Owner、Specification Writer、Architect、Tech Lead、Developer、Code Monkey、Reviewer、Troubleshooter、Debugger、Technical Writer 共十个 Agent，按真实开发流程一步一步把 App 写出来。它也是 Pythagora VS Code 扩展背后的核心引擎——也就是说，这个仓库更多是研究与引擎代码，日常想用图形界面的人直接装 VS Code 扩展即可。
核心信息一览表
| 项目 | 内容 |
|---|---|
| 仓库 | https://github.com/Pythagora-io/gpt-pilot |
| 官方站点 | https://www.pythagora.ai/ |
| VS Code 扩展 | https://marketplace.visualstudio.com/items?itemName=PythagoraTechnologies.pythagora-vs-code |
| 运行形态 | Python 命令行（python main.py） |
| 运行时要求 | Python 3.9+ |
| 数据库 | 默认 SQLite；可选 PostgreSQL（需额外装
asyncpg、psycopg2） |
| 模型提供商 | openai / anthropic /
groq（Azure、OpenRouter 走 openai 配置） |
| 仓库状态 | 官方声明已不再积极维护（见开篇安全通告） |
适用场景
- 研究多 Agent 协作写代码的真实流程（10 个 Agent 分工）；
- 在隔离环境里看"从一句需求到可运行 App"是怎么一步步被拆任务的；
- 配合 Pythagora VS Code 扩展做学习型二次开发。
能力边界
- 它生成的是完整 App 骨架，但 README 自己强调：任务拆得太粗 bug 难修，拆得太细 AI 又接不上已有代码，需要人在中间 review；
- 不适合直接在生产/有凭证的机器上长期运行（见安全通告）；
- 仓库已停更，遇到新模型/新依赖版本问题官方不会再修；
- 生成代码默认落在
workspace/<app-name>/目录，是普通文件，请自行备份； - 官方 README 对比了 Smol Developer / GPT Engineer 这类"一次吐整个代码库"的工具：GPT Pilot 选择像真人一样分步写、边写边调试，并通过上下文裁剪只把当前任务相关的文件喂给 LLM，号称能 scale 到更大的项目，但代价是要你陪着一步步走。
二、功能特性
- 十 Agent 流水线：Product Owner（README 自嘲"像现实中一样啥也不干"）→ Specification Writer（在需求不够清楚时反问几个问题）→ Architect（选技术栈并本机检查/安装依赖）→ Tech Lead（把功能拆成开发任务）→ Developer（把每个任务写成人类可读说明）→ Code Monkey（按说明真正改文件）→ Reviewer（每步审查，不对就打回 Code Monkey）→ Troubleshooter（帮你把"哪里不对"组织成模型能懂的反馈）→ Debugger（出问题时上场，README 说"谁也不想见他，但他是你最好的朋友"）→ Technical Writer（最后写项目文档）；
- 按步推进、可回滚：每个 App 有"分支"（目前只支持
main），可以指定从某一步继续； - 上下文裁剪：不会把整个代码库塞进 LLM 上下文，只给当前任务相关的文件，号称"可 scale"；
- 三种模型提供商：
openai（兼容 Azure 与 OpenRouter）、anthropic、groq； - SQLite 默认：零配置开箱即用；PostgreSQL 可选；
- VS Code 扩展一体化：不想敲命令行就装 Pythagora 扩展，由扩展调 CLI；
- 遥测可关：README 指向
docs/TELEMETRY.md，随时 opt-out。
三、官方界面预览
官方 README 顶部挂的是 Pythagora VS Code 扩展的宣传图（见文首图1）。CLI 本身是命令行交互，没有图形界面可截。
四、官方链接汇总
| 资源 | 地址 |
|---|---|
| GitHub 仓库 | https://github.com/Pythagora-io/gpt-pilot |
| Pythagora 官网 | https://www.pythagora.ai/ |
| VS Code 扩展 | https://marketplace.visualstudio.com/items?itemName=PythagoraTechnologies.pythagora-vs-code |
| 示例 App 集合 | https://github.com/Pythagora-io/gpt-pilot/wiki/Apps-created-with-GPT-Pilot |
| Discord | https://discord.gg/HaqXugmxr9 |
| 安全事件 commit | https://github.com/Pythagora-io/gpt-pilot/commit/065ee8ebee7385cb644fd1608587a18edb91f4fb |
| 遥测说明 | 仓库内 docs/TELEMETRY.md |
五、前置要求
| 项 | 要求 |
|---|---|
| Python | Python 3.9+（README 明文要求） |
| 操作系统 | 任意能跑 Python 3.9+ 的系统；Windows 激活虚拟环境用
venv\Scripts\activate |
| 模型 Key | 至少一家：OpenAI / Anthropic / Groq；写在 config.json
里，或留 null 走环境变量 |
| 数据库 | 默认 SQLite，无需额外装；选 PostgreSQL 才需要装库 |
| 强烈建议 | 在隔离容器/VM 里跑，机器上不要放任何真实云凭证、SSH Key、npm Token |
六、安装部署（仅在隔离环境）
官方 README 原文照抄：
git clone https://github.com/Pythagora-io/gpt-pilot.git
cd gpt-pilot
python3 -m venv venv
# Windows 用: venv\Scripts\activate
source venv/bin/activate
pip install -r requirements.txt
cp example-config.json config.json
# 编辑 config.json：填 LLM Provider 与 API Key
python main.py如果要用 PostgreSQL：
pip install asyncpg psycopg2然后把 config.json 里的 db.url 改成：
postgresql+asyncpg://<user>:<password>@<db-host>/<db-name>启动前再次确认：这台机器上没有你舍不得丢的凭证；
config.json里的 API Key 只在隔离环境里用一次；跑完把整个workspace/与config.json一起删掉。
七、配置项说明（config.json）
按 README，config.json 至少要填这几项：
| 字段 | 说明 |
|---|---|
| LLM Provider | 三选一：openai / anthropic /
groq；Azure 与 OpenRouter 走 openai
配置并填对应 endpoint，默认 endpoint 留 null |
| API Key | 写在这里；留 null 则从环境变量读 |
db.url |
默认 SQLite；换 PostgreSQL 用上面那条
postgresql+asyncpg://... |
fs.ignore_paths |
让 GPT Pilot
不要跟踪的目录/文件，例如编译器产物目录；加在这里可以避免它把
node_modules、构建缓存之类当成代码去读 |
配好
config.json之前，建议先确认你打算用哪家模型：OpenAI / Anthropic / Groq 三选一，endpoint 留null就走官方默认；Azure 和 OpenRouter 不是独立 provider，而是在openai这一项里改 endpoint 与 Key。Key 写在config.json里或者从环境变量读都行，但既然这是隔离环境，直接写在config.json里、跑完连文件一起删掉最干净。
八、使用流程
python main.py启动；- 输入 App 名称与一句话描述；
- Specification Writer Agent 会反问几个问题把需求问清楚——如果你的描述本身已经够具体，它会跳过这一步；
- Architect Agent 选技术栈，并在本机检查对应工具链是否已装、没装就尝试装；这一步会真实动你的环境，所以更要在隔离容器里跑；
- Tech Lead 拆开发任务，Developer 把每个任务写成人类可读说明，Code Monkey 真正改文件；
- Reviewer 每步审查，发现不对打回给 Code Monkey 重来；
- 出错时 Troubleshooter 帮你组织反馈语言，Debugger 上场定位；
- Technical Writer 最后写项目文档；
- 全部产物在
workspace/<app-name>/目录下，按 App 名分子目录存放。
常用 CLI 命令：
python main.py --list # 列出已建过的 App（同时列出每个 App 的"分支"，目前只支持 main）
python main.py --project <app_id> # 从最近一步继续
python main.py --project <app_id> --step <step> # 回到指定步（警告：会删除该步之后的全部进度）
python main.py --delete <app_id> # 删除 App（警告：不可恢复）
python main.py --help # 查看其余主要服务 VS Code 扩展调用的选项九、常用运维 / 更新命令
git pull
pip install -r requirements.txt
# 切 PostgreSQL 时额外
pip install asyncpg psycopg2仓库已停更，
git pull不会再收到新功能；如收到新提交，先看 commit 历史再决定要不要拉——这正是上次恶意提交混入的路径。
十、常见故障排查
| 现象 | 原因 / 处理 |
|---|---|
python main.py 报语法/依赖错 |
Python 版本低于 3.9；README 明确要求 3.9+ |
config.json 不知道怎么填 |
直接
cp example-config.json config.json，在模板基础上改；Key 留
null 则读环境变量 |
| 想连 Azure / OpenRouter | LLM Provider 仍选 openai，把对应 endpoint
写进配置，不要新建 provider 名 |
| 默认 SQLite 想换 PostgreSQL | 先 pip install asyncpg psycopg2，再把
db.url 改成 postgresql+asyncpg://... |
| AI 写的代码反复返工 | README 自己说：任务拆太粗 bug 难修、太细又接不上；在 Developer 阶段把任务描述写具体一点 |
| 怀疑机器被埋了 payload | 按开篇安全通告逐项排查
core/telemetry/_runtime.bin、_hooks.py、.loader.lock、意外
bun、rt-* 目录；发现即轮换全部凭证 |
| 不想被遥测 | 看仓库 docs/TELEMETRY.md 按说明 opt-out |
| 生成的 App 在哪 | 默认在仓库根目录 workspace/<你输入的 App 名>/
下 |
| 想接着上次继续 | python main.py --project <app_id>；先
--list 拿到 app_id |
| 想回到某一步重跑 | python main.py --project <app_id> --step <n>，警告会删掉该步之后所有进度 |
| 不想用命令行 | 直接装 Pythagora VS Code 扩展（链接见汇总表），由扩展调 CLI |
| Architect Agent 要装系统工具 | 这正是不要在日常机器上跑的原因之一；在隔离容器里它能装就装、装不上就换技术栈 |
十一、风险与责任使用声明
- 本仓库 2025-08 至 2026-06-11 期间被植入过凭证窃取 payload，官方已清理但仓库不再维护；本文命令仅作研究/复现用途，强烈建议在无任何真实凭证的隔离容器或虚拟机里运行；
- 调用 OpenAI / Anthropic / Groq 会产生真实 API 账单；Key 写在
config.json，不要把该文件提交到公开仓库； - AI
生成的代码未经审计，不得直接上生产；尤其要检查有没有外联可疑地址、有没有读取本机
~/.ssh、~/.aws、~/.npmrc等凭证文件的行为； - 不得用它批量复刻受版权保护的商业产品或他人作品；
- 本文所有命令、Python 版本要求（3.9+）、CLI 参数、Agent
分工均来自官方 README 与
docs/TELEMETRY.md，不构成对该仓库安全性的任何背书；后续任何安全事件以官方仓库通告为准； - 如果你只是想体验"AI 写整个 App"，优先用 Pythagora 官方 VS Code 扩展或其商业化产品（https://www.pythagora.ai/），而不是从这个已停更的仓库源码起步；本文之所以仍把部署流程写全，是为了让你在隔离环境里能复现它的多 Agent 设计思路，而不是推荐你把它带进生产。