Datawhale AI 夏令营 学习笔记 & 讯飞 Skill 参赛踩坑实录（整合版）

面向：参加讯飞 AI 开发者大赛 Skill 类赛题，要写参赛作品说明 / Skill 规范文件（SKILL.md）的同学。
本文本身是 Markdown 文件，可直接当示例对照看。
整合来源：① 今天「讯飞 AI 开发者大赛 Skill 类赛题」整轮实战（采访→定义→生成→自检→打包）② 真实审核反馈（多源表格批量清洗合并助手因公式注入被拒）。

---

一、Markdown 基础创建

1. 创建文件

• 新建文本文件，扩展名改为 .md（如 notes.md / SKILL.md）。
• 纯文本编辑器即可（VS Code、记事本、Typora），不需要特殊软件。
• 预览：VS Code 右上角「打开预览」，或拖进浏览器（需插件/支持 md 的查看器）。

2. 标题（# 数量 = 层级）

# 一级标题（最大）
## 二级标题
### 三级标题

• # 后必须有一个空格；建议一篇只一个一级标题。

3. 强调（粗体 / 斜体）

**加粗**   *斜体*   ***加粗斜体***

• 用英文星号 *，不是中文 ＊。

4. 列表

- 无序项 A
- 无序项 B
  - 子项（前加 2 空格缩进）
1. 有序项一
2. 有序项二

• 无序用 - / * / +；有序用 数字.；符号后必须空格，缩进用空格不用 Tab。

5. 代码

• 行内：反引号 ` 包裹，如 `print("hi")`。
• 代码块：三个反引号 ```包裹并标注语言：

def hi():
    print("hello")

• 踩雷点：写完一定要用三个反引号闭合，否则后面全文变代码。

6. 表格

| 列1 | 列2 |
| --- | --- |
| A   | B   |

• 第二行 | --- | --- | 是分隔行，不能省；列数要一致。

7. 链接与图片

[显示文字](https://example.com)
![图片描述](path/to/img.png)

• 链接 []()，图片多一个 !；路径用相对路径更稳。

8. 引用与分割线

> 这是引用，常用于提示/备注。

---   <!-- 三个减号独占一行 = 分割线 -->

9. 任务列表

- [x] 已完成
- [ ] 待办

10. Frontmatter（YAML 头，用于 SKILL.md）

用 --- 上下包裹，放在文件最开头：

---
name: 多源表格批量清洗合并助手
description: 输入多个Excel/CSV文件夹，清洗去重合并为merged.xlsx；适用于汇总各班成绩单的场景；触发词：合并表格、汇总成绩单、去重合并数据
---

• --- 必须独占一行；字段名后冒号 : 紧跟一个空格。
• Agent Skills 标准里 frontmatter 只保留 name + description 两个必填字段，不要多加。

---

二、讯飞 Skill 开发全流程 SOP（结合今天实战）

今天我们用「教练 + 产品经理 + 创建助手」连续流程做了两个 Skill，沉淀出可复用 SOP：

1. 先对齐赛题四大方向

方向	覆盖赛题举例
一、智能文档解析	金融材料解析、医疗理解、多源检索分析
二、智能分析与决策	数据智能分析、人才匹配、代码辅助
三、智能生成与创作	全场景内容创作、电商内容、政务公文、办公协同
四、智能服务与陪伴	智慧生活助理、教育智能辅助与个性化学习

2. 3 轮采访法（≤3 轮、每轮 ≤3 问，信息够就停止追问）

• 第1轮：身份 → 最重复/耗时/易错的工作 → 交付结果。
• 第2轮：补缺口——赛题类别 / 用户输入 / 期望输出。
• 第3轮：验收标准——什么算成功 / 什么不能编造 / 有无真实样例。

3. 收敛成「需求定义卡」（12 字段）

名称、目标用户、赛题类别、覆盖赛题、关键词价值点、真实场景、用户输入、Skill 输出、标准流程、触发词、验收标准、不该做什么。

4. 生成 SKILL.md

• 开头 --- 包裹 frontmatter，仅 name + description。
• 正文写清：角色定位、何时使用、范式方法论、输入处理、输出模板、工作流程、约束、示例。
• 可附带 references/（范式详解）+ assets/（样例）让 Skill 更厚实。

5. name 命名公式

细分场景 + 核心动作 + 定位，中文 8–15 字具象，禁止泛化（如"文档助手"“办公助手”）、禁止版本号/英文后缀。

• 例：学生PPT结构化大纲生成器、学生假期出游行程规划助手、多源表格批量清洗合并助手。

6. description 三段式（顺序不可逆，分号分隔）

核心能力 + 适用场景 + 触发词

• 核心能力段：写清「输入类型 + 处理动作 + 输出产物」，精确到格式。
• 适用场景段：讲清"何时加载"并隐含能力边界。
• 触发词段：≥6 个，书面+口语混合，必须是用户真会说的原话。

7. 自测 + 打包

• 无真实样例 → 先造最小模拟样例跑通，显式提醒"请替换为真实样例"。
• 打包（PowerShell，路径含特殊字符用双引号）：

Compress-Archive -Path "skill-folder/*" -DestinationPath "skill-folder.zip" -Force

• 今日产物：student-ppt-outline-generator.zip（智能生成与创作）、student-trip-planner.zip（智能服务与陪伴）。

---

三、踩雷实战（整合：原雷 1–10 + 今日新增）

雷 1：Frontmatter 的 --- 不干净

• 错误：--- 前后多空格、写成 -- / ----，YAML 直接解析失败。
• 正确：正好三个减号，独占一行，文件第一行就是 ---。

雷 2：YAML 冒号后没空格

# 错误
name:多源表格批量清洗合并助手
# 正确
name: 多源表格批量清洗合并助手

• 缺空格会导致整个 frontmatter 报错，连带「请求参数不合法」。

雷 3：中英文标点混用

• Markdown 符号（# * - > | 等）必须英文半角。
• 常见事故：用中文 － 当分割线、用中文引号 " 包路径，渲染器全不认。

雷 4：提交「请求参数不合法」的 3 个真凶（按概率）

1. 作品名称 ≠ frontmatter 的 name：表单"作品名称"必须一字不差等于 name（含汉字、不带引号/空格/版本号）。
2. 包里混入了非允许文件：平台通常只允许 .md + .py。把样例 class1.csv 一起打进 ZIP 会被拒。
3. ZIP 套了多余文件夹 / 体积不符：要求解压后 SKILL.md 在根目录（zip/SKILL.md），不要多套一层 zip/skill/...。

雷 5：写出数据时的「公式注入」（安全坑，今日已真实触发审核不通过，并已修复）

• 真实案例：多源表格批量清洗合并助手 本次审核暂不能通过——脚本在 clean_merge.py:149、clean_merge.py:168 把多份 Excel/CSV 内容直接导出到 merged.xlsx 和 summary.xlsx，却没有对 = + - @ 开头的单元格做中和，存在公式注入风险。
• 原理：单元格以 = + - @ 开头（如备注写成 =HYPERLINK(...) 或 =cmd|...，甚至看似无害的 =2+2），Excel 会当公式执行，可造成数据外泄/执行风险。
• 错误修复（踩过的坑）：只在写入前给危险字符串加前导单引号 ' 是不够的——pandas/openpyxl 写出链路仍可能把以 = 开头的内容再次识别为公式。审核实测：=2+2 经"写前加前缀"后，生成的 merged.xlsx 里该单元格仍是公式单元格。
• 正确修复（两层兜底）：
  1. 写前：neutralize() 给 = + - @ 开头的用户可控字符串加前导单引号 '（第一道防线）。
  2. 写后：用 openpyxl 重新打开已写出的 xlsx，对触发符单元格显式设置 quotePrefix=True + number_format='@'（文本格式），彻底强制按文本存储：

FORMULA_TRIGGERS = ("=", "+", "-", "@")
def neutralize(v):
    if isinstance(v, str) and v[:1] in FORMULA_TRIGGERS:
        return "'" + v          # 写前第一道防线
    return v

def force_text_cells(path):
    wb = load_workbook(path)
    for ws in wb.worksheets:
        for row in ws.iter_rows():
            for cell in row:
                raw = cell.value if isinstance(cell.value, str) else ""
                if raw[:1] == "'":
                    raw = raw[1:]
                if cell.data_type == "f" or raw[:1] in FORMULA_TRIGGERS:
                    cell.value = "'" + raw
                    cell.quotePrefix = True   # 带引号文本前缀
                    cell.number_format = "@"  # 强制文本格式
    wb.save(path)
# to_excel 之后调用 force_text_cells(merged_path) / force_text_cells(summary_path)

• 验证技巧：别只看 pandas 读回的值，必须直接检查 xlsx 底层 XML 是否含 <f> 公式节点才算数。已补 regression_test.py：构造含 =2+2、+3、-4、@SUM(A1) 的 CSV，跑完整 CLI，断言无 data_type=='f' 单元格、危险单元格 quotePrefix=True、底层 XML 无 <f>——实测 PASS。

雷 6：代码块忘了闭合

• 写一半去忙，回来发现后面全成代码块——最高频「排版炸了」。
• 习惯：先写开头 立刻写结尾 ，再填中间。

雷 7：列表缩进用 Tab

• 不同渲染器对 Tab 支持不一，子列表可能不生效。统一用空格（通常 2 个）缩进。

雷 8：表格列数对不齐

• 分隔行与内容行列数必须相同；少了错位、多了被忽略。
• 长表格先 Excel 排好再粘成 md（可用在线互转工具）。

雷 9：特殊字符未转义

• 显示字面 # * ` \ | 可在前加 \：

\# 这不是标题，是井号

• 表格单元格里写 | 要转义成 \|，否则被当列分隔。

雷 10：改了文件但预览没刷新

• 编辑器缓存 / 预览未自动刷新，误以为改动没生效。手动 Ctrl+S 并重开预览确认。

雷 11：采访问题太开放 / 漏关键输入维度

• 现象：第1轮问"最耗时工作"若不加约束会收到一句"很多"；或像出游规划那轮用户没选"天数"，Skill 跑起来缺主语。
• 对策：每问绑死"服务于选方向/定场景/定输入输出"；在 SKILL.md 写兜底（如"天数缺失则主动询问或默认 3 天"）。

雷 12：description 模糊 / name 泛化

• 现象：写"处理各类文档"让 AI 不知何时加载、跨场景误触发；name 用"智能办公助手 v2"直接不及格。
• 对策：description 写死输入/输出格式 + 能力边界；name 用 8–15 字具象命名公式。

雷 13：编造实时信息 / 无样例空口说"已测试"

• 现象：出游规划把票价、开放时间写成确定值；或没样例就宣称跑通，评委一问露馅。
• 对策：实时/客观信息一律标"以官方为准/待核实"；先造最小模拟样例跑通并提醒替换。

雷 14：路径含特殊字符打包报错

• 现象：用户名 k'k 带单引号，PowerShell 路径易出错。
• 对策：路径用双引号包裹（单引号在双引号内为字面量），正常执行。

雷 15：教育类 Skill 未确认就硬编

• 现象：把"13 节课"默认成某门内置课，结果跑偏。
• 对策：先问清「课程来源（用户提供/内置/AI生成）/ 输出形态（对话+每课报告·仅对话·仅报告）/ 真实样例」再写。

---

四、快速自检清单（提交前过一遍）

Markdown / Frontmatter

• SKILL.md 开头是干净 --- + name + description + 干净 ---
• YAML 冒号后有空格；--- 独占一行
• 所有 Markdown 符号为英文半角
• 代码块全部闭合并标注语言
• 表格分隔行存在、列数一致

Skill 规范

• name 8–15 字具象，无泛化/版本号/英文后缀，且 = 表单"作品名称"
• description 三段式（核心能力+适用场景+触发词），触发词 ≥6 且真实
• 包内只有 .md 和 .py，无 CSV/图片/子文件夹
• ZIP 解压后 SKILL.md 在根目录（不套多余层）
• 若导出表格，已防公式注入：写前 neutralize() 中和 = + - @ 前缀 且 写后 force_text_cells() 强制文本化（quotePrefix + 文本格式），底层 XML 无 <f> 公式节点（用 regression_test.py 覆盖 = + - @ 验证 PASS）
• 无真实样例时已用最小模拟样例自测，并提醒替换

流程 / 内容

• 采访已收敛到单一具体场景与明确输入输出
• 验收标准可量化（如动线合理/预算可控/细节齐全/可照做）
• 不编造实时/客观信息，缺失标"待核实"
• 关键输入维度缺失已在 SKILL.md 写兜底逻辑

---