1.1 什么是”提示词”？#

提示词 = 你发给 AI 的工作指令。 没有任何神秘感，就是”把话说清楚”。

对比一下：

❌ 差的提示词：“帮我做个脚本。“（AI 不知道你要什么，只能瞎猜）

✅ 好的提示词：“参考我发给你的’蓝凌EKP系统登录’成功案例，帮我写一个自动登录我们公司 OA 系统的脚本：每天早上自动登录，把’请假审批’列表里昨天结束的流程全部导出成 Excel，存到 （本机路径） 文件夹。账号密码放在配置文件里。“（AI 能直接开工）

好提示词的秘诀就一条：把”谁、参考什么、做什么、结果放哪”四件事说全。 第 5 章会给你万能公式和现成模板。

1.2 什么是”成功案例”？#

成功案例就是 4 个已经做完、能正常运行的自动化项目，它们是你学走这套本领的”样板间”。你不需要看懂里面的代码——你只需要知道：

1. 它能干什么（比如：自动登录网站、下载报表、发钉钉通知）；
2. 哪个文件是”遥控器”（配置文件）；
3. 哪个文件双击就能跑（.bat 启动文件）。

AI 改造案例的原理：你把成功案例文件夹交给 AI，说”照着这个样子，改成我公司的场景”。AI 会模仿案例的结构、套路、写法，生成属于你的新脚本。这就是”参考成功案例”的含义——案例是给 AI 看的范本，不是给你看的。

1.3 什么是”配置文件”（.ini）？#

打开任何一个案例文件夹，你都会看到一个 .ini 结尾的文件，长得像这样（已脱敏）：

1
[登录信息]
2
登录账号 = 你的账号
3
登录密码 = 你的密码
4

5
[浏览器配置]
6
无头模式 = false

这就是遥控器：账号密码、网址、保存路径、要不要后台运行……所有”会变的东西”都集中在这一个文件里。

你以后 90% 的”修改工作”就是改这个文件——比如换账号、换下载路径、增删一个下载任务。改法：用记事本或 TraeCode 打开，改等号右边的值，保存。

⚠️ 注意：等号左边的名字不要动，只改等号右边的值；# 或 ; 开头的行是注释说明，可以随便看，删不删都行。

1.4 三个文件后缀，认识就够了#

2.1 安装 Python（唯一需要手动点几次鼠标的环节）#

1. 打开浏览器，访问 Python 官网下载页：`http（本机路径）
2. 点击黄色的 Download Python 3.x.x 大按钮，下载安装包。
3. 双击安装包，第一屏最关键：
   • ✅ 务必勾选底部的 “Add python.exe to PATH”（把 Python 加入系统路径）——不勾后面全盘卡住；
   • 然后点 Install Now，一路等待完成。
4. 验证是否装好：按键盘 Win + R，输入 cmd 回车，打开黑色命令行窗口，输入：

1
python --version

显示 Python 3.12 之类的版本号 = 成功。显示”不是内部或外部命令” = 大概率没勾 Add to PATH，不用慌，看 2.3 让 AI 救你。

2.2 安装 WorkBuddy、Trae Work、TraeCode#

三个都是图形界面软件，和装微信一样：官网下载安装包 → 双击 → 下一步到底。

三者的分工回顾：WorkBuddy / Trae Work 负责”聊天干活”，TraeCode 负责”打开项目看文件、跑脚本、看报错”。

2.3 关键姿势：环境部署也交给 AI#

装完软件后，缺什么库、路径不对、环境变量坏了——全都直接问 AI，不要自己百度。把下面这段话复制给 WorkBuddy：

📋 提示词模板 ①：环境体检与部署

1
我是一零基础新手，刚在这台 Windows 电脑上装好了 Python、WorkBuddy。
2
请你帮我完成环境检查和部署：
3
1、检查 Python 是否安装成功、版本是多少；
4
2、帮我安装项目需要的依赖库：playwright、beautifulsoup4、openpyxl、requests；
5
3、检测缺什么就装什么，安装过程和结果用大白话告诉我；
6
4、全部完成后，给我一份"环境体检报告"：哪些已就绪、哪些还有问题、下一步该干什么。
7
注意：所有命令你直接帮我执行，不要让我自己敲命令行。

AI 会自动执行检查、安装依赖、报告结果。遇到任何红色报错，直接截图发给它，说”这一步失败了，帮我解决”。

2.4 验证清单#

全部装完后，对着打勾：

• Win+R → cmd → python --version 能显示版本号
• WorkBuddy 打开后能正常对话
• Trae Work 打开后能正常对话
• TraeCode 能打开一个文件夹（随便拖个文件夹进去试试）
• 把提示词模板①发给 AI，它回复”环境就绪”

全打勾 → 进入第 3 章。

3.1 所有案例的共同骨架（看懂这个，你就看懂了全部）#

打开任意一个案例文件夹，结构都长一个样：

1
蓝凌EKP系统登录/
2
├── 蓝凌EKP系统登录_主程序.py      ← 代码主程序（不用碰）
3
├── 蓝凌EKP系统登录配置.ini        ← 遥控器（你主要改这个）
4
├── 启动蓝凌EKP系统主程序.bat      ← 双击运行
5
├── 使用说明书.md / 导航说明书.md   ← 案例自带说明书（遇到问题先翻它）
6
└── 模块/                          ← 功能零件（登录、下载、发通知……AI 负责写）

这就是贯穿所有项目的 “1 个主程序 + 1 个配置文件 + 1 个模块文件夹” 架构。你以后让 AI 给你做新脚本，也统一用这个架子，好维护、好替换。

3.2 每个案例都有的三类”可变东西”#

不管哪个案例，配置文件里无非三类内容：

1. 身份：账号、密码（改成你自己的）；
2. 目标：网址、报表导航路径、要下载什么（改成你公司的系统）；
3. 去处：文件存哪、钉钉机器人地址发到哪个群（改成你的路径和群）。

改造一个案例 = 把这三类东西换成你自己的。 里面具体怎么改，第 4、5 章手把手教。

4.1 第一步：让 AI 帮你读懂案例#

把案例文件夹拖进 WorkBuddy 对话框（或在 Trae Work 里打开该文件夹），发：

📋 提示词模板 ②：案例导读

1
这是公司的一个成功案例项目，我是零基础新手。请你：
2
1、用大白话讲清楚这个项目是干什么的、运行起来会发生什么；
3
2、告诉我哪些文件我可以动（配置、说明），哪些绝对不能动（代码）；
4
3、把配置文件里每一项的含义列成表格，标注"必改 / 可不改 / 别动"；
5
4、告诉我第一次运行前必须改哪几项才能跑起来。
6
不要给我讲代码，只讲使用方法。

AI 会给你一份导读报告。这份报告就是你的作业清单。

4.2 第二步：按清单改配置#

以蓝凌案例为例，需要改的一般是：

1
[登录信息]
2
登录账号 = 改成你的OA账号
3
登录密码 = 改成你的OA密码
4

5
[浏览器配置]
6
浏览器路径 = 改成本机Chrome的路径，例如 （本机路径） Files\Google\Chrome\Application\chrome.exe

改文件的三种方式（任选）：

• 方式 A（推荐新手）：直接在 WorkBuddy 里说”帮我把配置文件里的登录账号改成 xxx、密码改成 xxx”，让 AI 替你改；
• 方式 B：右键 .ini 文件 → 打开方式 → 记事本 → 改完 Ctrl+S 保存；
• 方式 C：用 TraeCode 打开项目，双击 .ini 文件编辑保存（顺便熟悉 TraeCode）。

💡 不知道自己电脑的 Chrome 路径？问 AI：“帮我查一下我电脑上 Chrome 浏览器的安装路径，并帮我写进配置文件。”

4.3 第三步：双击运行#

双击 启动蓝凌EKP系统主程序.bat，会弹出黑色窗口，随后自动打开浏览器自动登录、自动操作。期间不要动鼠标键盘去抢浏览器的控制权。

跑完看两个地方：

• 黑窗口里的文字：出现 [OK]、成功 字样即正常；
• 案例文件夹里的 输出结果/ 目录：导出的文件在里面。

4.4 第四步：跑不起来？把报错喂给 AI#

双击后黑窗口一闪而过，或出现大片红字 = 出错了。这是新手最需要学会的一招：

1. 用”截图 + 复制文字”把黑窗口里的报错信息完整保留（窗口关太快就问 AI：“帮我让 bat 运行完不自动关闭”）；
2. 发给 WorkBuddy，附一句话：

📋 提示词模板 ③：报错求救

1
我运行成功案例"蓝凌EKP系统登录"时报错了，报错信息如下（见截图/如下文字）。
2
请你：1、用大白话告诉我错在哪；2、直接帮我修好；3、告诉我怎么验证修好了。
3
我看不懂代码，修复过程你全权负责，改完哪个文件告诉我就行。

记住这个循环：运行 → 报错 → 贴给 AI → AI 修 → 再运行。 所有的学习都发生在这个循环里，你永远不需要独自面对报错。

5.1 万能提示词公式#

一个好提示词 = 下面六块积木，按顺序搭：

黄金法则：把 AI 当成一个很能干但对你公司一无所知的外包工程师。 它不知道你们系统网址、不知道报表叫什么、不知道存哪——这些你不说，它就只能瞎编。所以④”任务”要写得像给新员工的交接文档：几步、点什么、看到什么算成功。

5.2 实战一：仿”蓝凌EKP”做一个你们公司 OA 的导出脚本#

场景：你们公司也用蓝凌 OA（或类似系统），你想每天自动导出”请假流程”并转 Excel。

操作：把案例文件夹和下面提示词一起发给 WorkBuddy：

📋 提示词模板 ④：改造案例（完整范例，可直接抄改）

1
【角色】你是经验丰富的办公自动化工程师。
2
【背景】我零代码基础，Windows 11，Python 环境已就绪。
3
【素材】附件是公司的成功案例"蓝凌EKP系统登录"，它已能自动登录蓝凌OA、
4
按导航编码批量导出流程、并把HTML转成Excel。请完整参考它的架构和写法。
5
【任务】帮我在案例旁边新建一个同样架构的项目"请假流程导出"，实现：
6
1、自动登录我们公司OA（网址：htt（本机路径））；
7
2、进入"流程中心-请假审批"列表；
8
3、筛选"结束时间 = 前天到今天"的流程；
9
4、逐条打开详情，导出打印模板HTML；
10
5、自动转换成Excel（每个流程一个工作表，再合并一张总表）；
11
6、保存到 （本机路径）。
12
【要求】
13
1、严格沿用成功案例的"1主程序+1配置ini+模块文件夹"架构；
14
2、账号密码、网址、路径全部放进ini配置，代码里不写死；
15
3、变量和文件名用中文命名，关键逻辑加中文注释；
16
4、参考案例的"组件编码"导航写法（ACC/CARD/FLT那些）。
17
【输出】
18
1、生成完整项目文件夹；
19
2、附一份《使用说明书.md》，包含：怎么配置、怎么双击运行、常见问题；
20
3、最后教我第一步先改哪个配置项。

展开收起

要点解析（为什么这么写）：

• “参考它的架构和写法” → AI 会照着成熟套路来，成功率远高于从零写；
• 任务写成 1、2、3、4 步骤 → 每一步都可验证，AI 不容易跑偏；
• “账号密码放 ini 不写死” → 以后换账号你改配置就行，不用再求 AI；
• “附使用说明书” → 逼 AI 留下文档，一个月后你自己都还记得怎么用。

5.3 实战二：仿”每日CRM任务”做自家业务系统导出#

CRM 案例的精髓是”任务步骤文档”：当初开发者就是写了一份《CRM任务步骤.txt》，把”点哪、看到什么算加载完、下载到哪”用大白话+网页元素代码写清楚，AI 照此生成脚本。

你也能照做，三步：

第 1 步：写你自己的”任务步骤”文档（打开目标网页，人肉走一遍流程，边走边记录）：

1
任务：导出我们系统的"客户订单"列表
2
1、打开登录页：http（本机路径），输入账号密码登录；
3
2、登录成功的标志：页面右上角出现"工作台"三个字；
4
3、点击左侧菜单"订单管理"→"全部订单"；
5
4、列表加载完成的标志：表头出现"订单编号"；
6
5、点击右上角"导出"按钮，等待下载完成；
7
6、文件保存到 （本机路径）。

第 2 步：顺手抓”网页元素”给 AI（进阶但极其有效）：在网页上按 F12 → 点左上角小箭头图标 → 点一下你要操作的按钮 → 下方高亮的那行代码右键 → Copy → Copy element，粘贴进步骤文档。案例里那些 <a id="export">导出</a> 就是这么来的。元素给得越准，AI 写的脚本越稳。

第 3 步：发提示词：

📋 提示词模板 ⑤：按任务步骤生成脚本

1
【素材1】成功案例"每日CRM任务"（附件），请参考其架构：
2
1主程序 + N任务模块 + 1个ini配置，登录逻辑、等待元素、静默下载的写法都可复用。
3
【素材2】我的任务步骤文档：（把上面第1步写的内容粘贴在这里）
4
【任务】按步骤文档，为我生成一个同架构的新项目"订单导出"。
5
【要求】
6
1、页面元素的定位优先用我文档里提供的元素，没提供的由你给出合理方案；
7
2、"加载完成的标志"必须做成验证步骤，验证不过就重试并报错，不要瞎点；
8
3、下载用静默下载（不弹保存对话框），路径读ini配置；
9
4、跑完把结果（成功几条/失败原因）推送到钉钉群机器人（机器人地址我之后填）。
10
【输出】完整项目 + 使用说明书 + 首次运行检查清单。

5.4 实战三：仿”BI任务模块化”增删报表下载任务#

BI 案例最好改造，因为加一个下载任务只需改配置、不用改代码。它的配置长这样（脱敏）：

1
[任务-2]
2
名称 = 库存下载
3
导航路径 = 我的分析|协作给我的|Ⅺ-库存|K1-库存数|库存明细
4
导出格式 = Excel
5
目标文件夹 = （本机路径）
6
目标文件名 = 库存明细.xlsx
7
启用 = True

你要做的就是在 BI 平台里人肉点一遍你要的报表，把”依次点过的菜单名”用 | 串起来填进 导航路径。

配套提示词（跑通前让 AI 把关）：

📋 提示词模板 ⑥：新增/修改下载任务

1
这是"BI任务模块化"项目的配置文件。我想新增一个下载任务：
2
报表位置：我依次点击了「分析 → 协作给我的 → 3-销售 → 每日销售达成」；
3
导出 Excel，保存到 （本机路径），文件名叫"每日销售达成.xlsx"。
4
请你：1、帮我把新任务写进配置文件；2、检查我的导航路径写法是否符合
5
该项目的格式要求；3、告诉我改完后怎么验证任务跑通了。

5.5 提示词的迭代心法：一次只改一件事#

AI 第一次生成的脚本很少一次完美，高手和新手的区别不在第一句提示词，而在后续怎么”追问”。心法三条：

1. 小步快跑：一次只提一个改动。“把下载路径改成 E 盘” ✅；“顺便把下载、汇总、通知、定时全改了” ❌——改动越多，AI 越容易顾此失彼。
2. 拿事实说话：不说”跑得不对”，要说”我双击运行后，浏览器打开登录页就没动了，黑窗口最后一行显示：等待元素超时（附截图）“。现象+报错原文，比任何形容词都有用。
3. 改完就测：AI 说改好了，你立刻双击跑一遍验证，别攒一堆改动再测——出了问题分不清是哪次改坏的。

5.6 改造时的边界与禁忌#

• ✅ 可以让 AI 参考案例的结构、写法、套路；
• ❌ 不要让 AI 直接在成功案例文件夹里大改（先复制一份再改，原案例留底）；
• ❌ 账号密码不要出现在提示词正文和给 AI 的截图里，让 AI”留空位”，你自己填进 ini；
• ❌ 不要一开始就挑战最复杂的场景。正确路径：先跑通登录 → 再跑通一个下载 → 再加筛选条件 → 最后加钉钉通知。每通一步，让 AI 确认一步。

6.1 四个基本动作#

1. 打开项目：TraeCode → 文件 → 打开文件夹 → 选案例文件夹。左侧出现文件树。
2. 看文件：双击任何文件打开。.ini、.md、.txt 都能直接看；.py 看不懂没关系，要用的是下一步。
3. 改文件：直接编辑保存（改 ini 主要用这个）。
4. 运行：菜单”终端”→“新建终端”，输入 python 主程序文件名.py 回车；或直接在文件管理器双击 .bat。报错信息会显示在下方终端里，不会一闪而过——这是 TraeCode 比双击 bat 好用的地方。

6.2 报错三看（不用懂代码也能定位问题）#

终端里一片红字时，只看三处：

然后把这三样原封不动复制给 AI（提示词模板③），加一句”请直接帮我修好”。 你的任务只是”搬运工”，诊断和修理是 AI 的事。

6.3 新手常见的三个”假故障”#

7.1 第一步：建群机器人，拿到 Webhook 地址#

1. 打开你要接收通知的钉钉群 → 群设置 → 机器人 → 添加机器人 → 选 自定义（通过 Webhook 接入）；
2. 名字随便取（如”报表小助手”），安全设置建议勾”自定义关键词”，填一个词如 报表；
3. 完成后会给你一个 Webhook 地址（`http（本机路径） 长这样）——复制保存，这就是机器人的”门牌号”。

7.2 第二步：把地址填进项目配置#

所有案例的 ini 里都有这一段：

1
[机器人配置]
2
报送机器人 = http（本机路径）
3
信息格式 = JSON

把 Webhook 粘贴进去保存即可。注意：若你的机器人设了关键词，让 AI 确保通知文案里包含该关键词（比如都带”报表”二字），否则消息会被钉钉拒收。改完可以让 AI 发条测试消息验证：

📋 提示词模板 ⑦：测试钉钉通知

1
我已把钉钉机器人的 Webhook 地址填进配置文件（关键词是"报表"）。
2
请帮我：1、检查配置格式对不对；2、发送一条测试消息到这个机器人；
3
3、如果群里没收到，帮我按"关键词/网络/地址"三个方向排查。

7.3 第三步：WorkBuddy 连接钉钉（MCP 连接器）#

这一步让 WorkBuddy 本身能直接操作钉钉（发消息、读写 AI 表格、查审批……），是”AI 表格自动流”的基础：

1. WorkBuddy → 设置/连接器 → 找到 钉钉 → 点击连接；
2. 弹出钉钉授权页面 → 用公司账号登录 → 点同意授权；
3. 回到 WorkBuddy 显示”已连接”即可。

连上之后你就可以说人话直接指挥，例如：

“帮我把 （本机路径） 里的数据整理成摘要，发到’运营数据群’。” “把今天三个下载任务的结果汇总成一张表，写进钉钉 AI 表格《每日报数看板》。”

7.4 AI 表格自动流：让结果沉淀成看板#

思路：脚本负责”产出文件”，WorkBuddy+钉钉 AI 表格负责”汇总展示”。典型玩法：

1. 在钉钉里建一张 AI 表格（如《每日报数看板》），列头设好：日期、任务名、状态、文件链接；
2. 让 WorkBuddy 记住这套格式，之后每次跑完脚本说一句”按老规矩把今天的运行结果写进看板”。

配套提示词：

📋 提示词模板 ⑧：结果自动入表

1
我有一个"BI任务模块化"项目，每天自动下载多张报表到共享盘，
2
并在ini里留有运行日志。请你帮我建立一条固定流程：
3
每次我发送"今日汇总"四个字时，你自动：
4
1、读取今天的运行日志和下载结果；
5
2、整理成四列：日期、任务名称、成功/失败、文件位置；
6
3、通过钉钉连接器写进 AI 表格《每日报数看板》；
7
4、有失败任务时，在群里额外@我并附报错摘要。

9.1 每天的动作#

9.2 出问题时的标准排障流程#

1
看钉钉通知/启动错误日志.txt 里的报错
2
    ↓ 原封不动复制报错
3
发给 AI（提示词模板③）："帮我修好，修完告诉我怎么验证"
4
    ↓ AI 修复
5
双击 bat / TraeCode 运行验证
6
    ↓ 成功
7
结束（把这次的报错和修法记下来，下次秒懂）

原则：报错不过夜、修复必验证、现象说清楚。

9.3 改配置的四条军规#

1. 改前先备份：复制一份 ini 改名为 配置_备份_日期.ini，改砸了好回滚；
2. 只改等号右边，左边字段名和 [中括号] 节名不要动；
3. 用 TraeCode 或 VS Code 改，别用 Word/WPS（会破坏格式）；保存编码选 UTF-8；
4. 一次只改一处，改完立刻试跑。

9.4 让 AI 改脚本后的验证流程#

1. AI 说改好 → 问它”这次改动会影响哪些功能？”；
2. 双击运行一次完整流程；
3. 核对三样：输出文件新增了没？文件内容对不对？钉钉通知到了没？
4. 三样都 OK，这次改动才算落地。

语法高亮#

语法高亮

1
console.log('此代码有语法高亮!')

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

编辑器和终端框架#

编辑器和终端框架

1
console.log('标题属性示例')

1
<div>文件名注释示例</div>

1
echo "此终端框架没有标题"

1
Write-Output "这个有标题!"

1
echo "看，没有框架!"

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

1
console.log('单词 yes 和 yep 将被标记。')

1
echo "Test" > /home/test.txt

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

基本用法#

1
::: code-group labels=[code.js, code.py, code.html]
2

3
```js
4
export function greet(name) {
5
  return `Hello, ${name}!`;
6
}
7
```
8

9
```py
10
def greet(name):
11
    return f"Hello, {name}!"
12
```
13

14
```html
15
<p>Hello, world!</p>
16
```
17

18
:::

渲染效果：

1
export function greet(name) {
2
  return `Hello, ${name}!`;
3
}

1
def greet(name):
2
    return f"Hello, {name}!"

1
<p>Hello, world!</p>

标签中使用 Emoji#

标签支持 emoji 短代码，构建时会自动转换成 emoji：

1
::: code-group labels=[:package: npm, :package: pnpm, :yarn: yarn]

1
npm create astro@latest

1
pnpm create astro@latest

1
yarn create astro

与其他代码块特性组合#

组内仍是普通的 Expressive Code 代码块，标题、行号、行标记、折叠、终端框架等特性都可以照常使用。

1
export default {
2
  theme: "firefly",
3
  codeGroup: true,
4
};

1
pnpm build && pnpm preview

3 collapsed lines
1
// 这三行默认折叠
2
import { a } from "a";
3
import { b } from "b";
4

5
console.log(a, b);

不止是代码块#

标签页内可以放任意内容，例如文字、列表或图片：

在提醒框内使用（MDX 组件）#

::: code-group 和 ::: tip 等 Docusaurus 风格提醒框都使用 ::: 容器语法，而 micromark-directive 规定父子容器的冒号数必须不同，因此 ::: code-group 无法嵌套在 ::: tip 等提醒框内（整块会失效）。

这种情况改用 MDX 组件 TabGroup：MDX 组件不经过 ::: 指令解析，在提醒框内外都能正常使用，也方便日后扩展更多 UI 组件。把文章后缀改为 .mdx，从统一入口 @/components/firefly-mdx 引入（可一次引入多个组件）：

1
import { TabGroup } from "@/components/firefly-mdx";
2

3
:::tip
4

5
<TabGroup labels={["test.js", "test.py"]} client:load>
6
  ```js
7
  console.log(1)
8
  ```
9

10
  ```py
11
  print("hello world")
12
  ```
13
</TabGroup>
14

15
:::

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

右侧边栏 (position: “right”)#

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
};

1.2 双侧边栏模式 (position: “both”)#

布局结构#

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

2.1 列表模式 (defaultMode: “list”)#

列表布局结构#

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list",    // 列表模式
4
    coverPosition: "right", // 封面图位置："right" 右侧，"left" 左侧
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    grid: {
5
      masonry: true,      // 开启瀑布流
6
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
7
    },
8
  },
9
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

• 智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
• 消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
• 自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
• 配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

第一种：slug#

slug 写法在 Obsidian 中不支持，slug 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 slug，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。

第二种：文件路径（推荐）#

文件路径写法需要改 Obsidian 设置，在 设置 → 文件与链接 → 链接 → 内部链接类型 中选择基于仓库根目录的绝对路径，Obsidian 插入的链接才会带上目录：

1
[[guide/firefly-layout-system|firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

2026-09-12博客指南#Firefly#布局#博客#指南

因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。

上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。

内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。

第三种：裸文件名#

「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：

1
[[firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

2026-09-12博客指南#Firefly#布局#博客#指南

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸

矩阵 (Matrices)#

极限与求和 (Limits and Sums)#

麦克斯韦方程组 (Maxwell’s Equations)#

化学方程式 (Chemical Equations)#

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::