From 51b6d0896a04f0e4ba0b96e4bb568e1cdb519f19 Mon Sep 17 00:00:00 2001 From: leon Date: Sun, 22 Mar 2026 15:40:24 +0800 Subject: [PATCH] docs(zh-cn): close explanation gap relinks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 我补齐 explanation 目录在本轮审校中确认的中文缺口，统一关键命令名为当前 `bmad-*` 形式，并修正 Party Mode 示例里的半翻角色标签。此前这些页面缺少回连到中文目标的入口且术语混用旧名，导致查阅路径容易断层；现在每页都补了中文回链并对齐命名，降低理解和跳转成本。 Feishu: https://feishu.cn/wiki/TODO Made-with: Cursor --- .../zh-cn/explanation/advanced-elicitation.md | 2 ++ docs/zh-cn/explanation/adversarial-review.md | 4 ++- docs/zh-cn/explanation/brainstorming.md | 4 ++- .../explanation/established-projects-faq.md | 14 ++++---- docs/zh-cn/explanation/party-mode.md | 36 ++++++++++--------- .../explanation/preventing-agent-conflicts.md | 4 ++- docs/zh-cn/explanation/project-context.md | 32 +++++++++-------- docs/zh-cn/explanation/quick-dev.md | 2 ++ .../explanation/why-solutioning-matters.md | 2 ++ 9 files changed, 59 insertions(+), 41 deletions(-) diff --git a/docs/zh-cn/explanation/advanced-elicitation.md b/docs/zh-cn/explanation/advanced-elicitation.md index 7ecbdf0e5..9e1caa6dd 100644 --- a/docs/zh-cn/explanation/advanced-elicitation.md +++ b/docs/zh-cn/explanation/advanced-elicitation.md @@ -48,6 +48,8 @@ sidebar: 对于任何规范或计划，事前复盘都是一个很好的首选。它始终能找到标准审查会遗漏的空白。 ::: +如果你还处在方向发散阶段，可先用 [头脑风暴](./brainstorming.md)；如果你需要多角色权衡讨论，可用 [派对模式](./party-mode.md)。在进入实现前做问题发现时，可结合 [对抗性评审](./adversarial-review.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/adversarial-review.md b/docs/zh-cn/explanation/adversarial-review.md index c969c1e53..ab10deab6 100644 --- a/docs/zh-cn/explanation/adversarial-review.md +++ b/docs/zh-cn/explanation/adversarial-review.md @@ -43,7 +43,7 @@ sidebar: 对抗性评审产生： > 1. **高** - `login.ts:47` - 失败尝试没有速率限制 -> 2. **高** - 会话令牌存储在 localStorage 中（易受 XSS 攻击） +> 2. **高** - 会话令牌存储在 `localStorage` 中（易受 XSS 攻击） > 3. **中** - 密码验证仅在客户端进行 > 4. **中** - 失败登录尝试没有审计日志 > 5. **低** - 魔法数字 `3600` 应该是 `SESSION_TIMEOUT_SECONDS` @@ -58,6 +58,8 @@ sidebar: 假设问题存在。寻找缺失的内容，而不仅仅是错误的内容。 ::: +如果你想把该策略放进快速实现节奏中，可参见 [快速开发](./quick-dev.md)；若要做多轮推理补强，可参见 [高级启发](./advanced-elicitation.md)。整体流程位置请见 [工作流地图](../reference/workflow-map.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/brainstorming.md b/docs/zh-cn/explanation/brainstorming.md index a7479e88f..1eb7a8b8e 100644 --- a/docs/zh-cn/explanation/brainstorming.md +++ b/docs/zh-cn/explanation/brainstorming.md @@ -9,7 +9,7 @@ sidebar: ## 什么是头脑风暴？ -运行 `brainstorming`，你就拥有了一位创意引导者，帮助你从自身挖掘想法——而不是替你生成想法。AI 充当教练和向导，使用经过验证的技术，创造让你最佳思维涌现的条件。 +运行 `bmad-brainstorming`，你就拥有了一位创意引导者，帮助你从自身挖掘想法——而不是替你生成想法。AI 充当教练和向导，使用经过验证的技术，创造让你最佳思维涌现的条件。 **适用于：** @@ -32,6 +32,8 @@ sidebar: 每个想法都来自你。工作流程创造洞察的条件——你是源头。 ::: +想继续深化现有输出，可参考 [高级启发](./advanced-elicitation.md)；需要多角色协同讨论，可参考 [派对模式](./party-mode.md)。若要查看它在整体流程中的位置，请参见 [工作流地图](../reference/workflow-map.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/established-projects-faq.md b/docs/zh-cn/explanation/established-projects-faq.md index dcf89df2c..b26f3fe77 100644 --- a/docs/zh-cn/explanation/established-projects-faq.md +++ b/docs/zh-cn/explanation/established-projects-faq.md @@ -8,12 +8,12 @@ sidebar: ## 问题 -- [我必须先运行 document-project 吗？](#我必须先运行-document-project-吗) -- [如果我忘记运行 document-project 怎么办？](#如果我忘记运行-document-project-怎么办) -- [我可以在既有项目上使用快速流程吗？](#我可以在既有项目上使用快速流程吗) +- [我必须先运行 bmad-document-project 吗？](#我必须先运行-bmad-document-project-吗) +- [如果我忘记运行 bmad-document-project 怎么办？](#如果我忘记运行-bmad-document-project-怎么办) +- [我可以在既有项目上使用 bmad-quick-dev 吗？](#我可以在既有项目上使用-bmad-quick-dev-吗) - [如果我的现有代码不遵循最佳实践怎么办？](#如果我的现有代码不遵循最佳实践怎么办) -### 我必须先运行 document-project 吗？ +### 我必须先运行 bmad-document-project 吗？ 强烈推荐，特别是如果： @@ -23,11 +23,11 @@ sidebar: 如果你拥有全面且最新的文档，包括 `docs/index.md`，或者将使用其他工具或技术来帮助智能体发现现有系统，则可以跳过此步骤。 -### 如果我忘记运行 document-project 怎么办？ +### 如果我忘记运行 bmad-document-project 怎么办？ 不用担心——你可以随时执行。你甚至可以在项目期间或项目之后执行，以帮助保持文档最新。 -### 我可以在既有项目上使用快速流程吗？ +### 我可以在既有项目上使用 bmad-quick-dev 吗？ 可以！快速流程在既有项目上效果很好。它将： @@ -49,6 +49,8 @@ BMM 尊重你的选择——它不会强制现代化，但会提供现代化选 **有未在此处回答的问题吗？** 请[提出问题](https://github.com/bmad-code-org/BMAD-METHOD/issues)或在 [Discord](https://discord.gg/gk8jAdXWmj) 中提问，以便我们添加它！ +如果你想了解这套接入方式的操作步骤，可继续阅读 [How-to：既有项目](../how-to/established-projects.md) 与 [How-to：项目上下文](../how-to/project-context.md)。想理解快速流程在方法论中的定位，可参见 [快速开发](./quick-dev.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/party-mode.md b/docs/zh-cn/explanation/party-mode.md index 85061f393..6786a9134 100644 --- a/docs/zh-cn/explanation/party-mode.md +++ b/docs/zh-cn/explanation/party-mode.md @@ -7,9 +7,9 @@ sidebar: 将所有 AI 智能体汇聚到一次对话中。 -## 什么是 Party Mode？ +## 什么是派对模式（Party Mode）？ -运行 `party-mode`，你的整个 AI 团队就齐聚一堂——PM、架构师、开发者、UX 设计师，任何你需要的人。BMad Master 负责编排，根据每条消息选择相关的智能体。智能体以角色身份回应，彼此同意、反对，并在彼此的想法基础上继续构建。 +运行 `bmad-party-mode`，你的整个 AI 团队就齐聚一堂——PM、架构师、开发者、UX 设计师，任何你需要的人。BMad Master 负责编排，根据每条消息选择相关的智能体。智能体以角色身份回应，彼此同意、反对，并在彼此的想法基础上继续构建。 对话可以持续到你想要的时间。提出追问、对答案提出质疑、引导讨论方向——这是与智能体之间真正的来回交流，直到你完成目标。 @@ -24,40 +24,42 @@ sidebar: ### 指出糟糕的架构 -**You:** "好了团队，我们上个冲刺是一场灾难。认证服务宕机了三次。谁搞砸了这件事？" +**你：** "好了团队，我们上个冲刺是一场灾难。认证服务宕机了三次。谁搞砸了这件事？" -**Architect:** "设计本身是合理的——分布式认证，有适当的回退机制。如果实现偏离了规范……" +**架构师：** "设计本身是合理的——分布式认证，有适当的回退机制。如果实现偏离了规范……" -**Dev:** "我完全按照架构文档执行的。规范没有考虑到并发会话失效的竞态条件。" +**开发者：** "我完全按照架构文档执行的。规范没有考虑到并发会话失效的竞态条件。" -**PM:** "你们两个都忽略了更大的问题——我们没有在 PRD 中验证会话管理需求。这是我的错，没有发现这一点。" +**产品经理：** "你们两个都忽略了更大的问题——我们没有在 PRD 中验证会话管理需求。这是我的错，没有发现这一点。" -**TEA:** "我也应该在集成测试中发现这一点。测试场景没有覆盖并发失效。" +**TEA 测试架构师：** "我也应该在集成测试中发现这一点。测试场景没有覆盖并发失效。" ### 创意头脑风暴 -**You:** "我们如何让入职体验变得神奇，而不是无聊？" +**你：** "我们如何让入职体验变得神奇，而不是无聊？" -**UX Designer:** "从渐进式披露开始——在用户需要时揭示功能，而不是在教程中一次性展示所有内容。" +**UX 设计师：** "从渐进式披露开始——在用户需要时揭示功能，而不是在教程中一次性展示所有内容。" -**Storyteller:** "如果入职是一个故事会怎样？每一步都揭示一个角色的旅程——用户就是英雄。" +**叙事设计师：** "如果入职是一个故事会怎样？每一步都揭示一个角色的旅程——用户就是英雄。" -**Game Designer:** "在此基础上——如果第一个'任务'实际上是解决一个真实的用户问题会怎样？他们通过做有价值的事情来学习。" +**游戏设计师：** "在此基础上——如果第一个'任务'实际上是解决一个真实的用户问题会怎样？他们通过做有价值的事情来学习。" ### 技术决策 -**You:** "MVP 用单体还是微服务？" +**你：** "MVP 用单体还是微服务？" -**Architect:** "从单体开始。微服务会增加你在 1000 用户时不需要的复杂性。" +**架构师：** "从单体开始。微服务会增加你在 1000 用户时不需要的复杂性。" -**PM:** "同意。上市时间比理论上的可扩展性更重要。" +**产品经理：** "同意。上市时间比理论上的可扩展性更重要。" -**Dev:** "单体，但要有清晰的模块边界。如果需要，我们以后可以提取服务。" +**开发者：** "单体，但要有清晰的模块边界。如果需要，我们以后可以提取服务。" -:::tip[Better Decisions] -通过多元视角做出更好的决策。欢迎来到 party mode。 +:::tip[更好的决策] +通过多元视角做出更好的决策。欢迎使用派对模式。 ::: +若你的目标是结构化发散创意，可先参考 [头脑风暴](./brainstorming.md)；若你已经有初稿并想做二次推理补强，可参考 [高级启发](./advanced-elicitation.md)。完整阶段位置见 [工作流地图](../reference/workflow-map.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/preventing-agent-conflicts.md b/docs/zh-cn/explanation/preventing-agent-conflicts.md index c3f24faf6..a7261c449 100644 --- a/docs/zh-cn/explanation/preventing-agent-conflicts.md +++ b/docs/zh-cn/explanation/preventing-agent-conflicts.md @@ -108,9 +108,11 @@ PRD："构建什么" - 记录跨越 epic 边界的决策 - 专注于容易产生冲突的领域 - 随着学习更新架构 -- 对重大变更使用 `correct-course` +- 对重大变更使用 `bmad-correct-course` ::: +如需先理解为什么要在实施前做 solutioning，可阅读 [为什么解决方案设计很重要](./why-solutioning-matters.md)；如果你想把这些约束落地到项目执行，可继续看 [项目上下文](./project-context.md)。流程全景见 [工作流地图](../reference/workflow-map.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/project-context.md b/docs/zh-cn/explanation/project-context.md index d43105ea6..58150a3b5 100644 --- a/docs/zh-cn/explanation/project-context.md +++ b/docs/zh-cn/explanation/project-context.md @@ -21,12 +21,12 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代 每个实施工作流都会自动加载 `project-context.md`（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。 **由以下工作流加载：** -- `create-architecture` — 在解决方案设计期间尊重技术偏好 -- `create-story` — 使用项目模式指导用户故事创建 -- `dev-story` — 指导实施决策 -- `code-review` — 根据项目标准进行验证 -- `quick-dev` — 在实施技术规范时应用模式 -- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文 +- `bmad-create-architecture` — 在解决方案设计期间尊重技术偏好 +- `bmad-create-story` — 使用项目模式指导用户故事创建 +- `bmad-dev-story` — 指导实施决策 +- `bmad-code-review` — 根据项目标准进行验证 +- `bmad-quick-dev` — 在实施技术规范时应用模式 +- `bmad-sprint-planning`、`bmad-retrospective`、`bmad-correct-course` — 提供项目范围的上下文 ## 何时创建 @@ -34,10 +34,10 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代 | 场景 | 何时创建 | 目的 | |----------|----------------|---------| -| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 | -| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 | -| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 | -| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 | +| **新项目，架构之前** | 手动，在 `bmad-create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 | +| **新项目，架构之后** | 通过 `bmad-generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 | +| **现有项目** | 通过 `bmad-generate-project-context` | 发现现有模式，以便智能体遵循既定约定 | +| **快速流程项目** | 在 `bmad-quick-dev` 之前或期间 | 确保快速实施尊重您的模式 | :::tip[推荐] 对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。 @@ -107,20 +107,20 @@ touch _bmad-output/project-context.md ### 架构后生成 -在完成架构后运行 `generate-project-context` 工作流： +在完成架构后运行 `bmad-generate-project-context` 工作流： ```bash -/bmad-bmm-generate-project-context +/bmad-generate-project-context ``` 这将扫描您的架构文档和项目文件，生成一个捕获所做决策的上下文文件。 ### 为现有项目生成 -对于现有项目，运行 `generate-project-context` 以发现现有模式： +对于现有项目，运行 `bmad-generate-project-context` 以发现现有模式： ```bash -/bmad-bmm-generate-project-context +/bmad-generate-project-context ``` 该工作流分析您的代码库以识别约定，然后生成一个您可以审查和优化的上下文文件。 @@ -150,12 +150,14 @@ touch _bmad-output/project-context.md - 模式在实施过程中演变 - 您从智能体行为中发现差距 -您可以随时手动编辑它，或者在重大更改后重新运行 `generate-project-context` 来更新它。 +您可以随时手动编辑它，或者在重大更改后重新运行 `bmad-generate-project-context` 来更新它。 :::note[文件位置] 默认位置是 `_bmad-output/project-context.md`。工作流在那里搜索它，并且还会检查项目中任何位置的 `**/project-context.md`。 ::: +如需可执行步骤说明，请阅读 [How-to：项目上下文](../how-to/project-context.md)；如果你在既有项目落地这套机制，可参考 [既有项目常见问题](./established-projects-faq.md)。整体流程定位见 [工作流地图](../reference/workflow-map.md)。 + --- ## 术语说明 diff --git a/docs/zh-cn/explanation/quick-dev.md b/docs/zh-cn/explanation/quick-dev.md index dc3b52f23..2edf7dc15 100644 --- a/docs/zh-cn/explanation/quick-dev.md +++ b/docs/zh-cn/explanation/quick-dev.md @@ -71,3 +71,5 @@ sidebar: 一些发现属于当前变更。一些不属于。如果一个发现是附带的而不是与当前工作有因果关系，工作流可以推迟它，而不是强迫人类立即处理它。这使运行保持专注，并防止随机的分支话题消耗注意力的预算。 那个分诊有时会不完美。这是可以接受的。通常，误判一些发现比用成千上万个低价值的审查评论淹没人类要好。系统正在优化信号质量，而不是详尽的召回率。 + +想进一步理解审查策略，可继续阅读 [对抗性评审](./adversarial-review.md)；需要对已有输出进行第二轮推理时，可参考 [高级启发](./advanced-elicitation.md)。若要查看它在完整流程中的位置，请参见 [工作流地图](../reference/workflow-map.md)。 diff --git a/docs/zh-cn/explanation/why-solutioning-matters.md b/docs/zh-cn/explanation/why-solutioning-matters.md index 27e8f96ca..975bbd858 100644 --- a/docs/zh-cn/explanation/why-solutioning-matters.md +++ b/docs/zh-cn/explanation/why-solutioning-matters.md @@ -76,6 +76,8 @@ sidebar: 在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。 ::: +想进一步理解冲突是如何发生并被架构约束消除的，可继续阅读 [防止智能体冲突](./preventing-agent-conflicts.md)。如果你要把这些约束落到执行层，请结合 [项目上下文](./project-context.md) 与 [工作流地图](../reference/workflow-map.md) 一起阅读。 + --- ## 术语说明