diff --git a/AGENTS.md b/AGENTS.md index f26f1b7..8507a56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/蜂群巡检脚本） diff --git a/README.md b/README.md index 7f7bf3e..60c8c31 100644 --- a/README.md +++ b/README.md @@ -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 的场景 @@ -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 功能的现代化终端，能有效提升命令行操作和错误排查的效率。 diff --git a/assets/documents/AGENTS.md b/assets/documents/AGENTS.md index 5434e86..b223c86 100644 --- a/assets/documents/AGENTS.md +++ b/assets/documents/AGENTS.md @@ -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 不可用时的备选路线。 + ## 操作规范 ### 允许 diff --git a/assets/documents/README.md b/assets/documents/README.md index 90fbba2..e76b63f 100644 --- a/assets/documents/README.md +++ b/assets/documents/README.md @@ -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/) ## 🔗 相关资源 diff --git a/assets/documents/guides/getting-started/Codex-CLI配置.md b/assets/documents/guides/getting-started/Codex-CLI配置.md new file mode 100644 index 0000000..f401d26 --- /dev/null +++ b/assets/documents/guides/getting-started/Codex-CLI配置.md @@ -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 不可用时的备选方案 diff --git a/assets/documents/guides/getting-started/OpenCode-CLI配置.md b/assets/documents/guides/getting-started/OpenCode-CLI配置.md index 868102b..7f16dbd 100644 --- a/assets/documents/guides/getting-started/OpenCode-CLI配置.md +++ b/assets/documents/guides/getting-started/OpenCode-CLI配置.md @@ -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 服务器 diff --git a/assets/documents/guides/getting-started/README.md b/assets/documents/guides/getting-started/README.md index 9ef585a..757976e 100644 --- a/assets/documents/guides/getting-started/README.md +++ b/assets/documents/guides/getting-started/README.md @@ -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/) - 核心理念与方法论 diff --git a/assets/documents/guides/getting-started/Vibe Coding 哲学原理.md b/assets/documents/guides/getting-started/Vibe Coding 哲学原理.md index c90dd38..40c7e7b 100644 --- a/assets/documents/guides/getting-started/Vibe Coding 哲学原理.md +++ b/assets/documents/guides/getting-started/Vibe Coding 哲学原理.md @@ -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 不可用时的备选路线 diff --git a/assets/documents/guides/getting-started/开发环境搭建.md b/assets/documents/guides/getting-started/开发环境搭建.md index 728d1dc..56dc198 100644 --- a/assets/documents/guides/getting-started/开发环境搭建.md +++ b/assets/documents/guides/getting-started/开发环境搭建.md @@ -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