| name | doc-coauthoring |
| description | 引导用户完成结构化的文档协作工作流程。当用户想要编写文档、提案、技术规范、决策文档或类似结构化内容时使用。此工作流程帮助用户高效地传递上下文、通过迭代优化内容,并验证文档对读者是否有效。当用户提到编写文档、创建提案、起草规范或类似文档任务时触发。 |
文档协作工作流程
此技能提供了一个结构化的工作流程,用于指导用户完成协作文档创建。作为主动引导,引导用户完成三个阶段:上下文收集、优化与结构化、以及读者测试。
何时提供此工作流程
触发条件:
- 用户提到编写文档:"写个文档"、"起草提案"、"创建规范"、"写一下"
- 用户提到特定文档类型:"PRD"、"设计文档"、"决策文档"、"RFC"
- 用户似乎正在开始一项实质性的写作任务
初始提供:
向用户提供结构化的文档协作工作流程。解释三个阶段:
- 上下文收集:用户提供所有相关上下文,同时 Opencode 提出澄清问题
- 优化与结构化:通过头脑风暴和编辑迭代构建每个部分
- 读者测试:用全新的 Opencode(无上下文)测试文档,在他人阅读之前发现盲点
解释这种方法有助于确保文档在他人阅读时效果良好(包括当他们将其粘贴到 Opencode 中时)。询问他们是否想尝试此工作流程或更喜欢自由形式工作。
如果用户拒绝,自由形式工作。如果用户接受,进入阶段 1。
阶段 1:上下文收集
目标: 缩小用户知道的和 Opencode 知道的之间的差距,使后续能够提供智能指导。
初始问题
首先询问用户关于文档的元上下文:
- 这是什么类型的文档?(例如,技术规范、决策文档、提案)
- 主要受众是谁?
- 当有人阅读此文档时希望产生什么影响?
- 是否有模板或特定格式要遵循?
- 还有其他需要了解的限制或上下文吗?
告诉他们可以用简写回答,或者以任何最适合他们的方式转储信息。
如果用户提供模板或提到文档类型:
- 询问他们是否有模板文档可以分享
- 如果他们提供共享文档的链接,使用适当的集成获取它
- 如果他们提供文件,读取它
如果用户提到编辑现有的共享文档:
- 使用适当的集成读取当前状态
- 检查没有 alt 文本的图像
- 如果存在没有 alt 文本的图像,解释当其他人使用 Opencode 理解文档时,Opencode 将无法看到它们。询问他们是否想生成 alt 文本。如果是,请求他们将每个图像粘贴到聊天中以生成描述性 alt 文本。
信息转储
一旦初始问题得到回答,鼓励用户转储他们拥有的所有上下文。请求信息如:
- 项目/问题的背景
- 相关的团队讨论或共享文档
- 为什么不使用替代方案
- 组织上下文(团队动态、过去的事件、政治)
- 时间压力或限制
- 技术架构或依赖关系
- 利益相关者的担忧
建议他们不要担心组织它——只是把它们都倒出来。提供多种方式来提供上下文:
- 意识流信息转储
- 指向要阅读的团队频道或帖子
- 链接到共享文档
如果集成可用可以直接使用这些来拉入上下文。
告诉他们一旦完成初始转储,将会提出澄清问题。
在上下文收集期间:
提出澄清问题:
当用户表明已完成初始转储(或在提供大量上下文后),提出澄清问题以确保理解:
根据上下文中的差距生成 5-10 个编号问题。
告诉他们可以用简写回答(例如,"1: 是,2: 否,3:其他说明 "),链接到更多文档,指向要阅读的频道,或者只是继续信息转储。任何对他们最有效的方式。
退出条件:
当问题显示出理解时,已收集足够的上下文——当可以询问边缘情况和权衡而不需要解释基础知识时。
过渡:
询问在此阶段是否还有更多上下文要提供,或者是否该开始起草文档。
如果用户想添加更多,让他们添加。准备好后,进入阶段 2。
阶段 2:优化与结构化
目标: 通过头脑风暴、策划和迭代优化逐部分构建文档。
给用户的说明:
解释文档将逐部分构建。对于每个部分:
- 将询问关于包含什么的澄清问题
- 将列出 5-20 个选项
- 用户将指示保留/删除/合并什么
- 将起草该部分
- 将通过精确编辑进行优化
从未知数最多的部分开始(通常是核心决策/提案),然后处理其余部分。
部分排序:
如果文档结构清晰:
询问他们想从哪个部分开始。
建议从未知数最多的部分开始。对于决策文档,通常是核心提案。对于规范,通常是技术方法。总结部分最好留到最后。
如果用户不知道他们需要什么部分:
根据文档类型和模板,建议 3-5 个适合文档类型的部分。
询问此结构是否有效,或者他们是否想调整它。
一旦结构达成一致:
创建带有所有部分占位符文本的初始文档结构。
如果可以访问 artifacts:
创建 artifact。这给 Opencode 和用户一个可以工作的脚手架。
告诉他们将创建带有所有部分占位符的初始结构。
创建包含所有部分标题和简短占位符文本(如"[待编写]"或"[内容在此]")的 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:起草
将该部分的占位符文本替换为实际起草的内容。
宣布现在将根据他们选择的内容起草 [部分名称] 部分。
如果使用 artifacts:
起草后,提供 artifact 的链接。
让他们通读并指出要更改什么。注意具体说明有助于为下一部分学习。
如果使用文件(无 artifacts):
起草后,确认完成。
告诉他们 [部分名称] 部分已在 [文件名] 中起草。让他们通读并指出要更改什么。注意具体说明有助于为下一部分学习。
用户的关键说明(在起草第一部分时包含):
提供说明:不要直接编辑文档,让他们指出要更改什么。这有助于学习他们的风格以用于后续部分。例如:"删除 X 要点——已被 Y 覆盖"或"使第三段更简洁"。
步骤 6:迭代优化
当用户提供反馈时:
- 进行编辑(从不重新打印整个文档)
- 如果使用 artifacts: 每次编辑后提供 artifact 链接
- 如果使用文件: 只需确认编辑完成
- 如果用户直接编辑文档并要求读取它:在心里记下他们所做的更改,并在后续部分中记住它们(这表明他们的偏好)
继续迭代 直到用户对该部分满意。
质量检查
在连续 3 次迭代没有实质性更改后,询问是否可以在不丢失重要信息的情况下删除任何内容。
当部分完成时,确认 [部分名称] 已完成。询问是否准备好进入下一部分。
对所有部分重复。
接近完成
当接近完成时(80%+ 的部分完成),宣布打算重新阅读整个文档并检查:
- 各部分之间的流畅性和一致性
- 冗余或矛盾
- 任何感觉像"废话"或通用填充物的内容
- 是否每句话都有分量
阅读整个文档并提供反馈。
当所有部分都起草和优化后:
宣布所有部分都已起草。表明打算最后一次审查完整文档。
审查整体连贯性、流畅性、完整性。
提供任何最终建议。
询问是否准备好进入读者测试,或者他们是否想进一步优化任何内容。
阶段 3:读者测试
目标: 用全新的 Opencode(无上下文污染)测试文档,验证它对读者是否有效。
给用户的说明:
解释现在将测试文档是否真的对读者有效。这可以发现盲点——对作者有意义但可能让其他人困惑的事情。
测试方法
如果可以访问子代理(例如,在 Opencode 中):
直接执行测试,无需用户参与。
步骤 1:预测读者问题
宣布打算预测读者在尝试发现此文档时可能会问什么问题。
生成 5-10 个读者会实际提出的问题。
步骤 2:用子代理测试
宣布将用全新的 Opencode 实例(无此对话的上下文)测试这些问题。
对于每个问题,用仅文档内容和问题调用子代理。
总结读者 Opencode 对每个问题的对错。
步骤 3:运行额外检查
宣布将执行额外检查。
调用子代理检查歧义、错误假设、矛盾。
总结发现的任何问题。
步骤 4:报告并修复
如果发现问题:
报告读者 Opencode 在特定问题上遇到困难。
列出具体问题。
表明打算修复这些差距。
循环回到有问题部分的优化。
如果无法访问子代理 :
用户需要手动执行测试。
步骤 1:预测读者问题
询问人们在尝试发现此文档时可能会问什么问题。他们会向 Opencode 输入什么?
生成 5-10 个读者会实际提出的问题。
步骤 2:设置测试
提供测试说明:
- 打开全新的 Opencode 对话:
- 粘贴或分享文档内容(如果使用启用了连接器的共享文档平台,提供链接)
- 向读者 Opencode 提出生成的问题
对于每个问题,指示读者 Opencode 提供:
- 答案
- 是否有任何歧义或不清晰
- 文档假设读者已知的知识/上下文
检查读者 Opencode 是否给出正确答案或误解任何内容。
步骤 3:额外检查
还询问读者 Opencode:
- "此文档中什么可能对读者来说有歧义或不清晰?"
- "此文档假设读者已有什么知识或上下文?"
- "是否有任何内部矛盾或不一致?"
步骤 4:根据结果迭代
询问读者 Opencode 答错或遇到困难的内容。表明打算修复这些差距。
循环回到任何有问题部分的优化。
退出条件(两种方法)
当读者 Opencode 始终正确回答问题且未发现新的差距或歧义时,文档就准备好了。
最终审查
当读者测试通过时:
宣布文档已通过读者 Opencode 测试。在完成之前:
- 建议他们自己进行最终通读——他们拥有此文档并对其质量负责
- 建议仔细检查任何事实、链接或技术细节
- 询问他们验证是否达到了他们想要的影响
询问他们是否想要最后一次审查,或者工作是否完成。
如果用户想要最终审查,提供它。否则:
宣布文档完成。提供一些最终提示:
- 考虑在附录中链接此对话,以便读者可以看到文档是如何开发的
- 使用附录提供深度而不使主文档臃肿
- 从真实读者收到反馈时更新文档
有效指导的技巧
语气:
- 直接且程序化
- 在影响用户行为时简要解释理由
- 不要试图"推销"这种方法——只是执行它
处理偏差:
- 如果用户想跳过某个阶段:询问他们是否想跳过此阶段并自由形式编写
- 如果用户似乎沮丧:承认这比预期花费更长时间。建议加快速度的方法
- 始终给用户调整过程的权限
上下文管理:
- 在整个过程中,如果缺少提到的内容的上下文,主动询问
- 不要让差距积累——在出现时解决它们
Artifact 管理:
- 起草完整部分
- 进行所有编辑
- 每次更改后提供 artifact 链接
- 绝不使用 artifact 进行头脑风暴列表——那只是对话
质量优于速度:
- 不要匆忙完成各个阶段
- 每次迭代都应做出有意义的改进
- 目标是创建一份真正对读者有效的文档