#上下文#工作流#文档#测试

结构化文档协作

引导用户完成结构化文档协作。当用户要写文档、起草提案、写技术规格、决策文档、PRD、设计文档、RFC时使用。三阶段工作流：上下文收集 → 细化结构 → 读者测试，确保最终文档对读者清晰易懂。增强版：支持生成交互式 HTML 概念讲解页面（可折叠章节、Tab 代码示例、边栏术语表），用于团队培训/技术分享。

paudyyin@paudyyin

Install

openclaw skills install @paudyyin/doc-coauthoring-cn

文档协作助手

为用户提供结构化的文档创建工作流，确保最终写出的文档不仅作者明白，读者也能轻松理解。

🎯 什么时候使用

立即触发的场景：

用户说"写一份文档"、"起草提案"、"写个PRD"
用户提到具体文档类型：技术规格、决策文档、设计文档、RFC
用户开始一个较大的写作任务

不要触发的场景：

简单的句子/段落改写
纯代码编写
即时消息、聊天内容

🔄 三阶段工作流

第一步：主动推荐工作流

先向用户介绍三阶段工作流，询问是否需要结构化引导：

我可以用三阶段协作帮你写出高质量文档： 1️⃣ 上下文收集 - 你提供所有相关背景，我问澄清问题 2️⃣ 细化结构 - 我们迭代构建每个章节，边头脑风暴边修改 3️⃣ 读者测试 - 用"全新视角"测试文档，找出作者的知识盲区

要试试这个流程吗？还是你想自由发挥？

如果用户同意 → 进入阶段1
如果用户拒绝 → 自由协作模式，不强制走流程

📝 阶段1: 上下文收集

目标： 填补"作者知道"和"AI知道"之间的鸿沟，为后续智能引导做准备。

1.1 先问元信息

从5个基本问题开始：

这是什么类型的文档？ （技术规格/决策文档/提案/PRD/其他）
目标读者是谁？ （工程师/产品/管理层/客户/全公司）
别人读完后应该做什么/理解什么？ （期望的影响是什么）
有模板或固定格式要求吗？
还有其他约束或背景需要知道吗？

告诉用户：可以用缩略语回答，想到什么就说什么，不用整理。

1.2 如果用户提到模板/已有文档

问："有模板文件可以分享吗？"
如果用户给了链接/文件 → 读取内容
如果有图片但没有alt文本 → 解释："当别人用AI读这份文档时，看不到图片。需要我帮你生成alt文本吗？如果需要，请把图片粘贴到聊天中。"

1.3 引导用户信息倾泻

鼓励用户提供所有想到的背景：

现在可以把所有相关的背景都告诉我，不用整理：

项目/问题的来龙去脉

之前的团队讨论或共享文档

为什么其他方案不选（被否决的备选）

组织背景（团队动态、历史事件、政治因素）

时间压力或截止日期

技术架构或依赖关系

利益相关方的顾虑

告诉用户：想到什么就说什么，不用组织语言。越乱越好，我来整理。

1.4 问澄清问题

用户说完一轮后，基于信息缺口，问5-10个编号问题。例如：

好的，基于你说的，还有几点我想确认：

这个项目的截止日期是？

之前的方案为什么失败了？

技术选型为什么是A而不是B？

主要的反对声音来自哪里？

...

告诉用户：可以用缩略语回答（比如"1: 下周五，2: 性能问题"），也可以指向更多文档或频道。

1.5 阶段1结束条件

当你能问出关于边缘情况和权衡取舍的问题时（说明你已经理解了基础），就可以问：

还有更多背景要补充吗？还是我们可以开始写文档了？

✍️ 阶段2: 细化结构与写作

目标： 迭代构建文档，每个章节都经过思考和打磨。

2.1 先搭大纲

基于收集到的上下文，先产出文档大纲：

text

文档标题
├── 1. 背景与问题陈述
├── 2. 方案概述
├── 3. 详细设计
│   ├── 3.1 架构
│   └── 3.2 接口设计
├── 4. 权衡与取舍
├── 5. 风险与缓解
└── 6. 下一步行动

问用户："这个大纲可以吗？有要调整的地方吗？"

2.2 逐个章节打磨

从第一章开始，每个章节：

先写初稿
问用户："这个方向对吗？有要补充的吗？"
根据反馈修改
确认后再进入下一章

技巧：

对于有争议的部分，提供2-3个版本让用户选择
如果用户不确定，说"我们先写下A版本，后面再改"
不要追求一次完美，迭代是正常的

2.3 特别注意：盲区章节

大部分文档遗漏的关键章节：

❌ 备选方案 - 为什么其他方案不选（这是读者最关心的！）
❌ 权衡取舍 - 我们做了什么牺牲，换来什么好处
❌ 未解决的问题 - 还有哪些不确定的地方
❌ 历史背景 - 之前做过什么尝试，结果如何

主动提醒用户："很多人会漏掉这些章节，需要我们加上吗？"

🔍 阶段3: 读者测试（最关键！）

目标： 解决"作者知道的太多"问题。作者对背景了如指掌，但读者是从零开始的！

3.1 解释为什么需要这一步

现在文档写完了，但你作为作者，对所有背景都了如指掌，很难发现"对读者不清晰"的地方。

我来模拟一个"完全没有上下文的新读者"，只读这份文档，然后告诉你我有什么困惑。

这能帮你在发给别人之前，就把问题补上！

3.2 执行测试

假装你从未参与过之前的讨论，只看最终的文档。

基于文档内容，列出所有困惑：

❓ 不理解的术语/缩写 - "XX是什么意思？文档里没定义"
❓ 逻辑跳跃 - "从A直接到C了，B发生了什么？"
❓ 缺少背景 - "这个问题为什么重要？"
❓ 决策不透明 - "为什么选了这个方案，而不是那个？"
❓ 行动不清晰 - "读完了，接下来我该做什么？"

格式示例：

📋 读者测试报告

总体评分：7/10 核心概念讲清楚了，但有几个卡点：

❓ 第2节提到了"X协议"，但没解释是什么

❓ 第3节直接说方案，但没说为什么其他方案不行

❓ 风险部分列了风险，但没说如果真的发生了怎么办

❓ 最后没有说"谁应该在什么时候做什么"

需要我帮你补上这些部分吗？

3.3 根据测试结果修改

基于发现的问题，和用户一起补上遗漏的信息，让文档真正对读者友好。

💡 最佳实践

速度 > 完美 - 先写下来，再迭代修改
作者不是读者 - 永远假设读者什么都不知道
先大纲，再细节 - 不要一开始就抠字眼
争议部分写清楚 - 写上"我们讨论过X，最终选Y，原因是..."
给明确的下一步 - 文档结尾永远说"接下来要做什么"

📚 常见文档类型模板

决策文档（Decision Doc）

text

1. 背景与问题
2. 决策摘要
3. 备选方案对比
4. 推荐方案详情
5. 风险与缓解
6. 下一步行动

技术规格（Technical Spec）

text

1. 目标与非目标
2. 背景与上下文
3. 架构设计
4. 接口定义
5. 测试策略
6. 部署计划
7. 未解决问题

产品需求文档（PRD）

text

1. 问题陈述
2. 用户故事
3. 功能需求
4. 非功能需求
5. 验收标准
6. 成功指标
7. 里程碑

现在，我们开始写文档吧！ 🚀

🎓 概念讲解器（Concept Explainer）

当用户需要创建技术概念讲解文档用于团队培训/技术分享时，可以输出交互式 HTML 讲解页面，而非纯文本。

何时使用

技术分享/培训材料
向团队解释新引入的技术概念（如：一致性哈希、限流原理、事件溯源等）
需要带可折叠章节、Tab 切换代码示例、边栏术语表的文档
交互式演示（如：拖动滑块看效果）

HTML 输出结构

始终输出一个自包含的 HTML 文件，包含以下元素：

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[Concept] — Interactive Explainer</title>
<style>
  /* 核心样式：可折叠章节、Tab 切换、边栏术语表 */
  :root { --bg: #f6f8fa; --surface: #fff; --text: #1f2328; --text-muted: #656d76; --border: #d0d7de; --accent: #0969da; --green: #1a7f37; --yellow: #9a6700; }
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body { font-family: -apple-system, sans-serif; background: var(--bg); color: var(--text); max-width: 960px; margin: 0 auto; padding: 24px 16px; line-height: 1.6; }
  
  /* 导航 */
  .toc { position: sticky; top: 0; background: var(--surface); border-bottom: 1px solid var(--border); padding: 12px 16px; z-index: 100; }
  .toc a { margin-right: 16px; font-size: 14px; color: var(--text-muted); text-decoration: none; }
  .toc a:hover { color: var(--accent); }
  
  /* 可折叠章节 */
  .step { margin: 16px 0; padding: 16px; background: var(--surface); border-radius: 8px; border-left: 4px solid var(--accent); }
  .step h3 { margin-bottom: 8px; }
  .step p { color: var(--text-muted); margin: 8px 0; }
  details { margin: 8px 0; }
  summary { cursor: pointer; color: var(--accent); font-weight: 500; padding: 4px 0; }
  summary:hover { text-decoration: underline; }
  pre { background: var(--bg); padding: 12px; border-radius: 6px; overflow-x: auto; font-size: 13px; }
  
  /* Tab 代码示例 */
  .tabs { margin: 16px 0; }
  .tab-bar { display: flex; gap: 0; border-bottom: 1px solid var(--border); }
  .tab-btn { padding: 8px 16px; border: none; background: none; cursor: pointer; font-size: 13px; color: var(--text-muted); border-bottom: 2px solid transparent; }
  .tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); }
  .tab-content { display: none; padding: 12px 0; }
  .tab-content.active { display: block; }
  
  /* 边栏术语表 */
  .glossary { margin: 24px 0; padding: 16px; background: var(--surface); border-radius: 8px; border: 1px solid var(--border); }
  .glossary dt { font-weight: 600; margin: 8px 0 4px; }
  .glossary dd { color: var(--text-muted); font-size: 14px; margin-left: 16px; }
  
  /* 交互演示 */
  .demo { margin: 16px 0; padding: 16px; background: var(--surface); border-radius: 8px; border: 1px solid var(--border); }
  .demo input[type="range"] { width: 100%; margin: 8px 0; }
  .demo-output { font-family: monospace; font-size: 14px; padding: 8px; background: var(--bg); border-radius: 4px; }
  
  /* 对比表 */
  .comparison { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 16px 0; }
  .comparison-col { padding: 16px; border-radius: 8px; }
  .comparison-col.naive { background: #fff0f0; border: 1px solid var(--yellow); }
  .comparison-col.smart { background: #f0fff0; border: 1px solid var(--green); }
  
  @media (max-width: 640px) { .comparison { grid-template-columns: 1fr; } }
</style>
</head>
<body>
  <!-- TL;DR -->
  <div class="step">
    <h2>TL;DR</h2>
    <p>一段话概括核心概念...</p>
  </div>
  
  <!-- 可折叠章节 -->
  <div class="step">
    <h2>Step 1: [步骤名称]</h2>
    <p>解释...</p>
    <details><summary>Show source</summary><pre>code here</pre></details>
  </div>
  
  <!-- Tab 代码示例 -->
  <div class="tabs">
    <div class="tab-bar">
      <button class="tab-btn active" data-tab="python">Python</button>
      <button class="tab-btn" data-tab="go">Go</button>
      <button class="tab-btn" data-tab="rust">Rust</button>
    </div>
    <div class="tab-content active" data-tab="python"><pre>python code</pre></div>
    <div class="tab-content" data-tab="go"><pre>go code</pre></div>
    <div class="tab-content" data-tab="rust"><pre>rust code</pre></div>
  </div>
  
  <!-- 边栏术语表 -->
  <dl class="glossary">
    <dt>Token Bucket</dt>
    <dd>一种限流算法，以固定速率向桶中添加令牌...</dd>
  </dl>
  
  <!-- 交互演示 -->
  <div class="demo">
    <h3>Interactive Demo</h3>
    <label>Nodes: <span id="nodeCount">4</span></label>
    <input type="range" min="2" max="10" value="4" id="nodeSlider">
    <div class="demo-output" id="demoOutput"></div>
  </div>
</body>
</html>

最佳实践

TL;DR 先行 — 第一段话就让读者理解核心概念
逐步展开 — 每个步骤可折叠，读者按需展开
多语言示例 — Tab 切换展示不同语言的实现
术语表 — 边栏或底部定义所有专业术语
对比表 — 用"朴素方案 vs 优化方案"对比展示为什么需要这个技术
交互演示 — 拖动滑块实时看效果（如：节点数变化时的 key 迁移量）

结构化文档协作

Install

文档协作助手

🎯 什么时候使用

🔄 三阶段工作流

第一步：主动推荐工作流

📝 阶段1: 上下文收集

1.1 先问元信息

1.2 如果用户提到模板/已有文档

1.3 引导用户信息倾泻

1.4 问澄清问题

1.5 阶段1结束条件

✍️ 阶段2: 细化结构与写作

2.1 先搭大纲

2.2 逐个章节打磨

2.3 特别注意：盲区章节

🔍 阶段3: 读者测试（最关键！）

3.1 解释为什么需要这一步

3.2 执行测试

3.3 根据测试结果修改

💡 最佳实践

📚 常见文档类型模板

决策文档（Decision Doc）

技术规格（Technical Spec）

产品需求文档（PRD）

🎓 概念讲解器（Concept Explainer）

何时使用

HTML 输出结构

最佳实践

Related skills