本文由 莫潇羽@无忆研习社（www.wuyi.wiki）撰写,转载请注明出处。

快速摘要

核心结论:AI 编程已经从概念走到了真正能上手的阶段,即使你完全没有编程背景,也可以借助 Claude Code、Cursor、Gemini CLI 这类主流工具,配合国内阿里百炼、火山引擎方舟等平台的 API,搭建出一套低成本可用的开发环境,并做出真正能跑起来的桌面工具、Web 应用,甚至带 AI 能力的复杂软件。你唯一需要练的核心能力,是把需求说清楚。

本文按"概念—工具—配置—方法—实战—心法"的脉络,从 Vibe Coding 的起源讲起,把市面上主流 AI 编程工具横向梳理一遍,详细拆解 Claude Code 在国内的完整接入方案、CLAUDE.md 与 Skills 渐进式披露体系,再用两个完整的项目案例(一个本地桌面整理工具、一个多模态 AI 画布工具)展示从需求规划到打包交付的全流程,最后总结九条经过反复验证的实战心法。想看完整拆解和避坑细节,往下翻。

一、AI 编程到底是什么:从 Vibe Coding 到 Agentic Engineering

1.1 一条推文掀起的浪潮

回到 2025 年 2 月 3 日,OpenAI 联合创始人、前特斯拉 AI 负责人 Andrej Karpathy 在 X 上随手发了一条只有 185 个英文单词的推文,定义了一种新的编程方式——Vibe Coding(氛围编程)。他原话的大意是:有一种新的编程方式,你完全沉浸在氛围里,拥抱指数级变化,甚至忘记代码的存在。他形容自己当时的工作流是"看东西、说东西、运行东西、复制粘贴东西,大多数时候它就能跑起来"。

这条推文在不到一周内积累了 450 万次浏览量,纽约时报、卫报、Ars Technica 接连跟进。到了 2025 年 3 月,韦氏词典把"vibe coding"收录为年度科技词汇;同年 11 月,柯林斯词典将其评为 2025 年度词汇。更刺眼的数据来自 Y Combinator——2025 年冬季那一批被孵化的初创公司里,有 25% 的团队报告称自己代码库中有 95% 是 AI 生成的。

到了 2026 年 2 月,Karpathy 本人又主动更新了说法。他指出这个名字其实已经有点过时:通过 LLM Agent 来写代码,正在变成专业开发者的默认工作流,但需要配合更细致的监督和审查。他给出的新名字叫 Agentic Engineering(代理工程),目标是"在拿到 Agent 带来的杠杆同时,不在软件质量上做任何妥协"。

1.2 Vibe Coding 不等于 AI 辅助编程

如果你只是用 GitHub Copilot 帮你补全两行代码,这不是 Vibe Coding,这只是把 LLM 当成更快的打字员而已。

真正的 Vibe Coding,关键在于开发者主动放弃逐行理解代码,把实现层完全交给模型,自己只在意图(intent)层做判断:这个东西能不能跑、跑得对不对、好不好用。出错就把报错文本贴回去让 AI 修;界面别扭就用自然语言描述新的交互。整个过程不依赖你看懂每一行代码,而是依赖你看得懂运行结果。

这种范式转变带来的最大意义是:它让原本与"程序员"这个身份无关的人,也有了真正做出软件的可能。Bubble 等平台的调研显示,Vibe Coding 用户中超过六成不是开发者,他们是设计师、产品经理、内容创作者、独立创业者,甚至完全的文科背景。

1.3 它适合什么、不适合什么

莫潇羽自己折腾下来,真实体感是这样:Vibe Coding 非常适合做原型、内部工具、个人效率工具、轻量 SaaS、独立小产品,因为这些场景对极致代码质量的容忍度比较高,出问题不会立刻爆雷。

但要诚实地讲——它目前还不适合直接用来做高安全、高合规、高并发的生产系统。Veracode 2025 年的 GenAI 代码安全报告显示,AI 生成的代码中有 45% 包含已知的安全漏洞;某些公开测评里,AI 共同作者的 GitHub PR 比纯人工写的代码出现"重大问题"的概率高约 1.7 倍。这并不意味着 AI 写出来的代码就一定不能用,而是说在涉及支付、个人数据、企业敏感系统的时候,"它能跑"和"它安全"不是同一件事。

理解了这个边界,后面所有的工具选择、流程设计就都有了参照系——我们不是要让 AI 取代工程师,而是要让自己用上 AI 的杠杆,在合适的场景里把事情做出来。

二、主流 AI 编程工具版图:三大流派与代表产品

2.1 把工具先归到三个大类

刚开始接触这个领域的人很容易被各种名字砸晕,Claude Code、Cursor、Windsurf、Gemini CLI、Codex CLI、Cline、Trae、Antigravity、Qwen Code、Kiro……名字一长串。其实只要先归个类,选择就清爽多了。

AI 编程工具三大流派
├─ CLI 命令行 Agent
│  ├─ Claude Code       (Anthropic)
│  ├─ Gemini CLI        (Google,开源)
│  ├─ Codex CLI         (OpenAI)
│  ├─ Qwen Code         (阿里,开源)
│  └─ Cursor CLI / OpenCode (开源)
│
├─ AI 原生 IDE
│  ├─ Cursor            (VS Code 二次开发)
│  ├─ Windsurf          (Google 收购)
│  ├─ Antigravity       (Google)
│  ├─ Trae              (字节)
│  └─ Zed               (Rust 原生高性能)
│
└─ VS Code 插件类
   ├─ GitHub Copilot
   ├─ Cline
   ├─ Continue
   └─ Roo Code

CLI 命令行 Agent:在终端(就是那个黑色窗口)里运行的 AI 助手。它能直接读你的项目目录、改文件、跑命令、提 PR,权限最完整,适合做大范围的代码改造、Git 工作流自动化、跨文件重构。学习曲线相对陡一点,但一旦上手了,处理复杂工程任务的效率最高。

AI 原生 IDE:把 AI 能力深度嵌入到一个看起来像编辑器的图形界面里。优势是上手友好,你能直接看到 AI 修改了哪些代码、对比 diff,适合喜欢可视化操作的人,以及需要做大量前端页面的场景。

VS Code 插件:在原版 VS Code 上加个插件,既保留原来的工作习惯,又能调用 AI。优点是迁移成本接近零,缺点是受插件 API 的限制,有些深度自治的 Agent 操作做不出来。

2.2 几款主力产品的真实体感

下面这张表是莫潇羽@无忆研习社 结合自己使用 + 各家公开评测整理出来的,关键维度都涵盖到位:

2.3 给完全零基础读者的选型建议

很多新手会卡在"我到底该用哪个"。下面给一个简化版的决策思路,不一定唯一最优,但能让你少走弯路:

• 完全没用过命令行、想看见可视化界面:从 Cursor 入门,它有清晰的图形界面,改代码时还能直接对比新旧文件。
• 能接受敲命令、想长期培养习惯:直接上 Claude Code,搭配国内平台接入,费用可控,Skills 生态正在成熟。
• 想白嫖、对前端 UI 类工作偏多:Gemini CLI 或 Antigravity,Google 系给 Gemini 模型留了不错的免费额度。
• 预算紧又只能用 VS Code:Cline + 智谱 GLM 或通义千问 Code 系列免费额度,基本能跑起来。

2026 年的一个共识是:单押一个工具不如组合 2 到 3 个工具。比如日常补全用 Cursor、复杂重构和大改用 Claude Code、大仓库探索用 Gemini CLI——让每个工具发挥它最擅长的那个维度。

本文后面会重点拆解 Claude Code,因为它的整体方法论(CLAUDE.md、Skills、子代理)最完整,把这一个工具吃透了,迁移到其他工具几乎没有额外学习成本。

三、Claude Code 完整环境配置:Node.js 安装到国内平台接入

这一节是纯实操,目标是让一个完全没装过开发环境的人也能把 Claude Code 跑起来。从安装 Node.js 开始,一步一步说清楚为什么要这么做,以及哪些坑要提前避开。

3.1 先把 Node.js 装好

Claude Code 本身是一个 Node.js 程序,所以 Node.js 是它运行的底座。打开 nodejs.org 官网,选择 LTS(长期支持版本)下载,Windows 用户下载 .msi 安装包,一路默认下一步即可;macOS 用户直接下载 pkg 安装包;Linux 用户推荐用包管理器装。

安装完成后,一定要打开一个新的命令行窗口(Windows 按 Win+R 输入 cmd 回车,或者用 PowerShell;macOS / Linux 打开终端),输入下面这行做验证:

node -v

如果显示一个版本号比如 v20.19.0 或更高,就说明 Node.js 已经成功安装。官方要求 Node.js v18.0 及以上,实测建议直接装 v20 或者最新 LTS,避免一些边缘的兼容问题。

⚠️ Windows 用户额外注意:Claude Code 官方推荐在 Windows 上通过 WSL(适用于 Linux 的 Windows 子系统) 或者 Git for Windows 提供的 Git Bash 来运行,直接用 cmd 偶尔会有路径解析的奇怪问题。第一次用建议装一个 Git for Windows,它会附带一个干净的 Bash 环境,各种类 Unix 命令开箱即用。

3.2 安装 Claude Code

环境准备好之后,在命令行里执行下面这条命令:

npm install -g @anthropic-ai/claude-code

-g 表示全局安装,装完后你在任何目录下输入 claude 都能启动它。

如果你在国内,npm 默认源走的是国外,可能很慢甚至连不上。莫潇羽的做法是先把 npm 镜像切换到国内的:

npm config set registry https://registry.npmmirror.com

切换之后再 install,基本秒级完成。装完做个验证:

claude --version

输出一个版本号就 OK。Mac 或 Linux 用户如果遇到 EACCES 权限报错,可以在命令前加 sudo;Windows 用户建议以管理员身份打开 PowerShell 再装。

3.3 国内接入方案:阿里云百炼 Coding Plan

下面是国内用户配置 Claude Code 最关键的一步——把它从默认连官方账号切换成连国内模型平台。这样做有两个好处:网络稳定 + 费用便宜。

目前对国内用户最友好的两个平台是:

• 阿里云百炼(Model Studio):bailian.console.aliyun.com,推出了专门面向 AI 编程的 Coding Plan 套餐,内含 Qwen3.5-Plus、Qwen3-Coder-Plus、GLM-4.7、Kimi-K2.5 等多个满血模型可以切换。
• 火山引擎方舟:www.volcengine.com/product/ark,字节系,主推豆包代码模型,同样兼容 Anthropic API 协议。

这两家都提供了与 Anthropic API 完全兼容的接口,所以 Claude Code 不需要做任何二次开发就能切过去。下面以阿里百炼 Coding Plan 为主线讲清楚。

配置前要分清的两类 API Key

阿里百炼里其实有两套 API Key,不能混用,这是新手最常踩的坑:

强烈建议选 Coding Plan,原因下面单独说。

settings.json 的写法

在用户主目录下找到(或者新建) .claude 文件夹,在里面创建 settings.json 文件。如果目录不存在,先创建:

mkdir -p ~/.claude

然后用任意文本编辑器打开 ~/.claude/settings.json,写入:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "把你的 Coding Plan API Key 粘到这里",
    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_MODEL": "qwen3.5-plus"
  }
}

⚠️ 重点提醒:

• 套餐用户用的 key 名字是 ANTHROPIC_AUTH_TOKEN,不是 ANTHROPIC_API_KEY
• Base URL 要带 coding. 前缀
• 模型可以填写 qwen3.5-plus、qwen3-coder-plus、qwen3-coder-next、glm-4.7、kimi-k2.5 等套餐支持的型号

保存之后关闭当前命令行窗口,重新开一个新窗口让环境变量生效。

火山引擎方舟备用方案

如果某天阿里百炼不稳,你切到火山引擎也是几乎一样的流程。在火山引擎方舟控制台开通 Claude Code 接入服务后,把 settings.json 里的 ANTHROPIC_BASE_URL 换成方舟提供的对应地址,Key 换成方舟的 Key,模型换成豆包代码模型的型号即可。建议两家都申请,某一家抖动时可以快速切换。

3.4 启动 Claude Code 与第一个验证项目

新建一个用来练手的空文件夹,路径里不要有中文(避免编码问题),然后在这个目录下打开命令行,输入:

claude

第一次启动会问你是否信任当前目录,选信任(回车选 Yes, proceed)。进入交互界面之后,直接用中文问它:

请简单介绍一下你当前的运行状态和接入的模型。

如果它正常返回了一段中文,告诉你它运行在你的本地、当前使用的模型是 Qwen 系列或者你配置的型号,那就完全跑通了。

3.5 套餐 vs 按量,为什么我推荐套餐

这里单独展开讲一下计费方式,因为很多新手在这里会有心理负担。

Claude Code 在执行一个编程任务时,单次消耗的 token 量非常惊人。它不只是"回你一句话",而是要读取整个代码文件、分析上下文、生成新代码、再做一轮自检。一个中等规模的项目,一天累计消耗几百万 token 完全是常态。如果按量计费,账单会让你心跳加速。

套餐订阅的逻辑完全不同——固定月费,用多少都是这个价,心理上没有任何负担。以阿里百炼当前的 Coding Plan 为例,Lite 基础版和 Pro 高级版都设计成"按请求次数计费"而非"按 token 计费",这意味着你写一个超长的 prompt 让它分析整个项目,也只算一次请求,根本不用焦虑。

💡 莫潇羽的实操体验:学习阶段每天用 4 到 6 小时跑各种小项目,基础套餐基本撑得住;真正进入"长时间在复杂项目里反复跑"的阶段,升到更高一档套餐就够了。

另外,不同模型的免费额度是相互独立的。阿里百炼模型广场里很多模型都有几百万到上千万 token 的免费额度,Qwen3-Max-Preview、GLM-4.7、DeepSeek-V3.2、Kimi-K2 等各家旗舰都能领。如果你只是练手、跑跑小工具,这些免费额度排队用完都得好几个月。

3.6 不想改配置文件?试试可视化切换工具

如果你嫌每次手动改 settings.json 麻烦,可以装一个开源的图形化工具叫 CC Switch(cc-sw)。它提供了可视化界面,你可以在里面同时配置阿里百炼、火山引擎、智谱 GLM、DeepSeek 等多家服务商,一键切换,还自带"健康检查"功能,可以测试当前 API Key 是否还有效。

类似工具还有 claude-code-router ,它的原理是在本地起一个小服务,Claude Code 实际访问的是这个本地服务,本地服务再决定把请求路由到哪家供应商。配置略复杂一些,但优势是可以做"长上下文走 A 平台,默认对话走 B 平台,联网搜索走 C 平台"这种精细化路由。

3.7 常见报错与排查思路

新手前几次跑 Claude Code,大概率会遇到下面这几个错。提前知道一下,出问题时心里不慌。

报错一:Unable to connect to Anthropic services

这是最常见的报错,意思是 Claude Code 默认要联官方 Anthropic 服务,但你的网络通不到。这一类报错并不代表配置错了,而是 Claude Code 在启动阶段还有一个"onboarding 检查"在跑。处理办法是在你的用户主目录下找(或新建)~/.claude.json,把里面的 hasCompletedOnboarding 字段从 false 改成 true,保存后重启终端。这一步本质上是告诉它"我已经完成首次设置,别再去连外网了",之后所有请求都会按 settings.json 走你配置的国内 BaseURL。

报错二:401 Unauthorized 或 Invalid API Key

九成原因是 Key 类型和 BaseURL 不匹配。前面强调过的那张表再贴一遍:sk-sp- 开头的 Key 必须配 coding.dashscope.aliyuncs.com 那个 BaseURL,普通 sk- 开头的 Key 必须配标准 BaseURL。两套配置不能交叉用,出错就核对一下这两个字段。

报错三:Windows 下 claude 命令找不到

通常是 npm 全局安装的路径没加到系统 PATH 里。在 PowerShell(以管理员身份)里跑下面这段:

$npmPath = $(npm config get prefix)
[System.Environment]::SetEnvironmentVariable(
  "Path",
  [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath",
  "User"
)

跑完必须关闭当前 PowerShell 窗口再重新打开才会生效。

报错四:中文路径下文件读取异常

Windows 上 cmd 默认编码是 GBK,Claude Code 在某些场景下会按 UTF-8 解码,遇到中文路径直接报错。我的做法是把所有练手项目放在 D:\projects\ 这类纯英文路径下,从根上避免这类问题。如果项目已经在中文目录里了,可以在启动前先跑 chcp 65001 把 cmd 临时切到 UTF-8 编码,但治标不治本。

3.8 关于 WSL(Windows 用户进阶)

Windows 上长期跑 Claude Code,我个人最推荐的方案不是 cmd 也不是 PowerShell,而是 WSL2(适用于 Linux 的 Windows 子系统第二版)。开 WSL 后,你在 Windows 里就有了一个真正的 Ubuntu 环境,Bash、各种命令行工具、文件系统都是 Linux 原生的,Node.js 安装、npm 全局路径、权限管理都跟标准 Linux 一致,中文路径乱码这一类典型问题基本就不存在了。

开启 WSL2 的步骤大致是:管理员身份打开 PowerShell,跑 wsl --install,系统会自动装 Ubuntu。装完重启,设置用户名密码,后面就和用一个 Linux 机器没区别。把 Claude Code 装在 WSL2 里,跟 Windows 主机之间还能通过 /mnt/c/ 互访文件,体验比纯 Windows 干净很多。

四、CLAUDE.md 与 Skills 体系:渐进式披露让 AI 真正懂你

环境装好之后,很多人就直接开始用了。但说实话,如果你不懂 CLAUDE.md 和 Skills,Claude Code 至少有一半的能力你是没用上的。这一节把这两个机制讲清楚,它们决定了你长期使用的效率上限。

4.1 CLAUDE.md:项目级长期约定

CLAUDE.md 是放在项目根目录下的一个 Markdown 文件,你可以把它理解成"告诉 AI 的项目守则"。每次你在这个项目里启动 Claude Code,它都会自动把这个文件的内容当作前置上下文读取一遍,把里面写的规则当作长期生效的指令。

举几个写在 CLAUDE.md 里特别有价值的内容:

# 项目约定

## 启动与端口
- 启动脚本里所有文本(包括日志)必须用纯英文,避免 Windows 命令行 GBK 乱码
- 后端默认端口从 8765 开始往后挑,不要占用 3000、5173、8080 这类常用端口

## 代码风格
- 代码内注释统一用中文
- Python 项目优先用 uv 管理依赖,不要混用 pip 与 conda
- 前端组件单文件不超过 400 行,超过就拆

## 流程约定
- 每完成一个功能,在 docs/CHANGELOG.md 里追加一条变更说明
- 修复 bug 时先复现、再修,不要"看起来对就行"

写过几个项目之后你会发现,这些规则每个项目都需要,但每次都说一遍非常累。CLAUDE.md 让这些规则一次写入、长期生效。它最大的价值不是技术,而是"把人的经验沉淀下来"。

4.2 Skills:任务级专项技能包

CLAUDE.md 是项目层面的约定,而 Skills(技能包) 是任务层面的专项手册。

每一个 Skill 本质上就是一个文件夹,里面至少有一个 SKILL.md 文件,头部用 YAML frontmatter 写好名字和描述,内容是这个领域的执行指南。Claude Code 在启动时只会读取所有 Skill 的元数据(名字 + 描述,加起来才几百 token),平时不加载正文。只有当你的请求和某个 Skill 的描述匹配上,它才会真正读取那个 Skill 的完整内容——这个机制叫"渐进式披露"(Progressive Disclosure)。

~/.claude/skills/                       # 个人级,所有项目通用
├── frontend-design/
│   ├── SKILL.md                        # 必须
│   ├── color-tokens.md                 # 参考资料,按需读
│   └── scripts/
│       └── check-contrast.py           # 可执行脚本

.claude/skills/                         # 项目级,跟项目走,可被 git 共享
└── api-conventions/
    └── SKILL.md

一个最简单的 Skill 长这样:

---
name: frontend-design
description: 当用户需要创建前端组件或调整 Web UI 视觉效果时触发,统一使用本规范
---

# 前端设计技能

## 适用场景
用户提到"页面""组件""按钮""做个 UI""换个配色"等关键词时使用。

## 设计原则
- 优先使用 Tailwind CSS,不引入额外的 UI 框架,除非用户明确指定
- 主色 #4F46E5,圆角 12px,所有交互元素必须有 hover 与 focus 态
- 不要使用过度饱和的渐变色,正文字号默认 16px,行高 1.6

## 输出要求
- 每个组件给出 props 类型定义
- 用例代码必须可直接复制运行

description 字段非常关键,它决定了 Claude 能不能在恰当的时机自动调用这个 Skill。写描述时要尽量包含"触发关键词"和"使用场景"。

4.3 Skills 的三种典型用法

用法一:单一技能(最常见)

最普通的用法,就像上面那个 frontend-design 一样,写好规范,以后说"做一个登录页"它就会自动按这个规范来。

用法二:嵌套引用(套娃)

这是 Skills 的进阶玩法。假设你要做客服机器人,基础应答规范在主 Skill 里,但每个产品有不同的话术。你可以在主 SKILL.md 里写:

如果用户的问题涉及到 X 产品,请读取 references/product-x.md;
如果涉及到退货流程,请读取 references/refund-flow.md。

这样 Claude 只在真正需要的时候才去读对应的附件,其他时候不消耗任何上下文,实现了"按需加载"。这个思路可以无限套娃,形成一棵资料树,只有用到的分支会被加载。

用法三:脚本调用(自动化执行)

Skills 不只能存指令,还能调用确定性脚本。比如你把"批量压缩并重命名图片"封装成一个 Python 脚本:

---
name: image-batch-process
description: 用户需要批量处理图片(压缩、改尺寸、重命名)时触发
---

# 图片批处理技能

## 工作流
当用户要求批处理图片时,直接调用:
\`\`\`bash
python scripts/process_images.py --input <用户提供的路径> --output ./out
\`\`\`
不要尝试自己实现压缩逻辑,直接调用脚本即可。

这种做法的好处是:Claude 不需要把脚本内容读进上下文,只调用它,只看返回结果——既快又稳。

4.4 怎么获取和创建 Skill

获取渠道大致有三个层级:

graph LR
    A[GitHub anthropics/skills 官方仓库] --> D[直接安装]
    B[社区开源 Skill 包] --> D
    C[你自己的实战沉淀] --> D
    D --> E[~/.claude/skills/]

我的建议是:不要一上来就疯狂下载社区 Skill 包。先用 Claude Code 跑两三个项目,把你反复要叮嘱它的那些事情(比如某种排版、某种代码风格、某种部署规范)整理成 Skill,这些才是真正属于你的资产。社区包看着热闹,十有八九是你用不上的。

莫潇羽@无忆研习社 自己的 Skill 目录里,沉淀下来的有"博文改写规范""前端美学约束""桌面应用打包规范""README 结构模板"这几个,数量不多,但每个都用了几十次以上。

4.5 渐进式披露:为什么它比"一股脑塞 prompt"省钱

很多人第一次听说 Skills,直觉反应是:"那我把规范全写在 CLAUDE.md 里不行吗?"

理论上可以,但成本完全不同。CLAUDE.md 是每次启动都会被完整加载到上下文里的,你写得越长,每次对话起步就吃掉越多 token。如果你有 20 条领域规范,全塞 CLAUDE.md,光启动就消耗几万 token,而且其中绝大多数和你当前这个任务毫无关系。

Skills 走的是另一条路径——三层加载:

层级 1:启动时只读元数据(name + description)
        ↓ 这一层始终在,但每个 Skill 才消耗几十到一百多 token

层级 2:任务匹配时,加载对应 Skill 的 SKILL.md 正文
        ↓ 几千 token,只在被触发时才进上下文

层级 3:正文里引用了某个参考文件 / 脚本,才去读它
        ↓ 大块资料按需才进上下文

这套机制叫 Progressive Disclosure(渐进式披露),核心思想是:只在真正需要的时候才把信息加载进来。它的好处是你可以装很多很多 Skill 都不会拖累性能,日积月累形成一个属于你自己的"领域专家库",随用随调。

4.6 Skills 和 MCP:经常被混淆的两个机制

Claude Code 还有一个跟 Skills 平行的能力叫 MCP(Model Context Protocol,模型上下文协议)。这两个东西经常被混着说,但其实定位完全不同:

简单说:Skills 是"内功心法",MCP 是"外接装备"。一个标准化流程能不能跑通靠 Skills;一个外部系统能不能被调用靠 MCP。两者经常组合使用——比如 Skills 里规定"代码改完后必须运行 lint",而 lint 工具本身通过 MCP 暴露给 Claude 调用。

理解这层关系之后,你在选择"要不要给某个能力做成 Skill"还是"做成 MCP"时就不会犹豫:纯文字 / 流程 / 规范 → Skill;需要执行真实操作、访问外部数据 → MCP。

五、实战一:桌面文件整理工具——从需求到打包的完整链路

光讲理论容易飘,下面用一个真实做过的项目把整个流程串起来。第一个案例是桌面文件整理工具——选中一个混乱的目录,工具能自动按类型 / 时间归档,也能用鼠标把文件拖到指定目录。这个项目纯本地操作,不依赖任何外部 AI API,逻辑清晰,适合入门。

5.1 写代码之前,先把需求写清楚

刚开始做 AI 编程的人有一个非常普遍的误区——把模糊的需求丢给 AI 让它发散。前两次确实会很有惊喜感:"哇,它居然真的做出来了!"但等你做到第五个项目,你就会意识到:前期需求写得有多清楚,后期改动量就有多少。

下面这套需求是我反复优化几次后的最终版,可以直接借鉴格式:

## 项目名
桌面端文件整理工具

## 核心场景
用户选择一个混乱的文件夹,工具帮 ta 把里面的文件归档整理。

## 必须有的功能
1. 选择目录后,遍历读取所有文件(包括子文件夹)
2. 提供两种模式:
   - 一键整理:按文件类型 / 按创建时间 / 类型+时间混合
   - 手动拖拽:把单个文件拖到右侧目标文件夹,执行剪切或复制
3. 预览区显示文件缩略图:
   - 图片:压缩后的缩略图
   - 视频:取首帧
   - 文本:读前 20 行
   - 压缩包:列出文件清单(不解压)
4. 系统隐藏文件(. 开头)和子目录里的隐藏文件都不读取

## 交互布局(文字示意图)
+----------------------------------------------------+
| 顶部操作栏:[选目录] [一键整理▼] [复制/剪切切换]    |
+------------+-----------------------+---------------+
| 左侧导航   |    中央预览区         | 右侧目标盘    |
| 文件夹树   |    瀑布流缩略图       | 多个文件夹槽  |
|            |    [大小调节滑块]     | 拖动文件到这  |
+------------+-----------------------+---------------+

## 技术要求
- 整体架构请你先给方案,确认后再写
- Python 后端 + Web 前端,浏览器打开
- 启动脚本所有文本用纯英文,避免命令行乱码
- 最终打包成解压即用的便携包

## 注意点
- 长时间复制大文件,前端必须显示进度条,不能"瞬间完成"
- 默认推荐用复制模式,剪切是高风险操作

需求最后一定要加一句:"以上是我的初步想法,请先给我专业的完善建议和技术架构