人类文档生成器

目的

这项技能将存储在ai/文件夹中的详细AI文档转换为docs/文件夹中的人类友好文档。它创建摘要、快速入门和视觉图表，使人类能够快速理解和操作复杂系统。

关键原则：ai/文件夹保持为真相的来源（详细、全面，适用于AI上下文）。docs/文件夹包含人类优化的提取（摘要、图表、快速参考）。

何时使用这项技能

当：

用户需要从AI上下文文档中获得人类可读的文档
AI文档对于快速人类消费来说太详细了
系统复杂性需要视觉图表以便于理解
需要快速入门指南或执行摘要
用户特别提到难以遵循AI文档
为新团队成员创建入职材料
提取操作快速参考的关键信息

触发短语：

“为…创建人类文档”
“我跟不上AI文档”
“让这个更容易理解”
“创建一个快速入门指南”
“添加图表以解释…”
“总结AI文档”

核心原则

1. 保持并行结构

ai/                          docs/
├── architect/               ├── architect/
│   ├── app/                │   ├── app/
│   │   └── 01_DOC.md       │   │   └── 01_DOC_SUMMARY.md
│   └── src/                │   └── src/
│       └── 01_DOC.md       │       └── 01_DOC_QUICKSTART.md
├── backend/                ├── backend/
├── frontend/               ├── frontend/
└── testing/                └── testing/

关键规则：docs/镜像ai/结构，但包含人类优化的版本

2. 三种人类友好格式

对于每个AI文档，创建一个或多个：

摘要 (*_SUMMARY.md)
- 执行摘要（1-2段落）
- 关键点（项目符号列表）
- 快速决策辅助
- 原始长度的20%
快速入门 (*_QUICKSTART.md)
- 逐步入门
- 最多5分钟阅读
- 代码示例
- 常见陷阱
- 成功标准
图表 (*_DIAGRAMS.md)
- 使用Mermaid.js进行视觉表示
- 架构图表
- 流程图
- 序列图
- 实体关系

3. Mermaid图表指南

始终使用Mermaid.js进行图表绘制（在GitHub、VS Code、大多数Markdown查看器中呈现）：

graph TD
    A[开始] --> B{决策}
    B -->|是| C[动作1]
    B -->|否| D[动作2]

要使用的图表类型：

graph TD - 从上到下的流程图
sequenceDiagram - API/交互流程
erDiagram - 数据库模式
journey - 用户旅程
stateDiagram-v2 - 状态机
gantt - 时间线/路线图

查看references/mermaid_examples.md以获取模板

工作流程

工作流程1：从AI文档创建摘要

输入： AI文档文件的路径（例如，ai/architect/app/02_BACKEND_REQUIREMENTS.md）

流程：

彻底阅读AI文档
确定20%最关键的信息
创建执行摘要（2-3段落）
提取关键点（5-10项目标）
添加快速参考表
保存到docs/中的平行位置，并带有_SUMMARY.md后缀

输出： docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md

模板： assets/templates/summary_template.md

工作流程2：创建快速入门指南

输入： AI文档文件的路径

流程：

阅读AI文档
确定“入门”路径
创建分步指令（编号）
添加代码片段/命令
包括成功标准
添加“下一步”部分
保存到平行位置，并带有_QUICKSTART.md后缀

输出： docs/architect/app/02_BACKEND_REQUIREMENTS_QUICKSTART.md

模板： assets/templates/quickstart_template.md

工作流程3：创建视觉图表

输入： AI文档文件的路径或主题描述

流程：

阅读AI文档
确定可视觉化的概念：
- 系统架构
- 数据流
- 用户旅程
- 数据库模式
- 决策树
创建Mermaid图表（2-5图表）
为每个图表添加解释性文本
保存到平行位置，并带有_DIAGRAMS.md后缀

输出： docs/architect/app/02_BACKEND_REQUIREMENTS_DIAGRAMS.md

模板： assets/templates/diagrams_template.md

工作流程4：批量处理整个文件夹

输入： AI文档文件夹的路径（例如，ai/architect/app/）

流程：

列出文件夹中的所有Markdown文件
对于每个文件，确定最佳格式：
- 架构文档 → 摘要 + 图表
- 实施指南 → 快速入门
- 规范 → 摘要 + 图表
在平行结构中创建人类文档
为docs/文件夹生成索引README
报告完成摘要

输出： 完整的docs/文件夹结构

工作流程5：更新现有的人类文档

输入： 更新的AI文档的路径

流程：

检查docs/中是否存在人类文档
如果存在，比较修改日期
如果AI文档更新，则重新生成人类文档
保留任何手动添加（检查"Manual:"标记）
保存更新的人类文档

输出： 更新的人类文档

文档格式标准

摘要格式

# [原始标题] - 摘要

**来源：** AI文档链接
**最后更新：** 日期
**阅读时间：** X分钟

## 执行摘要

[2-3段落捕捉本质]

## 关键点

- 点1
- 点2
- 点3

## 快速参考

| 方面 | 细节 |
|--------|--------|
| 键1  | 值  |

## 何时阅读完整文档

- 场景1
- 场景2

[完整文档链接]

快速入门格式

# [主题]快速入门

**完成时间：** X分钟
**先决条件：** 列表

## 第1步：[动作]

[指令+代码/命令]

## 第2步：[动作]

[指令+代码/命令]

## 成功标准

✅ 检查表项目
✅ 检查表项目

## 下一步

- 详细文档链接
- 相关快速入门

## 故障排除

**问题：** 描述
**修复：** 解决方案

图表格式

# [主题]视觉指南

**来源：** AI文档链接

## 概览图表

```mermaid
[图表代码]

解释： 这张图表显示了什么

[特定方面]图表

[图表代码]

解释： 这张图表显示了什么

图例

符号 → 含义


## 与其他技能的集成

**与架构师技能一起使用：**
- 架构师在`ai/architect/`中创建详细规范
- 人类文档在`docs/architect/`中创建摘要

**与业务技能一起使用：**
- 业务在`ai/business/`中创建用例
- 人类文档创建执行摘要

**与执行技能一起使用：**
- 执行定义策略
- 人类文档创建视觉路线图

**与清理技能一起使用：**
- 清理组织`ai/`文件夹
- 人类文档重新生成`docs/`结构

## 质量标准

**每个人类文档必须有：**
✅ **清晰度** - 不阅读AI文档即可理解
✅ **简洁性** - 原始长度的20%或更少（摘要）
✅ **可操作性** - 清晰的下一步
✅ **视觉** - 复杂主题至少有1个图表
✅ **可导航性** - 链接到源和相关文档
✅ **日期** - 最后更新的时间戳

**最低质量阈值：8/10**

## 文件命名约定

AI文档： ai/文件夹/FILE.md 摘要： docs/文件夹/FILE_SUMMARY.md 快速入门： docs/文件夹/FILE_QUICKSTART.md 图表： docs/文件夹/FILE_DIAGRAMS.md


**从不：**
- 在`ai/`中创建文件（只从那里读取）
- 替换AI文档
- 在格式间复制信息

## 维护

**当AI文档更新时：**
1. 检查`docs/`中是否有相应的人类文档
2. 如果AI文档更新，则重新生成
3. 更新"最后更新"时间戳
4. 保持变更历史记录最小化（人类不需要完整的变更日志）

**索引README重新生成：**
- 创建`docs/README.md`，导航到所有人类文档
- 按文件夹结构分组
- 添加"快速链接"部分

## 常见用例

### 用例1：新团队成员入职

**场景：** 新开发人员需要了解GabeDA架构

**行动：**
1. 为所有`ai/architect/app/`文档生成摘要
2. 为关键架构概念生成图表
3. 创建`docs/ONBOARDING.md`，提供策划路径
4. 包括常见任务的快速入门

### 用例2：执行审查

**场景：** 执行需要高层次的理解

**行动：**
1. 从技术规范中生成执行摘要
2. 创建系统架构的视觉图表
3. 最多1页，带有Mermaid图表
4. 无技术术语

### 用例3：开发人员快速参考

**场景：** 开发人员忘记了API端点结构

**行动：**
1. 从API文档中创建快速入门
2. 包括代码示例
3. 添加常见模式
4. 链接到完整规范

## 示例

**示例1：架构摘要**

输入：`ai/architect/app/02_BACKEND_REQUIREMENTS.md`（14,000字）
输出：`docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md`（2,000字）

**示例2：快速入门**

输入：`ai/architect/app/05_CSV_UPLOAD_SPECIFICATION.md`
输出：`docs/architect/app/05_CSV_UPLOAD_QUICKSTART.md`
- 实施CSV上传的5个步骤
- 代码片段
- 10分钟阅读

**示例3：视觉指南**

输入：`ai/architect/app/07_WORKFLOWS_AND_DATA_FLOW.md`
输出：`docs/architect/app/07_WORKFLOWS_DIAGRAMS.md`
- 已经有图表，提取和简化
- 添加注释
- 创建简化版本

## 版本历史

**v1.0.0** （2025-11-01）
- 初始技能创建
- 支持摘要、快速入门、图表格式
- Mermaid图表集成
- 平行文件夹结构

---

**最后更新：** 2025-11-01
**技能类型：** 文档转换和可视化