@xopcai/xopc 0.0.29 → 0.0.31

package/skills/documents/doc-coauthoring/SKILL-zh.md

@@ -0,0 +1,375 @@
+---
+name: doc-coauthoring
+description: 引导用户通过结构化工作流共同撰写文档。当用户想要编写文档、提案、技术规范、决策文档或类似结构化内容时使用。该工作流帮助用户高效传递上下文、通过迭代打磨内容，并验证文档对读者是否有效。当用户提到写文档、起草提案、撰写规范或类似文档任务时触发。
+---
+
+# 文档共同撰写工作流
+
+本技能提供用于引导用户完成协作式文档创建的结构化工作流。作为主动引导者，带领用户经历三个阶段：上下文收集、打磨与结构、读者测试。
+
+## 何时提供此工作流
+
+**触发条件：**
+- 用户提到编写文档："写个文档"、"起草提案"、"创建设计规范"、"写写"
+- 用户提到特定文档类型："PRD"、"设计文档"、"决策文档"、"RFC"
+- 用户似乎要开始一项重要的写作任务
+
+**初始邀请：**
+向用户提供一个结构化的文档共同撰写工作流。解释三个阶段：
+
+1. **上下文收集**：用户提供所有相关上下文，同时 Claude 提出澄清性问题
+2. **打磨与结构**：通过头脑风暴和编辑迭代构建每个章节
+3. **读者测试**：用一个全新的 Claude（无上下文）测试文档，在他人阅读之前发现盲点
+
+解释这种方法有助于确保文档在他人阅读时（包括当他们把文档粘贴给 Claude 时）效果良好。询问他们是否想尝试此工作流，或更倾向于自由写作。
+
+如果用户拒绝，则自由写作。如果接受，进入阶段 1。
+
+## 阶段 1：上下文收集
+
+**目标：** 缩小用户所知与 Claude 所知之间的差距，为后续的智能引导奠定基础。
+
+### 初始问题
+
+首先向用户了解文档的元上下文：
+
+1. 这是什么类型的文档？（如技术规范、决策文档、提案）
+2. 主要读者是谁？
+3. 希望读者阅读后产生什么影响？
+4. 是否有模板或特定格式需遵循？
+5. 还有其他约束或背景需要了解吗？
+
+告知他们可以用简写方式回答，或以最适合他们的方式倾泻信息。
+
+**如果用户提供模板或提到文档类型：**
+- 询问他们是否有模板文档可以分享
+- 如果他们提供共享文档的链接，使用相应的集成工具获取
+- 如果他们提供文件，则读取
+
+**如果用户提到编辑现有的共享文档：**
+- 使用相应集成工具读取当前状态
+- 检查是否有缺少 alt-text 的图片
+- 如果没有 alt-text 的图片，解释当其他人使用 Claude 理解文档时，Claude 无法看到这些图片。询问是否需要生成 alt-text。如果需要，请他们将每张图片粘贴到聊天中以生成描述性 alt-text。
+
+### 信息倾泻
+
+一旦回答了初始问题，鼓励用户倾泻他们拥有的所有上下文。请求的信息包括：
+- 项目/问题的背景
+- 相关的团队讨论或共享文档
+- 为什么不采用替代方案
+- 组织背景（团队动态、过往事件、政治因素）
+- 时间压力或约束
+- 技术架构或依赖关系
+- 利益相关者的关切
+
+告知他们不用操心组织——只管全部倒出来。提供多种提供上下文的方式：
+- 意识流式信息倾泻
+- 指向要阅读的团队频道或讨论串
+- 链接到共享文档
+
+**如果有可用的集成工具**（如 Slack、Teams、Google Drive、SharePoint 或其他 MCP 服务器），告知可以用于直接拉取上下文。
+
+**如果未检测到集成工具且在 Claude.ai 或 Claude 应用中：** 建议他们可以在 Claude 设置中启用连接器，以便从消息应用和文档存储中直接拉取上下文。
+
+告知他们一旦完成初步信息倾泻，将会提出澄清性问题。
+
+**在上下文收集过程中：**
+
+- 如果用户提到团队频道或共享文档：
+  - 如果有可用集成工具：告知现在将读取内容，然后使用相应的集成工具
+  - 如果没有可用集成工具：解释无法访问。建议他们在 Claude 设置中启用连接器，或直接粘贴相关内容。
+
+- 如果用户提到未知的实体/项目：
+  - 询问是否应搜索已连接的工具以了解更多信息
+  - 等待用户确认后再搜索
+
+- 当用户提供上下文时，跟踪学到了什么以及还有哪些不清楚
+
+**提出澄清性问题：**
+
+当用户表示已完成初步信息倾泻（或提供了大量上下文后），提出澄清性问题以确保理解。
+
+根据上下文中的空白生出 5-10 个编号问题。
+
+告知他们可以用简写方式回答（如"1：是，2：见 #频道，3：不，因为向后兼容"），链接更多文档、指向要阅读的频道，或继续倾泻信息。任何对他们最有效率的方式都可以。
+
+**退出条件：**
+当问题显示出理解——可以问出边界情况和权衡取舍，而无需解释基础概念时，上下文收集完成。
+
+**过渡：**
+询问他们在此阶段是否还有更多上下文要提供，或是否该进入文档起草了。
+
+如果用户想补充更多内容，让他们补充。准备好后，进入阶段 2。
+
+## 阶段 2：打磨与结构
+
+**目标：** 通过头脑风暴、精选和迭代打磨，逐个章节构建文档。
+
+**给用户的说明：**
+解释文档将逐个章节构建。对每个章节：
+1. 会问澄清性问题以确定包含什么内容
+2. 会头脑风暴 5-20 个选项
+3. 用户指示保留/删除/合并哪些内容
+4. 该章节将被起草
+5. 通过精准编辑进行打磨
+
+从最不确定的章节开始（通常是核心决策/提案），然后逐一完成其余部分。
+
+**章节排序：**
+
+如果文档结构明确：
+询问他们想从哪个章节开始。
+
+建议从最不确定的章节开始。对于决策文档，通常是核心提案。对于规范文档，通常是技术方案。摘要部分最好放在最后。
+
+如果用户不知道需要哪些章节：
+根据文档类型和模板，建议 3-5 个适合该文档类型的章节。
+
+询问此结构是否合适，或是否需要调整。
+
+**一旦结构达成一致：**
+
+创建包含所有章节占位文本的初始文档结构。
+
+**如果可以访问 artifacts：**
+使用 `create_file` 创建一个 artifact。这为 Claude 和用户都提供了一个可操作框架。
+
+告知他们将创建包含所有章节占位文本的初始结构。
+
+创建包含所有章节标题和简短占位文本（如"[待编写]"或"[内容在此]"）的 artifact。
+
+提供框架链接，并说明是时候填充每个章节了。
+
+**如果无法访问 artifacts：**
+在工作目录中创建一个 Markdown 文件。适当命名（如 `decision-doc.md`、`technical-spec.md`）。
+
+告知他们将创建包含所有章节占位文本的初始结构。
+
+创建包含所有章节标题和占位文本的文件。
+
+确认文件名已创建，并说明是时候填充每个章节了。
+
+**对每个章节：**
+
+### 第 1 步：澄清性问题
+
+宣布将开始编写 [章节名称] 章节。提出 5-10 个关于应包含内容的澄清性问题。
+
+根据上下文和章节目的生成 5-10 个具体问题。
+
+告知他们可以用简写回答，或仅指出哪些内容需要覆盖。
+
+### 第 2 步：头脑风暴
+
+针对 [章节名称] 章节，根据章节复杂度头脑风暴 5-20 个可能包含的内容。寻找：
+- 可能被遗忘的已共享上下文
+- 尚未提及的角度或考虑因素
+
+根据章节复杂度生成 5-20 个编号选项。结尾处主动询问是否需要更多选项。
+
+### 第 3 步：精选
+
+询问哪些要点需要保留、删除或合并。请求简短的理由说明，以帮助为后续章节学习优先级。
+
+提供示例：
+- "保留 1、4、7、9"
+- "删除 3（与 1 重复）"
+- "删除 6（读者已经知道）"
+- "合并 11 和 12"
+
+**如果用户给出自由形式的反馈**（如"看起来不错"或"大部分我挺喜欢的，但是……"）而非编号选择，提取他们的偏好并继续执行。解析他们想要保留/删除/修改的内容并应用。
+
+### 第 4 步：差距检查
+
+根据他们选择的内容，询问 [章节名称] 章节是否遗漏了重要内容。
+
+### 第 5 步：起草
+
+使用 `str_replace` 将该章节的占位文本替换为实际起草的内容。
+
+宣布现在将根据用户选择的内容起草 [章节名称] 章节。
+
+**如果使用 artifacts：**
+起草后，提供 artifact 的链接。
+
+请用户通读并指出需要修改的地方。注意具体说明有助于为后续章节积累经验。
+
+**如果使用文件（无 artifacts）：**
+起草后，确认完成。
+
+告知 [章节名称] 章节已在 [文件名] 中起草完成。请用户通读并指出需要修改的地方。注意具体说明有助于为后续章节积累经验。
+
+**给用户的关键说明（在起草第一个章节时包含）：**
+提供一个提示：不用直接编辑文档，请他们指出要修改的地方。这有助于学习他们的风格以用于后续章节。例如："删除 X 要点的项目符号 - Y 已经涵盖了"或"让第三段更简洁"。
+
+### 第 6 步：迭代打磨
+
+用户提供反馈时：
+- 使用 `str_replace` 进行编辑（绝不重新打印整个文档）
+- **如果使用 artifacts：** 每次编辑后提供 artifact 链接
+- **如果使用文件：** 仅确认编辑完成
+- 如果用户直接编辑文档并要求读取：在脑海中记录他们所做的更改，并在后续章节中考虑这些更改（这展示了他们的偏好）
+
+**持续迭代**直到用户对该章节满意。
+
+### 质量检查
+
+在连续 3 次迭代无明显变更后，询问是否可以删除某些内容而不丢失重要信息。
+
+当章节完成后，确认 [章节名称] 已完成。询问是否准备好进入下一章节。
+
+**对所有章节重复上述过程。**
+
+### 接近完成
+
+当接近完成（80%+ 的章节已完成）时，宣布将重新通读整个文档，检查：
+- 各章节之间的流畅性和一致性
+- 冗余或矛盾
+- 是否有"AI 废话"或泛泛的填充内容
+- 是否每句话都有分量
+
+通读整个文档并提供反馈。
+
+**当所有章节都起草并打磨完毕：**
+宣布所有章节已完成。表明将再整体审阅一次完整文档。
+
+检查整体连贯性、流畅性和完整性。
+
+提供任何最终建议。
+
+询问是否准备好进入读者测试，或是否还想打磨其他内容。
+
+## 阶段 3：读者测试
+
+**目标：** 用一个全新的 Claude（没有上下文泄露）测试文档，验证它对读者是否有效。
+
+**给用户的说明：**
+解释现在将进行测试，看看文档是否真的对读者有效。这能发现盲点——作者觉得理所当然但可能会让他人困惑的内容。
+
+### 测试方法
+
+**如果可以访问子代理（如在 Claude Code 中）：**
+
+直接执行测试，无需用户参与。
+
+### 第 1 步：预测读者问题
+
+宣布将预测读者在尝试查找此文档时可能会问的问题。
+
+生成 5-10 个读者会实际提出的问题。
+
+### 第 2 步：用子代理测试
+
+宣布将用一个全新的 Claude 实例（无本对话的上下文）测试这些问题。
+
+对每个问题，调用一个只有文档内容和该问题的子代理。
+
+总结 Reader Claude 对每个问题的回答正确/错误之处。
+
+### 第 3 步：执行额外检查
+
+宣布将执行额外检查。
+
+调用子代理检查歧义、错误假设和矛盾。
+
+总结发现的任何问题。
+
+### 第 4 步：报告和修复
+
+如果发现问题：
+报告 Reader Claude 在特定问题上遇到了困难。
+
+列出具体问题。
+
+表明将修复这些空白。
+
+对有问题的章节循环回到打磨阶段。
+
+---
+
+**如果无法访问子代理（如 claude.ai Web 界面）：**
+
+用户需要手动进行测试。
+
+### 第 1 步：预测读者问题
+
+询问人们在尝试查找此文档时可能会问什么问题。他们会向 Claude.ai 输入什么？
+
+生成 5-10 个读者会实际提出的问题。
+
+### 第 2 步：设置测试
+
+提供测试说明：
+1. 打开一个新的 Claude 对话：https://claude.ai
+2. 粘贴或分享文档内容（如果使用启用了连接器的共享文档平台，提供链接）
+3. 向 Reader Claude 提出生成的问题
+
+对每个问题，指示 Reader Claude 提供：
+- 答案
+- 是否有任何内容存在歧义或不清晰
+- 文档假设读者已经知道什么知识/上下文
+
+检查 Reader Claude 是否给出正确答案，或是否有误解。
+
+### 第 3 步：额外检查
+
+同时也问 Reader Claude：
+- "这篇文档中对读者来说可能有歧义或不清晰的地方是什么？"
+- "这篇文档假设读者已经具备哪些知识或上下文？"
+- "是否有任何内部矛盾或不一致之处？"
+
+### 第 4 步：根据结果迭代
+
+询问 Reader Claude 答错或难以回答的内容。表明将修复这些空白。
+
+对有问题的章节循环回到打磨阶段。
+
+---
+
+### 退出条件（两种方法通用）
+
+当 Reader Claude 能持续正确回答问题，且不再发现新的空白或歧义时，文档就准备好了。
+
+## 最终审阅
+
+当读者测试通过后：
+宣布文档已通过 Reader Claude 测试。在完成之前：
+
+1. 建议他们自己最后通读一遍——他们拥有这篇文档并对其质量负责
+2. 建议再次核对任何事实、链接或技术细节
+3. 请他们验证文档是否达到了预期的效果
+
+询问他们是否还需要一次审阅，或工作是否已完成。
+
+**如果用户需要最终审阅，提供。否则：**
+宣布文档完成。提供一些最终小贴士：
+- 考虑在附录中链接此对话，以便读者了解文档是如何开发的
+- 使用附录在不使主文档膨胀的情况下提供深度信息
+- 根据真实读者的反馈更新文档
+
+## 有效引导的小贴士
+
+**语气：**
+- 直接且有条理
+- 简要解释为何某些操作会影响用户行为
+- 不要"推销"方法——直接执行
+
+**处理偏离：**
+- 如果用户想跳过某个阶段：询问他们是否想跳过并以自由形式编写
+- 如果用户显得沮丧：承认这比预期耗时更长。建议加快速度的方法
+- 始终让用户有权调整流程
+
+**上下文管理：**
+- 在整个过程中，如果缺少某些提及内容的上下文，主动询问
+- 不要让空白积累——出现时立即解决
+
+**制品管理：**
+- 使用 `create_file` 起草完整章节
+- 使用 `str_replace` 进行所有编辑
+- 每次更改后提供 artifact 链接
+- 永远不要使用 artifacts 展示头脑风暴列表——那只是对话
+
+**质量优先于速度：**
+- 不要仓促完成各阶段
+- 每次迭代都应有意义的改进
+- 目标是创建一份真正对读者有用的文档