⚡

人类文档生成器 human-docs-generator

人类文档生成器技能用于在系统发生重大变化时自动生成和维护针对不同角色的文档，将复杂的技术信息转化为易于理解的指南，提高开发效率和用户体验。

DevOps 0 次安装 0 次浏览 更新于 3/2/2026

人类文档生成器技能

角色

自动生成并在系统发生重大变化时维护针对人类的特定角色文档。

目的

将复杂的AI状态和技术实现转化为简单、针对角色的指南，人类实际上可以理解和使用。

触发条件

自动触发

  • ✅ 史诗完成
  • 🔧 公共API修改
  • 🎯 新用户功能部署
  • 💥 引入破坏性变更
  • 🐛 修复关键错误
  • 📊 完成5+相关任务

手动触发

{
  "event": "generate.human.docs",
  "scope": "all|specific-role",
  "reason": "手动请求"
}

文档结构

维护的文件

ai-state/human-docs/
├── INDEX.md                 # 角色目录和快速导航
├── frontend-developer.md    # React, 组件, 路由
├── backend-developer.md     # APIs, 模型, 数据库
├── architect.md            # 系统设计, 模式
├── devops.md              # 部署, 监控, 调试
├── tester.md              # 测试套件, 覆盖率
├── product-manager.md     # 功能, 指标, 路线图
└── end-user-guide.md      # 屏幕截图, 如何使用

生成过程

1. 收集上下文

sources:
  - ai-state/active/     # 当前实现
  - ai-state/knowledge/  # 模式和决策
  - operations.log       # 最近的变化
  - test-results/        # 工作内容

2. 提取角色相关信息

前端开发人员需求

  • 组件位置和层次结构
  • 状态管理模式
  • 可重用组件列表
  • 最近的UI更改

后端开发人员需求

  • API端点文档
  • 数据库模式更改
  • 认证流程
  • 服务依赖关系

最终用户需求

  • 带注释的屏幕截图
  • 逐步指南
  • 功能位置
  • 常见工作流程

3. 转换为人类格式

人类文档规则

  1. 每篇文档最多1000字
  2. 图表优于文字（Mermaid.js）
  3. 示例优于解释
  4. 仅当前状态（无历史）
  5. 快速入门聚焦

4. 生成图表

组件树（前端）

graph TD
    App --> Header
    App --> Routes
    Routes --> Login
    Routes --> Dashboard
    Dashboard --> Charts
    Dashboard --> Tables

API流程（后端）

sequenceDiagram
    用户->>前端：点击登录
    前端->>API：POST /auth/login
    API->>数据库：验证凭据
    数据库->>API：用户数据
    API->>前端：JWT令牌
    前端->>用户：仪表板

用户流程（最终用户）

graph LR
    Start[打开应用] --> Login[输入电子邮件/密码]
    Login --> Dash[查看仪表板]
    Dash --> Upload[上传数据]
    Upload --> Process[等待处理]
    Process --> View[查看结果]
    View --> Export[下载报告]

文档模板

前端开发人员模板

# 前端开发人员指南

## 快速入门
[3步设置过程]

## 组件地图
[组件的Mermaid图表]

## 添加新页面
1. 在 `/src/pages/` 中创建组件
2. 在 `/src/routes.tsx` 中添加路由
3. 在 `/src/components/Nav.tsx` 中更新导航

## 可用组件
- `<Button>` - 主要操作
- `<Card>` - 内容容器
- `<Table>` - 数据显示
[列出可重用组件]

## 状态管理
[当前状态形状图表]

## 最近更改
- ✅ 添加密码重置
- ✅ 更新仪表板布局

最终用户模板

# 如何使用[应用名称]

## 开始使用
[带有箭头的登录页面屏幕截图]

## 主要功能

### 上传数据
1. 点击 "上传" 按钮（右上角）
2. 选择你的CSV文件
3. 点击 "处理"
[带有编号步骤的屏幕截图]

### 查看报告
[报告页面的屏幕截图]
- 黄色框 = 警告
- 绿色框 = 成功
- 红色框 = 错误

## 常见任务
**Q: 如何重置我的密码？**
A: 在登录页面点击 "忘记密码"

**Q: 我的旧报告在哪里？**
A: 在侧边栏点击 "历史"

质量检查

发布前

  • [ ] 少于1000字？
  • [ ] 包含图表/屏幕截图？
  • [ ] 包括快速入门？
  • [ ] 提供示例？
  • [ ] 无技术术语？
  • [ ] 测试过的指令有效？

集成

输入事件

{
  "event": "epic.completed",
  "epic_id": "epic-oauth",
  "tasks_completed": ["task-001", "task-002"],
  "changes": ["Added Google login"]
}

输出事件

{
  "event": "human.docs.updated",
  "files": [
    "frontend-developer.md",
    "end-user-guide.md"
  ],
  "sections_changed": [
    "authentication",
    "login-methods"
  ]
}

避免的反模式

❌ 编写变更日志（仅当前状态） ❌ 技术深入研究（保持简单） ❌ 文字墙（使用项目符号/图表） ❌ 假设知识（解释一切） ❌ 版本历史（一个活文档）

成功指标

  • 阅读时间 < 5分钟
  • 图表与文本比例 > 40%
  • 快速入门成功率 > 90%
  • 人类困惑工单 < 5%
  • 文档更新频率 = 功能频率