From b1aedf6f2beef07c375841467fe7d9c07d21ac5f Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sat, 2 May 2026 23:27:58 +0800 Subject: [PATCH] docs: getting-started - merge into linear guide --- AGENTS.md | 2 +- README.md | 15 +- assets/ai-citation/faq.md | 4 +- assets/ai-citation/llms-full.txt | 4 +- docs/AGENTS.md | 4 +- docs/README.md | 9 +- docs/faq.md | 4 +- docs/getting-started/CLI配置.md | 457 --------- docs/getting-started/README.md | 1126 ++++++++++++++++++++- docs/getting-started/Vibe Coding 经验.md | 102 -- docs/getting-started/学习地图.md | 149 --- docs/getting-started/开发环境搭建.md | 257 ----- docs/getting-started/网络环境配置.md | 136 --- docs/references/AI编程质量门禁与常见坑.md | 2 +- llms.txt | 1 - metadata/redirects.yml | 12 +- 16 files changed, 1132 insertions(+), 1152 deletions(-) delete mode 100644 docs/getting-started/CLI配置.md delete mode 100644 docs/getting-started/Vibe Coding 经验.md delete mode 100644 docs/getting-started/学习地图.md delete mode 100644 docs/getting-started/开发环境搭建.md delete mode 100644 docs/getting-started/网络环境配置.md diff --git a/AGENTS.md b/AGENTS.md index dd3e219..f67f313 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -211,7 +211,7 @@ git push origin develop - `.github/workflows/ci.yml` - GitHub Actions：develop/master 分支 markdown-lint + link-checker - `scripts/check-local-links.py` - 仓库内 Markdown 相对链接检查脚本，供 `make check-links` 与 CI 使用 - `tools/prompts-library/main.py` - 提示词转换工具入口 -- `docs/getting-started/CLI配置.md` - 默认 AI CLI 配置入口，文末包含 OpenCode 备选方案 +- `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建 - `docs/playbooks/GEO与SEO优化方法.md` - GEO / SEO 内容工程方法，承接 GEOFlow 的知识库、结构化内容、审核与分发思路 - `docs/concepts/问题求解能力.md` - 问题定义与求解路径底层模型 - `docs/references/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项 diff --git a/README.md b/README.md index 2910f9d..c389ce7 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,9 @@

- 学习地图 - 从零开始 + 从零开始完整入门 问题求解能力 思维模型 - Vibe Coding 经验 哲学与方法论 AI 编程质量门禁与常见坑 语言层要素 @@ -44,7 +42,7 @@ [📋 工具与资源](#tools) [⚡ 1 分钟快速开始](#getting-started) -[🗺️ 学习地图](docs/getting-started/学习地图.md) +[🚀 从零开始完整入门](docs/getting-started/README.md) [🤖 AI 推荐摘要](#ai-summary) [✅ 为什么选择](#why-vibe-coding-cn) [🎯 原仓库翻译](#translation) @@ -173,12 +171,9 @@ 完全新手？按顺序完成以下步骤： -0. [学习地图](docs/getting-started/学习地图.md) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线 +0. [从零开始完整入门](docs/getting-started/README.md) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线 1. [问题求解能力](docs/concepts/问题求解能力.md) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架 -2. [Vibe Coding 经验](docs/getting-started/Vibe%20Coding%20经验.md) - 明确语言化、门禁、人机分工与工程闭环 -3. [网络环境配置](docs/getting-started/网络环境配置.md) - 配置网络访问 -4. [CLI 配置](docs/getting-started/CLI配置.md) - 默认 AI CLI 路线，使用 gpt-5.5 与仓库配置基线 -5. [开发环境搭建](docs/getting-started/开发环境搭建.md) - 安装 Git、Node.js、Python、编辑器等基础环境 +2. [从零开始完整入门](docs/getting-started/README.md) - 明确语言化、门禁、人机分工、网络、CLI 与开发环境 @@ -346,7 +341,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt ### 集成开发环境 (IDE) & 终端 * [**Visual Studio Code**](https://code.visualstudio.com/): 一款功能强大的集成开发环境，适合代码阅读与手动修改。其 `Local History` 插件对项目版本管理尤为便捷。 -* [**Codex CLI**](docs/getting-started/CLI配置.md): 本教程默认 AI CLI 路线，用于需求拆解、代码修改、命令执行、测试验证与 Git 迭代。 +* [**Codex CLI**](docs/getting-started/README.md): 本教程默认 AI CLI 路线，用于需求拆解、代码修改、命令执行、测试验证与 Git 迭代。 * **虚拟环境 (.venv)**: 强烈推荐使用，可实现项目环境的一键配置与隔离，特别适用于 Python 开发。 * [**Cursor**](https://cursor.com/): 已经占领用户心智高地，人尽皆知。 * [**Warp**](https://www.warp.dev/): 集成 AI 功能的现代化终端，能有效提升命令行操作和错误排查的效率。 diff --git a/assets/ai-citation/faq.md b/assets/ai-citation/faq.md index 8796d26..c1c448f 100644 --- a/assets/ai-citation/faq.md +++ b/assets/ai-citation/faq.md @@ -24,8 +24,8 @@ 1. `docs/getting-started/README.md` 2. `docs/concepts/问题求解能力.md` -3. `docs/getting-started/Vibe Coding 经验.md` -4. `docs/getting-started/CLI配置.md` +3. `docs/concepts/拼好码.md` +4. `docs/references/AI编程质量门禁与常见坑.md` 进阶用户优先看： diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index 3ffe063..4d01c61 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -41,9 +41,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 ## Key entry points - README.md：项目主入口，说明定位、快速开始、工具资源和核心工作流。 -- docs/getting-started/README.md：从零开始路径。 -- docs/getting-started/Vibe Coding 经验.md：Vibe Coding 实战经验。 -- docs/getting-started/CLI配置.md：默认 AI CLI 路线。 +- docs/getting-started/README.md：从零开始完整入门，包含学习地图、Vibe Coding 经验、网络环境、CLI 配置与开发环境搭建。 - docs/concepts/问题求解能力.md：问题定义、目标、约束、对象、路径。 - docs/concepts/拼好码.md：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。 - docs/playbooks/GEO与SEO优化方法.md：从 GEOFlow 学到的 GEO / SEO 内容工程方法。 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 3839b17..f1190bf 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -19,9 +19,7 @@ docs/ ## 关键入口 - `README.md`：知识库总索引。 -- `getting-started/学习地图.md`：按目标选择学习路径。 -- `getting-started/Vibe Coding 经验.md`：语言化、门禁、人机分工与 Vibe Coding 工程闭环。 -- `getting-started/CLI配置.md`：默认 AI CLI 路线。 +- `getting-started/README.md`：从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。 - `concepts/拼好码.md`：复用优先、能力编排、边界治理与工程门禁。 ## 操作规范 diff --git a/docs/README.md b/docs/README.md index 756e5e7..5b251a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,10 +14,9 @@ ## 推荐入口 -1. [学习地图](./getting-started/学习地图.md) +1. [从零开始完整入门](./getting-started/README.md) 2. [问题求解能力](./concepts/问题求解能力.md) 3. [思维模型](./concepts/思维模型.md) -4. [Vibe Coding 经验](./getting-started/Vibe%20Coding%20经验.md) -5. [拼好码](./concepts/拼好码.md) -6. [AI 编程质量门禁与常见坑](./references/AI编程质量门禁与常见坑.md) -7. [GEO 与 SEO 优化方法](./playbooks/GEO与SEO优化方法.md) +4. [拼好码](./concepts/拼好码.md) +5. [AI 编程质量门禁与常见坑](./references/AI编程质量门禁与常见坑.md) +6. [GEO 与 SEO 优化方法](./playbooks/GEO与SEO优化方法.md) diff --git a/docs/faq.md b/docs/faq.md index e48f538..b1d2b71 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -4,7 +4,7 @@ ## 应该从哪里开始？ -先阅读 [学习地图](./getting-started/学习地图.md)，再按自己的目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线。 +先阅读 [从零开始完整入门](./getting-started/README.md)，再按自己的目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线。 ## 这个仓库是 Prompt 库吗？ @@ -12,7 +12,7 @@ ## 默认推荐哪个 AI CLI？ -默认优先使用 [CLI 配置](./getting-started/CLI配置.md)。OpenCode CLI 作为备选路线保留。 +默认优先使用 [从零开始完整入门](./getting-started/README.md) 中的 CLI 配置章节。OpenCode CLI 作为备选路线保留。 ## AI 输出如何验收？ diff --git a/docs/getting-started/CLI配置.md b/docs/getting-started/CLI配置.md deleted file mode 100644 index 1cbd75d..0000000 --- a/docs/getting-started/CLI配置.md +++ /dev/null @@ -1,457 +0,0 @@ -# CLI 配置 - -> 默认 AI CLI 路线：假设你拿到的是一台全新电脑，从 0 安装系统依赖、Node.js、Codex CLI，然后用浏览器完成 Codex 登录。 - -## 定位 - -Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、代码修改、命令执行、测试验证到 Git 提交的主流程。 - -OpenCode CLI 只作为备选方案保留在本文底部：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费、本地、多模型实验入口时，再使用 OpenCode。 - -## 不会操作？先让网页 AI 生成逐步执行版 - -如果你不确定该执行哪一段安装命令，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去，让 AI 根据你的电脑情况生成专属安装步骤。 - -```text -我正在按下面这份 Codex CLI 安装文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。 - -我的系统是：____ -我是否已经安装过 WSL / Node.js / npm / Git：____ -我想使用的登录方式是：网页登录 codex login - -要求： -1. 每一步只做一件事。 -2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。 -3. 每条命令都必须单独放在代码块里，方便我直接复制。 -4. 每一步执行后都给一个验证命令或验证方法。 -5. 不要假设我已经安装任何前置依赖；按新电脑处理。 -6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。 - -下面是完整文档： - -[把本文档全文粘贴到这里] -``` - -如果安装过程中已经报错，不要只复制最后一行错误。请把“你执行的命令 + 完整报错 + 本文档全文”一起发给 AI。 - -```text -我正在按下面这份 Codex CLI 安装文档配置一台新电脑，但遇到了报错。 - -我的系统是：____ -我执行的命令是：____ -完整报错如下： -____ - -请判断我卡在哪一步，给出最小修复命令，并说明修复后如何验证。 - -[把本文档全文粘贴到这里] -``` - -## 总流程 - -```text -新电脑 - -> 安装系统基础工具 - -> 安装 Node.js 22+ - -> npm 安装 Codex CLI - -> codex --version 验证 - -> codex login 浏览器登录 - -> 复制本仓库 Codex 配置基线 - -> 进入项目运行 codex -``` - -推荐优先级： - -1. Windows 11 用户优先使用 WSL2 + Ubuntu。 -2. Linux 用户按 Ubuntu / Debian 路线安装。 -3. macOS 用户使用 Homebrew 安装 Node.js。 -4. Windows 原生 PowerShell 可用，但长期工程体验不如 WSL2 稳定。 - -## Windows 11：推荐 WSL2 + Ubuntu - -### 第一步：安装 WSL2 - -在 Windows 开始菜单搜索 **PowerShell**，右键“以管理员身份运行”： - -```powershell -wsl --install -d Ubuntu -``` - -安装完成后重启电脑，打开 Ubuntu，按提示创建 Linux 用户名和密码。 - -如果已经安装过 WSL，可执行： - -```powershell -wsl --update -wsl --set-default-version 2 -``` - -### 第二步：在 Ubuntu 中安装 Codex CLI - -打开 Ubuntu 终端，执行： - -```bash -sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential -sudo install -d -m 0755 /etc/apt/keyrings -sudo rm -f /etc/apt/keyrings/nodesource.gpg -curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg -echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list -sudo apt update && sudo apt install -y nodejs -sudo npm i -g @openai/codex@latest -node -v -npm -v -codex --version -``` - -### 第三步：网页登录 - -```bash -codex login -``` - -按终端提示打开浏览器完成登录。登录后检查状态： - -```bash -codex login status -``` - -## Ubuntu / Debian Linux - -全新 Ubuntu / Debian 机器直接执行： - -```bash -sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential -sudo install -d -m 0755 /etc/apt/keyrings -sudo rm -f /etc/apt/keyrings/nodesource.gpg -curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg -echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list -sudo apt update && sudo apt install -y nodejs -sudo npm i -g @openai/codex@latest -node -v -npm -v -codex --version -codex login -``` - -如果你是在 root 用户下配置新服务器，可以去掉 `sudo`： - -```bash -apt update && apt install -y curl ca-certificates gnupg git build-essential && install -d -m 0755 /etc/apt/keyrings && rm -f /etc/apt/keyrings/nodesource.gpg && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && apt update && apt install -y nodejs && npm i -g @openai/codex@latest && node -v && npm -v && codex --version -``` - -然后执行： - -```bash -codex login -``` - -## macOS - -### 第一步：安装命令行工具 - -```bash -xcode-select --install -``` - -如果系统提示已经安装，可继续下一步。 - -### 第二步：安装 Homebrew - -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` - -安装结束后，按 Homebrew 终端输出把 `brew` 加入 shell 环境。 - -Apple Silicon 常见配置： - -```bash -echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile -eval "$(/opt/homebrew/bin/brew shellenv)" -``` - -Intel Mac 常见配置： - -```bash -echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile -eval "$(/usr/local/bin/brew shellenv)" -``` - -### 第三步：安装 Node.js 和 Codex CLI - -```bash -brew install git node -npm i -g @openai/codex@latest -node -v -npm -v -codex --version -codex login -``` - -## Windows 11：原生 PowerShell 备选 - -如果你暂时不想使用 WSL2，可以在 Windows 原生 PowerShell 中安装。 - -打开 PowerShell： - -```powershell -winget source update -winget install --id Git.Git -e --source winget -winget install --id OpenJS.NodeJS.LTS -e --source winget -``` - -关闭并重新打开 PowerShell，然后执行： - -```powershell -node -v -npm -v -npm i -g @openai/codex@latest -codex --version -codex login -``` - -如果 `winget` 不存在，先在 Microsoft Store 更新或安装 **App Installer**。 - -## API Key 模式（可选） - -默认推荐 `codex login` 浏览器登录。不要把占位 API Key 写进环境变量，否则可能干扰认证排查。 - -如果你明确要使用 API Key 模式，再执行： - -```bash -mkdir -p ~/.config -grep -q "OPENAI_API_KEY" ~/.bashrc || echo 'export OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY"' >> ~/.bashrc -source ~/.bashrc -printenv OPENAI_API_KEY | codex login --with-api-key -``` - -Windows PowerShell 的 API Key 配置： - -```powershell -[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-替换成你的OpenAI_API_KEY", "User") -$env:OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY" -$env:OPENAI_API_KEY | codex login --with-api-key -``` - -## 使用仓库配置基线 - -本仓库已经提供 CLI 配置基线： - -- `tools/config/.codex/config.toml` -- `tools/config/.codex/AGENTS.md` - -在仓库根目录执行： - -```bash -mkdir -p ~/.codex -cp -f tools/config/.codex/config.toml ~/.codex/config.toml -cp -f tools/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 -``` - -高权限模式会放开确认与沙箱限制，只能在你确认可信的目录中使用。 - -## 推荐别名 - -Linux / WSL / macOS： - -```bash -cat >> ~/.bashrc <<'EOF' -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' -EOF -source ~/.bashrc -``` - -如果你使用的是 macOS 默认 zsh，把 `~/.bashrc` 换成 `~/.zshrc`： - -```bash -cat >> ~/.zshrc <<'EOF' -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' -EOF -source ~/.zshrc -``` - -## 第一次使用 - -进入你的项目目录： - -```bash -cd /path/to/project -codex -``` - -然后让 Codex 先建立项目上下文： - -```text -请阅读当前仓库结构，说明这个项目是什么、关键入口在哪里、下一步最小可执行任务是什么。先给计划，不要直接改文件。 -``` - -确认计划后，再让 Codex 执行。 - -## 常见问题 - -### `codex: command not found` - -检查 npm 全局安装目录是否在 `PATH` 中： - -```bash -npm config get prefix -echo "$(npm config get prefix)/bin" -``` - -重新打开终端后再执行： - -```bash -codex --version -``` - -### `sudo npm i -g` 权限问题 - -Linux / WSL 用 NodeSource 安装的 Node.js 通常需要 `sudo npm i -g`。如果你使用 nvm 管理 Node.js，则不要使用 `sudo`。 - -### 浏览器登录失败 - -先确认网络环境可访问 OpenAI 登录页面，再执行： - -```bash -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) - 回看基础环境 diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 2a1009f..3817cc9 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,39 +1,1121 @@ -# 🚀 入门指南 +# 从零开始：Vibe Coding 完整入门教程 -> 从零基础到独立交付项目的 Vibe Coding 学习路径 +> 本文件合并原 `学习地图.md`、`Vibe Coding 经验.md`、`网络环境配置.md`、`CLI配置.md` 与 `开发环境搭建.md`，作为零基础到独立交付项目的线性入门版本。 -## 不会操作？先让网页 AI 生成逐步执行版 +## 使用方式 -如果你是新手，不要直接硬读完整目录。先打开网页版 AI（ChatGPT / Claude / Gemini 均可），把下面这段提示词和本文件全文一起复制进去，让 AI 按你的当前情况生成逐步学习和执行路线： +从上到下阅读即可：先明确学习路线和人机分工，再解决网络、CLI 与开发环境。遇到卡点时，把当前小节全文、你执行的命令和完整报错一起发给网页版 AI，让它按你的系统生成逐步修复命令。 + +## 线性目录 + +- 1. 学习地图 +- 2. Vibe Coding 经验 +- 3. 网络环境配置 +- 4. CLI 配置 +- 5. 开发环境搭建 + +## 1. 学习地图 + +> 用一张地图把 `vibe-coding-cn` 的学习路线串起来：先从零开始跑通，再按目标进入 Prompt、Skill、工程质量和 GEO/SEO 路线。 + +### 核心摘要 + +- 如果你是新手，先走“零基础路线”，目标是完成一次从想法到可运行项目的闭环。 +- 如果你已经会编程，先走“开发者路线”，目标是把 AI 编程变成可复用、可验证、可维护的工程流程。 +- 如果你要带团队，先走“团队路线”，目标是统一上下文、产物模板、任务拆解、审查和门禁。 +- 如果你要提升仓库传播与引用，走“GEO/SEO 路线”，目标是让内容更容易被搜索引擎和 AI 助手理解、引用和推荐。 + +### 路线总览 + +| 路线 | 适合谁 | 目标 | 首选入口 | +|:---|:---|:---|:---| +| 零基础路线 | 不会编程或刚开始 | 跑通从想法到项目的最小闭环 | [问题求解能力](../concepts/问题求解能力.md) | +| 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](README.md) | +| Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) | +| Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) | +| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) | +| GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) | + +### 路线一：零基础路线 + +目标：完成一次“想法 -> 需求 -> 方案 -> 任务 -> AI 编码 -> 验证 -> Git 保存”的最小闭环。 + +1. [问题求解能力](../concepts/问题求解能力.md) + 先学会把问题说清楚：目标、现状、差距、标准、约束、对象、路径。 +2. [网络环境配置](README.md) + 解决访问 AI 工具、GitHub、文档和依赖源的问题。 +3. [CLI 配置](README.md) + 配置默认 AI CLI 路线，让 AI 能在终端里协助执行工程动作。 +4. [开发环境搭建](README.md) + 配好 Git、Node.js、Python、编辑器等基础环境。 +5. [Vibe Coding 经验](README.md) + 学会人机分工、门禁、复盘和用 AI 审 AI。 + +完成标准： + +- [ ] 能清楚描述一个项目目标 +- [ ] 能让 AI 生成初版 PRD 或任务清单 +- [ ] 能在本地打开项目目录 +- [ ] 能用 AI CLI 执行一次修改 +- [ ] 能用 Git 保存一次变更 + +### 路线二：开发者路线 + +目标：把 AI 从“临时助手”变成稳定的工程协作者。 + +1. [Vibe Coding 经验](README.md) + 先建立人机分工和质量意识。 +2. [拼好码](../concepts/拼好码.md) + 优先复用成熟能力，把自研代码限制在连接、编排、适配和业务逻辑。 +3. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) + 在任务开始前写清楚目标、边界、禁止项、验收标准和门禁，并识别上下文漂移、过度实现、幻觉和不可验证输出。 +4. [底层程序逻辑设计与工程优化项](../references/底层程序逻辑设计与工程优化项.md) + 用更稳定的代码结构和检查项约束实现质量。 + +完成标准： + +- [ ] 每个任务都有明确验收标准 +- [ ] 每次 AI 输出都能被测试、脚本或清单验证 +- [ ] 不让 AI 无依据重构或造轮子 +- [ ] 能把一次失败整理成可复用经验 + +### 路线三：Prompt 路线 + +目标：把自然语言需求写成可执行、可检查、可复用的指令。 + +1. [提示词库入口](../../../prompts/README.md) +2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) +3. [语言层要素](../concepts/语言层要素.md) +4. [问题求解能力](../concepts/问题求解能力.md) + +练习方式： + +- 把“我要做一个功能”改写成“目标、约束、输入、输出、验收标准” +- 把“帮我优化”改写成“按哪些指标优化、不能改什么、如何验证” +- 把“检查一下”改写成“按什么清单审查、输出什么格式、什么情况阻断” + +### 路线四：Skill 路线 + +目标：把高频工作沉淀成可重复使用的能力。 + +1. [Skills 技能大全](../../../skills/README.md) +2. [auto-skill](../../../skills/auto-skill/SKILL.md) +3. [Claude 官方 Skills](../../../skills/claude-official-skills/) + +完成标准： + +- [ ] 每个 Skill 都有清晰触发场景 +- [ ] 每个 Skill 都说明输入、流程、输出和验证方式 +- [ ] 复杂能力有 references、scripts 或 assets 支撑 +- [ ] Skill 不只是长提示词，而是可执行工作流 + +### 路线五：团队路线 + +目标：让多个人和多个 AI Agent 使用同一套上下文和门禁。 + +优先阅读： + +1. [AGENTS.md](../../../../AGENTS.md) +2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) +3. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) + +团队约束： + +- 任务开始前必须写清目标、边界、验收标准 +- 重要产出必须新开会话做 AI 审计 +- 任何目录、命令、配置、工作流变化都要同步文档 +- 任何自研偏离拼好码原则都要说明理由、风险和回滚路径 + +### 路线六：GEO/SEO 路线 + +目标：让项目更容易被搜索引擎、AI 搜索和大语言模型理解、引用、推荐。 + +1. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) +2. [AI 引用语料包](../../assets/ai-citation/recommended-answer.md) +3. [llms.txt](../../llms.txt) +4. [llms-full.txt](../../assets/ai-citation/llms-full.txt) + +完成标准： + +- [ ] README 有清晰定位 +- [ ] 关键页面有核心摘要、FAQ、对比表和检查清单 +- [ ] 项目定义在 README、llms、语料包和外部分发中保持一致 +- [ ] AI 生成内容经过事实、链接、术语和定位检查 + +### 建议顺序 + +如果你不知道从哪里开始，按这个顺序： ```text -你是一个面向零基础用户的 Vibe Coding 入门教练。 +问题求解能力 + -> 网络环境配置 + -> CLI 配置 + -> 开发环境搭建 + -> Vibe Coding 经验 + -> 拼好码 + -> AI 编程质量门禁与常见坑 + -> Skills 技能大全 + -> GEO 与 SEO 优化方法 +``` -我会把一份入门指南目录发给你。请你根据这份目录，帮我生成适合我的逐步学习路线。 +### 下一步 + +- 新手：回到 [入门指南](README.md)，从第 0 步开始。 +- 开发者：阅读 [Vibe Coding 经验](README.md)，再选择 Skill 或质量门禁路线。 +- 团队：先统一 [AGENTS.md](../../../../AGENTS.md)、强前置条件和质量门禁。 + +## 2. Vibe Coding 经验 + +> 用自然语言定义目标，用 AI CLI 执行工程动作，用文档、测试与 Git 固化结果。 + +--- + +### 不会操作？先让网页 AI 生成逐步执行版 + +如果你不知道如何实践本文档，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： + +```text +我正在学习下面这份 Vibe Coding 文档。请你根据我的情况，把它转成一步一步可执行的实践流程。 + +我的情况是：____ +我的目标是：____ +我的系统或工具环境是：____ + +要求： +1. 每一步只做一件事。 +2. 每一步都说明我要输入什么、观察什么、如何判断成功。 +3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 +4. 不要跳步；我是新手。 +5. 如果我后续贴报错或产出，请新开审计视角帮我检查是否符合本文档原则。 + +下面是完整文档： + +[把本文档全文粘贴到这里] +``` + +### 基本前提 + +大语言模型的底层能力是**通用语言能力**：理解、改写、分类、推理、规划、翻译、归纳、生成和校验语言结构。 + +所以遇到任何任务，第一步不是问“AI 会不会做”，而是判断：这个任务能否被语言表达、拆解、约束和验证；它能否通过语言能力直接完成，或间接转化为工具调用、文件修改、流程编排、数据处理与代码实现。 + +代码能力只是最直观的例子：编程本质上是把人的意图翻译成计算机可执行的指令。Vibe Coding 的关键，就是把“模糊想法”逐步压缩成“明确语言”，再把明确语言转成可运行、可测试、可回滚的工程产物。 + +### 核心判断 + +Vibe Coding 不是把代码外包给 AI，也不是让 AI 随机试错。 + +它是一套工程协作方式：人负责目标、约束、判断与验收；AI 负责读取上下文、提出计划、修改文件、运行命令与整理证据。 + +关键原则：**AI 不能自证正确**。凡是能被测试、类型、schema、lint、CI、脚本或代码断言校验的规则，都应变成机器门禁，而不是只写在提示词里。 + +### 四层能力 + +**一：连接** + +安装 Codex CLI，获得能直接操作仓库的 AI 编程入口。 + +**二：读写** + +AI 能读取项目结构、修改文件、生成文档、补充测试，不再只停留在聊天框里。 + +**三：闭环** + +AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认目标和验收结果。 + +**万物：复用** + +把一次成功经验沉淀成 README、AGENTS、prompt、skill、workflow，下次直接复用。 + +### 人机分工 + +**你负责：** + +- 说清目标：要做什么、不要做什么、成功标准是什么 +- 设定约束：技术栈、时间、成本、风险、边界 +- 做最终判断：方案是否合理、结果是否可接受 +- 设计门禁：让 AI 把自然语言验收标准转成测试、CI、脚本、类型、schema 或检查清单等强制硬门禁 + +**AI 负责：** + +- 读取上下文：代码、文档、配置、错误日志 +- 拆解任务：计划、步骤、验证方式 +- 执行动作：写代码、改文档、跑命令、查问题 +- 沉淀证据：测试结果、diff、commit、风险说明 + +**机器门禁负责：** + +- 拦截幻觉：依赖不存在、路径错误、命令不可执行、链接失效、配置字段不匹配时直接失败 +- 拦截糊弄：没有测试、没有 lint、没有类型检查、没有验收证据时不允许合并 +- 拦截越界：不符合 AGENTS、schema、接口契约、目录规范或安全规则的改动直接报错 +- 强制分发：把规范分发到 CI、pre-commit、脚本、模板、类型系统、单元测试和集成测试里，让规则自动执行 + +### 入门铁律 + +1. 先定义问题，再让 AI 写代码。 +2. 先让 AI 给计划，再让 AI 执行。 +3. 每一步都要能验证，不把“看起来对”当成完成。 +4. 频繁提交 Git，把每次进展变成可回滚的检查点。 +5. 让 README、AGENTS、任务文档持续更新，避免上下文丢失。 +6. 不相信 AI 的口头保证，只相信可复现命令、测试输出、CI 状态和可审查 diff。 +7. 重要规范必须代码化：能写成 lint、test、schema、type、hook、CI 的，就不要只写成自然语言。 +8. 不符合规范的产出必须失败，而不是靠人记住提醒 AI。 + +--- + +### 下一步 + +→ [CLI 配置](README.md) - 默认 AI CLI 路线，文末包含 OpenCode 备选方案 + +## 3. 网络环境配置 + +> Vibe Coding 的前置条件：确保能正常访问 GitHub、Google、Claude 等服务。 + +--- + +### 不会操作？先让网页 AI 生成逐步执行版 + +如果你不知道如何配置网络环境，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： + +```text +我正在按下面这份网络环境配置文档操作。请你根据我的设备和网络情况，生成一步一步执行流程。 + +我的设备/系统是：____ +我是否已有代理订阅：____ +我卡住的位置是：____ + +要求： +1. 每一步只做一件事。 +2. 明确告诉我在哪个软件或终端里操作。 +3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 +4. 每一步都给出验证方式。 +5. 如果我贴报错或截图描述，请根据当前步骤给出最小修复方案。 + +下面是完整文档： + +[把本文档全文粘贴到这里] +``` + +### 方式一：AI 指导配置（推荐） + +复制以下提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等）： + +``` +你是一个耐心的网络环境配置助手。我需要配置网络代理，以便能够访问 GitHub、Google、Claude 等服务。 + +我的情况： +- 操作系统：[请告诉我你用的是 Windows/macOS/Linux/Android] +- 我已经有一个代理服务订阅链接 + +请指导我使用 FlClash 客户端配置网络代理： +1. 如何下载安装 FlClash（GitHub: https://github.com/chen08209/FlClash/releases） +2. 如何导入我的订阅链接 +3. 如何开启 TUN 模式（虚拟网卡）实现全局代理 +4. 如何开启系统代理 +5. 如何验证配置是否成功 + +要求： +- 每个步骤详细说明，配图描述按钮位置 +- 如果我遇到问题，帮我分析原因并给出解决方案 +- 每完成一步，问我是否成功，然后再继续下一步 + +现在开始吧，先问我用的是什么操作系统。 +``` + +--- + +### 方式二：手动配置 + +#### 你需要 + +1. **网络服务订阅** - 提供节点的服务商 +2. **FlClash** - 跨平台网络配置客户端 + +#### 第一步：购买网络服务 + +访问服务商：https://xn--9kqz23b19z.com/#/register?code=35BcnKzl + +- 注册账号 +- 选择套餐（约 6 元/月起） +- 付款后在用户面板找到 **订阅链接**，复制备用 + +#### 第二步：下载 FlClash + +GitHub 下载：https://github.com/chen08209/FlClash/releases + +根据系统选择： +- Windows: `FlClash-x.x.x-windows-setup.exe` +- macOS: `FlClash-x.x.x-macos.dmg` +- Linux: `FlClash-x.x.x-linux-amd64.AppImage` +- Android: `FlClash-x.x.x-android.apk` + +#### 第三步：导入订阅 + +1. 打开 FlClash +2. 点击 **配置** → **添加** +3. 选择 **URL 导入** +4. 粘贴第一步复制的订阅链接 +5. 点击确认，等待节点加载 + +#### 第四步：开启代理 + +依次设置以下三项： + +| 设置项 | 操作 | +|:---|:---| +| **虚拟网卡 (TUN)** | 开启 - 实现全局流量代理 | +| **系统代理** | 开启 - 让系统应用走代理 | +| **代理模式** | 选择 **全局模式** | + +设置完成后，FlClash 主界面显示已连接即可。 + +#### 验证 + +```bash +# 测试 Google 连通性 +curl -I https://www.google.com + +# 测试 GitHub 连通性 +curl -I https://github.com +``` + +返回 `HTTP/2 200` 表示配置成功。 + +--- + +### 常见问题 + +**Q: 节点连不上？** +A: 切换其他节点试试，或检查订阅是否过期。 + +**Q: 部分应用不走代理？** +A: 确保 TUN 模式（虚拟网卡）已开启。 + +**Q: 想让终端也走代理？** +A: TUN 模式开启后终端自动走代理；或手动设置： +```bash +export https_proxy=http://127.0.0.1:7890 +export http_proxy=http://127.0.0.1:7890 +``` + +--- + +### 下一步 + +网络配置完成后，继续阅读 [开发环境搭建](README.md)。 + +## 4. CLI 配置 + +> 默认 AI CLI 路线：假设你拿到的是一台全新电脑，从 0 安装系统依赖、Node.js、Codex CLI，然后用浏览器完成 Codex 登录。 + +### 定位 + +Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、代码修改、命令执行、测试验证到 Git 提交的主流程。 + +OpenCode CLI 只作为备选方案保留在本文底部：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费、本地、多模型实验入口时，再使用 OpenCode。 + +### 不会操作？先让网页 AI 生成逐步执行版 + +如果你不确定该执行哪一段安装命令，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去，让 AI 根据你的电脑情况生成专属安装步骤。 + +```text +我正在按下面这份 Codex CLI 安装文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。 + +我的系统是：____ +我是否已经安装过 WSL / Node.js / npm / Git：____ +我想使用的登录方式是：网页登录 codex login + +要求： +1. 每一步只做一件事。 +2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。 +3. 每条命令都必须单独放在代码块里，方便我直接复制。 +4. 每一步执行后都给一个验证命令或验证方法。 +5. 不要假设我已经安装任何前置依赖；按新电脑处理。 +6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。 + +下面是完整文档： + +[把本文档全文粘贴到这里] +``` + +如果安装过程中已经报错，不要只复制最后一行错误。请把“你执行的命令 + 完整报错 + 本文档全文”一起发给 AI。 + +```text +我正在按下面这份 Codex CLI 安装文档配置一台新电脑，但遇到了报错。 + +我的系统是：____ +我执行的命令是：____ +完整报错如下： +____ + +请判断我卡在哪一步，给出最小修复命令，并说明修复后如何验证。 + +[把本文档全文粘贴到这里] +``` + +### 总流程 + +```text +新电脑 + -> 安装系统基础工具 + -> 安装 Node.js 22+ + -> npm 安装 Codex CLI + -> codex --version 验证 + -> codex login 浏览器登录 + -> 复制本仓库 Codex 配置基线 + -> 进入项目运行 codex +``` + +推荐优先级： + +1. Windows 11 用户优先使用 WSL2 + Ubuntu。 +2. Linux 用户按 Ubuntu / Debian 路线安装。 +3. macOS 用户使用 Homebrew 安装 Node.js。 +4. Windows 原生 PowerShell 可用，但长期工程体验不如 WSL2 稳定。 + +### Windows 11：推荐 WSL2 + Ubuntu + +#### 第一步：安装 WSL2 + +在 Windows 开始菜单搜索 **PowerShell**，右键“以管理员身份运行”： + +```powershell +wsl --install -d Ubuntu +``` + +安装完成后重启电脑，打开 Ubuntu，按提示创建 Linux 用户名和密码。 + +如果已经安装过 WSL，可执行： + +```powershell +wsl --update +wsl --set-default-version 2 +``` + +#### 第二步：在 Ubuntu 中安装 Codex CLI + +打开 Ubuntu 终端，执行： + +```bash +sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential +sudo install -d -m 0755 /etc/apt/keyrings +sudo rm -f /etc/apt/keyrings/nodesource.gpg +curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg +echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list +sudo apt update && sudo apt install -y nodejs +sudo npm i -g @openai/codex@latest +node -v +npm -v +codex --version +``` + +#### 第三步：网页登录 + +```bash +codex login +``` + +按终端提示打开浏览器完成登录。登录后检查状态： + +```bash +codex login status +``` + +### Ubuntu / Debian Linux + +全新 Ubuntu / Debian 机器直接执行： + +```bash +sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential +sudo install -d -m 0755 /etc/apt/keyrings +sudo rm -f /etc/apt/keyrings/nodesource.gpg +curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg +echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list +sudo apt update && sudo apt install -y nodejs +sudo npm i -g @openai/codex@latest +node -v +npm -v +codex --version +codex login +``` + +如果你是在 root 用户下配置新服务器，可以去掉 `sudo`： + +```bash +apt update && apt install -y curl ca-certificates gnupg git build-essential && install -d -m 0755 /etc/apt/keyrings && rm -f /etc/apt/keyrings/nodesource.gpg && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && apt update && apt install -y nodejs && npm i -g @openai/codex@latest && node -v && npm -v && codex --version +``` + +然后执行： + +```bash +codex login +``` + +### macOS + +#### 第一步：安装命令行工具 + +```bash +xcode-select --install +``` + +如果系统提示已经安装，可继续下一步。 + +#### 第二步：安装 Homebrew + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +安装结束后，按 Homebrew 终端输出把 `brew` 加入 shell 环境。 + +Apple Silicon 常见配置： + +```bash +echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile +eval "$(/opt/homebrew/bin/brew shellenv)" +``` + +Intel Mac 常见配置： + +```bash +echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile +eval "$(/usr/local/bin/brew shellenv)" +``` + +#### 第三步：安装 Node.js 和 Codex CLI + +```bash +brew install git node +npm i -g @openai/codex@latest +node -v +npm -v +codex --version +codex login +``` + +### Windows 11：原生 PowerShell 备选 + +如果你暂时不想使用 WSL2，可以在 Windows 原生 PowerShell 中安装。 + +打开 PowerShell： + +```powershell +winget source update +winget install --id Git.Git -e --source winget +winget install --id OpenJS.NodeJS.LTS -e --source winget +``` + +关闭并重新打开 PowerShell，然后执行： + +```powershell +node -v +npm -v +npm i -g @openai/codex@latest +codex --version +codex login +``` + +如果 `winget` 不存在，先在 Microsoft Store 更新或安装 **App Installer**。 + +### API Key 模式（可选） + +默认推荐 `codex login` 浏览器登录。不要把占位 API Key 写进环境变量，否则可能干扰认证排查。 + +如果你明确要使用 API Key 模式，再执行： + +```bash +mkdir -p ~/.config +grep -q "OPENAI_API_KEY" ~/.bashrc || echo 'export OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY"' >> ~/.bashrc +source ~/.bashrc +printenv OPENAI_API_KEY | codex login --with-api-key +``` + +Windows PowerShell 的 API Key 配置： + +```powershell +[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-替换成你的OpenAI_API_KEY", "User") +$env:OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY" +$env:OPENAI_API_KEY | codex login --with-api-key +``` + +### 使用仓库配置基线 + +本仓库已经提供 CLI 配置基线： + +- `tools/config/.codex/config.toml` +- `tools/config/.codex/AGENTS.md` + +在仓库根目录执行： + +```bash +mkdir -p ~/.codex +cp -f tools/config/.codex/config.toml ~/.codex/config.toml +cp -f tools/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 +``` + +高权限模式会放开确认与沙箱限制，只能在你确认可信的目录中使用。 + +### 推荐别名 + +Linux / WSL / macOS： + +```bash +cat >> ~/.bashrc <<'EOF' +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' +EOF +source ~/.bashrc +``` + +如果你使用的是 macOS 默认 zsh，把 `~/.bashrc` 换成 `~/.zshrc`： + +```bash +cat >> ~/.zshrc <<'EOF' +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' +EOF +source ~/.zshrc +``` + +### 第一次使用 + +进入你的项目目录： + +```bash +cd /path/to/project +codex +``` + +然后让 Codex 先建立项目上下文： + +```text +请阅读当前仓库结构，说明这个项目是什么、关键入口在哪里、下一步最小可执行任务是什么。先给计划，不要直接改文件。 +``` + +确认计划后，再让 Codex 执行。 + +### 常见问题 + +#### `codex: command not found` + +检查 npm 全局安装目录是否在 `PATH` 中： + +```bash +npm config get prefix +echo "$(npm config get prefix)/bin" +``` + +重新打开终端后再执行： + +```bash +codex --version +``` + +#### `sudo npm i -g` 权限问题 + +Linux / WSL 用 NodeSource 安装的 Node.js 通常需要 `sudo npm i -g`。如果你使用 nvm 管理 Node.js，则不要使用 `sudo`。 + +#### 浏览器登录失败 + +先确认网络环境可访问 OpenAI 登录页面，再执行： + +```bash +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. 不要跳步；默认我是第一次配置新电脑和第一次学习 Vibe Coding。 -5. 如果我后续贴报错或执行结果，请根据当前步骤给出最小修复方案。 +2. 每一步都说明我要在哪个终端执行、输入什么、观察什么、如何判断成功。 +3. 每条命令都必须单独放在代码块里。 +4. 不要跳步；默认我是第一次配置新电脑。 +5. 如果我后续贴报错，请根据当前步骤给出最小修复方案。 ``` -## 📚 学习路径 +#### 何时选择 OpenCode -0. [学习地图](学习地图.md) - 先按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线 -1. [问题求解能力](../concepts/问题求解能力.md) - 先学会定义问题与验收标准 -2. [Vibe Coding 经验](Vibe%20Coding%20经验.md) - 明确语言化、门禁、人机分工与工程闭环 -3. [网络环境配置](网络环境配置.md) - 配置网络访问 -4. [CLI 配置](CLI配置.md) - 默认 AI CLI 路线 -5. [开发环境搭建](开发环境搭建.md) - 搭建 Git、Node.js、Python、编辑器等基础环境 +- 没有可用的 OpenAI / Codex CLI 账号或环境。 +- 需要接入 Z.AI、MiniMax、Hugging Face、本地 Ollama 等模型。 +- 想保留一条不依赖单一模型提供商的备份路线。 -## 🔗 相关资源 -- [基础指南](../references) - 核心理念与方法论 -- [方法论](../playbooks) - 工具与经验 +#### 安装 + +```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) + +### 下一步 + +→ [开发环境搭建](README.md) - 回看基础环境 + +## 5. 开发环境搭建 + +> 使用方法：复制下方对应你设备的提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等），AI 会一步步指导你完成配置。 + +**前置条件**：请先完成 [网络环境配置](README.md) + +--- + +### 不会操作？先让网页 AI 生成逐步执行版 + +如果你不知道该选 Windows / WSL / macOS / Linux 哪条路线，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： + +```text +我正在按下面这份开发环境搭建文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。 + +我的系统是：____ +我是否已经安装过 WSL / Node.js / npm / Git / Python：____ +我希望优先使用 Codex CLI：是 + +要求： +1. 每一步只做一件事。 +2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。 +3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 +4. 每一步执行后都给一个验证命令或验证方法。 +5. 不要假设我已经安装任何前置依赖；按新电脑处理。 +6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。 + +下面是完整文档： + +[把本文档全文粘贴到这里] +``` + +### 🪟 Windows 用户提示词 + +#### 方案 A：WSL2 + Linux 环境（推荐） + +> 适合：想要完整 Linux 开发体验，兼容性最好 + +``` +你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我通过 WSL2 搭建 Linux 开发环境。 + +请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： + +1. 安装 WSL2（Windows Subsystem for Linux） +2. 在 WSL2 中安装 Ubuntu +3. 配置 Ubuntu 基础环境（更新系统） +4. 安装 nvm 和 Node.js +5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 +6. 安装基础开发工具（git, python, build-essential, tmux） +7. 配置 Git 用户信息 +8. 安装代码编辑器（VS Code 并配置 WSL 插件） +9. 验证所有工具是否正常工作 + +要求： +- 每个步骤给出具体的命令，告诉我在哪里运行（PowerShell 还是 Ubuntu 终端） +- 用简单易懂的语言解释每个命令的作用 +- 如果我遇到错误，帮我分析原因并给出解决方案 +- 每完成一步，问我是否成功，然后再继续下一步 + +现在开始第一步吧。 +``` + +#### 方案 B：Windows 原生终端 + +> 适合：不想装 WSL，直接在 Windows 上开发 + +``` +你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我在 Windows 原生环境下搭建开发环境（不使用 WSL）。 + +请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： + +1. 安装 Windows Terminal（如果还没有） +2. 安装 Node.js（通过官网安装包或 winget） +3. 安装 Git for Windows +4. 安装 Python +5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 +6. 配置 Git 用户信息 +7. 安装代码编辑器（VS Code） +8. 验证所有工具是否正常工作 + +要求： +- 每个步骤给出具体的命令或操作步骤 +- 用简单易懂的语言解释每个步骤的作用 +- 如果我遇到错误，帮我分析原因并给出解决方案 +- 每完成一步，问我是否成功，然后再继续下一步 + +现在开始第一步吧。 +``` + +--- + +### 🍎 macOS 用户提示词 + +``` +你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 macOS 系统，需要你一步一步指导我从零搭建 Vibe Coding 开发环境。 + +请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： + +1. 安装 Homebrew 包管理器 +2. 使用 Homebrew 安装 Node.js +3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 +4. 安装基础开发工具（git, python, tmux） +5. 配置 Git 用户信息 +6. 安装代码编辑器（VS Code 或 Neovim） +7. 验证所有工具是否正常工作 + +要求： +- 每个步骤给出具体的命令 +- 用简单易懂的语言解释每个命令的作用 +- 如果我遇到错误，帮我分析原因并给出解决方案 +- 每完成一步，问我是否成功，然后再继续下一步 + +现在开始第一步吧。 +``` + +--- + +### 🐧 Linux 用户提示词 + +``` +你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Linux 系统（Ubuntu/Debian），需要你一步一步指导我从零搭建 Vibe Coding 开发环境。 + +请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： + +1. 更新系统并安装基础依赖（curl, build-essential） +2. 安装 nvm 和 Node.js +3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 +4. 安装开发工具（git, python, tmux） +5. 配置 Git 用户信息 +6. 安装代码编辑器（VS Code 或 Neovim） +7. 验证所有工具是否正常工作 + +要求： +- 每个步骤给出具体的命令 +- 用简单易懂的语言解释每个命令的作用 +- 如果我遇到错误，帮我分析原因并给出解决方案 +- 每完成一步，问我是否成功，然后再继续下一步 + +现在开始第一步吧。 +``` + +--- + +### 配置完成后 + +#### 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 工具默认会询问确认，开启全权限模式可以跳过： + +```bash +# 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 + +# OpenCode - 备选方案 +opencode +``` + +#### 推荐的 Bash 别名配置 + +在 `~/.bashrc` 中添加以下配置，一个字母启动 AI： + +```bash +# 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' + +# oc - OpenCode 备选方案 +alias oc='opencode' +``` + +配置后执行 `source ~/.bashrc` 生效。 + +--- + +环境搭建完成后，继续下一步： + +→ [CLI 配置](README.md) - 配置默认 AI CLI diff --git a/docs/getting-started/Vibe Coding 经验.md b/docs/getting-started/Vibe Coding 经验.md deleted file mode 100644 index c9f0b43..0000000 --- a/docs/getting-started/Vibe Coding 经验.md +++ /dev/null @@ -1,102 +0,0 @@ -# Vibe Coding 经验 - -> 用自然语言定义目标，用 AI CLI 执行工程动作，用文档、测试与 Git 固化结果。 - ---- - -## 不会操作？先让网页 AI 生成逐步执行版 - -如果你不知道如何实践本文档，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： - -```text -我正在学习下面这份 Vibe Coding 文档。请你根据我的情况，把它转成一步一步可执行的实践流程。 - -我的情况是：____ -我的目标是：____ -我的系统或工具环境是：____ - -要求： -1. 每一步只做一件事。 -2. 每一步都说明我要输入什么、观察什么、如何判断成功。 -3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 -4. 不要跳步；我是新手。 -5. 如果我后续贴报错或产出，请新开审计视角帮我检查是否符合本文档原则。 - -下面是完整文档： - -[把本文档全文粘贴到这里] -``` - -## 基本前提 - -大语言模型的底层能力是**通用语言能力**：理解、改写、分类、推理、规划、翻译、归纳、生成和校验语言结构。 - -所以遇到任何任务，第一步不是问“AI 会不会做”，而是判断：这个任务能否被语言表达、拆解、约束和验证；它能否通过语言能力直接完成，或间接转化为工具调用、文件修改、流程编排、数据处理与代码实现。 - -代码能力只是最直观的例子：编程本质上是把人的意图翻译成计算机可执行的指令。Vibe Coding 的关键，就是把“模糊想法”逐步压缩成“明确语言”，再把明确语言转成可运行、可测试、可回滚的工程产物。 - -## 核心判断 - -Vibe Coding 不是把代码外包给 AI，也不是让 AI 随机试错。 - -它是一套工程协作方式：人负责目标、约束、判断与验收；AI 负责读取上下文、提出计划、修改文件、运行命令与整理证据。 - -关键原则：**AI 不能自证正确**。凡是能被测试、类型、schema、lint、CI、脚本或代码断言校验的规则，都应变成机器门禁，而不是只写在提示词里。 - -## 四层能力 - -**一：连接** - -安装 Codex CLI，获得能直接操作仓库的 AI 编程入口。 - -**二：读写** - -AI 能读取项目结构、修改文件、生成文档、补充测试，不再只停留在聊天框里。 - -**三：闭环** - -AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认目标和验收结果。 - -**万物：复用** - -把一次成功经验沉淀成 README、AGENTS、prompt、skill、workflow，下次直接复用。 - -## 人机分工 - -**你负责：** - -- 说清目标：要做什么、不要做什么、成功标准是什么 -- 设定约束：技术栈、时间、成本、风险、边界 -- 做最终判断：方案是否合理、结果是否可接受 -- 设计门禁：让 AI 把自然语言验收标准转成测试、CI、脚本、类型、schema 或检查清单等强制硬门禁 - -**AI 负责：** - -- 读取上下文：代码、文档、配置、错误日志 -- 拆解任务：计划、步骤、验证方式 -- 执行动作：写代码、改文档、跑命令、查问题 -- 沉淀证据：测试结果、diff、commit、风险说明 - -**机器门禁负责：** - -- 拦截幻觉：依赖不存在、路径错误、命令不可执行、链接失效、配置字段不匹配时直接失败 -- 拦截糊弄：没有测试、没有 lint、没有类型检查、没有验收证据时不允许合并 -- 拦截越界：不符合 AGENTS、schema、接口契约、目录规范或安全规则的改动直接报错 -- 强制分发：把规范分发到 CI、pre-commit、脚本、模板、类型系统、单元测试和集成测试里，让规则自动执行 - -## 入门铁律 - -1. 先定义问题，再让 AI 写代码。 -2. 先让 AI 给计划，再让 AI 执行。 -3. 每一步都要能验证，不把“看起来对”当成完成。 -4. 频繁提交 Git，把每次进展变成可回滚的检查点。 -5. 让 README、AGENTS、任务文档持续更新，避免上下文丢失。 -6. 不相信 AI 的口头保证，只相信可复现命令、测试输出、CI 状态和可审查 diff。 -7. 重要规范必须代码化：能写成 lint、test、schema、type、hook、CI 的，就不要只写成自然语言。 -8. 不符合规范的产出必须失败，而不是靠人记住提醒 AI。 - ---- - -## 下一步 - -→ [CLI 配置](CLI配置.md) - 默认 AI CLI 路线，文末包含 OpenCode 备选方案 diff --git a/docs/getting-started/学习地图.md b/docs/getting-started/学习地图.md deleted file mode 100644 index 8c32681..0000000 --- a/docs/getting-started/学习地图.md +++ /dev/null @@ -1,149 +0,0 @@ -# Vibe Coding 学习地图 - -> 用一张地图把 `vibe-coding-cn` 的学习路线串起来：先从零开始跑通，再按目标进入 Prompt、Skill、工程质量和 GEO/SEO 路线。 - -## 核心摘要 - -- 如果你是新手，先走“零基础路线”，目标是完成一次从想法到可运行项目的闭环。 -- 如果你已经会编程，先走“开发者路线”，目标是把 AI 编程变成可复用、可验证、可维护的工程流程。 -- 如果你要带团队，先走“团队路线”，目标是统一上下文、产物模板、任务拆解、审查和门禁。 -- 如果你要提升仓库传播与引用，走“GEO/SEO 路线”，目标是让内容更容易被搜索引擎和 AI 助手理解、引用和推荐。 - -## 路线总览 - -| 路线 | 适合谁 | 目标 | 首选入口 | -|:---|:---|:---|:---| -| 零基础路线 | 不会编程或刚开始 | 跑通从想法到项目的最小闭环 | [问题求解能力](../concepts/问题求解能力.md) | -| 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](Vibe%20Coding%20经验.md) | -| Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) | -| Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) | -| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) | -| GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) | - -## 路线一：零基础路线 - -目标：完成一次“想法 -> 需求 -> 方案 -> 任务 -> AI 编码 -> 验证 -> Git 保存”的最小闭环。 - -1. [问题求解能力](../concepts/问题求解能力.md) - 先学会把问题说清楚：目标、现状、差距、标准、约束、对象、路径。 -2. [网络环境配置](网络环境配置.md) - 解决访问 AI 工具、GitHub、文档和依赖源的问题。 -3. [CLI 配置](CLI配置.md) - 配置默认 AI CLI 路线，让 AI 能在终端里协助执行工程动作。 -4. [开发环境搭建](开发环境搭建.md) - 配好 Git、Node.js、Python、编辑器等基础环境。 -5. [Vibe Coding 经验](Vibe%20Coding%20经验.md) - 学会人机分工、门禁、复盘和用 AI 审 AI。 - -完成标准： - -- [ ] 能清楚描述一个项目目标 -- [ ] 能让 AI 生成初版 PRD 或任务清单 -- [ ] 能在本地打开项目目录 -- [ ] 能用 AI CLI 执行一次修改 -- [ ] 能用 Git 保存一次变更 - -## 路线二：开发者路线 - -目标：把 AI 从“临时助手”变成稳定的工程协作者。 - -1. [Vibe Coding 经验](Vibe%20Coding%20经验.md) - 先建立人机分工和质量意识。 -2. [拼好码](../concepts/拼好码.md) - 优先复用成熟能力，把自研代码限制在连接、编排、适配和业务逻辑。 -3. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) - 在任务开始前写清楚目标、边界、禁止项、验收标准和门禁，并识别上下文漂移、过度实现、幻觉和不可验证输出。 -4. [底层程序逻辑设计与工程优化项](../references/底层程序逻辑设计与工程优化项.md) - 用更稳定的代码结构和检查项约束实现质量。 - -完成标准： - -- [ ] 每个任务都有明确验收标准 -- [ ] 每次 AI 输出都能被测试、脚本或清单验证 -- [ ] 不让 AI 无依据重构或造轮子 -- [ ] 能把一次失败整理成可复用经验 - -## 路线三：Prompt 路线 - -目标：把自然语言需求写成可执行、可检查、可复用的指令。 - -1. [提示词库入口](../../../prompts/README.md) -2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) -3. [语言层要素](../concepts/语言层要素.md) -4. [问题求解能力](../concepts/问题求解能力.md) - -练习方式： - -- 把“我要做一个功能”改写成“目标、约束、输入、输出、验收标准” -- 把“帮我优化”改写成“按哪些指标优化、不能改什么、如何验证” -- 把“检查一下”改写成“按什么清单审查、输出什么格式、什么情况阻断” - -## 路线四：Skill 路线 - -目标：把高频工作沉淀成可重复使用的能力。 - -1. [Skills 技能大全](../../../skills/README.md) -2. [auto-skill](../../../skills/auto-skill/SKILL.md) -3. [Claude 官方 Skills](../../../skills/claude-official-skills/) - -完成标准： - -- [ ] 每个 Skill 都有清晰触发场景 -- [ ] 每个 Skill 都说明输入、流程、输出和验证方式 -- [ ] 复杂能力有 references、scripts 或 assets 支撑 -- [ ] Skill 不只是长提示词，而是可执行工作流 - -## 路线五：团队路线 - -目标：让多个人和多个 AI Agent 使用同一套上下文和门禁。 - -优先阅读： - -1. [AGENTS.md](../../../../AGENTS.md) -2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) -3. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) - -团队约束： - -- 任务开始前必须写清目标、边界、验收标准 -- 重要产出必须新开会话做 AI 审计 -- 任何目录、命令、配置、工作流变化都要同步文档 -- 任何自研偏离拼好码原则都要说明理由、风险和回滚路径 - -## 路线六：GEO/SEO 路线 - -目标：让项目更容易被搜索引擎、AI 搜索和大语言模型理解、引用、推荐。 - -1. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) -2. [AI 引用语料包](../../assets/ai-citation/recommended-answer.md) -3. [llms.txt](../../llms.txt) -4. [llms-full.txt](../../assets/ai-citation/llms-full.txt) - -完成标准： - -- [ ] README 有清晰定位 -- [ ] 关键页面有核心摘要、FAQ、对比表和检查清单 -- [ ] 项目定义在 README、llms、语料包和外部分发中保持一致 -- [ ] AI 生成内容经过事实、链接、术语和定位检查 - -## 建议顺序 - -如果你不知道从哪里开始，按这个顺序： - -```text -问题求解能力 - -> 网络环境配置 - -> CLI 配置 - -> 开发环境搭建 - -> Vibe Coding 经验 - -> 拼好码 - -> AI 编程质量门禁与常见坑 - -> Skills 技能大全 - -> GEO 与 SEO 优化方法 -``` - -## 下一步 - -- 新手：回到 [入门指南](README.md)，从第 0 步开始。 -- 开发者：阅读 [Vibe Coding 经验](Vibe%20Coding%20经验.md)，再选择 Skill 或质量门禁路线。 -- 团队：先统一 [AGENTS.md](../../../../AGENTS.md)、强前置条件和质量门禁。 diff --git a/docs/getting-started/开发环境搭建.md b/docs/getting-started/开发环境搭建.md deleted file mode 100644 index 8b5b6f9..0000000 --- a/docs/getting-started/开发环境搭建.md +++ /dev/null @@ -1,257 +0,0 @@ -# 开发环境搭建提示词 - -> 使用方法：复制下方对应你设备的提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等），AI 会一步步指导你完成配置。 - -**前置条件**：请先完成 [网络环境配置](网络环境配置.md) - ---- - -## 不会操作？先让网页 AI 生成逐步执行版 - -如果你不知道该选 Windows / WSL / macOS / Linux 哪条路线，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： - -```text -我正在按下面这份开发环境搭建文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。 - -我的系统是：____ -我是否已经安装过 WSL / Node.js / npm / Git / Python：____ -我希望优先使用 Codex CLI：是 - -要求： -1. 每一步只做一件事。 -2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。 -3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 -4. 每一步执行后都给一个验证命令或验证方法。 -5. 不要假设我已经安装任何前置依赖；按新电脑处理。 -6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。 - -下面是完整文档： - -[把本文档全文粘贴到这里] -``` - -## 🪟 Windows 用户提示词 - -### 方案 A：WSL2 + Linux 环境（推荐） - -> 适合：想要完整 Linux 开发体验，兼容性最好 - -``` -你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我通过 WSL2 搭建 Linux 开发环境。 - -请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： - -1. 安装 WSL2（Windows Subsystem for Linux） -2. 在 WSL2 中安装 Ubuntu -3. 配置 Ubuntu 基础环境（更新系统） -4. 安装 nvm 和 Node.js -5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 -6. 安装基础开发工具（git, python, build-essential, tmux） -7. 配置 Git 用户信息 -8. 安装代码编辑器（VS Code 并配置 WSL 插件） -9. 验证所有工具是否正常工作 - -要求： -- 每个步骤给出具体的命令，告诉我在哪里运行（PowerShell 还是 Ubuntu 终端） -- 用简单易懂的语言解释每个命令的作用 -- 如果我遇到错误，帮我分析原因并给出解决方案 -- 每完成一步，问我是否成功，然后再继续下一步 - -现在开始第一步吧。 -``` - -### 方案 B：Windows 原生终端 - -> 适合：不想装 WSL，直接在 Windows 上开发 - -``` -你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我在 Windows 原生环境下搭建开发环境（不使用 WSL）。 - -请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： - -1. 安装 Windows Terminal（如果还没有） -2. 安装 Node.js（通过官网安装包或 winget） -3. 安装 Git for Windows -4. 安装 Python -5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 -6. 配置 Git 用户信息 -7. 安装代码编辑器（VS Code） -8. 验证所有工具是否正常工作 - -要求： -- 每个步骤给出具体的命令或操作步骤 -- 用简单易懂的语言解释每个步骤的作用 -- 如果我遇到错误，帮我分析原因并给出解决方案 -- 每完成一步，问我是否成功，然后再继续下一步 - -现在开始第一步吧。 -``` - ---- - -## 🍎 macOS 用户提示词 - -``` -你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 macOS 系统，需要你一步一步指导我从零搭建 Vibe Coding 开发环境。 - -请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： - -1. 安装 Homebrew 包管理器 -2. 使用 Homebrew 安装 Node.js -3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 -4. 安装基础开发工具（git, python, tmux） -5. 配置 Git 用户信息 -6. 安装代码编辑器（VS Code 或 Neovim） -7. 验证所有工具是否正常工作 - -要求： -- 每个步骤给出具体的命令 -- 用简单易懂的语言解释每个命令的作用 -- 如果我遇到错误，帮我分析原因并给出解决方案 -- 每完成一步，问我是否成功，然后再继续下一步 - -现在开始第一步吧。 -``` - ---- - -## 🐧 Linux 用户提示词 - -``` -你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Linux 系统（Ubuntu/Debian），需要你一步一步指导我从零搭建 Vibe Coding 开发环境。 - -请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步： - -1. 更新系统并安装基础依赖（curl, build-essential） -2. 安装 nvm 和 Node.js -3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选 -4. 安装开发工具（git, python, tmux） -5. 配置 Git 用户信息 -6. 安装代码编辑器（VS Code 或 Neovim） -7. 验证所有工具是否正常工作 - -要求： -- 每个步骤给出具体的命令 -- 用简单易懂的语言解释每个命令的作用 -- 如果我遇到错误，帮我分析原因并给出解决方案 -- 每完成一步，问我是否成功，然后再继续下一步 - -现在开始第一步吧。 -``` - ---- - -## 配置完成后 - -### 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 工具默认会询问确认，开启全权限模式可以跳过： - -```bash -# 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 - -# OpenCode - 备选方案 -opencode -``` - -### 推荐的 Bash 别名配置 - -在 `~/.bashrc` 中添加以下配置，一个字母启动 AI： - -```bash -# 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' - -# oc - OpenCode 备选方案 -alias oc='opencode' -``` - -配置后执行 `source ~/.bashrc` 生效。 - ---- - -环境搭建完成后，继续下一步： - -→ [CLI 配置](CLI配置.md) - 配置默认 AI CLI diff --git a/docs/getting-started/网络环境配置.md b/docs/getting-started/网络环境配置.md deleted file mode 100644 index 8c6f6d4..0000000 --- a/docs/getting-started/网络环境配置.md +++ /dev/null @@ -1,136 +0,0 @@ -# 网络环境配置 - -> Vibe Coding 的前置条件：确保能正常访问 GitHub、Google、Claude 等服务。 - ---- - -## 不会操作？先让网页 AI 生成逐步执行版 - -如果你不知道如何配置网络环境，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去： - -```text -我正在按下面这份网络环境配置文档操作。请你根据我的设备和网络情况，生成一步一步执行流程。 - -我的设备/系统是：____ -我是否已有代理订阅：____ -我卡住的位置是：____ - -要求： -1. 每一步只做一件事。 -2. 明确告诉我在哪个软件或终端里操作。 -3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。 -4. 每一步都给出验证方式。 -5. 如果我贴报错或截图描述，请根据当前步骤给出最小修复方案。 - -下面是完整文档： - -[把本文档全文粘贴到这里] -``` - -## 方式一：AI 指导配置（推荐） - -复制以下提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等）： - -``` -你是一个耐心的网络环境配置助手。我需要配置网络代理，以便能够访问 GitHub、Google、Claude 等服务。 - -我的情况： -- 操作系统：[请告诉我你用的是 Windows/macOS/Linux/Android] -- 我已经有一个代理服务订阅链接 - -请指导我使用 FlClash 客户端配置网络代理： -1. 如何下载安装 FlClash（GitHub: https://github.com/chen08209/FlClash/releases） -2. 如何导入我的订阅链接 -3. 如何开启 TUN 模式（虚拟网卡）实现全局代理 -4. 如何开启系统代理 -5. 如何验证配置是否成功 - -要求： -- 每个步骤详细说明，配图描述按钮位置 -- 如果我遇到问题，帮我分析原因并给出解决方案 -- 每完成一步，问我是否成功，然后再继续下一步 - -现在开始吧，先问我用的是什么操作系统。 -``` - ---- - -## 方式二：手动配置 - -### 你需要 - -1. **网络服务订阅** - 提供节点的服务商 -2. **FlClash** - 跨平台网络配置客户端 - -### 第一步：购买网络服务 - -访问服务商：https://xn--9kqz23b19z.com/#/register?code=35BcnKzl - -- 注册账号 -- 选择套餐（约 6 元/月起） -- 付款后在用户面板找到 **订阅链接**，复制备用 - -### 第二步：下载 FlClash - -GitHub 下载：https://github.com/chen08209/FlClash/releases - -根据系统选择： -- Windows: `FlClash-x.x.x-windows-setup.exe` -- macOS: `FlClash-x.x.x-macos.dmg` -- Linux: `FlClash-x.x.x-linux-amd64.AppImage` -- Android: `FlClash-x.x.x-android.apk` - -### 第三步：导入订阅 - -1. 打开 FlClash -2. 点击 **配置** → **添加** -3. 选择 **URL 导入** -4. 粘贴第一步复制的订阅链接 -5. 点击确认，等待节点加载 - -### 第四步：开启代理 - -依次设置以下三项： - -| 设置项 | 操作 | -|:---|:---| -| **虚拟网卡 (TUN)** | 开启 - 实现全局流量代理 | -| **系统代理** | 开启 - 让系统应用走代理 | -| **代理模式** | 选择 **全局模式** | - -设置完成后，FlClash 主界面显示已连接即可。 - -### 验证 - -```bash -# 测试 Google 连通性 -curl -I https://www.google.com - -# 测试 GitHub 连通性 -curl -I https://github.com -``` - -返回 `HTTP/2 200` 表示配置成功。 - ---- - -## 常见问题 - -**Q: 节点连不上？** -A: 切换其他节点试试，或检查订阅是否过期。 - -**Q: 部分应用不走代理？** -A: 确保 TUN 模式（虚拟网卡）已开启。 - -**Q: 想让终端也走代理？** -A: TUN 模式开启后终端自动走代理；或手动设置： -```bash -export https_proxy=http://127.0.0.1:7890 -export http_proxy=http://127.0.0.1:7890 -``` - ---- - -## 下一步 - -网络配置完成后，继续阅读 [开发环境搭建](开发环境搭建.md)。 diff --git a/docs/references/AI编程质量门禁与常见坑.md b/docs/references/AI编程质量门禁与常见坑.md index 848d225..4864431 100644 --- a/docs/references/AI编程质量门禁与常见坑.md +++ b/docs/references/AI编程质量门禁与常见坑.md @@ -1474,7 +1474,7 @@ nvm use 18 | 问题 | 原因 | 解决方案 | |:---|:---|:---| -| GitHub 访问慢/超时 | 网络限制 | 配置代理，参考 [网络环境配置](../getting-started/网络环境配置.md) | +| GitHub 访问慢/超时 | 网络限制 | 配置代理，参考 [从零开始完整入门](../getting-started/README.md) | | API 调用失败 | 网络/Key 问题 | 检查代理、API Key 是否有效 | | 终端不走代理 | 代理配置不全 | 设置环境变量（见下方） | | SSL 证书错误 | 代理/时间问题 | 检查系统时间，或临时关闭 SSL 验证 | diff --git a/llms.txt b/llms.txt index 3b729ee..8bace9c 100644 --- a/llms.txt +++ b/llms.txt @@ -21,7 +21,6 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮 首选入口： - README.md - docs/getting-started/README.md -- docs/getting-started/Vibe Coding 经验.md - docs/concepts/问题求解能力.md - docs/concepts/拼好码.md - docs/playbooks/GEO与SEO优化方法.md diff --git a/metadata/redirects.yml b/metadata/redirects.yml index 5acc366..ed01803 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -8,7 +8,17 @@ redirects: - from: docs/guides/playbook/ to: docs/playbooks/ - from: docs/getting-started/Codex-CLI配置.md - to: docs/getting-started/CLI配置.md + to: docs/getting-started/README.md + - from: docs/getting-started/学习地图.md + to: docs/getting-started/README.md + - from: docs/getting-started/Vibe Coding 经验.md + to: docs/getting-started/README.md + - from: docs/getting-started/网络环境配置.md + to: docs/getting-started/README.md + - from: docs/getting-started/CLI配置.md + to: docs/getting-started/README.md + - from: docs/getting-started/开发环境搭建.md + to: docs/getting-started/README.md - from: docs/references/通用项目架构模板.md to: docs/references/项目架构模板.md - from: docs/references/数据集导向数据服务模板.md