智能体需求文档生成 Skill

一句话定位

把"无版本号 Markdown 源文档"稳定产出为"版本化 .md 快照"，适用于需求文档、功能设计文档、PRD、设计说明等标准化文档场景。

适用触发语句

当用户出现以下意图时，优先使用本 skill：

新建需求文档 / 新建 PRD / 新建设计说明
按模板生成某功能设计文档
修改现有源文档并输出新版本快照
批量生成多个模块文档
为某项目建立通用 profile / manifest / 模板
将 Markdown 文档沉淀为可交付的 .md 版本快照

适用场景

新建某个功能、模块、页面的需求文档或功能设计文档
更新现有无版本号源文档，并生成新版本快照
将 Markdown 源文档转换为 .md 版本快照
批量生成多个文档快照
为不同项目复用统一的需求文档工作流

使用边界

本 skill 提供通用工作流、模板和脚本，不绑定任何特定项目、目录或文档清单
项目专属章节、角色、命名、组织边界、私有业务规则等，应写进项目自己的源文档、profile、模板或参考资料
通用合规基线：references/通用等保三级安全要求.md 是 skill 内统一维护的跨项目通用安全基准，功能文档在涉及等保功能点时按需引用；若具体项目需要调整合规口径，直接修改该参考文件即可，不要把项目私有规则写死在通用 skill 主体中
若团队存在"生成前必须二次确认"等协作规则，应记录在项目记忆或项目文档中，而不是写死为 skill 强制规则
若需求是自由体报告、会议纪要、营销文案等非结构化文档，不必强行套用本 skill

标准工作流

先确认文档名称、适用系统/项目、模块路径、角色、字段和交互范围
新建文档时，优先参考 references/通用需求文档模板.md，再通过 scripts/gen_template.js 初始化源 Markdown
若文档涉及身份鉴别、访问控制、日志留痕、敏感字段、导入导出或接口安全等内容，同时参考 references/通用等保三级安全要求.md，在源文档 7.1 中按章节引用并补充模块特有要求
更新文档时，直接编辑无版本号源文件，并同步维护文档版本与修订记录
生成快照前，确认输出目录、源文件路径和版本号是否正确
使用 scripts/gen_from_md.js 生成 .md 快照；如目录下已有旧快照，脚本会自动归档到 backup/
如需批量生成，使用 manifest 文件集中声明多个源文件；如有共享参数，再叠加 profile
交付前确认源文件、Markdown 快照两者版本一致

资源说明

references/快速上手.md：三分钟上手说明，适合首次导入后快速照着跑
references/通用需求文档模板.md：通用十二章需求/功能设计模板
references/通用等保三级安全要求.md：skill 内统一维护的通用安全基准文件；功能设计文档在 7.1 中按需引用适用章节，并补充模块特有要求
references/PROFILE_SCHEMA.md：profile / manifest 字段说明、优先级与组合示例
assets/examples/feature-design.profile.json：模板初始化示例 profile
assets/examples/single-generate.profile.json：单文档生成示例 profile
assets/examples/batch-shared.profile.json：批量生成时的共享参数示例 profile
assets/examples/feature-design.manifest.json：批量生成示例 manifest
assets/examples/示例功能设计.md：示例源文档

合规引用约定

通用等保要求统一维护在 references/通用等保三级安全要求.md
功能设计文档仅在涉及账号、权限、日志、敏感字段、导入导出、接口安全等功能点时，在 7.1 合规与安全要求 中按章节引用
功能文档应写"引用章节 + 本模块特有要求"，不要把通用规则原文整段复制到每份文档中
若某项目需要调整合规口径，直接修改上述参考文件即可，后续文档按更新后的内容引用

数据导出文件命名规范（通用约束）

生成功能设计文档时，如涉及「导出」功能描述，推荐遵循以下命名规范：

格式: {业务前缀}_{YYYYMMDD}_{HHMMSS}.xlsx
示例: 用户信息_20260405_103045.xlsx
时间戳: 使用当前系统时间，年月日(8位) + 时分秒(6位)
扩展名: 固定为 .xlsx

规范说明：

业务前缀应简洁明了，建议使用「模块名+信息」或「功能名+数据」格式
时间戳确保文件名唯一性，避免覆盖
导入模板文件名建议使用固定名称（不带时间戳），如：批量导入模板.xlsx

示例对照表：

| 模块 | 导出前缀示例 | 示例文件名 | |------|-------------|-----------| | 用户管理 | 用户信息 | 用户信息_20260405_103045.xlsx | | 订单管理 | 订单数据 | 订单数据_20260405_103045.xlsx | | 设备管理 | 设备信息 | 设备信息_20260405_103045.xlsx |

注意：具体项目可根据实际业务调整前缀命名，但建议保持 {前缀}_{时间戳}.xlsx 的统一格式。

删除功能规范（推荐）

生成功能设计文档时，如涉及「删除」功能描述，推荐遵循以下规范：

核心原则：根据业务需要决定是否提供批量删除功能

| 模式 | 适用场景 | 实现方式 | |-----|---------|---------| | 单条删除 | 数据敏感、操作不可逆、需严格控制的场景 | 列表不展示复选框，仅在行内操作列提供删除按钮 | | 批量删除 | 数据量大、操作频繁、需提升效率的场景 | 列表展示复选框，工具栏提供批量删除按钮 |

| 项目 | 规范要求 | |-----|---------| | 删除入口 | 单条删除在每行数据的操作列提供"删除"按钮；批量删除在工具栏提供"删除"按钮 | | 删除约束 | 已绑定/已入网/已启用等状态的数据，删除按钮灰化不可用 | | 确认机制 | 点击删除后弹出确认弹窗，确认后才执行删除 |

建议：

对于车辆、设备、用户等核心数据，建议仅提供单条删除，避免误操作
对于日志、临时数据等非核心数据，可考虑提供批量删除
具体项目应在文档中明确是否提供批量删除功能

导入功能逻辑规范（前置校验模式）

生成功能设计文档时，如涉及「导入」功能描述，推荐遵循以下逻辑规范：

核心原则：前置全量校验，有错不导入，全部通过才入库

| 阶段 | 处理逻辑 | 用户反馈 | |-----|---------|---------| | 文件上传 | 校验文件格式（.xlsx）和大小（≤10MB） | 格式错误时Toast提示阻断 | | 数据校验 | 逐行校验所有数据（必填/格式/长度/唯一性/关联数据/字典值） | 错误列表直接展示在页面（行号+列名+原因） | | 导入执行 | 仅当全部数据校验通过后才执行导入 | 成功后Toast提示导入条数 |

校验类型清单：

文件级校验：格式、大小
必填项校验：必填字段不能为空
格式校验：正则匹配（手机号、邮箱、编码等）
长度校验：字段值长度限制
唯一性校验：与现有数据对比，关键字段不重复
关联数据校验：外键/关联字段值在系统中存在
字典值校验：枚举/字典字段值在有效范围内

错误提示格式：

统一格式：第X行，【字段名】：错误原因
示例：第3行，用户名：不能为空、第5行，手机号：格式不正确

快速开始

首次导入后，进入 scripts/ 目录执行一次 npm install
按场景选择入口：
- 新建首版：gen_template.js
- 单文档出版：gen_from_md.js --source 或 --profile
- 批量出版：gen_from_md.js --manifest
生成完成后，检查输出目录中的：
- 无版本号源文件
- {baseName}_{version}.md
- backup/ 中是否已归档旧快照

脚本入口

1）初始化源文档

/usr/local/bin/node ~/.workbuddy/skills/智能体需求文档生成skill/scripts/gen_template.js \
  --output-dir /path/to/doc \
  --basename 示例项目-用户管理功能设计 \
  --title 用户管理功能设计 \
  --system 示例管理平台 \
  --project 示例项目

或使用 profile：

/usr/local/bin/node ~/.workbuddy/skills/智能体需求文档生成skill/scripts/gen_template.js \
  --profile ~/.workbuddy/skills/智能体需求文档生成skill/assets/examples/feature-design.profile.json

2）生成单个文档快照

直接指定源文件：

/usr/local/bin/node ~/.workbuddy/skills/智能体需求文档生成skill/scripts/gen_from_md.js \
  --source /path/to/doc/示例项目-用户管理功能设计.md \
  --output-dir /path/to/doc