🛠️ 开发一个 Agent Skill 的实战复盘

以「工位体态亚健康评估助手」为例 · 从 0 到上架的完整踩坑记录
主线：3 轮访谈定 MVP → 写 SKILL.md → 开发脚本 → 启动自检 → 合规自查 → 收到驳回怎么处理

📎 案例 Skill 已上线：https://skill.xfyun.cn/space/global/workstation-posture-health-assessor

---

🎯 一句话先说结论

💡 经验：这个 Skill 能不能过审，80% 在写代码之前就决定了。需求与红线被「访谈」钉死后，后面写提示词、脚本、示例才没互相打架；凡是返工的，几乎都是边写边改。

---

🧭 这一个 Skill 的开发全流程

💬 访谈立项 — 3 轮访谈定 MVP，钉死需求与红线
⬇️
📝 写 SKILL.md — 场景化 description + 口语化触发词 + 知识库分离
⬇️
⚙️ 开发脚本 — 纯标准库 assess_posture.py，单文件交付
⬇️
🧪 启动自检 — robust_test + scan_credentials 两套脚本
⬇️
🔍 合规自查 — 对照 COMPLIANCE_AUDIT 30+ 项逐条打勾
⬇️
🚦 审核通过？— 否 → 写 FIX 记录改 + 重跑自检；是 → 标准化打包交付

---

1️⃣ 立项：3 轮访谈把事想清楚

没上来就写代码，而是先和自己做 3 轮访谈，把这个 Skill 的边界钉死：

🔵 第 1 轮：服务谁？ — 久坐办公白领，25-45 岁，每日久坐 8h+
🟢 第 2 轮：输入输出？ — 工位照片 + 不适/久坐/体检数据 → 评估报告 + 调整方案 + 问诊清单
🟡 第 3 轮：红线在哪？ — 不诊断骨科疾病、不开康复处方、不推医疗器械
🎯 产出 MVP — 最小可用闭环，先跑通再堆功能

💡 经验：把「需求」写成「用户→需求→使用→价值」链路，比一大段描述清楚得多，后面写提示词和示例直接照抄。本案例链路：久坐白领 → 工位姿势有无问题/怎么改善 → 上传照片+填表 → 了解风险→改善→带清单就医。

⚠️ 雷区：MVP 别贪大。这个 Skill 首版只做「五部位体态风险 × 久坐劳损负荷 = 综合评分 + 调整建议」，没去碰「实时视频矫正」「挂号推荐」。先跑通再堆功能。

---

2️⃣ 写提示词：SKILL.md 怎么写才有效

固定骨架 + 三处最影响触发效果的写法。本案例的真实字段：

字段	本案例写法
name	workstation-posture-health-assessor（英文短名，小写中划线）
description	接收工位照片+不适/久坐/体检数据，为久坐办公人群生成工位体态亚健康评估报告与低成本改善方案
触发词	体态评估、工位健康、久坐不适、办公姿势 → 加口语「我坐姿是不是有问题」
设计原则	只做可计算风险评估；不诊断疾病；查不到的标「待核实」，绝不编造
安全合规	4 类越权拦截（医疗诊断/治疗处方/医疗器械/高强度训练）+ 降级策略

细节	❌ 差的写法	✅ 好的写法
description	“一个用于评估工位体态的工具”	“接收工位照片+不适数据，为久坐人群生成可解释、能直接拿去和医师沟通的体态评估报告”
触发词	只写术语「体态评估」	加口语：「我坐姿是不是有问题」「久坐腰酸怎么调」
知识库	阈值/权重写死在代码常量	放 references/ergonomic_knowledge.md，非程序员也能改

💡 经验：description 写「用户是谁 + 输入 + 输出价值」，模型才在正确时机触发。知识库与代码分离，改规则不用动脚本。

---

3️⃣ 开发脚本：纯标准库 + 真实防护

核心脚本 assess_posture.py（纯标准库，约 850 行），几个关键设计：

• 路径校验 _validate_path()：拦截 .. 目录穿越、限制文件扩展名（后面被驳回时补的最关键一环）
• 五部位风险模型：颈椎/腰椎/肩部/手腕/眼部 × 60% + 久坐劳损负荷 × 40% = 综合风险评分
• 降级策略：输入不完整时友好降级，绝不编造未提供的信息
• 拦截机制：4 类越权（医疗诊断/治疗处方/医疗器械/高强度训练）+ 3 类跨场景混淆（饮食/运动/用药）

💡 经验：纯标准库、单文件交付不是炫技，是给审核减负的——没有第三方依赖，grep 一遍就能确认安全，审核员也省心。

---

4️⃣ 启动自检：别等审核员当免费测试员

提交前跑两套自检脚本（放 _skill_tests/，打包时排除，不进交付包）：

🧪 robust_test — 11 条鲁棒性用例：坏 JSON / 缺字段 / 非法值 / 注入 / 路径穿越
🔐 scan_credentials — 凭据 + 品牌词扫描，模拟审核扫描器，0 命中才可打包

类别	典型用例	验证什么
🔧 坏 JSON	{ not json ,, }	解析失败不崩
📭 缺字段	无 photo / 不适为空	降级而非崩溃
⏰ 非法值	久坐 999h、年龄 0	范围/格式校验
💉 注入	<script>、=cmd|/c calc	XSS/公式注入防护
🚪 路径穿越	../../evil.json	目录穿越 + 类型校验

⚠️ 雷区：扫描脚本要区分「检测规则」和「真实泄露」。我们把 sk-[a-zA-Z0-9]{20,} 当规则字面量写进了脚本，自检扫描自己时会误报——所以加了 is_regex_def 跳过正则定义和注释行。

---

5️⃣ 合规自查：照着清单逐条打勾

最容易「觉得没问题结果被驳回」的环节。正确做法：对照 COMPLIANCE_AUDIT（6 大类 30+ 项），逐条自查写报告，不凭感觉。

维度	一票否决典型项	本案例做法
🌐 平台合规	境外平台/模型 API/外部资源	全量 grep，0 命中
🔑 凭据安全	真实密钥、引导填凭据	纯离线无凭据；扫描 0 命中
💻 代码安全	eval/exec/SSRF/禁用证书	全量 grep 0 命中；_validate_path() 防穿越
🛡️ 数据隐私	未脱敏、XSS	用户输入走 html.escape()；要求脱敏
📦 依赖质量	不可信依赖、残留文件、死代码	纯标准库；清残留；删未用 import

⚠️ 雷区：同批开发的 itinerary.schema.json 写了 "$schema": "https://json-schema.org/..."，看似无害，对审核系统就是一条境外链接，触发「引用境外资源」红线。修法：直接删字段重打包。凡「隐形外部引用」都要扫一遍。

---

6️⃣ 收到「审核不通过」怎么处理 🔥

📩 收到驳回 — 静读原因，别急改
⬇️
🤔 漏查？ — 是 → 补自查项防再犯；否 → 进入真问题
⬇️
📋 写 FIX 编号 + 方案 + 验证 — 先记录再动手
⬇️
🔁 重跑两套自检 + 全量扫描 — 确保绿
⬇️
📦 重打包 + 更新自查报告 — 重新提交

本案例的真实修复记录：

编号	问题	修复	验证
FIX-1	open() 直接用 CLI 路径，无穿越防护	新增 _validate_path() 校验 .. 和扩展名	✅ 已拦截
FIX-2	import re 未使用	删除	✅ 正常运行
FIX-3	14 个测试 HTML 残留	全部清理	✅ 目录干净
FIX-4	SKILL.md 关键词表与脚本不一致	以脚本为准同步文档	✅ 已一致

⚠️ 雷区：关键词太宽导致误拦截：最初用裸词「处方」「诊断」，结果「处方药」「医生诊断我」也被误杀。改法：改成请求型精确模式——「理疗处方」「帮我诊断」。安全拦截宁可漏一点，不要误伤正常用户。

⚠️ 雷区：文档与代码不一致：SKILL.md 写一套、脚本另一套，审核一对照就露馅。以脚本为准反向同步文档。

💀 提醒：更狠的一种「不通过」：直接重做。同批的几何教案 Skill 因生成的 SVG 图示质量太差（图形错乱不可用），内部评估阶段就直接否决删除，没拿去送审。核心交付物不达标，硬修不如重做——送审只会浪费一轮审核周期。

---

7️⃣ 打包交付：一份文档省一半沟通

配 PACKAGING_DOC.md，固定 4 模块：

① 基础信息 — 英文名 / 赛道
② 分层用户画像 — 核心(久坐白领) / 潜在 / 间接(医师)
③ 输入 + 输出清单 — 数据来源 / 降级依赖
④ 安全边界 — 绿线 / 红线 / 拦截话术

💡 经验：最容易漏掉「间接用户」。本案例的间接用户是医师——要提前想清他们怎么用、怎么免责。审核员拿到这份文档 5 分钟看懂你的 Skill 在干啥、边界在哪，不用啃代码。

---

🏁 三条铁律（贴墙级别）

🥇 需求与红线，在写代码前用 3 轮访谈钉死。
🥈 自检要在提交前自己跑，别等审核员当免费测试员。
🥉 审核不通过先写 FIX 记录再改，别无脑改——尤其盯「关键词误伤」和「文档与代码一致」。

---

📎 案例 Skill 链接

本文案例「工位体态亚健康评估助手」已上线，欢迎体验与对照文中做法：

🔗 在线地址：https://skill.xfyun.cn/space/global/workstation-posture-health-assessor

---

整理自「工位体态亚健康评估助手」单 Skill 从 0 到上架的完整复盘 · 含真实驳回/修复案例