03 / 04 · 从这里开始

Official quickstart 安装命令高波动

Install · Auth · First run

先完成一次可回退的首次运行。

先只选一个 CLI。按“准备练习仓 → 安装 → 做一次小任务 → 看 diff”走完一遍。所有安装命令只引用官方 Quickstart；失败时回到对应 README 或 Releases 核对。

官方核对：2026-07-24 · 本页说明是官方文档与官方仓库内容的中文摘要；具体命令、账号与权限行为以打开后的官方页面为准。

00 · Prerequisites

开始前检查

终端与系统

macOS / Linux 用原生 shell；Windows 优先 WSL2，或各产品文档写明的 PowerShell 安装脚本。需要 Node 时，以该 CLI 的官方要求为准。

Git 与练习仓

先准备可丢弃的练习分支，再给 agent 开写权限。把 git status / diff / restore 当作安全网，而不是事后补救。

账号已就绪

完成 Android、iPhone / iPad 或网页中的一种官方订阅方式，并确认电脑与移动端登录的是同一个账号。

Git 安全网（必做）

AI CLI 改文件很快，回退要靠 Git。生产仓首次只读；练习仓用独立分支。密钥、token 与本地配置永远不要进提交。

zsh · git · 练习仓模板

# 1) 克隆一个可丢弃的练习仓（示例：OpenCode 源码，只读浏览）
mkdir -p ~/ai-cli-practice && cd ~/ai-cli-practice
git clone --depth 1 https://github.com/anomalyco/opencode.git opencode-src
cd opencode-src

# 2) 开练习分支——agent 只在这一层改动
git switch -c practice/$(date +%Y%m%d)-first-run
git status

# 3) 会话前后对照（也要求 agent 按此验收）
git status -sb
git diff
git diff --stat

# 4) 一次会话只做一个主题；满意再提交
git add -p
git commit -m "practice: describe the one change"

# 5) 回退未提交改动 / 整段会话
git restore .                    # 丢弃工作区（未 stage）
git restore --staged .           # 取消 stage
git switch main && git branch -D practice/…   # 整分支放弃

# 6) 已提交但未 push：安全反悔
git revert HEAD                  # 推荐：可审计
# git reset --hard HEAD~1        # 仅本地、未 push 的练习仓

# 成功：分支还在、diff 可读、密钥未出现在 git log -p

给 agent 的 Git 约束（可贴进提示词）

约束： - 不要 git push；不要改 remote - 不要 git commit --amend / force - 改完用 git status + git diff --stat 自检 - 密钥、.env、auth.json 不得写入仓库 - 一次会话只做一个主题；无关文件先 restore

先定位问题，再重试；不要直接关掉权限或安全设置。

找不到命令

关掉并重开终端，再用产品官方文档确认安装位置与系统要求。不要靠复制陌生的 PATH 修改命令硬修。

登录失败或 401

先确认走的是订阅登录还是 API 路径；退出并重新登录。token 只放在本机安全位置，不能贴进仓库或聊天记录。

Node / 运行时不匹配

回到该 CLI 的官方安装页，确认支持的运行时版本；更新后重新执行安装，不要混用多份全局包。

网络或权限被拒绝

检查公司代理、VPN、系统防火墙和项目目录权限。先在练习仓复现；不要为了通过安装临时关闭整机防护。

远程安装脚本：先核对，再执行

页面里的 curl | sh 和 irm | iex 仅在确认域名属于官方、理解其用途且处于非生产环境时使用。官方提供包管理器或可下载安装包时，优先采用可检查、可回退的路径。

Official Open source

Codex CLI

OpenAI 官方将 Codex CLI 用于在终端中检查代码、编辑文件、运行本地工具和自动化重复工作。进入项目目录后运行 codex，首次按提示登录；/init 可生成 AGENTS.md。执行前后保留 Git 检查点，并按权限提示确认操作。

Codex CLI 文档仓库 / Changelog npm @openai/codex

zsh · codex · official install

# 官方独立安装（macOS / Linux）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 或包管理器
npm install -g @openai/codex
# brew install --cask codex
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

codex --version

# 启动 TUI；首次按提示登录 ChatGPT 或配置 API Key
cd ~/projects/demo-app
codex

# 在 TUI 中：/init → 生成 AGENTS.md（技术栈、命令、改动规则）
# 非交互 / CI 常用 exec（以当前 --help 为准）
codex "阅读 README，用三句话总结项目；先不要改文件"

# 成功：鉴权通过、能读仓库、权限 / sandbox 提示可理解

文档要点

安装后直接运行 codex 进入交互；用 /init 写项目规则；脚本 / CI 走非交互模式。写文件与跑 shell 前，先确认 sandbox 与批准范围。

验收

codex --version 有输出；一次只读任务结果与仓库一致；git status 无意外改动。

Official

Claude Code

Claude Code 的官方入门顺序是安装、登录、在项目目录启动。首次运行 claude 会引导浏览器登录；默认模式会在改文件前请求批准。可用 Shift+Tab 在默认、acceptEdits 和 plan 等模式间切换，先用只读问题了解仓库。

Quickstart Setup Hooks Skills

zsh · claude · official install

# 官方原生安装（macOS / Linux / WSL，推荐）
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
# irm https://claude.ai/install.ps1 | iex

# 或 Homebrew / WinGet（以当前文档为准）
# brew install --cask claude-code
# winget install Anthropic.ClaudeCode

claude
# 首次按提示登录 Claude 账号（或 ANTHROPIC_API_KEY）

cd ~/projects/demo-app
claude "先阅读 CLAUDE.md（如有）与 README，给出不超过 3 步的计划，先不改文件"

# 交互习惯（官方 Quickstart）
# Shift+Tab 切换模式：默认需批准 → acceptEdits → plan（只规划不改）
# /init 生成/更新 CLAUDE.md；不满意的改动可用 /undo，恢复用 /redo

# 成功：登录完成、能概括仓库、权限提示清晰、会拒绝一次 tool 请求

习惯

复杂需求先 Plan 再 Build；把反复纠正写进 CLAUDE.md；危险操作靠 hooks 拦截。免费 Claude.ai 计划通常不含 Code，以 Plans 页为准。

验收

claude 可启动；只读任务结果正确；你知道如何拒绝一次 tool 请求。

Official Open source

Gemini CLI

Gemini CLI 的官方入门顺序是安装、认证、配置、使用。标准安装为 npm install -g @google/gemini-cli；启动 gemini 后通常可用 Google 账号登录。它支持环境变量、命令行参数和设置文件；其他认证方式以 Authentication 页面为准。

Get Started Installation Authentication 官方仓库

zsh · gemini · official install

# 官方推荐：全局安装
npm install -g @google/gemini-cli

# 或不安装，直接运行
# npx @google/gemini-cli

# 认证：AI Studio 密钥（见 Authentication 文档）
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
# 首次也可走 Google 账号登录（以 TUI 提示为准）

gemini
gemini "用两点解释 context window，并列出当前目录文件名"

# 深入：官方 docs 的 settings、MCP、Cheatsheet、配额与定价页

# 成功：无鉴权错误，能列目录并回答

配置系统

模型、主题、MCP 等写在用户 / 项目配置里；改前先备份。配额以及与 Code Assist / AI Studio / Cloud 的结算关系，以 Quotas and Pricing 官方页为准。

验收

全局安装或 npx 均可运行；密钥未出现在仓库；一次工具调用可被你拒绝。

Official Open source

Grok Build （命令：grok）

Grok Build 是 xAI 的编码 agent，可在交互式 TUI、无头脚本或支持 ACP 的应用中使用。首次启动 grok 会打开浏览器认证；无浏览器环境可用 XAI_API_KEY。无头任务使用 grok -p。

x.ai/cli Docs overview Headless / ACP xai-org/grok-build

zsh · grok · official install

# 官方安装（macOS / Linux / Git Bash）
curl -fsSL https://x.ai/cli/install.sh | bash

# Windows PowerShell
# irm https://x.ai/cli/install.ps1 | iex

cd ~/projects/demo-app
grok
# 首次启动：浏览器认证；无浏览器环境可设置 XAI_API_KEY

# 无头模式（脚本 / CI）
grok -p "Summarize this repo in 5 bullets; do not edit files"
# CI 可加 --no-auto-update 跳过后台更新检查

# ACP：给 IDE / 编排器用
# grok agent stdio

# 成功：TUI 可进项目、鉴权通过、无头命令有输出

命名澄清

本指南里的「Grok」一律指 Grok Build / grok CLI（xAI 官方）。社区项目 superagent-ai/grok-cli、whitesmith/grok-cli 等仅作对照，不作为官方安装来源。

Open source · GitHub README · zh

OpenCode

OpenCode 是开源的终端编码助手。第一次进入项目后，先用 /connect 连接模型提供商，再执行 /init 生成项目级 AGENTS.md。主对话可用 Tab 在 Build 和 Plan 间切换：Build 用来实施；Plan 适合先看方案，因为编辑文件和运行 Bash 默认都会询问。

GitHub 仓库 README.zh.md Releases CONTRIBUTING 站点文档（补充）

zsh · opencode · GitHub README.zh.md

# 安装前：移除 0.1.x 之前的旧版本（仓库 TIP）
# 一键安装（YOLO）
curl -fsSL https://opencode.ai/install | bash

# 包管理器（README）
# npm i -g opencode-ai@latest
# brew install anomalyco/tap/opencode   # 推荐，更新快
# brew install opencode                 # 官方 formula，更新慢
# Windows: scoop / choco install opencode
# Arch: pacman -S opencode  或  paru -S opencode-bin
# mise use -g opencode
# nix run nixpkgs#opencode  # 或 github:anomalyco/opencode

# 可选：用 git 只读浏览源码（不要用来安装二进制）
git clone --depth 1 https://github.com/anomalyco/opencode.git ~/ai-cli-practice/opencode-src

# 第一次进入项目：连接提供商，再建立项目说明
cd ~/ai-cli-practice/demo-app   # 先 git switch -c practice/…
opencode
/connect                           # 选择提供商并完成登录 / 填入 Key
/init                              # 生成并检查项目级 AGENTS.md

# 复杂任务：先按 Tab 进入 Plan，确认方案后再切回 Build
# 结束或走偏时可用 /undo 撤销最近一次 agent 改动

# 常用能力（仓库 + 站点 CLI 补充）
opencode run "Explain how closures work in JavaScript"
opencode models
opencode mcp add
opencode serve
opencode web
opencode stats

# 成功：which opencode 有输出；TUI 可 /connect；plan 模式不改文件

先计划，再动手

Build 是默认主助手，能使用更多工具；Plan 用来分析和列方案，编辑文件与运行 Bash 默认会询问。内置的 @general、@explore、@scout 可以由主助手调用，也能在消息中点名。第一次改仓库时，先让 Plan 列出涉及文件、风险和验收方式，再明确批准 Build 实施。

与 Git 一起用

在练习分支上开会话；结束后用 git diff --stat 验收。不满意就用 git restore .，或直接删掉练习分支。不要让 agent 执行 git push 或 --force。密钥目录与 .env 请写进 .gitignore。

最小安全配置（项目根目录）

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git push": "deny"
    }
  },
  "agent": {
    "review": {
      "description": "只读审阅，不修改文件",
      "mode": "subagent",
      "permission": { "edit": "deny" }
    }
  }
}

项目根目录的 opencode.jsonc 会覆盖个人偏好中冲突的字段，适合放团队共识；个人模型和界面偏好留在全局配置。更多权限、配置合并与 MCP 字段，按 Config 和 Agents 官方文档核对。

统一验收清单（Smoke）

which codex claude gemini grok opencode 至少有一个在 PATH 中
登录或 API Key 生效，无 401 / unauthorized
在练习目录完成：读文件 →（可选）小改动 → 看 diff
会用 /help、/init 或 --help 查本地命令
知道如何拒绝一次危险工具调用；OpenCode 用户已试过 opencode run "…"，或用 Tab 切换计划模式

下一步：构建属于自己的工作流

把「会装」升级成「按任务可重复执行」的个人系统。

04 / 04 · 构建工作流

Official patterns Community pain points

Task playbooks

按真实任务组织，不按产品堆功能。

每个工作流都写清：目标、准备、推荐 CLI、示例提示、工具会做什么、你要确认什么、如何验收、怎样回退。复杂案例再补常见卡点、处理策略与可复用提示。设计还原见 12 · Figma / OpenDesign：从 Token、Spec 到 CLI 的完整过程。

Daily loop

四步日环

框定任务

用一句话写清目标、约束与完成标准。例如：「只改登录文案，不动 API」。

先读项目约定

先读 AGENTS.md / CLAUDE.md / README，别让工具从零猜项目结构。

小步执行

一次只做一个可验证的改动：改代码 → 跑测 → 看 diff → 再继续。

记下可复用的做法

把反复使用的指令写回约定文件；把踩过的坑记进禁止事项。

MCP · for beginners

要用 MCP，先弄清它能帮什么。

把 MCP 想成给 AI 工具加的统一“转接头”：Codex、Claude Code 这类客户端通过它连接外部资料或功能。比如让工具读 Figma 里的某个画板，或读 Open Design 项目。只是在仓库里读写代码时，通常不需要先装 MCP。

核对日期：2026-07-24 · 安装命令 / 端点属高波动

第一次接 MCP，只做一件小事

不要一开始就装一长串服务。先在练习项目接入一个和当前任务有关的 MCP，然后只让它读取信息。确认它找对了资料、不会越权后，再考虑写入或全局启用。

什么时候值得装

你手上已有 Figma 设计稿，想让工具读选中的画板；或已经在用 Open Design，想让工具读原型和设计变量。

什么时候先别装

你只是想让 CLI 解释仓库、改一个页面或跑测试。先把基础工作流跑通，MCP 不会替你解决提示不清或权限没设好的问题。

选一个场景：有 Figma 设计稿就试 Figma MCP；有 Open Design 项目才试 OD MCP；两者都没有就先跳过。
只在当前项目接入：远程服务会打开网页登录；本地服务在你的电脑上启动。第一次不必记住 stdio 或 HTTP 的区别。
先发只读请求：「告诉我你能读取哪些资料，不要写文件、不要运行命令。」看结果是否确实来自目标项目。
完成后再收口：不再使用就删除配置；远程服务同时在其网站撤销已授权会话。

MCP 官方介绍 MCP 架构与工具发现

A · 已经在用 Open Design？从本地原型读取开始

Open Design MCP

od mcp

Open source 中波动

只有当你的原型已经放在 Open Design 里，才需要这个 MCP。接好后，AI CLI 可以读取当前项目的原型、设计变量和项目资料，不必靠截图猜布局。大多数情况下只要执行安装命令，CLI 会在需要时启动本地服务。

展开安装与配置命令

open design · mcp

# 本地服务（通常由 CLI 自动启动，不必先手动运行）
od mcp

# 先预览，再决定是否写入目标 CLI 的配置
od mcp install claude    # 或 codex | cursor | …
od mcp install --print claude   # 只打印配置片段，不写入磁盘

先用 od mcp install --print <agent> 预览配置，再决定是否写入。
接入后先问：「你现在能看到哪些原型和变量？只列名称，不要修改。」确认项目找对了。
需要改网页时，再让工具引用这些变量；原型或变量要写回时，先保留 Git 分支与变更预览。

nexu-io/open-design · Settings → MCP · docs/agent-adapters

GitHub MCP 说明

适合的情况

design ↔ code

低波动 · 场景

你在 Open Design 里已经有 HTML 原型或设计变量，同时要在 Codex、Claude Code 之类的 CLI 里改页面。它能让工具读取已有资料，而不是让你反复贴截图和说明。

本机已安装 od，且 daemon 可连接
目标 CLI 支持 MCP
第一次只读确认，不直接允许写文件

分类 · 设计与原型 · 本地 stdio

B · 有 Figma 设计稿？让工具先读一个画板

Figma MCP

mcp.figma.com

Official 高波动

Figma MCP 的实用场景很简单：把某个画板的链接交给 AI CLI，让它读取组件、变量和布局，再按这份资料写代码。第一次只做“读取一个画板”；写回 Figma 画布是另一个动作，等你熟悉后再开。

展开远程 MCP 接入命令

figma · remote mcp

# Claude Code — 推荐插件（含 MCP + Skills）
claude plugin install figma@claude-plugins-official

# 或手动添加远程 HTTP 传输
claude mcp add --transport http figma https://mcp.figma.com/mcp
# 全局：加 --scope user

# Codex CLI — 添加远程端点，然后按提示完成 OAuth
codex mcp add figma --url https://mcp.figma.com/mcp

使用 Codex App 时，从 Plugins 安装 Figma；使用 CLI 时添加端点后按提示登录。
复制目标 Frame 或图层链接，先说：「读取这个画板，列出组件和变量，不要修改 Figma。」
确认读取内容和文件权限都正确后，才考虑写回画布或使用 Code to Canvas。

developers.figma.com · figma.com/mcp-catalog

Remote 安装 MCP Catalog

Figma 使用注意

auth · scope

Official

你需要有目标 Figma 文件的访问权限，并完成登录。实现页面时，先让工具只读一个画板，再让它写代码。不要一开始就给“写回画布”的权限；命令和插件名以 Figma Developer Docs 为准。

分清「读取设计资料」与「写回 Figma 画布」
企业账号可能限制第三方 MCP
不要把 file token 写进仓库

分类 · 设计稿协作 · 远程 HTTP

C · 工作流方法（不是 MCP，等基础跑通再看）

HelloAGENTS

workflow layer

Community Open source 中波动

这是一个社区工作流包，用来约束“先计划、再修改、最后验收”这类过程。它不是 MCP，不会帮你连接 Figma 或外部数据。刚开始用 CLI 时，先把一次只读任务和一次小改动跑通；需要固定团队流程时，再考虑安装它。

展开安装说明

helloagents · install

# 以仓库 README 为准（路径/脚本会变）
git clone https://github.com/hellowind777/helloagents.git
cd helloagents
# 按文档把 skills 装到对应 CLI 的 skills 目录
# 例：Claude → ~/.claude/skills 或项目 .claude/skills

github.com/hellowind777/helloagents · 14+ workflow skills

仓库 README

它和 MCP 怎么配合

skills ≠ mcp

Community

MCP 让工具拿到资料或执行特定动作，例如读取 Figma；HelloAGENTS skills 规定任务怎样推进和验收。先确保 MCP 能只读到正确资料，再用工作流规则约束后续修改。

这是社区项目，安装与版本以 README 为准
安装前先备份已有 skills / hooks
生产仓先保持只读，并保留人工确认

分类 · 工作流层 · 多 CLI

分类速记

A 原型读取 Open Design 项目；B 设计稿读取 Figma 画板；C 流程规范任务推进（不是 MCP）。一次只接一种，确认它能只读到正确资料后，再加第二种。设计稿还原的图解见任务手册 12。

Design → code pipeline

设计到代码的三条链路

只看命令行，很难知道变量在 Figma 哪一栏、Inspector 显示什么、OD 里的 token 叫什么。先记住这条对应关系，再看 Playbook 12 的面板标注。

01 · Figma

命名 + Variables

图层用组件语义名；Local Variables 用 kebab-case，与 CSS --token 对齐。

02 · Spec

Dev Mode / OD

Dev Mode 读 CSS / 属性；导出 JSON Spec 或经 Open Design MCP 读本地原型与 tokens。

03 · AI CLI

防漂移落地

把 Spec 当上下文；只改变量绑定，禁止硬编码色值与随意改 DOM。

Playbooks · 11 tasks + Real-World + Design

任务手册

模板能帮助你上手，但复杂任务还要知道怎样限制改动、定位问题和验证结果。下面覆盖上下文过长、工具误改、渐进式重构、复杂日志、跨系统联调，以及设计 Token 与代码变量不一致等情况；02 / 05 / 11 / 12 附有可直接使用的提示，12 还带 Figma 面板图解。

案例优先级：官方 common workflows → 仓库 examples → release notes → Issues / Discussions → 社区痛点。社区适合回答「大家卡在哪」，不适合证明「现在价格是多少」。

01 · 理解陌生项目 Any CLI 只读优先

目标

在 30 分钟内建立架构地图，并划出安全改动边界。

准备条件

可克隆的仓库；只读权限策略；本地能跑基础命令。

你需要确认什么

仅允许 read / search；拒绝写文件与任意 shell（除非你指定 pnpm test 等）。

示例提示词

先阅读 README、包管理清单与入口文件。输出： 1) 系统一句话描述 2) 目录地图 3) 本地启动 / 测试命令 4) 高风险目录（勿动）5) 若要改「小文案」应碰哪些文件。不要修改任何文件。

AI 将执行什么

列目录、读关键文件
总结架构与脚本

验收命令

人工对照 README；抽查 2 个路径是否存在。

失败回退

无文件变更则直接结束会话；有误读则指定正确入口文件后重跑。

02 · 排查复杂线上 Bug（Real-World Ex） Claude Code 只读侦探 Real-World

目标

先定位、再验证、后动刀：用最小 diff 修好，并有回归验证。

准备条件

复现步骤、错误日志切片（不要整本 dump）、失败测试，或录屏的文字版说明。

你需要确认什么

第一轮禁止写文件；验证 log 贴回后再决定是否开写权限与测试命令。

AI 将执行什么

精读指定文件行号与调用链
提出可证伪的假说 + 要打的 log
等你验证后才改代码 / 补测试

验收

假说被日志证明或证伪；最终 diff 可读；原先失败用例转绿；无无关重构。

回退

只读阶段无变更；编辑后用 git restore / git checkout -- .；保留复现笔记。

Real-World Ex · 日志过长，工具容易猜错

卡点与坑（Pain Point）

线上 500，栈追踪上百行。若把整段日志丢给 AI，它常会凭空猜测并乱改主业务代码，污染 Git 状态。

处理办法（Strategy）

先定位，不改代码：限定只读范围 → 查上游调用链（不猜）→ 给出 2 个假说和验证日志 → 你贴结果后再决定是否改。

实战 Prompt（Ex）

claude "项目在运行 `pnpm test:e2e` 时抛出以下错误： --- [ERROR LOG START] --- TypeError: Cannot read properties of undefined (reading 'user_id') at AuthMiddleware.process (src/middleware/auth.ts:42:21) --- [ERROR LOG END] --- 要求： 1. 先搜索并阅读 src/middleware/auth.ts 的第 30-50 行。 2. 找出导致 user_id 为空的最可能上游调用方（不要猜测，只找代码里的调用链）。 3. 给出 2 个可能的排查假说（Hypotheses），并告诉我需要打印什么 log 来验证。 4. 【严格约束】：不要修改任何文件！等我贴出日志验证结果后，再由我决定是否编辑。"

为什么这有用

强制把 AI 限制在「只读侦探」角色，防止它破坏 Git 状态；引导它给出验证手段，而不是直接抛一个可能带坑的 Patch。等日志验证完，再进入「最小改动 + 回归测试」阶段。

模板版提示词（通用）

Bug：…… 复现：…… 期望：…… 约束：最小改动；先定位再改；补 / 改一个回归测试。先给出计划，等我确认后再编辑。

03 · 新增小功能主编程 CLI 可选第二模型

目标

做垂直切片的小功能：可演示、可测、可回滚。

准备条件

用户故事 + 非目标列表；仓库内已有类似模块的路径。

示例提示词

功能：…… 非目标：…… 请先找仓库内最相似的实现并复用模式。交付：实现 + 测试 + 简短手测步骤。一次 PR 只做这一件事。

验收

手测步骤通过；类型检查 / 测试按项目脚本全绿。

回退

用功能开关，或整 commit revert；删除半成品分支。

04 · 编写并运行测试 Any CLI 测试框架

目标

为既有行为补测试，不趁机改生产逻辑。

准备条件

测试框架与命令已知（如 pnpm test）。

示例提示词

为 path/to/module 补单元测试，覆盖边界：…… 禁止改生产代码行为；若发现 bug 只开 issue 说明。跑：<项目测试命令>

验收

新测试失败 → 修复循环结束于全绿；无 snapshot 噪音。

回退

删除测试文件或 restore；生产代码应无变更。

05 · 渐进式重构 · 绞杀者（Real-World Ex） Codex Strangler Fig Real-World

目标

结构更清晰，行为与测试结果不变；每个 commit 都处于可工作状态。

准备条件

已有测试或可手测清单；明确「不准改」的对外 API；干净工作区（便于失败即 restore）。

你需要确认什么

大范围移动文件前先看计划；禁止顺手加功能；测试红了必须停并回滚，不许「越补越烂」。

验收

测试全绿；对外 API 签名不变；行为对照表逐项勾选；diff 可 Code Review。

回退

单步提取 + 单 commit；失败立刻 git checkout / git restore；便于 git revert。

Real-World Ex · 重构完测试全红，不敢提交

卡点与坑（Pain Point）

拆分 800 行遗留单体（Monolith）时，工具可能一次重写 10 个文件；测试全红，diff 也难以审查。

处理办法（Strategy）

绞杀者模式（Strangler Fig）配合单次 Commit 验证：一次只抽一个函数 → 原文件保留 re-export 和原签名 → 跑测试 → 通过后停下来检查 diff，失败就立刻撤销。

实战 Prompt（Ex）

codex "我们准备重构 `src/services/order.ts`。这个文件太大了，但不能破坏现有业务。请按以下步骤执行，一次只做一步：第一步：在 `src/services/order/` 下创建一个新文件 `calculator.ts`，仅把计算折扣逻辑 (`calculateDiscount`) 提取过去。第二步：在原 `order.ts` 中引用新模块，确保对外 API 签名 100% 保持不变。第三步：运行 `pnpm test src/tests/order.test.ts`。【严格约束】：如果测试通过，暂停并等待我检查 `git diff`；如果测试失败，立即撤销本次修改 (`git checkout`) 并告诉我哪里阻碍了提取，不要尝试强行修复！"

为什么这有用

给 AI 设定物理止损线。自动化测试没过就要求放弃，而不是越修越烂；保证每一个 Commit 都处于可工作状态，才敢继续下一步提取。

模板版提示词（通用）

重构 X，目标：降低嵌套 / 提取函数。约束：不改公共 API；每一步后跑测试；提交信息说明动机。一次只做一步；失败立即 restore，不要连环修补。

06 · 做代码审查 Any CLI 交叉验证

目标

按严重度列出正确性、安全、可测性风险，而不是重写代码。

示例提示词

请审阅 git diff / 指定 PR。输出：P0 / P1 / P2；每条含文件位置、风险、建议。不要直接改代码，除非我要求提供补丁草稿。

验收

你能根据清单决定「合并 / 打回」；没有空话。

回退

审查本身无写操作；忽略错误建议即可。

07 · 整理文档与 changelog Any CLI 文档

目标

用户向的更新说明 + 开发者向的变更要点。

准备条件

git log / PR 列表；版本号规则。

示例提示词

根据下列提交写 changelog（Keep a Changelog 风格）。区分 Breaking / Feature / Fix。标注需人工核实的高波动项（命令、价格）。

验收

抽 3 条对照真实 commit；不要发明未发生的功能。

回退

文档文件单独 commit，可独立 revert。

08 · 第一次接 MCP：只读一个外部资料 MCP Open Design Figma 只读优先

目标

只接一个 MCP，并确认它能读到正确资料：要么读一个 Figma 画板，要么列出一个 Open Design 项目的原型和变量。

准备条件

一个真实来源：可访问的 Figma Frame 链接，或本机已有的 Open Design 项目；备份当前 CLI 的 MCP 配置。没有这两种资料就跳过本节。

示例提示词

我要第一次接 MCP，只做只读验证。先告诉我你准备修改哪个配置文件，并展示配置 diff；等我确认后再写入。如果是 Figma：读取我给出的 Frame 链接，列出组件、变量和布局，不要修改 Figma。如果是 Open Design：先用 od mcp install --print 预览；接入后列出当前项目的原型和变量名称，不要修改文件。完成后说明怎样移除这项配置。

AI 将执行什么

读官方安装说明 → 生成配置片段 → 经你确认后写入当前项目配置 → 试一次只读调用。

你需要确认什么

配置写到哪里；是否要网页登录；本次连接能读取哪些资料；不要改成全局启用，也不要开写入权限。

验收

Open Design 能列出当前项目资料，或 Figma 能读到指定画板；输出来自正确项目，且没有文件或画布被修改。

回退

卡点与坑（Pain Point）

没有具体面板时，学习者很难对应组件层级和属性栏位置；OpenDesign / HTML 与 Figma 的标记、Token、代码变量也容易不一致，工具只能靠截图猜测，最后写死 #FFF / 16px。

处理办法（Strategy）

先统一 Figma 的语义命名和 kebab-case Variables，再从 Dev Mode / JSON Spec（或 OD MCP）读取资料，最后让 CLI 只改 token 绑定。下面三步都有可对照的面板图解（示意 UI，标注点对应真实 Figma 位置）。

1 · Figma 图层与 Local Variables 规范

在右侧 Design 面板建 Color / Number 变量库；图层名与 Open Design / HTML 组件名一致。禁止保留 Frame 4821 这类默认名。状态用 Variants：State=Default | Hover | Focus。

截图对照区 · 图层树 + Variables 示意 UI · 红框 = 必对齐命名

Layers Page 1

❖AppleTile

TTileKicker

TTitle

TDescription

□TileVisual

TTileCTA

—Frame 4821 ← 禁止

TText

Local Variables Collections · Design Tokens

Name	Value
bg-main	#F3EEE6
bg-surface	#FAF7F1
fg-main	#1A1A1A
radius-lg	22px
space-tile	clamp(28px, 4vw, 44px)

1左侧图层：组件根节点用 AppleTile，子层与 JSON children 同名。
2右侧 Variables：名称必须是 kebab-case（如 bg-main），对应 CSS --bg / --surface。
3位置：Figma → 右侧栏 → Local Variables → 你的 Design Tokens 集合。

路径：Figma → Right Sidebar → Local Variables · Layers 面板同步选中组件

2 · Dev Mode 与 OpenDesign / Spec 导出

切换 Dev Mode（Shift+D），选中 AppleTile，在 Inspector 看 CSS / 组件属性。目标是产出 AI 能读的结构化 Spec，而不是只丢一张 PNG。

截图对照区 · Dev Mode Inspector Code · CSS · Tokens

Inspect · AppleTile Dev Mode

backgroundvar(--surface)

border-radiusvar(--radius-xl)

paddingclamp(28px, 4vw, 44px)

variants.tonea · b · c · d

❌ hard-code#FFFFFF · 16px

childrenKicker · Title · …

1Inspector 里优先抄 token 引用（绿），不要抄被划掉的硬编码。
2导出 / 手抄 JSON Spec 到 design-specs/apple-tile.json（或经 Figma MCP / OD 读取）。
3位置：Figma → 右上角 Dev Mode → Inspect → CSS / Component Properties。

路径：Figma → Dev Mode (⇧D) → Inspect → CSS / Component Properties

design-specs/apple-tile.json · 喂给 CLI 的上下文

{
  "component": "AppleTile",
  "variants": { "tone": ["a", "b", "c", "d"] },
  "tokens": {
    "background": "var(--surface)",
    "borderRadius": "var(--radius-xl)",
    "padding": "clamp(28px, 4vw, 44px)"
  },
  "children": ["TileKicker", "Title", "Description", "TileVisual", "TileCTA"]
}

3 · 喂给 AI CLI 的防漂移 Prompt（Figma → Code）

把 Spec 嵌进提示词；约束「只改 CSS 变量绑定、不改 DOM」。若已接 Figma MCP / OD MCP，可让 agent 自己读文件与选中 frame，仍保留同样的硬约束。

claude "我刚用 Figma Dev Mode 导出了组件 Spec。请对照本地文件 `src/components/AppleTile.html` 与 `components/apple-tile.css`： 1. 检查 class 命名是否与 Figma Tokens 对应（如 var(--radius-xl)）。 2. 增加对 data-tone='d' 暗色卡片的类名支持。 3. 【严格约束】：只改动 CSS 变量绑定，不要修改任何 HTML DOM 结构。 4. 颜色与圆角必须全部使用 var(--…)，禁止硬编码 16px 或 #FFF。 5. 核对 :hover / :active 过渡是否匹配稿（约 300ms ease）。 --- [FIGMA SPEC JSON START] --- $(cat ./design-specs/apple-tile.json) --- [FIGMA SPEC JSON END] ---"

为什么这有用

打通 设计稿（Figma）→ 结构数据（Spec / Open Design）→ 自动化代码（AI CLI）：学习者能对着面板位置操作，不再摸黑；AI 有机器可读锚点，不会凭空发散色板与结构。

MCP 最短路径（可选）

# Figma claude plugin install figma@claude-plugins-official # 或 claude mcp add --transport http figma https://mcp.figma.com/mcp # Open Design 本地原型 od mcp install claude # 会话内先只读选中 frame / 读 OD 当前 artifact，再允许写 CSS

自检清单（还原后）

Figma 图层名 = HTML / OD 组件名
Variables 名可映射到 :root token（无同义冲突）
深色 tone-d 有独立前景色 token，不沿用浅色 --fg
git diff 无无关文件；无密钥 / file key

Project contract

仓库里的约定模板

AGENTS.md · template

# 项目约定（给 AI 与人类）

## 技术栈
- 语言 / 框架：……
- 包管理：pnpm
- 校验：pnpm typecheck && pnpm test

## 改动规则
- 先读再改；一次 PR 只做一件事
- 不新增未要求的依赖
- 密钥只走环境变量

## 禁止
- 不要提交 .env
- 不要改生成物目录

## 完成定义
- 有测试或手测步骤
- diff 可在 10 分钟内审完

Source ledger

资料台账（维护模板）

价格、模型名、配额、安装命令标为高波动；基础概念与教学结构标为低波动。社区来源不用于证明当前价格。

Product	Topic	Claim	Source level	Checked	Volatility
Codex	安装	npm i -g @openai/codex 是常见官方路径	Official	2026-07-23	高
Codex	订阅	CLI 可能包含在 ChatGPT 计划中；以 Pricing 页为准	Official	2026-07-23	高
Claude	安装	curl …/install.sh \| bash 是官方 Quickstart	Official	2026-07-23	高
Claude	工作流	CLAUDE.md / hooks / skills 是官方扩展点	Official	2026-07-23	中
Gemini	安装	见 @google/gemini-cli 官方仓库安装说明	Open source	2026-07-23	高
Gemini	配额	与 Code Assist / AI Studio 的关系需打开官方配额页核对	Official	2026-07-23	高
Grok Build	安装	x.ai/cli/install.sh；不是第三方 grok-cli	Official	2026-07-23	高
Grok Build	能力	TUI · Shell · Web 搜索 · headless · ACP	Open source	2026-07-23	中
通用	概念	Token / agent / sandbox / injection 的教学结构	Official	2026-07-23	低
通用	痛点	权限过宽、密钥进库、二手教程过期等常见痛点	Community	2026-07-23	中
OpenCode	安装 / 简介	anomalyco/opencode README.zh.md；npm 包 opencode-ai	Open source	2026-07-24	高
OpenCode	Releases / 源码	版本与变更看 GitHub Releases；可用 git clone --depth 1 只读浏览源码	Open source	2026-07-24	中
OpenCode	命名澄清	opencode-ai/opencode 已归档 → Crush；勿与本指南产品混装	Community	2026-07-24	高
OpenCode	配置 / Agent	build / plan（Tab 切换）；配置细节见 opencode.ai/docs 补充	Official	2026-07-24	中
通用	Git 安全网	练习分支 · status / diff · restore / revert · 禁 push / force · 密钥不入库	Community	2026-07-24	高
Open Design	MCP · 设计原型	od mcp / od mcp install <agent> 暴露本地项目	Open source	2026-07-24	中
Figma	MCP · 设计稿	远程端点 https://mcp.figma.com/mcp；Claude 可用官方插件	Official	2026-07-24	高
HelloAGENTS	Skills · 工作流层	hellowind777/helloagents：skills、交付检查、多 CLI	Community	2026-07-24	中
Figma × OD	设计还原 · Tokens	Variables kebab-case → Spec JSON → CLI 只绑 var(--…)；见 Playbook 12 面板图解	Official	2026-07-24	中

字段完整版还可加：Source URL · Screenshot needed · Tested · OS · Notes。高波动项建议每次发布前重新打开官方页核对。

回到首页，按卡片重走一遍

建议收藏本原型。换工具时重复：概念核对 → 订阅路径 → 官方安装 → 任务手册。

把 AI CLI用成你的工作流程

先定一个能验收的任务

选择你的订阅入口

完成一次可回退的首次运行

把成功步骤写成规则

先判断资料能不能信，再照着做。

不用先研究所有工具。先完成一件能检查的小事。

按你的起点走

这份指南不替你做决定

先弄清它能做什么，再选工具。

基础知识库

大语言模型

标记与上下文窗口

智能体与工具调用

三种界面，同一类能力

Model Context Protocol

技能、钩子与子代理

沙箱与权限确认

提示注入、密钥与仓库安全

为什么 CLI 要你确认每一步

五款 CLI（选型地图，不是排行榜）

Codex CLI

Claude Code

Gemini CLI

Grok Build

OpenCode

下一步：如何订阅

订阅入口，只有三种。

按你最常用的设备开通

Android

iPhone / iPad

网页

先找订单，再改设置

取消不等于立刻失效

换入口时别重新点购买

下一步：从这里开始

先完成一次可回退的首次运行。

开始前检查

终端与系统

Git 与练习仓

账号已就绪

Git 安全网（必做）

给 agent 的 Git 约束（可贴进提示词）

推荐练习仓来源

先定位问题，再重试；不要直接关掉权限或安全设置。

找不到命令

登录失败或 401

Node / 运行时不匹配

网络或权限被拒绝

Codex CLI

文档要点

验收

Claude Code

习惯

验收

Gemini CLI

配置系统

验收

Grok Build （命令：grok）

OpenCode

先计划，再动手

与 Git 一起用

最小安全配置（项目根目录）

统一验收清单（Smoke）

下一步：构建属于自己的工作流

按真实任务组织，不按产品堆功能。

四步日环

框定任务

先读项目约定

小步执行

记下可复用的做法

要用 MCP，先弄清它能帮什么。

第一次接 MCP，只做一件小事

什么时候值得装

什么时候先别装

Open Design MCP

适合的情况

Figma MCP

Figma 使用注意

HelloAGENTS

把 AI CLI
用成你的工作流程