gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-07-28 03:07:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: align beginner path around codex cli

Browse Source
This commit is contained in:
tukuaiai
2026-05-01 22:01:14 +08:00
parent f9e9b75dd8
commit 98f1f1f632
9 changed files with 216 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2
View File
@@ -202,6 +202,8 @@ git push origin develop
- `.github/workflows/ci.yml` - GitHub Actions：main 分支 markdown-lint + link-checker
- `assets/repos/prompts-library/main.py` - 提示词转换工具入口
- `assets/repos/backups/一键备份.sh` - 备份脚本入口
- `assets/documents/guides/getting-started/Codex-CLI配置.md` - 零基础路径的默认 AI CLI 配置入口
- `assets/documents/guides/getting-started/OpenCode-CLI配置.md` - Codex CLI 不可用时的备选 AI CLI 配置入口
- `assets/documents/principles/fundamentals/问题求解能力.md` - 问题定义与求解路径底层模型
- `assets/documents/principles/fundamentals/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项
- `assets/skills/tmux-autopilot/` - tmux 自动化操控技能（基于 oh-my-tmux，含 capture-pane/send-keys/蜂群巡检脚本）
README.md
+8 -5
View File
@@ -12,7 +12,7 @@
# Vibe Coding 指南
**一个通过与 AI 结对编程，将想法变为现实的终极工作站**
**一套面向零基础学习者的 Vibe Coding 入门到精通教程**
---
@@ -55,7 +55,7 @@
## 🎲 前言
**这是一个不断生长和自我否定的项目，当下的一切经验和能力都可能因 AI 能力的变化而失去意义，所以请时刻保持以 AI 为主的思维，重视这次宇宙级的变革，所有的经验都可能失效，辩证的看🙏🙏🙏**，**Vibe Coding** 是一个与 AI 结对编程的终极工作流程，旨在帮助开发者丝滑地将想法变为现实。本指南详细介绍了从项目构思、技术选型、实施规划到具体开发、调试和扩展的全过程，强调以**规划驱动**和**模块化**，**索引构建**为核心（受限于模型上下文窗口而生成的解决策略），避免让 AI 失控导致项目混乱，Vibe Coding（氛围编程）是一种以自然语言驱动、让LLM生成大部分代码的开发方式，主张“先沉浸式做出能跑的东西”，以极低门槛快速产出原型但也伴随可控性与可靠性风险，由计算机科学家 [Andrej Karpathy](https://x.com/karpathy) 首次提出。
**这是一个不断生长和自我校正的项目。** 本仓库的统一定位是：帮助零基础学习者从环境配置、工具选择、需求表达、计划拆解、AI CLI 协作、代码验证、Git 迭代一路走到可独立交付项目。**Vibe Coding** 不是“让 AI 随便写”，而是用自然语言定义目标，用 Codex CLI 等 AI 工具执行工程动作，再用文档、测试和版本控制把结果固定下来。本指南强调**规划驱动**、**模块化**与**索引构建**，目标是让新手能从 0 开始，也能逐步形成可复用的专业工作流。
> **注意**：以下经验分享并非普遍适用，请在具体实践中结合场景，辩证采纳（点击标题可以展开收起内容）
@@ -97,11 +97,12 @@
完全新手？按顺序完成以下步骤：
0. [问题求解能力](./assets/documents/principles/fundamentals/问题求解能力.md) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架
1. [Vibe Coding 哲学原理](./assets/documents/guides/getting-started/Vibe%20Coding%20哲学原理.md) - 理解核心理念
1. [Vibe Coding 哲学原理](./assets/documents/guides/getting-started/Vibe%20Coding%20哲学原理.md) - 明确人机分工与工程闭环
2. [网络环境配置](./assets/documents/guides/getting-started/网络环境配置.md) - 配置网络访问
3. [开发环境搭建](./assets/documents/guides/getting-started/开发环境搭建.md) - 复制提示词给 AI，让 AI 指导你搭建环境
3. [开发环境搭建](./assets/documents/guides/getting-started/开发环境搭建.md) - 安装 Git、Node.js、Python、编辑器等基础环境
4. [IDE配置](./assets/documents/guides/getting-started/IDE配置.md) - 配置 VS Code 编辑器
5. [OpenCode-CLI配置](./assets/documents/guides/getting-started/OpenCode-CLI配置.md) - 免费 AI CLI 工具，支持 GLM-4.7/MiniMax M2.1 等模型
5. [Codex-CLI配置](./assets/documents/guides/getting-started/Codex-CLI配置.md) - 默认 AI CLI 路线，使用 gpt-5.5 与仓库配置基线
6. [OpenCode-CLI配置](./assets/documents/guides/getting-started/OpenCode-CLI配置.md) - 备选 AI CLI 路线，适合暂时无法使用 Codex CLI 的场景
</details>
@@ -267,6 +268,8 @@ TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
### 集成开发环境 (IDE) & 终端
* [**Visual Studio Code**](https://code.visualstudio.com/): 一款功能强大的集成开发环境，适合代码阅读与手动修改。其 `Local History` 插件对项目版本管理尤为便捷。
* [**Codex CLI**](./assets/documents/guides/getting-started/Codex-CLI配置.md): 本教程默认 AI CLI 路线，用于需求拆解、代码修改、命令执行、测试验证与 Git 迭代。
* [**OpenCode CLI**](./assets/documents/guides/getting-started/OpenCode-CLI配置.md): 备选 AI CLI 路线，适合 Codex CLI 不可用或需要免费/本地模型的场景。
* **虚拟环境 (.venv)**: 强烈推荐使用，可实现项目环境的一键配置与隔离，特别适用于 Python 开发。
* [**Cursor**](https://cursor.com/): 已经占领用户心智高地，人尽皆知。
* [**Warp**](https://www.warp.dev/): 集成 AI 功能的现代化终端，能有效提升命令行操作和错误排查的效率。
assets/documents/AGENTS.md
+7
View File
@@ -18,6 +18,13 @@ assets/documents/
└── workflow/ # 可复用工作流模板
```
## 关键入口
- `guides/getting-started/README.md`：零基础学习路径索引。
- `guides/getting-started/Vibe Coding 哲学原理.md`：人机分工与 Vibe Coding 工程闭环。
- `guides/getting-started/Codex-CLI配置.md`：默认 AI CLI 路线。
- `guides/getting-started/OpenCode-CLI配置.md`：Codex CLI 不可用时的备选路线。
## 操作规范
### 允许
assets/documents/README.md
+7 -6
View File
@@ -7,7 +7,7 @@
```
assets/documents/
├── principles/ # 原则与思想（fundamentals + philosophy）
│ ├── fundamentals/ # 原 00-基础指南
│ ├── fundamentals/ # 基础原则、问题求解、工程范式与代码质量
│ └── philosophy/ # 原 05-哲学与方法论
├── guides/ # 入门与方法（getting-started + playbook）
│ ├── getting-started/ # 原 01-入门指南
@@ -34,11 +34,12 @@ assets/documents/
5. **思维** → [philosophy](./principles/philosophy/README.md)
6. **理念** → [胶水编程](./principles/fundamentals/胶水编程.md)
7. **入门** → [Vibe Coding 哲学原理](./guides/getting-started/Vibe%20Coding%20哲学原理.md)
8. **配置** → [开发环境搭建](./guides/getting-started/开发环境搭建.md)
9. **工具** → [tmux 快捷键](./guides/playbook/tmux快捷键大全.md)
10. **远程** → [VS Code Remote Tunnel（WSL）](./guides/playbook/REMOTE_TUNNEL_GUIDE.md)
11. **实践** → [项目实战经验](./case-studies/)
12. **流程** → [工作流模板](./workflow/)
8. **环境** → [开发环境搭建](./guides/getting-started/开发环境搭建.md)
9. **默认 CLI** → [Codex CLI 配置](./guides/getting-started/Codex-CLI配置.md)
10. **工具** → [tmux 快捷键](./guides/playbook/tmux快捷键大全.md)
11. **远程** → [VS Code Remote Tunnel（WSL）](./guides/playbook/REMOTE_TUNNEL_GUIDE.md)
12. **实践** → [项目实战经验](./case-studies/)
13. **流程** → [工作流模板](./workflow/)
## 🔗 相关资源
assets/documents/guides/getting-started/Codex-CLI配置.md
+112
View File
@@ -0,0 +1,112 @@
# Codex CLI 配置
> 默认 AI CLI 路线：用 Codex CLI 作为主要编程代理，把本仓库的配置基线复制到本机 Codex Home。
## 定位
Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、代码修改、命令执行、测试验证到 Git 提交的主流程。
OpenCode CLI 保留为备选方案：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费模型时，再使用 [OpenCode-CLI配置](./OpenCode-CLI配置.md)。
## 前置条件
请先完成：
1. [网络环境配置](./网络环境配置.md)
2. [开发环境搭建](./开发环境搭建.md)
3. [IDE 配置](./IDE配置.md)
在终端验证 Codex CLI 是否可用：
```bash
codex --help
```
如果命令不存在，先按你当前系统的 Codex CLI 安装方式完成安装，再回到本页继续。
## 登录
```bash
codex login
```
登录完成后，再次运行：
```bash
codex --help
```
能看到命令说明，就说明 CLI 已可用。
## 使用仓库配置基线
本仓库已经提供 Codex CLI 配置基线：
- `assets/config/.codex/config.toml`
- `assets/config/.codex/AGENTS.md`
在仓库根目录执行：
```bash
mkdir -p ~/.codex
cp -f assets/config/.codex/config.toml ~/.codex/config.toml
cp -f assets/config/.codex/AGENTS.md ~/.codex/AGENTS.md
```
详细说明见：[Codex 配置基线](../../../config/.codex/README.md)。
## 推荐启动方式
日常使用：
```bash
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"
```
在完全可信的本地仓库中，需要减少确认弹窗时使用：
```bash
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox
```
高权限模式会放开确认与沙箱限制，只能在你确认可信的目录中使用。
## 推荐别名
在 `~/.bashrc` 中添加：
```bash
alias c='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"'
alias cy='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'
```
生效：
```bash
source ~/.bashrc
```
## 第一次使用
进入你的项目目录：
```bash
cd /path/to/project
codex
```
然后让 Codex 先建立项目上下文：
```text
请阅读当前仓库结构，说明这个项目是什么、关键入口在哪里、下一步最小可执行任务是什么。先给计划，不要直接改文件。
```
确认计划后，再让 Codex 执行。
## 下一步
→ [开发环境搭建](./开发环境搭建.md) - 回看基础环境
→ [IDE 配置](./IDE配置.md) - 配置编辑器
→ [OpenCode-CLI配置](./OpenCode-CLI配置.md) - Codex CLI 不可用时的备选方案
assets/documents/guides/getting-started/OpenCode-CLI配置.md
+13 -5
View File
@@ -1,13 +1,21 @@
# OpenCode CLI 配置
# OpenCode CLI 配置（备选方案）
> 免费 AI 编程助手，支持 75+ 模型，无需信用卡
> 备选 AI CLI 路线：当你暂时无法使用 Codex CLI，或希望接入免费/本地模型时使用。
OpenCode 是一个开源 AI 编程代理，支持终端、桌面应用和 IDE 扩展。无需账号即可使用免费模型。
本教程默认推荐 [Codex CLI](./Codex-CLI配置.md)。OpenCode 是开源 AI 编程代理，支持终端、桌面应用和 IDE 扩展，适合用作免费模型、本地模型或多模型实验入口。
官网：[opencode.ai](https://opencode.ai/)
---
## 何时选择 OpenCode
- 没有可用的 OpenAI / Codex CLI 账号或环境
- 需要接入 Z.AI、MiniMax、Hugging Face、本地 Ollama 等模型
- 想保留一条不依赖单一模型提供商的备份路线
如果 Codex CLI 可用，优先完成：[Codex-CLI配置](./Codex-CLI配置.md)。
## 安装
```bash
@@ -31,7 +39,7 @@ choco install opencode
## 免费模型配置
OpenCode 支持多个免费模型提供商，无需付费即可使用。
OpenCode 支持多个模型提供商。以下配置适合作为 Codex CLI 不可用时的备选入口。
### 方式一：Z.AI（推荐，GLM-4.7）
@@ -113,7 +121,7 @@ ollama pull llama2
## 让 AI 执行一切配置任务
OpenCode 的核心思维：**把所有配置任务交给 AI**。
OpenCode 的核心思维：**把配置任务交给 AI 执行，把选择权和验收权留给你**。
### 示例：安装 MCP 服务器
assets/documents/guides/getting-started/README.md
+6 -3
View File
@@ -1,13 +1,16 @@
# 🚀 入门指南
> 从零开始学习 Vibe Coding，配置环境
> 从零基础到独立交付项目的 Vibe Coding 学习路径
## 📚 学习路径
1. [Vibe Coding 哲学原理](./Vibe%20Coding%20哲学原理.md) - 理解核心理念
0. [问题求解能力](../../principles/fundamentals/问题求解能力.md) - 先学会定义问题与验收标准
1. [Vibe Coding 哲学原理](./Vibe%20Coding%20哲学原理.md) - 明确人机分工与工程闭环
2. [网络环境配置](./网络环境配置.md) - 配置网络访问
3. [开发环境搭建](./开发环境搭建.md) - 搭建开发环境
3. [开发环境搭建](./开发环境搭建.md) - 搭建 Git、Node.js、Python、编辑器等基础环境
4. [IDE 配置](./IDE配置.md) - 配置编辑器
5. [Codex CLI 配置](./Codex-CLI配置.md) - 默认 AI CLI 路线
6. [OpenCode CLI 配置](./OpenCode-CLI配置.md) - 备选 AI CLI 路线
## 🔗 相关资源
- [基础指南](../../principles/fundamentals/) - 核心理念与方法论
assets/documents/guides/getting-started/Vibe Coding 哲学原理.md
+42 -11
View File
@@ -1,29 +1,60 @@
# Vibe Coding 哲学原理
> 道生一，一生二，二生三，三生万物。
> 用自然语言定义目标，用 AI CLI 执行工程动作，用文档、测试与 Git 固化结果。
---
**一**：安装一个 AI CLI，获得与 AI 对话的能力
## 核心判断
**二**：AI 能读写一切文件，你不再需要手动编辑
Vibe Coding 不是把代码外包给 AI，也不是让 AI 随机试错。
**三**：AI 能配置一切环境，安装依赖、部署项目
它是一套工程协作方式：人负责目标、约束、判断与验收；AI 负责读取上下文、提出计划、修改文件、运行命令与整理证据。
**万物**：AI 生成代码、文档、测试、脚本——一切皆可生成
## 四层能力
---
**一：连接**
## 心法
安装 Codex CLI，获得能直接操作仓库的 AI 编程入口。
> 我是 AI 的寄生者，没有 AI 我失去一切能力。
**二：读写**
**你**：描述意图、验证结果、做决策
AI 能读取项目结构、修改文件、生成文档、补充测试，不再只停留在聊天框里。
**AI**：理解意图、执行操作、生成产出
**三：闭环**
AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认目标和验收结果。
**万物：复用**
把一次成功经验沉淀成 README、AGENTS、prompt、skill、workflow，下次直接复用。
## 人机分工
**你负责：**
- 说清目标：要做什么、不要做什么、成功标准是什么
- 设定约束：技术栈、时间、成本、风险、边界
- 做最终判断：方案是否合理、结果是否可接受
**AI 负责：**
- 读取上下文：代码、文档、配置、错误日志
- 拆解任务：计划、步骤、验证方式
- 执行动作：写代码、改文档、跑命令、查问题
- 沉淀证据：测试结果、diff、commit、风险说明
## 入门铁律
1. 先定义问题，再让 AI 写代码。
2. 先让 AI 给计划，再让 AI 执行。
3. 每一步都要能验证，不把“看起来对”当成完成。
4. 频繁提交 Git，把每次进展变成可回滚的检查点。
5. 让 README、AGENTS、任务文档持续更新，避免上下文丢失。
---
## 下一步
→ [OpenCode-CLI配置](./OpenCode-CLI配置.md) - 获得你的"一"
→ [Codex-CLI配置](./Codex-CLI配置.md) - 默认 AI CLI 路线
→ [OpenCode-CLI配置](./OpenCode-CLI配置.md) - Codex CLI 不可用时的备选路线
assets/documents/guides/getting-started/开发环境搭建.md
+19 -13
View File
@@ -21,7 +21,7 @@
2. 在 WSL2 中安装 Ubuntu
3. 配置 Ubuntu 基础环境（更新系统）
4. 安装 nvm 和 Node.js
5. 安装 Gemini CLI 或其他免费 AI CLI 工具
5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
6. 安装基础开发工具（git, python, build-essential, tmux）
7. 配置 Git 用户信息
8. 安装代码编辑器（VS Code 并配置 WSL 插件）
@@ -49,7 +49,7 @@
2. 安装 Node.js（通过官网安装包或 winget）
3. 安装 Git for Windows
4. 安装 Python
5. 安装 Gemini CLI 或其他免费 AI CLI 工具
5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
6. 配置 Git 用户信息
7. 安装代码编辑器（VS Code）
8. 验证所有工具是否正常工作
@@ -74,7 +74,7 @@
1. 安装 Homebrew 包管理器
2. 使用 Homebrew 安装 Node.js
3. 安装 Gemini CLI 或其他免费 AI CLI 工具
3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
4. 安装基础开发工具（git, python, tmux）
5. 配置 Git 用户信息
6. 安装代码编辑器（VS Code 或 Neovim）
@@ -100,7 +100,7 @@
1. 更新系统并安装基础依赖（curl, build-essential）
2. 安装 nvm 和 Node.js
3. 安装 Gemini CLI 或其他免费 AI CLI 工具
3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
4. 安装开发工具（git, python, tmux）
5. 配置 Git 用户信息
6. 安装代码编辑器（VS Code 或 Neovim）
@@ -124,14 +124,17 @@
AI CLI 工具默认会询问确认，开启全权限模式可以跳过：
```bash
# Codex - 最强配置
codex --enable web_search_request -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox
# Codex - 默认推荐
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"
# Codex - 高权限模式，仅限可信仓库
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox
# Claude Code - 跳过所有确认
claude --dangerously-skip-permissions
# Gemini CLI - YOLO 模式
gemini --yolo
# OpenCode - 备选方案
opencode
```
### 推荐的 Bash 别名配置
@@ -139,14 +142,17 @@ gemini --yolo
在 `~/.bashrc` 中添加以下配置，一个字母启动 AI：
```bash
# c - Codex (GPT-5.5 最强模式)
alias c='codex --enable web_search_request -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'
# c - Codex 默认模式
alias c='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"'
# cy - Codex 高权限模式，仅限可信仓库
alias cy='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'
# cc - Claude Code (全权限)
alias cc='claude --dangerously-skip-permissions'
# g - Gemini CLI (YOLO 模式)
alias g='gemini --yolo'
# oc - OpenCode 备选方案
alias oc='opencode'
```
配置后执行 `source ~/.bashrc` 生效。
@@ -155,4 +161,4 @@ alias g='gemini --yolo'
环境搭建完成后，继续下一步：
→ [IDE配置](./IDE配置.md) - 配置 VS Code 开发环境
→ [Codex-CLI配置](./Codex-CLI配置.md) - 配置默认 AI CLI