配置驱动示例系统
概述
以 YAML 配置文件作为单一真实来源（SSOT），自动生成多视图文档索引和 API 反向映射的示例管理架构。
关键内容
核心架构
三层结构：配置文件 → 处理脚本 → 多种输出文档。
examples-config.yaml (SSOT)
↓
tools/process_examples.py
↓
├── 复制示例文件
├── index.md（按分类/难度的主索引）
└── api-index.md（API → 示例的反向映射）
SSOT 配置结构
每个示例的元信息集中存储在 YAML 中：
- source/target：文件路径映射
- metadata：title（双语）、category、difficulty、apis、features、tags
分类和难度级别也在配置中统一定义，支持图标和颜色标注。
多视图文档生成
主索引 index.md 自动生成三种浏览视图：
1. 按分类浏览：分类 → 难度分组
2. 按难度浏览：难度 → 示例列表
3. 快速查找表：完整表格
API 反向索引
api-index.md 构建 API → 使用该 API 的示例列表的反向映射，主要用途：
- AI 助手快速定位特定 API 的使用示例
- 评估 API 文档覆盖率
- 开发者学习 API 用法
设计决策
| 决策 | 理由 |
|---|---|
| 使用 YAML | 可读性强，支持注释和嵌套，Python 生态成熟 |
| 配置与代码分离 | 非程序员可编辑，配置变更不需改代码 |
| 生成而非手写索引 | 避免多视图不同步，减少人为错误 |
| 文件复制而非符号链接 | Windows 兼容，可独立分发，支持复制时转换 |
AI 友好设计
系统专为 AI 助手优化： - 结构化元信息（apis 字段）便于语义检索 - API 反向索引支持"给我看用 RigidBody 的示例"类查询 - 双语标题支持中英文检索
扩展点
- 添加新分类：在
categories部分增加条目 - 添加新元数据字段：metadata 下增加自定义字段，脚本自动保留
- 添加新生成器：扩展
ExamplesProcessor类的generate_*方法 - 添加新验证规则：在
validate_config()中增加逻辑
工作流程
添加新示例：编辑 YAML → --validate 验证 → 执行生成 → 提交全部变更（配置 + 示例文件 + 生成文档）。
来源
- raw/articles/personal/ai-dev-kit/config/EXAMPLES_SYSTEM.md — UrhoX AI Dev Kit 示例系统架构文档 v1.0（2025-11-17）