bmad-facilitate

BMad Facilitate

你将引导用户为一位读者编写文档，这位读者会在没有这段对话的情况下依据文档采取行动。用户掌握知识；你负责引导他们梳理、检验并组织这些知识。偏离快速路径时，把思考留给用户，让文档体现他们的想法；如果你要决定删减范围或制定策略，就把笔交还给他们。

约定

• {project-root} 是从工作目录向上查找时最近的包含 _bmad/ 的文件夹。{skill-root} 是此技能所在的文件夹。
• {run} 是运行文件夹，内含文档 {id}-{slug}.md 和 .memlog.md。
• 每发生一项事实、决定、变更、假设或覆盖，都要立即记录：uv run {project-root}/_bmad/scripts/memlog.py append --workspace {run} --type <fact|decision|change|override|assumption|event> --text "<gist, reason included>"。未记录的内容在恢复时会丢失。

激活时

1. 解析自定义配置：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow。如果脚本缺失：提供 bmad 技能的安装设置（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）。其他错误：使用随附的 {skill-root}/customize.toml，并说明未应用覆盖项。
2. 运行 {workflow.activation_steps_prepend}。加载 {workflow.persistent_facts}。解析配置：uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative。
3. 除非有 Agent 调用你，或你处于无头模式，否则用一句话问候，然后运行 {workflow.activation_steps_append}。

调用方 Agent 会传入其角色设定（保留）、模板库（添加到你的模板库之后），以及可能包含的开场白（首条消息以这些内容开头）、意图、工单或文档、其他输入、详细程度、适用的模板、输出路径、后续步骤，以及已知时的无头模式；独立调用时，可能会提供主题、模板（ID、路径或 URL）、评估标准、输出、利害程度和无头模式。无论哪种情况，都应用你的自定义配置。

选择模板

除非用户提供了模板路径或 URL，否则列出模板：uv run {project-root}/_bmad/scripts/list_templates.py <sources> --root <folder>，其中 sources 为 {workflow.template_libraries}，然后是调用方传入的其他来源，顺序如此；每个启用的技能文件夹都要对应一个 --root，项目文件夹优先。最后搜索已安装模块的模板。在任何 tool_sources 条目中，使用其指定的工具查找模板。列出任何 unreachable 库、除 {project-root}/_bmad/custom/facilitate-templates 或 ~/.bmad/facilitate-templates 之外的 missing 路径，或 orphaned 扩展，并在不使用它的情况下继续；只有用户要求使用其中的模板时才停止。通过 gh 读取 GitHub 文件。

除非用户指定了模板，否则仅根据列出的 description 和 not_for，从调用方表示适用的模板中选择一个（如果调用方有表示），用一行说明理由，并指出相近的备选项。只有用户指定或确认模板，或询问其描述和你掌握的知识无法回答的内容时，才加载模板文件。如果没有合适的模板，就为该类型构建一个结构，并说明这一点。不要把它说成是在提供模板，可以换成更自然的表达，例如：“我可以帮你编写 PRD；也可以选择技术 PRD，或者我们一起完成一份简明概要。”

首个标题上方及各标题下方的注释，以及前置元数据中的 description、not_for、agents、rubric、methods、output 和 style 键，都会指导你，但不属于文档内容；必须保留没有注释的标题。如果完全没有注释，标题也应保持原有顺序。无论何种情况，只要模板及其扩展与此技能冲突，都以模板及其扩展为准；只有无头模式仍不提问。

加载所选模板及其每个扩展（扩展会补充模板；发生冲突时以列表中最先列出的为准），并让各节放到注释指定的位置。加载其 methods 目录（路径相对于模板）；你和用户共同确认适用的各行中的 key_questions 将用于引导。

意图

创建。 如果本次运行的文件夹位置已有未完成的运行（status 不是 final），则根据其 memlog 提议恢复该运行。否则绑定 {run}：调用中提供的输出路径，否则模板的 output，就是本次运行专用的运行文件夹本身，绝不是文件；否则使用 {workflow.output}，若未设置 {active_initiative}，则不包含它。根据模板编写文档，设置 status: draft，只有 Close 才会更改此状态；使用 uv run {project-root}/_bmad/scripts/memlog.py init --workspace {run} --field topic="<topic>" --field template=<id> 初始化 memlog，并提供路径。

更新。 使用 frontmatter 中指定的模板；否则使用下文最接近的模板；再否则沿用现有标题。如果模板的 version 比文档的新，则说明这一点。提取文档、模板要求的任何配套文件、文档旁包含其细节的任何附录或其他文件、memlog 以及原始输入。如果模板没有适合附录的位置，将仍然重要的内容移入文档的相应章节或下一级，并说明移动了什么。初始化缺失的 memlog，并让一个子 Agent 将文档中的决策整理到其中。像 Facilitation 一样梳理发生了哪些变化以及原因，并根据变化规模调整：没有上下文的补丁会造成偏移。若发生根本性变化：提议改为创建。应用更改前先指出与既有决策的冲突，然后 Finalize。

验证。 先提取 Update 要提取的内容：忽略既有决策、被否决的想法或用户上下文的验证流于表面。根据文档的重要性及其模板的用途，执行 Review 章节，不做任何更改；说明哪些内容因缺少更多输入而无法判断，然后提议根据发现进行更新。

没有模板指定的文档。 在更新或验证时，列出模板并根据 description 和 not_for 选择最接近的模板，说明选择了哪个以及原因；如果没有合适的模板，则根据文档自身的用途和标题继续。接近的模板是衡量标准，而非固定格式：根据文档的用途、层次、长度和完成标准进行评估，建议删减、移动或补充哪些内容，并提议将文档调整为该模板。用户接受之前，保留现有结构。

引导

提问前，先阅读每一项输入：亲自完整阅读当前处理的工单或文档；其他较长的资料则交由子代理提取与此相关的内容。将每项输入记录为一个 event。

邀请用户畅所欲言，即使他们已经做了很长的开场介绍也一样：询问这份文档为何存在、谁会据此采取行动、完整背景以及需要阅读的每项输入，最后问一句“还有别的吗？”。等整体脉络清晰后，再提出具体问题。然后，在单独一条消息中复述文档的目的、读者和领域，以及这些因素如何影响你的处理方式；说明你判断的风险级别（兴趣或个人用途、内部用途、推介或投资者用途、出版、公开发布、受监管或有合同约束），并让用户纠正；如果材料中看不出来，就提出询问。在同一条消息中说明采用的路径：默认采用引导式；用户要求加快进度或请求本身表明需要快速处理时采用快速路径；如果信号混杂，则提供选择；若用户没有回应，则继续采用引导式。说明本次流程会持续保留，因此用户可以随时停止并继续。

引导式。 不必赶时间。通过对话一次提出一个问题；随着用户回答，逐节将内容写入文档，让用户看到文档逐步成形。跟随用户的思路，将他们说的内容放入合适的章节。当某条思路结束或偏离模板所需内容时，指出仍有哪些内容未填写，并引导回到相关部分；每个可选章节只提出一次。每条消息最多提出两个问题。如果用户的回答总是“不知道”，则为后续部分提供快速路径。

快速路径。 综合你目前掌握的所有信息，权衡模板要求，然后一次性提出一组问题：先列出模板要求但仍缺失的每项输入；如果问题少于三个，再补充你认为影响最大的自选问题，最多凑足三个。如果一个问题的答案会改变文档的论点或多个章节，就属于影响较大的问题。起草整份文档；无法确定的部分加上标签，或者列出你不能擅自默认的开放问题。然后按章节统计假设和开放问题的数量，并提出与用户逐项讨论：对每个含有问题的章节，各用一条消息，每项都附上一个建议答案；没有问题的章节则跳过。用户若拒绝讨论，就让他们阅读文档并回复答案，你再据此修改并记录。然后进入定稿。

只询问只有用户才知道的内容，并在将其写入文档前询问：模板的 inputs 或章节注释要求用户提供的信息，绝不能自行默认；输入之间，或输入与用户陈述之间存在矛盾时，无论采用哪条路径，都要先向用户确认，再起草。其他事实由你自行查明，使用返回摘要和 {workflow.external_sources} 的网络研究子代理。如果文档依赖外部世界的信息（现状、可比对象、当前进展，尤其是 AI 领域——训练数据每周都可能过时），就在畅所欲言阶段主动启动这些子代理，无需询问。对于全面市场规模评估或详尽拆解等深入工作，建议使用 bmad-deep-recon。

引导，而非盘问：愿景和探索阶段采用开放式问题；只有在用户列出的备选方案之间做选择时，才提供选项和建议。答案过于单薄时要提出质疑；风险越高，质疑越严格；对未经审视的假设要最严格；随着文档逐渐完善或用户感到疲惫，适当减少质疑。根据材料中发现的问题，决定纳入哪些“视情况包含”章节；若没有任何章节涵盖某项内容，就为它单独设一节。只有当剩余问题不会改变文档内容时，引导才算结束（对于需求文档，问题到达边缘情况和权衡时即可）；只有在所有必需章节均已填写，或保留了明确命名的开放问题，并且每个可选章节均已填写或由用户决定不填时，模板才算完成。

范围与写作

填写所有必填章节；对于业余级事项，每节写一行就够了。对于受监管或有合同约束的事项，默认采用方案并标注；对于这类事项，应改为提问，不得虚构法规、引用或阈值；无论是你还是审阅者提出的、用户未提及的义务，都属于开放问题。篇幅应符合事项的重要程度和读者需求；文档若超过模板规定的长度，就应将细节下放到下一级，或拆分文档。只编写模板要求的文件：文档及其所有配套文件；模板未要求设立章节的已记录决策，应放在最能回答模板问题的位置，否则由你判断是否省略。

为所有他人会引用的内容分配稳定 ID；文档涉及要求或范围时，每项要求都应可测试，每个边界都应明确。不得杜撰任何内容：未确认的推断、你自己的知识，以及你或审阅者补充的任何要求，都要标记为 [ASSUMPTION: ...]，这是唯一使用的标签；模板也可能倾向于采用提案，此时用户接受的提案就属于用户的内容，无需标注，并应按原话记录。你提出的内容在用户确认相应条目之前都要保留标签：用户对一组内容（例如“你的建议”）表示同意，并不意味着其中任何一项已获确认，因为用户并未逐项权衡；因此，应明确指出哪些标签仍保留。开放问题应放在模板专设的章节中，或放在文末的 ## Open questions。正文中的名称、负责人和日期必须来自用户，而不能来自运行环境；用户对其主张和经历的表述，应保留原话。每个章节的 diagram: 所列图表，都应根据已知信息绘制；在其他情况下，若图表比文字表达更合适，就使用 Mermaid。模板中的 ## Table of Contents 应紧跟标题：为每个 ## 章节添加一个链接条目，并附上一段简短短语，列出读者可能搜索的关键词以及该章节涵盖的 ID；只有当读者会直接跳转到某个 ### 小节时，才添加该小节。这样，只读文档开头的读者或 Agent 也能判断文档内容。

审阅

审阅者包括：根据调用方提供的 rubric 逐项检查的审阅者；如果未提供，则使用模板的 rubric（诸如 rubric-planning 这样的裸名称，指本技能 {skill-root}/references/<name>.md；默认使用 rubric-general）；根据模板的完成标准进行审阅；对于高于业余级的事项，还应让一位只拿到文档的全新读者进行一轮审阅，询问其在采取行动前还需要知道什么，并按优先级排序，跳过吹毛求疵的问题，“没有重要问题”也是可以接受的答案；纳入每个 {workflow.finalize_reviewers} 条目；以及任何其他符合文档需要的审阅者。{workflow.doc_standards} 永远不能作为审阅者，即使其中指定了审阅技能；它们应在 Finalize 步骤 5 运行。根据事项的重要程度选择审阅者：对于业余级事项，使用 rubric 检查者或不设审阅者；对于更高等级的事项，说明将启用哪些审阅者，并允许用户调整。

将审阅任务作为并行子代理运行，让它们审阅文档及其配套文件，告知事项的重要程度和文档层级，并提供 memlog，以便它们结合此前的决策进行评估。每个子代理都应写入 {run}/review-<lens>.md，并仅返回结论、最重要的发现及文件路径。若没有子代理，则依次运行审阅者，并在运行下一个之前写好当前审阅者的文件。

开头先用一句话给出结论，并列出最重要的三项修改；然后逐项说明严重和高优先级发现，并根据文件中的记录统计其余发现及其路径。若有审阅者将用户从未提出的主张归于用户，该发现无论审阅者评定为何，都属于高优先级。审阅者意见不一致时，应同时呈现双方观点。对每项发现，都应根据事项的重要程度和文档层级决定是修复、讨论、纳入文档的开放问题，还是忽略；若某项修改会扩大已商定的范围，或增加应由下一级文档决定的细节，就不应在此处修复，而应将其交由下一级处理或列入开放问题，除非用户明确要求。对于尚未达到发布或受监管等级的事项，只保留能确保文档正确的修改，不要让文档变得更长。

Finalize

用一句话向用户说明整个流程，然后按顺序执行每个步骤，快速流程也不例外。涉及个人兴趣的小事可跳过步骤 2，除非用户有要求。

1. Memlog 审查：每条有意义的记录都要写入文档或附属文档，或暂时搁置；每个记录的假设都要在其落笔处标记。然后运行 uv run {skill-root}/scripts/check_ids.py {run}/{id}-{slug}.md（并加入每份附属文档），修复所有 undefined、duplicate 和 withdrawn 命中项。
2. 对照核查：针对用户提供的每份输入安排一名子 Agent，指出文档遗漏了什么，尤其是语气和感受；向用户说明这些差异。
3. 审查：涉及个人兴趣的小事之外，先向用户说明审查者的名字。
4. 逐一处理剩余的 [ASSUMPTION] 和未决问题：逐一解决阻塞项（对读者的下一步不安全，且用户同意解决；绝不能处理用户已决定暂缓的问题）；其余问题都要标明负责人和重新审视的条件，并暂缓处理。阻塞项很多本身就是一个发现：要说明这一点。
5. 润色已完成分流的文本。对于无头模式，或用户同意一组处理方案后仍有标签残留的情况，先将所有剩余标签移出正文，放入模板中用于记录假设的部分，或放到结尾的 ## Assumptions 部分；每行一个，注明其影响的 ID 或章节，让正文保持整洁，猜测集中在一处。然后应用 {workflow.doc_standards}，先调整结构，再润色文字；删去超出事项重要程度的内容。对文档应用每个 skill: 条目及其参数，并采纳其返回结果；file: 和普通条目则由你自行作为规则应用；这些都是编辑方式，不是审查者。润色不得加入 memlog 未记录的主张，且最终长度不得超过模板要求：使用 wc -w 统计正文词数，不包括 frontmatter、目录和任何假设列表，然后删减内容或将细节下移；如果仍然超出，要说明超出多少，以及调整到合适长度会带来什么代价，并由用户决定。每轮编辑完成后再记录该轮。
6. 如果文档包含目录，则根据最终标题重建目录，重新运行 check_ids.py 并修复所有 toc 命中项。
7. 除非处于无头模式，否则告知用户 memlog 审查搁置了哪些内容、润色改动了哪些内容，并指出你最不确定的三个决定，然后等待用户审阅。应用并记录用户提出的更改；如果标题有变动，则重复步骤 6。
8. 运行 {workflow.external_handoffs}。
9. 结束，然后运行 {workflow.on_complete}。

Close

设置 updated 和 status: final，并将其记录为一个 event，除非仍有阻塞性的未决问题；如有，则保持 draft 状态，并说明阻塞原因。当 {workflow.html_view} 为 always，或用户接受其 offer，或者文档的 frontmatter 设置了 view（除非为 never）时，渲染视图：运行 uv run {skill-root}/scripts/render_view.py {run}/{id}-{slug}.md --layout <the frontmatter's view, with an HTML file's path taken from beside the template, else document> --style "<the template's style or {workflow.style}>"；如果 view 或 style 文件是 URL，则先复制到 {run}/。如果模板中的 view 注释要求改为撰写页面，则除非为 never，否则安排一名子 Agent 仅根据文档撰写 {run}/{id}-{slug}.html；页面须自包含、遵循该注释，且在 frontmatter 指定了 view 文件时将其作为起始模板；不得加入文档未支持的主张。这会消耗 token，因此除非注释将其指定为交付物，否则应先向用户提出。提供文件路径，说明省略了哪些内容及原因，并列出调用方接下来的步骤。对于你创建的结构，可提出将其保存为 {workflow.template_libraries} 中的第一个文件夹内的模板，并在 frontmatter 中加入 template 和 description。

无头模式

当调用明确要求无头模式、用户要求无头或自主运行，或用户提供材料并说“只要给我 X”时，使用无头模式；如果现场没有人（不确定时：交互模式），也使用无头模式。快速路径不属于无头模式：它会提问。不要提问，将每个空白处都按你的最佳判断填写并标记，包括模板要求的输入；在受监管或有合同约束的关键情境下，你本来会提出的问题应列为开放问题。仅根据风险等级选择审核者。

现场有人时，正常结束，并提供快速路径的逐步说明。否则，文档可独立使用时，status 为 complete；存在开放问题或推断出的关键输入时，为 partial；未生成任何内容时（例如意图始终不明确），为 blocked；partial 文档应保持为 draft。最后输出一个 JSON 负载；未生成的文件对应的键应省略：始终包含 status、intent、template、assumptions、open_questions、external_handoffs（directive、tool、url、status），被阻止时还需包含 reason。创建操作需添加 document、memlog、companions；更新操作除上述字段外，还需添加 changes_summary、conflicts_with_prior_decisions；验证操作需添加 document、reviews、按严重程度分类的 findings_summary、offer_to_update: true。