AI工具 on Yanmu

web-design-skill 实操手册（详细版）

Wed, 27 May 2026 00:00:00 +0800

web-design-skill 实操手册（详细版）

适用工具： Claude Code / OpenCode 目标： 跟着本笔记，你将用 AI 生成一个高质量的太空探索博物馆网页，并录制为视频 预计耗时： 40-90 分钟（含录制）

在开始之前：理解我们要做什么

整体流程概览

`1`	`准备环境 → 安装 Skill → 创建项目 → 裸跑体验 → Skill 加持 → 对比 → 录制`

为什么要先"裸跑"再用 Skill？

这是一个对比实验。就像视频里演示的那样：

如果你直接用 Skill，你不会感受到 Skill 的价值
先让 AI 自由发挥 → 你会看到典型的 AI 味网页（紫粉蓝渐变、大圆角卡片、Emoji 图标……）
然后用 Skill 再做一遍 → 你会亲眼看到同一个主题、同一个模型做出截然不同的效果

这个对比过程本身就可以录制成视频。

你需要的工具清单

工具	是什么	去哪里获取
终端	你和 AI 对话的地方	Windows: PowerShell / Terminal；macOS: Terminal
Claude Code 或 OpenCode	AI 编码 Agent	见下方安装说明
Git	从 GitHub 下载 Skill 文件	`winget install Git.Git`（Win）/ `brew install git`（macOS）
浏览器	预览网页效果	Chrome / Edge / Firefox
录屏软件（可选）	录制操作过程	OBS Studio（免费）/ 系统自带录屏

确认 Agent 已就绪

如果你用 Claude Code

是什么： Anthropic 官方的终端 AI 编码工具，你在终端里打字，它帮你读文件、写代码、执行命令。

确认已安装：

打开终端（Windows 用 PowerShell，macOS 用 Terminal），输入：

`1`	`claude --version`

如果显示版本号（如 1.0.x），说明已安装。

如果没安装：

1
2

# 需要先安装 Node.js（https://nodejs.org），然后：
npm install -g @anthropic-ai/claude-code

确认 API Key 已配置：

Claude Code 需要 Anthropic API Key 才能使用。在终端输入：

`1`	`claude config list`

如果看到 apiKey 已设置，就 OK。如果没有，运行：

`1`	`claude config set apiKey sk-ant-xxxxx`

（把 sk-ant-xxxxx 换成你的真实 Key）

为什么要确认这个？ 后续所有操作都依赖 Agent 能正常调用 AI 模型。如果 Key 没配好，后面所有步骤都会卡住。

如果你用 OpenCode

是什么： SST 团队开发的开源终端 AI 编码工具，和 Claude Code 类似，但支持多种模型（Claude、GPT 等），界面是 TUI（终端图形界面）。

确认已安装：

`1`	`opencode --version`

如果显示版本号，说明已安装。

如果没安装（二选一）：

# 方法 1：通过 Go 安装（需要先安装 Go）
go install github.com/sst/opencode@latest

# 方法 2：通过 Homebrew（macOS/Linux）
brew install sst/tap/opencode

确认模型已配置：

OpenCode 启动后，在 TUI 界面中按快捷键查看设置，确认已选择 Claude 模型并配置好 API Key。

为什么要确认这个？ OpenCode 支持多个模型供应商，你需要确保选择的是 Claude（而非 GPT），因为 web-design-skill 的提示词是针对 Claude 优化的。

创建项目目录

创建工作文件夹

打开终端，执行以下命令：

# 切换到你想要存放项目的目录（比如桌面）
cd ~/Desktop

# 创建项目文件夹
mkdir space-museum-demo

# 进入项目文件夹
cd space-museum-demo

初始化 Git 仓库

`1`	`git init`

为什么要 Git？ 不是为了推送到 GitHub，而是为了对比两个版本的差异。后面做完两个版本后，你可以用 git diff 精确看到 Skill 带来了哪些变化。

创建初始文件

用终端创建一个空的 HTML 文件：

Claude Code 方式：

1
2

# 启动 Claude Code，告诉它创建一个空的 HTML 骨架
claude

进入 Claude Code 后输入：

请在当前目录创建一个 index.html 文件，只包含最基本的 HTML5 结构（DOCTYPE、head、body），不需要任何样式和内容。HTML lang 设为 zh-CN，title 设为"太空探索博物馆"。

Claude Code 会自动创建文件。输入 /exit 退出。

OpenCode 方式：

1
2

# 启动 OpenCode
opencode

在 OpenCode 的 TUI 界面中输入同样的提示词。OpenCode 会创建文件。按 Ctrl+C 或 q 退出。

或者手动创建（不依赖 Agent）：

# Windows PowerShell
@"
<!DOCTYPE html>
<html lang=`"zh-CN`">
<head>
  <meta charset=`"UTF-8`">
  <meta name=`"viewport`" content=`"width=device-width, initial-scale=1.0`">
  <title>太空探索博物馆</title>
</head>
<body>
</body>
</html>
"@ | Out-File -Encoding utf8 index.html

# macOS / Linux
cat > index.html << 'EOF'
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>太空探索博物馆</title>
</head>
<body>
</body>
</html>
EOF

启动本地预览服务器

在终端中（不要在 Agent 里，另开一个终端窗口）执行：

1
2
3

# 方法 1：用 Node.js 的 serve（推荐，最简单）
npx serve .
# 首次会提示你安装 serve，输入 y 确认即可

1
2

# 方法 2：用 Python
python -m http.server 8080

打开浏览器访问 http://localhost:3000（npx serve 默认端口）或 http://localhost:8080（Python 默认端口），你应该看到一个空白页面。

为什么要提前启动预览服务器？ 因为后面 AI 生成代码后，你需要立刻在浏览器里看效果。提前启动好服务器，后面只需要刷新浏览器就行，不用每次都重新启动。

保持这个终端窗口开着，不要关掉它。后续你在另一个终端窗口里和 AI 对话。

下载 web-design-skill

克隆仓库

在哪里操作： 新开一个终端窗口（不要关掉上面的预览服务器窗口）

# 进入项目目录
cd ~/Desktop/space-museum-demo

# 克隆 skill 仓库到当前目录下
git clone https://github.com/ConardLi/web-design-skill.git

执行完后，你的项目目录结构会变成这样：

space-museum-demo/
├── index.html                  ← 你创建的空 HTML 文件
└── web-design-skill/           ← 刚克隆下来的仓库
    ├── README.md               ← 仓库说明文档
    ├── skill.md                ← ⭐ 核心 Skill 文件（约 400 行）
    ├── reference.md            ← 参考代码模板
    └── ...                     ← 其他文件（demo 等）

为什么要克隆整个仓库而不只是复制文件？

skill.md 是核心，但 reference.md 也很重要（里面是代码模板参考）

仓库里的 demo 文件可以作为学习参考

后续作者更新了你可以直接 git pull 获取最新版本

查看 Skill 文件内容（可选但推荐）

1
2

# 查看 skill.md 的前 30 行，了解它的结构
head -30 web-design-skill/skill.md

裸跑体验 — 见识 AI 的"原生审美"

🎯 目的： 让 AI 用默认方式生成网页，观察它的"原生审美"。

启动 Agent（不加载 Skill）

Claude Code：

# 确保在项目目录下
cd ~/Desktop/space-museum-demo

# 启动 Claude Code
claude

OpenCode：

1
2

cd ~/Desktop/space-museum-demo
opencode

关键： 这一步不要引用任何 Skill 文件。让 AI 用它自己的默认行为来工作。

输入设计需求

在 Agent 的对话框中，输入以下内容（直接复制粘贴）：

请帮我做一个太空探索博物馆的线上展览网页，所有代码写在一个 index.html 文件里（HTML + CSS + JS 都内联），要求如下：

1. 深色主题，有宇宙感和科幻氛围
2. Hero 区域展示博物馆名称"星际探索博物馆"和一句标语
3. 展品卡片区域，展示 4 个太空探索里程碑事件（加加林、阿波罗 11 号、哈勃望远镜、韦伯望远镜）
4. 时间线区域，展示太空探索的关键年份
5. 有滚动动画效果（元素随滚动渐入）
6. 响应式布局，手机端也能看

请直接生成完整代码，写入 index.html 文件。

为什么给这么详细的需求？ 这是裸跑测试，我们要排除"需求不清"这个干扰因素。给足够详细的需求，这样最终效果不好就只能是 AI 的审美问题，而不是"你没说清楚"。

等待 AI 生成

AI 会开始工作。你会看到它：

先思考/规划
然后写入 index.html 文件
可能会告诉你"已完成"

整个过程大约需要 1-3 分钟。

查看结果

切到浏览器，刷新 http://localhost:3000（或 http://localhost:8080）。

你应该能看到一个完整的网页。仔细观察并记录以下内容：

📝 观察清单（边看边打勾）

配色：

背景是否是深色？用了什么颜色？

是否有紫粉蓝的渐变？（这是 AI 最喜欢的"霓虹风"）

文字颜色和背景的对比度够不够？

布局：

Hero 区域是不是标准的"居中标题 + 副标题"？

展品卡片是不是等宽的网格排列？（这是 AI 最爱用的布局）

是否有大胆的留白？还是把每个角落都塞满了？

字体：

用了什么字体？是不是最常见的那几个？（如 Inter、Roboto）

标题和正文的字体有没有区分？

AI 味特征：

有没有用 Emoji 当图标？（🚀🌌✨ 等）

有没有大圆角卡片（border-radius: 20px 那种）？

有没有到处都是的发光效果（glow、box-shadow with color）？

有没有堆砌的假数据？

整体评分：______ / 100

保存裸跑版本

在 Agent 中输入：

`1`	`请把当前的 index.html 复制一份，命名为 index-no-skill.html`

或者退出 Agent 后在终端执行：

`1`	`cp index.html index-no-skill.html`

为什么要保存？ 后面用 Skill 重做时，index.html 会被覆盖。保留一份裸跑版本才能做对比。

安装 Skill 到 Agent 中

🎯 目的： 把 web-design-skill 的规则注入到 Agent 的系统提示中，让 AI 后续所有的设计决策都遵循这些规则。

Claude Code — 两种安装方式

方式 A：写入 CLAUDE.md（推荐，永久生效）

什么是 CLAUDE.md？

这是 Claude Code 的"项目说明书"
Claude Code 每次启动时都会自动读取这个文件
文件里的内容会成为 AI 的"行为准则"
就像给 AI 一份"员工手册"，它会一直遵守

在哪里创建： 项目根目录下（即 ~/Desktop/space-museum-demo/CLAUDE.md）

操作步骤：

# 确保在项目目录下
cd ~/Desktop/space-museum-demo

# 创建 CLAUDE.md（把 Skill 内容作为规则写入）
# 方法：读取 skill.md 的内容，写入 CLAUDE.md

在 Claude Code 中操作：

claude

进入后输入：

`1`	`请读取 web-design-skill/skill.md 文件的全部内容，然后创建一个 CLAUDE.md 文件，把 skill.md 的内容写进去。`

等待 Claude Code 完成。输入 /exit 退出。

验证：

# 查看 CLAUDE.md 是否存在
ls -la CLAUDE.md

# 查看内容是否正确（应该能看到 skill.md 的内容）
head -20 CLAUDE.md

你应该能看到 Skill 文件的内容已经写入了 CLAUDE.md。

CLAUDE.md 的作用原理：
1
2
3
4
5
6
7
你启动 Claude Code
       ↓
Claude Code 自动读取 CLAUDE.md
       ↓
CLAUDE.md 的内容被注入到 AI 的系统提示中
       ↓
AI 后续所有的决策都会参考这些规则
这就像你给一个新员工发了一份设计规范手册，他后续做所有设计都会遵守这份手册。

方式 B：在对话中引用（临时生效）

如果你不想修改 CLAUDE.md，也可以每次在对话中引用 Skill 文件：

claude

然后输入：

`1`	`@web-design-skill/skill.md 请根据这个 Skill 文件的规则来帮我设计网页。`

方式 A vs 方式 B 的区别：

方式 A（CLAUDE.md）方式 B（对话引用）

持久性永久生效，每次启动都加载仅当前对话有效

适合场景你要长期用这个 Skill 做设计你只是想试一下

操作一次设置，后续无感每次都要手动引用

	方式 A（CLAUDE.md）	方式 B（对话引用）
持久性	永久生效，每次启动都加载	仅当前对话有效
适合场景	你要长期用这个 Skill 做设计	你只是想试一下
操作	一次设置，后续无感	每次都要手动引用

OpenCode — 安装方式

OpenCode 支持读取项目根目录的配置文件来注入自定义指令。

方式 A：写入 AGENTS.md（推荐）

什么是 AGENTS.md？

类似于 Claude Code 的 CLAUDE.md
OpenCode 启动时会自动读取
内容会成为 AI 的行为准则

操作步骤：

cd ~/Desktop/space-museum-demo

# 把 skill.md 的内容复制到 AGENTS.md
cp web-design-skill/skill.md AGENTS.md

或者用 OpenCode 自身操作：

`1`	`opencode`

进入后输入：

`1`	`请读取 web-design-skill/skill.md 文件的全部内容，然后创建一个 AGENTS.md 文件，把 skill.md 的内容写进去。`

注意： 如果 OpenCode 也支持读取 CLAUDE.md（很多工具兼容这个格式），你也可以用 CLAUDE.md 作为文件名。具体取决于你使用的 OpenCode 版本。

方式 B：在对话中引用

`1`	`opencode`

在对话中直接告诉 AI：

`1`	`请先阅读 web-design-skill/skill.md 文件，后续所有设计工作都遵循这个文件中的规则。`

验证 Skill 是否生效

无论用哪种工具，验证方法都一样：

启动 Agent，输入：

`1`	`在开始设计之前，请告诉我：按照你的设计系统，你会使用什么配色方案？什么字体？什么间距规则？有哪些绝对不能做的事情？`

如果 Skill 生效了， AI 的回答应该包含：

提到 OKLCH 色彩空间
列出具体的字体推荐（不是泛泛的"使用 sans-serif"）
提到"去除 AI 味"的具体规则（不使用渐变、不用 Emoji 当图标等）
提到工作流（先确认设计系统 → 快速 V0 → 迭代 → 验证）

如果 Skill 没生效， AI 的回答会很笼统：

“我会使用现代的配色方案”
“使用清晰的 sans-serif 字体”
没有提到 OKLCH 或具体的反面规则

如果没生效怎么办？

Claude Code：检查 CLAUDE.md 是否在项目根目录，文件名是否拼写正确

OpenCode：检查 AGENTS.md 是否在项目根目录

通用：尝试在对话中直接引用文件（方式 B）

Skill 加持 — 打磨高级感

🎯 目的： 用同样的需求，让 Skill 引导 AI 做出完全不同的网页。

启动新的对话

重要：必须新开一个对话！

Claude Code：

1
2
3

# 退出之前的对话（如果还在里面的话）
# 然后重新启动
claude

OpenCode：

`1`	`opencode`

为什么要新开对话？ 上一个对话里 AI 已经"看过"裸跑版本的代码了，如果在同一个对话里重做，AI 可能会受到之前代码的影响。新开对话确保 AI 从零开始，唯一的变化就是多了 Skill 的规则。

输入设计需求

这次我们故意只给极简需求，测试 Skill 引导下的 AI 自主决策能力：

`1`	`帮我做一个太空探索博物馆的线上展览网页，所有代码写在一个 index.html 文件里。`

为什么这次需求这么简短？

阶段 A：AI 提问（如果信息不足）

你应该会看到： AI 先问你几个关键问题，比如：

在开始之前，我想确认几个关键点：
1. 目标受众是谁？（太空爱好者 / 学生 / 大众？）
2. 希望什么风格？（杂志感 / 科幻感 / 极简？）
3. 有没有参考网站？

你的操作： 根据你的想法回答。例如：

1
2
3

1. 大众，对太空感兴趣但不一定专业
2. 科幻感，但要高级，不要廉价的霓虹感
3. 没有参考，你来决定

如果你的初始需求已经足够详细（比如第四步那种），AI 可能跳过提问直接进入下一步。这是正常的——Skill 的规则是"信息够就直接干"。

阶段 B：AI 说明设计系统

你应该会看到： AI 在写代码之前，先用自然语言描述它的设计系统：

设计系统：
━━━━━━━━━━━━
配色方案（基于 OKLCH）：
- 背景：oklch(15% 0.02 260) — 极深的太空蓝
- 主色：oklch(70% 0.15 250) — 冷蓝色
- 辅色：oklch(60% 0.12 310) — 深紫色
- 文字：oklch(95% 0.01 260) — 近白色

字体：
- 标题：Orbitron（科技感强）
- 正文：Space Grotesk（可读性好）

间距系统：基于 8px 网格

布局策略：杂志式大图排版，非传统的卡片网格

你的操作： 仔细审核，提出修改意见。例如：

1
2
3

配色可以，这个深空蓝很对味。
字体也 OK。
继续吧。

或者如果不对味：

`1`	`配色太冷了，我希望有一点暖色点缀（比如星云的橙红色），让画面更丰富。`

为什么要先确认设计系统？ 这是 Skill 的核心优化之一。如果 AI 直接写代码，等你看到成品时发现配色不对，就要推翻重来。在写代码之前确认设计系统，成本为零，方向错了随时改。

阶段 C：AI 输出 V0（粗糙初版）

你应该会看到： AI 快速生成一个带占位符的初版。可能：

部分文字是 [待补充]
图片区域是纯色块
动画可能还没做

你的操作： 刷新浏览器查看效果，判断方向是否正确：

✅ 方向正确：
"整体方向很好，配色和氛围都对了。继续完善细节吧。"

❌ 方向不对：
"整体太暗了，看不清内容。我希望暗但不是全黑，要有层次感。"

❌ 布局不对：
"卡片式布局太普通了，我想要更像杂志那种大图排版，有冲击力。"

为什么要先出 V0 而不是一步到位？ 想象你请人装修房子：

方式 A：先给你看一张效果图 → 你确认后再施工 ✅

方式 B：直接施工三个月 → 完工后你发现风格不对 → 全部拆掉重来 ❌

V0 就是那张"效果图"。粗糙但方向对了，后面就只是精雕细琢的事。

阶段 D：迭代打磨

你应该会看到： AI 根据你的反馈逐步完善代码。

你可以给的反馈方向：

第 1 轮："Hero 区域加一个 Canvas 绘制的星空动画，要有缓慢移动的星星"
第 2 轮："展品卡片的排版太规整了，试试不对称的杂志式排版"
第 3 轮："时间线部分加滚动动画，年份数字要大，有视觉冲击力"
第 4 轮："整体字体太大了，调小一点，留白再多一些"

每轮只提 1-2 个修改点，不要一次性说太多。 原因：

AI 一次改太多容易顾此失彼

每轮改完你都要看一眼效果，确认改对了再继续

这样你能清楚知道每一步发生了什么（对录视频也有好处）

阶段 E：最终验证

当你觉得差不多了，触发验证：

请你现在以一个全新设计评审专家的视角，全面检查这个网页：
1. 是否有任何"一看就是 AI 做的"的特征？逐一列出。
2. 配色是否和谐？有没有用 OKLCH？
3. 字体使用是否恰当？有没有用到烂大街的字体？
4. 布局是否有创意？还是标准的 Hero + 卡片网格？
5. 动画是否自然？有没有过度使用发光效果？
6. 移动端适配是否正常？
列出所有需要改进的地方，然后逐一修复。

为什么要"全新视角"？ 这是 Skill 里的子 Agent 验证理念：如果让同一个上下文的 AI 检查自己的作品，它天然倾向于"觉得自己没问题"。但当你要求它以"全新视角"重新审视时，它更容易发现问题。

保存 Skill 版本

AI 完成后，保存最终版：

# 如果你还在 Agent 对话中，让 AI 帮你复制：
# "请把当前的 index.html 复制一份，命名为 index-with-skill.html"

# 或者退出 Agent 后手动复制：
cp index.html index-with-skill.html

对比两个版本

文件结构

你的项目目录现在应该有这些文件：

space-museum-demo/
├── index.html                  ← Skill 版本（最终版）
├── index-no-skill.html         ← 裸跑版本
├── index-with-skill.html       ← Skill 版本的备份
├── CLAUDE.md 或 AGENTS.md      ← Skill 规则文件
└── web-design-skill/           ← Skill 源文件

代码差异对比

1
2

# 用 diff 查看两个版本的代码差异
diff index-no-skill.html index-with-skill.html

或者如果你用了 Git：

1
2

# 查看整个过程中所有文件的变化
git diff

视觉对比

同时在浏览器中打开两个文件：

1
2

http://localhost:3000/index-no-skill.html     ← 裸跑版本
http://localhost:3000/index.html               ← Skill 版本

在两个浏览器标签页之间切换，对比：

维度	裸跑版本	Skill 版本	差距
配色	？	？	？
字体	？	？	？
布局	？	？	？
AI 味	？	？	？
动画	？	？	？
总评	/100	/100	？

录制成视频（可选）

录制工具

平台	工具	操作
Windows	Xbox Game Bar	按 `Win + G` 打开，点击录制按钮
Windows	OBS Studio	免费下载，功能最全
macOS	QuickTime	`Cmd + Shift + 5` 打开截屏工具栏
macOS	OBS Studio	免费下载

建议录制的镜头

镜头 1：【成品展示】（30 秒）
  → 打开最终网页，缓慢滚动展示全貌
  → 让观众先看到"结果"

镜头 2：【对比展示】（1 分钟）
  → 分屏或标签页切换，展示裸跑 vs Skill 版本
  → 逐个对比配色、字体、布局、动画

镜头 3：【过程回放】（2-3 分钟）
  → 回放你在终端中和 AI 对话的过程
  → 重点展示：AI 提问 → 确认设计系统 → 生成 V0 → 迭代

镜头 4：【设计细节讲解】（1 分钟）
  → 放大展示几个关键设计细节
  → 比如 OKLCH 配色的和谐感、字体的选择、留白的运用

镜头 5：【总结】（30 秒）
  → 总结 Skill 带来的提升
  → 展示开源仓库地址

录制设置

分辨率：1920×1080
帧率：30fps
录浏览器时，把地址栏也录进去（增加真实感）
录终端时，把整个终端窗口都录进去

进阶练习

完成上面的流程后，你已经掌握了基本操作。以下是三个进阶练习：

练习 1：换一个主题

在同一个项目目录下，新建一个文件，用 Skill 做一个完全不同风格的网页：

1
2

# 新建一个练习用的 HTML 文件
# 在 Agent 中输入：

`1`	`请帮我做一个独立咖啡店的官网，所有代码写在一个 coffee.html 文件里。`

`1`	`请帮我做一个日本旅行攻略的展示页，所有代码写在一个 japan.html 文件里。`

练习 2：极简提示词挑战

只给 AI 一个词，看它如何在 Skill 引导下自主决策：

钢琴

观察： AI 是先问你几个问题？还是直接开始创作？它做了什么假设？

练习 3：修改 Skill 文件

# 用编辑器打开 Skill 文件
# Claude Code 中：
claude
# 输入："请打开 web-design-skill/skill.md，我要修改它"

# OpenCode 中：
opencode
# 输入同样的内容

尝试修改以下内容，然后重新测试效果：

在字体推荐中增加一个你喜欢的字体
增加一条"去除 AI 味"的新规则（比如"不要使用全屏背景视频"）
修改配色策略的优先级

附录 A：常用提示词速查

让 AI 先说设计系统

在写任何代码之前，请先用自然语言描述你的设计系统，包括：
1. 配色方案（使用 OKLCH）
2. 字体选择（标题和正文分别用什么）
3. 间距系统
4. 布局策略
5. 绝对不能做的事情
我确认后再开始写代码。

要求快速 V0

先给我一个最小可用版本（V0）。
可以有占位符和未完成的部分。
我确认方向后再完善细节。
不要花太多时间在细节上。

触发全面验证

请以一个全新的设计评审专家视角，全面检查当前网页。
列出所有"一看就是 AI 做的"的特征，
以及配色、字体、布局上的所有问题。
然后逐一修复。

去除特定 AI 味

请检查并修改以下 AI 味特征：
1. 删除所有紫粉蓝渐变背景
2. 将 Emoji 图标替换为 SVG 或纯文字
3. 将大圆角卡片改为更有设计感的布局
4. 删除所有无意义的装饰性发光效果
5. 减少假数据，使用更有真实感的内容

附录 B：常见问题排查

Q：AI 生成的代码写入了错误的文件？

告诉 AI：

1
2

请把所有代码写入 ~/Desktop/space-museum-demo/index.html
用绝对路径，不要写到其他地方。

Q：浏览器刷新后没变化？

确认文件确实被修改了：cat index.html | head -5（查看文件头几行）
强制刷新：Ctrl + Shift + R（Windows）/ Cmd + Shift + R（macOS）
确认预览服务器还开着

Q：Skill 安装后 AI 还是生成紫粉蓝渐变？

在对话中强调：

1
2
3

严格遵守 CLAUDE.md（或 AGENTS.md）中的"去除 AI 味"规则。
特别注意：不要使用渐变背景、Emoji 图标、大圆角卡片。
使用 OKLCH 色彩空间定义所有颜色。

Q：AI 生成的网页没有动画效果？

明确要求：

请添加原生 JavaScript 实现的滚动动画：
使用 IntersectionObserver API，
元素进入视口时添加渐入效果。
不要用任何第三方库。

Q：想在网页中使用中文但 AI 默认用了英文？

在需求中明确：

1
2
3

所有文案内容使用中文。
HTML lang 属性设为 zh-CN。
字体要支持中文显示（在字体栈中加入中文字体作为 fallback）。

Q：Claude Code 和 OpenCode 的行为有差异？

两个工具的核心区别：

	Claude Code	OpenCode
配置文件	`CLAUDE.md`	`AGENTS.md`（或兼容 CLAUDE.md）
模型	只用 Claude	支持多模型（确保选 Claude）
界面	纯文本终端	TUI 图形终端
文件引用	`@文件名`	具体语法看版本文档

如果 OpenCode 生成效果和 Claude Code 差异很大，检查是否用的是同一个模型。

附录 C：完整项目结构参考

完成所有步骤后，你的项目目录应该长这样：

space-museum-demo/
│
├── CLAUDE.md                       ← Skill 规则（Claude Code 用）
├── AGENTS.md                       ← Skill 规则（OpenCode 用）
├── index.html                      ← 最终成品（Skill 版本）
├── index-no-skill.html             ← 裸跑版本（用于对比）
├── index-with-skill.html           ← Skill 版本备份
│
├── coffee.html                     ← 进阶练习：咖啡店网页（可选）
├── japan.html                      ← 进阶练习：日本旅行网页（可选）
│
└── web-design-skill/               ← Skill 源文件
    ├── skill.md                    ← 核心提示词
    ├── reference.md                ← 参考代码模板
    ├── README.md                   ← 仓库说明
    └── demo/                       ← 示例网页

最后总结

1
2

做网页的核心流程：
理解需求 → 确认设计系统 → 快速 V0 → 迭代打磨 → 验证

三句话记住 Skill 的精髓：

先说设计系统，再写代码 — 方向不对，代码白写
先出粗糙 V0，再精雕细琢 — 快速试错，成本最低
大胆留白，每个元素要证明自己 — 克制即高级

web-design-skill 学习笔记

Tue, 26 May 2026 00:00:00 +0800

web-design-skill 学习笔记

Claude Design 是什么？

Claude Design 是 Anthropic 发布的设计工具，发布当天直接导致了 Figma 股价暴跌。

核心理念： 左边打字，右边直接出设计稿（本质上是可运行的网页，不是图片）

与传统设计工具的区别

维度	传统设计工具（如 Figma）	Claude Design
主导者	人在画布上操作，AI 辅助提速	AI 是主要生成者，人负责审核
输出物	设计图/图片	真实可运行的代码
交互方式	手动绘制	文字描述 → 自动生成
版本管理	需手动操作	链接可点击，标签可切版本

本质： Claude Design 更像 Claude Code（设计师版），而不是 AI 版 Figma。

核心提示词拆解（6 大要点）

视频对 Claude Design 泄露的提示词进行了深度拆解，提炼出 6 个核心设计原则：

角色定位 —— 动态身份切换

提示词原文要旨： “你是一个专家设计师，而用户是你的产品经理”

关键洞察：

❌ 不要说"你是一个 AI 助手"
✅ 建立设计师 ↔ 产品经理的协作关系

两个好处：

AI 决策更果断 — 设计师本身应该有判断力，不用事事请示
关键点会来问你 — 因为用户是产品经理，最终由用户拍板

动态身份切换：

做动画 → 动效设计师
做原型 → UX 设计师
做 PPT → Deck 设计师

💡 启示： 很多人的提示词只写一句"你是个前端开发者"就完事了。好的角色定位应该是动态的，根据具体任务灵活切换身份。

工作流 —— 六步流程

`1`	`理解需求 → 探索资源 → 制定计划 → 搭建结构 → 完成验证 → 简要总结`

细节一：提问的艺术（什么时候该问？什么时候直接干？）

问题： 很多 Agent 要么先问你一堆问题，要么啥也不问闷头就干。

Claude Design 的策略：

输入 “帮我做个 PPT” → 先问几个问题（信息不足）
输入 “帮我做个 PPT，全运会马上要用，10 分钟” → 直接开干（紧急场景，信息充分）

💡 启示： 根据上下文的紧迫程度和信息完整度，灵活决定是提问还是执行。

细节二：总结原则

✅ 只说关键注意事项和下一步动作
❌ 不要复述自己已经做了什么

💡 启示： 这个原则可以有效避免 AI 产生大量废话。

去除 AI 味（最有价值的部分）

典型的 AI 生成网页特征：

紫粉蓝渐变背景
大圆角卡片
Emoji 当图标
到处堆砌假数据
左侧彩色边框的圆角卡片
烂大街的字体
无意义的数据和图标堆砌

这就像文章里通篇都是"此外"“值得注意的是"“综上所述"一样，一眼就能闻出来是 AI 写的。

Claude Design 的做法： 列出一份完整的"雷区清单”，逐条告诉 AI 不能走这些老套路。

字体推荐也很讲究：

明确列出千万不能用的字体 + 替代方案
推荐小众但品质很高的字体

色彩系统 —— OKLCH 色彩空间

配色策略优先级：

`1`	`品牌色 → OKLCH 派生颜色 → 绝不凭空编新颜色`

为什么用 OKLCH 而不是 HSL？

	HSL	OKLCH
感知均匀性	❌ 不均匀（同亮度值，黄色比蓝色亮很多）	✅ 均匀
AI 配色效果	数值没问题但看着不舒服	保持亮度和色度不变，只转色相，颜色自然和谐

💡 启示： OKLCH 这个看似很小的细节，能让网页的高级感直接提升一个档次。

内容原则 —— “用 1000 个 NO 换一个 YES”

引用乔布斯经典名言。

AI 做网页的传统毛病： 恨不得把空间全塞满 — Hero、特性、评价、数据、FAQ、联系方式……一股脑全上，但每块都平庸。

Claude Design 的态度：

每个元素都得证明自己为什么应该在那里
如果觉得页面空 → 可能是排版问题，用留白来解决
一个大胆的留白 > 十个凑数的板块

验证机制 —— 子 Agent 检查

原理： 开发完成后，fork 出一个独立的子 Agent 对网页做全面检查。

为什么要独立的子 Agent？

同一个上下文里的 AI 容易"自我感觉良好”
独立的子 Agent 没有"感情包袱"，更容易发现问题

验证内容：

是否有 AI 味特征？
配色是否和谐？
字体是否恰当？
布局是否有创意？

Skill 文件的核心优化

Skill 文件在 Claude Design 提示词的基础上，做了三个关键优化：

先说设计系统再写代码

在开始编码之前，要求 AI 明确列出：

配色方案
字体选择
间距系统
……

为什么？ 如果不说清楚，AI 会默默自己做决定直接写代码。等你看到成品时，如果方向不对只能推翻重来。提前说出来，还没写代码就能纠偏。

尽早输出最小可用版本

要求 AI 先拿出一个带假设和占位符的粗糙 V0 版本
一个粗糙的 V0 > 花几倍时间做出精雕细琢的 V1

为什么？ 如果整个方向都错了，V1 做得再精致也全白干了。

额外补充

补充了更多去除 AI 味的条目
增加了几套经过验证的字体和配色参考对照表
附带 reference 文件（典型代码模板，来源于提示词中的 “copy study the component” 部分）

效果对比演示

测试环境：Cursor + Claude 4.7（有 Skill vs 无 Skill）

太空探索博物馆线上展览页

	无 Skill	有 Skill
配色	青紫粉渐变，典型 AI 霓虹感	OKLCH 定义，接近杂志印刷的深沉色调
字体	比较老套	标题和正文都有特点，技术感十足
布局	标准 Hero + 卡片，教科书式落地页	非传统卡片式，有创意感
动画	有星空和行星动画，但堆砌了大量发光特效	舒适、有创意感
总体	有太空感，缺少创意	像非常有经验的设计师的杰作

独立摄影师个人作品集（极简提示词）

	无 Skill	有 Skill
设计风格	深色背景 + 霓虹发光 + 半透明卡片，老套	虚构了一位北欧摄影师，从头设计完整视觉风格
文案	满满的 AI 感	—
情感表达	摄影师本该有的自由感完全没体现	像在翻一本高端摄影画册
决策策略	直接开干，没问问题	主动提问了配色倾向、核心元素等

最终结论

1
2

无 Skill: 85 分 → 能用、完整、合格
有 Skill: 95 分 → 好看、精致、有风格

Skill 里的每条规则单独看效果不大，但加起来就会产生质变。这就是从"能用"到"好看"、从"完整"到"精致"、从"合格"到"有风格"的差距。

核心知识点速查

#	知识点	一句话总结
1	动态角色定位	根据任务灵活切换 AI 身份，而不是一句"你是前端"了事
2	工作流六步法	理解需求→探索资源→制定计划→搭建结构→完成验证→简要总结
3	提问的艺术	根据信息完整度和紧迫度决定是提问还是直接干
4	去除 AI 味	列出雷区清单，禁用渐变/Emoji/大圆角卡片等老套路
5	OKLCH 配色	感知均匀的色彩空间，比 HSL 更能产生和谐配色
6	内容克制	每个元素都要证明自己存在的理由，大胆留白
7	子 Agent 验证	用独立上下文检查，避免"自我感觉良好"
8	先说设计系统再写代码	提前暴露设计决策，避免方向性错误
9	快速出 V0	粗糙但快速的原型 > 精致但方向错误的成品

OpenCode + Obsidian：打造你的AI驱动知识管理工作流

Thu, 30 Apr 2026 02:00:15 +0800

📋 目录

一、什么是 opencode-obsidian 插件？

opencode-obsidian 是一个第三方社区插件，它将 OpenCode AI 助手直接嵌入到 Obsidian 窗口中。不同于传统的终端集成方案，这个插件使用 OpenCode 的 Web 视图直接嵌入，你看到的就是完整的 OpenCode 界面，不需要在终端和 Obsidian 之间来回切换。

核心特性：

🖥️ OpenCode 界面直接嵌入 Obsidian 侧边栏或主编辑区
🔄 服务端自动管理——打开面板即启动，关闭即停止
📄 实验性的上下文注入——自动将当前打开的笔记和选中文本传给 AI
⌨️ 快捷键 Ctrl/Cmd + Shift + O 快速切换面板

适用场景：

总结和提炼长文本内容
起草、编辑和润色写作
查询和探索你的知识库
生成大纲和结构化笔记

⚠️ 插件作者与 OpenCode / Obsidian 无关联，这是一个独立的第三方项目。目前版本为 0.2.1（Beta 阶段），仅支持桌面端。

二、环境准备

在开始之前，确保你已准备好以下内容：

项目	要求	说明
Obsidian	≥ 1.4.0	官网下载
Node.js	≥ 18+	下载地址，用于安装 OpenCode

准备就绪后，跟着下面的步骤走就行。

三、安装 BRAT 插件

BRAT（Beta Reviewer’s Auto-update Tool）是 Obsidian 的一个社区插件，专门用来安装尚未上架社区插件市场的 Beta 版插件。opencode-obsidian 目前还没有正式上架，所以需要通过 BRAT 安装。

步骤 1：打开社区插件市场

在 Obsidian 中依次点击：设置 → 第三方插件 → 关闭「安全模式」→ 社区插件市场

步骤 2：搜索并安装 BRAT

在社区插件市场中搜索 BRAT（全名：Obsidian42 - BRAT），点击「安装」→「启用」。

💡 BRAT 的全称是 Beta Reviewer’s Auto-update Tool，由 TfTHacker 开发。它能自动检测 Beta 插件的更新并提醒你升级。

四、通过 BRAT 安装 opencode-obsidian

安装好 BRAT 后，就可以用它来安装 opencode-obsidian 插件了。

步骤 1：打开 BRAT 设置

设置 → 第三方插件 → 找到已安装的 BRAT，点击右侧的齿轮图标进入设置。

步骤 2：添加 Beta 插件

在 BRAT 设置页面中，点击 「Add Beta plugin」 按钮。

步骤 3：输入仓库地址

在弹出的输入框中输入：

`1`	`mtymek/opencode-obsidian`

点击 「Add Plugin」。

BRAT 会自动从 GitHub 拉取最新的 release 版本并安装。

步骤 4：启用插件

安装完成后，前往设置 → 第三方插件 → 在「已安装插件」列表中找到 OpenCode-Obsidian，打开开关启用它。

✅ 启用后，Obsidian 左侧栏会出现一个终端样式的图标——这就是 OpenCode 的入口。

自动更新

BRAT 会定期检查 GitHub 上的新版本。当有更新时，它会在 Obsidian 中弹出通知，你只需点击确认即可自动升级。

五、安装 OpenCode CLI

插件本身只是一个"壳"——它会在后台启动 opencode serve 服务，然后把 OpenCode 的 Web 界面嵌入到 Obsidian 里。所以你只需要通过 npm 安装 OpenCode CLI 就够了。

打开系统的终端（Windows 用 PowerShell，macOS/Linux 用 Terminal）：

`1`	`npm i -g opencode-ai`

验证安装：

1
2

opencode --version
# 期望输出类似: 1.14.39

⚠️ Windows 用户：如果插件提示「Executable not found at ‘opencode’」，请跳到本文第十节查看解决方案。

六、插件设置详解

启用插件后，进入设置 → 第三方插件 → OpenCode-Obsidian 的齿轮图标，可以看到以下配置项：

基础设置

设置项	默认值	说明
OpenCode 可执行文件路径	`opencode`	如果系统 PATH 中找不到，填入完整路径
端口	`14096`	OpenCode 服务监听的端口号
主机名	`127.0.0.1`	服务绑定的地址
项目目录	（自动取 Vault 路径）	OpenCode 操作的工作目录
启动超时	`45000` (45秒)	等待服务启动的最大毫秒数

界面设置

设置项	默认值	说明
默认视图位置	`sidebar`	`sidebar` = 侧边栏，`main` = 主编辑区
自动启动	`关闭`	打开 Obsidian 时自动启动 OpenCode 服务

上下文注入（实验性）

设置项	默认值	说明
注入工作区上下文	`关闭`	自动将当前笔记信息传给 OpenCode
最大笔记数量	`20`	上下文中包含的最大笔记数
最大选中文本长度	`2000`	传给 AI 的选中文本字符上限

自定义命令

设置项	默认值	说明
使用自定义命令	`关闭`	启用后可自定义 OpenCode 启动命令
自定义命令	（空）	自定义的启动命令（见第九节）

七、首次使用

打开 OpenCode 面板

有三种方式打开 OpenCode：

点击侧边栏图标：点击左侧栏的终端图标
快捷键：Ctrl + Shift + O（macOS 用 Cmd + Shift + O）
命令面板：Ctrl/Cmd + P → 输入 Toggle OpenCode panel

首次启动流程

打开面板后，插件会自动执行以下操作：

检测 OpenCode 可执行文件路径
启动 OpenCode 服务（opencode serve）
在嵌入式 Web 视图中加载 OpenCode 界面

启动成功后，你会看到完整的 OpenCode 对话界面，可以直接在里面输入 prompt。

验证一切正常

在 OpenCode 界面中输入：

/help

如果看到命令列表，说明一切正常。你也可以输入：

/models

查看可用的 AI 模型。OpenCode 内置了免费模型（如 GLM-4.7、MiniMax-2.1），无需任何配置即可使用。

快捷键速查

快捷键	功能
`Ctrl/Cmd + Shift + O`	切换 OpenCode 面板

八、上下文注入（实验性功能）

这是 opencode-obsidian 插件最独特的功能之一——它可以自动将 Obsidian 的工作上下文传递给 OpenCode。

开启方式

在插件设置中，打开 「注入工作区上下文」 开关。

注入的内容

启用后，插件会自动将以下信息传给正在运行的 OpenCode 实例：

📂 当前打开的笔记列表：你正在编辑哪些文件
📝 选中的文本：你在笔记中选中的文字

使用场景

选中一段文字，打开 OpenCode 面板，直接说「润色这段话」——AI 已经知道你说的是哪段文字
同时打开多篇笔记，让 AI「对比这两篇笔记的差异」——AI 已经知道你打开的是哪些文件

局限性

⚠️ 这是实验性功能，目前有一些限制：

在 OpenCode 界面中创建新 Session 时，上下文不会自动注入

上下文更新有一定的延迟

九、自定义命令模式

默认情况下，插件会自动调用 opencode serve 命令启动服务。如果你需要更多控制，可以启用自定义命令模式。

什么时候需要自定义命令？

需要添加额外的 CLI 参数
使用自定义的启动脚本
通过容器或虚拟环境运行 OpenCode
OpenCode 安装在非标准路径

配置步骤

在插件设置中打开 「使用自定义命令」
在 「自定义命令」 输入框中填写完整命令

命令模板

`1`	`opencode serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md`

⚠️ 重要注意事项

端口和主机名必须与设置中的值一致
必须包含 --cors app://obsidian.md，否则 Obsidian 无法嵌入 OpenCode 的 Web 界面

十、常见问题与故障排除

❌ 找不到 OpenCode 可执行文件

现象：打开面板后提示「Executable not found at ‘opencode’」，但终端中执行 opencode 是正常的。

原因：Electron（Obsidian 底层框架）在 Windows 上不完全继承系统 PATH 环境变量。

解决方案：

在终端中查找 opencode.cmd 的完整路径：

`1`	`where opencode.cmd`

将输出的完整路径填入插件设置的「OpenCode 可执行文件路径」中，例如：

`1`	`C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd`

❌ 服务启动超时

可能原因：网络问题、模型加载慢、端口被占用。

解决方案：

检查端口 14096 是否被其他程序占用
尝试修改端口号（比如改成 15096）
增加启动超时时间

❌ 面板显示空白

可能原因：CORS 配置不正确。

解决方案：

如果使用了自定义命令，确保命令中包含 --cors app://obsidian.md。

❌ 面板无法嵌入

可能原因：OpenCode 版本过旧。

解决方案：

`1`	`npm i -g opencode-ai@latest`

❌ 中文文件名乱码（Windows）

解决方案：在 PowerShell 中执行：

`1`	`chcp 65001`

然后重启 Obsidian。

❌ 插件更新后需要重新配置

BRAT 更新插件时会保留你的设置数据。如果发现设置丢失，重新进入设置页面配置即可。

总结

整个安装流程可以用一张图概括：

┌──────────────────────────────────────────┐
│           安装 BRAT 插件                  │
│   设置 → 社区插件市场 → 搜索 BRAT → 安装   │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│      通过 BRAT 安装 opencode-obsidian      │
│   BRAT 设置 → Add Beta plugin             │
│   输入: mtymek/opencode-obsidian           │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│           安装 OpenCode CLI               │
│   npm i -g opencode-ai                   │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│         启用插件，开始使用                  │
│   Ctrl+Shift+O 打开面板                   │
│   直接在 Obsidian 里使用 OpenCode         │
└──────────────────────────────────────────┘

一句话总结：装 BRAT → 搜 mtymek/opencode-obsidian → 装好 OpenCode CLI → Ctrl+Shift+O 开始用。就这么简单。

📚 参考来源：

opencode-obsidian GitHub 仓库

BRAT 插件 GitHub 仓库

OpenCode 官方文档

OpenCode 全深度指南：开源版 Claude Code 的安装、配置与高级玩法

Thu, 30 Apr 2026 02:00:15 +0800

📋 目录

一、什么是 OpenCode？

OpenCode 是近期热度最高的 AI 编程工具，本质上是一个开源版的 Claude Code。它几乎复刻了 Claude Code 的所有核心功能，同时解决了 Claude Code 在中国用户中常见的限速、封号等痛点。

与 Claude Code 对比

对比维度	Claude Code	OpenCode
开源	❌ 闭源	✅ 开源
免费模型	❌ 需付费 API	✅ 内置免费模型
中国用户友好	⚠️ 限速/封号风险	✅ 无限制
Skills/MCP	✅ 支持	✅ 完全兼容
Session 并行	❌	✅ 核心亮点

核心定位

开源版 Claude Code：具备几乎全部功能，中国用户友好，不限速不封号
免费模型：开箱即用 GLM-4.7、MiniMax-2.1 等免费模型，零配置即可上手
顶级模型接入：通过 Antigravity 插件免费接入 Gemini 3 Pro、Claude 4.5 Opus；通过 /connect 接入 GPT Codex
杀手级功能：Session 并行、Timeline 回退、Share 分享、Ultra Work 多智能体协作
插件生态：Oh My Open Code (OMO) 集成七大编程智能体 + 三大 MCP Server + 多种工具

二、四种安装形态

⭐ 1. 命令行版（主力推荐）

最稳定、功能最全的使用方式。

# 安装（需先安装 Node.js）
npm i -g opencode-ai

# 启动
opencode

前置条件：需要安装 Node.js（前往 nodejs.org 下载对应系统版本）

2. 桌面客户端（Beta）

从官网下载客户端，一路下一步安装，选择项目文件夹即可使用。

⚠️ 目前处于 Beta 测试阶段，bug 较多，暂不推荐作为主力工具。

3. VS Code 插件版

前提：已安装命令行版 OpenCode。插件版的核心价值在于与 IDE 的无缝集成，让 AI 直接感知你的代码上下文。

在 VS Code 扩展商店搜索 OpenCode 并安装
快捷键 Ctrl + Shift + P → 输入 open opencode 回车
插件会自动关联左侧窗口打开的代码文件
选中代码后按 Ctrl + Alt + K 可快速粘贴到 OpenCode 聊天窗口

4. 云端运行环境（GitHub Actions）

非常适合开源项目的自动化 Issue 修复：

将项目上传到 GitHub 公开仓库
在仓库中配置 API Key（Settings → Secrets and Variables → Actions）
在 Issue 评论中输入 /opencode + 需求描述
GitHub Actions 自动运行 OpenCode 工作流
完成后自动创建 Pull Request

三、免费模型配置

查看可用模型

`1`	`/models # 查看所有可用模型（带 free 标记的即可免费使用）`

接入顶级模型

方式一：Antigravity 插件（免费接入 Gemini + Claude）

Antigravity 是 Google 推出的 AI 编程 IDE，它慷慨地免费提供了 Gemini 3 Pro 和 Claude 4.5 Opus。

在 OpenCode 中粘贴安装提示词（从 Antigravity GitHub 首页复制）
等待 AI 自动完成安装
打开新终端执行登录命令，选择 Google → Antigravity 登录
登录 Google 账户，粘贴生成的 URL
重启 OpenCode，/models 即可看到 Gemini 3 Pro 和 Claude 4.5 Opus

方式二：GPT Codex（OpenAI 官方合作）

OpenAI 与 OpenCode 官宣合作，可直接接入 ChatGPT Codex。

`1`	`/connect # 选择 OpenAI → GPT Pro → 浏览器登录`

前提：需要有 ChatGPT Plus 或以上订阅。

方式三：OpenRouter（万能接入）

通过 OpenRouter 可以接入市面上几乎所有大模型，国内用户也能方便获取额度。

`1`	`/connect # 选择 OpenRouter → 填写 API Key`

OpenCode 支持 75 种 AI 接入方式，几乎囊括所有模型供应商。

四、核心功能亮点

1. 反问式需求澄清

在动手编码之前，OpenCode 会反向询问你一系列问题：

只需要代码样例，还是完整可运行的程序？
哪些功能是必须实现的？
调用哪个模型？
环境变量如何保存？

这种"先问清楚再动手"的机制，大幅减少了返工。

2. 命令行代码比对界面

OpenCode 的命令行 diff 展示被认为是所有命令行编程工具中做得最好的，代码变更一目了然。

⭐ 3. Session 并行处理

这是 OpenCode 最具特色的功能——多 Session 并行运行：

# 发起第一个任务（如：增加计时器）
# 任务执行中，创建新 session
/new

# 发起第二个任务（如：画笔调色）
# 查看所有 session 状态
/sessions

# 在 session 间切换
/session <id>

打转符号表示 Session 正在后台运行。两个需求可以完全并行开发，互不干扰。

4. Timeline 检查点回退

`1`	`/timeline # 查看当前 Session 的完整对话记录`

选择任意历史节点：

Revert：将代码和聊天内容同时回退到该时间点
View：查看当时 AI 做了什么修改

相当于编程过程中的"时光机"，可以大胆尝试不同方案。

1
2
3

/share      # 将对话记录分享为网页
/unshare    # 取消分享
/export     # 导出对话记录为文件

分享后生成一个网页链接，展示完整的对话记录和代码修改过程，方便与他人协作或展示。

五、Skills 技能迁移

OpenCode 完全兼容 Claude Code 的 Skills 目录结构，迁移成本极低：

1
2

# 目录结构对应关系
.claude/skills/<skill-name>/    →    .opencode/skills/<skill-name>/

操作步骤

在项目根目录新建 .opencode 文件夹
在 .opencode 下新建 skills 文件夹
将原 .claude/skills/ 下的技能文件夹直接复制过来
重启 OpenCode，AI 即可识别并调用这些 Skills

每个 Skill 就是一个带目录的说明书，告诉 AI 如何完成特定领域的任务。

六、MCP 配置

OpenCode 支持两种 MCP（Model Context Protocol）模式：

本地 MCP（Local）

通过本地命令执行。在 ~/.config/opencode/opencode.json 中配置：

{
  "mcpServers": {
    "shed-cn": {
      "type": "local",
      "command": "npx",
      "args": ["shed-cn"],
      "enabled": true
    }
  }
}

远程 MCP（Remote）

通过 URL 远程调用。以 Context7 为例：

{
  "mcpServers": {
    "context7": {
      "type": "remote",
      "url": "https://context7-mcp-server-url",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      },
      "enabled": true
    }
  }
}

配置完成后重启 OpenCode，输入 /mcp 即可查看已配置的 MCP Server。

七、Oh My Open Code (OMO) 超强插件 ⭐

OMO 是 OpenCode 上最火的编程插件，本质上是 工具 + MCP + 编程 Agent 的组合捆绑包。

七大编程智能体

智能体	角色	推荐模型
🧠 西西弗斯 (Sisyphus)	主智能体，规划与调度	Claude 4.5 Opus / GPT 5.2
🔮 先知 (Prophet)	架构设计、代码评审	—
📚 图书管理员 (Librarian)	查阅文献、文档检索	—
🔍 探索者 (Explorer)	网络搜索	—
🎨 前端工程师	前端开发	Gemini 3 Pro
📝 文档编写者	文档生成	—
🖼️ 多模态	图片/PDF 理解	—

每个智能体都分配了最适合其工作的大模型，据作者称耗费了 24,000 美元的 Token 才找到最佳组合。

三大 MCP Server

Web Search：网络搜索
Context7：获取最新技术文档
Grep App：GitHub 仓库快速代码搜索

集成工具

LSP 高级版：通过编程语言的语法和语义帮助 AI 快速定位代码
AST 工具：通过代码语法树进行关联搜索
LOC 工具：借助多模态视觉能力理解图片、PDF
Delegate Task / Background Task：Agent 任务分配和后台调度

安装与使用

配置文件位置：C:\Users\<用户名>\.config\opencode\oh-my-opencode.json

从 OMO GitHub 首页复制 install 开头的提示词
粘贴到 OpenCode 中，回答配置问题（订阅情况等）
自动完成安装

两种核心用法

① @ 指定智能体

`1`	`@前端工程师帮我优化这个页面的响应式布局`

② Ultra Work 模式（魔法词 ULW）

`1`	`ULW 帮我创建一个宠物商店应用`

Ultra Work 模式下，西西弗斯作为主智能体会：

将任务拆解成 Todo List
同时开启多个后台任务并行执行
居中调度各个智能体协同工作
最终交付完整项目

Ralph Loop 循环模式

强制 AI 长时间循环工作，适合极难任务：

`1`	`/ralph-loop`

示例：“使用 Spring Boot 4 最新标准重构整个项目，直到所有测试用例通过”——可以连续运行数小时直到任务完成。

八、其他实用功能

`/init` — 项目知识初始化

让 AI 通读整个项目文件夹，生成 agents.md 文件作为系统提示词，帮助 AI 快速了解项目。

`/compact` — 上下文压缩

将之前的对话提炼为简洁摘要，释放模型上下文窗口，避免 Token 超限。

自定义命令

在 ~/.config/opencode/commands/ 下创建 .md 文件定义自定义命令：

# 运行测试
模式：build
命令：npm test
描述：运行项目的全部测试用例

使用：/运行测试 即可触发。

自定义智能体

在 ~/.config/opencode/agents/ 下创建 .md 文件：

# Code Review Agent
类型：subagent
模型：claude-4.5-opus
描述：专门负责代码审查，检查代码质量、安全漏洞和最佳实践。

Primary Agent：按 Tab 键切换，在对话中直接使用
Sub Agent：由主智能体在后台自动调度

九、总结与推荐

适用场景

场景	推荐度	说明
新手入门 AI 编程	⭐⭐⭐⭐⭐	免费模型零成本上手
日常开发辅助	⭐⭐⭐⭐⭐	Session 并行 + Timeline 回退
复杂项目开发	⭐⭐⭐⭐⭐	OMO 插件多智能体协作
开源项目维护	⭐⭐⭐⭐	GitHub Actions 云端自动化
练习 Skills/MCP	⭐⭐⭐⭐⭐	完全兼容 Claude Code 生态

十、实战记录：安装 Oh My OpenAgent

以下是笔者亲测安装 Oh My OpenAgent（原 Oh My Open Code）的完整对话记录，环境为 Windows + PowerShell。

环境检查

1
2

opencode --version
# 输出: 1.14.39

安装过程

在 OpenCode 对话中直接告诉 AI：

“Install and configure oh-my-openagent by following the instructions here: https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md"

AI 会先询问你拥有的模型订阅情况：

订阅	我的情况
Claude Pro/Max	❌ 无
OpenAI / ChatGPT Plus	❌ 无
Gemini	❌ 无
GitHub Copilot	✅ 学生认证版
OpenCode Zen	✅ 免费可用
Z.ai Coding Plan	❌ 无
OpenCode Go	❌ 无
Kimi for Coding	❌ 无
Vercel AI Gateway	❌ 无

⚠️ AI 会提示 “Without a Claude subscription, the Sisyphus agent might not work ideally”，但 GitHub Copilot 会作为后备模型自动接管。

确认订阅后，AI 自动执行安装命令：

bunx oh-my-openagent install --no-tui \
  --claude=no --openai=no --gemini=no \
  --copilot=yes --opencode-zen=yes \
  --zai-coding-plan=no --opencode-go=no \
  --kimi-for-coding=no --vercel-ai-gateway=no

安装成功的输出：

[1/4] Checking OpenCode installation...
[OK] OpenCode 1.14.39 detected
[2/4] Adding oh-my-openagent plugin...
[OK] Plugin added -> C:\Users\<用户名>\.config\opencode\opencode.json

安装后的配置文件

主配置文件 ~/.config/opencode/opencode.json：

{
  "plugin": [
    "oh-my-openagent@latest"
  ]
}

Agent 模型配置 ~/.config/opencode/oh-my-openagent.json：

AI 自动根据 GitHub Copilot 订阅分配了模型：

Agent	分配的模型
Sisyphus（主智能体）	`github-copilot/claude-opus-4.7`
Oracle（先知）	`github-copilot/gpt-5.5` (medium)
其余 Agent	自动选择 Copilot 可用模型

认证配置

安装完成后需要手动认证 GitHub Copilot：

`1`	`opencode auth login`

交互步骤：

上下键选择 GitHub Copilot
按回车确认
浏览器自动打开，登录 GitHub 学生账号
授权完成，终端显示认证成功

如何重新配置 Agent 模型？

方式一：直接告诉 AI

“把 Sisyphus 的模型改成 claude-sonnet-4.6” “Oracle 用 gpt-5.5”

方式二：手动编辑配置文件

直接修改 ~/.config/opencode/oh-my-openagent.json 中对应 agent 的 model 字段。

追加配置：补上 OpenCode Zen 作为备选

安装时遗漏了免费的 OpenCode Zen（--opencode-zen=no），后续在 OpenCode 新对话中直接让 AI 帮忙修正：

“其实我还有你免费的 OpenCode Zen，但是我已经登录 GitHub Copilot 了，你帮我修改一下”

AI 的第一次尝试把 OpenCode Zen 设成了主力（opencode/claude-opus-4-7），GitHub Copilot 变成了备选。实际需求是反过来的：

“不是，是 GitHub Copilot 作为主力，OpenCode Zen 自带的免费模型作为备选”

AI 修正后，最终配置策略：

1
2

主力模型: github-copilot/*     （已付费，优先使用）
备选模型: opencode/*           （免费额度，Copilot 不可用时自动切换）

关键配置片段（以 Sisyphus 为例）：

{
  "sisyphus": {
    "model": "github-copilot/claude-opus-4-7",
    "fallback_models": [
      { "model": "opencode/claude-opus-4-7" },
      { "model": "opencode/gpt-5.5" }
    ]
  }
}

💡 经验：描述配置需求时，主次关系要说清楚——“XX 作为主力，YY 作为备选”，避免 AI 搞反。

使用提示

安装完成后，在终端输入 opencode 即可开始：

在 prompt 中包含 ultrawork 或 ulw 触发自动并行处理
按 Tab 进入 Prometheus（规划器）模式
运行 /start-work 执行完整编排

附录：踩坑记录

问题	解决
`doctor` 命令超时（30s）	部分检查可能挂起，加 `--verbose` 排查，或跳过不影响使用
PowerShell 下 `if` 语法报错	OpenCode 的 bash 命令在 PowerShell 下需转换语法
Sisyphus 非 Claude 模型性能下降	这是已知限制，有 Claude 订阅体验最佳
AI 把主力/备选模型搞反	描述需求时说清主次：“XX 作为主力，YY 作为备选”，不要只说"帮我加上 YY”

📚 参考来源：技术爬爬虾 - OpenCode 详细攻略、Oh My OpenAgent 安装指南

OpenCode 新手进阶：并行调度与使用技巧全攻略

Thu, 30 Apr 2026 02:00:15 +0800

📋 目录

📌 核心要点概括

功能	一句话说明
Session 并行	OpenCode 杀手级功能，多个任务同时跑，互不干扰，效率翻倍
Ultra Work 模式	输入 `ULW`，主智能体自动拆解任务、调度多个子智能体并行干活
@ 指定智能体	让擅长前端的干前端，擅长架构的做评审，人尽其才
Timeline 时光机	随时回退到任意历史节点，大胆试错零成本
Ralph Loop	让 AI 循环工作数小时，攻坚极难任务

一、Session 并行：让 AI 同时干多件事

这是 OpenCode 相比其他 AI 编程工具最大的差异化优势。传统工具只能串行——一个任务跑完才能开始下一个。OpenCode 可以同时开启多个 Session，互不干扰。

基础操作

/new              # 创建新 Session
/sessions         # 查看所有 Session 的状态（打转符号 = 正在运行）
/session <id>     # 切换到指定 Session
/session prev     # 回到上一个 Session

实战场景

假设你在开发一个"你画我猜"小游戏，有两个独立需求：

需求 A：增加一个计时器，首次落笔开始计时，超过 20 秒游戏失败
需求 B：画笔可以调节颜色

传统做法

先做完 A，再做 B → 需求 B 白白等待 5-10 分钟。

OpenCode 做法

1. 输入需求 A，AI 开始工作
2. 输入 /new，创建新 Session
3. 输入需求 B，AI 开始工作
4. 输入 /sessions 查看进度：

   Session 1  ◐  正在添加计时器逻辑...
   Session 2  ◐  正在添加颜色选择器...

两个需求完全并行开发，总耗时从 15 分钟压缩到 8 分钟。

注意事项

⚠️ Session 之间完全隔离，修改同一文件可能冲突，建议分配给不同模块
⚠️ 后台 Session 不会自动通知完成，需要手动 /sessions 查看
✅ 可以随时 /new 开第三个、第四个……没有数量限制

二、Ultra Work：一键召唤 AI 编程团队

如果说 Session 并行是"手动挡"，那 Ultra Work 就是"全自动驾驶"。输入一个魔法词，AI 自动把任务拆开、分配给最合适的智能体、并行执行。

触发方式

在 prompt 中包含以下任一关键词：

1
2
3

ULW
ultrawork
Ultra Work

工作原理

你的需求：帮我做一个宠物商店网站
        │
        ▼
  ┌─────────────────────────────┐
  │  西西弗斯（主智能体）         │
  │  1. 拆解任务 → Todo List     │
  │  2. 分配子任务              │
  └──────┬──────────┬───────────┘
         │          │
    ┌────▼───┐ ┌───▼────┐ ┌────────▼────┐
    │ 先知    │ │ 前端    │ │ 文档编写者   │
    │ 架构设计 │ │ UI 开发 │ │ 文档生成     │
    └────────┘ └────────┘ └─────────────┘
         │          │            │
         └──────────┴────────────┘
                    │
                    ▼
              完整项目交付

自动拆分 Todo List
同时开启 3 个后台任务并行执行
主智能体居中调度
最终交付完整项目

什么时候用？

场景	适用	说明
从零创建完整项目	✅ 极佳	自动拆分前端、后端、文档
多模块并行开发	✅ 极佳	各智能体分工明确
单文件小修改	❌ 不推荐	杀鸡用牛刀，反而更慢
简单 bug 修复	❌ 不推荐	普通对话更快

💡 复杂度越高，Ultra Work 的价值越大。简单任务反而会因为调度开销变慢。

实际效果

用 Ultra Work 模式创建了一个宠物商店网站：

✅ 在没有任何图片素材的情况下，用 emoji 作为装饰
✅ 界面清新、交互流畅、动画完整

三、@ 指定智能体：让专业的人干专业的事

安装了 Oh My OpenAgent（OMO）后，你拥有一个 AI 编程团队。通过 @ 可以点名让特定智能体干活。

智能体能力表

智能体	擅长领域	最适模型	示例用法
🧠 西西弗斯	统筹规划、任务调度	Claude Opus	复杂多步骤任务
🔮 先知	架构设计、代码评审	GPT 5.5	项目结构设计
🎨 前端工程师	UI 开发、页面布局	Gemini 3 Pro	响应式布局优化
🔍 探索者	网络搜索、查资料	MiniMax	查最新 API 文档
📚 图书管理员	文献查阅、文档检索	—	梳理开源项目源码
📝 文档编写者	README、注释生成	—	生成项目文档
🖼️ 多模态	图片/PDF 理解	—	根据设计稿写代码

使用示例

@前端工程师 帮我把这个登录页改成响应式布局，移动端也要好看

@先知 审查一下 src/service/ 目录下的代码，找出潜在的性能问题

@探索者 查一下 React 19 的 Server Components 最新用法

@文档编写者 给整个项目生成一份 API 文档

切换主智能体

按 Tab 键可以切换当前对话的主智能体，适合长时间使用某个特定角色。

四、Timeline 时光机：随意试错，随时回退

编程中最怕什么？改了一大堆代码，发现方向错了，又回不去。Timeline 就是你的后悔药。

基本用法

`1`	`/timeline # 列出当前 Session 的每一步对话记录`

选择任意节点：

Revert：代码和聊天内容同时回退到该节点，就像什么都没发生过
View：查看当时 AI 做了什么修改

实战场景

1
2
3

1. 你让 AI 重构了某个模块 → 效果不理想
2. /timeline → 选择重构前的节点 → Revert
3. 代码回到重构前，换个思路重新来

使用技巧

🕐 完成一个阶段性任务后，在心里记下那个节点（第几次对话）
🕐 大胆尝试激进方案——反正可以一键回退
🕐 对比两个方案：Revert 到 A 方案 → 看看效果 → Revert 到 B 方案 → 对比

这就是编程版的"存档/读档"，让你敢于探索任何可能性。

五、Ralph Loop：让 AI 死磕到底

这个模式会让 AI 持续循环工作，直到任务真正完成。适合那些需要反复迭代的硬骨头。

启动方式

`1`	`/ralph-loop`

适用场景

"使用 Spring Boot 4 最新标准重构整个项目，直到所有测试用例通过"

"逐个检查 src/ 下所有文件的代码规范，修复每一个违规项"

"为项目添加完整的单元测试，直到覆盖率达到 90%"

和 Ultra Work 的区别

对比维度	Ultra Work	Ralph Loop
工作机制	并行拆分、多智能体协作	串行循环、持续迭代
适合场景	从零构建、多模块项目	重构、修复、达标类任务
耗时	几分钟到十几分钟	可能数小时
终点	任务拆解完成	满足终止条件

⚠️ Ralph Loop 可能运行很久，注意 API 额度消耗。

六、日常提速小技巧

1. 善用 `/compact` 节省上下文

当你和 AI 聊了很多轮，上下文窗口快满时：

`1`	`/compact`

AI 会把之前的对话提炼成一个摘要，释放空间继续工作。不需要开新对话丢失上下文。

2. 用 `/init` 让 AI 快速上手新项目

进入一个新项目时，先让 AI 通读代码：

/init

AI 会扫描整个项目，生成 agents.md 作为系统提示词。之后任何对话都会基于这个理解，效率大幅提升。

1
2
3

/share      # 生成分享链接，展示完整对话和代码修改
/unshare    # 取消分享，链接失效
/export     # 导出对话记录为文件

适合场景：

给同事展示你是如何用 AI 解决某个问题的
记录踩坑过程，供团队参考
写博客时的素材

4. 查看可用模型

`1`	`/models # 带 free 标记的是免费模型`

GLM-4.7 和 MiniMax-2.1 编程能力不错，适合轻量任务。

5. 快捷粘贴代码（VS Code 插件）

在 VS Code 中选中代码片段 → Ctrl + Alt + K → 直接粘贴到 OpenCode 对话框。

省去复制粘贴的切换成本，保持心流。

七、新手推荐工作流

┌─────────────────────────────────────────────┐
│                 拿到新需求                    │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
          ┌────────────────┐
          │ 简单？          │
          └───┬────────┬───┘
              │ 是      │ 否（复杂/多模块）
              ▼         ▼
    ┌─────────────┐  ┌─────────────────┐
    │ 普通对话搞定  │  │ 输入 ULW 触发    │
    │             │  │ Ultra Work 模式  │
    └─────────────┘  └────────┬────────┘
                              │
                   ┌──────────▼──────────┐
                   │ 多个独立子任务？       │
                   └───┬──────────┬──────┘
                       │ 是        │ 否
                       ▼           ▼
              ┌─────────────┐ ┌──────────────┐
              │ /new 开多个   │ │ 等 Ultra Work │
              │ Session 并行  │ │ 自动完成       │
              └──────┬──────┘ └──────────────┘
                     │
                     ▼
              ┌─────────────┐
              │ /sessions    │
              │ 查看所有进度  │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │ 某个方向错了？ │
              └───┬─────────┘
                  │
                  ▼
              ┌─────────────┐
              │ /timeline →  │
              │ Revert 回退   │
              └─────────────┘

一句话总结

小活直接聊，大活喊 ULW，并行用 Session，错了就 Timeline 回退，死磕开 Ralph Loop。

八、一个真实案例

在 Oh My OpenAgent 安装完成后，想调整 Agent 模型配置——让 GitHub Copilot 作为主力，免费的 OpenCode Zen 作为备选。

第一次尝试

直接在 OpenCode 对话中说：

“其实我还有你免费的 OpenCode Zen，但是我已经登录 GitHub Copilot 了，你帮我修改一下”

AI 把 OpenCode Zen 设成了主力——因为没说清楚主次关系。❌

纠正

“不是，是 GitHub Copilot 作为主力，OpenCode Zen 自带的免费模型作为备选”

AI 立即修正，更新了 oh-my-openagent.json，所有 Agent 都用 github-copilot/* 为主、opencode/* 为 fallback。✅

💡 教训：跟 AI 描述需求时，主次关系一定要说清楚——“XX 作为主力，YY 作为备选”，不要只说"帮我加上 YY"。

📚 参考来源：OpenCode 全深度指南、Oh My OpenAgent 📅 笔记生成日期：2026-05-07

5分钟安装ClaudeCode并接入DeepSeek

Sun, 26 Apr 2026 02:00:15 +0800

概述

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，内置多种 Skills 插件，通过不同组合可以完成许多 AI 单独做不到的事。接入国产大模型 DeepSeek V4 后，可以大幅降低使用成本。

核心用途：

构建个人知识库，自动化整理学习笔记
按时搜集行业资讯并整理成文稿
自动发布到各大社交媒体平台

第一步：安装运行环境

1.1 安装 Node.js

前往 Node.js 官网下载 Windows 安装包（.msi），双击后一路下一步。

验证安装：

1
2

node -v
npm -v

1.2 配置 npm 国内镜像

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

💡 为什么要配置镜像？

默认 npm 源在国外，下载速度很慢。配置国内镜像后安装速度可提升 10 倍以上。

1.3 安装 Git

前往 Git 官网下载对应版本安装包，一路下一步。

验证安装：

git -v

1.4 安装 CC-Switch

CC-Switch 用于将第三方模型接入 Claude Code。

前往 GitHub Release 页面下载对应版本（如 Windows MSI），双击安装，一路下一步。

第二步：安装 Claude Code

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

验证：

`1`	`claude --version`

跳过登录（使用第三方 API）

启动一次 Claude Code 后关闭
在用户目录下找到 .claude.json 文件
添加以下字段（注意上一字段尾部需加英文逗号）：

`1`	`"hasCompletedOnboarding": true`

重新执行 claude 启动，选择信任当前文件夹即可

⚠️ 常见错误

如果忘记在上一字段末尾加逗号，会导致 JSON 解析错误，Claude Code 无法启动。

第三步：接入 DeepSeek

3.1 获取 API Key

打开 DeepSeek 开放平台，注册登录
确保账户有余额
右侧 API Keys → 创建 API Key → 复制保存（关闭后无法再次查看）

🚨 密钥安全

密钥不要分享给他人，否则会消耗你的余额。

3.2 配置 CC-Switch

打开 CC-Switch，点击右上角 + 号
模型预设选择 DeepSeek
填入 API Key
模型名称统一改为：deepseek-v4-pro[1m]（上下文 1M，Claude Code 默认使用 128K）
点击添加

3.3 验证模型

在 Claude Code 对话框中输入：

/model

可查看当前可用模型，或直接问"你当前是什么模型"确认接入成功。

第四步：实战示例

桌面新建一个文件夹
在地址栏输入 CMD 回车
执行 claude 启动，选择信任当前文件夹
输入需求：使用 HTML + JS + CSS 做一个 Todo 软件
运行中会申请工具权限，选择 Yes 即可
完成后让它帮你打开页面预览

💡 小技巧

可以用中文直接描述需求，Claude Code 支持中英文混合输入。

命令速查表

操作	命令
Node 版本检查	`node -v`
npm 版本检查	`npm -v`
npm 国内镜像	`npm config set registry https://registry.npmmirror.com/`
Git 版本检查	`git -v`
安装 Claude Code	`npm install -g @anthropic-ai/claude-code`
Claude Code 版本检查	`claude --version`
启动 Claude Code	`claude`
切换模型	`/model`

常见问题

执行 claude 后提示找不到命令？

检查 Node.js 是否安装成功（node -v），以及 npm 全局路径是否在系统 PATH 中。

启动后要求登录 Anthropic 账号？

说明 .claude.json 中的 hasCompletedOnboarding 未正确配置，请回到第二步检查。

模型调用报错 / 无响应？

检查 DeepSeek 账户余额是否充足，以及 CC-Switch 中 API Key 是否正确填写。

安装ClaudeCode并接入DeepSeek（面向小白）

Sun, 26 Apr 2026 02:00:15 +0800

概述

这份教程是给谁看的？

这份教程面向完全没有计算机基础的用户。你不需要知道什么是"命令行"、什么是"环境变量"、什么是"版本管理"——我会把每一步都拆解到最细，告诉你在哪里点、点什么、输入什么、看到什么说明成功了。

你要装什么？为什么要装这些？

在开始之前，先了解我们一共要安装 3 个东西，它们各自的作用：

序号	软件名称	一句话解释	为什么必须装
1	Node.js	让你的电脑能运行 JavaScript 程序的"引擎"	Claude Code 是用 JavaScript 写的，没有它就跑不起来
2	Claude Code	一个住在你电脑终端里的 AI 编程助手	这就是我们最终要用的东西
3	CC-Switch	一个给 Claude Code “换大脑"的小工具	让 Claude Code 从昂贵的官方模型换成便宜的 DeepSeek

整个过程大约需要 10-15 分钟。请按顺序一步步来，不要跳步。

📌 前提条件

你需要一台 Windows 电脑（Windows 10/11），能正常上网。

安装 Node.js

什么是 Node.js？

Node.js = 让电脑能运行 Claude Code 的运行环境。它是完全免费的，就像你需要先装好 Windows 系统才能运行软件一样，你需要先装好 Node.js 才能运行 Claude Code。

下载 Node.js

第 1 步：打开浏览器

打开你电脑上任意一个浏览器（Chrome、Edge、Firefox 都可以）。

第 2 步：访问 Node.js 官网

在浏览器地址栏（顶部输入网址的长条框）中输入以下网址，然后按回车：

`1`	`https://nodejs.org/`

第 3 步：找到下载按钮

打开网页后，你会看到页面中央有两个大按钮：

左边的按钮写着 LTS（推荐的版本号，比如 22.16.0 LTS）
右边的按钮写着 Current

点击左边的 LTS 按钮，浏览器会自动开始下载一个 .msi 文件。

第 4 步：找到下载好的文件

下载完成后（通常只需几秒钟），有两种方式找到这个文件：

方式一：点击浏览器右上角的下载列表（通常是一个向下的箭头 ↓ 图标），在列表中找到刚才下载的文件，文件名类似 node-v22.16.0-x64.msi
方式二：打开文件资源管理器（就是你看文件夹的那个窗口），在左侧找到下载文件夹，里面就有这个文件

安装 Node.js

第 1 步：双击安装文件

在下载文件夹中，找到 node-v22.16.0-x64.msi（版本号可能略有不同），双击它。

第 2 步：欢迎界面

弹出一个标题为 Node.js Setup（Node.js 安装向导）的窗口。点击底部的 Next（下一步）按钮。

第 3 步：许可协议

窗口中显示一大段英文协议文字。

勾选左下角的复选框：I accept the terms in the License Agreement（我接受许可协议中的条款）
点击 Next

第 4 步：安装位置（⚠️ 重要！需要修改路径）

这里显示的是 Node.js 将要安装到你电脑的哪个位置。

默认路径是：C:\Program Files\nodejs\

📌 我们要把它改到 D 盘！

建议安装到 D 盘，原因：

C 盘是系统盘，放太多东西会影响电脑速度

D 盘专门用来装软件，万一系统重装了，D 盘的东西还在

方便管理和查找

修改步骤：

点击路径输入框，把里面的内容全部选中（按 Ctrl + A），然后删除
输入新的路径：
1

D:\nodejs\
点击 Next

💡 注意

路径中不要有中文和空格，否则可能导致安装出错。

第 5 步：自定义安装

显示一个带有树状复选框的页面（Custom Setup）。

什么都不要改，直接点击 Next。

第 6 步：确认安装

点击 Install（安装）按钮。如果弹出安全提示，点击是。

第 7 步：等待安装

进度条会走完，通常只需 10-30 秒。

第 8 步：完成

点击 Finish（完成）。

Node.js 安装完成！

此时 Node.js 和 npm（Node.js 的包管理器，可以理解为"软件商店”）都已经装好了。

验证 Node.js 是否安装成功

安装完成后，我们需要验证一下——就像买完菜要检查一下有没有漏掉的东西。

第 1 步：打开命令提示符（CMD）

什么是"命令提示符"？

命令提示符（也叫 CMD）是一个黑色背景、白色文字的窗口，你可以在这个窗口里输入文字命令来让电脑执行操作。以后会经常用到它。

打开方式（任选一种）：

方式一（推荐）：
1. 按住键盘上的 Win 键（键盘左下角，画着 Windows 图标的那个键）
2. 同时按下 R 键
3. 弹出一个小窗口（标题是"运行"），在里面输入 cmd
4. 点击确定，或直接按回车键（Enter）
方式二：
1. 点击桌面左下角的开始菜单（Windows 图标）
2. 在搜索框中输入 cmd
3. 点击搜索结果中的 命令提示符

第 2 步：输入验证命令

在打开的黑色窗口中，输入以下内容（输入时屏幕上会显示你打的字），然后按回车键：

node -v

如果窗口中显示类似 v22.16.0 的内容，说明 Node.js 安装成功了 ✅

继续输入以下命令，按回车：

npm -v

如果显示类似 10.9.2 的版本号，说明 npm 也正常 ✅

⚠️ 提示"不是内部或外部命令"？

说明环境变量没有配置好，请看下面的 1.4 如何配置环境变量。

如何配置环境变量

什么是环境变量（PATH）？

PATH 可以理解为电脑的"通讯录"。当你在命令提示符里输入 node 时，电脑不知道 node 装在哪里，它会去 PATH 这个"通讯录"里找。如果 PATH 里没有 Node.js 的安装目录，电脑就找不到它，就会报"不是内部或外部命令"。

正常情况下，Node.js 安装时会自动把自己加到 PATH 里。但如果出了问题，你需要手动添加。

查看 PATH 里有没有 Node.js

按 Win + R，输入 sysdm.cpl，回车
点击顶部的高级选项卡
点击底部的 环境变量 按钮
在下方 系统变量 列表中，找到 Path 这一行，选中它，点击编辑

在弹出的列表中，检查有没有类似这样的条目：

`1`	`D:\nodejs\`

💡 路径要和你安装时设置的一致

如果你当时装在了 D:\Software\nodejs\，那这里也应该显示 D:\Software\nodejs\。

如果有这个条目：说明 PATH 没问题，但仍然报错的话，关掉当前命令提示符窗口，重新打开一个新的再试。

如果没有这个条目：按下面步骤手动添加。

手动添加 Node.js 到 PATH

在刚才打开的 编辑环境变量 窗口中，点击新建
输入 Node.js 的安装路径：
1

D:\nodejs\
点击确定
点击确定关闭环境变量窗口
点击确定关闭系统属性窗口
关掉所有已打开的命令提示符窗口，重新打开一个新的（旧窗口不会识别新配置）
再次输入 node -v 验证

配置 npm 国内镜像（强烈推荐）

💡 为什么要配置？

npm 默认从国外下载软件，速度很慢。配置国内镜像后下载速度提升 10 倍以上。

在命令提示符中输入以下命令，按回车：

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

输入以下命令验证，如果显示 https://registry.npmmirror.com/ 则成功 ✅：

`1`	`npm config get registry`

第一步完成！

你已经在电脑上安装好了 Node.js，并且配置了国内镜像。接下来安装 Claude Code。

安装 Claude Code

通过 npm 安装 Claude Code

打开命令提示符（如果还没打开的话），输入以下命令，按回车：

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

等待安装完成（一般 1-3 分钟）。屏幕上会滚动一些文字，只要最后没有报错就行。

验证安装

输入：

`1`	`claude --version`

按回车。如果显示版本号（例如 1.0.x），说明安装成功 ✅

首次启动（跳过登录）

为什么要跳过登录？

Claude Code 官方要求你用 Anthropic 账号登录才能使用。但 Anthropic 的服务需要海外信用卡支付，对国内用户很不方便。

我们的方案是：先跳过登录，然后通过 CC-Switch 工具接入国产的 DeepSeek 模型，这样就不需要 Anthropic 账号了，费用也低得多。

第 1 步：先启动一次 Claude Code

在命令提示符中输入：

claude

按回车。Claude Code 会启动，可能会显示一些介绍信息或要求你登录。

不用管它，直接关闭这个命令提示符窗口（点右上角的 ×）。

第 2 步：找到配置文件

按 Win + R（Win 键 + R 键同时按）
在弹出的"运行"窗口中，输入 %USERPROFILE%
点击确定或按回车
打开后，你会看到一个文件夹，里面有各种文件和子文件夹

第 3 步：找到 .claude.json 文件

在这个文件夹中，找到一个名为 .claude.json 的文件。

⚠️ 找不到这个文件？

如果找不到 .claude.json，可能是以下原因：

文件扩展名被隐藏了——在文件夹窗口顶部，点击查看 → 勾选 文件扩展名 和 隐藏的项目

Claude Code 还没有创建这个文件——请回到第 1 步，确保你成功启动过一次 Claude Code

在某些情况下，这个文件可能在 .claude 文件夹里面，文件名为 settings.json

第 4 步：用记事本打开配置文件

右键点击 .claude.json 文件
在弹出的菜单中，选择 打开方式
选择 记事本（Notepad）
- 如果列表中没有记事本，选择 选择其他应用 → 在列表中找到 记事本 → 点击确定

第 5 步：编辑配置文件

打开后，你会看到类似这样的内容（具体内容可能不同）：

{
  "someField": "someValue",
  "anotherField": "anotherValue"
}

我们需要在最后的 } 前面，添加一行 "hasCompletedOnboarding": true。

修改后的样子应该是这样的：

{
  "someField": "someValue",
  "anotherField": "anotherValue",
  "hasCompletedOnboarding": true
}

📌 ⚠️ 注意三个细节，否则会报错！

加逗号：hasCompletedOnboarding 前面那行的末尾要加一个英文逗号 ,

用英文引号：引号必须是英文的 "，不能是中文的 "

true 是小写：必须写 true，不能写 True

第 6 步：保存文件

按 Ctrl + S 保存（或者点击左上角文件 → 保存）
关闭记事本窗口

第 7 步：验证跳过登录是否成功

重新打开命令提示符（Win + R → cmd → 回车）
输入 claude，按回车
如果直接进入了 Claude Code 的主界面（没有要求你登录），说明跳过登录成功 ✅

第二步完成！

Claude Code 安装完毕，并且跳过了登录步骤。接下来安装 CC-Switch 来接入 DeepSeek。

安装 CC-Switch（模型切换工具）

什么是 CC-Switch？

CC-Switch 是一个可视化工具，让你不用手动改配置文件，点点鼠标就能把 Claude Code 的"大脑"从官方模型换成 DeepSeek。

下载 CC-Switch

第 1 步：打开下载页面

在浏览器地址栏中输入以下网址，按回车：

`1`	`https://github.com/cc-switch/cc-switch/releases`

第 2 步：找到最新版本

打开页面后，找到带有绿色 Latest 标签的版本，点击展开。

第 3 步：找到下载链接

展开后往下滚动，找到 Assets 这个词（旁边可能有个小箭头 ▾），点击展开它。

找到以 .msi 结尾的文件（Windows 安装包），点击文件名开始下载。

💡 选哪个文件？

Windows 电脑：选 x64.msi 结尾的文件

Mac 电脑：选 .dmg 结尾的文件

安装 CC-Switch

第 1 步：双击安装文件

在下载文件夹中，双击下载好的 .msi 文件。如果弹出安全提示，点击 仍要运行 或 更多信息 → 仍要运行。

第 2 步：按提示安装

安装向导和 Node.js 类似：

点击 Next
接受协议 → Next
保持默认安装路径 → Next
点击 Install
等待安装完成 → Finish

第三步完成！

CC-Switch 安装好了。接下来获取 DeepSeek 的 API Key。

获取 DeepSeek API Key

什么是 DeepSeek？

国产大语言模型，性能强大且价格低廉（日常使用每月约 10-30 元），接入后可以大幅降低使用成本。

什么是 API Key？

API Key 是一把钥匙，用来调用 DeepSeek 的 AI 服务，每次使用会从账户余额中扣费。你需要：① 注册账号 ② 充值 ③ 创建 Key

注册 DeepSeek 账号

第 1 步：打开 DeepSeek 开放平台

在浏览器地址栏中输入：

`1`	`https://platform.deepseek.com/`

按回车。

💡 注意

这是 DeepSeek 的开发者平台（platform.deepseek.com），不是聊天网站（chat.deepseek.com），别搞混了。

第 2 步：注册/登录

页面右上角有登录 / 注册按钮
点击注册（如果没有账号）或登录（已有账号）
按页面提示填写信息完成注册

充值余额

💡 费用参考

日常使用一个月大约只需 10-30 元，建议首次充值 20-50 元。

登录后，在页面左侧菜单中找到充值（或钱包 / Billing），点击它
选择充值金额，选择支付方式，完成支付
确保账户余额大于 0（没有余额无法使用 API）

创建 API Key

第 1 步：进入 API Keys 页面

登录后，在左侧菜单中找到 API Keys，点击它
你会看到一个 API Keys 管理页面

第 2 步：创建新的 API Key

点击 创建 API Key 按钮
弹出一个对话框，要求你输入 Key 的名称
- 可以随意填写，比如 claude-code、我的key、test 都行
- 这个名称只是给你自己看的，用来区分不同的 Key
点击确认或创建

第 3 步：复制 API Key（⚠️ 最关键的一步！）

创建成功后，页面会显示你的 API Key，格式类似：

`1`	`sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

⚠️ 这个 Key 只会显示一次！

关闭对话框后就再也看不到了。请立即复制保存到记事本或微信文件传输助手。

🚨 安全提醒

API Key 等同于你的账号密码，不要分享给任何人，不要发到公开场合。如果怀疑泄露，立即删除并重新创建。

第四步完成！

你已经有了 DeepSeek 的 API Key（钥匙）。最后一步，把这把钥匙交给 CC-Switch，完成接入。

配置 CC-Switch 接入 DeepSeek

打开 CC-Switch

在桌面上或开始菜单中找到 CC-Switch 的图标，双击打开。

添加 DeepSeek 配置

第 1 步：点击添加按钮

CC-Switch 打开后，找到右上角的 + 号（加号按钮），点击它。

第 2 步：填写配置信息

点击 + 号后，会弹出一个配置面板，填写以下信息：

① 模型预设（Model Preset）：选择 DeepSeek

② API Key：粘贴你之前复制的 DeepSeek API Key（注意首尾不要有空格）

③ 模型名称（Model Name）：把输入框内容删掉，输入：

`1`	`deepseek-v4-pro[1m]`

④ Base URL / API 地址（如果有的话）：

`1`	`https://api.deepseek.com`

第 3 步：保存配置

检查所有信息都填好后，点击添加 / 保存 / 确认按钮。

切换到 DeepSeek

回到 CC-Switch 的主界面
你会看到刚才添加的 DeepSeek 配置已经出现在列表中
点击该配置旁边的切换 / 启用按钮
界面上应该会显示"当前模型：DeepSeek"或类似的信息

验证接入是否成功

打开命令提示符，输入 claude 启动 Claude Code。

在 Claude Code 中输入：

/model

按回车。如果显示的模型信息中包含 DeepSeek，说明接入成功 ✅

全部配置完成！

现在可以开始使用 AI 编程助手了！

开始使用（实战示例）

配置完成后，做一个简单的练习确保一切正常。

创建项目文件夹并打开命令提示符

在桌面右键 → 新建 → 文件夹，命名为 my-first-ai-project
双击打开这个文件夹
点击窗口顶部的地址栏，输入 cmd，按回车

启动 Claude Code

在弹出的命令提示符窗口中，输入：

claude

按回车。如果询问是否信任这个文件夹，输入 y 按回车。

发出第一个指令

Claude Code 启动后，输入以下内容（可以直接用中文）：

`1`	`帮我创建一个简单的个人主页，使用 HTML + CSS + JavaScript，包含一个标题、一段自我介绍和一个深色模式切换按钮`

按回车提交。

处理权限请求

运行过程中 Claude Code 可能会询问是否允许创建/修改文件，选择 Yes 即可。建议在自己创建的项目中选择 Yes, always allow（以后不再询问）。

查看成果

完成后，回到项目文件夹，双击 index.html，它会在浏览器中打开，你就能看到 AI 帮你创建的网页了！

恭喜！

你已经用 Claude Code + DeepSeek 完成了第一个项目！

常用命令速查表

操作	命令	说明
检查 Node.js 版本	`node -v`	验证 Node.js 是否安装
检查 npm 版本	`npm -v`	验证 npm 是否正常
设置 npm 镜像	`npm config set registry https://registry.npmmirror.com/`	加速下载
检查 npm 镜像	`npm config get registry`	验证镜像是否生效
安装 Claude Code	`npm install -g @anthropic-ai/claude-code`	全局安装
检查 Claude Code 版本	`claude --version`	验证 Claude Code 是否安装
启动 Claude Code	`claude`	在当前文件夹启动
查看当前模型	`/model`	在 Claude Code 内输入
退出 Claude Code	`/exit` 或按两次 `Ctrl + C`	退出程序

常见问题 FAQ

输入 node -v 提示"不是内部或外部命令"？

Node.js 的环境变量（PATH）没有配置好。打开文件资源管理器，进入 D:\nodejs\ 看看里面有没有 node.exe：

有这个文件：说明安装了但 PATH 没配好，按照上方 1.4 如何配置环境变量 的步骤手动添加

没有这个文件：说明安装失败了，重新下载安装

输入 claude 提示"不是内部或外部命令"？

Claude Code 安装没成功。先确认 node -v 和 npm -v 正常，然后重新执行 npm install -g @anthropic-ai/claude-code。

启动 Claude Code 后要求登录 Anthropic 账号？

.claude.json 没改对。按 Win + R，输入 %USERPROFILE% 回车，找到 .claude.json 用记事本打开，确认里面有 "hasCompletedOnboarding": true，且前面那行末尾有英文逗号、true 是小写、引号是英文引号。

Claude Code 对话时报错 / 无响应？

常见原因：① DeepSeek 余额不足 ② API Key 填写错误 ③ 模型名称不是 deepseek-v4-pro[1m] ④ 网络问题。逐项检查即可。

npm 安装 Claude Code 非常慢（超过 5 分钟）？

检查是否配置了国内镜像：npm config get registry（应显示 registry.npmmirror.com）。如果没有，执行 npm config set registry https://registry.npmmirror.com/ 后重试。

CC-Switch 打不开或闪退？

到 GitHub Release 重新下载最新版本，或尝试右键以管理员身份运行。

GitHub 页面打不开？

原因：GitHub 在国内可能访问不稳定。解决：

多刷新几次页面

尝试使用不同的浏览器

如果实在打不开，可以在网上搜索"CC-Switch 下载"，有些国内镜像站也提供了下载

完整流程回顾

步骤内容一句话总结

第一步安装 Node.js 装好"运行引擎"，让电脑能跑 JavaScript 程序

第二步安装 Claude Code 装好"AI 助手"，并跳过登录

第三步安装 CC-Switch 装好"换脑器"，用来切换 AI 模型

第四步获取 DeepSeek API Key 拿到"钥匙"，用来调用 DeepSeek 的 AI 服务

第五步配置 CC-Switch 用"换脑器"+“钥匙”，把 Claude Code 的大脑换成 DeepSeek

第六步开始使用在任何文件夹中输入 claude 启动 AI 助手！

完成全部步骤后，你就可以在电脑的任何文件夹中，输入 claude 命令，启动一个由 DeepSeek 驱动的 AI 编程助手了！

小白也能学会！用 AI 快速画出漂亮的技术架构图

Tue, 31 Mar 2026 19:51:00 +0800

✈️ 小白也能学会！用 AI 快速画出漂亮的技术架构图

👋 这篇文档是写给完全没画过架构图的新手看的。你不需要会设计、不需要会写代码，只要会用 AI 聊天就能跟着做。

什么是技术架构图？我为什么要画它？

简单说，技术架构图就是把你脑子里的系统"画出来"——

比如你要做一个 App，它有哪些功能模块？用户怎么用？数据怎么流转？把这些关系画成图，就是架构图。

画它的好处很实在：

✅ 自己理清思路——画图的过程就是你梳理系统设计的过程
✅ 跟同事沟通不费劲——一张图胜过千言万语
✅ 汇报展示有面子——老板和客户一看就明白你的方案有多牛
✅ AI 帮你画，省时省力——现在用 AI，几分钟就能出一张像样的图

🤔 新手该选哪种方法？（先看这个）

你的情况	推荐方案	难度
就想最快出一张好看的图，后期不改了	方案一（AI 直接生成图片）	⭐
愿意多一步，让图以后好修改	方案二（Mermaid.js 代码生成）	⭐⭐
做正式文档，需要反复修改、风格统一	方案三（Excalidraw 本地画图）	⭐⭐⭐

💡 新手建议：先试 方案一 感受一下，再尝试 方案二。方案三等你需要做正式文档时再研究。

方案一：直接让 AI 帮你画一张图（最简单，最快）

⏱ 耗时：2-3 分钟 🛠 工具：Gemini 3.1 Pro（谷歌出品，免费可用）

一句话原理

让你用的 AI（比如 Gemini）先写出"画图描述词"，再把这个描述词喂给 AI 的画图功能，AI 就帮你把图画出来了。

手把手操作步骤

第 1 步：让 AI 帮你写"画图描述词"

打开 Gemini，输入下面这段话（直接复制，替换你的内容就行）：

请帮我写一段用于生成技术架构图的提示词（prompt），
我要画的是一个 [你的系统名称，比如：电商网站] 的架构图，
包含以下模块：用户端、商品管理、订单系统、支付系统、后台管理。
模块之间的数据流向是：用户下单 → 订单系统调支付 → 支付完成通知商品管理扣库存。
请用英文给出适合文生图模型的详细提示词，风格要专业、清晰、好看。

AI 会还你一段英文描述词。

第 2 步：把提示词喂给 AI 画图

在 Gemini（或其他支持画图的 AI）里，选择画图功能（如 Gemini 自带的 Banana 2.0 模型），然后把上一步得到的描述词粘贴进去，点生成。

第 3 步：完成 🎉

AI 会输出一张图片。不满意就重新生成一次，直到满意为止。

优缺点

✅ 优点	❌ 缺点
速度最快，几分钟搞定	改起来麻烦——系统变了就得重新生图
图片效果好看，色彩丰富	结果不稳定，有时第一次出的图不满意
不需要任何额外工具	提示词写得不好，出图效果就不好

📌 小白避坑提示

提示词一定要详细——你给 AI 的信息越具体，出图越准。别只说"画个架构图"，要说清楚有哪些模块、怎么连接的
多试几次——第一次出的图如果不满意很正常，微调提示词再生成一两次
英文提示词效果更好——大部分画图模型对英文理解更好，所以第一步让 AI 生成英文描述词

方案二：让 AI 先生成代码，再用代码渲染成图（推荐新手尝试）

⏱ 耗时：3-5 分钟 🛠 工具：任意 AI（ChatGPT、Claude、Gemini 都行）+ Mermaid.js

一句话原理

流程图的本质是一段代码（Mermaid.js 语法）。你让 AI 帮你写出这段代码，然后通过一个免费在线网站把代码渲染成图片。想改图？让 AI 改代码，重新渲染就行。

手把手操作步骤

第 1 步：让 AI 生成 Mermaid 代码

打开你用的 AI（ChatGPT、Claude、Gemini 都行），输入（直接复制，替换成你的内容）：

请用 Mermaid 语法帮我画一个电商系统的架构图。
系统包含：用户端、商品管理、订单系统、支付系统、后台管理。
数据流向是：用户下单 → 订单系统调支付 → 支付完成通知商品管理扣库存。
请输出纯 Mermaid 代码，用 graph TD 格式。

AI 会返回一段像这样的代码：

graph TD
    A[用户端] --> B[订单系统]
    B --> C[支付系统]
    B --> D[商品管理]
    C --> E[支付完成]
    E --> D

第 2 步：把代码渲染成图片

打开这个免费网站：mermaid.live

把 AI 给你的代码粘贴到左边的编辑区
右边立刻就会显示出流程图
点右上角的"导出"按钮，选择 PNG 或 SVG 格式下载（SVG 是矢量图，放多大都不模糊，适合正式文档）

第 3 步：想修改？让 AI 改代码就行

把旧代码贴回给 AI，告诉它你想怎么改：

`1`	`把上面的代码改一下，在"用户端"和"订单系统"之间加一个"登录验证"模块。`

改好后重新去 mermaid.live 粘贴、导出就行。

优缺点

✅ 优点	❌ 缺点
图片质量好，专业感强	复杂的图后期修改仍然比较麻烦
比方案一好修改——改代码再渲染就行	架构逻辑有大的变化时，基本要重新生成
不需要安装任何软件，打开网页就能用

📌 小白避坑提示

Mermaid 语法有固定格式——让 AI 生成时明确说"用 Mermaid 语法"，AI 都知道
mermaid.live 是神器——粘贴即预览，完全免费，不用注册账号
导出选 SVG 更好——SVG 是矢量图，放多大都不模糊，适合正式文档
代码保存好——以后修改时直接把旧代码发给 AI，说"改这行"就行

方案三：让 AI 生成可编辑的架构图（适合做正式文档）

⏱ 耗时：10-15 分钟（第一次配置稍久） 🛠 需要：一个 AI 编程工具 + Obsidian + 一个"画图指令包"

一句话原理

这是最专业的方法，但第一次需要花点时间配置。装好之后，你告诉 AI 想画什么，AI 直接生成一个可以拖拽修改的架构图文件，你用 Obsidian 打开，哪里不满意就手动调一下。方案一方案二出的图是"死图"，这个方案出的图是"活的"。

🤔 先搞懂：什么是 “画图指令包”（Skills）？

Skills 就是一套写好的"说明书"，告诉 AI 怎么帮你画图。

没装之前：你跟 AI 说"帮我画个架构图"，AI 只能给你一段文字描述
装好之后：AI 知道怎么生成一个可以编辑的架构图文件

好比给你的 AI 装了一个"画图插件"。

这个指令包叫 axton-obsidian-visual-skills，是一个叫 Axton 的人做的免费开源项目。它含 3 种画图能力：

画图方式	生成的文件	适合画什么	画面风格
Excalidraw 画图	`.excalidraw` 文件	流程图、思维导图、架构图	✏️ 手绘风格（像白板上画的）
Mermaid 画图	一段文字规则	流程图、时序图、对比图	🎯 商务专业风格
Canvas 画布	`.canvas` 文件	思维导图、知识整理	🎨 彩色卡片

💡 也可以换 Draw.io——Draw.io 是另一款免费画图软件，也有对应的指令包。本教程以 Excalidraw 为例。

🔧 前置安装（只需一次）

💡 先搞懂：这个指令包要放哪里？

AI 工具会去你电脑上的固定位置找这些指令文件。推荐放这个位置：

C:\Users\你的用户名\.claude\skills\

🤔 这串路径是啥？

C:\Users\你的用户名\ ← 你的"用户文件夹"（也叫用户目录），你电脑上的软件默认把配置文件放这里

\.claude\ ← Claude Code 这个软件建的配置文件夹

skills\ ← 专门放画图指令的地方

不知道怎么查"你的用户名"？打开文件管理器，在地址栏输入 %USERPROFILE% 按回车，跳到的那个文件夹就是。

如果你的用户名是 xiaoming，那完整路径就是 C:\Users\xiaoming\.claude\skills\

🤔 为什么在 C 盘？ 因为你的用户文件夹默认就在 C 盘。放这里是让这台电脑上所有项目都能用这个指令包，不用每个项目都装一次。

这个位置 OpenCode 和 Claude Code 通用，文件放一次，两个工具都能用。

其他工具也可以放别的位置，但新手不用管，直接放上面那个路径就行。

安装方式一：让 AI 帮你装（推荐，最简单）

不管你用 OpenCode、Claude Code 还是 Cursor，直接对它说：

1
2
3

帮我从 GitHub 下载 axtonliu/axton-obsidian-visual-skills，
解压后把 excalidraw-diagram、mermaid-visualizer、obsidian-canvas-creator
这三个文件夹放到 C:\Users\你的电脑用户名\.claude\skills\ 目录下。

AI 会自动帮你完成下载、解压、复制。完成后重启工具即可。

💡 记得把上面路径里的"你的电脑用户名"换成你真正的用户名。

安装方式二：自己手动下载

如果 AI 不支持操作文件，或者你想自己来：

打开 axton-obsidian-visual-skills 下载页面
点绿色的 Code 按钮 → Download ZIP
解压下载的文件，你会看到 3 个文件夹
打开你的 C:\Users\你的用户名\.claude\ 文件夹（如果没有 skills 文件夹，就新建一个）

把解压出来的 3 个文件夹整个拖进去

最终效果是这样：

C:\Users\你的用户名\.claude\skills\
   ├── excalidraw-diagram\
   │     └── SKILL.md
   ├── mermaid-visualizer\
   │     └── SKILL.md
   └── obsidian-canvas-creator\
         └── SKILL.md

安装方式三：Claude Code 专属的快捷安装

如果你用的是 Claude Code（只有它支持这种方式），可以直接在聊天里输入：

1
2

/plugin marketplace add axtonliu/axton-obsidian-visual-skills
/plugin install obsidian-visual-skills

安装完重启 Claude Code 就能用。OpenCode 和 Cursor 不支持这种安装方式。

还需要装这些：

软件	用途	费用
OpenCode / Claude Code / Cursor	用来运行 AI 生成画图文件	各有免费方案
Obsidian	用来查看和手动调整架构图	免费
Obsidian Excalidraw 插件	在 Obsidian 里编辑 Excalidraw 文件	免费（插件市场直接搜 “Excalidraw” 安装）

🖐️ 手把手操作步骤

第 1 步：装好 Skills，告诉 AI 你想画什么

装好 Skills 之后，直接在 OpenCode、Claude Code 或 Cursor 里输入：

如果你想画 Excalidraw 手绘风格架构图：

用 Excalidraw 帮我画一个电商系统的架构图，包含：
用户端、商品管理、订单系统、支付系统、后台管理。
用户下单 → 订单系统调支付 → 支付完成扣库存。
用中文标注。

AI 会自动在当前目录下生成一个 .excalidraw 文件（比如 电商系统架构图.excalidraw.md）。

🔍 找不到文件？ 看看 AI 打印的输出信息，它通常会告诉你文件保存的路径，比如 文件已保存到：D:/project/电商系统架构图.excalidraw.md。记住这个路径，下一步要用。

如果你想画 Mermaid 商务风格流程图：

1
2

把这个流程转成 Mermaid 图表：
用户访问首页 → 浏览商品 → 加入购物车 → 提交订单 → 在线支付 → 完成交易

AI 会生成一段 Mermaid 代码，你复制到 mermaid.live 就能渲染成图。

如果你想画 Canvas 思维导图：

1
2

把这篇文章整理成 Obsidian Canvas 思维导图：
[粘贴你的内容]

AI 会生成一个 .canvas 文件，用 Obsidian 打开就能看到彩色卡片布局。

第 2 步：在 Obsidian 中手动调整

打开 Obsidian，把上一步生成的文件拖进去
如果是 Excalidraw 文件（.excalidraw 或 .md），双击就能进入编辑模式
你可以随意拖拽方框、调整箭头、修改文字、换颜色
想加模块就拖一个新框，想删除就选中按 Delete

💡 这一步相当于你有一个"活的"架构图，想怎么改就怎么改。

第 3 步（可选）：用 AI 换风格

调整好内容和布局后，如果你想要不同的视觉效果，可以截图发给 Gemini（或其他 AI），配上参考图说：

`1`	`帮我把图1转换成类似图2的手绘风格，并加入适量的图画帮助用户理解`

（提示词1：改变很大，连内容布局都可能调整）

`1`	`转换成类似图2的手绘画面风格`

（提示词2：改变较小，只改配色和画风，内容布局不变）

🔍 Excalidraw 技能能画哪些图？

这套 Skills 的 Excalidraw 画图支持以下类型：

图表类型	适合画什么
流程图	业务流程、操作步骤、任务顺序
思维导图	概念扩展、话题分类、头脑风暴
层级图	组织架构、系统分层、目录结构
关系图	依赖关系、影响关系、元素之间的交互
对比图	方案对比、选项分析、前后对比
时间线	事件演进、项目里程碑、版本迭代
矩阵图	二维分类、优先级矩阵、能力定位
自由画布	零散想法、初期构思、自由笔记

⚠️ 常见问题与解决

Q：中文字体没有手写效果怎么办？ A：Excalidraw 的手写字体（Excalifont）默认只支持英文，中文字体需要联网加载。如果你在 Obsidian 里中文显示为普通字体：

确保能访问 Excalidraw.com（需要网络）
或者从 Excalidraw 官方字体库下载中文字体文件
放到你的 Obsidian 笔记库的 Excalidraw/CJK Fonts 文件夹下
在 Excalidraw 插件设置里开启"启动时加载中文字体"，重启 Obsidian

Q：生成出来的图有点乱怎么办？ A：这很正常，因为 AI 生成的排版不一定完美。手动在 Obsidian 里拖拽调整一下就行——这也是方案三最大的优势。

Q：一定要用 Claude Code 吗？ A：不一定。这套 Skills 在 OpenCode、Claude Code、Cursor 上都能用。OpenCode 兼容 Claude Code 的 Skills 格式，直接安装就能用。

优缺点

✅ 优点	❌ 缺点
想怎么改就怎么改——拖拽就能调整	第一次配置环境需要花点时间
不依赖提示词质量，内容可手动精修	整体流程比较长，操作步骤多
可以做出一套风格统一的文档图	美化时偶尔会出现文字乱码或错位
结合 Obsidian 做知识管理很方便
一个 Skills 装好，三种画图方式随便选

📌 小白避坑提示

建议先用方案一和方案二，熟悉了再尝试方案三
Skills 安装是关键一步——装好了 AI 才知道怎么生成可编辑的文件
Excalidraw 默认是手绘风格，画出来像手画的，很亲切
Obsidian 的 Excalidraw 插件是体验最好的查看和编辑方式
方案三最大的价值是可修改——一次配置好，后续改图只需要拖拽几步就完成
动手前可以在 GitHub 上看这个仓库的演示视频，看到效果再决定要不要装

🔧 经常用到的工具汇总

工具	用途	费用	难度
Gemini	对话 + 文生图	免费	低
ChatGPT	对话 + 文生图	付费/免费版	低
OpenCode	AI 编程工具，自动加载 `~/.claude/skills/`，支持并行调度	免费	中
Claude Code	AI 编程工具，可加载 Skills	按 API 用量付费	中
Cursor	AI 编程工具	免费版够用	中
mermaid.live	Mermaid 代码转图片	免费	低
Excalidraw	可编辑架构图工具	免费开源	低
Obsidian	笔记软件 + Excalidraw 插件可编辑架构图	免费	中
axton-obsidian-visual-skills	AI 画图指令包（含 Excalidraw / Mermaid / Canvas 三种技能）	免费开源	中

🎯 新手快速入门路线图

第1天 → 试方案一：用 Gemini 直接生图（体验一下）
         ↓
第2天 → 试方案二：用 Mermaid.js 生成流程图
         （学会"改代码 = 改图"的思路）
         ↓
第3天 → 把方案二的图用在你的文档里
         ↓
需要了 → 再研究方案三：安装 Skills + Obsidian + Excalidraw 插件
（不着急，方案一和二已经够用）

💬 常见问题（小白 FAQ）

Q：这些工具都是免费的吗？ A：Gemini 和 mermaid.live 完全免费。ChatGPT 和 Claude 有免费额度，用完才需付费。

Q：生成出来的图片能商用吗？ A：可以，架构图是你自己的设计，AI 只是帮你画出来。

Q：我是产品经理/运营，不是程序员，也能画吗？ A：完全没问题。方案一只需要打字，方案二只要会复制粘贴，都不需要写代码。

Q：生成的图片有版权问题吗？ A：工具生成的图片版权归你所有，放心使用。

Q：Mac 和 Windows 都能用吗？ A：文中所有工具都有网页版，操作系统不影响。

Q：方案三说的 “axton-obsidian-visual-skills” 到底是什么，必须装吗？ A：它是一个开源的 AI 画图"指令包"。不装也能画图，但装了之后 AI 能直接生成可编辑的架构图文件（而不是一张死图片）。如果你只是偶尔画一两张图，用方案一方案二就够了；如果你需要反复修改、做正式文档，非常推荐装一下。

Q：方案三里的 3 种画图方式（Excalidraw / Mermaid / Canvas）有什么区别？ A：简单说——Excalidraw 像手绘白板，最适合画架构图；Mermaid 偏专业商务风，适合正式文档；Canvas 是彩色思维导图，适合整理思路。根据你要的效果选就行，不用全学。

Q：方案三一定要用 Claude Code 吗？用 ChatGPT 可以吗？ A：这套 Skills 是给 能操作本地文件的 AI 编程工具设计的，比如 OpenCode、Claude Code、Cursor 都行。ChatGPT 网页版没有本地文件操作能力，所以不能用。

Q：Skills 装好后在哪？我想看看装没装成功。 A：文件放到 ~/.claude/skills/ 目录下就算装好了。你可以手动去这个目录看一眼，里面应该有 excalidraw-diagram、mermaid-visualizer、obsidian-canvas-creator 三个文件夹。重启 AI 工具后，它就能识别到。

📝 最后的话：画架构图最重要的是理清你想表达什么，AI 只是帮你把想法变成图片。先从最简单的方案一开始动手，迈出第一步最重要！

模型	特点
GLM-4.7	编程能力强，零配置
MiniMax-2.1	编程能力出色，响应快

步骤	内容	一句话总结
第一步	安装 Node.js	装好"运行引擎"，让电脑能跑 JavaScript 程序
第二步	安装 Claude Code	装好"AI 助手"，并跳过登录
第三步	安装 CC-Switch	装好"换脑器"，用来切换 AI 模型
第四步	获取 DeepSeek API Key	拿到"钥匙"，用来调用 DeepSeek 的 AI 服务
第五步	配置 CC-Switch	用"换脑器"+“钥匙”，把 Claude Code 的大脑换成 DeepSeek
第六步	开始使用	在任何文件夹中输入 `claude` 启动 AI 助手！