QuoteApp Skills技能设计理念与技巧总结

---

一、技能整体架构

1.1 目录结构规范

skill-name/
├── SKILL.md              # 技能主文件（入口定义 + 完整流程文档）
├── scripts/              # 可执行脚本（核心能力载体）
│   ├── run_quote.py      # 主功能脚本（CLI 调用入口）
│   └── launch_quoteapp.py # 辅助脚本（GUI/CLI 启动器）
└── references/           # 参考资料库（只读知识）
    └── materials.md      # 材料/格式/辅材等静态数据

设计要点：

• SKILL.md 是唯一入口：AI 只需读取一个文件即可理解全部技能逻辑
• scripts/ 承载执行逻辑：将复杂操作封装为可调用脚本，AI 无需自己拼凑命令
• references/ 提供知识底座：结构化参考数据供 AI 按需查阅，减少幻觉

---

1.2 SKILL.md 结构解剖

SKILL.md 采用 YAML Frontmatter + Markdown 正文 的双层结构：

---
name: <技能名>
description: >
  <多行描述：适用对象 + 触发场景 + 触发关键词>
---

# 技能标题

## 概述 → Step 0 → Step 1A/1B → Step 2 → 附录

部分	作用	设计理念
YAML Frontmatter	机器可读的元数据	供技能系统自动索引、匹配、触发
description 字段	精确定义触发条件	关键词穷举 + 场景枚举 = 精准触发
正文 Markdown	AI 执行的完整指令	分步骤、有条件分支、带示例

---

二、核心设计理念

2.1 理念一：意图识别先行，路由分派

模式：消息 → 意图分类 → 置信度评估 → 分支路由

用户消息
  ↓
Step 0: 意图识别（6大一级意图 + 二级意图）
  ↓
置信度判断：
  ≥ 0.8 → 直接路由
  0.6-0.79 → 路由 + 确认
  < 0.6 → 询问用户
  ↓
Step 1A / 1B / 2 ... 分支执行

技巧：

• 一级意图用表格定义（意图 | 典型输入 | 路由目标），一目了然
• 二级意图做精细分类，避免误路由
• 置信度阈值分级是核心设计——既不过度确认（≥0.8直接执行），也不盲目猜测（<0.6必须问）

2.2 理念二：内外双版，权限分离

两个技能共享同一底层能力（QuoteApp），但面向不同用户群体：

维度	quote-app（外部版）	quote-app-inner（内部版）
适用对象	外部客户（微信 ClawBot）	内部员工（企业微信 AIBot）
成本明细	隐藏，仅展示总价+材料+加工	完整13步拆解
利润率/管销费	不可见	完全可见+可讨论
供应商信息	礼貌拒绝	可查询
批量处理	不支持	支持 --batch
敏感问题	严格拒绝	引导至对应内部系统
输出格式	表格+推荐理由	完整成本明细+碳排放

技巧：

• 用同一套脚本，靠 SKILL.md 层面的指令控制展示粒度
• 内部版在 SKILL.md 中显式声明每类信息的可见性（✅/❌），避免 AI 猜测
• 外部版把"拒绝话术"写死，内部版把"引导话术"写活

2.3 理念三：脚本封装，CLI 驱动

核心原则：AI 不直接操作数据库/文件系统，而是通过 CLI 脚本间接执行。

AI 识别意图 → 收集参数 → 构造 CLI 命令 → 执行脚本 → 解读输出

技巧：

• 三套调用方式分层：Python 脚本（推荐）> exe CLI（备用）> GUI（手动）
• 脚本内部处理所有复杂逻辑（数据库连接、模块导入、异常处理），AI 只需拼参数
• 受管 Python 解释器路径写死在 SKILL.md 中，避免环境问题

2.4 理念四：参数设计——必要 vs 可选，显式默认值

参数类型	设计方式	示例
必要参数	标注 （必填），缺值时 AI 主动询问	--file
可选参数	写明默认值，未提供则自动填入	--material-code（默认铝6061）
探索性参数	提供 --list-* 子命令	--list-materials、--list-aux

技巧：

• 参数按功能分组注释（工件信息/报价单头部/费率参数/输出参数）
• 每个参数都有中文说明和默认值，AI 不需要猜
• --json-result 参数用于自动化对接，AI 可直接解析结构化输出

2.5 理念五：错误处理穷举，分级应对

错误处理表覆盖所有已知失败场景：

错误类型	处理方式
程序不存在	检查路径
材料名称不存在	运行 --list-materials
图纸格式不支持	告知支持格式
DWG 无法解析	需配置 ODA
环境初始化失败	检查数据库锁定
PDF 识别精度低	建议改用 STEP

技巧：

• 每种错误都有具体的恢复动作，不是泛泛的"请重试"
• AI 看到错误输出后直接查表操作，无需自行判断

---

三、SKILL.md 写作技巧

3.1 Frontmatter description 的写法

description: >
  适用对象：XXX（通过 XXX 渠道接入）。
  触发场景：(1) ... (2) ... (3) ... (4) ...
  触发关键词："关键词1"、"关键词2"、
  "关键词3"、"关键词4"、
  # 分类注释 ↓
  "关键词5"、"关键词6"、...
  以及任何携带图纸文件（.xxx/.yyy）的XXX意图。

关键技巧：

1. 适用对象：明确告诉系统"这个技能给谁用"
2. 触发场景用编号枚举：(1)(2)(3)(4)… 清晰不遗漏
3. 触发关键词穷举：把所有可能的用户表述都列出来
4. 分类注释：用 # 分类注释 ↓ 把关键词分组，提高可读性
5. 兜底条件：最后一行用"以及任何携带…的意图"捕获遗漏

3.2 流程步骤的编号体系

Step 0：意图识别与路由     ← 永远是 Step 0
Step 1A：分支流程 A       ← 用字母区分并行分支
Step 1B：分支流程 B
Step 2：通用后处理         ← 独立于分支的后续步骤

技巧：

• Step 0 恒为"意图识别"，保证 AI 不会跳过判断直接执行
• 分支用字母（1A/1B）而非数字（1/2），语义更清晰
• 每个步骤内部用 ### 1. 2. 3. 子编号，避免嵌套混乱

3.3 输出模板化

给 AI 提供严格的输出格式模板：

您好！关于【产品名称 型号】：

[简要说明产品用途和特点，1-2句]

| 档位 | 品牌 | 型号 | 单价 | 批量价 | 交期 |
|------|------|------|------|--------|------|
| 高档 | XX  | XX  | ¥XX  | ¥XX/件 | X天  |
| 中档 | XX  | XX  | ¥XX  | ¥XX/件 | X天  |
| 低档 | XX  | XX  | ¥XX  | ¥XX/件 | X天  |

推荐理由：[用户需求匹配说明 + 核心特点 + 质量评价]

技巧：

• 用 XX 占位符，AI 知道哪些是变量
• 明确字数限制（50-150字正文，含表格可适当延长）
• 内部版和外部版给不同模板（外部版隐藏成本明细）

3.4 敏感信息分级处理

级别	类型	处理方式
一级敏感	内部运营信息（薪资/营业额/供应商详情）	礼貌拒绝，给固定话术
二级敏感	商务合作（代理/加盟）	话题转移，引导至官方渠道
无关话题	与业务无关	友好引导回业务主题

技巧：

• 每级都写死回复话术（用「」包裹），AI 直接使用，不走样
• 内部版额外定义"超出本技能范围"的边界（HR数据❌、财务报表❌）

3.5 版本与兼容性信息

SKILL.md 尾部固定格式：

*技能版本：3.0.2*  
*最后更新：2026-04-01*  
*适配程序：G:\QuoteApp\QuoteApp.exe*

内部版额外标注：

*适用渠道：企业微信 AIBot（内部员工）*  
*对应外部版：quote-app v3.0.2（微信 ClawBot）*

---

四、脚本设计技巧

4.1 脚本角色分工

脚本	职责	调用时机
run_quote.py	核心报价计算（解析→计算→导出）	AI 构造 CLI 命令调用
launch_quoteapp.py	GUI/CLI 启动器	需要人工精细操作时

技巧：

• 主脚本做重活，启动脚本做轻活
• 主脚本输出结构化信息（--json-result），AI 可解析
• 启动脚本只是 subprocess.Popen 透传，简单可靠

4.2 主脚本的内部结构

# 1. 环境配置（硬编码路径 + sys.path 注入）
QUOTE_APP_ROOT = Path(r"G:\QuoteApp")
sys.path.insert(0, str(INTERNAL_SRC))

# 2. 模块导入（try-except 保护，失败时给明确错误提示）
try:
    from src.core.geometry_extractor import extract
    ...
except ImportError as e:
    print(f"[ERROR] 无法加载 QuoteApp 模块: {e}")
    sys.exit(1)

# 3. 功能函数（list_materials, list_aux_costs, run_single_quote）
#    - 每个函数内自管 session 生命周期
#    - 输出格式化到终端，方便 AI 解读

# 4. argparse 命令行入口
#    - 参数分组注释
#    - 默认值硬编码
#    - epilog 提供完整示例

关键技巧：

• sys.path 注入：把宿主程序的 _internal 目录加入搜索路径，直接复用其核心模块
• try-except 导入保护：失败时输出 [ERROR] + 解决建议，AI 可据此排障
• argparse 分组注释：参数按功能分组，epilog 提供完整命令示例
• 5步流程日志：[1/5] 到 [5/5]，AI 可追踪执行进度
• session 生命周期管理：try/finally 确保数据库会话关闭

4.3 输出格式设计

终端输出兼顾人类阅读和 AI 解析：

📄 处理文件: bracket.step

  材质    : 铝6061
  总报价  : ¥285.60
  ├ 材料费: ¥45.30
  └ 加工费: ¥240.30

📄 报价单已保存到: C:\输出目录

技巧：

• 用 📄 ✅ ❌ ⚠ emoji 前缀做视觉分层
• 树状缩进（├ └）表达成本结构
• 批量模式输出汇总统计（成功: 4 失败: 1）

---

五、参考资料设计技巧

5.1 references/ 的定位

materials.md 是只读知识库，包含：

• 材料列表（20种，含代码/名称/密度/单价）
• 图纸格式（5种，含置信度评级）
• 辅材费（20种，含分类/默认勾选）
• 表面处理/热处理选项

技巧：

• 用表格而非段落描述数据，AI 可精确定位
• 置信度评级（100%/90%/85%/75%/50%）帮助 AI 向用户解释格式选择
• 辅材费的"默认选中"标记（✅）让 AI 知道什么会被自动计算

5.2 数据与指令分离

信息类型	放在哪里	原因
执行流程/路由逻辑	SKILL.md	是"怎么做的"指令
触发条件/关键词	SKILL.md frontmatter	供系统匹配
材料/格式/辅材数据	references/	是"参考什么"的知识
计算脚本	scripts/	是"执行什么"的能力

---

六、可复用的技能设计模板

6.1 SKILL.md 模板

---
name: <技能名>
description: >
  适用对象：<用户类型>（通过 <渠道> 接入）。
  触发场景：(1) <场景1> (2) <场景2> (3) <场景3> ...
  触发关键词："<关键词1>"、"<关键词2>"、
  # <分类注释> ↓
  "<关键词3>"、"<关键词4>"、
  以及任何<兜底条件>的<意图类型>。
---

# <技能标题>

## 概述

| 能力 | 说明 |
|------|------|
| **能力1** | 简述 |
| **能力2** | 简述 |

**程序位置**：`<绝对路径>`  
**数据库**：`<绝对路径>`  
**Python 解释器**：`<绝对路径>`

---

## Step 0：意图识别与路由

### 意图分类体系

| primary_intent | 典型输入 | 路由目标 |
|----------------|---------|---------|
| `<意图1>` | `"示例输入"` | → [对应流程] |

### 路由规则

- **confidence ≥ 0.8**：直接路由
- **confidence 0.6–0.79**：路由 + 确认
- **confidence < 0.6**：询问用户

---

## Step 1：主流程

### 1. 收集信息
**必要信息**：...
**可选信息**：...

### 2. 执行命令
```powershell
& $PYTHON $SCRIPT --参数 "值"

3. 处理结果

…

---

Step 2：异常与边界处理

类型	处理方式
…	…

---

CLI 参数参考

参数	说明	默认值
…	…	…

---

技能版本：X.X.X
最后更新：YYYY-MM-DD
适配程序：<路径>

### 6.2 脚本模板

```python
"""
<脚本名>
<功能简述>

功能：
  - <功能1>
  - <功能2>

用法：
  $PYTHON = "<受管Python路径>"
  & $PYTHON <脚本名>.py --<主参数> <值> [选项...]

依赖：
  - <外部程序路径>
  - <Python 依赖>
"""

import argparse, sys
from pathlib import Path

# ── 环境配置 ──
APP_ROOT = Path(r"<程序根目录>")

# ── 模块导入（带保护） ──
try:
    from xxx import yyy
except ImportError as e:
    print(f"[ERROR] 无法加载模块: {e}", file=sys.stderr)
    sys.exit(1)

# ── 功能函数 ──
def list_xxx():
    """列出可用选项"""
    ...

def run_main(args):
    """主流程"""
    # [1/N] 步骤1
    # [2/N] 步骤2
    # ...
    return result

# ── CLI 入口 ──
def main():
    parser = argparse.ArgumentParser(
        description="<描述>",
        epilog=r"""
示例：
  & $PYTHON <脚本名>.py --<参数> <值>
        """
    )
    # 参数定义（分组注释）
    ...
    
    args = parser.parse_args()
    result = run_main(args)
    
    if args.json_result:
        print(json.dumps(result, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

---

七、设计原则速查表

#	原则	说明	体现位置
1	意图先行	所有消息先过意图识别，再路由执行	Step 0
2	权限分离	内外版本差异化，SKILL.md 层面控制展示粒度	两个独立技能
3	脚本封装	复杂操作封装为 CLI 脚本，AI 只需拼参数	scripts/
4	参数分层	必填/可选/探索性三分，显式默认值	CLI 参数参考表
5	模板化输出	给 AI 严格的输出格式模板，含占位符	输出示例
6	错误穷举	每种错误都有具体恢复动作	错误处理表
7	数据与指令分离	静态知识放 references/，流程逻辑放 SKILL.md	目录结构
8	话术写死	敏感/拒绝/引导类回复用固定文本，AI 不走样	「」引用
9	版本标注	末尾固定版本/日期/适配信息	SKILL.md 尾部
10	置信度路由	三级阈值（≥0.8/0.6-0.79/<0.6）精准分派	路由规则
11	触发词穷举	frontmatter 中列尽所有可能的用户表述	description
12	5步日志	脚本输出带 [1/5]~[5/5] 进度标记	脚本内部
13	环境硬编码	Python 解释器/程序路径等写死在 SKILL.md 中	概述段
14	多方式调用	推荐/备用/手动三套调用方式	执行命令段
15	emoji 视觉分层	📄✅❌⚠ 前缀让输出一目了然	脚本输出

---

八、最佳实践总结

DO ✅

1. SKILL.md 是唯一真相来源——AI 不需要看其他文件就能执行
2. 意图分类用表格——比文字描述更精确
3. 给 AI 提供完整的命令示例——包括 PowerShell 变量定义
4. 脚本输出结构化——--json-result 供程序解析，终端输出供人阅读
5. 错误消息带建议——[ERROR] xxx. 建议: yyy
6. 参数分组注释——# 工件信息 # 费率参数 等
7. 默认值写入 SKILL.md——AI 知道不提供参数时的行为
8. 内外版用独立技能——而不是用 if/else 在一个技能中切换
9. references/ 放静态数据——避免 SKILL.md 过长
10. 版本号 + 日期 + 适配信息——方便维护和排查兼容性

DON’T ❌

1. 不要让 AI 自行判断权限——在 SKILL.md 中显式声明每类信息的可见性
2. 不要用自然语言描述复杂流程——用表格/代码块/模板
3. 不要省略错误处理——每种已知错误都要有对应动作
4. 不要让 AI 操作数据库——通过脚本间接执行
5. 不要模糊化触发条件——穷举关键词，给兜底条件
6. 不要省略默认值——每个可选参数都要标明默认值
7. 不要在 SKILL.md 中写代码逻辑——代码放 scripts/，SKILL.md 只写调用方式
8. 不要把内部信息暴露给外部版——两个版本独立维护

---