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

docs: consolidate getting started references

Browse Source
This commit is contained in:
tukuaiai
2026-05-02 05:56:44 +08:00
parent f57ccc2f9d
commit 7bf3b782f2
25 changed files with 244 additions and 456 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/Codex-CLI配置.md
+117 -3
View File
@@ -6,7 +6,7 @@
Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、代码修改、命令执行、测试验证到 Git 提交的主流程。
OpenCode CLI 保留为备选方案：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费模型时，再使用 [OpenCode-CLI配置](OpenCode-CLI配置.md)。
OpenCode CLI 只作为备选方案保留在本文底部：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费、本地、多模型实验入口时，再使用 OpenCode。
## 不会操作？先让网页 AI 生成逐步执行版
@@ -336,8 +336,122 @@ codex login
如果你是在无桌面的远程服务器上登录，按终端输出的设备码或链接，在本机浏览器完成授权。
## Codex 不可用时：OpenCode 备选方案
OpenCode 是开源 AI 编程代理，支持终端、桌面应用和 IDE 扩展。本文仍然以 Codex CLI 为默认路线；只有当 Codex CLI 暂时不可用、账号不可用，或你明确需要接入免费/本地模型时，才切到 OpenCode。
官网：[opencode.ai](https://opencode.ai/)
### 不会操作？先让网页 AI 生成逐步执行版
如果你要用 OpenCode 作为备选路线，先打开网页版 AI，把下面提示词和本节内容一起复制进去，让 AI 按你的系统和模型来源生成逐步执行方案：
```text
你是一个面向零基础用户的 OpenCode CLI 配置助手。
请根据我的电脑环境、可用模型和目标，生成适合我的逐步安装与配置流程。
我的当前情况是：
- 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux]
- 是否已经安装 Node.js / npm / Homebrew / Scoop / Chocolatey：[填写没有 / 已安装 / 不确定]
- 想使用的模型来源：[填写 Z.AI / MiniMax / Hugging Face / Ollama / 不确定]
- 是否已经有 API Key：[填写有 / 没有 / 不确定]
- 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”]
要求：
1. 每一步只做一件事。
2. 每一步都说明我要在哪个终端执行、输入什么、观察什么、如何判断成功。
3. 每条命令都必须单独放在代码块里。
4. 不要跳步；默认我是第一次配置新电脑。
5. 如果我后续贴报错，请根据当前步骤给出最小修复方案。
```
### 何时选择 OpenCode
- 没有可用的 OpenAI / Codex CLI 账号或环境。
- 需要接入 Z.AI、MiniMax、Hugging Face、本地 Ollama 等模型。
- 想保留一条不依赖单一模型提供商的备份路线。
### 安装
```bash
# 一键安装（推荐）
curl -fsSL https://opencode.ai/install | bash
# 或使用 npm
npm install -g opencode-ai
# 或使用 Homebrew（macOS/Linux）
brew install anomalyco/tap/opencode
```
Windows 可用 Scoop 或 Chocolatey：
```powershell
scoop bucket add extras
scoop install extras/opencode
choco install opencode
```
### 模型配置
OpenCode 支持多个模型提供商。进入 OpenCode 后，用 `/connect` 添加模型提供商，用 `/models` 切换模型。
常见备选：
1. Z.AI：注册 API Key 后，`/connect` 搜索 Z.AI，再用 `/models` 选择 GLM 模型。
2. MiniMax：注册 API Key 后，`/connect` 搜索 MiniMax，再用 `/models` 选择可用模型。
3. Hugging Face：创建 Token 后，`/connect` 搜索 Hugging Face，再用 `/models` 选择可用模型。
4. Ollama：本地安装 Ollama 后，在 `opencode.json` 中配置 OpenAI-compatible base URL。
Ollama 最小安装示例：
```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama2
```
### 核心命令
| 命令 | 功能 |
|:---|:---|
| `/models` | 切换模型 |
| `/connect` | 添加 API Key |
| `/init` | 初始化项目，生成 AGENTS.md |
| `/undo` | 撤销上次修改 |
| `/redo` | 重做 |
| `/share` | 分享对话链接 |
| `Tab` | 切换 Plan 模式 |
### 推荐工作流
```bash
cd /path/to/project
opencode
```
进入后先初始化项目，再切换模型：
```text
/init
/models
```
建议先用 Plan 模式让 AI 规划，确认方案后再执行。
### 配置文件位置
- 全局配置：`~/.config/opencode/opencode.json`
- 项目配置：`./opencode.json`
- 认证信息：`~/.local/share/opencode/auth.json`
### 相关资源
- [OpenCode 官方文档](https://opencode.ai/docs/)
- [OpenCode GitHub 仓库](https://github.com/opencode-ai/opencode)
- [Models.dev 模型目录](https://models.dev)
## 下一步
→ [开发环境搭建](开发环境搭建.md) - 回看基础环境
→ [OpenCode-CLI配置](OpenCode-CLI配置.md) - Codex CLI 不可用时的备选方案
docs/getting-started/IDE配置.md
-196
View File
@@ -1,196 +0,0 @@
# IDE 配置提示词
> 使用方法：复制下方对应你 IDE 的提示词，粘贴到任意 AI 对话框，AI 会一步步指导你完成配置。
**前置条件**：请先完成 [开发环境搭建](开发环境搭建.md)
---
## 不会操作？先让网页 AI 生成逐步执行版
如果你不知道该选 VS Code、Cursor 还是 Windsurf，先打开网页版 AI（ChatGPT / Claude / Gemini 均可），把下面这段提示词和本文件全文一起复制进去，让 AI 按你的电脑环境生成逐步配置方案：
```text
你是一个面向零基础用户的 IDE 配置助手。
我会把一份 IDE 配置文档发给你。请你根据我的电脑环境和目标，帮我选择合适的 IDE 路线，并输出逐步执行流程。
我的当前情况是：
- 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux]
- 是否已经安装 VS Code / Cursor / Windsurf：[填写没有 / 已安装某个]
- 是否已经完成开发环境搭建：[填写是 / 否 / 不确定]
- 当前目标：[填写我想用 IDE 做什么项目或任务]
- 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”]
要求：
1. 每一步只做一件事。
2. 每一步都说明我要点哪里、输入什么、观察什么、如何判断成功。
3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。
4. 不要跳步；默认我是第一次配置新电脑。
5. 如果我后续贴报错或截图描述，请根据当前步骤给出最小修复方案。
```
## 选择你的 IDE
- [VS Code](#vs-code) - 免费，最通用
- [Cursor](#cursor) - AI 原生 IDE，基于 VS Code
- [Windsurf](#windsurf) - AI 原生 IDE，新用户有免费额度
---
## VS Code
### 🪟 Windows + WSL 用户
```
你是一个耐心的 VS Code 配置助手。我已经安装好了 WSL2 和 Ubuntu，现在需要你一步一步指导我配置 VS Code 以获得最佳的 WSL 开发体验。
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 在 Windows 上安装 VS Code（如果还没装）
2. 安装 Remote - WSL 扩展
3. 通过 WSL 打开项目文件夹
4. 安装基础开发扩展（GitLens、Prettier、ESLint、Local History）
5. 配置终端默认使用 WSL
6. 配置自动保存和格式化
7. 验证配置是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在开始第一步吧。
```
### 🪟 Windows 原生用户
```
你是一个耐心的 VS Code 配置助手。我使用 Windows 系统（不使用 WSL），现在需要你一步一步指导我配置 VS Code。
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 安装 VS Code（如果还没装）
2. 安装基础开发扩展（GitLens、Prettier、ESLint、Local History）
3. 配置终端使用 PowerShell 或 Git Bash
4. 配置自动保存和格式化
5. 配置 Git 集成
6. 验证配置是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在开始第一步吧。
```
### 🍎 macOS 用户
```
你是一个耐心的 VS Code 配置助手。我使用 macOS 系统，现在需要你一步一步指导我配置 VS Code。
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 安装 VS Code（通过 Homebrew 或官网）
2. 配置 code 命令行工具
3. 安装基础开发扩展（GitLens、Prettier、ESLint、Local History）
4. 配置自动保存和格式化
5. 验证配置是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在开始第一步吧。
```
### 🐧 Linux 用户
```
你是一个耐心的 VS Code 配置助手。我使用 Linux 系统（Ubuntu/Debian），现在需要你一步一步指导我配置 VS Code。
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 安装 VS Code（通过 apt 或 snap）
2. 安装基础开发扩展（GitLens、Prettier、ESLint、Local History）
3. 配置自动保存和格式化
4. 配置终端集成
5. 验证配置是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在开始第一步吧。
```
---
## Cursor
> AI 原生 IDE，基于 VS Code，内置 AI 编程功能。官网：https://cursor.com
```
你是一个耐心的 Cursor IDE 配置助手。我想使用 Cursor 作为我的主要开发工具，需要你一步一步指导我完成安装和配置。
我的操作系统是：[请告诉我你用的是 Windows/macOS/Linux]
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 下载并安装 Cursor（官网：https://cursor.com）
2. 首次启动配置（登录、选择主题等）
3. 导入 VS Code 设置和扩展（如果之前用过 VS Code）
4. 配置 AI 功能（API Key 或订阅）
5. 学习 Cursor 的核心快捷键：
- Cmd/Ctrl + K：AI 编辑
- Cmd/Ctrl + L：AI 聊天
- Cmd/Ctrl + I：Composer 模式
6. 配置自动保存
7. 验证 AI 功能是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 解释 Cursor 相比 VS Code 的独特功能
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在先问我用的是什么操作系统吧。
```
---
## Windsurf
> AI 原生 IDE，新用户有免费额度。官网：https://windsurf.com
```
你是一个耐心的 Windsurf IDE 配置助手。我想使用 Windsurf 作为我的开发工具，需要你一步一步指导我完成安装和配置。
我的操作系统是：[请告诉我你用的是 Windows/macOS/Linux]
请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：
1. 下载并安装 Windsurf（官网：https://windsurf.com）
2. 注册账号并登录（新用户有免费额度）
3. 首次启动配置
4. 了解 Windsurf 的 AI 功能（Cascade 等）
5. 配置基础开发环境
6. 验证 AI 功能是否正常工作
要求：
- 每个步骤给出具体的操作方法
- 解释 Windsurf 的独特功能
- 如果我遇到问题，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步
现在先问我用的是什么操作系统吧。
```
---
## 配置完成后
IDE 配置完成后，阅读 [README.md](../../../../README.md) 了解 Vibe Coding 工作流，开始你的第一个项目！
docs/getting-started/OpenCode-CLI配置.md
-219
View File
@@ -1,219 +0,0 @@
# OpenCode CLI 配置（备选方案）
> 备选 AI CLI 路线：当你暂时无法使用 Codex CLI，或希望接入免费/本地模型时使用。
本教程默认推荐 [Codex CLI](Codex-CLI配置.md)。OpenCode 是开源 AI 编程代理，支持终端、桌面应用和 IDE 扩展，适合用作免费模型、本地模型或多模型实验入口。
官网：[opencode.ai](https://opencode.ai/)
---
## 不会操作？先让网页 AI 生成逐步执行版
如果你暂时无法使用 Codex CLI，或想把 OpenCode 作为备选路线，先打开网页版 AI（ChatGPT / Claude / Gemini 均可），把下面这段提示词和本文件全文一起复制进去，让 AI 按你的系统和模型来源生成逐步执行方案：
```text
你是一个面向零基础用户的 OpenCode CLI 配置助手。
我会把一份 OpenCode CLI 配置文档发给你。请你根据我的电脑环境、可用模型和目标，生成适合我的逐步安装与配置流程。
我的当前情况是：
- 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux]
- 是否已经安装 Node.js / npm / Homebrew / Scoop / Chocolatey：[填写没有 / 已安装 / 不确定]
- 想使用的模型来源：[填写 Z.AI / MiniMax / Hugging Face / Ollama / 不确定]
- 是否已经有 API Key：[填写有 / 没有 / 不确定]
- 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”]
要求：
1. 每一步只做一件事。
2. 每一步都说明我要在哪个终端执行、输入什么、观察什么、如何判断成功。
3. 每条命令都必须单独放在代码块里。
4. 不要跳步；默认我是第一次配置新电脑。
5. 如果我后续贴报错，请根据当前步骤给出最小修复方案。
```
## 何时选择 OpenCode
- 没有可用的 OpenAI / Codex CLI 账号或环境
- 需要接入 Z.AI、MiniMax、Hugging Face、本地 Ollama 等模型
- 想保留一条不依赖单一模型提供商的备份路线
如果 Codex CLI 可用，优先完成：[Codex-CLI配置](Codex-CLI配置.md)。
## 安装
```bash
# 一键安装（推荐）
curl -fsSL https://opencode.ai/install | bash
# 或使用 npm
npm install -g opencode-ai
# 或使用 Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode
# Windows - Scoop
scoop bucket add extras && scoop install extras/opencode
# Windows - Chocolatey
choco install opencode
```
---
## 免费模型配置
OpenCode 支持多个模型提供商。以下配置适合作为 Codex CLI 不可用时的备选入口。
### 方式一：Z.AI（推荐，GLM-4.7）
1. 访问 [Z.AI API 控制台](https://z.ai/manage-apikey/apikey-list) 注册并创建 API Key
2. 运行 `/connect` 命令，搜索 **Z.AI**
3. 输入 API Key
4. 运行 `/models` 选择 **GLM-4.7**
```bash
opencode
# 进入后输入
/connect
# 选择 Z.AI，输入 API Key
/models
# 选择 GLM-4.7
```
### 方式二：MiniMax（M2.1）
1. 访问 [MiniMax API 控制台](https://platform.minimax.io/login) 注册并创建 API Key
2. 运行 `/connect`，搜索 **MiniMax**
3. 输入 API Key
4. 运行 `/models` 选择 **M2.1**
### 方式三：Hugging Face（多种免费模型）
1. 访问 [Hugging Face 设置](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) 创建 Token
2. 运行 `/connect`，搜索 **Hugging Face**
3. 输入 Token
4. 运行 `/models` 选择 **Kimi-K2-Instruct** 或 **GLM-4.6**
### 方式四：本地模型（Ollama）
```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 拉取模型
ollama pull llama2
```
在 `opencode.json` 中配置：
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama2": {
"name": "Llama 2"
}
}
}
}
}
```
---
## 核心命令
| 命令 | 功能 |
|:---|:---|
| `/models` | 切换模型 |
| `/connect` | 添加 API Key |
| `/init` | 初始化项目（生成 AGENTS.md） |
| `/undo` | 撤销上次修改 |
| `/redo` | 重做 |
| `/share` | 分享对话链接 |
| `Tab` | 切换 Plan 模式（只规划不执行） |
---
## 让 AI 执行一切配置任务
OpenCode 的核心思维：**把配置任务交给 AI 执行，把选择权和验收权留给你**。
### 示例：安装 MCP 服务器
```
帮我安装 filesystem MCP 服务器，配置到 opencode
```
### 示例：部署 GitHub 开源项目
```
克隆 https://github.com/xxx/yyy 项目，阅读 README，帮我完成所有依赖安装和环境配置
```
### 示例：配置 Skills
```
阅读项目结构，为这个项目创建合适的 AGENTS.md 规则文件
```
### 示例：配置环境变量
```
检查项目需要哪些环境变量，帮我创建 .env 文件模板并说明每个变量的用途
```
### 示例：安装依赖
```
分析 package.json / requirements.txt，安装所有依赖，解决版本冲突
```
---
## 推荐工作流
1. **进入项目目录**
```bash
cd /path/to/project
opencode
```
2. **初始化项目**
```
/init
```
3. **切换免费模型**
```
/models
# 选择 GLM-4.7 或 MiniMax M2.1
```
4. **开始工作**
- 先用 `Tab` 切换到 Plan 模式，让 AI 规划
- 确认方案后再让 AI 执行
---
## 配置文件位置
- 全局配置：`~/.config/opencode/opencode.json`
- 项目配置：`./opencode.json`（项目根目录）
- 认证信息：`~/.local/share/opencode/auth.json`
---
## 相关资源
- [OpenCode 官方文档](https://opencode.ai/docs/)
- [GitHub 仓库](https://github.com/opencode-ai/opencode)
- [Models.dev - 模型目录](https://models.dev)
docs/getting-started/README.md
+1 -1
View File
@@ -27,7 +27,7 @@
## 📚 学习路径
0. [学习地图](学习地图.md) - 先按目标选择新手、开发者、团队、Prompt、Skill、Workflow 或 GEO/SEO 路线
0. [学习地图](学习地图.md) - 先按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线
1. [问题求解能力](../concepts/问题求解能力.md) - 先学会定义问题与验收标准
2. [Vibe Coding 经验](Vibe%20Coding%20经验.md) - 明确语言化、门禁、人机分工与工程闭环
3. [网络环境配置](网络环境配置.md) - 配置网络访问
docs/getting-started/Vibe Coding 经验.md
+1 -1
View File
@@ -101,4 +101,4 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
→ [Codex-CLI配置](Codex-CLI配置.md) - 默认 AI CLI 路线
→ [OpenCode-CLI配置](OpenCode-CLI配置.md) - Codex CLI 不可用时的备选路线
→ [Codex CLI 配置](Codex-CLI配置.md) - 默认 AI CLI 路线，文末包含 OpenCode 备选方案
docs/getting-started/开发环境搭建.md
+69
View File
@@ -143,6 +143,75 @@
## 配置完成后
### IDE 配置
开发环境装好后，再选择编辑器。新手默认选 VS Code；想使用 AI 原生 IDE 时，再考虑 Cursor 或 Windsurf。
如果你不知道该选 VS Code、Cursor 还是 Windsurf，先打开网页版 AI，把下面提示词和本节内容一起复制进去：
```text
你是一个面向零基础用户的 IDE 配置助手。
请根据我的电脑环境和目标，帮我选择合适的 IDE 路线，并输出逐步执行流程。
我的当前情况是：
- 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux]
- 是否已经安装 VS Code / Cursor / Windsurf：[填写没有 / 已安装某个]
- 是否已经完成开发环境搭建：[填写是 / 否 / 不确定]
- 当前目标：[填写我想用 IDE 做什么项目或任务]
- 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”]
要求：
1. 每一步只做一件事。
2. 每一步都说明我要点哪里、输入什么、观察什么、如何判断成功。
3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。
4. 不要跳步；默认我是第一次配置新电脑。
5. 如果我后续贴报错或截图描述，请根据当前步骤给出最小修复方案。
```
#### VS Code（默认推荐）
适合：免费、通用、教程最多，Windows + WSL 体验稳定。
Windows + WSL 用户重点做：
1. 在 Windows 上安装 VS Code。
2. 安装 **Remote - WSL** 扩展。
3. 从 Ubuntu 终端进入项目目录，执行 `code .` 打开项目。
4. 安装基础扩展：GitLens、Prettier、ESLint、Local History。
5. 确认 VS Code 终端默认进入 WSL 环境。
macOS / Linux / Windows 原生用户重点做：
1. 安装 VS Code。
2. 安装基础扩展：GitLens、Prettier、ESLint、Local History。
3. 配置自动保存和格式化。
4. 确认终端、Git、Node.js、Python 可用。
#### Cursor
适合：想要 AI 原生 IDE，且愿意使用 Cursor 的内置 AI 编程能力。
配置重点：
1. 从 [cursor.com](https://cursor.com) 下载并安装。
2. 首次启动后登录账号。
3. 如已有 VS Code，可导入设置和扩展。
4. 熟悉核心入口：`Cmd/Ctrl + K`、`Cmd/Ctrl + L`、`Cmd/Ctrl + I`。
5. 打开项目后，先让 AI 读取 README、AGENTS 和当前目录结构，再执行任务。
#### Windsurf
适合：想体验另一类 AI 原生 IDE，或需要备用 IDE。
配置重点：
1. 从 [windsurf.com](https://windsurf.com) 下载并安装。
2. 注册并登录账号。
3. 打开项目目录。
4. 了解 Cascade 等 AI 功能。
5. 用一个小修改验证 AI、终端和 Git 是否能正常工作。
### CLI 工具配置技巧
AI CLI 工具默认会询问确认，开启全权限模式可以跳过：