@guru-ai-product/ai-product-kit 0.2.251112184032 → 0.2.251113163244

package/mcp/.doc_cache/5b91334295d6ad31_SKILL.md

@@ -0,0 +1,588 @@
+---
+name: guide_writing_standard
+description: Comprehensive standards, templates, and references for producing high-quality guide documentation.
+---
+
+# 指南文档规范
+
+## 文档信息
+
+| 项目 | 内容 |
+|------|------|
+| 版本号 | v1.2 |
+| 适用范围 | 全体团队成员、文档撰写者、项目管理者 |
+
+## 1. 概述
+
+### 1.1 规范目的
+
+本规范旨在建立统一的指南文档撰写标准，确保项目中所有指南文档的质量、一致性和可用性。通过标准化的文档结构和格式要求，提升团队协作效率和知识传承效果。
+
+### 1.2 适用范围
+
+**适用文档类型**
+
+- 工具使用指南
+- 流程操作指南
+- 技术实施指南
+- 最佳实践指南
+- 培训教程文档
+
+**适用团队角色**
+
+- 产品经理和产品负责人
+- 技术团队成员
+- 设计师和用户体验专家
+- 项目管理者
+- 新员工和实习生
+
+### 1.3 规范价值
+
+- **标准化**：建立统一的文档结构和格式标准
+- **可读性**：提升文档的可读性和理解效率
+- **一致性**：确保不同作者撰写的文档保持一致
+- **质量保证**：通过规范化流程提升文档质量
+- **效率提升**：减少文档撰写和维护的时间成本
+
+## 2. 文档结构规范
+
+### 2.1 必需章节结构
+
+#### 2.1.1 文档信息部分
+
+**标准格式**
+
+```markdown
+## 文档信息
+
+| 项目 | 内容 |
+|------|------|
+| 版本号 | v[主版本].[次版本] |
+| 适用范围 | [目标用户群体] |
+```
+
+**字段说明**
+
+- **版本号**：采用语义化版本控制（如 v1.0, v1.1, v2.0）
+- **适用范围**：明确目标读者和使用场景
+
+**注意**：创建日期、最后更新等时间信息可通过git历史记录查询，无需在文档中重复记录。
+
+#### 2.1.2 核心章节结构
+
+```markdown
+## 1. 概述
+### 1.1 [工具/流程]价值
+### 1.2 适用场景
+### 1.3 [其他概述内容]
+
+## 2. [主要内容章节]
+### 2.1 [子章节]
+### 2.2 [子章节]
+
+## 3. [实操/使用]指南
+### 3.1 [具体操作步骤]
+### 3.2 [最佳实践]
+
+## 4. [模板/示例]（如适用）
+
+## 5. 常见问题
+
+## 6. 最佳实践总结
+
+## 7. 附录
+### 7.1 [相关资源]
+### 7.2 [参考资料]
+```
+
+### 2.2 推荐章节安排
+
+#### 2.2.1 工具使用指南结构
+
+```markdown
+1. 概述（工具价值、适用场景）
+2. 工具介绍（功能特点、核心优势）
+3. 使用流程（完整工作流程、质量控制）
+4. 模板库（标准模板、变量说明）
+5. 实操指南（最佳实践、优化技巧）
+6. 案例演示（实际案例、操作流程）
+7. 常见问题（问题分类、解决方案）
+8. 最佳实践总结
+9. 附录（工具对比、成本预算、资源链接）
+```
+
+#### 2.2.2 流程操作指南结构
+
+```markdown
+1. 概述（流程目的、适用范围）
+2. 流程设计（整体架构、关键节点）
+3. 操作步骤（详细步骤、注意事项）
+4. 质量控制（检查点、验证方法）
+5. 角色职责（参与角色、权责分工）
+6. 常见问题（问题处理、异常流程）
+7. 最佳实践（经验总结、改进建议）
+8. 附录（表单模板、工具资源）
+```
+
+### 2.3 标题层级规范
+
+**层级结构**
+
+```markdown
+# 文档标题（H1，仅用于文档标题）
+## 一级章节（H2）
+### 二级章节（H3）
+#### 三级章节（H4）
+##### 四级章节（H5，谨慎使用）
+```
+
+**命名原则**
+
+- 使用数字编号：`## 1. 概述`、`### 1.1 工具价值`
+- 标题简洁明确，避免过长
+- 使用动词开头的标题表示操作性内容
+- 使用名词短语表示描述性内容
+
+## 3. 内容撰写规范
+
+### 3.1 核心要求
+
+- **简洁明了**：避免冗余和复杂的句式，直接表达核心内容
+- **模块化组织**：将文档内容按功能模块组织，便于查找和维护
+- **模板引用**：涉及模板、样例等内容时，单独引用外部文件，避免文档冗长
+- **专业正式**：禁止使用emoji表情符号，保持文档的专业性和正式性
+- **准确可靠**：避免包含不准确的时间预估、成本预算等可能误导读者的信息
+
+### 3.2 语言风格
+
+- 使用主动语态：`执行以下步骤` 而非 `以下步骤需要被执行`
+- 使用祈使句：`点击确认按钮` 而非 `用户应该点击确认按钮`
+- 避免模糊表述：`设置为30秒` 而非 `设置为合适的时间`
+- 使用具体数据：`提升60%效率` 而非 `显著提升效率`
+- 避免装饰性符号：不使用emoji表情符号或其他装饰性符号
+- 避免不确定信息：不包含未经验证的成本预估、时间预测等可能不准确的信息
+
+### 3.3 内容组织
+
+- **信息层次**：概述信息 → 详细说明 → 具体操作 → 注意事项 → 相关资源
+- **段落控制**：每段3-5句话，避免过长段落
+- **逻辑清晰**：从简单到复杂，从概念到实践
+
+## 4. 质量控制
+
+### 4.1 质量检查清单
+
+#### 4.1.1 内容检查
+
+- [ ] 文档信息表格完整准确
+- [ ] 章节结构符合规范要求
+- [ ] 内容逻辑清晰连贯
+- [ ] 操作步骤详细可执行
+- [ ] 示例和案例真实有效
+- [ ] 常见问题覆盖全面
+- [ ] 相关资源链接有效
+
+#### 4.1.2 格式检查
+
+- [ ] Markdown格式正确
+- [ ] 标题层级规范
+- [ ] 表格格式统一
+- [ ] 代码块格式正确
+- [ ] 无emoji表情符号或装饰性符号
+- [ ] 图片和链接正常显示
+
+#### 4.1.3 实用性检查
+
+- [ ] 目标用户明确
+- [ ] 使用场景清晰
+- [ ] 操作步骤可重现
+- [ ] 预期结果明确
+- [ ] 错误处理完善
+- [ ] 最佳实践实用
+
+## 5. 文件组织结构
+
+### 5.1 组织原则
+
+所有引用的文档应该放到对应的子文件夹中，确保项目文档的有序组织和便于管理。通过合理的文件组织结构，提升文档的可维护性和团队协作效率。
+
+### 5.2 标准文件夹结构
+
+#### 5.2.1 基础文件夹结构
+
+```
+skills/guide_writing_standard/
+├── template/          # 模板文件
+├── checklists/        # 检查清单
+├── configs/           # 配置文件
+├── references/        # 参考资料
+├── assets/            # 资源文件
+│   ├── diagrams/      # 图表和流程图
+│   └── images/        # 图片和截图
+└── examples/          # 示例和案例
+```
+
+#### 5.2.2 功能模块文件夹结构
+
+**需求收集模块示例**
+
+```
+../requirements
+├── SKILL.md                    # 主入口 Skill 文档
+├── requirements/intake/        # 需求收集工具
+│   ├── SKILL.md               # 工具使用指南
+│   ├── template/              # 工具模板
+│   ├── examples/              # 使用案例
+│   └── references/            # 参考资料
+├── requirements/initiative_planning/        # 立项规划
+│   ├── SKILL.md               # 规划指南
+│   └── template/              # 规划模板
+├── requirements/documentation/ # 需求文档
+│   ├── SKILL.md               # 文档撰写指南
+│   └── template/              # 文档模板
+├── requirements/review/        # 需求评审
+│   └── SKILL.md               # 评审指南
+└── requirements-iteration/     # 需求迭代
+    ├── SKILL.md               # 迭代指南
+    └── template/              # 迭代模板
+```
+
+#### 5.2.3 模板文件夹结构
+
+```
+template/
+├── README.md               # 模板索引
+├── SKILL模板.md            # 技能入口模板
+├── 指南文档标准模板.md       # 标准指南模板
+└── 工具使用指南模板.md       # 工具指南模板
+```
+
+#### 5.2.4 分版本组织文档文件夹结构
+
+```
+requirements/
+├── v1.0.0/                     # 版本1.0.0
+│   ├── index.md                # 版本索引
+│   ├── 1_产品定位与分析.md       # 模块化文档
+│   ├── 2_功能需求.md            # 模块化文档
+│   ├── 3_商业化策略.md          # 模块化文档
+│   ├── 4_用户界面与体验.md       # 模块化文档
+│   └── 5_风险评估与成功指标.md    # 模块化文档
+├── v1.1.0/                     # 版本1.1.0
+│   └── ...                     # 新版本文档
+└── v2.0.0/                     # 版本2.0.0
+    └── ...                     # 重大版本文档
+```
+
+### 5.3 引用文档类型分类
+
+#### 5.3.1 模板文件（template/）
+
+模板文件是工具使用的基础，提供标准化的文档结构：
+
+- **Skill 入口模板**：遵循 Agent Skills Spec 的 `SKILL.md` 模板，包含 YAML frontmatter 和章节骨架
+- **指南文档标准模板**：通用的指南结构模板
+- **工具使用指南模板**：标准化的工具使用指南结构
+- **索引模板**：用于构建模板库或资料库的 `README.md`
+- **表单与表格模板**：标准化的数据采集结构
+- **代码片段模板**：可复用的代码或命令段落
+
+#### 5.3.2 参考资料（references/）
+
+- 术语表和词汇表
+- 常见问题解答
+- 技术规范文档
+- 外部资源链接
+
+#### 5.3.3 资源文件（assets/）
+
+- 图片和截图
+- 流程图和架构图
+- 视频和音频文件
+- 其他多媒体资源
+
+#### 5.3.4 检查清单（checklists/）
+
+- 文档质量检查清单
+- 发布前检查清单
+- 审核标准清单
+- 维护任务清单
+
+#### 5.3.5 工具配置（configs/）
+
+- 编辑器配置文件
+- 格式化规则设置
+- 自动化工具配置
+- 集成工具设置
+
+### 5.4 文件命名规范
+
+#### 5.4.1 基本原则
+
+- **使用有意义的文件名**：体现文档内容，便于快速识别
+- **采用中文命名**：便于团队理解，符合项目本地化需求
+- **避免特殊字符**：不使用空格、特殊符号等可能导致问题的字符
+- **使用下划线或连字符**：分隔词语，提高可读性
+- **包含版本信息**：如适用，在文件名中体现版本号
+
+#### 5.4.2 文档类型命名规范
+
+**指南文档命名**
+
+- **主文档**：每个技能目录必须包含 `SKILL.md`，并在 YAML frontmatter 中声明与目录同名的 `name`
+- **指南文档**：围绕主题命名，如 `Quickstart.md`、`最佳实践.md`、`检查清单.md`
+- **模板文档**：`[模板类型]模板.md`
+- **草稿文档**：`Draft_[文档名称].md`
+
+**示例**：
+
+```
+需求收集指南.md → requirements/intake/SKILL.md
+需求文档撰写指南.md → requirements/documentation/SKILL.md
+产品需求草稿.md → requirements/documentation/template/Draft_产品需求草稿.md
+```
+
+#### 5.4.3 文件夹命名规范
+
+**文件夹命名原则**
+
+- **去除冗余后缀**：避免使用"指南"、"文档"等冗余后缀
+- **简洁明了**：使用核心功能词，便于理解和导航
+- **保持一致性**：同类文件夹使用统一的命名模式
+- **层级清晰**：通过命名体现文件夹的层级关系
+
+**命名示例**：
+
+```
+需求收集工具指南/ → requirements/intake/
+需求文档指南/ → requirements/documentation/
+立项规划指南/ → requirements/initiative_planning/
+需求迭代文档/ → requirements-iteration/
+需求评审指南/ → requirements/review/
+```
+
+#### 5.4.4 版本管理规范
+
+**语义化版本控制**
+
+- **主版本号**：重大变更时递增（如 v1.0 → v2.0）
+- **次版本号**：功能增加时递增（如 v1.0 → v1.1）
+- **修订版本号**：错误修复时递增（如 v1.0.0 → v1.0.1）
+
+**版本文件夹命名**
+
+```
+v1.0.0/          # 主版本文件夹
+v1.1.0/          # 次版本文件夹
+v2.0.0/          # 重大版本文件夹
+```
+
+#### 5.4.5 特殊文件命名
+
+**模板文件**
+
+- **索引文件**：`index.md` - 提供导航和概览
+- **模块化模板**：`[序号]_[模块名称].md` - 如 `1_产品定位与分析.md`
+- **草稿模板**：`Draft_[模板名称].md` - 如 `Draft_产品需求草稿.md`
+
+**配置文件**
+
+- **配置文件**：`config.[扩展名]` 或 `[功能].config.[扩展名]`
+- **检查清单**：`[功能]检查清单.md`
+- **参考资料**：`[主题]参考资料.md`
+
+### 5.5 引用规范
+
+#### 5.5.1 路径引用原则
+
+在文档中引用其他文件时，应：
+
+- **使用相对路径引用**：确保文档的可移植性
+- **提供清晰的链接描述**：让读者明确链接内容
+- **确保链接的有效性**：定期检查和更新链接
+- **保持路径一致性**：统一使用相对路径格式
+
+#### 5.5.2 路径更新规范
+
+**重命名后的路径更新**
+
+当文件夹或文件重命名后，必须更新所有相关引用：
+
+1. **主文档引用**：更新主入口 `SKILL.md` 或索引 `README.md` 中的目录链接
+2. **交叉引用**：更新各文档间的相互引用
+3. **模板引用**：更新模板中的路径引用
+4. **外部引用**：更新其他项目文档中的引用
+
+**更新检查清单**：
+
+- [ ] 主入口 `SKILL.md` / `README.md` 中的目录链接
+- [ ] 各子文件夹 `SKILL.md` 中的交叉引用
+- [ ] 模板文件中的路径引用
+- [ ] 项目根目录文件中的引用（如顶层 README 或 AGENTS.md）
+- [ ] 其他模块文档中的引用
+
+#### 5.5.3 引用示例
+
+**标准引用格式**：
+
+```markdown
+# 文档引用
+- 参考模板：[指南文档标准模板](/Users/wuchong/Develop/AI_Product_Kit/mcp/.doc_cache/04e80f12d73851a2_指南文档标准模板.md)
+- 查看模板：[工具使用指南模板](/Users/wuchong/Develop/AI_Product_Kit/mcp/.doc_cache/07cc092c31fd7015_工具使用指南模板.md)
+- 相关资料：[术语表](references/术语表.md)
+
+# 目录引用
+- [需求收集](./requirements/intake/) - 需求收集工具使用指南
+- [需求文档](./requirements/documentation/) - 需求文档撰写指南
+
+# 模板引用
+- [产品需求草稿模板](./template/Draft_产品需求草稿.md)
+- [功能需求模板](./template/2_功能需求.md)
+```
+
+#### 5.5.4 路径管理最佳实践
+
+**避免绝对路径**
+
+```markdown
+# 错误示例
+/../requirements/documentation/SKILL.md
+
+# 正确示例
+./requirements/documentation/SKILL.md
+../requirements/intake/SKILL.md
+```
+
+**使用描述性链接**
+
+```markdown
+# 错误示例
+[点击这里](./template/1_产品定位与分析.md)
+
+# 正确示例
+[产品定位与分析模板](./template/1_产品定位与分析.md)
+```
+
+### 5.6 模板撰写规范
+
+#### 5.6.1 模板内容分类
+
+模板文件应明确区分两类内容：
+
+- **模板内容**：需要被填充和输出的实际内容结构，包括占位符、章节骨架、示例字段等
+- **规范说明内容**：用于指导如何填写模板的说明性文字，包括使用说明、格式规范、检查清单等
+
+#### 5.6.2 规范说明内容的标记方式
+
+所有规范说明内容必须使用HTML注释格式进行标记，确保在使用模板生成最终文档时不会被输出。
+
+**标准标记格式**：
+
+```markdown
+<!-- ⚠️ 以下为规范说明，请勿输出到最终文档 ⚠️ -->
+[规范说明内容，如使用说明、格式规范、检查清单等]
+<!-- ⚠️ 规范说明结束 ⚠️ -->
+```
+
+**完整章节标记**：
+
+对于整个章节都是规范说明的情况（如"模板使用说明"章节），使用以下格式：
+
+```markdown
+---
+
+<!-- ============================================
+⚠️ 模板规范说明区域 - 请勿输出到最终文档 ⚠️
+============================================
+以下内容为模板使用规范和说明，仅用于指导如何填写模板，
+在使用模板生成最终文档时，应完全删除或忽略此部分内容。
+============================================ -->
+
+## 模板使用说明
+[规范说明内容]
+```
+
+#### 5.6.3 需要标记的规范说明内容类型
+
+以下类型的内容应标记为规范说明：
+
+- **模板概述和使用指导**：说明模板的用途、使用方式、填写要求等
+- **格式规范说明**：如列表格式规范、加粗格式规范、代码格式规范等
+- **检查清单**：质量检查清单、格式检查清单等
+- **使用示例**：模板使用示例、场景示例等
+- **注意事项和最佳实践**：使用注意事项、常见问题处理等
+- **版本信息**：模板版本号、更新日期、更新说明等
+- **概念说明**：对模板中概念的详细解释和说明
+
+#### 5.6.4 标记示例
+
+**示例1：章节内的规范说明**
+
+```markdown
+#### 2.2.1 完整交互流程
+
+<!-- ⚠️ 以下为规范说明，请勿输出到最终文档 ⚠️ -->
+**重要说明**：以下情况可以省略流程图，直接使用 `*略*` 标记：
+
+* **简单功能场景**：单一操作、无分支判断、无复杂交互
+* **无流程变更场景**：在现有流程基础上增加功能，不改变原有交互逻辑
+<!-- ⚠️ 规范说明结束 ⚠️ -->
+
+[使用Mermaid流程图展示完整的用户交互流程]
+```
+
+**示例2：完整章节的规范说明**
+
+```markdown
+---
+
+<!-- ============================================
+⚠️ 模板规范说明区域 - 请勿输出到最终文档 ⚠️
+============================================
+以下内容为模板使用规范和说明，仅用于指导如何填写模板，
+在使用模板生成最终文档时，应完全删除或忽略此部分内容。
+============================================ -->
+
+## 模板使用说明
+
+### 文档格式规范与检查清单
+[详细规范说明内容]
+```
+
+**示例3：行内规范说明**
+
+```markdown
+**线框示意图**（可选）：
+
+<!-- ⚠️ 以下为规范说明，请勿输出到最终文档 ⚠️ -->
+*当页面布局复杂或包含多个组件时，提供线框示意图*
+<!-- ⚠️ 规范说明结束 ⚠️ -->
+```
+
+#### 5.6.5 模板撰写检查清单
+
+在创建或更新模板文件时，应检查：
+
+- [ ] 所有规范说明内容已使用HTML注释标记
+- [ ] 标记格式统一，使用标准标记符号
+- [ ] 模板内容和规范说明内容清晰区分
+- [ ] 规范说明内容不影响模板的可读性
+- [ ] 使用模板时能够明确识别哪些内容需要删除
+
+#### 5.6.6 使用模板时的处理原则
+
+在使用模板生成最终文档时：
+
+1. **删除规范说明**：删除所有标记为规范说明的内容（HTML注释及其包裹的内容）
+2. **保留模板内容**：保留所有未标记的模板内容，包括占位符、章节结构等
+3. **替换占位符**：将模板中的占位符替换为实际内容
+4. **删除注释标记**：确保最终文档中不包含HTML注释标记
+
+## 6. 模板引用
+
+本规范提供了标准的文档模板，可根据不同类型的指南文档选择使用：
+
+- **标准指南文档模板**：[`skills/guide_writing_standard/template/指南文档标准模板.md`](/Users/wuchong/Develop/AI_Product_Kit/mcp/.doc_cache/04e80f12d73851a2_指南文档标准模板.md)
+- **工具使用指南模板**：[`skills/guide_writing_standard/template/工具使用指南模板.md`](/Users/wuchong/Develop/AI_Product_Kit/mcp/.doc_cache/07cc092c31fd7015_工具使用指南模板.md)
+
+使用模板时，请根据具体需求调整章节结构和内容，确保符合本规范的要求。