docs(zh-cn): add missing Chinese translations for 3 documents
Translate the remaining untranslated English docs to Chinese: - explanation/analysis-phase.md - explanation/checkpoint-preview.md - how-to/install-custom-modules.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
leon
parent
ea99b7ece5
commit
10c194c2a6
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: "分析阶段：从想法到基础"
|
||||
description: 头脑风暴、调研、产品简报和 PRFAQ 分别是什么——以及何时使用
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
分析阶段（Phase 1）帮助你在决定动手构建之前，把产品想清楚。这个阶段的每个工具都是可选的，但如果完全跳过分析，你的 PRD 就是建立在假设而非洞察之上。
|
||||
|
||||
## 为什么先分析再规划？
|
||||
|
||||
PRD 回答的是"我们应该构建什么、为什么？"如果输入的是模糊的思考，得到的就是模糊的 PRD——而下游的每一份文档都会继承这种模糊。基于薄弱 PRD 搭建的架构会押错技术方向；从薄弱架构派生的 story 会遗漏边界场景。代价是层层叠加的。
|
||||
|
||||
分析工具的作用就是让你的 PRD 变得锐利。它们从不同角度攻击问题——创意探索、市场现实、客户画像、可行性——这样当你坐下来和 PM agent 协作时，你已经清楚要构建什么、为谁构建。
|
||||
|
||||
## 工具介绍
|
||||
|
||||
### 头脑风暴
|
||||
|
||||
**是什么。** 一个使用经过验证的创意技法的引导式创意会议。AI 充当教练，通过结构化练习从你身上引出想法——而不是替你生成想法。
|
||||
|
||||
**为什么在这里。** 原始想法需要发展空间，然后才能被锁定为需求。头脑风暴创造了这个空间。当你有一个问题领域但还没有清晰的解决方案时，或者你想在确定方向之前探索多种可能性时，它尤其有价值。
|
||||
|
||||
**何时使用。** 你对想要构建什么有一个模糊的感觉，但概念尚未结晶。或者你有了概念，但想在备选方案中做压力测试。
|
||||
|
||||
详见[头脑风暴](./brainstorming.md)了解会议的具体运作方式。
|
||||
|
||||
### 调研（市场、领域、技术）
|
||||
|
||||
**是什么。** 三个聚焦的调研工作流，分别调查你的想法的不同维度。市场调研考察竞争对手、趋势和用户情绪；领域调研建立专业知识和术语体系；技术调研评估可行性、架构选项和实现方案。
|
||||
|
||||
**为什么在这里。** 基于假设构建产品是最快做出没人需要的东西的方式。调研让你的概念扎根于现实——已有哪些竞争对手、用户真正的痛点是什么、技术上是否可行、所在行业有哪些特定约束。
|
||||
|
||||
**何时使用。** 你正在进入一个不熟悉的领域，你怀疑竞品存在但还没有做过梳理，或者你的概念依赖于尚未验证的技术能力。可以只做一项、两项或三项全做——每项都是独立的。
|
||||
|
||||
### 产品简报
|
||||
|
||||
**是什么。** 一个引导式发现会议，输出 1-2 页的产品概念执行摘要。AI 充当协作式业务分析师，帮你阐明愿景、目标受众、价值主张和范围。
|
||||
|
||||
**为什么在这里。** 产品简报是进入规划阶段的较温和路径。它以结构化格式捕获你的战略愿景，可以直接输入到 PRD 的创建中。当你已经对概念有了信心——你了解客户、了解问题、大致知道想构建什么时——它效果最好。简报的作用是组织和打磨这些思考。
|
||||
|
||||
**何时使用。** 你的概念相对清晰，希望在创建 PRD 之前高效地记录下来。你对方向有信心，不需要有人来激烈挑战你的假设。
|
||||
|
||||
### PRFAQ（逆向工作法）
|
||||
|
||||
**是什么。** 亚马逊的逆向工作法（Working Backwards），改编为交互式挑战。你在写一行代码之前，先撰写宣布成品的新闻稿，然后回答客户和利益相关者会提出的最刁钻的问题。AI 充当不留情面但有建设性的产品教练。
|
||||
|
||||
**为什么在这里。** PRFAQ 是进入规划阶段的严格路径。它通过让你为每一个论断辩护，来强制实现以客户为中心的清晰度。如果你写不出一篇有说服力的新闻稿，说明产品还没准备好。如果客户 FAQ 的回答暴露了缺口，那些就是你在实现阶段才会——以更高代价——发现的缺口。这道关卡在成本最低的时候暴露薄弱的思考。
|
||||
|
||||
**何时使用。** 你希望在投入资源之前对概念进行压力测试。你不确定用户是否真的在意。你想验证自己能否阐述一个清晰、站得住脚的价值主张。或者你只是想借助逆向工作法的纪律来打磨你的思考。
|
||||
|
||||
## 我该用哪个？
|
||||
|
||||
| 情境 | 推荐工具 |
|
||||
| ---- | -------- |
|
||||
| "我有一个模糊的想法，不知道从哪里开始" | 头脑风暴 |
|
||||
| "我需要先了解市场再做决定" | 调研 |
|
||||
| "我知道要构建什么，只需要记录下来" | 产品简报 |
|
||||
| "我想确认这个想法是否真的值得构建" | PRFAQ |
|
||||
| "我想先探索，再验证，再记录" | 头脑风暴 → 调研 → PRFAQ 或 简报 |
|
||||
|
||||
产品简报和 PRFAQ 都会为 PRD 提供输入——根据你想要多大程度的挑战来选择。简报是协作式发现，PRFAQ 是严格的关卡挑战。两者通往同一个目的地；PRFAQ 检验你的概念是否配得上到达那里。
|
||||
|
||||
:::tip[不确定？]
|
||||
运行 `bmad-help`，描述你的情况。它会根据你已经做了什么、想达成什么来推荐合适的起点。
|
||||
:::
|
||||
|
||||
## 分析之后呢？
|
||||
|
||||
分析阶段的输出直接进入 Phase 2（规划）。PRD 工作流接受产品简报、PRFAQ 文档、调研成果和头脑风暴报告作为输入——它会将你产出的所有内容综合成结构化需求。分析做得越充分，PRD 就越锐利。
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
title: "检查点预览"
|
||||
description: LLM 辅助的人机协作审查，引导你从目的到细节逐步走过一个变更
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
`bmad-checkpoint-preview` 是一个交互式的、LLM 辅助的人机协作审查工作流。它带你逐步走过一个代码变更——从目的和上下文到细节——让你能做出知情决策：是发布、返工，还是深入挖掘。
|
||||
|
||||
|
||||
|
||||
## 典型流程
|
||||
|
||||
你运行 `bmad-quick-dev`。它澄清你的意图、构建规范、实现变更，完成后将审查线索追加到 spec 文件并在编辑器中打开。你查看 spec，发现这次变更涉及跨多个模块的 20 个文件。
|
||||
|
||||
你可以肉眼扫一遍 diff。但 20 个文件正是肉眼审查开始失效的临界点——你会丢失线索，漏掉两个相距甚远的变更之间的关联，或者批准了自己没有完全理解的东西。所以你改为说 "checkpoint"，让 LLM 带你走一遍。
|
||||
|
||||
这种交接——从自主实现回到人工判断——就是核心使用场景。Quick-dev 以最少的监督长时间运行，检查点预览则是你重新掌舵的地方。
|
||||
|
||||
## 为什么需要它
|
||||
|
||||
代码审查有两种失败模式。一种是审查者浏览 diff，什么也没发现，直接批准。另一种是逐文件仔细阅读，但丢失了全局线索——见树不见林。两种模式的结果相同：审查没有抓住真正重要的东西。
|
||||
|
||||
根本问题在于顺序。原始 diff 按文件顺序呈现变更，而这几乎从来不是构建理解的顺序。你先看到一个辅助函数，却不知道它存在的原因；先看到一个 schema 变更，却不了解它支撑什么功能。审查者必须从零散的线索中重建作者的意图，而这个重建过程正是注意力失效的地方。
|
||||
|
||||
检查点预览通过让 LLM 完成重建工作来解决这个问题。它读取 diff、spec（如果有的话）和周围的代码库，然后按照有利于理解的顺序——而不是 `git diff` 的顺序——呈现变更。
|
||||
|
||||
## 工作原理
|
||||
|
||||
工作流分为五个步骤。每一步都建立在前一步的基础上，逐步从"这是什么？"过渡到"我们该不该发布？"
|
||||
|
||||
### 1. 定向
|
||||
|
||||
工作流识别变更来源（来自 PR、commit、分支、spec 文件或当前 git 状态），生成一行意图摘要以及表面积统计：变更文件数、涉及模块数、逻辑行数、边界穿越数和新增公共接口数。
|
||||
|
||||
这是"这是不是我以为的那个东西？"的时刻。在阅读任何代码之前，审查者确认自己看的是正确的东西，并对范围建立预期。
|
||||
|
||||
### 2. 走查
|
||||
|
||||
变更按**关注点**——而非按文件——组织。关注点是内聚的设计意图，例如"输入验证"或"API 契约"。每个关注点附带简短说明——*为什么选择这种方案*，然后列出可点击的 `path:line` 停靠点，审查者可以沿着这些停靠点在代码中导航。
|
||||
|
||||
这是设计判断步骤。审查者评估的是方案对系统是否合理，而不是代码是否正确。关注点按自顶向下排列：最高层意图在前，支撑实现在后。审查者永远不会遇到引用了自己尚未看过的内容。
|
||||
|
||||
### 3. 细节审视
|
||||
|
||||
在审查者理解了设计之后，工作流浮出 2-5 个"出错代价最高"的位置。这些位置按风险类别标记——`[auth]`、`[schema]`、`[billing]`、`[public API]`、`[security]` 等——并按出错后的影响范围排序。
|
||||
|
||||
这不是找 bug。自动化测试和 CI 负责正确性。细节审视激活的是风险意识："这些是出错成本最高的地方。"如果审查者想在某个领域深入，可以说 "dig into [area]" 来触发一次聚焦正确性的重新审查。
|
||||
|
||||
如果 spec 经过了对抗性审查循环（机器硬化），那些发现也会在这里浮出——不是已修复的 bug，而是审查循环标记出的、审查者应当知晓的决策。
|
||||
|
||||
### 4. 测试
|
||||
|
||||
建议 2-5 种手动观察变更生效的方式。不是自动化测试命令——而是能构建信心、但测试套件无法提供的手动观察。一个可以尝试的 UI 交互、一条可以运行的 CLI 命令、一个可以发送的 API 请求，以及每项的预期结果。
|
||||
|
||||
如果变更没有用户可见的行为，它会明确说明。不发明多余的忙活。
|
||||
|
||||
### 5. 总结
|
||||
|
||||
审查者做出决定：批准、返工或继续讨论。如果批准 PR，工作流可以协助执行 `gh pr review --approve`。如果需要返工，它帮助诊断问题出在方案、spec 还是实现，并帮助起草与具体代码位置关联的可操作反馈。
|
||||
|
||||
## 它是对话，不是报告
|
||||
|
||||
工作流将每一步呈现为起点，而非定论。在步骤之间——或步骤中间——你可以与 LLM 对话、提问、挑战它的框架，或调用其他技能来获取不同视角：
|
||||
|
||||
- **"run advanced elicitation on the error handling"** — 推动 LLM 重新思考并细化对特定领域的分析
|
||||
- **"party mode on whether this schema migration is safe"** — 引入多个 agent 视角进行聚焦辩论
|
||||
- **"run code review"** — 生成包含对抗性和边界场景分析的结构化 agentic 审查报告
|
||||
|
||||
检查点工作流不会把你锁在线性路径上。它在你需要结构时提供结构，在你想探索时让开。五个步骤确保你看到全貌，但每一步深入到什么程度——以及调用什么工具——完全由你决定。
|
||||
|
||||
## 审查线索
|
||||
|
||||
走查步骤在有**建议审查顺序**时效果最好——这是 spec 作者编写的停靠点列表，用于引导审查者走过变更。当 spec 包含此内容时，工作流直接使用它。
|
||||
|
||||
当没有作者提供的线索时，工作流会从 diff 和代码库上下文生成一份。生成的线索质量不如作者编写的，但远好于按文件顺序阅读变更。
|
||||
|
||||
## 何时使用
|
||||
|
||||
主要场景是 `bmad-quick-dev` 的交接：实现完成，spec 文件在编辑器中打开并追加了审查线索，你需要决定是否发布。说 "checkpoint" 即可开始。
|
||||
|
||||
它也可以独立使用：
|
||||
|
||||
- **审查 PR** — 尤其是涉及多个文件或跨模块变更的 PR
|
||||
- **了解一个变更** — 当你需要理解一个不是你写的分支上发生了什么
|
||||
- **Sprint 审查** — 工作流可以提取 sprint 状态文件中标记为 `review` 的 story
|
||||
|
||||
通过说 "checkpoint" 或 "walk me through this change" 来调用。它在任何终端中都能工作，但在 IDE 中——VS Code、Cursor 或类似工具——你会获得更多，因为工作流在每一步都生成 `path:line` 引用。在嵌入 IDE 的终端中，这些引用是可点击的，你可以沿着审查线索在文件间跳转。
|
||||
|
||||
## 它不是什么
|
||||
|
||||
检查点预览不是自动化审查的替代品。它不运行 linter、类型检查器或测试套件。它不打分也不给出通过/不通过的判定。它是一份阅读指南，帮助人类在最重要的地方运用自己的判断力。
|
||||
|
|
@ -0,0 +1,180 @@
|
|||
---
|
||||
title: "安装自定义和社区模块"
|
||||
description: 从社区注册表、Git 仓库或本地路径安装第三方模块
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
使用 BMad 安装程序从社区注册表、第三方 Git 仓库或本地文件路径添加模块。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 从 BMad 注册表安装社区贡献的模块
|
||||
- 从第三方 Git 仓库安装模块（GitHub、GitLab、Bitbucket、自托管）
|
||||
- 使用 BMad Builder 测试本地开发中的模块
|
||||
- 从私有或自托管 Git 服务器安装模块
|
||||
|
||||
:::note[前置条件]
|
||||
需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（npm 自带）。自定义和社区模块可以在全新安装时选择，也可以添加到现有安装中。
|
||||
:::
|
||||
|
||||
## 社区模块
|
||||
|
||||
社区模块收录在 [BMad 插件市场](https://github.com/bmad-code-org/bmad-plugins-marketplace)。它们按类别组织，并锁定在经过审核的 commit 上以确保安全。
|
||||
|
||||
### 1. 运行安装程序
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
### 2. 浏览社区目录
|
||||
|
||||
选择官方模块后，安装程序会询问：
|
||||
|
||||
```
|
||||
Would you like to browse community modules?
|
||||
```
|
||||
|
||||
选择 **Yes** 进入目录浏览器。你可以：
|
||||
|
||||
- 按类别浏览
|
||||
- 查看推荐模块
|
||||
- 查看所有可用模块
|
||||
- 按关键词搜索
|
||||
|
||||
### 3. 选择模块
|
||||
|
||||
从任意类别中选取模块。安装程序显示描述、版本和信任等级。已安装的模块会预选以便更新。
|
||||
|
||||
### 4. 继续安装
|
||||
|
||||
选择社区模块后，安装程序将继续到自定义来源，然后是工具/IDE 配置及其余安装流程。
|
||||
|
||||
## 自定义来源（Git URL 和本地路径）
|
||||
|
||||
自定义模块可以来自任何 Git 仓库或本地目录。安装程序会解析来源、分析模块结构，并将其与其他模块一起安装。
|
||||
|
||||
### 交互式安装
|
||||
|
||||
安装过程中，在社区模块步骤之后，安装程序会询问：
|
||||
|
||||
```
|
||||
Would you like to install from a custom source (Git URL or local path)?
|
||||
```
|
||||
|
||||
选择 **Yes**，然后提供来源：
|
||||
|
||||
| 输入类型 | 示例 |
|
||||
| -------- | ---- |
|
||||
| HTTPS URL（任意主机） | `https://github.com/org/repo` |
|
||||
| 带子目录的 HTTPS URL | `https://github.com/org/repo/tree/main/my-module` |
|
||||
| SSH URL | `git@github.com:org/repo.git` |
|
||||
| 本地路径 | `/Users/me/projects/my-module` |
|
||||
| 使用 ~ 的本地路径 | `~/projects/my-module` |
|
||||
|
||||
安装程序会克隆仓库（URL 来源）或直接从磁盘读取（本地路径），然后展示发现的模块供你选择。
|
||||
|
||||
### 非交互式安装
|
||||
|
||||
使用 `--custom-source` 标志从命令行安装自定义模块：
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--custom-source /path/to/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
提供 `--custom-source` 但未指定 `--modules` 时，只安装 core 和自定义模块。要同时包含官方模块，需添加 `--modules`：
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--modules bmm \
|
||||
--custom-source https://gitlab.com/myorg/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
多个来源可用逗号分隔：
|
||||
|
||||
```bash
|
||||
--custom-source /path/one,https://github.com/org/repo,/path/two
|
||||
```
|
||||
|
||||
## 模块发现机制
|
||||
|
||||
安装程序使用两种模式在来源中查找可安装的模块：
|
||||
|
||||
| 模式 | 触发条件 | 行为 |
|
||||
| ---- | -------- | ---- |
|
||||
| 发现模式 | 来源包含 `.claude-plugin/marketplace.json` | 列出清单中的所有插件；你选择要安装哪些 |
|
||||
| 直接模式 | 未找到 marketplace.json | 扫描目录中的 skill（包含 `SKILL.md` 的子目录），作为单个模块解析 |
|
||||
|
||||
发现模式适用于已发布的模块。直接模式适合本地开发时指向 skills 目录。
|
||||
|
||||
:::note[关于 `.claude-plugin/`]
|
||||
`.claude-plugin/marketplace.json` 路径是多个 AI 工具安装程序采用的标准约定，用于插件可发现性。它不依赖 Claude，不使用 Claude API，也不影响你使用哪个 AI 工具。任何包含此文件的模块都可以被遵循此约定的安装程序发现。
|
||||
:::
|
||||
|
||||
## 本地开发工作流
|
||||
|
||||
如果你正在使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 构建模块，可以直接从工作目录安装：
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory ~/my-project \
|
||||
--custom-source ~/my-module-repo/skills \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
本地来源通过路径引用，不会复制到缓存。当你更新模块源码并重新安装时，安装程序会获取最新变更。
|
||||
|
||||
:::caution[来源移除]
|
||||
如果你在安装后删除了本地来源目录，`_bmad/` 中已安装的模块文件会保留。在恢复来源路径之前，该模块在更新时会被跳过。
|
||||
:::
|
||||
|
||||
## 安装结果
|
||||
|
||||
安装后，自定义模块与官方模块一起出现在 `_bmad/` 中：
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── _bmad/
|
||||
│ ├── core/ # 内置核心模块
|
||||
│ ├── bmm/ # 官方模块（如已选择）
|
||||
│ ├── my-module/ # 你的自定义模块
|
||||
│ │ ├── my-skill/
|
||||
│ │ │ └── SKILL.md
|
||||
│ │ └── module-help.csv
|
||||
│ └── _config/
|
||||
│ └── manifest.yaml # 跟踪所有模块、版本和来源
|
||||
└── ...
|
||||
```
|
||||
|
||||
manifest 记录每个自定义模块的来源（Git 来源为 `repoUrl`，本地来源为 `localPath`），以便快速更新时能重新定位来源。
|
||||
|
||||
## 更新自定义模块
|
||||
|
||||
自定义模块参与正常的更新流程：
|
||||
|
||||
- **快速更新**（`--action quick-update`）：从原始来源刷新所有模块。基于 Git 的模块会重新拉取；本地模块会从来源路径重新读取。
|
||||
- **完整更新**：重新运行模块选择，你可以添加或移除自定义模块。
|
||||
|
||||
## 创建自己的模块
|
||||
|
||||
使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 创建可供他人安装的模块：
|
||||
|
||||
1. 运行 `bmad-module-builder` 搭建模块结构
|
||||
2. 使用各种 BMad Builder 工具添加 skill、agent 和 workflow
|
||||
3. 发布到 Git 仓库或共享文件夹集合
|
||||
4. 他人使用 `--custom-source <your-repo-url>` 安装
|
||||
|
||||
要让模块支持发现模式，请在仓库根目录包含 `.claude-plugin/marketplace.json`（这是跨工具约定，非 Claude 专属）。格式详见 [BMad Builder 文档](https://github.com/bmad-code-org/bmad-builder)。
|
||||
|
||||
:::tip[先在本地测试]
|
||||
开发期间，使用本地路径安装模块以快速迭代，发布到 Git 仓库之前先确认一切正常。
|
||||
:::
|
||||
Loading…
Reference in New Issue