一个插件标准，七个工具共用

图：Open Plugins 标准——装一个就能在七个工具里用

最近 AI 编程工具越来越多：Cursor、Claude Code、Codex、Grok Build……每个一套插件格式。然后冒出了个 Open Plugins。

它是 Vercel Labs 维护的一个开放标准。装一个插件，就能在七个工具里跑。

现状：AI 编程工具的"插件战国"​

先说问题。

图：各工具各说各话，夹不到一起

假设你有一组很好用的 AI 编程辅助工具：

• 一个代码审查 skill，每次提交前自动审查变更
• 一个 MCP 服务器，连接到公司的 API 文档
• 一个钩子脚本，保存文件时自动格式化

在 Claude Code 里配一遍，换到 Cursor 又得重新配，换到 Codex 格式可能还不一样。这就像 npm 出现之前的 JavaScript——每个库有自己的模块格式，想复用就得手动折腾。

Open Plugins 的目的就是终结这种割裂：定一套标准，所有工具共用。

npx plugins：怎么装​

怎么用？一条命令：

# 从 GitHub 安装插件（短格式）
npx plugins add vercel/vercel-plugin

# 完整 HTTPS URL
npx plugins add https://github.com/vercel/vercel-plugin

# 从本地目录安装
npx plugins add ./my-plugin

# 先看看有哪些组件，不实际安装
npx plugins discover owner/repo

# 查看本地已检测到的工具
npx plugins targets

这个 plugins 包（v1.3.4）就是 Open Plugins 生态的"安装器"。安装后的存储路径统一走 .agents/plugins/。

它的工作流程可以看作一条流水线：

支持的安装 scope 分为三档：

npx plugins add repo --scope user     # 用户级（~/.agents/plugins/）
npx plugins add repo --scope project  # 项目级（./.agents/plugins/）
npx plugins add repo --scope local    # 仅本地开发测试

还可以指定安装到某个特定工具：

npx plugins add owner/repo -t grok     # 只装到 Grok Build
npx plugins add owner/repo -t vscode   # 只装到 VS Code

支持七种 AI 编程工具​

npx plugins targets 会检测你机器上安装了哪些工具，然后自动安装到所有检测到的目标。

图：七种 AI 编程工具，一个插件标准全支持

不过，装完不等于每个组件都在所有工具里能用。这里有个关键认知——Open Plugin Spec v1 保证的只有两类组件：Skills 和 MCP。其他组件（Hooks、Commands、Agents）不在 v1 规范里，支不支持完全看宿主工具。

Spec v1 保证 → Skills + MCP（装完就能用）
Spec v1 不保证 → Hooks / Commands / Agents（宿主不认识就忽略，不报错）

来看看各工具的实际情况：

⭐ v1 = Spec v1 标准保证；✅ = 宿主额外支持；❌ = 不支持（宿主会静默忽略）

关键要点：

• Skills + MCP 是跨 IDE 通用协议，装到哪个工具都能用——这是我们推荐 npx plugins add 的根本原因
• Hooks 不是全员标配。Claude Code 和 Copilot CLI 支持最完整，VS Code 和 Kimi Code 就不认
• Claude Code 通过原生 marketplace 机制支持最全（hooks + commands + agents），但那是宿主能力，不是 v1 标准
• 不支持 Hooks 的工具会静默忽略，不会报错，插件仍然能正常工作

协议拆解​

一个插件其实就是按约定结构放了一堆文件的目录。

标准目录结构​

安装后的存储路径分两个 scope：

~/.agents/plugins/          # 用户级
<project>/.agents/plugins/  # 项目级

plugin.json 清单文件​

清单文件是可选的。如果省略，插件名称从目录名派生，组件只在默认位置发现。

如果提供，name 是唯一必填字段：

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "插件描述",
  "author": {
    "name": "Author",
    "email": "author@example.com"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["code-review", "automation"]
}

name 的命名约束：1-64 字符，小写字母/数字/连字符/点号，字母数字开头结尾，禁止 -- 或 ..。✅ deployment-tools、code-reviewer、prompts.chat ❌ My-Plugin、-tools、my--plugin

组件发现算法​

这是协议最核心的部分。工具扫描插件的完整流程：

插件的四步生命周期——从安装到激活：

图：插件的安装、发现、命名空间和激活流程

${PLUGIN_ROOT} 路径展开​

插件内的所有配置文件中都可以使用 ${PLUGIN_ROOT}，工具加载时自动替换为插件根目录的绝对路径。这个机制让插件可以自包含——所有路径引用都相对于自身，装到任何位置都能工作。

{
  "mcpServers": {
    "db-server": {
      "command": "${PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${PLUGIN_ROOT}/data"
      }
    }
  }
}

扩展规则：递归展开，嵌套引用也会被替换；逃逸检查保证路径不超出插件目录。

实战：把 CloudBase MCP 改成 Open Plugins 插件​

前面讲了一堆理论，来点真实的。

我们最近在维护一个叫 CloudBase MCP 的开源项目，给 AI 编程工具提供云接入能力——AI 模型调用、NoSQL/PostgreSQL 数据库、云函数、云托管、云存储、微信小程序对接等等。以前手动配 .claude-plugin/、.codex-plugin/、.mcp.json，每个工具一个配置，维护起来头大。这次正好借 Open Plugins 标准的东风，做了一次改造。

完整改造 PR：TencentCloudBase/CloudBase-MCP#808（+818 / -34）

图：PR #808 改造前后对比——从 vendor 专属格式到通用插件标准

改造前后对比​

plugin.json​

按照 Open Plugins 规范 v1.0.0 的 closed schema，只保留规范允许的元数据字段：

{
  "$schema": "https://open-plugins.com/schemas/1.0.0/plugin.schema.json",
  "name": "cloudbase",
  "version": "0.2.0",
  "description": "Tencent CloudBase — AI models, authentication, NoSQL/PostgreSQL databases, cloud functions, cloud storage, CloudRun backend services, and WeChat Mini Program integration.",
  "author": {
    "name": "Tencent CloudBase",
    "url": "https://cloudbase.net"
  },
  "homepage": "https://github.com/TencentCloudBase/cloudbase-mcp",
  "license": "MIT",
  "keywords": [
    "cloudbase", "tencent-cloud", "baas",
    "ai-model", "database", "cloud-function",
    "authentication", "storage", "cloudrun"
  ]
}

mcp.json​

MCP 服务器配置从 .mcp.json 复制到规范路径 mcp.json：

{
  "mcpServers": {
    "cloudbase-mcp": {
      "command": "npx",
      "args": ["-y", "@cloudbase/cloudbase-mcp@latest"],
      "env": {}
    }
  }
}

自动化构建​

写了 build-open-plugin-spec.mjs 构建脚本，从 .claude-plugin/plugin.json 自动生成产物。还加了 --check 模式跑在 CI 里——每次 PR 自动校验，防止改源码忘了更新。

# 生成产物
node scripts/build-open-plugin-spec.mjs

# CI 模式：只检查不写入
node scripts/build-open-plugin-spec.mjs --check

配了 GitHub Actions workflow（.github/workflows/open-plugin-spec-check.yml），PR 自动跑检查。

验收结果​

最大的成就感是一行命令装到所有工具：

npx plugins add TencentCloudBase/cloudbase-plugin

而且因为之前就已经在 skills/ 目录下放了 4 个 Skill，npx plugins discover 自动把它们注册为命名空间下的命令：

不用多写一行配置，按规范放目录就行。

第一个坑：marketplace.json 冲突​

PR #808 合进去之后，兴冲冲跑 npx plugins add TencentCloudBase/CloudBase-MCP，结果：

No plugins found. 2 remote plugin(s) not shown.

插件就在仓库里，但 CLI 说找不到。

查了半天发现原因：主仓库根目录有一个 marketplace.json，这是给 Claude Code 和 Codex 的 marketplace add 用的索引文件。npx plugins CLI 检测到它后，把整个仓库识别为 marketplace（多插件集合），拒绝安装其中的子目录插件。

解决方案：创建专门插件仓库

参考 Vercel（vercel/vercel-plugin）和 Supabase（supabase-community/supabase-plugin）的做法——建专门的插件仓库，根目录只有 .plugin/plugin.json，没有 marketplace.json，让 CLI 识别为单插件。

创建了两个仓库：

内容从主仓库 plugin/cloudbase/ 和 plugin/cloudbase-sites/ 自动同步，同步时排除 marketplace.json——这是关键。

自动化同步机制

新增了这些文件：

验证全部通过：

npx plugins discover TencentCloudBase/cloudbase-plugin --remote
# → ✅ Found 1 local plugin(s), 28 skills, 5 cmds, 2 agents, hooks

npx plugins add TencentCloudBase/cloudbase-plugin --target cursor --scope local
# → ✅ Installed

npx plugins discover TencentCloudBase/cloudbase-sites-plugin --remote
# → ✅ Found 1 local plugin(s), 1 skill, hooks

现在的安装命令统一指向专门仓库：

# 主插件
npx plugins add TencentCloudBase/cloudbase-plugin

# Sites 插件
npx plugins add TencentCloudBase/cloudbase-sites-plugin

这个坑的核心教训是：Open Plugins 会把根目录有 marketplace.json 的仓库当作插件集合，而非单插件。 如果你的仓库本身就有多个发布物（像 CloudBase-MCP 既有 MCP 服务器又有插件），需要建专门的插件仓库。Vercel 和 Supabase 也是这样做的。

Hook 系统​

我看规范时觉得最值钱的部分是这个——Hook 能在 agent 工作流的各个生命周期点插一脚。不过注意：Hook 不在 Spec v1 标准里，支不支持全看宿主工具。Claude Code 和 Copilot CLI 支持最全，VS Code 和 Kimi Code 就不认（静默忽略，不报错）。

下面讲的事件模型来自 Open Plugin Spec 的 Hooks 组件规范——如果你的宿主工具支持 Hooks，这就是它的工作方式。

图：Hook 系统——从 SessionStart 到 SessionEnd 的完整事件链

事件全景​

三种 Action 类型​

command — 执行外部脚本，事件上下文通过 stdin JSON 传入：

{ "type": "command", "command": "${PLUGIN_ROOT}/scripts/lint.sh" }

prompt — 向 LLM 发送提示词，$ARGUMENTS 替换为事件上下文：

{ "type": "prompt", "prompt": "Review the change: $ARGUMENTS" }

agent — 类似 prompt 但带工具访问权限，可以做多步验证：

{ "type": "agent", "prompt": "Verify style guide compliance: $ARGUMENTS" }

执行模型​

• 多个规则可以匹配同一个事件，全部执行
• 同一规则内的 hooks 按数组顺序串行执行
• 实现端应该设置超时
• 失败不能 crash 宿主工具

给你的工具加上 Open Plugins 支持​

如果你自己做 AI 编程工具、想让插件生态兼容 Open Plugins，需要实现五条：

五大核心能力​

不同工具的集成方式​

每个工具现有的插件机制不同，npx plugins 在安装时做了一层翻译——把通用 .plugin/ 格式转成各工具自己的原生格式：

安全防护模型​

一些感受​

Open Plugins 让我想起十年前 npm 刚流行的时候。JavaScript 的包管理也是一团乱麻：AMD、CommonJS、UMD、IIFE……每个项目有自己的一套。后来 npm + ES Modules 统一了标准，整个生态起飞了。AI 编程工具的插件生态，现在就处在那"前 npm"时代。

这次给 CloudBase MCP 做改造是个挺有意思的过程。从 npx plugins discover 识别出插件，到一行命令装到所有工具，那种"写一次到处用"的感觉，恰好就是这个标准想解决的问题。

图：npx plugins add TencentCloudBase/cloudbase-plugin——一行命令装到所有工具

如果你也在做 AI 编程工具的扩展，推荐看看 Open Plugins 规范。好消息是不用搞多复杂——项目里加个 .plugin/plugin.json，你的插件就能被 7 种工具识别。我们的改造也就四百来行代码，两天不到搞完。

CloudBase-MCP 对应的插件在这两个仓库，供参考：

npx plugins add TencentCloudBase/cloudbase-plugin
npx plugins add TencentCloudBase/cloudbase-sites-plugin

Open Plugins 还没到"成熟"那一步，但方向是对的。能让同一份插件在不同工具之间跑，这个问题本身值得被认真解决。剩下的就看社区怎么长出来了。

参考链接​

• Open Plugins 官网
• plugins npm 包 — npx plugins add 的安装器
• Agent Skills 规范
• Model Context Protocol
• CloudBase Plugin — Open Plugins 标准插件仓库
• CloudBase Sites Plugin — Sites 插件仓库
• CloudBase MCP — 腾讯云开发 MCP 插件
• PR #808: CloudBase MCP 集成 Open Plugin 规范

让 AI 把 fetch 全换成 axios，泡了杯咖啡回来，发现它改了三四个文件就停下来等你点头。反复七八次，一杯咖啡都凉了

或者睡前跑了 /loop 盯 PR，早上发现它凌晨两点卡在 git merge 冲突上，窗口占了一整夜

或者开了三个 sub-agent 各查各的——完事三个结论互相矛盾，因为它们都没看到对方在做什么

根不在 AI 不够聪明。Claude Code 是回合制的——每轮只能做一件事，做完等你决定下一步。想让它持续运行、自动决策、并行工作，就得靠产品层面的编排机制来弥补

Claude Code 给了五个：/goal、/loop、sub-agent、Agent Teams、Workflows

选错了不仅浪费 token，还会把事情搞得更复杂

痛点一：我在等它，它在等我​

你给 AI 一个明确目标，它有能力完成，但每一轮做完都停下来等你批准。这就是 /goal 要解决的问题

/goal — 条件引导的自主轮询​

/goal 完成 data-editor 的测试经验泛化为全模块标准测试框架，分三步：
  Step 1: 创建共享 test-utils.sh
  Step 2: 为每个模块创建 verify-*.sh
  Step 3: 更新验收标准

底层是轻量级的 Stop Hook：往 sessionHooksRegistry 注册一个 type: 'prompt' 的 hook，每个 turn 结束后触发一次评估

评估模型拿到三样东西：

1. 目标条件——你写的 /goal 描述
2. 对话 transcript——从 goal 设定时刻之后的所有对话
3. 元信息——session ID、时间戳、权限模式等

输出是结构化 JSON：

{"ok": false, "reason": "Step 1 已完成，test-utils.sh 已创建，但 Step 2 还未开始"}

ok: true → stop，ok: false → 带着 reason 继续下一轮

关键设计：干活的和做检查的是两个模型，避免了主模型一边干活一边给自己打分。评估器只看 transcript，不做执行，所以能客观判断

局限也很明显：

• 串行的——一次跑一个 turn，只是省了手动回车
• 评估器不可观测——没日志告诉你为什么判定通过或失败
• 每个 turn 的 transcript 都传给评估器，对话越长评估成本越高
• 评估模型延迟叠加到每个 turn 上，选 Haiku 省时间，选 Sonnet 保准确

适用边界​

适合：目标有明确终态的任务，过程可能跨多轮，你不想坐在旁边看着

不适合：需要持续监控的（用 /loop），目标是发散探索性质的

有个细节：评估模型可以换。目标复杂度高就用 Sonnet 做评估，反之用更小的模型省成本

需要 v2.1.139+

痛点二：项目放着不管就长草​

很多场景没终点——PR 需要持续关注、CI 挂了要处理、依赖要升级。你不可能一直盯着终端。但一个不盯着，就可能卡一整夜

/loop — 自适应调度器​

/goal 关心"做完了没"，/loop 关心"现在有什么需要做"

不加参数执行三段式管线：

1. 把没做完的收尾
2. 检查当前 PR 评论、CI 状态、合并冲突
3. 跑 lint、类型检查、格式化

间隔动态调整：状态活跃时 1 分钟一轮，闲下来慢慢延长到 1 小时

/loop          # 自适应模式（日常推荐）
/loop 15m      # 固定 15 分钟
/loop 2h       # 固定 2 小时

三段式不是硬编码逻辑，是内置 prompt 模板，Claude 自己决定该执行哪一步。自适应间隔也靠 Claude 对"刚才发生了什么"的感知，不是外部指标（CI、CPU、日志）

这个限制解释了为什么 Bedrock、Vertex AI、Azure Foundry 上自适应不可用——退化为固定 10 分钟。这些平台的 API 不支持"由模型决定间隔"的通信模式

代价：/loop 跑在同一个 session 里。第 10 轮的上下文比第 1 轮臃肿得多——塞了前 9 轮的产物。开销在递增，注意力在被稀释。不是 loop 本身费钱，是 session 在老化

痛点三：主上下文被灌了一堆垃圾​

一个 session 跑久了，上下文里塞满中间产物——查过的文档、试过的方案、反复修正的路径。token 越花越多，模型越来越"笨"。但你的辅助工作（查 API、调研库、验证猜想）不该污染主线

Sub-Agent — 上下文隔离的工人​

sub-agent 解决的是"主上下文宝贵"的问题。每个 sub-agent 启动时拥有全新的 context window，看不到你的对话历史，做完只返回摘要，不污染主会话。嵌套限制 5 层，硬编码不可配置

隔离机制（源码来自 forkedAgent.ts）：

• 独立的 AbortController：父会话取消不影响 sub-agent，反之亦然
• 无状态传播（no-op state propagation）：父会话不传递任何内部状态。sub-agent 连父会话用了哪些工具都不知道。想让 sub-agent 知道某个上下文，必须显式通过 prompt 传入

5 层限制的理由很实际——每层嵌套开一个新 LLM session，深度 5 意味着同时维护 5 个 session 的 token 开销。超出深度的 sub-agent 不会收到 Agent 工具，等于被静默拒绝

三种创建方式​

# 方式一：一次性的
/agent 去调研下这个函数的调用链路

# 方式二：配置文件（持久化）
# .claude/agents/researcher.yaml
name: researcher
description: 专门做技术调研的 agent，擅长读源码、查文档
prompt: 你专注于调研...
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit]

# 方式三：SDK 创建
const agent = claude.subAgent({ prompt: "..." });

配置文件的 description 字段有特殊作用——Claude 会根据描述内容自动决定什么时候该委派任务

什么时候用​

团队里的 sub-agent​

多人协作时，项目级 .claude/agents/ 目录可以 git 共享。团队成员 push 自己配的 agent，其他人 pull 下来就能用。这个机制让 agent 配置变成了工程资产——跟 .claude/rules/ 一样，是项目的一部分

痛点四：十个活挤在一起干​

/goal 跑一个任务，sub-agent 处理一个子任务。但你有十个活要干——修 bug、重构模块、写文档、准备 demo。不可能一个一个来，也不能让它们互相踩

Agent Teams — 可观察的并行​

Claude Code v2.1.166+ 引入的功能。核心是用独立 session 跑每个任务，互不干扰。主 session 创建任务时指定 agenda（类似 job description），Team 层负责调度

关键行为：

Task → sub-Agent session（独立，不可见）
       ↕
Task → sub-Agent session（独立，不可见）
       ↕
Main session ← 可观测 ← 各 Agent 汇报

相比 sub-agent，Teams 多了三层：

1. 可观测性——主 session 能看到各个 Agent 的实时进展
2. 并行执行——各 Agent 跑在各自的 session 里，真正的并行
3. 被动调度——不用显式写什么时候做什么，系统自动决定

子任务分配规则​

主 session 拆解任务并分发，拆法不是固定的提示工程，是模型自己的判断。给一个 agenda 说"重构 user 模块"，它自己决定怎么拆

对主任务的"理解"就来自拆解的粒度：粗就代表它没真正理解，细就代表它理清了依赖关系

调试难题​

独立的 session 也意味着独立的 token 消耗。不出问题还好，出问题你根本不知道是哪个 Agent、哪一步、为什么。没有全局日志，每个 session 的输入输出只能单独看

官方在同一个 TUI 里展示，但独立的 session 数据只能通过主 session 间接查看，没有中心化的调试视图。这是并行化天然要付出的代价

痛点五：一个复杂任务靠纯对话推不动​

有些任务不是"干就完了"，而是多个步骤环环相扣——先调研，再设计，再编码，再测试。任何一个步骤出偏差，后面全歪。没有个框架约束，纯靠模型自由发挥，结果就是"第一次成功，第二次不行"

Workflows — 确定性的工作流​

Workflows 是 Claude Code 最近推的机制，用声明式 YAML 定义多 Agent 协作的拓扑结构。跟 Teams 的区别不在谁厉害，在编排哲学不同：

Workflows 的阶段定义：

name: "feature-dev"
agents:
  design:
    model: claude-sonnet-4-20260514
    prompt: "你负责技术设计..."
  implement:
    model: claude-sonnet-4-20260514
    prompt: "你负责实现..."
  review:
    model: claude-sonnet-4-20260514
    prompt: "你负责代码审查..."

steps:
  - agent: design
    output: DESIGN
  - agent: implement
    input: DESIGN
    output: CODE
  - agent: review
    input: CODE
    output: REVIEW

每个 step 的 output 是上个 step 的输出路径，input 是当前 step 的输入。链条清晰，出了问题知道在哪一步断的

Workflows 里的任务类型​

内置三种：

• feature — 串行步进
• swe — 专门针对软件工程的多轮循环（设计→编码→测试→修复→审查）
• research — 探索性研究（不是多步，是让 agent 自己探索）

决策指南：什么场景用什么？​

                    你的痛点是什么？
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
  每轮确认太烦        不能一直盯着         任务太复杂
   /goal               /loop               Workflows
          │                │
          ▼                ▼
   主上下文爆了        十个活挤一起
   sub-agent           Agent Teams

具体来说：

• 单个明确目标，过程可能跨多轮 → /goal（串行自主，最轻量）
• 没终点，需要持续关注 → /loop（自适应，但注意 session 老化）
• 辅助工作不应污染主上下文 → sub-agent（隔离最彻底）
• 同时做多件事，互不依赖 → Agent Teams（真正的并行）
• 质量要求稳定，步骤环环相扣 → Workflows（确定性最高）

写在后面​

这些痛点的共同来源不是 Claude Code 的功能缺陷，而是我们让 AI 做它设计上不擅长的事——持续运行、自主决策、并行协作。/goal 把回合制伪装成持续执行，/loop 把等待包装成自适应调度，sub-agent 用隔离对抗膨胀。每个机制都在弥补回合制模型的局限

补丁思维看，它们确实是 hook 和 session 层面的包装。但换个角度，Claude Code 没有重新发明运行时，而是在回合制上用最轻量的方式（hook、新 session、JS 沙箱）递进出编排能力的光谱——从简单到复杂，从串行到并行

回合制不是缺陷，是约束。每次 turn 交回控制权，意味着可中断、可审计、可干预。持续执行的系统出问题很难喊停。回合制给了一个天然的安全边界

编排是妥协的艺术。想要可预测性？用 Workflows，放弃灵活性。想要隔离性？用 sub-agent，接受上下文同步成本。没有完美机制，只有取舍

最贵的不是 token，是你的注意力。省掉你盯着终端的时间，比省几个 token 更有价值。释放认知带宽才是这些机制真正的价值

彩蛋：一份可以直接用的 agent 配置包​

上面讲了五种机制，但最有用的事情是帮你配好。这是我目前在用的 .claude/agents/ 配置——三个配置好的 Agent，各自管一件事：

1. researcher — 纯调研，不改代码

# .claude/agents/researcher.yaml
name: researcher
description: 专门做技术调研的 agent，擅长读源码、查文档、验证猜想
prompt: |
  你是一个技术调研助手。
  你的工具权限限制为只读：可以 Read、Grep、Glob，但不能 Edit、Write、Bash（除了非破坏性命令）。
  你收到的任务格式是：
    ## 调研目标
    [要搞清楚的问题]
    
    ## 背景
    [相关代码/文档的定位]
  调研完成后输出：
    - 核心发现（3-5 条）
    - 证据来源（文件路径 + 行号）
    - 推荐方案或下一步
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit, Bash]

2. reviewer — 代码审查，不改代码

# .claude/agents/reviewer.yaml
name: reviewer
description: 代码审查，侧重安全、性能、可维护性
prompt: |
  你是一个代码审查助手。
  你只读不改。收到 PR diff 或代码块后，按以下维度审查：
  1. 安全隐患（SQL 注入、XSS、凭据泄露）
  2. 性能问题（N+1 查询、不必要的循环、内存泄漏）
  3. 可维护性（重复代码、命名、复杂度）
  4. 测试覆盖（缺什么测试、怎么补）
  每条问题标注严重程度：P0(必须修) / P1(建议修) / P2(可以以后修)
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit]

3. refactorer — 专注重构，全权限

# .claude/agents/refactorer.yaml
name: refactorer  
description: 代码重构 agent，处理有明确范围的重构任务
prompt: |
  你是一个重构助手。
  你接收一个明确的模块路径 + 重构目标。
  规则：
  - 重构前必须先在当前目录跑一次测试，确认基线通过
  - 每次修改后跑相关测试，失败立即回退
  - 不改模块边界之外的文件
  - 重构完成后输出变更摘要
allowedTools: [Read, Write, Edit, Bash, Glob, Grep]

用法： 把这些文件放到项目根目录的 .claude/agents/ 下，然后在 Claude Code 里用 /agent researcher 或 /agent reviewer 直接调。配置文件 Push 到仓库后团队都能用。

你现在用什么场景在用这些机制？踩过什么坑？评论区聊聊 :)

全文基于 Claude Code 实际使用 + 源码分析（forkedAgent.ts / sessionHooksRegistry / DynamicWorkflow testing 等），持续更新

这篇文章帮你搞懂四件事：① Codex 是什么、能干什么 → ② 五分钟上手做个能玩的小游戏 → ③ 基本用法和核心功能 → ④ 接低成本的国产开源模型，把做好的应用发布上线，让别人能访问。

赶时间？ Codex 现在能接 DeepSeek、GLM 这些便宜模型了。想省钱 + 一键部署的，跳到第四步复制一段配置就行。想从头搞懂的，往下读。

图：文章配图

第一步 · 先认识它​

Codex 是 OpenAI 推出的 AI 编程桌面工具，2026 年上半年周活从 60 万涨到了 500 万。涨得快，4 月 Sam Altman 直接在 X 上发帖"重置所有用户限额，每多 100 万再重置一次"。最值得注意的是：现在大约 20% 的用户根本不写代码，是产品、运营、做投资的人。

跟你的关系直接：6 月 18 日 OpenAI 放开了第三方模型，DeepSeek、GLM、Kimi 都能接——用便宜的国产模型跑，成本能压下来一大截。

它跟 ChatGPT 有啥不一样？​

不少人第一反应："这不就是个会写代码的 ChatGPT 吗？"差远了。

ChatGPT 是对话式的——你问它答，它给你建议，但活还得你自己干。Codex 直接在文件系统上工作。你告诉它"写一个贪吃蛇游戏"，它自己创建文件、装依赖、运行调试。

举个例子：你让 ChatGPT 写贪吃蛇，它给你一段代码，你得自己新建文件、粘贴、装库、运行、找错。你让 Codex 写贪吃蛇，它直接创建一个项目文件夹，生成代码，安装依赖，运行游戏。如果报错了，它会自己读错误信息，改完再跑，直到能玩为止。

ChatGPT 是顾问，Codex 是帮你干活的。

第二步 · 五分钟上手，做个能玩的小游戏​

装好它：下载 · 登录 · 认识界面​

去 codex.com 下载桌面 App，用 OpenAI 账号登录。

界面不复杂，就三块：

• 左侧：项目文件列表
• 中间：对话窗口 + 代码编辑器
• 右下：终端（能看到它在干什么）

第一个任务：一句话，让它做个贪吃蛇​

打开 Codex，在对话框里输入：

用 Python 写一个贪吃蛇游戏，要用 pygame，能直接运行

说完它就开始干了。注意看中间区域——它会先创建文件、写代码，然后自动运行。

可能第一次报错（比如没装 pygame），它会自己发现问题，装好依赖再试一次。最终你会看到一个窗口弹出来，贪吃蛇已经能跑了。

从打开 Codex 到玩上游戏，快的话 五分钟。

第三步 · 动手之前，先搞懂这些​

① 三档权限：决定它能动你多少东西​

Codex 有三档权限来控制它的行动范围：

• Clipboard Only：只读剪贴板，啥也动不了，安全但没用
• Read & Write Files：能读写文件，干活的基本盘
• Admin：能装软件、改系统设置

默认是 Read & Write，日常够用了。做游戏、写代码、部署都用这个。

② 插件 · 技能 · MCP：三个最容易搞混的词​

这三个不是同一个东西：

• 插件（Plugin）：Codex 能调用的外部 API，比如连数据库、发消息、查天气。Codex 自己就内置了几十个。
• Skill：教 Codex 怎么干活的一套指令。你写好一个 Skill，下次吩咐一句话，它就知道整套流程怎么走。
• MCP Server：一个通用接口，让 Codex 能跟外部工具通信。

③ 招牌技能 Skill：教它一次，以后一句话复用​

举个例子，你想让 Codex 每次写代码时都跑测试、检查类型、格式化代码。写一个 Skill：

## 代码质量规则

在完成任何代码修改后：
1. 运行 `npm test`，确保所有测试通过
2. 运行 `npx tsc --noEmit`，确保没有类型错误
3. 运行 `npx prettier --write .`，格式化代码

存成 Skill，下次说"用我的质量规则跑一遍"，它就按你说的做。

插曲 · 它远不止写代码​

⏰ 定时自动干活​

Codex 可以设定时任务：每天早上 9 点跑测试，每周一更新依赖。你睡觉的时候它帮你做这些杂活。

🚀 一键部署网站​

写好的网页，跟 Codex 说一声它就能部署。配上 MCP 插件，它能直接连云服务。

📱 手机远程遥控​

Codex 有手机 App，能随时看任务进度、发新指令。通勤路上看到 bug，直接手机发指令让它修。

📄 顺手生成文档和图片​

画架构图、写更新日志、生成配图——都能干。

第四步 · 用便宜的国产模型，把游戏部署上线​

先说那个坑：想接国产模型省钱，却卡住了​

Codex 默认用 OpenAI 自己的模型，对于日常开发完全够用。但如果你想跑大量自动化任务或者团队协作，Token 消耗很快就上去了。

6 月 18 日 Codex 开放了第三方模型接入。但有个问题：你要自己搞定 API Key、模型配置、部署环境。

解法：CloudBase（配模型 + 装插件）​

CloudBase 是腾讯云的 Serverless 平台，它的 AI Toolkit 正好解决了这个问题。

配模型（5 分钟）​

CloudBase 兼容 OpenAI 的和 Anthropic 的协议，DeepSeek、GLM、Kimi 用一个 Key 打通。配置好之后，Codex 里直接选国产模型就行，Token 成本能降到原来的十分之一以下。

装插件（让它能直接部署）​

CloudBase MCP 插件装了之后，Codex 就能直接在对话里把应用部署上线。不需要手动登录云控制台、配置域名、传文件。说一句"帮我部署到线上"，它就自动办完。

写在最后​

Codex 这半年证明的事：AI 工具拼的早就不是"能不能答题"，而是"能不能把活干完、把东西交付出来"。

对我这种普通人，真正的坎也不是"有没有便宜模型"，而是接进来麻烦、做完没地方部署。协议要对得上，上线要有地方落。踩完一圈，我现在的答案就是 CloudBase：三种协议都兼容，国产模型一个 Key 全打通，写完还能在同一个窗口里部署。

别处的 Token Plan 只给你 Token，CloudBase 还给你上线的地方。

你用过 Codex 吗？是拿它写代码，还是干别的活？评论区聊聊，我都会回。

• 没有浏览器（远程服务器，没图形界面）
• 没有 sudo 权限（只能装到自己 ~/bin）
• 需要 gh 能正常认证、创建 PR
• 关键：不能把 Token 直接发给 Agent——不管走什么通道，Token 一旦进了 Agent 的上下文就会被记录、可能被写入日志、甚至出现在训练数据里

传统 OAuth 流程要在浏览器里跳转。这里行不通。

第一个直觉是手动生成 Personal Access Token，gh auth login --with-token 灌进去。能用，但很麻烦——你要打开 GitHub 设置页、找到 Token 生成页面、选权限、复制、回到终端粘贴。隔几个月 Token 过期了，再来一遍。

我翻了翻 GitHub CLI 文档，发现它默认走的是一条不同的路：Device Flow（设备授权流）。执行 gh auth login --web，终端打印一串验证码，你去另外一台设备上打开 github.com/login/device 输入它，这边自动完成认证。

整个流程不到两分钟。当时觉得——这东西挺聪明的，值得拆开看看里面怎么跑的。

图：文章配图

部署场景：无 sudo 装 gh​

先把环境搭起来。这台服务器的情况很典型：

# 无 sudo，手动装 gh
mkdir -p ~/bin
cd /tmp
curl -fsSL https://github.com/cli/cli/releases/download/v2.62.0/gh_2.62.0_linux_amd64.tar.gz -o gh.tar.gz
tar -xzf gh.tar.gz
cp gh_2.62.0_linux_amd64/bin/gh ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/bin:$PATH"
gh --version

装完之后跑认证：

gh auth login --web --hostname github.com --git-protocol https

终端输出：

! First copy your one-time code: BFEE-895F
Open this URL to continue in your web browser: https://github.com/login/device

我在笔记本上打开链接，输入验证码，点击授权。回到终端按回车——

✓ Authentication complete.
✓ Logged in as binggg

结束了。没有配 SSH 密钥，没有手动填 Token，没有 sudo。

但这里有个细节我盯了很久：终端只是打印了一串验证码然后开始轮询，是怎么知道我在浏览器上完成了授权的？ 这一段通信完全发生在客户端和 GitHub 服务器之间，浏览器全程没跟终端说过一句话。

这就是 Device Flow 有意思的地方。

设备授权：把"登录"从设备上抽走​

Device Flow 的核心想法其实很简单。

传统 OAuth 授权码流程假设用户有一个浏览器，应用可以重定向用户到授权页面再跳回来。但智能电视、CLI 工具、IoT 设备——这些设备根本没有浏览器，或者有浏览器但输入 URL 极其痛苦。

解决方式：让用户在另一台设备上完成授权，设备自己轮询等结果。

我后来翻了 RFC 8628 标准文档，发现整个流程可以拆成四个步骤：

Step 1：设备请求验证码​

CLI 向授权服务器发一个 POST，告诉它"我想走设备流认证"：

POST https://github.com/login/device/code
client_id=xxx&scope=repo,gist

服务器返回一堆东西：

{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "BFEE-895F",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}

关键就三个字段：

• user_code（BFEE-895F）— 你要手动输入的那个验证码，8 字符，人类友好
• device_code（40 字符）— 客户端内部用的，不展示给用户
• interval（5 秒）— 服务器建议的轮询间隔

Step 2：你去浏览器干活​

终端打印验证码，你在手机上打开 github.com/login/device，输入它。这时候浏览器和 GitHub 服务器之间走了完整的 OAuth 授权——你登录、看权限、点 Authorize。

注意：这一步跟终端没有任何直接通信。你手机浏览器不知道终端的存在，终端也不知道你在手机上干了什么。

Step 3：设备不断轮询​

这是最巧妙的一步。终端不知道你什么时候点完授权，所以它每隔 5 秒问一次服务器："他点了吗？"

POST /login/oauth/access_token
device_code=xxx&grant_type=urn:ietf:params:oauth:grant-type:device_code

没点完：

{"error": "authorization_pending"}

你点了：

{"access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a", "scope": "repo,gist"}

轮询不是无线循环。device_code 只有 15 分钟有效期，超时了要重新来。客户端收到 expired_token 错误就必须停下来报错。

Step 4：拿着 Token 干活​

拿到 token 之后就跟普通 OAuth 一样了：

curl -H "Authorization: Bearer gho_xxx" https://api.github.com/user

轮询策略：客户端的"礼貌"有多重要？​

实际写轮询代码时，interval 和错误处理上有一些我没想到的门道。

RFC 8628 定义了 5 种错误码，每个对应不同的客户端行为：

slow_down 是我觉得最体贴的设计——很多协议限流就直接 429 断连接了，Device Flow 专门留了一个错误码告诉客户端"不是不让你问，是慢一点问"。实现时收到这个错误要在当前间隔基础上加 5 秒。

正确的轮询代码大概长这样：

import time, requests

def poll_for_token(device_code, client_id, interval=5):
    timeout = 900
    elapsed = 0
    
    while elapsed < timeout:
        r = requests.post(
            "https://github.com/login/oauth/access_token",
            data={
                "client_id": client_id,
                "device_code": device_code,
                "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
            },
            headers={"Accept": "application/json"}
        )
        data = r.json()
        
        if "access_token" in data:
            return data["access_token"]
        
        err = data.get("error")
        if err == "authorization_pending":
            time.sleep(interval)
            elapsed += interval
        elif err == "slow_down":
            interval += 5  # 加 5 秒
            time.sleep(interval)
            elapsed += interval
        elif err in ("expired_token", "access_denied"):
            raise Exception(f"授权失败: {err}")
        else:
            raise Exception(f"未知错误: {err}")
    
    raise Exception("授权超时")

有两个点容易被忽略：

1. 收到 slow_down 后，新增的 5 秒是永久累加的。不是恢复原来的间隔，而是从 interval + 5 开始。这是 RFC 8628 的要求。
2. 轮询期间理论上可以展示进度反馈。gh auth login 默认是在等，实现里可以加个 spinner 或者倒计时，至少让人知道程序还在跑。

Device Flow vs 传统 OAuth​

读完 RFC 8628 后我画了一张对比表：

GitHub CLI 选择 Device Flow 的理由很实际：CLI 可能跑在 Docker 容器、CI 环境、跳板机——这些地方没有浏览器，配回调 URL 也麻烦。Device Flow 不需要注册回调地址，也不需要保管 client_secret（CLI 二进制的 client_secret 本来也保不住），对 CLI 工具来说是最省心的方案。

安全问题：验证码只有 8 位，够吗？​

第一反应是觉得 8 位验证码太短了。但读了 RFC 8628 的设计理由之后，理解了这个长度的权衡。

8 位字符的熵是 20^8 ≈ 2^34.5 位（字符集只用了大写字母去掉易混淆字符，共 20 个）。单独看不算高，但配合几个限制就够用了：

1. 有效期 15 分钟 — 窗口很短
2. 提交限流 — 每小时最多 50 次验证码尝试
3. device_code 一次性 — 一个设备码对应一个令牌，用完即废

真正的安全风险不在验证码长度，而在远程钓鱼。攻击者可以伪造一个页面让人输入验证码，然后用自己的账号完成授权。GitHub 的缓解方式是授权页面上显示设备类型、IP 地址、权限列表，让用户有信息做判断。

Token 存储是另一个容易被忽略的点。gh 把 Token 存到 ~/.config/gh/hosts.yml，权限设 chmod 600。如果你自己写工具调用 Device Flow，不要往 shell 历史里塞 token，也不要明文存文件。macOS 可以用 Keychain，Linux 可以用 Secret Service：

# macOS
security add-generic-password -a "$USER" -s "github_token" -w "gho_xxx"

# Linux
secret-tool store --label="GitHub Token" service github user "$USER"

Device Flow 为什么是 AI Agent 的最佳认证方案​

写这篇文章的时候我其实在解决另一个问题：Agent 跑在远端服务器上，我通过微信跟它对话。Agent 要调用 GitHub API 来操作仓库、创建 PR、管理 issues——但怎么安全地给它授权？

最直觉的做法是把 Token 发到微信聊天里。这也是最危险的。

IM 发 Token 的路径：
  你 → [ 微信服务器 ] → [ 聊天记录 ] → [ Agent 上下文 ]
                                            ↓
                                     每一层都能看到你的 Token

Token 一旦进了聊天记录，IM 服务器有一份、本地聊天记录有一份、Agent 的消息上下文里也有一份。而且 Token 不会过期——拿到一次就能一直用。

Device Flow 解决了这个问题：你的机器从不接触 Token。

它的思路是这样的：

1. Agent 打印一串验证码（BFEE-895F）到聊天里
2. 你打开 github.com/login/device——这是 GitHub 的官方授权页，不是 Agent 给你的链接
3. 输入验证码，在 GitHub 的页面上完成授权
4. Token 直接从 GitHub 服务器发给 Agent（server-to-server）

Device Flow 的路径：
  Agent 打印验证码 → 你看到
        ↓
  你打开 github.com/login/device → 输入验证码 → 完成 OAuth
        ↓
  Token 直接从 GitHub 到 Agent（server-to-server，不经过任何中间层）

你的 IM 里只有一段 8 位验证码（15 分钟有效，用完作废）。Token 从头到尾没有经过你的聊天记录。

后来想想，如果你的 Agent 也需要在远端认证——Device Flow 差不多是唯一不用把密钥喂进聊天记录的办法了。

🥚 彩蛋​

如果你也经常需要配远程服务器的 GitHub 认证，我写了一段脚本——一条命令走完"下载 gh + 认证 + 配置 git 用户"全流程：

# remote-gh-setup.sh
# 在远程服务器上跑：curl -fsSL https://gist.github.com/binggg/xxx/remote-gh-setup.sh | bash
# 然后在你自己的电脑上打开 https://github.com/login/device 输入验证码

set -e

# 1. 装 gh 到 ~/bin
mkdir -p ~/bin
curl -fsSL https://github.com/cli/cli/releases/latest/download/gh_*_linux_amd64.tar.gz \
  | tar -xz -C /tmp
cp /tmp/gh_*/bin/gh ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/bin:$PATH"

# 2. 启动 Device Flow 认证
gh auth login --web --git-protocol https

# 3. 配 git user
gh api user --jq '.login' | xargs -I{} git config --global user.name "{}"
gh api user --jq '.email // .login + "@users.noreply.github.com"' | xargs -I{} git config --global user.email "{}"

echo "✅ Done! Logged in as $(gh api user --jq '.login')"

这个脚本覆盖了我上一篇踩坑的全部流程。如果你那里还有我没遇到过的环境限制，评论区聊聊。

你的 Agent 在远端怎么认证的？是自己配的 Token 还是走了 Device Flow？评论区聊聊 👇

全文基于 GitHub CLI v2.62.0、RFC 8628（2019年8月发布）和一次实际部署验证。

这篇文章主要分享两件事：

1. 让 AI 生成的代码能真正上线 — AI 写的代码 Demo 感十足，一上线就全是安全隐患。问题是 AI 不感知真实的后端底座。
2. 解决"AI 有 Skill 却不爱用"的毛病 — 明明配好了 Skills，AI 却视而不见，非要凭直觉盲干。技能激活率从 20% 硬拉到 84% 的方法。

图：文章配图

Vibe Coding 的"本地舒适区"​

最近大家都在享受 Vibe Coding 的快感。在 localhost 一顿操作，UI 漂亮得像成品，但魔法往往在"上线"瞬间戛然而止。

AI 的代码逻辑还不错，但它无法感知真实的生产环境，导致生成的"局部最优解"难以落地。

世界上最遥远的距离，是从 localhost 到真实访问的距离。 AI 填补了代码量的空白，却填补不了工程底座的断层。

什么是 Skills​

Skills 最早是 Anthropic 在 2025 年 10 月给 Claude Code 加的一个功能。它是一套包含指令、脚本和资源的能力包——把专业知识、步骤、代码打包成"技能包"。

my-skill/
├── SKILL.md          # 核心：指令 + 元数据
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源

如果把 AI 比作高材生，Skills 就是他的岗位操作手册。它不改变 AI 的智商，但通过注入程序性知识（Procedural Knowledge），让 AI 知道在你的特定环境下，"正确且高效"的操作标准是什么。

Agent Skills 在 2025 年 12 月正式成为开放规范，目前 Claude、Cursor、VS Code、GitHub Copilot、OpenCode 等主流 AI 开发工具都已宣布兼容支持。

渐进式加载​

Skills 通过渐进式加载来高效管理上下文：

1. 发现阶段：启动时，Agent 仅加载每个 Skill 的名称和描述。这足以判断哪些 Skill 相关，而不耗尽上下文窗口。
2. 激活阶段：当任务匹配描述时，Agent 按需将完整 SKILL.md 读入上下文。
3. 执行阶段：Agent 遵循指令执行，按需加载引用文件或运行脚本。

这种设计让 Agent 保持高速响应的同时，像"随身携带百科全书"——用的时候再翻开。

行业里已经有团队在推动这件事。Vercel 发布了 react-best-practices 解决 AI 乱写 React 的问题；Remotion 推出了视频制作 Skill 让 AI 学会用代码"剪辑"视频。这些 Skills 解决的核心问题是：让 AI 拥有特定领域的"工程直觉"。

最大难题：AI 为什么会"装死"？​

给 AI 配了 Skill，它视而不见。这是几个月里最让我头疼的事。背后的原因其实涉及大模型的两个底层逻辑：

注意力稀释：在大模型的 Transformer 架构里，它根据你的 Prompt 实时计算每个词的权重。对话越深入，业务需求的权重越高，作为背景板的 Skills 权重就会被"稀释"。

决策惰性：调用 Skill 本质上是一次工具调用。模型在推理时会算账：如果它觉得自己脑子里的预训练数据就能生成一段"看起来正确"的代码，它就会为了省推理资源而跳过外部工具调用。

结果很残酷：在我们的回归测试中，如果不加干预，AI 的主动 Skill 调用率只有 20% 左右。它宁愿"盲目裸奔"，也不愿意翻书。

"驯服" AI 的三套解法​

既然 AI 有决策惰性，就得用工程手段拉高它的"警觉性"。

1. 首行注入（最土但最稳）​

如果项目不容许犯错，在提问的最开头带上这句"咒语"：

You MUST read the guideline skill FIRST when working with this project.

原理：利用首因效应。模型对输入序列最前端的信息有天然的高关注度。这种强行注入能把 Skill 的激活率拉到可用水平。

2. 项目级"家法"（System Rules）​

在项目根目录创建 CLAUDE.md 或 AGENT.md，增加项目级别的约束规则：

# Project Workflow

0. You MUST read the guideline skill FIRST when working with this project.
1. 评估：写代码前，必须显式评估可用 Skills 列表。
2. 承诺：必须在输出中陈述"我需要调用某个 Skill"的理由。
3. 执行：禁止跳过规矩直接写代码。

这个方法不用每次都在 prompt 里写"咒语"了，但缺陷也很明显：随着对话上下文变长，AI 仍然可能忽略规则。

3. 强制拦截（Forced Eval Hook）​

如果前两个方案是靠"嘴"叮嘱 AI，那方案 3 就是物理拦截。

技术专家 Scott Spence 在他的实测中发现，最有效的方式是利用编辑器的 Hook（钩子）机制。配置一个 .claude/settings.json，脚本会在你按下回车的那一刻，自动拦截并"魔改"你的问题——强制 AI 在输出任何代码前，必须先写一段评估报告：

• 当前有哪些 Skill 可用？
• 针对这个需求，需不需要调用它们？理由是什么？

AI 有个毛病：只要觉得脑子里的旧数据能糊弄过去，它就不会翻书。这种 Hook 强迫 AI 白纸黑字写下"我要用这个工具"，一旦它在开头表了态，后面的代码生成就会严格遵守。

效果：Skill 激活率从 20% 暴力拉升到 84%。

架构复盘：一个总纲 + N 个独立 Skill​

在开发 Skills 的过程中，我发现 AI 最大的毛病是**"环境不分"**——它分不清 Web、小程序和 Node.js 的边界。没有搞"全家桶"式的单体 Skill，而是采用了 1 个总纲 + N 个独立 Skill 的分布式架构。

解决"语义污染"​

Web、小程序、Node.js 的 SDK 方法名极其相似。如果全塞进一个 Skill，AI 经常在写小程序逻辑时掏出 Web 端的语法。这种语义污染是代码无法上线的元凶。

解法是按端物理拆分。配合一个总纲 Skill 作为入口点，先指挥 AI 判定项目环境。环境判定后，AI 只会加载相关的子 Skill，干扰项直接屏蔽掉。搜索空间缩小了 90%，推理精度自然大幅提升。

支持"精准点菜"​

全能包太重了。当你想让 AI 专门解决一个特定问题时（比如"微信支付"或"安全规则"），AI 的注意力会被庞大的全量手册稀释。

独立插件支持局部强化。你可以直接下令："调用 auth 插件看怎么实现手机号登录"。这种设计允许直接干预 AI 的决策路径——在 AI 逻辑混乱时，通过唤起特定子 Skill 强行把它的思维拉回到正确的窄道上。

写在最后​

折腾了这么久的 Skills，最大的感触是：AI 编程的生产力，不取决于模型能写出多么精妙的逻辑，而取决于你对它生成的代码具备多少工程约束力。

几点观察：

核心本质：把隐性经验转化为程序性知识。 目前的 Agent 是博学的实习生，对真实生产环境缺乏敬畏。Skills 的本质是给它注入一套工程化的"肌肉记忆"——把多年积累的填坑经验转化为 AI 的前置判定条件。

范式转换：Agent 必须具备环境感知力。 Agent 进化的下一站，不仅仅是推理能力的增强，更是对基础设施感知力的补齐。Skills 守住工程下限，底座承载逻辑上限。

确定性是唯一度量衡。 不应该期待 AI 自动变得"完美"，而应该通过工程手段让它变得"稳定"。AI 提供逻辑的上限，工程约束守住交付的下限。

如果你也在折腾 Skills，最有价值的一件事就是：先测一下你的 AI 到底有没有真的在用它们。 20% 的默认激活率不丢人，但不知道这个数字才丢人。

后来我花了不少时间在 prompt 里调参数做减法，试了好几套风格方案，慢慢摸索出一些规律。回头想想，去掉 AI 味的核心其实很简单：做减法、加纹理、扁平化、低饱和度。

下面这三套方案是实战下来最稳的，直接贴 prompt 后缀就能用。

图：文章配图

为什么 AI 图片会"油腻"？​

你有没有发现，很多 AI 生成的图片虽然看起来很"完美"，但总有一种说不出的"塑料感"？

这就是我们常说的"AI 味道"和"油腻感"。它们通常来自于：

• 过度的光影渲染：高光、反光、阴影太刻意
• 过于完美的细节：每个像素都太精致，缺少真实感
• 高饱和度的色彩：颜色太鲜艳，显得不自然
• 典型的 3D 建模感：像游戏引擎渲染出来的，而不是人画的

举个常见的例子​

假设你要为"读书"主题配图，如果使用默认的 AI 提示词，可能会生成这样的图片：

问题在哪里？

• 光影太戏剧化，像电影海报
• 细节过于完美，每个角落都很精致
• 3D 渲染感太强，像游戏场景
• 整体感觉"太假"，缺少真实感

想要去"油"且友好？核心策略很简单：做减法、加纹理、扁平化、低饱和度。

下面为你整理了 3 套可以直接用的风格方案，用同样的"读书"主题，看看不油腻的版本：

方案一：极简矢量扁平风​

适合： 科技博客、职场干货、产品介绍

这是最安全、最现代的风格。它去除了所有不必要的立体感，就像 Notion 的插画或者大厂 UI 设计那样，干净、简洁、专业。

看起来像什么： 干净、大面积留白、几何形状、哑光质感，就像你在 Apple 官网或者 Notion 里看到的那些插画。

通用提示词后缀 (Prompt Suffix)：

English: flat vector illustration, minimal style, corporate memphis, simple shapes, 2D, white background, wide margins, clean lines, matte finish, low saturation, soft pastel colors, no shading, Behance style --ar 16:9

中文释义： 扁平矢量插画，极简风格，企业孟菲斯风格，简单形状，2D，白底，宽边距，线条干净，哑光表面，低饱和度，柔和的粉彩色，无阴影，Behance 风格。

示例对比：

同样的"读书"主题，使用扁平风格后：

对比油腻版本： 去掉了 3D 渲染感，没有复杂的光影，简洁干净，专业感强。

方案二：手绘蜡笔/水彩风​

适合： 生活感悟、读书笔记、情感故事

这种风格通过模拟真实的画材（蜡笔、铅笔、水彩），引入人为的"瑕疵感"和"噪点"，彻底消除 AI 的塑料光滑感，显得非常有温度。

看起来像什么： 就像你在儿童绘本里看到的那种插画，粗糙的纹理、温暖的色调、有点不完美的边缘，但特别有亲和力。

通用提示词后缀 (Prompt Suffix)：

English: hand-drawn sketch, crayon texture, watercolor style, children's book illustration, rough edges, textured paper, visible brush strokes, warm tones, cozy atmosphere, simple composition, cute and friendly --ar 16:9

中文释义： 手绘素描，蜡笔纹理，水彩风格，儿童绘本插画，边缘粗糙，纹理纸张，可见笔触，暖色调，舒适氛围，构图简单，可爱友好。

示例对比：

同样的"读书"主题，使用手绘风格后：

对比油腻版本： 有了真实的纹理和笔触，温暖的色调，就像真的手绘作品，特别有亲和力。

方案三：复古孔版印刷风 (Risograph)​

适合： 观点文章、文艺评论、创意设计

这是目前去 AI 味的大杀器。Risograph（孔版印刷）风格强制使用有限的色彩和颗粒感，会让图片看起来像是有年代感的印刷品，非常高级且完全不油腻。

看起来像什么： 就像独立杂志或者艺术海报，有颗粒感、双色或三色套印、复古的错位感，特别有文艺范儿。

通用提示词后缀 (Prompt Suffix)：

English: Risograph style, grain and noise, screen print texture, limited color palette (blue and orange), halftone pattern, abstract minimalism, vintage aesthetic, matte paper texture, high contrast, flat illustration --ar 16:9

中文释义： 孔版印刷风格，颗粒和噪点，丝网印刷纹理，限制色板（如蓝和橙），半调图案，抽象极简，复古美学，哑光纸质感，高对比度，扁平插画。

示例对比：

同样的"读书"主题，使用 Risograph 风格后：

对比油腻版本： 有了颗粒感和印刷质感，限定的色彩让画面更高级，完全摆脱了 3D 渲染的塑料感。

💡 核心"去油"魔法词​

如果你想自己微调风格，下面这些词是必用的"去油神器"：

1. 材质控制 (必选)​

• Matte (哑光，去反光)
• Grainy / Noise (噪点，增加真实感)
• Textured paper (纸张纹理)

2. 光影控制​

• Flat lighting (平光，避免戏剧性光影)
• Soft shadows (柔和阴影)
• Natural light (自然光)

3. 负向提示词（告诉 AI 不要画什么）​

这非常重要！把这些词填入 Negative Prompt 框，告诉 AI 避免这些"油腻"元素：

photorealistic, 3d render, octane render, unreal engine, shiny, glossy, reflection, hyper detailed, neon lights, cyberpunk, plastic looking, oily skin, complex background

简单理解： 就是告诉 AI "不要画得太真实、太 3D、太闪亮、太复杂"。

实战示例：同一个主题，三种风格​

假设你要写一篇关于 "如何高效管理时间" 的文章，来看看三种风格的区别：

使用方案一 (扁平风) 的组合方式：​

Prompt: A person organizing giant clock gears, happy expression, working on a desk + flat vector illustration, minimal style, simple shapes, 2D, white background, clean lines, matte finish, soft pastel colors, no shading --ar 16:9

使用方案二 (手绘风) 的组合方式：​

Prompt: A cute clock and a cup of coffee on a wooden table, sunlight + hand-drawn sketch, crayon texture, children's book illustration, rough edges, textured paper, warm tones, cozy atmosphere --ar 16:9

使用方案三 (Risograph 风) 的组合方式：​

Prompt: Abstract clock design with calendar elements + Risograph style, grain and noise, screen print texture, limited color palette (blue and orange), halftone pattern, abstract minimalism, vintage aesthetic --ar 16:9

实用技巧​

1. 混搭风格​

你可以把不同风格的提示词组合起来，创造出独特的视觉效果：

主体描述 + 风格A的关键词 + 风格B的材质词

举个例子：

A person reading a book + flat vector illustration + crayon texture, rough edges

这样就能得到"扁平风格但带手绘质感"的图片。

2. 如果颜色还是太鲜艳​

可以加上这些词：

• desaturated (去饱和)
• muted colors (柔和色彩)
• pastel palette (粉彩色板)

3. 避免过度细节​

如果 AI 画得太复杂，加上这些：

• simple composition (简单构图)
• minimal details (最少细节)
• focus on main subject (聚焦主体)

总结：5 个去油原则​

去"AI 味道"的核心其实很简单：让图片看起来像人画的，而不是机器渲染的。

记住这 5 个原则：

1. ✅ 加纹理：纸张、画布、噪点，增加真实感
2. ✅ 减细节：不要过度完美，留点"瑕疵"
3. ✅ 降饱和度：柔和色彩比鲜艳色彩更友好
4. ✅ 扁平化：避免 3D 立体感，2D 更自然
5. ✅ 哑光处理：去除高光和反光，避免"塑料感"

记住：不完美才是真实，真实才最友好。

很多非技术人员在用 AI 编程时都会遇到这样的痛点：

• Debug 困难：页面显示异常，但不知道问题出在哪一层（前端？后端？还是部署？）
• 提问不准确：不知道如何描述问题，让 AI 能理解并给出准确答案
• 学习路径模糊：知道需要学一些基础，但不知道从哪开始，学什么才够用

今天，我将为你分享一套系统的方法，从基础概念到调试技巧，再到后端方案，让你从"能生成应用"到"能做出真正可用的应用"。

图：文章配图

问题的本质：为什么 Debug 这么难？​

你遇到的问题其实是一个问题的两面：debug 困难，不知道问什么问题。

这是因为：

1. 不知道问题出在哪一层：前端？后端？还是部署？
2. 不知道如何描述问题：让 AI 能理解你的真实情况
3. 不知道该怎么学习：可能也知道一些调试方法，但不够系统

核心问题：缺乏系统的基础概念，导致无法准确诊断和描述问题。

解决方案一：系统学习基础概念​

这是最关键的。很多人用 AI 编程，直接就开始写代码，但不知道基础概念，出错了也不知道问什么问题。

为什么需要学习基础概念？​

你不需要成为专家，但需要理解：

1. 前端 vs 后端：用户看到的是前端，处理数据的是后端
2. 请求 vs 响应：你的浏览器向服务器请求数据，服务器返回结果
3. 本地 vs 线上：在你电脑上跑的叫"本地"，在服务器上跑的才叫"线上"

这些概念不懂，出错了你连描述都描述不清。

具体做法​

1. 打开 Frontend Roadmap​

访问 developer-roadmap，这不是让你去学所有东西，而是用来了解全貌。

• 看一遍，不需要全部理解
• 用 AI 解释你不懂的概念
• 重点理解：HTML/CSS/JavaScript/浏览器如何工作

2. 用 AI 帮你理解概念​

不理解 HTTP 请求是什么？直接问 AI：

"请用最简单的语言解释 HTTP 请求是什么，用餐厅点餐做比喻"

AI 会结合你的经验，给你最贴切的解释。

3. 边学边实践​

• 不要求全部学完再开始
• 遇到问题就回头查
• 用项目驱动学习

核心概念（前端阶段）​

1. HTML 结构：网页骨架，标签语义
2. CSS 样式：颜色、布局、响应式
3. JavaScript 行为：交互、数据请求
4. 浏览器开发者工具：调试利器，查看错误和网络请求
5. 控制台错误：理解错误信息
6. 网络请求：前端如何和后端交互

为什么这样做有效？​

当你理解了这些基础概念，你就能：

• 准确描述问题："我的前端页面发起的请求，后端返回了 500 错误"
• 理解 AI 给出的解决方案："AI 说要在后端添加 CORS 配置，我理解这是跨域问题"
• 判断哪个方案适合你：而不是让 AI 给 N 个方案，你猜哪个对

解决方案二：系统掌握调试技巧​

有了基础概念，下一步是学会调试。

调试方法体系​

1. 查看控制台错误​

按 F12 或者右键 → 检查 → Console

控制台会显示红色的错误信息，这是最直接的调试入口。

常见错误：

• Uncaught ReferenceError: xxx is not defined — 某个变量没定义
• Cannot read properties of undefined — 尝试读取未定义的对象属性
• NetworkError — 网络请求失败

2. 截图反馈​

遇到问题时，截图 + 控制台错误信息一起发给 AI。

好的提问方式：

"我的页面在点击登录按钮后没有反应，控制台显示 'Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')'，这是什么问题？"

不好的提问方式：

"我的页面出错了，帮我看看。"

3. 系统化调试流程​

1. 观察现象：发生了什么？截图 + 描述
2. 查看控制台：按 F12，看 Console 有没有红色错误
3. 复制错误：把控制台的错误信息复制出来
4. 提供上下文：告诉 AI 你在做什么、期望什么、实际发生了什么
5. 尝试修复：根据 AI 的建议，逐步修复

解决方案三：进阶后端方案​

前端做好了，下一步是后端。

后端挑战​

很多人把前端做好了，却卡在了后端：

• 不会 MySQL/MongoDB
• 不会写 API
• 不会部署服务器

更简单的方案：BaaS（Backend as a Service）​

什么是 BaaS？

BaaS（后端即服务）把后端能力封装成简单 API：

你需要的后端功能，其实大部分都已经做好了，直接用就行。

更进一步：AI 自动化的后端方案​

如果 BaaS 还不够，现在有了更新的方案：MCP 协议。

MCP（Model Context Protocol）让 AI 可以直接调用云服务。你只需要告诉 AI 你要什么，AI 自动帮你完成所有操作。

特别篇：设计岗转技术的快速提升路径​

如果你是设计师，想用 AI 做出真正的应用，你的路径和纯新手不太一样。

设计思维 vs 编程思维​

你的优势：

• 理解用户体验，知道什么样的界面好用
• 有设计规范意识，不会弄出"AI 味"界面
• 理解交互逻辑，知道用户操作流程

需要补充的：

• 知道设计稿怎么变成代码
• 理解数据如何流动
• 学会调试和排查问题

快速提升方法​

1. 利用设计优势​

• 你的设计规范可以直接告诉 AI
• 你的设计稿可以截图给 AI，让它生成对应的代码
• 你的用户视角是巨大的优势

2. 重点补充编程逻辑​

• 条件判断：if/else
• 数据循环：for/forEach
• 事件处理：点击、输入、提交
• 数据请求：fetch/axios

这些是理解 AI 生成代码的关键。

3. 实践项目驱动学习​

建议项目路径：

1. 个人作品集网站：展示你的设计作品
2. 交互式原型：把设计稿变成可交互的页面
3. 小型工具应用：解决实际问题的工具

总结​

Vibe Coding 不是迷思，但需要正确的方法：

1. 系统学习基础概念 - 结合 developer-roadmap 和 AI，了解前端开发的基础概念
2. 系统掌握调试技巧 - 截图反馈、控制台错误、提供完整上下文
3. 进阶：后端方案 - 前端做好后，用 BaaS 降低后端门槛

最重要的是：不要急于求成，先把前端基础打好。系统学习概念，系统掌握调试方法，再考虑进阶。

对于设计岗转技术的朋友：利用你的设计优势，重点补充编程逻辑，通过实践项目驱动学习，建立调试习惯。

重要术语表​

代码能跑，功能也有，但就是...不能用。

不是技术问题，是别的问题。

图：文章配图

一个典型的场景​

朋友兴冲冲地发来一个链接："你看我用 AI 做的，三小时搞定！"

打开一看：

• 页面是有的，圆角卡片、渐变按钮、紫色配色——一眼 AI 味
• 登录功能点了没反应
• 数据是写死的假数据
• 只能在他电脑上跑

我问："这个怎么给用户用？"

他愣了一下："...还没想到那一步。"

这不是个例。我观察了很多用 AI 做的项目，发现大部分都卡在同一个地方：从 demo 到产品的鸿沟。

vibe coding 的五个坑​

仔细分析这些项目，问题可以归结为五个：

1. 需求是个谜​

"帮我做一个任务管理应用"——这是大多数人给 AI 的提示词。

问题是，AI 不知道：

• 任务要不要分优先级？
• 要不要支持多人协作？
• 数据存本地还是云端？
• 要不要提醒功能？

AI 只能猜。猜对了是运气，猜错了就是返工。

本质问题：没有 Spec 思维。需求不清晰，AI 再聪明也白搭。

2. UI 一眼假​

为什么 AI 生成的界面总有一种说不出的"AI 味"？

• 圆角用得太多太大
• 渐变色滥用
• 紫色 + 蓝色的万年配色
• 布局千篇一律

不是 AI 不会设计，是你没告诉它什么是好设计。

本质问题：缺乏设计规范。AI 只是在模仿它见过的"平均水平"。

3. 后端是空的​

前端页面做得再漂亮，点击登录按钮——没反应。

因为：

• 没有用户系统
• 没有数据库
• 没有 API 接口
• 没有服务器

很多人以为 AI 编程就是做前端页面。但一个能用的产品，后端才是大头。

本质问题：不懂架构选型。不知道用什么技术栈，干脆就不做了。

4. 部署是玄学​

代码写完了，然后呢？

• 域名怎么买？
• HTTPS 怎么配？
• 服务器怎么选？
• 数据库怎么部署？

对于没有运维经验的人，这些问题每一个都是拦路虎。

本质问题：不了解部署。代码能跑和产品能用是两回事。

5. 改一行崩全部​

好不容易跑起来了，想加个小功能。

改了一行代码，整个项目报错。

AI 生成的代码往往是"一次性"的——能跑，但不能改。因为：

• 没有模块化
• 没有类型检查
• 没有测试
• 到处是硬编码

本质问题：缺乏工程化。代码是写给机器跑的，不是给人维护的。

怎么破？​

分析完问题，解决思路就清晰了。下面是我总结的五个具体方法：

方法 1：先写 Spec，再写代码​

我之前写过一篇关于 Kiro Spec 工作流的文章，核心观点是：

vibe coding 最大的问题是：它让开发变成了"碰运气"，而不是"可控的工程"。

解决方案是在让 AI 写代码之前，先让它帮你梳理需求。具体来说，生成三个文件：

1. requirements.md —— 需求文档（用 EARS 语法写用户故事和验收标准）
2. design.md —— 技术方案（架构、流程、注意事项）
3. tasks.md —— 任务清单（todolist，便于跟踪）

这和大厂的研发流程、敏捷开发的拆解方式如出一辙，但 Kiro 把它和 AI IDE 深度结合，极大提升了落地效率。

什么是 EARS 需求语法？

EARS（简易需求语法）最早用于喷气发动机控制系统，后来被软件工程广泛采用。它用简单句式约束需求，避免"模糊表达"：

需求清晰了，AI 才能精准输出。

怎么在其他 AI IDE 里用？

即使没有 Kiro，其他 AI IDE 也能复刻这套流程：

• Claude Code：在项目下建立 CLAUDE.md，写入 Spec 工作流规则
• Cursor：使用 .cursor/rules/project.mdc
• Augment：使用 .augment-guidelines

整个流程下来，AI 不再是"黑箱"式地帮你生成代码，而是和你像搭档一样，步步确认、逐步推进。

方法 2：用 Skill 约束 AI 的设计输出​

不要让 AI 自由发挥，给它一套设计规范。

这里介绍一个概念：Skill（技能）。

Skill 是一种可复用的提示词模板，封装了特定领域的专业知识。比如 Anthropic 官方开源的 frontend-design Skill，专门用来解决"AI 味"问题：

有了这个 Skill，AI 生成的 UI 就不会那么"AI 味"了。

方法 3：选 BaaS，不要从零搭​

后端是大多数人的拦路虎。但其实不需要自己搭。

什么是 BaaS？

BaaS（Backend as a Service）是一种云服务模式，把后端能力封装成 API，开发者只需调用 SDK：

这比自己用 Express/Nest.js 从零搭建简单 10 倍。

国内外主流 BaaS 平台：

• 国外：Supabase、Firebase
• 国内：CloudBase（腾讯云开发）

BaaS 的核心理念是：开箱即用。创建项目时，数据库、认证、存储就已经准备好了，不需要你操心底层基础设施。

方法 4：用平台托管，不碰服务器​

部署也不需要自己折腾。

现在有很多平台可以帮你搞定部署：

如果你用的是 BaaS 平台（比如 CloudBase），部署就更简单了——前端静态托管、后端云函数、数据库，都在一个平台里，不用到处开账号。

把代码推上去，平台自动帮你搞定一切。

方法 5：工程化思维​

让 AI 生成代码时，要求它：

这样生成的代码才能维护和迭代。

我的实践​

说了这么多方法，我自己是怎么做的呢？

经过一段时间的摸索，我沉淀出一套方案，把上面五个方法整合在一起：

1. Spec 工作流 — 每次开始一个项目，先让 AI 帮我生成 requirements.md → design.md → tasks.md。需求清晰了，后面写代码就顺了。

2. Skill 技能体系 — 整理了一套设计规范，封装成 Skill。每次生成 UI 时调用，就不会有 AI 味了。

3. BaaS 架构 — 后端用云开发平台，不碰服务器。数据库、云函数、用户登录、文件存储——都是现成的。

4. MCP 协议 — 用 MCP 让 AI 直接调用云服务。创建数据库、部署函数、配置域名——都不用手动操作了。

这套方案我打包成了 CloudBase AI Toolkit，开源在 GitHub。

写在最后​

vibe coding 不是不能用，而是只能用来做 demo。

从 demo 到产品，需要的不是更强的 AI，而是工程化的思维：

• 需求要清晰（Spec 工作流）
• 设计要规范（Skill 技能体系）
• 架构要合理（BaaS 服务）
• 开发要智能（MCP 协议）
• 代码要可维护（工程化）

AI 是工具，但工具需要正确的使用方式。

就像有了电钻，不代表人人都能做木工。关键是你知道怎么用，用在哪里。

记住：AI 不是替代人，而是让人更强大。

如果你也有 AI 编程的实践经验，欢迎交流。

说实话，这个问题我也思考了很久。直到我看到了 Gojko Adzic 的《实例化需求：团队如何交付正确的软件》这本书，才恍然大悟。

原来，Kiro 的 Spec 工作流背后，是 SBE（Specification by Example）方法论的完美实践。今天就来揭秘这套方法论，解决你的 AI 编程返工问题。

图：文章配图

你的 AI 编程为什么总是返工？​

你有没有遇到过这样的情况：

• 让 AI 生成一个登录功能，结果生成了注册页面
• 要求实现数据导出，AI 却给你一个数据导入功能
• 想要一个简单的 API，AI 却生成了复杂的微服务架构

这些问题的根源是什么？

不是 AI 不够聪明，而是我们的需求表达太模糊了。就像和一个外国朋友交流，如果你说"我要吃饭"，他可能理解成"我要吃米饭"、"我要去餐厅"或者"我要点外卖"。

在 AI 编程中，这种模糊性被放大了。AI 只能根据你的描述来"猜"你想要什么，猜对了皆大欢喜，猜错了就要返工重来。

传统需求管理的困境​

在传统软件工程中，我们早就发现了类似的问题：

1. 需求歧义：同一个需求，不同人理解不同
2. 后期返工：开发完成后发现理解偏差
3. 文档滞后：需求文档跟不上实际变化
4. 沟通成本：反复确认需求，效率低下

这些问题在 AI 编程中被进一步放大。当需求不清晰时，AI 就像在黑暗中摸索，只能靠"运气"来生成符合期望的代码。

传统软件工程早就有了解决方案​

Gojko Adzic 在《实例化需求：团队如何交付正确的软件》中提出的 SBE（Specification by Example）方法论，正是为了解决这些问题而生。

SBE 的核心原则​

1. 以实例为中心的需求定义​

用具体、真实的例子替代抽象的需求描述。比如：

❌ 抽象描述：用户登录功能要安全可靠 ✅ 实例化描述：

• Given 用户输入正确的用户名和密码
• When 点击登录按钮
• Then 系统显示欢迎页面

2. 协作式需求澄清​

强调跨角色协作，通过共同讨论实例避免"需求孤岛"。在 AI 编程中，这就是人机协作的过程。

3. 从需求到可执行测试的转化​

将实例转化为自动化测试用例，实现"需求即测试"。这是 Spec 模式中基于 requirement 生成测试用例的理论基础。

4. 活文档（Living Documentation）​

实例化需求的结果是一套动态更新的文档系统，随需求变更自动同步。这正是 Spec 模式中持续更新的 requirements.md 和 design.md。

SBE 与 Spec 模式的完美映射​

需求澄清 → requirements.md 的迭代​

SBE 原则：用具体实例澄清需求，确保团队理解一致。

Spec 实践：

### 需求 1 - 用户登录功能

**用户故事：** 作为用户，我希望能够安全登录系统，以便访问我的个人数据。

#### 验收标准
1. When 用户输入正确的用户名和密码时，the 系统 shall 显示欢迎页面
2. When 用户输入错误的密码时，the 系统 shall 显示错误提示
3. When 用户连续输入错误密码3次时，the 系统 shall 锁定账户30分钟

技术设计 → design.md 的协作​

SBE 原则：避免技术陷阱，聚焦业务功能。

Spec 实践：

## 技术方案设计

### 架构设计
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：MongoDB
- 认证：JWT Token

测试驱动 → 基于需求的测试生成​

SBE 原则：需求即测试，确保实现符合预期。

Spec 实践：

// 基于 requirements.md 自动生成的测试用例
describe('用户登录功能', () => {
  test('正确密码登录成功', async () => {
    const response = await login('user@example.com', 'correctPassword');
    expect(response.status).toBe(200);
    expect(response.data.message).toBe('欢迎页面');
  });
});

实践经验：SBE 方法论在 AI 编程中的落地​

我的实践心得​

经过在多个项目中的实践，我发现 SBE 方法论在 AI 编程中确实很有效：

1. 需求迭代和澄清最重要​

关键发现：requirements.md 和 design.md 的不断迭代和澄清是整个流程的核心。

实践案例：

• 在 CloudBase-AI-ToolKit 项目中，我们每个新功能都采用 Spec 模式
• 通过反复迭代 requirements.md，需求清晰度提升了 80%
• 返工率从原来的 60% 降低到 15%

2. 基于需求生成测试用例​

关键发现：基于 requirements.md 生成的测试用例，让 AI 编程变得可验证。

3. 在存量项目中的应用​

关键发现：Spec 模式不仅适用于新项目，在存量项目中同样有效。

粒度拆分的最佳实践​

关于大家关心的粒度拆分问题，我的经验是：

按功能模块拆分​

specs/
├── user-management/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── file-upload/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
└── data-export/
    ├── requirements.md
    ├── design.md
    └── tasks.md

按迭代拆分​

specs/
├── v1.0-basic-features/
├── v1.1-advanced-features/
└── v1.2-optimization/

按复杂度拆分​

• 简单功能：单个 spec 文件
• 中等功能：独立的 spec 文件夹
• 复杂功能：多个关联的 spec 文件夹

那么，SBE 方法论到底有多香？​

看到这里，你可能会问："这套方法论真的这么有效吗？会不会太复杂了？"

说实话，我一开始也有同样的担心。但实践下来发现，SBE 方法论在 AI 编程中确实很"香"：

为什么 SBE 方法论这么有效？​

1. 需求清晰了：用具体例子替代抽象描述，AI 理解更准确
2. 返工率低了：基于清晰需求生成的代码，质量更高
3. 协作更顺畅了：团队成员对需求理解一致，沟通成本降低
4. 文档不过时了：活文档随需求变化自动更新

适用场景和注意事项​

适合的场景：

• ✅ 复杂项目，涉及多个模块
• ✅ 团队协作，需要统一标准
• ✅ 质量要求高，需要可追溯性

不太适合的场景：

• ❌ 快速原型，验证想法
• ❌ 个人项目，简单功能
• ❌ 时间极其紧迫的项目

总结：让 AI 编程从"碰运气"变成"可控工程"​

SBE 方法论为 AI 编程提供了一套经过验证的理论基础和实践框架。通过实例化需求、协作式澄清、测试驱动开发和活文档管理，我们可以让 AI 编程变得更加可控、高效和可靠。

记住：AI 不是替代人，而是让人更专注于决策和把控方向，把繁琐的细节交给 AI。

这样，你的 AI 编程就不再是"碰运气"，而是真正变成了"可控工程"。

互动话题：

1. 你目前使用的是哪种开发模式？
2. 你觉得 Spec 模式在你的项目中可行吗？
3. 分享一下你的 AI 编程经验！

图：文章配图

拉霸式 vibe coding，真的靠谱吗？​

你是否有过这样的体验：在 AI IDE 里输入一句模糊的需求，点击"生成"，满怀期待地等着 AI 给你一个完美的程序？结果却像在拉霸机前拉动拉杆——有时中个小奖，大多数时候却一无所获。

拉霸游戏和 vibe coding 的异同：

拉霸游戏：买代币，拉拉杆，偶尔中大奖，更多时候是"再来一次"，最终庄家总是赢家。

氛围编程（vibe coding）：买 Tokens，写模糊提示，点"生成"，有时得完美代码，有时一团乱麻。AI 鼓励你"再试一次"，你安慰自己"这次一定能修好 bug"，但最终模型厂商总是赢家。偶尔你觉得自己赚到了，回头却发现花了更多时间。

vibe coding 最大的问题是：它让开发变成了"碰运气"，而不是"可控的工程"。

常见的 vibe coding 流程示意图​

黄色节点为"人"操作，蓝色为 AI 产出，红色为不理想结果。

有没有更好的办法？——传统研发流程是怎么做的​

传统软件工程强调需求澄清、技术设计、任务拆分、过程可追溯。这样做虽然"慢"，但能让项目稳步推进、可复盘、可协作。

Kiro AI IDE 就把这种流程做成了"Spec 工作流"，让 AI 编程也能像工程师一样靠谱。

传统研发流程示意图​

该流程强调需求评审和迭代反馈，体现传统软件工程的闭环和持续优化。

Kiro 的 Spec 工作流有多香？​

Kiro 是 AWS 推出的 AI IDE，除了免费集成 Claude 4，更大的亮点是它的 Spec 工作流：

• 每个项目下有 3 个核心文件：
  1. requirements.md —— 需求文档（用 EARS 语法写用户故事和验收标准）
  2. design.md —— 技术方案（架构、流程、注意事项）
  3. tasks.md —— 任务清单（todolist，便于跟踪）

什么是 EARS 需求语法？​

EARS（简易需求语法）最早用于喷气发动机控制系统，后来被软件工程广泛采用。它用简单句式约束需求，避免"模糊表达"。

例：When 用户点击"静音"，系统应当抑制所有音频输出。

参考资料：EARS 语法指南 | v0.dev Cheat Sheet

Claude Code 也能玩 Spec 流程！（含实操演示和对话示例）​

即使没有 Kiro，其他 AI IDE 也能复刻这套流程。以 Claude Code 为例，整个过程可以非常丝滑：

1. 在项目下建立 CLAUDE.md
   • 你可以把下面的提示词模板直接写进 CLAUDE.md，作为 AI 协作的"工作说明书"。
   • 示例（可根据实际需求调整）：

# CLAUDE.md

你是一个专业的 AI 编程助手，协助我用标准软件工程流程推进项目。请严格按照 Spec 工作流推进：
1. 需求澄清与确认，输出 requirements.md，采用 EARS 语法。
2. 技术方案设计，输出 design.md，包含架构、技术选型、接口、测试策略。
3. 任务拆分，输出 tasks.md，细化为可执行的 todolist。
4. 按照任务清单协助编码、测试，输出过程产物到 output/。
5. 重要：每一步都要和我确认，只有我确认后才能进入下一步。

2. 启动 Claude Code，输入原始需求

   • 直接把你的想法、用户故事写进对话框。
   • Claude 会自动读取 CLAUDE.md，开始和你进行需求澄清和确认。

3. 需求确认后，Claude 输出 requirements.md

   • Claude 会用 EARS 语法梳理需求，生成标准的 requirements.md。
   • 你可以随时补充、修改，Claude 会持续和你对齐。

4. 技术方案设计

   • 需求确认后，Claude 会自动进入 design.md 阶段，输出详细的技术方案。
   • 包括架构、技术选型、接口、测试策略等。

5. 任务拆分

   • Claude 会根据 design.md 自动生成 tasks.md，把方案拆分为可执行的 todolist。

6. 逐步实现与验收

   • Claude 会按照 tasks.md 协助你逐步实现代码、测试，并输出所有过程产物到 output/ 目录。
   • 你只需参与需求、设计、验收等关键评审环节。

推荐 CLAUDE.md 提示词模板： "你是一个专业的 AI 编程助手，协助我用标准软件工程流程推进项目。请严格按照 Spec 工作流推进，每一步都要和我确认，只有我确认后才能进入下一步。"

这样，哪怕没有 Kiro，借助 Claude Code 也能轻松复刻 Spec 工作流，让 AI 编程变得高效、可控、可复盘。

vibe coding 与 Spec 工作流对比流程图​

黄色节点为"人"参与评审，蓝色为 AI 产出，红色为不理想结果，绿色为高质量结果，灰色为流程分组。

Claude Code 复刻 Spec 工作流对话示例​

**用户**：我想做一个"AI 帮我自动整理会议纪要"的小工具，能帮我规划一下吗？

**Claude**（读取 CLAUDE.md 后自动响应）：
当然可以！我们将采用标准 Spec 工作流推进。首先，我会帮你澄清需求并输出 requirements.md。请问你希望支持哪些输入方式？比如：语音、文字、文件上传等？

**用户**：主要是上传录音文件，最好还能支持多种音频格式。

**Claude**：
明白了。还有输出格式有要求吗？比如纯文本、Markdown、Word 文档等？

**用户**：最好能导出 Markdown 和 Word。

**Claude**：
好的，需求已澄清。下面是基于 EARS 语法梳理的 requirements.md 草稿：

---

# requirements.md

## 用户故事
作为一名经常开会的用户，我希望能上传会议录音，自动生成结构化的会议纪要，并能导出为 Markdown 或 Word 文档，提升整理效率。

## 验收标准
1. When 用户上传音频文件时，the 系统 shall 支持多种主流音频格式（如 mp3, wav, m4a）。
2. When 音频上传完成时，the 系统 shall 自动将音频转为文本并提取会议要点。
3. When 用户点击导出时，the 系统 shall 支持导出为 Markdown 和 Word 文档。

---

请确认需求内容，或补充修改。确认后我将进入技术方案设计阶段。

**用户**：确认，没问题。

**Claude**：
收到！接下来输出 design.md：

---

# design.md

## 架构概述
- 前端：文件上传、进度显示、导出按钮
- 后端：音频转文本（调用 ASR 服务）、要点提取（大模型）、文档格式转换
- 存储：临时存储音频和文本

## 技术选型
- 前端：React
- 后端：Node.js + OpenAI/Claude API
- ASR 服务：Whisper API
- 文档导出：jsdocx、markdown-it

## 流程
1. 用户上传音频
2. 后端转写为文本
3. 调用大模型提取要点
4. 前端展示并支持导出

## 安全性
- 文件仅临时存储，处理后自动删除

---

请确认技术方案，或补充修改。确认后我将拆分任务清单。

**用户**：确认。

**Claude**：
好的，下面是 tasks.md：

---

# tasks.md

- [ ] 搭建前端上传页面
- [ ] 实现音频文件上传接口
- [ ] 集成 ASR 服务实现音频转文本
- [ ] 调用大模型提取会议要点
- [ ] 实现导出 Markdown/Word 功能
- [ ] 前后端联调与测试
- [ ] 文档与验收

---

请确认任务清单，确认后我将协助你逐步实现每个任务。

CloudBase AI ToolKit：一站式复刻 Spec 工作流​

如果你想要更开箱即用的体验，可以试试 CloudBase AI ToolKit：

• 支持多种 AI IDE
• 自带 Spec 工作流模板
• 一键生成、部署、托管全栈应用，无需运维

人机协作，才是正解​

在 Spec 工作流下，AI 负责：

• 模糊需求 → 需求方案
• 技术设计文档
• 任务清单
• 编码实现
• 验收测试

人类只需参与：

• 需求输入
• 需求/技术/排期/测试评审

这样既能发挥 AI 的高效，又能保证工程质量。

标准软件工程流程示意图​

黄色节点为"人"参与评审，蓝色为工程活动（可由 AI 或人协作完成），绿色为高质量结果。

总结：让 AI 编程更快、更稳、更靠谱​

Spec 工作流让 AI 编程不再是"碰运气"，而是"有章可循"。人类工程师的经验和判断，配合 AI 的高效执行，才能让开发真正提速、提质、可复盘。

记住：AI 不是替代人，而是让人更强大。