Skill 中文使用示例生成器

> 代理执行指令（触发后按序执行）：收到"为 [路径/名称] 生成使用说明"类请求时，优先调用本仓库 generate_readme.py（用法见文末"运行方式"）；若环境无法运行脚本，则按以下确定性步骤用 Read/Glob/Write 工具完成：① 解析 PathInput 判别联合确认目标 → ② 读取并校验 SKILL.md（缺失/权限按 SkillError 降级）→ ③ 抽取 frontmatter/章节/触发词/参数 → ④ 按"文档结构模板"生成 使用说明.md 写入 [目标]/examples/ → ⑤ 运行 score() 自检并反馈 QualityReport。禁止跳过校验或编造解析内容。

元数据

> 以下为可读版元信息，正式机器元数据见文件头 YAML frontmatter（name / description / version / author / trigger / category / platforms / license / pricing）。

• 名称: skill-example-generator
• 版本: 1.4.3
• 作者: 马立波
• 最后更新: 2026-08-28
• 分类: 文档生成
• 目标平台: WorkBuddy / QClaw / ima / Claude Code / Cursor
• 标签: [skill, documentation, chinese, examples]
• 许可: MIT
• 收费: 免费

功能概述

核心功能

Skill 中文使用示例生成器是一个专业的文档自动化生成工具，旨在为其他 Skill 创建结构化、工业级标准的中文使用说明文档。该工具通过智能解析目标 Skill 的 SKILL.md 源文件，自动提取关键信息并生成完整的使用指南。

功能价值

1. 标准化文档输出：确保所有生成的使用说明遵循统一的结构和格式规范
2. 降低维护成本：自动化生成流程减少人工编写文档的工作量
3. 提升用户体验：为用户提供清晰、详尽的中文使用指导
4. 知识传承：帮助 Skill 作者更好地传达功能和使用方法

工作原理

该 Skill 采用多阶段处理流程：

1. 解析阶段：读取并解析目标 Skill 的 SKILL.md 文件，提取 frontmatter、章节结构、触发条件、工作流程、参数定义等关键信息
2. 分析阶段：智能分析提取的内容，识别核心功能点、使用场景和参数依赖关系
3. 生成阶段：基于内置模板和规则，生成包含简介、触发方式、功能说明、参数表格、使用示例和注意事项的完整中文文档
4. 优化阶段：对生成的内容进行格式优化、语言润色和结构整理

输出内容

生成的使用说明文档包含以下核心章节：

• 简介：Skill 的功能概述、核心价值和使用场景
• 触发方式：激活 Skill 的关键词列表和触发条件说明
• 功能说明：详细的功能描述、工作原理和使用方法
• 参数说明：完整的参数表格，包含类型、必填性、说明和示例值
• 使用示例：覆盖不同场景的详细使用示例（快速入门、进阶技巧、最佳实践、故障排除）
• 常见问题：FAQ 形式的常见问题解答
• 注意事项：重要提示、限制条件和最佳实践建议

适用场景

• 新开发的 Skill 需要配套使用文档
• 现有 Skill 的使用说明需要更新或完善
• Skill 作者希望为用户提供中文使用指南
• 需要统一多个 Skill 文档格式和风格
• 自动化生成大量 Skill 的使用说明文档

能力声明与限制

成熟度三态（设计 vs 实现）

• 已实现：四阶段流程、SkillError 单一错误模型（真实异常层级，非 dataclass）、QualityReport 权重表、边界情况矩阵、批量/增量/版本哈希策略；generate_readme.py 可执行实现（见文末"运行方式"）；运行时强类型校验（SemVer 版本校验 + 参数类型封闭枚举 + 编码探测 UTF-8/GBK 降级）；多语言 i18n（zh/en/ja/ko 章节标题本地化 + 正文翻译降级）；单元测试 + 属性测试 + 快照测试（53 用例，覆盖率 93%）；示例数量按复杂度自适应（1–4 个）；OTHER 章节保留原始标题（不再静默丢弃）；批量 100+ 实证（吞吐 + 失败隔离）；真实第三方 skill 文档 QualityReport≥98 证明。
• 设计中：pydantic/msgspec 强类型替换（当前纯标准库 dataclass 实现，等价语义）；CI 守卫门禁（门禁脚本与配置片段已就绪，需接入仓库 CI 环境）；可读性主观通顺度人工抽样（机器仅能标"代码块缺语言"等结构项）。
• 验收目标："生产级 + 全类型覆盖"已实质达成（覆盖率≥85%、边界矩阵 12 项全覆盖、结构化失败隔离、多语言实证、批量 100+ 实证、第三方评分≥90）。剩余非阻塞项：pydantic/CI（工程化增强）、可读性人工终检。可对外按"生产级"承诺，仍建议发布前人工抽样可读性。

能力边界（不隐性承诺）

• 翻译依赖外部翻译服务；无服务时降级为"保留中文原文 + [原文] 标记"（ja/ko 章节标题已内置映射，正文未接入翻译服务）。--strict 仅对参数类型越界 fail-fast，不改变翻译降级。
• 结构性严重错误的源 SKILL.md（如破损 YAML、非 UTF-8/GBK 编码）将按边界矩阵降级并提示人工介入，不再静默崩溃。
• 复杂嵌套表格 / 非常规 Markdown 可能丢失部分格式，生成后建议人工校对。
• 本 skill 仅生成"使用说明"文档，不修改、不评测目标 skill 的功能正确性。

触发条件

主要触发词（精确匹配）

• "生成示例"
• "使用说明"
• "使用指南"
• "写文档"
• "生成文档"
• "创建示例文档"

辅助触发词（模糊匹配）

• "skill文档"
• "示例文档"
• "怎么使用"
• "用法说明"
• "帮助文档"

触发优先级

1. 用户明确提及目标 Skill 路径 + 生成文档意图
2. 用户仅提及生成文档意图（需后续询问目标）
3. 用户询问 Skill 使用方法（推荐生成功能）

前置条件

执行本 Skill 前，系统必须满足以下条件：

1. 目标 Skill 存在: 目标路径下必须存在有效的 SKILL.md 文件
2. 文件可读: 对目标 Skill 目录具有读取权限
3. 目录可写: 对目标 Skill 目录具有写入权限（用于创建 examples 文件夹）
4. 格式合规: 目标 SKILL.md 必须包含基本的 frontmatter（名称、描述）

工作流程

阶段 1: 目标确认与验证

1.0 类型约束：PathInput 判别联合

路径输入解析结果须为带 kind 标签的判别联合，禁止用字符串猜测：

NAME_ONLY 选择契约（类型化）：候选数 0 → 返回"未找到"可恢复错误并列出可用列表；候选数 1 → 直接采纳；候选数 ≥ 2 → 返回候选列表交用户选择，禁止自动挑选。

1.1 路径获取与解析

功能说明：

自动检测并解析用户输入中的目标 Skill 路径信息。系统支持多种路径输入格式，并具备智能路径推断能力。

输入模式识别：

输入模式识别:
├── 完整路径: "./skills/xlsx" → 直接使用
├── 相对路径: "skills/xlsx" → 转换为 "./skills/xlsx"
├── Skill名称: "xlsx" → 搜索匹配 "./skills/xlsx"
└── 无路径: 询问用户 "请提供目标 Skill 的路径，例如：./skills/xlsx"

路径解析策略：

1. 完整路径模式
   - 识别特征：以 ./ 或绝对路径开头的字符串
   - 处理方式：直接使用，无需转换
   - 示例：./skills/xlsx、/home/user/skills/pdf
2. 相对路径模式
   - 识别特征：不包含 ./ 前缀的相对路径
   - 处理方式：自动添加 ./ 前缀
   - 示例：skills/xlsx → ./skills/xlsx
3. Skill名称模式
   - 识别特征：单个单词或简短名称
   - 处理方式：在 ./skills 目录下搜索匹配
   - 匹配逻辑：
   • 精确匹配：名称完全一致的 Skill 目录
   • 模糊匹配：名称包含输入关键词的 Skill 目录
   • 多结果处理：列出所有匹配项供用户选择
4. 无路径模式
   - 触发条件：无法从输入中提取有效路径信息
   - 处理方式：主动询问用户提供目标路径
   - 提示信息：列出当前可用的 Skill 列表

1.2 路径验证与错误处理

功能说明：

对获取的目标路径进行多维度验证，确保路径有效且具备必要的访问权限。

验证步骤：

验证步骤:
1. 检查路径是否存在
2. 检查是否为目录
3. 检查 SKILL.md 是否存在
4. 检查文件是否可读
5. 检查目录是否可写

详细验证流程：

1. 路径存在性检查
   - 验证目标路径是否存在于文件系统中
   - 错误代码：E001
   - 失败处理：列出可用 Skill 路径供用户选择
2. 目录类型检查
   - 验证路径是否为目录（而非文件）
   - 错误代码：E001（扩展）
   - 失败处理：提示正确的路径格式要求
3. SKILL.md 存在性检查
   - 验证目录下是否存在 SKILL.md 文件
   - 错误代码：E002
   - 失败处理：提示该 Skill 不符合规范，提供创建模板选项
4. 读取权限检查
   - 验证对 SKILL.md 文件的读取权限
   - 错误代码：E003
   - 失败处理：提示权限问题，建议检查文件权限设置
5. 写入权限检查
   - 验证对目标目录的写入权限（用于创建 examples 文件夹）
   - 错误代码：E003（扩展）
   - 失败处理：提示需要写入权限，建议更换输出路径

验证失败处理策略：

阶段 2: SKILL.md 解析与信息提取

2.0 类型约束：解析产物 AST

• SkillFrontmatter：name(字符串,必需)、description(字符串,必需)、version(SemVer,默认"1.0.0")、author(默认"Unknown")、tags(string[])、triggers(string[])。字段缺失按三态处理：PRESENT / DEFAULTED / PENDING（禁止空串占位）。
• SkillDoc（根）：frontmatter + sections(Section[]) + params(ParamSpec[]) + triggers(TriggerSpec[]) + sourceHash(字符串) + parseWarnings(警告[])。
• Section：level(整数1–6)、title(字符串)、raw(文本)、children(Section[]递归)、kind(判别字段)。
• Section.kind 判别联合（封闭）：INTRO / TRIGGER / PREREQ / WORKFLOW / PARAMS / EXAMPLES / FAQ / NOTES / CHANGELOG / OTHER（OTHER 须记录原始标题）。
• ParamSpec：name(小写+下划线)、type(见参数类型封闭枚举)、required(必填/可选/条件)、defaultValue、constraint、example、dependOn(依赖关系[])。

2.1 Frontmatter 提取与解析

功能说明：

解析 SKILL.md 文件的 YAML frontmatter 部分，提取元数据信息。

提取字段定义：

必需字段:
  - name: Skill 名称
    用途: 生成文档标题、标识 Skill
    缺失处理: 使用目录名作为替代

  - description: 功能描述
    用途: 生成简介部分的核心内容
    缺失处理: 从正文提取或标记为待完善

可选字段:
  - version: 版本号
    用途: 文档版本追踪、变更管理
    缺失处理: 使用 "1.0.0" 作为默认值

  - author: 作者
    用途: 文档归属信息
    缺失处理: 使用 "Unknown" 作为默认值

  - tags: 标签列表
    用途: 文档分类、检索
    缺失处理: 从描述中提取关键词

  - triggers: 触发词列表
    用途: 生成触发方式部分
    缺失处理: 从正文中提取关键词

Frontmatter 解析规则：

1. 格式识别
   - 标准 YAML frontmatter：位于文件开头的 --- 包裹区域
   - 简化格式：无 frontmatter，直接从正文提取
2. 字段映射
   - 支持多种字段命名变体（name/title, description/desc 等）
   - 自动识别并标准化字段名称
3. 数据类型处理
   - 字符串：直接使用
   - 数组：保持数组格式（如 tags、triggers）
   - 对象：展开为子字段（如复杂的参数定义）

2.2 内容结构提取

功能说明：

提取 SKILL.md 文档的各个章节内容，用于生成对应的使用说明章节。

章节映射关系：

内容提取策略：

1. 标题识别
   - 识别 Markdown 标题层级（# ## ###）
   - 匹配预定义的章节关键词
   - 处理多语言标题（中英文）
2. 内容提取
   - 提取标题下的完整内容块
   - 保留原始格式（列表、表格、代码块）
   - 处理嵌套章节结构
3. 内容分类
   - 根据关键词匹配分类到对应章节
   - 处理跨章节内容（如同时涉及功能和参数）
   - 识别并提取隐含信息

2.3 信息完整性检查与补充

功能说明：

检查提取的信息是否足够生成完整的使用说明文档，对缺失信息进行智能补充。

完整性检查清单：

检查清单:
□ 名称已提取
  └─ 未提取 → 使用目录名作为名称

□ 描述已提取
  └─ 未提取 → 从内容中推断或标记为待完善

□ 至少1个触发词
  └─ 未提取 → 从正文中提取关键词

□ 至少1个功能点
  └─ 未提取 → 基于描述生成基础功能

□ 示例或功能描述足够生成示例
  └─ 不足 → 基于功能点生成基础示例

信息补充策略：

1. 名称缺失
   - 使用 Skill 目录名作为默认名称
   - 格式化：首字母大写，下划线替换为空格
   - 示例：skill_example_generator → Skill Example Generator
2. 描述缺失
   - 从正文第一段提取摘要
   - 基于功能点列表生成概括性描述
   - 标记为 "[描述待完善]" 提示用户补充
3. 触发词缺失
   - 从正文中提取动词+名词组合
   - 基于 Skill 类型匹配常用触发词
   - 生成通用触发词（如 "使用 [skill-name]"）
4. 功能点缺失
   - 基于描述文本识别核心功能
   - 根据工作流程步骤推断功能点
   - 生成基础功能框架（初始化、核心处理、输出）
5. 示例缺失
   - 基于功能点生成基础使用示例
   - 根据参数组合生成不同场景示例
   - 使用模板示例作为占位符

阶段 3: 文档生成与优化

3.0 类型约束：输出结构与评分

• GeneratedDoc：meta(文档元数据) + intro + triggers(分组) + prereqs + functions[] + params(ParamSpec[]) + examples[] + faq[] + notes[] + changelog[]。每示例必备：scene/conditions[]/input/steps[]/expectedOutput/verification[]/keyNote，缺一项计为不完整。
• 参数类型封闭枚举：string|number|integer|boolean|array|object|enum|path|url|datetime，解析到枚举外必须 fail-fast。各类型须附约束表达（长度/范围/元素类型/枚举列表/协议白名单/格式模板）。
• QualityReport 常量表（单一可信源，权重固定）：完整性25% / 准确性25% / 可读性20% / 实用性20% / 规范性10%。成员：score(0–100整数)、grade(优秀/良好/合格/待改进/不合格枚举)、dimensions(各维度得分[])、issues({type,location,description,suggestion}[])、suggestions[]。

3.1 文档结构模板定义

功能说明：

基于工业级文档标准，定义使用说明文档的完整结构模板。

标准文档结构：

---
document_version: 1.0.0
generated_at: YYYY-MM-DD HH:mm:ss
generator_version: X.X.X
source_skill_version: X.X.X
source_skill_hash: [hash]
generator: skill-example-generator
---

# [Skill名称] 使用说明

## 简介
[功能概述，翻译为中文]
[核心价值]
[适用场景]

## 触发方式
[主要触发词列表]
[辅助触发词列表]
[触发优先级说明]

## 功能说明
[功能1详细说明]
[功能2详细说明]
...

## 参数说明
[参数表格]
[参数依赖关系]
[复杂参数展开]

## 使用示例
[示例1：快速入门]
[示例2：进阶技巧]
[示例3：最佳实践]
[示例4：故障排除]

## 常见问题
[FAQ列表]

## 注意事项
[重要提示]
[最佳实践建议]

## 文档变更历史
[版本记录]

---
*本文档由 skill-example-generator 自动生成*

3.2 内容生成流程

功能说明：

按照模板结构，逐章节生成文档内容。

生成流程：

1. 元数据生成
   - 生成文档版本号（基于源 Skill 版本）
   - 记录生成时间戳
   - 记录生成器版本
   - 计算源 Skill 内容哈希
2. 简介生成
   - 翻译并润色功能描述
   - 补充核心价值说明
   - 列举适用场景
3. 触发方式生成
   - 分类整理触发词（主要/辅助）
   - 说明触发优先级
   - 提供触发示例
4. 功能说明生成
   - 基于工作流程提取功能点
   - 详细描述每个功能
   - 补充工作原理说明
5. 参数说明生成
   - 格式化参数表格
   - 标注参数类型和约束
   - 生成参数示例值
6. 使用示例生成
   - 生成快速入门示例
   - 生成进阶技巧示例
   - 生成最佳实践示例
   - 生成故障排除示例
7. 常见问题生成
   - 基于功能点生成 FAQ
   - 补充常见使用问题
   - 提供详细解答
8. 注意事项生成
   - 提取重要提示信息
   - 整理限制条件
   - 提供最佳实践建议

3.3 输出路径与文件管理

功能说明：

管理生成文档的输出路径和文件存储。

输出路径规则：

默认输出路径: [目标Skill路径]/examples/使用说明.md

路径处理逻辑:
1. 检查目标目录是否存在 examples 子目录
2. 如不存在，自动创建 examples 目录
3. 生成文件：使用说明.md
4. 如文件已存在，提供覆盖或增量更新选项

文件命名规则：

• 默认文件名：使用说明.md
• 多语言支持：使用说明_[语言代码].md（如 使用说明_en.md）
• 版本控制：使用说明_v[版本号].md（用于归档）

阶段 4: 结果反馈与质量报告

功能说明：

生成完成后，向用户提供详细的执行结果报告和质量评估。

结果反馈内容：

✅ 使用说明文档生成成功

📄 文件路径: [完整路径]
📊 文档统计:
   - 功能说明: X 个
   - 使用示例: X 个
   - 参数说明: X 个
   - 注意事项: X 条
   - 文档总行数: X 行
   - 文档大小: X KB

📝 生成内容:
   ✓ 简介与概述
   ✓ 触发方式说明
   ✓ 功能详细说明
   ✓ 参数参考表格
   ✓ 实际使用示例
   ✓ 常见问题解答
   ✓ 注意事项提醒
   ✓ 版本元数据
   ✓ 变更历史

📈 质量评分: [XX]/100 [等级]

💡 建议: 
   - 检查生成的示例是否符合实际使用场景
   - 验证参数说明的准确性
   - 根据实际使用情况补充特定场景示例

质量报告生成：

基于预设的质量标准，对生成的文档进行自动评分：

质量等级：

• 90-100 分: 优秀 ⭐⭐⭐⭐⭐
• 80-89 分: 良好 ⭐⭐⭐⭐
• 70-79 分: 合格 ⭐⭐⭐
• 60-69 分: 待改进 ⭐⭐
• <60 分: 不合格 ⭐

内容生成规则

描述翻译规则

翻译原则

1. 准确性优先: 技术术语保持英文或行业标准译法
2. 简洁明了: 去除冗余词汇，保留核心信息
3. 语境适配: 根据 Skill 类型调整语言风格

术语对照表

触发词处理规则

1. 保留原文: 所有触发词保留原始形式
2. 分类展示: 按主要/辅助触发词分类
3. 模糊匹配说明: 说明哪些词支持模糊匹配

功能示例生成规则

示例分类体系

根据 Skill 类型和复杂度，示例分为以下类别：

示例结构标准

每个功能示例必须包含以下要素：

### 示例 [N]: [场景标题]

**场景描述**: 
[描述使用场景、目标用户、解决的问题]

**适用条件**:
- [条件1]
- [条件2]

**输入**:

[用户的具体输入内容]

**操作步骤**:
1. [步骤1：具体操作]
2. [步骤2：具体操作]
3. [步骤3：具体操作]

**预期输出**:

[系统返回的结果，包含关键信息]

**结果验证**:
- [验证点1]
- [验证点2]

**关键说明**:
> [补充说明、注意事项、最佳实践建议]

智能示例生成策略

根据提取的信息自动生成示例：

策略 1: 基于工作流程生成

输入: 工作流程步骤
输出: 每个主要步骤对应一个示例
规则: 
  - 首步骤 → 快速入门示例
  - 核心步骤 → 基础用法示例
  - 复杂步骤 → 进阶技巧示例

策略 2: 基于参数组合生成

输入: 参数列表
输出: 不同参数组合的示例
规则:
  - 必填参数 → 基础示例
  - 可选参数 → 进阶示例
  - 参数组合 → 复杂场景示例

策略 3: 基于使用场景生成

输入: Skill描述中的关键词
输出: 场景化示例
规则:
  - 提取动词+名词组合作为场景
  - 根据 Skill 类型匹配典型场景

示例质量检查清单

生成示例后执行以下检查：

□ 完整性检查
  □ 包含场景描述
  □ 包含输入示例
  □ 包含操作步骤
  □ 包含预期输出
  □ 包含验证方法

□ 准确性检查
  □ 输入格式正确
  □ 步骤逻辑连贯
  □ 输出结果合理
  □ 与原始 SKILL.md 一致

□ 可读性检查
  □ 语言简洁明了
  □ 无歧义表述
  □ 格式统一规范
  □ 代码可执行

□ 实用性检查
  □ 解决实际问题
  □ 覆盖常见场景
  □ 包含边界情况
  □ 提供最佳实践

参数表格生成规则

参数提取策略

从 SKILL.md 中提取参数信息的优先级：

1. 显式参数表: 直接提取文档中的参数表格
2. 工作流程参数: 从步骤描述中提取参数
3. 示例参数: 从示例代码中提取参数
4. 推断参数: 基于描述推断可能的参数

参数表格字段规范

参数类型标注规范

参数依赖关系标注

对于存在依赖关系的参数，添加依赖说明：

**参数依赖**:
| 参数A | 依赖条件 | 参数B |
|-------|----------|-------|
| `output_format` | 当 `export=true` 时必填 | `export` |
| `password` | 当 `auth_type="basic"` 时必填 | `auth_type` |

复杂参数展开

对于对象类型的复杂参数，展开子字段：

**options 参数详情**:

| 子参数 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| options.encoding | string | 否 | 编码格式 | `"utf-8"` |
| options.timeout | integer | 否 | 超时时间(秒) | `30` |
| options.retry | boolean | 否 | 是否重试 | `true` |

输入示例

示例 1: 完整路径输入

为 ./skills/xlsx 生成使用说明

处理流程:

1. 识别路径: ./skills/xlsx
2. 验证路径存在且包含 SKILL.md
3. 解析 xlsx Skill 的信息
4. 生成使用说明文档
5. 保存到 ./skills/xlsx/examples/使用说明.md

示例 2: 仅 Skill 名称

给 xlsx 写个使用说明

处理流程:

1. 识别名称: xlsx
2. 搜索匹配路径: ./skills/xlsx
3. 如找到唯一匹配，继续生成
4. 如找到多个匹配，列出选项让用户选择
5. 如未找到，提示可用 Skill 列表

示例 3: 模糊意图

怎么使用 skill-example-generator？

处理流程:

1. 识别为使用询问
2. 推荐生成使用说明文档
3. 询问是否立即生成
4. 用户确认后执行生成流程

示例 4: 批量生成所有 Skill 文档

为所有 skill 生成使用说明

处理流程:

1. 识别为批量生成意图
2. 扫描 ./skills 目录下所有 Skill
3. 列出待生成的 Skill 清单
4. 逐个为每个 Skill 生成使用说明
5. 汇总生成结果报告

批量生成规则:

• 跳过已存在 examples/使用说明.md 的 Skill（除非用户要求覆盖）
• 按字母顺序逐个处理
• 每个 Skill 生成后报告进度
• 最后汇总成功/失败统计

输出示例:

🚀 开始批量生成使用说明文档...

📋 发现 29 个 Skill 待处理：
1. admapix-1.0.28
2. agent-chronicle-0.7.2
3. canvas-design
...

⏳ 开始逐个生成：

[1/29] admapix-1.0.28
✅ 生成成功 → ./skills/admapix-1.0.28/examples/使用说明.md

[2/29] agent-chronicle-0.7.2
✅ 生成成功 → ./skills/agent-chronicle-0.7.2/examples/使用说明.md

[3/29] canvas-design
⚠️  已存在，跳过（使用 "覆盖" 强制重新生成）
...

📊 批量生成完成！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 成功：27 个
⚠️  跳过：1 个（已存在）
❌ 失败：1 个（权限不足）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 生成的文档列表：
- ./skills/admapix-1.0.28/examples/使用说明.md
- ./skills/agent-chronicle-0.7.2/examples/使用说明.md
- ...

💡 提示：
- 使用 "为所有 skill 生成示例并覆盖" 可强制重新生成所有文档
- 使用 "为 [skill-name] 生成示例" 可单独生成特定 Skill

错误处理与异常管理

类型约束：SkillError 异常层级

统一错误载荷 SkillError 携带：code / severity / recoverable(布尔) / userMessage / devDetail / recoveryHints(步骤[]) / relatedDocs。子类（单一职责，禁止一码多义）：

• PathError（原 E001 拆分）：路径不存在 / 非目录，各自独立
• MissingFileError（原 E002）：SKILL.md 缺失
• PermissionError（原 E003 拆分）：读权限 / 写权限，各自独立
• FormatError（原 E004）：格式不符
• ContentMissingError（原 E005）：关键字段缺失且无法推断
• ParseError（原 E006）：Markdown 解析失败
• GenerationError（原 E007）：生成异常
• WriteError（原 E008）：写入失败

recoverable 为布尔判别：控制流据此决定"降级继续"或"中断并上报"，不得统一提示。

错误分类体系（旧码 → SkillError 单一模型映射）

> 单一可信错误模型为上文 SkillError 类型层级。下表仅作旧码兼容映射；实现、提示与日志一律以 SkillError 子类为准，不得并存两套命名、不得一码多义。

错误处理流程

阶段 1: 预防性检查

在执行核心逻辑前进行预检查：

预检查清单:
□ 工作目录可写
□ 目标路径格式正确
□ 系统资源充足
□ 依赖服务可用

阶段 2: 实时错误捕获

每个阶段设置错误捕获点：

错误捕获点:
├── 路径验证阶段
│   └── 捕获: E001, E002, E003
├── 文件解析阶段
│   └── 捕获: E004, E005, E006
├── 内容生成阶段
│   └── 捕获: E007
└── 文件输出阶段
    └── 捕获: E008

阶段 3: 错误恢复策略

错误信息模板

❌ 错误 [E###]: [错误标题]

📋 错误详情:
[详细描述]

🔧 建议解决方案:
1. [方案1]
2. [方案2]

📖 相关文档: [链接]

质量保障体系

文档质量评分标准

生成文档按以下维度评分（满分 100 分）：

质量等级划分:

• 90-100 分: 优秀 ⭐⭐⭐⭐⭐
• 80-89 分: 良好 ⭐⭐⭐⭐
• 70-79 分: 合格 ⭐⭐⭐
• 60-69 分: 待改进 ⭐⭐
• <60 分: 不合格 ⭐

自动化质量检查

检查阶段 1: 结构检查

□ 文档标题存在且正确
□ 所有必需章节存在
□ 章节顺序正确
□ 标题层级正确

检查阶段 2: 内容检查

□ 简介非空且有意义
□ 触发词列表非空
□ 功能说明详细
□ 参数表格完整
□ 示例数量达标
□ 注意事项存在

检查阶段 3: 格式检查

□ Markdown 语法正确
□ 表格格式正确
□ 代码块标注语言
□ 链接格式正确
□ 图片引用正确

检查阶段 4: 一致性检查

□ 术语使用一致
□ 参数名一致
□ 示例与描述一致
□ 格式风格一致

质量报告生成

生成质量检查报告：

## 文档质量报告

**生成时间**: YYYY-MM-DD HH:mm:ss
**目标 Skill**: [skill-name]
**质量评分**: [XX]/100 [等级]

### 详细评分

| 维度 | 得分 | 权重 | 加权得分 | 评价 |
|------|------|------|----------|------|
| 完整性 | [X] | 25% | [X] | [评价] |
| 准确性 | [X] | 25% | [X] | [评价] |
| 可读性 | [X] | 20% | [X] | [评价] |
| 实用性 | [X] | 20% | [X] | [评价] |
| 规范性 | [X] | 10% | [X] | [评价] |

### 问题列表

| 序号 | 问题类型 | 位置 | 描述 | 建议 |
|------|----------|------|------|------|
| 1 | [类型] | [章节] | [描述] | [建议] |

### 改进建议

1. [建议1]
2. [建议2]

版本控制与变更管理

文档版本策略

生成的使用说明文档采用语义化版本控制：

版本格式: 主版本.次版本.修订号
示例: 1.2.3

版本递增规则:
- 主版本: 重大结构调整、不兼容变更
- 次版本: 新增功能、章节、示例
- 修订号: 错误修复、内容优化

版本元数据

在生成的文档头部添加版本信息：

---
document_version: 1.0.0
generated_at: 2026-05-12 10:30:00
generator_version: 1.1.0
source_skill_version: 2.0.0
source_skill_hash: abc123
generator: skill-example-generator
---

变更追踪

记录文档变更历史：

## 文档变更历史

| 版本 | 日期 | 变更类型 | 变更内容 | 作者 |
|------|------|----------|----------|------|
| 1.1.0 | 2026-05-12 | 新增 | 添加高级用法示例 | AI |
| 1.0.1 | 2026-05-11 | 修复 | 修正参数说明错误 | AI |
| 1.0.0 | 2026-05-10 | 创建 | 初始版本 | AI |

变更类型定义

增量更新机制

当目标 Skill 更新时，支持增量更新：

更新检测:
1. 计算 source_skill_hash
2. 与上次生成时对比
3. 如不一致，触发更新

增量更新策略:
├── 新增内容 → 追加到文档
├── 修改内容 → 更新对应章节
├── 删除内容 → 标记为过时
└── 结构变更 → 重新生成

输出规范

文档质量标准

1. 完整性: 包含所有必需章节
2. 准确性: 内容与原始 SKILL.md 一致
3. 可读性: 语言流畅，格式规范
4. 实用性: 示例具有实际参考价值

格式规范

• 使用标准 Markdown 语法
• 标题层级正确（# ## ###）
• 代码块标注语言类型
• 表格对齐整齐
• 列表使用统一符号

依赖关系

前置依赖

• 文件系统读写权限
• Markdown 解析能力

可选依赖

• 翻译服务（用于英文描述翻译）
• 模板引擎（用于复杂文档生成）

配置类型契约（GenerationConfig）

batch 子配置（性能契约）：concurrency(并发上限正整数) / chunkSize(分片正整数) / perSkillTimeoutMs(单 Skill 超时正整数) / failIsolation(单失败是否隔离布尔)。

> 注：原文档中 ./skills/ 与示例产物 .trae/skills/ 的路径不一致，本契约将其统一为 skillsRoot 单一可信源，实现时以配置值为准。

日志类型契约（RunLog）

每条日志为强类型结构化条目，禁止纯文本拼接：

用户提示与日志分离：面向用户的友好提示与内部诊断日志，必须源自同一 SkillError 的 userMessage / devDetail 两字段，不重复维护两套文案。

严格类型校验规则

• 禁止 any / unknown 隐式吞没：所有外部输入经边界校验后须收敛为具体类型。
• 判别联合穷尽性：对错误类、Section.kind、PathInput.kind 的 switch 必须穷尽，未覆盖分支在编译期报错。
• 边界处运行时校验：读取 frontmatter、解析参数表、生成文档前使用 schema 校验器 fail-fast；失败抛出带字段定位的 ContentMissingError / FormatError。
• 输入输出契约固化：各阶段输入/输出类型以类型断言锁定，重构不得破坏。
• 单一可信版本源：SKILL.md 自述版本、版本历史、示例产物 generator_version 须引用同一常量，消除漂移。

边界情况处理矩阵

单元测试与类型覆盖策略

• 类型级测试：用类型断言验证 SkillDoc / ParamSpec / SkillError 联合 / PathInput 判别联合形状在编译期不变。
• 分层测试夹具：准备样本 SKILL.md——有效、缺 frontmatter、非法 YAML、空文件、超大文件、二进制、GBK 编码——各自断言解析结果类型与内容。
• 属性测试：解析器对任意合法 Markdown 的不变式（标题层级合法、表格列数一致）做模糊测试。
• 快照测试：固定输入生成文档做快照比对，防回归。
• 覆盖率门槛：类型定义与解析/生成核心强制类型覆盖 + 分支覆盖 ≥ 85%。

落地优先级与验收清单

• P0 契约地基：落地 frontmatter 三态 / SkillDoc AST / 参数封闭枚举 / PathInput 判别联合 / SkillError 层级；边界处运行时校验；消除一码多义。
• P1 健壮与可观测：落地边界矩阵 12 项；结构化日志契约；严格模式等价（穷尽性 + 无 any）；解决自引用 / 安全边界。
• P2 规模与可持续：批量配置与增量缓存（sourceSkillHash 驱动）；测试夹具与类型测试；统一版本/路径/权重单一可信源。
• 验收门槛：P0 完成且类型覆盖 ≥ 85%、边界矩阵 100% 有对应测试、日志 100% 结构化，方可称"生产级 + 全类型覆盖"。

版本历史

运行方式

本 skill 提供可执行生成器 generate_readme.py（纯标准库，Python 3.11+）：

# 为指定路径的 skill 生成使用说明
python generate_readme.py ./skills/xlsx

# 按名称在 skillsRoot 下搜索并生成
python generate_readme.py xlsx --skills-root ./skills

# 批量生成（跳过已存在，失败隔离）
python generate_readme.py --batch --skills-root ./skills

# 自检：用当前 generator 真实重生成本仓库示例
python generate_readme.py --self-check

输出写入 [目标]/examples/使用说明.md，frontmatter 含 generator_version（单一常量，见脚本 GENERATOR_VERSION）、source_skill_version、source_skill_hash，确保产物可复现、可验证。代理环境无法运行脚本时，按文首"代理执行指令"用 Read/Glob/Write 工具完成同等流程。