Diátaxis 文档框架实践

快速开始

在创建或重构文档时：

写作前问题（必须提问）

开始前，请向用户确认以下问题：

1. 语言偏好：“该文档应使用哪种语言编写？”

   • English / 中文 / 其他

2. 输出方式：“完成后，您希望以何种方式输出该文档？”

   • 聊天消息（默认）
   • 飞书文档（通过 MCP/mcporter）
   • 本地 Markdown 文件
   • GitHub 仓库
   • 其他平台

工具可用性检查（用户选择后执行）

用户选定输出方式后，自动检测相关工具是否可用：

# 运行自动检测（脚本位于相对于本技能文件的 ./scripts/ 目录下）
python3 scripts/output-handler.py --detect

检查结果：

• ✅ 工具可用 → 按所选输出方式继续执行
• ⚠️ 工具不可用 → 告知用户并推荐替代方案

针对通过 MCP 输出至飞书的情况：

• 检查 mcporter 是否已安装
• 检查 MCP 飞书服务是否已配置（通常位于 /root/config/mcporter.json 或 ~/.mcporter/mcporter.json）
• 测试与飞书 MCP 服务器的连接

若工具不可用：

1. 通知用户：“所选输出方式 [X] 当前不可用”
2. 推荐可选项：“当前可用方式：[列表]”
3. 请用户确认替代方案，或自行完成工具配置

写作工作流

在确认语言、输出偏好及工具可用性后：

1. 识别用户需求 —— 使用 Diataxis 指南针（Compass）确定文档类型
2. 选择模板 —— 从 templates/ 目录中选取对应模板
3. 应用检查清单 —— 写作过程中参照对应类型的检查清单
4. 质量评估 —— 使用质量评估框架对终稿进行评审
5. 执行输出 —— 按用户指定的语言与方式输出文档

四类文档类型

Diataxis 将文档划分为四种本质不同的类型，分别对应四类用户需求：

各类型详细说明

• 教程：references/four-types.md#Tutorial
• 操作指南：references/four-types.md#How-to Guide
• 参考文档：references/four-types.md#Reference
• 说明文档：references/four-types.md#Explanation

使用 Diataxis 指南针（Compass）

当不确定文档类型时，可使用指南针工具：references/compass.md

需回答两个关键问题：

1. 内容性质：属于操作指导（action）还是认知知识（cognition）？
2. 用户状态：用户正处于技能获取阶段（acquisition/study），还是技能应用阶段（application/work）？

常见使用场景

场景 1：故障排查记录 → 操作指南 或 说明文档

故障排查记录通常归属为：

• 操作指南：若内容为“如何解决 X 问题”的分步指导
• 说明文档：若内容为“X 问题为何发生”的原理分析

模板：templates/template-troubleshooting.md

场景 2：经验总结 → 操作指南 或 说明文档

• 最佳实践：操作指南（指导如何正确执行）
• 踩坑总结：说明文档（解释为何某些做法不妥）

模板：templates/template-best-practices.md

场景 3：学习笔记 → 教程 或 说明文档

• 学习笔记：教程（含实操步骤）
• 理论摘要：说明文档（侧重概念性理解）

模板：templates/template-learning-notes.md

场景 4：探索性分享 → 说明文档

技术探索、实验记录、对比分析等内容通常归属为说明文档。

模板：templates/template-exploration.md

检查清单

写作过程中及完成后请使用对应检查清单：

• 教程：checklist/checklist-tutorial.md
• 操作指南：checklist/checklist-how-to.md
• 参考文档：checklist/checklist-reference.md
• 说明文档：checklist/checklist-explanation.md

质量评估

使用功能质量（Functional Quality）与深度质量（Deep Quality）框架：references/quality-framework.md

功能质量

• 准确性、完整性、一致性、可用性、精确性

深度质量

• 行文流畅度、契合用户真实需求、美感、前瞻性地预判用户需求

常见错误

避免以下典型错误模式：references/common-mistakes.md

1. 类型混淆 —— 在教程中混入参考文档内容
2. 类型错置 —— 将说明文档写成教程
3. 边界模糊 —— 在操作指南中掺杂过多解释性内容
4. 结构失配 —— 参考文档未能反映产品实际架构

语言风格

四类文档采用不同语言风格：references/writing-language.md

• 教程：“我们将……”、“请注意……”、“现在执行 X……”
• 操作指南：“如需实现 X，请执行 Y”、“完整选项请参阅 X 文档”
• 参考文档：“X 继承自 Y”、“子命令：a、b、c”、“必须使用 X”
• 说明文档：“X 的原因是……”、“W 优于 Z 是因为……”

输出方式

文档完成后，按用户选定的方式输出：

可用输出方式

1. 聊天消息 —— 直接在对话中展示（默认）
2. 飞书文档 —— 通过 MCP/mcporter 创建/更新飞书文档（需配置 MCP 飞书服务）
3. 本地 Markdown —— 保存为 .md 文件（内置支持）
4. GitHub 仓库 —— 提交至代码仓库（需配置 MCP github 或 git）
5. 其他平台 —— 用户提供平台信息及对应 MCP 能力

重要提示：飞书输出必须使用 MCP/mcporter 方式，不得使用频道工具。

检测可用工具

使用 scripts/output-handler.py 自动检测（脚本位于相对于本技能文件的 ./scripts/ 目录下）：

python3 scripts/output-handler.py --detect

工具可用性检查

用户选定输出方式后，检查工具是否可用：

1. 运行 output-handler.py --detect
2. 检查所选工具是否已配置且可用
3. 若不可用：
   • 通知用户：“所选输出方式 [X] 当前不可用”
   • 从可用工具列表中推荐替代方案
   • 请用户确认替代方式

选择输出方式

必须向用户确认：“文档已完成，您希望以何种方式输出？”

根据用户选择执行：

• 聊天 → 直接回复
• 飞书（MCP） → 使用 mcporter 调用飞书 MCP 服务器

  node /path/to/mcporter/dist/cli.js call feishu doc.create '{"title":"...", "content":"..."}'
  # 注意：mcporter 路径依安装方式而异，常见路径包括：
  # - ~/.npm/_npx/*/node_modules/mcporter/dist/cli.js
  # - 或使用：npx mcporter call feishu doc.create ...
  

• 本地 → 调用 write 工具，或执行 output-handler.py --output local
• GitHub → 执行 output-handler.py --output github
• 其他 → 请用户提供 MCP 服务相关信息

语言注意事项

按用户选定语言输出：

• 若为 English → 输出英文
• 若为 中文 → 输出中文
• 若为其他语言 → 确认系统是否支持相应翻译能力

输出平台详情

完整平台列表及配置方法：references/output-platforms.md

理论框架

完整的 Diataxis 理论体系：

• 地图模型（Map Model）：references/map.md
• 理论基础：references/four-types.md
• 质量理论：references/quality-framework.md

使用脚本（可选）

可使用诊断脚本自动识别文档类型（脚本位于相对于本技能文件的 ./scripts/ 目录下）：

python3 scripts/diagnose.py <文档内容或文件路径>

技能版本: 1.0
理论来源: https://diataxis.fr
作者: Zhua Zhua（为 Master 创建）