Imported from atom-set/prompt-engin (skills/documentation/wiki-output/SKILL.md). Install upstream with npx skills add atom-set/prompt-engin --skill wiki-output. Copyright stays with the author.

WIKI 输出规范

使用场景

当用户需要：

• 输出 WIKI 文档时
• 生成项目文档时
• 创建技术文档时

触发条件

以下情况自动应用此规范：

• 用户要求输出 WIKI 时
• 检测到需要 WIKI 格式时

与其他规则的配合

• 与 document-format 配合：确保文档格式正确
• 与核心规则配合使用

强制要求

• 核心原则：WIKI 文档必须结构清晰、易于导航、便于维护
• 适用范围：所有 WIKI 文档，包括项目文档、技术文档、使用说明等

文档结构要求

基本结构（总分总格式）

WIKI 文档必须遵循总分总结构，确保内容逻辑清晰：

1. 总（开头）：文档概述

   • 提供文档的目的、背景和核心内容概述
   • 包含文档目录（如果文档较长）
   • 简要说明文档要解决的问题或要传达的信息
   • 目的：让读者快速了解文档主旨，建立阅读预期

2. 分（主体）：详细内容部分

   • 按照逻辑顺序组织内容，使用清晰的标题层级
   • 每个小节应有明确的主题，内容详实
   • 可以包括：详细说明、代码示例、配置说明、使用场景等
   • 目的：提供充分的信息支撑，让读者深入理解主题

3. 总（结尾）：总结部分

   • 总结文档的核心要点
   • 提供相关链接和参考资料
   • 可以包括：关键信息汇总、下一步行动、相关文档链接等
   • 目的：强化核心信息，帮助读者形成清晰的认识

标题层级要求

• 一级标题（H1）：文档主标题，每个文档只有一个
• 二级标题（H2）：主要章节，用于划分文档的主要部分
• 三级标题（H3）：小节标题，用于细分章节内容
• 四级标题（H4）：子小节标题，用于进一步细分
• 层级限制：建议不超过 4 级标题，保持结构简洁

目录要求

• 长文档必须包含目录：文档超过 3 个主要章节时，应在开头提供目录
• 目录格式：使用 Markdown 的目录语法或手动维护链接列表
• 目录更新：文档结构变更时，及时更新目录

内容格式要求

文本格式

• 强调：使用 **粗体** 强调重要信息，使用 *斜体* 表示次要强调
• 代码引用：行内代码使用反引号 `code`，代码块使用三个反引号
• 列表：使用有序列表表示步骤，使用无序列表表示并列项
• 引用：使用 > 表示引用内容

表格格式

• 必须使用表格形式展示结构化数据
• 表格对齐：左对齐文本，右对齐数字
• 表格标题：复杂表格应添加标题或说明
• 示例格式：

  | 列1 | 列2 | 列3 |
  |-----|-----|-----|
  | 数据1 | 数据2 | 数据3 |

代码块格式

• 必须指定语言：代码块必须标注语言类型（如 python、bash、javascript）
• 代码注释：复杂代码应添加注释说明
• 代码示例：提供完整可运行的代码示例，避免片段代码
• 代码位置：如果代码来自项目文件，应标注文件路径

链接和引用

• 内部链接：使用相对路径链接到其他 WIKI 页面
• 外部链接：外部链接应在新标签页打开，并标注链接类型
• 锚点链接：长文档应使用锚点链接方便跳转
• 引用格式：引用其他文档时，应标注来源和版本

图片和图表

• 图片格式：优先使用 PNG 或 SVG 格式
• 图片背景：所有图片必须使用白色背景（白底）
• 图片说明：所有图片必须包含说明文字
• 图片路径：使用相对路径，统一存放在 images/ 或项目根目录的 assets/ 目录
• 图表工具：流程图使用 Mermaid，架构图使用 PlantUML 或 Mermaid

Mermaid 图表转换工具

WIKI 文档中的 Mermaid 图表应使用 mermaid_to_png.sh 脚本转换为 PNG 图片：

• 工具位置：.claude/skills/documentation/wiki-output/scripts/mermaid_to_png.sh
• 功能说明：将 Mermaid 流程图代码转换为 PNG 图片文件（自动使用白色背景）
• 使用场景：当 WIKI 平台不支持 Mermaid 渲染时，使用此工具生成图片

使用方法（在项目根目录执行）：

# 定义脚本路径变量（一次性设置）
MERMAID_SCRIPT=".claude/skills/documentation/wiki-output/scripts/mermaid_to_png.sh"

# 从文件转换
bash "$MERMAID_SCRIPT" diagram.mmd assets/

# 从标准输入转换
echo "graph TD; A-->B" | bash "$MERMAID_SCRIPT" assets/

# 自动生成文件名
bash "$MERMAID_SCRIPT" input.mmd assets/
# 输出: assets/mermaid_20240129_123456.png

依赖要求：

• Node.js
• npm
• @mermaid-js/mermaid-cli (mmdc)

安装依赖：

# 安装 Node.js: https://nodejs.org/
# 安装 mermaid-cli
npm install -g @mermaid-js/mermaid-cli

最佳实践：

• 将转换后的 PNG 图片统一存放在项目根目录的 assets/ 目录
• 在 WIKI 文档中引用图片时，使用相对路径
• 为每个图片添加说明文字，说明图表的内容和用途
• 保留 Mermaid 源代码文件（.mmd），便于后续更新和维护

批量转换工具

当文档中包含大量 Mermaid 图表时，可以使用批量转换工具自动提取并转换：

• 工具位置：.claude/skills/documentation/wiki-output/scripts/extract_and_convert_mermaid.py
• 功能说明：自动提取 Markdown 文档中的所有 Mermaid 图表，根据章节标题自动命名并批量转换为 PNG 图片
• 使用场景：将包含多个 Mermaid 图表的 Markdown 文档转换为 WIKI 版本

使用方法（在项目根目录执行）：

# 定义脚本路径变量（一次性设置）
MERMAID_BATCH=".claude/skills/documentation/wiki-output/scripts/extract_and_convert_mermaid.py"

# 批量转换
python3 "$MERMAID_BATCH" docs/架构图.md assets/

参数说明：

• markdown_file：包含 Mermaid 图表的 Markdown 文件路径
• output_dir：输出目录，默认为 ./assets/batch-logger

功能特性：

1. 自动提取：自动识别并提取文档中所有 Mermaid 代码块
2. 智能命名：根据图表前的章节标题（H3、H4）自动生成有意义的文件名
3. 批量转换：调用 scripts/mermaid_to_png.sh 批量转换为 PNG 图片（白色背景）
4. 生成清单：自动生成 image_list.txt 文件，记录所有图片文件名和对应标题

使用示例：

# 定义变量后使用
MERMAID_BATCH=".claude/skills/documentation/wiki-output/scripts/extract_and_convert_mermaid.py"
python3 "$MERMAID_BATCH" \
    "docs/04.批量上报与数据压缩优化/架构图.md" \
    "assets/batch-logger"

# 输出结果：
# assets/batch-logger/
#   ├── 1-1-1-日志收集层架构图.png
#   ├── 1-1-2-队列管理层架构图.png
#   ├── 1-1-3-上报执行层架构图.png
#   ├── ...
#   └── image_list.txt

文件命名规则：

• 提取章节编号（如 1.1.1）并替换为连字符（如 1-1-1）
• 提取章节名称作为文件名的一部分
• 格式：{章节编号}-{章节名称}.png
• 示例：1-1-1-日志收集层架构图.png

输出清单文件：

image_list.txt 文件格式（制表符分隔）：

1-1-1-日志收集层架构图.png	1.1.1 日志收集层架构图
1-1-2-队列管理层架构图.png	1.1.2 队列管理层架构图
...

工作流程：

1. 运行批量转换工具，生成所有 PNG 图片
2. 查看 image_list.txt 了解图片清单
3. 在 WIKI 文档中使用相对路径引用图片
4. 为每个图片添加说明文字

时间格式要求

WIKI 文档中的时间格式必须遵循时间格式规范：

重要提醒：

• ✅ 创建时间：必须使用文档实际创建时间（本地时间），禁止使用假设日期
• ✅ 更新时间：文档更新时，更新最后修改时间，禁止使用假设日期
• ❌ 禁止：使用固定日期占位符，必须使用动态获取的实际时间

获取时间方法：参见"时间格式规范"章节的详细说明

文档元信息

文档头部信息

每个 WIKI 文档应在开头包含以下元信息（可选，但推荐）：

---
title: 文档标题
description: 文档描述
author: 作者
created: YYYY-MM-DD（本地时间）  # 必须使用文档实际创建时间，禁止使用假设日期
updated: YYYY-MM-DD（本地时间）  # 必须使用文档实际更新时间，禁止使用假设日期
version: 1.0
tags: [标签1, 标签2]
---

版本管理

• 版本号：重要文档应标注版本号
• 更新日志：重大更新应在文档中记录更新日志
• 变更说明：文档结构或内容重大变更时，应在开头说明

适用场景

以下类型的 WIKI 文档应遵循此规范：

• ✅ 项目文档：项目介绍、架构说明、开发指南等
• ✅ 技术文档：API 文档、技术方案、设计文档等
• ✅ 使用说明：用户手册、操作指南、配置说明等
• ✅ 知识库：常见问题、最佳实践、经验总结等
• ✅ 其他 WIKI 文档：任何需要在 WIKI 中展示的文档

重要原则

1. 结构清晰：确保文档结构层次分明，易于导航
2. 内容完整：提供充分的信息，避免信息缺失
3. 格式统一：遵循统一的格式规范，保持文档风格一致
4. 易于维护：文档应易于更新和维护，避免冗余内容
5. 用户友好：从读者角度组织内容，提供清晰的导航和链接
6. 时间准确：所有时间信息必须使用本地时间，并标注时区
7. 链接有效：确保所有链接有效，定期检查并更新失效链接

注意事项

1. 强制要求：所有 WIKI 文档必须遵循此规范
2. 一致性要求：同一项目的 WIKI 文档应保持格式一致
3. 更新要求：文档更新时，同步更新元信息和目录
4. 审查要求：重要文档发布前应进行格式审查
5. 时间要求：时间信息必须使用本地时间，禁止使用固定的假设日期
6. 创建时间要求：创建时间必须使用文档实际创建时间，禁止使用假设日期
7. 更新时间要求：更新时间必须使用文档实际更新时间，禁止使用假设日期
8. 格式说明：规则中的格式示例（如 YYYY-MM-DD）仅用于说明格式结构，实际使用时必须使用动态获取的时间