抄 —— 直接拿 Orion + AI-Shifu 当蓝本，抄出你的“初始系统”（Docker 一键跑）

系列顺序：夯（Git） → 抄 → 学 → 喂
这一篇的目标很粗暴：先把现成项目跑起来/抄出底盘；下一篇再从这些“老师工程”里系统性抽黑话与术语库。

AI 编程现在最大的坑不是“不会写”，而是：

写得太快
改得太多
炸了没后路
炸完你甚至不知道它到底改了哪些文件

所以我准备写一套 vibe‑coding 九阳神功：核心不是提示词，而是把 AI 变成“可控交付的队友”。

这套“九阳神功”我先定了九个字诀：

夯：Git 生存技能（刹车 / 保险 / 录像）
抄：拆解 yfge/orion、ai-shifu/ai-shifu 的优秀骨架，搭底盘
学：会组合技术栈、会裁决，不懂原理也能不翻车
喂：把 API 文档 / 资料结构化成可执行知识
规：让 AI 出计划 + tasks.md，按清单推进
验：多模型交叉验证，专治幻觉
测：Chrome MCP 自动测试，交付有证据
扩：扩展认知边界，但必须可验证
收：上线交付、监控回滚、复盘闭环

一句话：不是教你“让 AI 写代码”，是教你“带着 AI 把东西交付上线”。

这篇咱们讲第二式抄：不做架构分析，先把东西跑起来，再把可复用的“底盘”抽出来。

这节很粗暴：先跑起来，再把底盘抄出来

你可以让 Codex / Claude 帮你敲命令、生成文件、写脚本——但你必须知道它在做什么：git clone 会拉代码；docker compose 会起哪些服务；docker compose down -v 可能会删数据。

你需要准备的就两样：

Git（至少保证 git --version 能跑）
Docker Desktop（自带 Docker Engine + Docker Compose）

0）为什么我推荐这两个项目当蓝本？

Orion：小而全、vibe-coding 味很正

它在仓库里把“documentation-first、agent-friendly、可审计（agents_chat）”写得很明确，而且是把规矩写进工程约束里的那种（不是口号）：

单一真源的 Agent 规矩：AGENTS.md 是 source of truth；.cursorrules / .CLAUDE.md / GEMINI.md（以及 GitHub instructions）都要求链接到同一个文件，避免“多份规则互相打架”。
强可审计协作：agents_chat/ 有严格的命名/模板；并且对“哪些目录算代码变更、必须同提交带 agents_chat”有明确说明，甚至有 CI 检查脚本来强制执行。
根目录可跑：根目录 docker-compose.yml + Docker/（backend/frontend Dockerfile、nginx.conf）直接一条命令能把 MySQL + FastAPI + Next.js + Nginx 拉起来（对照 docker-compose.yml 你能一眼验收它起了哪些服务）。

Orion README

AI-Shifu：大而稳、Docker 自托管做得很成熟

它的亮点更偏“自托管工程化落地”，尤其适合你抄一个可交付的 Docker 底盘：

docker/ 目录集中化：启动相关都在 docker/（Nginx 配置、数据卷目录、compose 文件等），读者不容易迷路。
Compose 三件套：docker-compose.latest.yml（追最新镜像）+ docker-compose.yml（pin 版本可复现）+ docker-compose.dev.yml（源码挂载/热更新）。
dev_in_docker.sh：一键 build 本地源码镜像，然后起 dev compose（bind mount + reload），非常适合“我不想在本机装一堆 Python/Node 环境”的人。
Nginx 反代更细：比如把 /api/i18n、/api/config 这类“前端自己的 API”明确反代到 Cook Web，而 /api/ 才走后端，边界很清晰。

AI-Shifu README

你这一节要“抄”的就是两家的并集优点：

（Orion）工程纪律 + 可审计协作
（AI-Shifu）docker/ 目录化 + .env 模板 + Docker Compose 双轨 + dev 脚本

PS: 别忘了顺手给这两个项目加个star/fork 吖：）

1）补齐：git clone 是什么、怎么用（小白够用版）

git clone 的意思很直白：把 GitHub（或其他平台）上的远程仓库，完整复制一份到你的电脑上。

你执行完 git clone ... 后，会得到一个本地文件夹（通常叫仓库名），里面就是项目源码；后面所有 docker compose ... 之类的命令，都是在这个文件夹里运行。

如果你连 Git 都还没安装/没配过，先把“能跑 git --version”这一步搞定再回来看这里（完整入门我单独写在 夯：Git 刹车系统 那篇里）。

# 1) 直接克隆到当前目录
git clone <仓库地址>

# 2) 克隆并指定本地目录名
git clone <仓库地址> <本地目录名>

# 3) 克隆后进入目录
cd <目录名>

新手建议先用 HTTPS（省事）。SSH 你第一课配过也可以用。

2）把两个项目 clone 下来（照抄命令就行）

建议先建个练功目录：

mkdir -p ~/dev/vibe-practice
cd ~/dev/vibe-practice

# clone Orion
git clone https://github.com/yfge/orion.git

# clone AI-Shifu
git clone https://github.com/ai-shifu/ai-shifu.git

如果你跟我一样，本机已经把两个项目放在固定位置，也可以直接用你现成的路径（本文后续示例按这个来写）：

Orion：~/dev/vibe-practice/orion
AI-Shifu：~/dev/vibe-practice/ai-shifu

3）装 Docker（Windows / macOS 小白版）

你后面“一键启动”全靠 Docker Desktop（自带 Docker Compose）。

Windows（Docker Desktop + WSL2）

按官方步骤安装 Docker Desktop for Windows
建议使用 WSL2 后端（官方也有配置说明）
装完验证：

docker --version
docker compose version
docker run --rm hello-world

（也可以参考微软的 WSL2 + Docker Desktop 指引）

macOS（Docker Desktop）

按官方步骤安装 Docker Desktop for Mac
装完验证：

docker --version
docker compose version
docker run --rm hello-world

备注：Docker Desktop 的商业使用条款/订阅要求，官方文档有写（别踩坑）。

4）先跑起来：一键启动这两个项目（你只要复制粘贴）

4.1 启动 AI-Shifu（官方 Quick Start，最适合小白）

cd ~/dev/vibe-practice/ai-shifu/docker
cp .env.example.full .env

# 编辑 .env：至少填一个 LLM API Key（例如 OPENAI_API_KEY=...）
docker compose -f docker-compose.latest.yml up -d
docker compose ps

它的 README 基本就是这么写的（含 latest vs pinned 的解释、dev_in_docker.sh 等）。

第一次启动会拉镜像，可能要等一会儿；docker compose ps 能看到服务起来了没。

4.2 启动 Orion（直接用它的 docker-compose.yml）

cd ~/dev/vibe-practice/orion
docker compose up -d
docker compose ps

Orion 仓库根目录直接有 docker-compose.yml，也有 tasks.md / agents_chat/ /（链接到 AGENTS.md 的）.cursorrules / .CLAUDE.md / GEMINI.md 这一套 vibe-coding 规矩。

注意：我这份 orion 的 compose 里，Nginx 对外端口是 8082（ports: "8082:80"），所以你应该访问 http://localhost:8082；不要想当然以为都是 8080。

小白提醒：别乱用 docker compose down -v。-v 可能会把 volume 数据也删掉。你不知道它会删什么，就先别用。

5）让 AI “直接抄并集优点”给你生成一个初始系统（不分析骨架，直接开干）

你现在要做的事只有一句话：

在你本地已经 clone 的两个项目基础上，参考 Orion + AI-Shifu 的“规矩文件 + Docker 启动方式”，生成一个全新的可交付项目底盘。

建议你把“参考源”的本地路径也明确告诉 AI（避免它瞎猜）：

Orion：~/dev/vibe-practice/orion（重点看 AGENTS.md 的“单一真源 + 链接策略”、agents_chat/ 的可审计约束、根目录 docker-compose.yml + Docker/）
AI-Shifu：~/dev/vibe-practice/ai-shifu（重点看 docker/ 目录：latest/pinned/dev 三套 compose、dev_in_docker.sh、nginx.conf/nginx.dev.conf）

5.1 你要生成的新项目约束（并集 + 取优）

项目名：vibe-starter

必须包含这些“并集约束”（照抄）：

工程纪律（Orion 风格）
- documentation-first：README / docs/ 先行
- agent-friendly：给 AI 的规则文件放根目录
- auditable：保留 agents_chat/（记录 AI 协作日志），并提供一套“写法 + 强制机制”
- pre-commit：提供可直接使用的 .pre-commit-config.yaml，并在 README 写清楚 pre-commit install / pre-commit run -a 的最小用法（让格式化与基础静态检查自动化）
Docker 化（AI-Shifu 风格）
- docker/ 目录集中管理一切
- .env.example.full（或等价）+ .env 运行
- docker-compose.latest.yml（追最新）+ docker-compose.yml（固定版本可复现）
- dev_in_docker.sh：本地源码构建并启动 dev compose（热更新/挂载）
- 一键启动脚本：./scripts/up.sh（或 make up）
基础技术栈（简单但可交付）
- backend：FastAPI（至少 /healthz、/api/hello）
- frontend：Next.js（首页显示 “it works”）
- nginx：/api -> backend，/ -> frontend
- MySQL：默认随 docker compose 启动，backend 用 env 连接
- 端口统一：对外只暴露 8080

5.2 直接给 Codex / Claude 的指令（复制粘贴就能用）

把下面这段原样丢给你的 Codex / Claude（很关键：要求它按文件创建，别一坨糊你一屏）：

你现在要在当前目录创建一个新仓库 vibe-starter。

参考源（已在本地）：
- Orion: ~/dev/vibe-practice/orion
- AI-Shifu: ~/dev/vibe-practice/ai-shifu

目标：同时参考两者的工程习惯与 Docker 启动方式，取并集优点，产出一个“可交付的最小底盘”。

约束（必须满足）：
1) 根目录规则文件齐全：.cursorrules / AGENTS.md / CLAUDE.md(or .CLAUDE.md) / GEMINI.md / tasks.md / README.md
2) 创建目录：agents_chat/、docs/、scripts/、backend/、frontend/、docker/
3) docker/ 目录必须提供：
   - .env.example.full（或等价）+ .env 运行
   - docker-compose.latest.yml（追最新）+ docker-compose.yml（固定版本可复现）+ docker-compose.dev.yml（热更新/挂载）
   - nginx.conf
   - backend/frontend 的 Dockerfile
   - dev_in_docker.sh（开发态：本地源码挂载 + 热更新）
4) scripts/ 目录必须提供：
   - up.sh：一键启动（默认 latest compose）
   - down.sh：停止（不要带 -v）
5) 基础技术栈：
   - backend: FastAPI（至少 /healthz、/api/hello）
   - frontend: Next.js（首页显示 “it works”，并调用 /api/hello 展示返回）
   - nginx: /api -> backend，/ -> frontend
   - MySQL: 默认随 docker compose 启动，backend 用 env 连接
   - 端口统一：对外只暴露 8080
6) 启动即自愈（自动迁移）：
   - `docker compose up` 后端容器启动时必须**自动执行数据库迁移**（例如 Alembic `upgrade head`），并且要**等待 MySQL 就绪**再迁移，迁移成功后再启动服务；避免要求用户手动执行迁移命令。
7) pre-commit 规则（开箱即用）：
   - 仓库根目录必须提供 `.pre-commit-config.yaml`
   - README 必须写清楚：`pre-commit install`（含 commit-msg 如有）与 `pre-commit run -a`
   - 规则目标：自动格式化 + 基础静态检查（至少覆盖 backend Python；frontend 可选接入 prettier/eslint）
8) agents_chat 机制（可审计协作，开箱即用）：
   - 目录：`agents_chat/YYYY/MM/DD/`
   - 文件名：`YYYY-MM-DDTHH-MM-SSZ-<topic>.md`
   - 每条日志必须包含 YAML frontmatter（至少：`id/date/participants/models/tags/related_paths/summary`）
   - 正文必须包含：需求/背景、做了什么（含改动文件）、关键决策、验收结果、后续 TODO
   - 强制规则：凡提交涉及代码/配置变更（例如 `backend/`、`frontend/`、`docker/`、`docker-compose*.yml`），同一次提交必须新增/更新至少一条 `agents_chat/` 日志
   - 例外：允许在提交信息中加入 `skip agents-chat` 跳过（强调“有意为之、少用”）
   - 实现方式：提供一个可运行的检查脚本（CI 或 pre-commit 阶段均可）来 enforce 上述规则

补一句：上面这段“提示词/约束”是我现在直接给你的 可用模板；但你完全可以反过来做——先让 Codex / Claude 分析你本地的两个参考仓库（例如 ~/dev/vibe-practice/orion 与 ~/dev/vibe-practice/ai-shifu），让它先输出一份“并集优点/目录骨架/关键规矩文件清单/Compose 双轨与 dev 脚本要点”的总结，再让它 基于这份总结生成最终提示词与文件清单。这样更贴合你手上版本，也更可审计（你能对照它的总结逐条验收）。

6）让 AI 给你“一键启动命令”，你只负责验收

你让 AI 最后输出这两类命令即可：

一键启动（latest）

cd vibe-starter
cp docker/.env.example.full docker/.env

# 编辑 docker/.env：至少填一个 LLM key（如果你项目需要的话；本 starter 可不填）
./scripts/up.sh

验收（必须给证据）

docker compose -f docker/docker-compose.latest.yml ps
curl -s http://localhost:8080/api/hello

# 浏览器打开 http://localhost:8080

核心心法：命令让 AI 写，验收你自己做。你不需要懂 Dockerfile 细节，但你必须看得懂“它启动了哪些服务、暴露了什么端口、接口是否通”。

7）这一节结束的“交付物”（你要拿到什么才算学会）

你最终应该得到一个新仓库 vibe-starter，满足：

docker compose up -d 能跑起来（对外 8080）
根目录规则文件齐全（给 AI 的约束一次写清）
有 tasks.md（按清单推进，可复现）
有 agents_chat/（记录协作过程，可审计）
有一键脚本（up/down/dev）

做到这一步，你就已经有了 vibe-coding 的“底盘”：这时候你就可以更自由地往项目里加功能了——因为你“抄”来的强规范（可审计、可回滚、可验收）会把你牢牢拉在轨道上，不容易跑偏。比如你想加“用户注册/登录”就放心加；当然你也可以继续“抄”，比如参考 AI-Shifu 的做法，把大模型调用这一套干净地接进来。

8）抄的另一半：抄“黑话”与“话术”（让 AI 按工程方式交付）

很多人把“黑话”当装逼词，但在工程里它其实是经验的压缩包：一句话背后默认了一堆约束（边界怎么划、数据怎么流、失败怎么重试、怎么验收、怎么回滚）。

vibe‑coding 里，“抄黑话”的目标不是背概念，而是学会把这些词当成按钮：你一说“前后端分离 / 数据库迁移 / 任务队列”，AI 就应该自动补齐对应的目录、配置、脚本、验收步骤——最后能 docker compose up 跑起来、能 curl 验收。

8.1 用 Orion / AI‑Shifu 当教材：每个词都问到“落地清单”

建议你从两个入口文件开始抄：

docker-compose.yml / docker/docker-compose*.yml：服务拆分、端口、依赖、数据卷、健康检查
nginx.conf / nginx.dev.conf：前后端边界、路由、反代规则

然后对着每一个你看不懂的词（或你想“抄”的做法）重复三层问法：

第 1 层：定义（它到底指什么，边界在哪）
第 2 层：选型（常见实现 / 替代方案 / trade‑off / 坑）
第 3 层：落地（在你的项目里要改哪些文件、加哪些服务、怎么验收）

8.2 五连问模板（抄黑话最省力）

把下面这段当成你的“黑话提问 Prompt”，每次只替换术语即可：

术语：<例如 前后端分离 / 数据库迁移 / 任务队列>

背景：我在做一个可 docker compose 一键启动的最小系统（FastAPI + Next.js + Nginx + MySQL）。

请按以下结构输出（不要空谈）：
1) 一句话定义（<=20字）
2) 解决什么痛点？不做会怎样？
3) 典型实现方式有哪些？各自 trade-off？
4) 在我的技术栈里怎么落地？
   - 需要新增/修改哪些文件（按路径列清单）
   - 需要新增哪些环境变量（按名字列清单）
   - docker-compose 里要加哪些服务/依赖（按服务名列清单）
5) 验收标准（给可复制的命令：docker compose / curl / 浏览器路径）
6) 最常见的 3 个坑，以及规避方式

输出顺序：先“结论摘要”，再“落地清单”，最后“验收步骤”。

8.3 抄话术：把“需求”说成“可交付的工程约束”

你跟 AI 沟通，尽量固定成这 5 段（别让它自由发挥）：

目标：我要什么（对用户/业务有什么用）
范围：这次做什么、不做什么（防止无限扩写）
约束：技术栈 / 目录结构 / 部署方式 / 兼容性
非功能：性能 / 安全 / 可观测 / 可回滚
验收：接口/页面/测试/日志证据（必须可复制执行）

下面这段是“万能开场白”，你可以直接丢给 AI 当工作指令：

我们要做 <功能>，目标是 <业务价值>。

约束：
- 前后端分离：Next.js 只负责页面；FastAPI 只负责 API；Nginx 统一入口与反代。
- 所有配置走 env；提供 docker/.env.example.full；本地 docker compose 一键启动。
- 涉及数据库结构变更必须用迁移工具（如 Alembic/Prisma），并在容器启动时自动迁移（包含等待 DB 就绪）。
- 如果需要异步任务：引入任务队列（如 Redis + Celery/BullMQ），任务必须幂等、可重试、可观测。

交付物：
- 按路径列出新增/修改的文件清单
- 更新 tasks.md：每条任务都可验收
- 更新 agents_chat：记录关键决策与验收结果

验收：
- 给出我可以复制粘贴执行的命令（docker compose / curl）
- 给出失败时排错路径（看哪些容器日志/端口/配置）

8.4 黑话 -> 交付物映射表（把词变成文件）

黑话	你需要交付什么（最小）	你应该让 AI 输出什么
前后端分离	`frontend/` + `backend/` 两套构建；`nginx.conf` 反代 `/api`；明确 CORS/CSRF 策略	路由边界说明 + Nginx 配置片段 + API 契约（请求/响应）+ 验收命令
技术栈组合	目录骨架 + Compose 服务图 + 端口/依赖约定	“一页纸架构”+ `docker-compose*.yml` 服务清单 + 启动/验收步骤
数据库迁移	迁移工具初始化（Alembic/Prisma 等）+ migration 脚本 + 自动执行 + 回滚策略	迁移目录结构 + 入口脚本（wait-for-db + migrate + start）+ 失败排错点
任务队列	broker（Redis/RabbitMQ）+ worker 服务 + retry/timeout + 幂等 + 失败落盘/死信	Compose 增加 worker/broker + 任务定义样例 + 指标/日志字段 + 验收（投递/消费）
健康检查	`/healthz` 接口 + Compose healthcheck + Nginx/上游超时	健康检查 URL + docker healthcheck 配置 + “不健康时怎么定位”
可观测性	结构化日志 + 请求链路 ID + 最小 metrics（请求数/耗时/错误率）	日志字段规范 + metrics endpoint + 最小告警阈值建议

9）从 0 到 1：一张“系统黑话清单”（你照着问，就能把系统拼出来）

下面这些词，你不需要一次全懂；你只要能用第 8.2 的模板问到能落地，就够你从 0 到 1 组装出专业系统：

架构边界：前后端分离、反向代理、BFF、API 版本、模块化单体（不是上来就微服务）
数据与一致性：数据库迁移、事务、幂等、唯一约束、索引、软删除、分页（游标 vs offset）
异步与可靠性：任务队列、消息队列、重试/退避、死信队列、定时任务（cron）、最终一致性
性能与缓存：缓存（本地/Redis）、缓存穿透/击穿/雪崩、限流、降级
权限与安全：JWT、OAuth2、RBAC、多租户、CORS、CSRF、Secrets 管理
交付与运维：Docker/Compose、CI/CD、配置分环境、蓝绿/灰度发布、回滚策略、备份恢复
质量与验收：OpenAPI、契约测试、集成测试、Smoke Test、SLO/报警、可复盘（agents_chat）

你会发现：当你能把这些词说清楚，并且能把它们变成“文件清单 + 验收清单”，AI 的产出会立刻从“能跑 Demo”升级到“能交付系统”。