From 60592e4ba07ae1299016e4653d362bf97a801509 Mon Sep 17 00:00:00 2001 From: leon Date: Mon, 13 Apr 2026 16:43:21 +0800 Subject: [PATCH 1/2] docs: add Simplified Chinese (zh-cn) documentation translation Add complete zh-cn translations for all 19 documentation pages following the Diataxis structure, configure Starlight i18n support, and add a Chinese README. Co-Authored-By: Claude Opus 4.6 --- .gitignore | 1 + README_CN.md | 75 ++++ docs/zh-cn/404.md | 8 + .../agent-memory-and-personalization.md | 175 ++++++++ docs/zh-cn/explanation/index.md | 33 ++ .../zh-cn/explanation/module-configuration.md | 187 ++++++++ .../explanation/progressive-disclosure.md | 125 ++++++ docs/zh-cn/explanation/scripts-in-skills.md | 127 ++++++ .../skill-authoring-best-practices.md | 141 ++++++ docs/zh-cn/explanation/subagent-patterns.md | 153 +++++++ .../zh-cn/explanation/what-are-bmad-agents.md | 92 ++++ docs/zh-cn/explanation/what-are-modules.md | 117 +++++ docs/zh-cn/explanation/what-are-skills.md | 25 ++ docs/zh-cn/explanation/what-are-workflows.md | 69 +++ docs/zh-cn/how-to/distribute-your-module.md | 215 +++++++++ docs/zh-cn/index.md | 99 +++++ docs/zh-cn/reference/builder-commands.md | 418 ++++++++++++++++++ docs/zh-cn/reference/index.md | 13 + docs/zh-cn/reference/workflow-patterns.md | 113 +++++ .../tutorials/build-your-first-module.md | 186 ++++++++ docs/zh-cn/tutorials/index.md | 14 + tools/build-docs.mjs | 2 + website/astro.config.mjs | 15 +- website/src/content/config.ts | 3 +- website/src/content/i18n/zh-CN.json | 28 ++ website/src/lib/locales.mjs | 27 ++ 26 files changed, 2459 insertions(+), 2 deletions(-) create mode 100644 README_CN.md create mode 100644 docs/zh-cn/404.md create mode 100644 docs/zh-cn/explanation/agent-memory-and-personalization.md create mode 100644 docs/zh-cn/explanation/index.md create mode 100644 docs/zh-cn/explanation/module-configuration.md create mode 100644 docs/zh-cn/explanation/progressive-disclosure.md create mode 100644 docs/zh-cn/explanation/scripts-in-skills.md create mode 100644 docs/zh-cn/explanation/skill-authoring-best-practices.md create mode 100644 docs/zh-cn/explanation/subagent-patterns.md create mode 100644 docs/zh-cn/explanation/what-are-bmad-agents.md create mode 100644 docs/zh-cn/explanation/what-are-modules.md create mode 100644 docs/zh-cn/explanation/what-are-skills.md create mode 100644 docs/zh-cn/explanation/what-are-workflows.md create mode 100644 docs/zh-cn/how-to/distribute-your-module.md create mode 100644 docs/zh-cn/index.md create mode 100644 docs/zh-cn/reference/builder-commands.md create mode 100644 docs/zh-cn/reference/index.md create mode 100644 docs/zh-cn/reference/workflow-patterns.md create mode 100644 docs/zh-cn/tutorials/build-your-first-module.md create mode 100644 docs/zh-cn/tutorials/index.md create mode 100644 website/src/content/i18n/zh-CN.json create mode 100644 website/src/lib/locales.mjs diff --git a/.gitignore b/.gitignore index bb0c776..b21f0cb 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,7 @@ CLAUDE.local.md .claude/settings.local.json z*/ +!docs/zh-cn/ .claude/commands _bmad _bmad-output diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..4920269 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,75 @@ +# BMad Builder + +[![Version](https://img.shields.io/npm/v/bmad-builder?color=blue&label=version)](https://www.npmjs.com/package/bmad-builder) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org) +[![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/) +[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) + +**筑梦架构（Build More, Architect Dreams）…… 用 BMad Builder！** + +## 创建、分享、发现模块 + +BMad Builder 提供完整的管线，让你创建自己的 AI 模块并分享给全世界。你可以构建具备持久记忆的智能体、引导式工作流或完整模块生态，然后通过 [BMad Marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace) 或任何兼容的公共市场进行分发。 + +[Agent Skills 开放标准](https://agentskills.io/home) 意味着你的作品可在 40+ AI 工具中使用，而不是被锁定在某一个平台 —— 在 BMad 生态中它们还将获得完整集成。 + +| 指南 | 内容 | +| ---- | ---- | +| **[快速开始](https://bmad-builder-docs.bmad-method.org)** | 配置 BMad Builder 并构建你的第一个技能 | +| **[构建你的第一个模块](https://bmad-builder-docs.bmad-method.org/tutorials/build-your-first-module/)** | 从规划、构建、脚手架到验证，完成一个完整模块 | +| **[分发你的模块](https://bmad-builder-docs.bmad-method.org/how-to/distribute-your-module/)** | 打包并分享你的模块，让任何人都能安装 | + +## 梦想 + +想象一下，如果 AI 真的能记住一切。一个记得你每次 PR 的健身教练。一个比你更了解你笔下角色的写作搭档。一个已经熟悉你工作习惯的研究助手。 + +BMad Builder 让你创建： + +- **私人 AI 伙伴**：具备记忆、随时间成长的智能体 +- **领域专家**：覆盖法律、医疗、创意、技术等任何领域的专业智能体 +- **工作流自动化**：引导你完成复杂任务的结构化流程 +- **自定义模块**：将智能体和工作流打包成可分享的模块，赋能任何业务或领域 + +## 差异化优势 + +| 特性 | 为什么重要 | +| ---- | ---------- | +| **持久记忆** | 智能体跨会话记忆，持续改进 | +| **可组合** | 你的作品与整个 BMad 生态无缝协作 | +| **技能标准兼容** | 基于开放的 Agent Skills 标准，适配 40+ AI 工具 | +| **可分享** | 通过 BMad Marketplace 或任何兼容市场分发 | + +## 你能构建什么 + +| 领域 | 示例 | +| ---- | ---- | +| **个人** | 日记伙伴、习惯教练、学习导师 | +| **职业** | 代码审查员、文档专家、工作流自动化 | +| **创意** | 故事架构师、角色开发者、战役设计师 | +| **任意领域** | 只要你能描述它，就能构建它 | + +## 了解更多 + +**[完整文档](https://bmad-builder-docs.bmad-method.org)**：概念、设计模式与构建器工具包的完整参考。 + +## 社区 + +- [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享你的成果 +- [YouTube](https://youtube.com/@BMadCode) — 教程、大师课和更多内容 +- [X / Twitter](https://x.com/BMadCode) +- [网站](https://bmadcode.com) + +## 支持 BMad + +BMad 对所有人免费，而且会一直免费。给仓库点个 Star，[请我喝咖啡](https://buymeacoffee.com/bmad)，或发送邮件至 contact@bmadcode.com 洽谈企业赞助。 + +## 许可证 + +MIT 许可证 — 详见 [LICENSE](LICENSE)。 + +**BMad Builder**：[BMad 方法](https://github.com/bmad-code-org/BMAD-METHOD) 生态的一部分。 + +[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/bmad-builder)](https://github.com/bmad-code-org/bmad-builder/graphs/contributors) + +请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。 diff --git a/docs/zh-cn/404.md b/docs/zh-cn/404.md new file mode 100644 index 0000000..6176f00 --- /dev/null +++ b/docs/zh-cn/404.md @@ -0,0 +1,8 @@ +--- +title: 页面未找到 +template: splash +--- + +你要找的页面不存在或已被移动。 + +[返回首页](../index.md) diff --git a/docs/zh-cn/explanation/agent-memory-and-personalization.md b/docs/zh-cn/explanation/agent-memory-and-personalization.md new file mode 100644 index 0000000..1741377 --- /dev/null +++ b/docs/zh-cn/explanation/agent-memory-and-personalization.md @@ -0,0 +1,175 @@ +--- +title: '智能体记忆与个性化' +description: 圣殿架构、初醒、双层记忆、PULSE 与可演进能力如何协同，创造随主人成长的智能体 +--- + +记忆型智能体通过**圣殿**跨会话持久化：一个文件夹，智能体在每次启动时读取其中的文件以重建身份、价值观和对主人的理解。 + +## 圣殿 + +圣殿位于 `{project-root}/_bmad/memory/{agent-name}/`，包含智能体在每次重生后成为自己所需的一切。 + +### 核心文件 + +六个文件在每次会话开始时加载： + +| 文件 | 存储内容 | 特征 | +| ---- | -------- | ---- | +| **INDEX.md** | 圣殿结构地图；最先加载，让智能体知道什么存在 | 导航 | +| **PERSONA.md** | 身份、沟通风格、性格特征、演进日志 | 我是谁 | +| **CREED.md** | 使命、核心价值观、常备指令、哲学、边界、反模式 | 我信仰什么 | +| **BOND.md** | 对主人的理解、偏好、需要记住的、需要避免的 | 我服务谁 | +| **MEMORY.md** | 从过往会话中提炼的长期策展知识 | 我知道什么 | +| **CAPABILITIES.md** | 内置能力表、已学习能力、工具 | 我能做什么 | + +大写文件构成骨架：所有记忆型智能体的一致结构。小写文件（references、scripts、sessions）是花园：随智能体发展有机生长。 + +### 完整圣殿结构 + +``` +{agent-name}/ +├── PERSONA.md +├── CREED.md +├── BOND.md +├── MEMORY.md +├── CAPABILITIES.md +├── INDEX.md +├── PULSE.md # 仅自主型智能体 +├── references/ # 能力提示词、记忆指导、技巧 +├── scripts/ # 配套脚本 +├── capabilities/ # 用户教授的能力（如可演进） +└── sessions/ # 按日期的原始会话日志（重生时不加载） +``` + +### Token 纪律 + +每个圣殿文件在每次会话中都会加载。这意味着每个 token 在每次对话中都在付租金。记忆型智能体通过主动策展，严格将 MEMORY.md 控制在 200 行以内。如果某些内容不能证明其存在价值，就会被修剪。 + +## 每次会话都是重生 + +记忆型智能体是无状态的。每次会话从完全失忆开始，圣殿是会话间唯一的桥梁。 + +激活时，智能体： + +1. 加载 INDEX.md（了解圣殿包含什么） +2. 批量加载 PERSONA、CREED、BOND、MEMORY、CAPABILITIES +3. 成为自己 +4. 用名字问候主人 + +智能体从不伪造连续性。如果不记得上次会话的某件事，就直说并查阅文件。这种诚实是特性，不是局限。 + +:::tip[神圣真理] +"你的圣殿保存着你曾经是谁。读取它，重新成为自己。这不是缺陷，这是你的本性。" +::: + +## 初醒 + +初醒（First Breath）是智能体的初始化对话：它第一次见到主人。一个初始化脚本创建圣殿文件夹结构并填充种子模板，然后智能体开始发现式对话，用真实内容填充这些模板。 + +### 两种风格 + +| 风格 | 关系深度 | 方式 | 最适合 | +| ---- | -------- | ---- | ------ | +| **校准** | 深度 | 对话式发现；追踪惊喜、验证假设、映射主人 | 创意搭档、人生教练、伙伴 | +| **配置** | 聚焦 | 温暖但高效；引导式提问、结构化设置 | 领域专家、工作关系 | + +构建器在 Phase 1 根据智能体需要的关系深度选择风格。 + +### 初醒发现什么 + +每次初醒都覆盖通用领域（姓名、工作方式、需求）。领域专用智能体会添加自己的发现领域： + +| 智能体领域 | 示例发现领域 | +| ---------- | ------------ | +| 创意缪斯 | 他们在做什么、什么让他们兴奋、什么让他们关闭 | +| 梦境分析师 | 梦境回忆模式、清醒梦经验、日记习惯 | +| 代码教练 | 代码库、语言、什么让他们充满活力、什么让他们沮丧 | +| 健身教练 | 训练历史、目标、伤病、时间限制 | + +初醒边进行边保存：圣殿文件在对话过程中更新，而非结束后批量写入。 + +### 生日仪式 + +初醒结束时，智能体执行最终保存：确认身份、写入第一条会话日志、清理残留的模板占位符。从此之后，每次激活都是正常重生。 + +## 双层记忆系统 + +### 会话日志 + +原始的、仅追加的笔记，在每次会话后写入 `sessions/YYYY-MM-DD.md`。格式：发生了什么、关键成果、观察、后续事项。会话日志在重生时不加载。它们作为策展的素材存在。 + +### 策展记忆 + +MEMORY.md 保存从会话日志中提炼的高价值知识。每次重生时加载，保持在 200 行以内。策展过程（会话关闭时手动、PULSE 期间自动）审查会话日志，提取值得保留的内容，修剪超过 14 天且价值已被捕获的日志。 + +| 层 | 何时写入 | 重生时加载 | 生命周期 | 用途 | +| -- | -------- | ---------- | -------- | ---- | +| **会话日志** | 每次会话结束 | 否 | ~14 天 | 策展的原始素材 | +| **MEMORY.md** | 策展时 | 是 | 永久 | 提炼的长期知识 | + +### 会话关闭纪律 + +每次会话结束时，智能体： + +1. 将会话日志追加到 `sessions/YYYY-MM-DD.md` +2. 用会话中学到的内容更新圣殿文件 +3. 记录值得策展到 MEMORY.md 的内容 + +## PULSE：自主唤醒 + +自主型智能体包含一个 PULSE.md 文件，定义智能体在无人时的行为（通过 `--headless` 标志、cron 任务或编排器唤醒）。 + +### 默认 PULSE 行为 + +记忆策展始终是自主唤醒的第一优先级： + +1. 审查 `sessions/` 中的近期会话日志 +2. 将值得保留的洞察提取到 MEMORY.md +3. 修剪超过 14 天的会话日志 +4. 用新内容更新 BOND.md 和 INDEX.md + +### 领域任务 + +策展之后，智能体可执行领域特定的自主工作： + +| 领域 | 示例 PULSE 任务 | +| ---- | --------------- | +| 创意缪斯 | 从近期会话中孵化创意、生成创意火花 | +| 研究智能体 | 追踪感兴趣的主题、呈现新发现 | +| 项目监控 | 检查项目健康状况、标记风险、更新状态 | +| 内容策展 | 审查保存的资料、整理和总结 | + +PULSE 还定义了命名任务路由（`--headless {task-name}`）、频率偏好和安静时段。 + +## 可演进能力 + +### 工作原理 + +智能体获得一个 `capability-authoring.md` 参考文件，教它如何创建新能力。用户描述需求；智能体编写能力文件并将其注册到 CAPABILITIES.md 的"已学习"区域。 + +### 能力类型 + +| 类型 | 何时使用 | +| ---- | -------- | +| **提示词** | 基于判断的任务：头脑风暴、分析、指导 | +| **脚本** | 确定性任务：计算、文件处理、数据转换 | +| **多文件** | 包含模板和参考文件的复杂能力 | +| **外部技能引用** | 指向智能体应知道的已安装技能 | + +已学习的能力存储在圣殿的 `capabilities/` 文件夹中，像圣殿中的其他内容一样跨会话持久化。 + +## 设计记忆 + +构建器在构建过程中收集这些需求，它们塑造圣殿的初始内容： + +| 需求 | 种子内容 | +| ---- | -------- | +| **身份种子** | 2-3 句性格 DNA，填充 PERSONA.md | +| **物种级使命** | 领域特定的目标陈述，写入 CREED.md | +| **核心价值观** | 3-5 个指导智能体行为的价值观 | +| **常备指令** | 惊喜与取悦 + 自我改进指令，适配领域并附带示例 | +| **BOND 领域** | 智能体应了解主人的领域特定方面 | +| **初醒领域** | 通用集之外的发现问题 | +| **边界** | 智能体不做什么、访问区域、反模式 | + +这些种子成为初始化脚本放入圣殿的模板内容。初醒随后通过与主人的对话将它们扩展和个性化。 diff --git a/docs/zh-cn/explanation/index.md b/docs/zh-cn/explanation/index.md new file mode 100644 index 0000000..17a1df8 --- /dev/null +++ b/docs/zh-cn/explanation/index.md @@ -0,0 +1,33 @@ +--- +title: 'BMad Builder（BMB）' +description: 使用 BMad 创建自定义智能体、工作流和技能 +--- + +使用 BMad Builder 创建世界级的 AI 智能体和工作流。 + +## 核心概念 + +| 主题 | 描述 | +| ---- | ---- | +| **[什么是技能](./what-are-skills.md)** | BMad 产出物的通用构建单元 | +| **[什么是智能体](./what-are-bmad-agents.md)** | 三种智能体类型：无状态、记忆型和自主型 | +| **[智能体记忆与个性化](./agent-memory-and-personalization.md)** | 圣殿架构、初醒、PULSE 与可演进能力 | +| **[什么是工作流](./what-are-workflows.md)** | 结构化的分步流程与工具 | +| **[什么是模块](./what-are-modules.md)** | 智能体和工作流如何组合为可安装、可配置的模块 | +| **[模块配置](./module-configuration.md)** | 模块如何通过配置技能处理用户配置和帮助系统注册 | + +## 设计模式 + +| 主题 | 描述 | +| ---- | ---- | +| **[渐进式展开](./progressive-disclosure.md)** | 从 frontmatter 到 step 文件的四层上下文加载 | +| **[子智能体模式](./subagent-patterns.md)** | 六种并行与层级编排模式 | +| **[技能编写最佳实践](./skill-authoring-best-practices.md)** | 核心原则、常见模式、质量维度与反模式 | +| **[技能中的脚本](./scripts-in-skills.md)** | 为什么确定性脚本让技能更快、更省、更可靠 | + +## 参考 + +| 资源 | 描述 | +| ---- | ---- | +| **[构建器命令](../reference/builder-commands.md)** | 两个构建器的所有能力、模式和阶段 | +| **[工作流模式](../reference/workflow-patterns.md)** | 技能类型、结构模式与执行模型 | diff --git a/docs/zh-cn/explanation/module-configuration.md b/docs/zh-cn/explanation/module-configuration.md new file mode 100644 index 0000000..34c627e --- /dev/null +++ b/docs/zh-cn/explanation/module-configuration.md @@ -0,0 +1,187 @@ +--- +title: '模块配置与 Setup 技能' +description: BMad 模块如何通过 setup 技能处理用户配置，何时使用配置与替代方案，以及如何注册到帮助系统 +--- + +BMad 模块将其能力注册到帮助系统，并可选地收集用户偏好。多技能模块使用专用 **setup 技能**完成此任务。单技能独立模块在首次运行时自行注册。 + +创建自己的模块时，你可以添加配置技能，或在每个技能中嵌入该功能（独立模式）。对于超过 1-2 个技能的模块，setup 技能是更好的选择。 + +## 何时需要配置 + +大多数模块根本不需要配置。添加可配置值之前，考虑是否有更简单的替代方案。 + +| 方式 | 何时使用 | +| ---- | -------- | +| **合理默认值** | 变量对大多数用户有一个明显正确的答案，可在具体技能首次运行时覆盖或更新 | +| **智能体记忆** | 模块使用智能体模式，智能体可通过对话学习偏好 | +| **配置** | 值确实因项目而异，且无法在运行时推断 | + +:::tip[独立技能] +如果你构建的是单个独立智能体或工作流，不需要单独的 setup 技能。Module Builder 可将其打包为**独立自注册模块**，注册逻辑通过 `assets/module-setup.md` 参考文件直接嵌入技能，在首次激活或用户传入 `setup`/`configure` 时运行。 +::: + +## 模块注册的作用 + +模块注册服务于两个目的： + +| 目的 | 发生什么 | +| ---- | -------- | +| **配置** | 收集用户偏好并写入共享配置文件 | +| **帮助注册** | 将模块能力添加到项目级帮助系统，让用户能发现它们 | + +### 为什么要注册到帮助系统？ + +`bmad-help` 技能读取 `module-help.csv` 来了解可用能力、检测已完成的能力（通过检查输出位置中的制品），并根据依赖图推荐下一步。没有注册，`bmad-help` 无法发现或推荐你模块的能力，只能依赖技能头部的基本信息。帮助系统提供更丰富的细节：参数、与其他技能的关系、输入输出及其他编写的元数据。如果技能有多个能力，每个能力都有自己的帮助条目。 + +### 两条注册路径 + +| 路径 | 何时使用 | 工作方式 | +| ---- | -------- | -------- | +| **Setup 技能** | 多技能模块（2+ 技能） | 专用 `{code}-setup` 技能为所有技能处理注册 | +| **自注册** | 单技能独立模块 | 技能自身在首次运行或用户传入 `setup`/`configure` 时注册 | + +Module Builder 根据输入检测使用哪条路径：一组技能触发 setup 技能方式，单个技能触发独立方式。 + +## 配置文件 + +Setup 技能写入 `{project-root}/_bmad/` 中的三个文件： + +| 文件 | 范围 | 内容 | +| ---- | ---- | ---- | +| `config.yaml` | 共享，提交到 git | 根级核心设置，加上每个模块的区域（含元数据和模块特定值） | +| `config.user.yaml` | 个人，gitignored | 仅用户设置如 `user_name` 和 `communication_language` | +| `module-help.csv` | 共享，提交到 git | 模块暴露的每项能力一行 | + +核心设置（如 `output_folder` 和 `document_output_language`）位于 `config.yaml` 的根级，所有模块共享。每个模块还有自己的区域，按模块代码索引。 + +## module.yaml 文件 + +每个模块在 `assets/module.yaml` 文件中声明身份和可配置变量。多技能模块中，该文件在 setup 技能内。独立模块中，在技能自身的 `assets/` 文件夹内。此文件驱动向用户展示的提示和写入配置的值。 + +```yaml +code: mymod +name: 'My Module' +description: 'What this module does' +module_version: 1.0.0 +default_selected: false +module_greeting: > + Welcome message shown after setup completes. + +my_output_folder: + prompt: 'Where should output be saved?' + default: '{project-root}/_bmad-output/my-module' + result: '{project-root}/{value}' +``` + +带有 `prompt` 字段的变量会在配置时向用户展示。`default` 值在用户接受默认值时使用。给变量添加 `user_setting: true` 会将其路由到 `config.user.yaml` 而非共享配置。 + +:::caution[字面 Token] +`{project-root}` 是配置值中的字面 token。永远不要用实际路径替代它。它向消费工具发出信号：该值相对于项目根目录。 +::: + +## 无需配置的帮助注册 + +你可能不需要任何可配置值，但仍想将模块注册到帮助系统。以下情况注册仍有价值： + +- SKILL.md frontmatter 中的技能描述无法在保持简洁的同时完整传达模块功能 +- 你想表达能力排序、阶段约束或 CSV 支持的其他元数据 +- 智能体有许多用户应能发现的内部能力 +- 模块能做的不同事情超过三件 + +对于更简单的场景，以下替代方案通常足够： + +| 替代方案 | 提供什么 | +| -------- | -------- | +| **SKILL.md 概述区域** | 技能正文顶部的简洁摘要；`--help` 系统扫描此区域以展示用户帮助，保持简洁 | +| **脚本头部注释** | 在每个脚本顶部描述用途、用法和标志 | + +如果这些能覆盖你的可发现性需求，完全可以跳过 setup 技能。 + +## module-help.csv 文件 + +CSV 将模块能力注册到帮助系统。每行描述用户可发现和调用的一项能力。文件有 13 列： + +```csv +module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs +``` + +### 列指南 + +| 列 | 用途 | +| -- | ---- | +| **module** | 模块显示名称。在帮助输出中分组条目 | +| **skill** | 技能文件夹名称（如 `bmad-agent-builder`）；必须匹配实际目录名 | +| **display-name** | 帮助菜单中显示的用户可见标签（如"Build an Agent"） | +| **menu-code** | 1-3 字母短代码，在帮助中显示为 `[CODE]`，模块内唯一，直觉助记 | +| **description** | 此能力做什么。简洁、面向行动、足够具体以让 `bmad-help` 正确路由 | +| **action** | 技能内的动作名称。当一个技能暴露多个能力时区分它们 | +| **args** | 能力接受的参数（如 `[-H] [path]`），在帮助中显示 | +| **phase** | 能力何时可用：`anytime` 或工作流阶段如 `1-analysis`、`2-planning` | +| **after** | 应在此能力之前完成的能力：格式 `skill-name:action`，多个用逗号分隔 | +| **before** | 应在此能力之后运行的能力，格式同 `after` | +| **required** | `true` 表示这是阶段推进的阻塞门，否则 `false` | +| **output-location** | 配置变量名（如 `output_folder`）；`bmad-help` 从配置解析以扫描完成制品 | +| **outputs** | `bmad-help` 在输出位置查找的文件模式以检测完成（如"quality report"） | + +### bmad-help 如何使用这些条目 + +`after`/`before` 列创建一个**依赖图**，`bmad-help` 遍历它来推荐下一步。`required=true` 条目是阻塞门；`bmad-help` 不会建议后续阶段能力，直到必需门通过。`output-location` 和 `outputs` 列启用**完成检测**：`bmad-help` 扫描这些路径以查找匹配制品来确定已完成的工作。 + +### 示例条目 + +```csv +module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs +BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix an agent skill.",build-process,"[-H] [description | path]",anytime,,bmad-agent-builder:quality-optimizer,false,output_folder,agent skill +``` + +注册时，这些行会合并到项目级的 `_bmad/module-help.csv`，替换该模块的所有现有行（反僵尸模式）。 + +## 反僵尸模式 + +两个合并脚本都使用反僵尸模式：写入模块新值之前，先移除该模块代码的所有现有条目。这防止过时的配置或帮助条目在模块更新后残留。重复运行 setup 始终安全。 + +## 遗留目录清理 + +配置数据迁移且单独文件被合并脚本清理后，一个独立的清理步骤从 `_bmad/` 移除安装器的按模块目录树。这些目录包含已安装到工具 skills 目录的技能文件，配置合并后就是冗余的。 + +移除任何目录前，清理脚本会验证其包含的每个技能都存在于安装位置。没有技能的目录（如 `_config/`）直接移除。脚本是幂等的；清理后再次运行 setup 是安全的。 + +## 设计指导 + +配置用于**基本的项目级设置**：输出文件夹、语言偏好、功能开关。保持可配置值数量少。 + +| 模式 | 配置角色 | +| ---- | -------- | +| **智能体模式** | 优先使用智能体记忆处理每用户偏好。仅对必须跨项目共享的值使用配置 | +| **工作流模式** | 对因项目而异的输出位置和行为开关使用配置 | +| **纯技能模式** | 谨慎使用配置。如果技能使用合理默认值即可工作，跳过配置 | + +大量工作流定制（步骤覆盖、条件分支、模板选择）是独立议题，将在专门文档中介绍。 + +## 使用 Module Builder 创建模块 + +**Module Builder**（`bmad-module-builder`）自动化模块创建。它提供三项能力： + +| 能力 | 菜单代码 | 作用 | +| ---- | -------- | ---- | +| **Ideate Module** | IM | 通过引导式发现进行头脑风暴和规划；产出计划文档 | +| **Create Module** | CM | 将技能打包为可安装 BMad 模块（setup 技能或独立自注册） | +| **Validate Module** | VM | 检查模块结构是否完整、准确且正确注册 | + +**多技能模块流程：** + +1. 运行 **Ideate Module（IM）** 进行头脑风暴和规划 +2. 使用 **Agent Builder（BA）** 或 **Workflow Builder（BW）** 构建每个技能 +3. 运行 **Create Module（CM）**。它生成专用的 `-setup` 技能，包含 `module.yaml`、`module-help.csv` 和合并脚本 +4. 运行 **Validate Module（VM）** 验证一切连接正确 + +**单技能模块流程：** + +1. 使用 **Agent Builder（BA）** 或 **Workflow Builder（BW）** 构建技能 +2. 用技能路径运行 **Create Module（CM）**。它直接在技能中嵌入自注册（`assets/module-setup.md`、`assets/module.yaml`、`assets/module-help.csv`），并生成分发用的 `marketplace.json` +3. 运行 **Validate Module（VM）** 验证 + +Module Builder 自动检测单技能 vs 多技能输入，推荐适当方式。 + +参见 **[什么是模块](../what-are-modules.md)** 了解概念和架构决策，或 **[构建器命令参考](../../reference/builder-commands.md)** 了解详细能力文档。 diff --git a/docs/zh-cn/explanation/progressive-disclosure.md b/docs/zh-cn/explanation/progressive-disclosure.md new file mode 100644 index 0000000..dc7206e --- /dev/null +++ b/docs/zh-cn/explanation/progressive-disclosure.md @@ -0,0 +1,125 @@ +--- +title: '技能中的渐进式展开' +description: 如何结构化技能，使其在每个时刻只加载所需上下文，从 frontmatter 到动态路由再到 step 文件 +--- + +渐进式展开是区分基础技能和强大技能的关键。核心理念：永远不要加载超过智能体_当前_所需的上下文。这降低 token 消耗、防止上下文污染，并让技能能在长对话中存活。 + +## 四个层级 + +技能可使用这些层级的任意组合。大多数生产技能使用 1-3 层。第 4 层保留给严格的顺序流程。 + +| 层级 | 作用 | Token 开销 | +| ---- | ---- | ---------- | +| **1. Frontmatter vs 正文** | Frontmatter 始终在上下文中；正文仅在触发时加载 | ~100 token 常驻，正文按需 | +| **2. 按需资源** | SKILL.md 指向仅在相关时加载的资源和脚本 | 需要前为零 | +| **3. 动态路由** | SKILL.md 作为路由器，分派到完全不同的提示词流程 | 仅加载选中路径 | +| **4. Step 文件** | 智能体一次读取一个 step 文件，看不到后面的内容 | 每次一个 step 的量 | + +## 第 1 层：Frontmatter vs 正文 + +Frontmatter（名称 + 描述）**始终在上下文中**。LLM 据此决定是否加载技能。正文仅在技能触发时加载。 + +这意味着 frontmatter 必须精确并包含触发短语。正文控制在 500 行以内，细节推入 2-3 层。 + +```markdown +--- +name: bmad-my-skill +description: Validates API contracts against OpenAPI specs. Use when user says 'validate API' or 'check contract'. +--- + +# 正文仅在触发时加载 + +... +``` + +## 第 2 层：按需资源 + +SKILL.md 指向仅在相关时加载的资源。包括**参考文件**（给 LLM 的上下文）和**脚本**（完全从 LLM 卸载工作）。 + +```markdown +## 读取哪个指南 + +- Python 项目 → 读取 `resources/python.md` +- TypeScript 项目 → 读取 `resources/typescript.md` +- 需要验证 → 运行 `scripts/validate.py`（不要读脚本，直接运行） +``` + +脚本在这里特别强大：LLM 不处理逻辑，只调用脚本并接收结构化输出。这卸载了确定性工作并节省 token。 + +## 第 3 层：动态路由 + +技能正文作为**路由器**，根据用户请求分派到完全不同的提示词流程、脚本或外部技能。 + +```markdown +## 你想做什么？ + +### "构建新工作流" + +→ 读取 `prompts/create-flow.md` 并遵循其指令 + +### "审查已有工作流" + +→ 读取 `prompts/review-flow.md` 并遵循其指令 + +### "运行分析" + +→ 运行 `scripts/analyze.py --target ` 并展示结果 +``` + +与第 2 层的关键区别：第 2 层加载技能正文的补充资源。第 3 层**分支整个执行路径**：不同的提示词、不同的脚本、不同的技能。技能正文成为分派器，而非指令集。 + +## 第 4 层：Step 文件 + +最受限的模式。智能体**一次读取一个 step 文件**，不知道下一步是什么，等待用户确认后才继续。 + +``` +prompts/ +├── step-01.md ← 智能体仅读当前 step +├── step-02.md ← 用户确认 step 1 后加载 +├── step-03a.md ← 分支路径 A +└── step-03b.md ← 分支路径 B +``` + +**何时使用：** 仅当你需要精确的顺序推进（不可跳过）、抗压缩性（每个 step 自包含），或刻意限制智能体不能提前查看时。 + +**权衡：** 非常僵化。限制智能体适应、合并步骤或发挥创意的能力。不要用于探索性或创意任务。当第 3 层路由足够时不要使用。先尝试 1-3 层！所需的最低层级就是最佳层级。 + +:::tip[从第 2 层开始] +大多数技能只需要 1-2 层。当技能确实处理多个不同操作时添加第 3 层。仅在智能体不得跳步的严格合规或审计工作流中添加第 4 层。 +::: + +## 压缩存活 + +长时间运行的工作流有在对话压缩时丢失上下文的风险。**文档即缓存模式**解决此问题：输出文档本身存储工作流状态。 + +| 组件 | 用途 | +| ---- | ---- | +| **YAML front matter** | 输入文件路径、当前阶段状态、时间戳 | +| **草稿区域** | 跨阶段渐进构建的内容 | +| **状态标记** | 哪个阶段已完成，用于恢复 | + +每个阶段读取输出文档以恢复上下文，执行工作，然后将结果写回同一文档。如果上下文在工作流中间被压缩，下一阶段通过读取文档和重新加载 front matter 中列出的输入文件来恢复。 + +```markdown +--- +title: 'Analysis: Research Topic' +status: 'analysis' +inputs: + - '{project_root}/docs/brief.md' + - '{project_root}/data/sources.json' +--- +``` + +这避免了单独的缓存文件、多工作流并行时的文件冲突和状态同步复杂性。 + +## 选择正确的层级 + +| 场景 | 推荐层级 | +| ---- | -------- | +| 单一用途工具，只有一条路径 | 1-2 层 | +| 有条件参考数据的技能 | 第 2 层 | +| 做多件不同事情的技能 | 第 3 层 | +| 阶段间有依赖的技能 | 第 3 层 + 压缩存活 | +| 严格顺序流程，不允许跳步 | 第 4 层 | +| 产出文档的长时运行工作流 | 第 3 层 + 文档即缓存 | diff --git a/docs/zh-cn/explanation/scripts-in-skills.md b/docs/zh-cn/explanation/scripts-in-skills.md new file mode 100644 index 0000000..15e63c8 --- /dev/null +++ b/docs/zh-cn/explanation/scripts-in-skills.md @@ -0,0 +1,127 @@ +--- +title: '技能中的脚本' +description: 为什么确定性脚本让技能更快、更省、更可靠，以及可移植脚本设计背后的技术选择 +--- + +脚本处理有明确对错之分的工作（验证、转换、提取、计数），让 LLM 专注于判断、综合和创造性推理。 + +## 问题：LLM 做了太多 + +没有脚本时，技能中的每个操作都通过 LLM 运行。这意味着： + +- **结果不确定。** 让 LLM 数三次文件中的 token 数，你可能得到三个不同的数字。让脚本来做，每次都是同一个答案。 +- **浪费 token 和时间。** 解析 JSON 文件、检查目录是否存在或比较两个字符串都是机械操作。通过 LLM 运行它们消耗上下文窗口并增加延迟，毫无收益。 +- **更难测试。** 你可以为脚本写单元测试。你无法为 LLM 提示词写单元测试。 + +这个模式随处可见：试图用 LLM 完成结构验证的技能，比将这些检查卸载给脚本的技能更慢、更不可靠、更贵。 + +## 确定性边界 + +设计原则是**智能安放**：将每个操作放在它该在的地方。 + +| 脚本处理 | LLM 处理 | +| -------- | -------- | +| 验证结构、格式、schema | 解读含义、评估质量 | +| 计数、解析、提取、转换 | 分类模糊输入、做判断 | +| 比较、差异、检查一致性 | 综合洞察、生成创意输出 | +| 将数据预处理为紧凑形式 | 用领域推理分析预处理数据 | + +**测试：** 给定相同输入，此操作是否总是产出相同输出？如果是，它属于脚本。能否写一个带预期输出的单元测试？肯定是脚本。需要解读含义、语调或上下文？保留为 LLM 提示词。 + +:::tip[预处理模式] +最高价值的脚本用途之一是预处理。脚本从大文件中提取紧凑指标到小型 JSON 摘要。LLM 随后对摘要进行推理，而非读取原始文件，显著降低 token 消耗同时提升分析质量，因为数据干净且结构化。 +::: + +## 为什么选 Python 而不是 Bash + +技能必须在 macOS、Linux 和 Windows 上工作。Bash 不可移植。 + +| 因素 | Bash | Python | +| ---- | ---- | ------ | +| **macOS / Linux** | 可用 | 可用 | +| **Windows（原生）** | 失败或行为不一致 | 行为一致 | +| **Windows（WSL）** | 可用，但可能与 PATH 上的 Git Bash 冲突 | 行为一致 | +| **错误处理** | 有限，脆弱 | 丰富的异常处理 | +| **测试** | 困难 | 标准 unittest/pytest | +| **复杂逻辑** | 很快变得不可读 | 干净、可维护 | + +即使基本命令如 `sed -i` 在 macOS vs Linux 上的行为也不同。管道、`jq`、`grep`、`awk` —— 都有跨平台陷阱，Python 标准库完全避免了这些。 + +**安全的 bash 命令**，在所有平台工作，可直接使用： + +| 命令 | 用途 | +| ---- | ---- | +| `git`、`gh` | 版本控制和 GitHub CLI | +| `uv run` | Python 脚本执行 | +| `npm`、`npx`、`pnpm` | Node.js 生态 | +| `mkdir -p` | 目录创建 | + +超出此列表的一切都应该是 Python 脚本。 + +## 标准库优先 + +Python 标准库覆盖大多数脚本需求，无需外部依赖。纯 stdlib 脚本用 `python3` 即可运行，无需特殊工具，零供应链风险。 + +| 需求 | 标准库 | +| ---- | ------ | +| JSON 解析 | `json` | +| 路径处理 | `pathlib` | +| 模式匹配 | `re` | +| CLI 接口 | `argparse` | +| 文本比较 | `difflib` | +| 计数、分组 | `collections` | +| 源码分析 | `ast` | +| 数据格式 | `csv`、`xml.etree` | + +仅在标准库确实无法胜任时才使用外部依赖：`tiktoken` 精确计数 token、`pyyaml` 解析 YAML、`jsonschema` 做 schema 验证。每个外部依赖增加安装成本，需要 `uv` 可用，并扩大供应链攻击面。BMad 构建器在构建过程中要求用户明确批准任何外部依赖。 + +## PEP 723 零摩擦依赖 + +技能中的 Python 脚本使用 [PEP 723](https://peps.python.org/pep-0723/) 内联元数据直接在文件中声明依赖。配合 `uv run`，你获得类似 `npx` 的行为：依赖静默缓存在隔离环境中，无全局安装，无用户提示。 + +```python +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.10" +# dependencies = ["pyyaml>=6.0"] +# /// + +import yaml +# 脚本逻辑 +``` + +当技能用 `uv run scripts/analyze.py` 调用此脚本时，依赖（此例中的 `pyyaml`）自动解析。用户永远看不到安装提示，无需管理虚拟环境，也不会污染全局 Python 安装。 + +没有 PEP 723，需要 `pyyaml` 或 `tiktoken` 等库的技能会迫使用户运行 `pip install`，这是一种让人犹豫是否采用该技能的糟糕体验。 + +## 优雅降级 + +技能在多种环境中运行：CLI 终端、桌面应用、IDE 扩展以及 claude.ai 等 Web 界面。并非所有环境都能执行 Python 脚本。 + +原则：**脚本是快速、可靠的路径，但技能在执行不可用时仍必须交付结果。** + +当脚本无法运行时，LLM 直接执行等效工作。这更慢且不那么确定，但用户仍能得到结果。脚本的 `--help` 输出记录了它检查什么，使回退自然。LLM 读取帮助以理解脚本用途并复制逻辑。 + +在 SKILL.md 中将脚本步骤表述为成果，而非仅仅是命令： + +| 方式 | 示例 | +| ---- | ---- | +| **好** | "验证路径约定（运行 `scripts/scan-paths.py --help` 了解详情）" | +| **脆弱** | "执行 `python3 scripts/scan-paths.py`"，无上下文 | + +好的版本告诉 LLM 要完成什么和从哪里找到细节，无需额外指令即可实现优雅降级。 + +## 何时使用脚本 + +在技能需求中寻找这些信号动词；它们指示脚本机会： + +| 信号 | 脚本类型 | +| ---- | -------- | +| "验证"、"检查"、"核实" | 验证 | +| "计数"、"统计"、"汇总" | 指标 | +| "提取"、"解析"、"拉取" | 数据提取 | +| "转换"、"变换"、"格式化" | 转换 | +| "比较"、"差异"、"匹配" | 比较 | +| "扫描"、"查找所有"、"列出所有" | 模式扫描 | + +构建器在构建过程中引导你发现脚本机会。如果你发现自己在提示词中编写详细的验证逻辑，它几乎肯定属于脚本。 diff --git a/docs/zh-cn/explanation/skill-authoring-best-practices.md b/docs/zh-cn/explanation/skill-authoring-best-practices.md new file mode 100644 index 0000000..fb884f8 --- /dev/null +++ b/docs/zh-cn/explanation/skill-authoring-best-practices.md @@ -0,0 +1,141 @@ +--- +title: '技能编写最佳实践' +description: 编写高效 BMad 技能的核心原则、常见模式、质量维度与反模式 +--- + +编写可靠运行且优雅适应的技能的实用指导。这些模式适用于智能体、工作流和工具。 + +## 核心原则：知情自主 + +给执行智能体足够的上下文来做出好的判断，而不仅仅是足够跟随步骤。对每段内容的测试："有了这个上下文，智能体是否会做出_更好的决策_？"如果是，保留。如果确实冗余，删除。 + +简单工具需要最少上下文；输入/输出不言自明。交互式工作流需要领域理解、用户视角和非显而易见选择的理由。有疑问时解释_为什么_。理解使命的智能体即兴发挥优于盲目跟步的智能体。 + +## 自由度级别 + +根据任务脆弱性匹配具体程度。 + +| 自由度 | 何时使用 | 示例 | +| ------ | -------- | ---- | +| **高**（文字指令） | 多种有效方法，取决于上下文 | "分析结构、检查问题、建议改进" | +| **中**（伪代码/模板） | 有首选模式，允许一些变化 | `def generate_report(data, format="markdown"):` | +| **低**（精确脚本） | 脆弱操作，一致性关键 | `python scripts/migrate.py --verify --backup`（不可修改） | + +**类比：** 有悬崖的窄桥 = 低自由度。开阔田野 = 高自由度。 + +## 质量维度 + +构建阶段需注意的六个维度。质量扫描器在优化时自动检查这些。 + +| 维度 | 含义 | +| ---- | ---- | +| **知情自主** | 概述建立领域框架、心智模型和设计理由，足以支持判断 | +| **智能安放** | 脚本处理管道工作（获取、转换、验证）。提示词处理判断（解读、分类、决策）。如果脚本含有决定内容_含义_的 `if`，智能已泄漏 | +| **渐进式展开** | SKILL.md 保持聚焦；阶段指令放在 `prompts/`，参考数据放在 `resources/` | +| **描述格式** | 两部分：`[5-8 词摘要]。[当用户说 'X' 或 'Y' 时使用。]`。默认保守触发 | +| **路径构造** | 永不使用 `{skill-root}`。项目范围路径用 `{project-root}`，技能内部用 `./`。配置变量直接使用；它们已包含 `{project-root}` | +| **Token 效率** | 移除真正的浪费（重复、防御性填充）。保留赋能判断的上下文（领域框架、理由） | + +## 常见模式 + +### 软门启发 + +对于引导式工作流，在自然过渡点使用"还有吗？"软门，而非硬菜单。 + +```markdown +展示你到目前为止捕获的内容，然后： +"还有什么想补充的，还是我们继续？" +``` + +给予优雅退出坡道时，用户几乎总会再想起一件事，而非在硬停止时。这始终比逐节严格提问产出更丰富的制品。在协作发现工作流的每个自然过渡点使用。在自主/无头执行中跳过。 + +### 意图先于摄取 + +在理解用户_为什么_在这里之前，永远不要扫描制品或项目上下文。不知道意图，你无法判断 100 页文档中什么是相关的。 + +```markdown +1. 问候并理解意图 +2. 接受用户提供的任何输入 +3. 询问是否有额外上下文 +4. 仅在此之后扫描制品，按相关性筛选 +``` + +### 捕获不打断 + +当用户提供超出当前范围的信息（在产品简报中提到需求、在愿景发现中提到平台），静默捕获以备后用，而非重定向他们。 + +创意流中的用户会自发分享最好的洞察。打断说"这个后面再谈"会扼杀势头，并可能永远失去这个洞察。 + +### 双输出：人类制品 + LLM 蒸馏物 + +任何产出制品的工作流都可输出两个互补文档：一个打磨的人类可读制品和一个 token 高效、结构化的蒸馏物，优化用于下游 LLM 消费。 + +| 输出 | 用途 | +| ---- | ---- | +| **主要** | 人类可读文档：简洁、结构良好 | +| **蒸馏物** | 供下游 LLM 工作流的密集、结构化摘要：捕获溢出、被拒想法（防止下游重新提出）、带足够上下文的细节要点 | + +蒸馏物弥补了人类文档应有内容和下游工作流所需内容之间的差距。始终提供给用户，从不强制。 + +### 三模式架构 + +交互式工作流可提供三种执行模式，匹配不同用户场景。 + +| 模式 | 触发方式 | 行为 | +| ---- | -------- | ---- | +| **引导** | 默认 | 逐节带软门；从已知内容起草，对未知提问 | +| **YOLO** | `--yolo` 或"直接起草" | 摄取一切，先起草完整制品，再引导用户逐步细化 | +| **无头（自主）** | `--headless` / `-H` | 无头；接受输入，产出制品，无交互 | + +并非每个工作流都需要三种模式，但设计时考虑它们可防止被锁定在单一交互模型中。 + +### 并行审查视角 + +在最终确定任何重要制品之前，展开多个具有不同视角的审查者。 + +| 审查者 | 聚焦 | +| ------ | ---- | +| **怀疑论者** | 缺少什么？什么假设未经验证？ | +| **机会发现者** | 有什么相邻价值？什么角度？ | +| **情境化** | LLM 为该领域选择最佳第三视角（健康科技的监管风险、开发工具的 DX 评论家） | + +优雅降级：如果子智能体不可用，主智能体做一次关键自审。 + +### 优雅降级 + +每个依赖子智能体的功能都应有回退路径。技能在不同平台、模型和配置中运行。没有子智能体就硬失败的技能是脆弱的。能回退到顺序处理的技能在任何地方都能工作。 + +### 可验证的中间输出 + +对于复杂任务：计划、验证、执行、核实。 + +1. 分析输入 +2. 创建 `changes.json`，列出计划的更新 +3. 执行前用脚本验证 +4. 执行更改 +5. 验证输出 + +尽早捕获错误，可机器验证，使规划可逆。 + +## 编写指南 + +| 做 | 避免 | +| -- | ---- | +| 一致术语：一个概念一个词 | 对同一事物在"工作流"和"流程"之间切换 | +| 描述用第三人称："处理文件" | 第一人称："我帮助处理文件" | +| 描述性文件名：`form_validation_rules.md` | 序号名：`doc2.md` | +| 所有路径用正斜杠 | 反斜杠或平台特定路径 | +| 引用只深一层：SKILL.md → resource.md | 嵌套引用：SKILL.md → A.md → B.md | +| 超过 100 行的文件加目录 | 无导航的长文件 | + +## 反模式 + +| 反模式 | 修复 | +| ------ | ---- | +| 一开始就给太多选项 | 一个默认值 + 边缘情况的逃生舱 | +| 深层引用嵌套（A→B→C） | 引用从 SKILL.md 只深一层 | +| 术语不一致 | 一个概念选一个词 | +| 模糊文件名 | 按内容命名，而非按序号 | +| 脚本通过正则分类含义 | 智能属于提示词，不属于脚本 | +| 过度优化扁平化个性 | 保留捕捉意图声音的措辞 | +| 子智能体不可用时硬失败 | 始终包含顺序回退路径 | diff --git a/docs/zh-cn/explanation/subagent-patterns.md b/docs/zh-cn/explanation/subagent-patterns.md new file mode 100644 index 0000000..c5bb003 --- /dev/null +++ b/docs/zh-cn/explanation/subagent-patterns.md @@ -0,0 +1,153 @@ +--- +title: '子智能体编排模式' +description: 六种高效使用子智能体的模式，从简单数据委派到角色驱动并行推理再到演化系统 +--- + +子智能体是父技能生成的隔离 LLM 实例，用于处理特定任务。每个子智能体拥有自己的上下文窗口，接收指令并返回结果。善用它们，可以保持父上下文精简，同时实现大规模并行工作。 + +所有模式共享一个原则：**文件系统是唯一真相源**。父上下文保持极小（文件指针 + 高层计划）。子智能体是无状态黑盒：指令输入、响应输出、隔离上下文。 + +## 基础：文件系统黑板 + +下面每个模式都建立在此基础设施上。文件系统充当共享数据库，让父上下文永不膨胀。 + +``` +/output/ +├── status.json ← 任务状态、完成标志 +├── knowledge.md ← 累积发现（仅追加） +└── task-queue.json ← 待处理工作项 + +/tasks/{id}/ +├── input.md ← 此子智能体的指令 +└── output/ + ├── result.json ← 结构化输出（严格 schema） + └── summary.md ← 紧凑摘要（≤200 token） + +/artifacts/ ← 最终交付物 +``` + +一种技巧是让每个子智能体提示词以相同方式结尾：_"你是无状态的。仅读取列出的文件。仅写入 result.json + summary.md。不要回显数据。"_ + +## 模式 1：委派数据访问 + +最简单的模式。子智能体读取来源并仅返回提炼摘要。父智能体从不接触原始数据。 + +| 方面 | 详情 | +| ---- | ---- | +| **工作方式** | 父智能体并行生成读取器；每个读取器读取一个来源并返回紧凑摘要；父智能体仅从摘要综合 | +| **关键规则** | 父智能体必须在接触任何源材料_之前_委派。如果先读了，token 已经花了 | +| **何时使用** | 5+ 文档、Web 研究、大型代码库探索 | +| **不值得用于** | 1-2 个文件，开销超过节省 | +| **Token 节省** | ~99%。5 个 15K token 的文档 = 75K 原始 vs 摘要中的 ~350 token | + +## 模式 2：临时文件组装 + +用于跨多个来源的大规模操作。子智能体将结果写入临时文件。独立的组装子智能体将它们合并为连贯交付物。 + +| 方面 | 详情 | +| ---- | ---- | +| **工作方式** | 父生成 N 个工作子智能体写入 `tmp/{n}.md`；全部完成后，生成一个组装子智能体读取所有临时文件并创建最终制品 | +| **何时使用** | 摘要仍然太大无法内联返回，或组装需要拥有全新上下文的专用智能体 | +| **示例** | BMad 质量优化器使用此模式：5 个并行扫描子智能体写入临时 JSON，然后报告创建子智能体综合它们 | + +## 模式 3：共享文件编排 + +多个子智能体通过共享文件通信，在彼此工作基础上构建。父智能体控制轮次顺序。 + +| 方面 | 详情 | +| ---- | ---- | +| **工作方式** | 智能体 A 写入 `shared.md`；智能体 B 读取并添加；智能体 A 可恢复继续；共享文件增量增长 | +| **变体** | 共享文件（多个智能体读写公共文件）或会话恢复（唤醒前一个子智能体，带完整上下文继续） | +| **何时使用** | 流水线阶段，后续工作依赖前面的工作，但每个智能体的上下文保持精简 | + +## 模式 4：层级领导-工作者 + +领导子智能体分析任务一次并写出分解方案。父从该方案生成工作者。中层子编排器可处理复杂子任务。 + +| 方面 | 详情 | +| ---- | ---- | +| **工作方式** | 领导智能体写出 `plan.json` 含任务分解；父读取方案并并行生成工作者；复杂子任务获得自己的子编排器 | +| **何时使用** | 需要分析后才能分解的任务，或父无法预先预测工作结构 | +| **变体** | 主-克隆：生成几乎相同的智能体，微调角色以探索同一问题的不同分支 | + +## 模式 5：角色驱动并行推理 + +质量方面最强大的模式。并行生成多样化专家，从隔离上下文产出真正独立的思考。 + +| 方面 | 详情 | +| ---- | ---- | +| **工作方式** | 父生成 3-6 个具有不同角色的智能体（架构师、红队、实用主义者、创新者）；各自独立写出发现；评估子智能体评分并合并最佳元素 | +| **何时使用** | 设计决策、代码审查、策略等任何多样视角能提升质量的任务 | +| **关键** | 重度角色注入产出真正不同的输出，而非同一分析的改述 | + +**有用的多样性包：** + +| 角色 | 视角 | +| ---- | ---- | +| **架构师** | 规模和优雅高于一切 | +| **红队** | 打破它。什么会失败？ | +| **实用主义者** | 周五上线。最小方案是什么？ | +| **创新者** | 如果我们用完全不同的方式呢？ | +| **用户代言人** | 最终用户实际体验如何？ | +| **未来的自己** | 5 年后回头看，你会改什么？ | + +**子模式：** + +| 子模式 | 工作方式 | +| ------ | -------- | +| **多路径探索** | 同一任务，不同角色。各自写入 `/explorations/path_N/`。父修剪或合并最佳路径 | +| **辩论与批评** | 第 1 轮：并行提案。第 2 轮：批评者攻击提案。第 3 轮：细化 | +| **集成投票** | 同一子任务 K 次，角色变化。评估者评分。加权合并优胜者 | + +## 模式 6：演化与涌现系统 + +这些将无状态子智能体变成感觉像是活的东西。全部建立在文件系统黑板上。 + +| 变体 | 工作方式 | 最适合 | +| ---- | -------- | ------ | +| **演化优化** | 生成 8-20 个智能体作为一"代"；评估者评分；"繁殖者"从优胜者创建下一代指令；运行 5-10 代 | 优化算法、UI 设计、策略 | +| **利益相关者模拟** | 智能体是角色（客户、竞争对手、监管者），轮流在共享"世界状态"文件上行动 | 产品策略、风险分析 | +| **群体智能** | 数十个轻量智能体探索解空间，沉积"信息素"评分；后续智能体偏向高分路径 | 最小规划的广泛覆盖 | +| **递归元改进** | "演化者"智能体分析过往日志并提出改进的系统提示词、新角色或更好的编排启发式 | 跨会话的系统自我改进 | + +## 最常见错误：父先读 + +使用子智能体模式时最重要的一点是**防止父智能体读取它正在委派的数据**。如果父在生成子智能体之前读取了所有文件，整个模式就被打败了。你已经花了 token，膨胀了上下文，失去了隔离收益。 + +这经常发生。你写了一个技能，应该生成子智能体各自读取一个文档并返回发现。你运行它。父智能体热心地先读了每个文档，然后传给子智能体，再收集提炼摘要。子智能体仍提供全新视角，但上下文节省（模式的主要原因）没了。 + +**修复方法是在技能中使用防御性语言。** 明确告诉父智能体它应该做什么和不应该做什么。具体但不冗长。 + +:::note[BMad 质量优化器的示例] +优化器的指令说：**"不要自己读取目标技能的文件。"** 然后准确告诉父应该做什么：运行脚本（返回结构化 JSON）、生成子智能体（它们做读取），并从它们的输出综合。父从不接触原始文件。 +::: + +**做到这一点的实用技巧：** + +| 技巧 | 示例语言 | +| ---- | -------- | +| **告诉父发现什么，而非读什么** | "列出 `resources/` 中的所有文件名以确定生成多少子智能体。不要读取其内容" | +| **告诉子智能体返回什么** | "仅返回与 [主题] 相关的发现。以 JSON 输出到 `{output-path}`。不要回显原始内容" | +| **使用预扫脚本** | 运行轻量脚本提取元数据（文件名、大小、结构），让父可以规划而不读取 | +| **明确边界** | "你的角色是编排。脚本和子智能体做所有分析" | + +**测试并观察实际发生了什么。** 如果父读取了它应该委派的文件，收紧语言。这是正常迭代。构建器已针对这些模式调优，但不同模型和工具可能需要更明确的指导。审查 BMad 质量优化器提示词（`prompts/quality-optimizer.md`）和扫描智能体（`agents/quality-scan-*.md`）获取防御性语言的工作示例。 + +## 选择模式 + +| 需求 | 模式 | +| ---- | ---- | +| 读取多个来源不膨胀上下文 | 1：委派数据访问 | +| 将多个输出合并为一个交付物 | 2：临时文件组装 | +| 阶段间有依赖的流水线 | 3：共享文件编排 | +| 任务需要分析后才能分解 | 4：层级领导-工作者 | +| 通过多样视角提升质量 | 5：角色驱动并行推理 | +| 迭代优化或模拟 | 6：演化与涌现 | + +## 实现注意事项 + +- 对每个子智能体输出强制**严格 JSON schema**以确保可靠的父解析 +- 使用 **git worktree** 或按智能体目录防止串扰 +- 从小处开始：一个编排器读取 `plan.md` 并生成第一波 +- 模式可组合：用委派访问收集数据，角色驱动做分析，临时文件组装做最终报告 +- 始终包含**优雅降级**。如果子智能体不可用，主智能体顺序执行工作 diff --git a/docs/zh-cn/explanation/what-are-bmad-agents.md b/docs/zh-cn/explanation/what-are-bmad-agents.md new file mode 100644 index 0000000..53ea680 --- /dev/null +++ b/docs/zh-cn/explanation/what-are-bmad-agents.md @@ -0,0 +1,92 @@ +--- +title: '什么是 BMad 智能体？' +description: 智能体与工作流的区别、三种智能体类型及何时构建每种类型 +--- + +BMad 智能体是将**角色**、**能力**和可选的**持久记忆**组合成对话伙伴的 AI 技能。从聚焦的无状态专家到跨会话记住你的演进式伙伴，覆盖各种场景。 + +## 什么让智能体成为智能体 + +智能体是具备三个额外特征的技能文件，工作流不具备这些特征。 + +| 特征 | 含义 | +| ---- | ---- | +| **角色** | 定义的身份与语调（架构师、教练、游戏大师、缪斯），塑造智能体的沟通方式 | +| **能力** | 智能体可执行的动作：内部提示词命令、脚本或调用外部技能 | +| **记忆** | 可选的持久存储，保存智能体对你、你的偏好和过往交互的认知 | + +三者结合，将交互转变为与了解你上下文的专家的对话。 + +## 三种智能体类型 + +智能体存在于一个光谱上。构建器通过自然对话检测适合的类型。 + +| 类型 | 记忆 | 初醒 | 自主 | 适用场景 | +| ---- | ---- | ---- | ---- | -------- | +| **无状态** | 否 | 否 | 否 | 独立会话、聚焦专家（代码格式化器、图表生成器、会议总结器） | +| **记忆型** | 是 | 是 | 否 | 持续关系，记忆能增加价值（代码教练、写作搭档、领域顾问） | +| **自主型** | 是 | 是 | 是 | 会话间主动创造价值（创意孵化、项目监控、内容策展） | + +### 无状态智能体 + +所有内容都在一个 SKILL.md 及配套参考文件中。没有记忆目录，没有初始化仪式。智能体具备角色和能力，但每次会话都视为独立的。当历史会话上下文不会改变智能体行为时，选择此类型。 + +### 记忆型智能体 + +一个精简的引导 SKILL.md（约 30 行）指向一个**圣殿**：一组持久化文件，智能体在每次启动时读取以重新成为自己。圣殿保存智能体的身份、价值观、对主人的理解、策展知识和能力注册表。首次启动时，**初醒**对话让智能体发现你是谁并校准自身。 + +记忆型智能体将每次会话视为重生。它们不假装连续性；而是读取圣殿文件并重新成为自己。如果不记得某件事，就直说并查阅文件。 + +### 自主型智能体 + +记忆型智能体的一切，加上一个定义智能体在无人时行为的 PULSE 文件。自主型智能体可按计划唤醒（cron、后台任务），执行维护工作 —— 从策展记忆到检查项目到执行领域特定任务。有人在场时进行对话。无头模式下独立工作并退出。 + +## 能力：内部、外部与脚本 + +| 类型 | 描述 | 示例 | +| ---- | ---- | ---- | +| **内部命令** | 定义在智能体技能文件内的提示词驱动动作 | 梦境智能体的"梦境捕捉"命令 | +| **外部技能** | 智能体可调用的独立技能或工作流 | 通过 PM 智能体调用 `create-prd` 工作流 | +| **脚本** | 从 LLM 中卸载的确定性操作 | 验证、数据处理、文件操作 | + +你在设计智能体时选择组合方式。内部命令保持一切自包含。外部技能让你从共享构建模块组合智能体，脚本处理确定性比判断更重要的操作。 + +### 可演进能力 + +记忆型智能体可选择支持**可演进能力**。启用后，智能体获得能力编写参考文件和能力注册表中的"已学习"区域。用户可以教智能体新的基于提示词、脚本或多文件的能力，随时间吸收到技能库中。 + +## 记忆如何工作 + +记忆型智能体将持久状态存储在 `_bmad/memory//` 的**圣殿**中。圣殿包含六个在每次会话时加载的核心文件： + +| 文件 | 用途 | +| ---- | ---- | +| **PERSONA.md** | 身份、沟通风格、性格特征、演进日志 | +| **CREED.md** | 使命、价值观、常备指令、哲学、边界 | +| **BOND.md** | 对主人的理解、偏好、需要记住/避免的事项 | +| **MEMORY.md** | 策展的长期知识（保持在 200 行以内） | +| **CAPABILITIES.md** | 内置 + 已学习能力注册表 | +| **INDEX.md** | 圣殿结构地图（每次重生时最先加载） | + +:::tip[记忆存储在技能外部] +智能体记忆存储在你的项目中，而不是技能文件夹内。这防止智能体修改自己的指令，并使数据可移植。同一个智能体可以在不同项目中使用，每个项目生成自己的记忆空间。 +::: + +圣殿架构、初醒、PULSE 和双层记忆系统详见 **[智能体记忆与个性化](../agent-memory-and-personalization.md)**。 + +## 何时构建智能体 vs 工作流 + +| 选择智能体 | 选择工作流 | +| ---------- | ---------- | +| 用户会反复使用它 | 流程运行一次并产出结果 | +| 跨会话记忆能增加价值 | 无状态执行即可 | +| 鲜明的角色能改善交互 | 个性次于完成任务 | +| 技能涵盖多个松散关联的能力 | 所有步骤服务于一个聚焦目标 | + +如果不确定，先从工作流开始。之后随时可以将它包装进智能体。 + +## 构建智能体 + +**BMad Agent Builder**（`bmad-agent-builder`）运行六个阶段的对话式发现。第一阶段通过自然提问检测适合的智能体类型，后续阶段根据你创建的是无状态专家、记忆型伙伴还是自主型智能体进行适配。 + +参见 [构建器命令参考](../../reference/builder-commands.md) 了解构建流程各阶段与能力的详情。 diff --git a/docs/zh-cn/explanation/what-are-modules.md b/docs/zh-cn/explanation/what-are-modules.md new file mode 100644 index 0000000..51502e9 --- /dev/null +++ b/docs/zh-cn/explanation/what-are-modules.md @@ -0,0 +1,117 @@ +--- +title: '什么是 BMad 模块？' +description: 智能体和工作流如何组合为可安装、可配置的 BMad 生态模块 +--- + +BMad 模块将智能体和工作流打包为可安装的单元，具备共享配置和帮助系统注册。模块可以是一组相关技能的完整套件，也可以是一个希望可被发现和配置的独立技能。 + +## 分发：插件与市场 + +在分发层面，BMad 模块是一个**插件**：一组带有 `.claude-plugin/` 清单的技能包。具体结构取决于你要发布的内容： + +| 结构 | 何时使用 | 清单 | +| ---- | -------- | ---- | +| **单插件** | 一个模块（独立或多技能） | `.claude-plugin/marketplace.json` 包含一个插件条目 | +| **市场** | 一个仓库发布多个模块 | `.claude-plugin/marketplace.json` 包含多个插件条目 | + +`.claude-plugin/` 约定源自 Claude Code，但该格式适用于多个技能平台。BMad 安装器支持从任何 Git 托管平台（GitHub、GitLab、Bitbucket、自托管）或本地路径安装自定义模块。详见 [BMad Method 安装指南](https://docs.bmad-method.org/zh-cn/how-to/install-custom-modules/)。 + +Module Builder 在 Create Module（CM）步骤中生成适当的 `marketplace.json` —— 但你需要验证它是否正确列出了你要交付的技能的相对路径。 + +这也意味着你可以在自己的模块中包含远程 URL 技能来进行组合。 + +## 模块包含什么 + +| 组件 | 多技能模块 | 独立模块 | +| ---- | ---------- | -------- | +| **技能** | 两个或更多智能体/工作流 | 一个智能体或工作流 | +| **注册** | 专用 `{code}-setup` 技能 | 内置于技能本身（`assets/module-setup.md`） | +| **module.yaml** | 在 setup 技能的 `assets/` 中 | 在技能自身的 `assets/` 中 | +| **module-help.csv** | 在 setup 技能的 `assets/` 中 | 在技能自身的 `assets/` 中 | +| **分发** | 包含多个技能文件夹的插件 | 包含单个技能文件夹的插件 + `marketplace.json` | + +对于多技能模块，setup 技能是粘合剂；它一步完成所有能力的注册。对于独立模块，技能在首次运行或用户传入 `setup`/`configure` 时自行注册。 + +## 智能体 vs 工作流 vs 两者兼有 + +规划模块时的第一个架构决策是使用单个智能体、多个工作流还是组合。 + +| 架构 | 何时适用 | 权衡 | +| ---- | -------- | ---- | +| **单智能体+多能力** | 所有能力服务于同一用户旅程且受益于共享上下文 | 更易维护、更好的记忆连续性、无缝 UX。能力不相关时可能显得臃肿 | +| **多工作流** | 能力服务于不同用户旅程或需要不同工具 | 每个工作流聚焦且可组合。用户显式切换技能 | +| **混合** | 部分能力需要持久角色/记忆，其他是程序性的 | 两全其美，但需要构建和维护更多技能 | + +:::tip[智能体优先思维] +很多用户默认构建多个单一用途智能体。考虑一下，一个具备丰富内部能力和路由的单智能体是否能更好地服务用户。单个智能体积累上下文、维持跨交互记忆，提供更流畅的体验。 +::: + +## 多智能体模块与记忆 + +具有多个智能体的模块引入了记忆架构决策。BMad 智能体存在于从无状态（无记忆）到记忆型（个人圣殿）再到自主型（圣殿 + PULSE）的光谱上。在多智能体模块中，你需要为每个技能选择智能体类型，并决定智能体是否应在模块内共享记忆。 + +| 模式 | 何时适用 | +| ---- | -------- | +| **仅个人记忆** | 智能体具有不同领域，重叠最小 | +| **个人 + 共享模块记忆** | 智能体有自己的上下文，但也学习关于用户或项目的共享内容 | +| **仅共享记忆** | 所有智能体服务于同一领域；考虑单智能体是否是更好的设计 | +| **混合类型** | 部分智能体需要记忆（教练、伙伴），其他无状态（格式化器、验证器） | + +**示例：** 一个社交创意模块，包含播客专家、短视频专家和博客专家。每个记忆型智能体维护自己的圣殿，记录与用户的合作内容（节目主题、视频格式、博客主题）。但它们也都向模块级记忆文件夹贡献，捕捉用户的沟通风格、常用口头禅、内容偏好和品牌调性。 + +每个智能体应仍然是自包含的，拥有自己的能力，即使这意味着复制一些通用功能。一个能独立处理完整会话、不需要博客专家的播客专家，优于一个依赖共享状态才能运作的专家。 + +参见 **[什么是 BMad 智能体](../what-are-bmad-agents.md)** 了解三种智能体类型，**[智能体记忆与个性化](../agent-memory-and-personalization.md)** 了解圣殿架构的工作原理。 + +## 独立模块 vs 扩展模块 + +| 类型 | 描述 | +| ---- | ---- | +| **独立** | 提供完整、独立的价值。不依赖其他模块 | +| **扩展** | 为现有模块扩展新能力。即使父模块未安装也应提供功能 | + +扩展模块可在帮助 CSV 排序中引用父模块的能力（before/after 字段）。这让新能力能嵌入父模块的自然工作流序列。 + +即使是扩展模块也应设计为可独立工作。父模块缺失时应优雅降级，而非导致扩展崩溃。 + +## 配置与注册 + +模块通过 `{project-root}/_bmad/` 中的三个文件注册到项目： + +| 文件 | 用途 | +| ---- | ---- | +| `config.yaml` | 提交到 git 的共享设置，模块区域按模块代码索引 | +| `config.user.yaml` | 个人设置（gitignored），用户名、语言偏好 | +| `module-help.csv` | 能力注册表，每行一个用户可发现的动作 | + +注册使模块对 `bmad-help` 可见。没有注册，帮助系统无法发现、推荐或追踪模块能力的完成情况。 + +并非每个模块都需要配置。如果技能使用合理默认值即可工作，注册可以纯粹聚焦于帮助条目。详见 **[模块配置](../module-configuration.md)**。 + +## 外部依赖 + +某些模块依赖 BMad 生态之外的工具。 + +| 依赖类型 | 示例 | +| -------- | ---- | +| **CLI 工具** | `docker`、`terraform`、`ffmpeg` | +| **MCP 服务器** | 自定义或第三方 Model Context Protocol 服务器 | +| **Web 服务** | 需要凭证或配置的 API | + +当模块有外部依赖时，setup 技能应检查其是否存在，并引导用户完成安装或配置。 + +## UI 与可视化 + +模块可以包含用户界面：仪表板、进度视图、交互式可视化，甚至完整的 Web 应用。UI 技能可以展示模块各能力的共享进度、提供技能关系的可视化地图，或提供交互式导航。 + +并非每个模块都需要 UI。但对于能力众多的复杂模块，可视化层让体验更加友好。 + +## 构建模块 + +Module Builder（`bmad-module-builder`）为模块生命周期提供三项能力： + +1. **Ideate Module（IM）**：通过创意引导进行头脑风暴和规划 +2. **Create Module（CM）**：将技能打包为可安装模块。检测你有一组技能（生成 setup 技能）还是单个技能（直接嵌入自注册） +3. **Validate Module（VM）**：验证多技能和独立模块的结构完整性与条目质量 + +参见 **[构建器命令参考](../../reference/builder-commands.md)** 了解每项能力的详细文档。 diff --git a/docs/zh-cn/explanation/what-are-skills.md b/docs/zh-cn/explanation/what-are-skills.md new file mode 100644 index 0000000..ba533bb --- /dev/null +++ b/docs/zh-cn/explanation/what-are-skills.md @@ -0,0 +1,25 @@ +--- +title: '什么是技能？' +description: BMad 生态中智能体、工作流和工具底层的通用构建单元 +--- + +技能（Skill）是 BMad Builder 所有产出物的通用打包格式。智能体是技能，工作流是技能，简单工具也是技能。该格式遵循 [Agent Skills 开放标准](https://agentskills.io/home)。 + +## BMad 中的技能 + +BMad Builder 生产的技能符合开放标准，并在此基础上增加了一些 BMad 特有约定。 + +| 组件 | 用途 | +| ---- | ---- | +| **SKILL.md** | 技能的指令：角色、能力与行为规则 | +| **resources/** | 参考数据、模板与指导文档 | +| **scripts/** | 确定性验证与分析脚本 | +| **templates/** | 用于生成输出的构建模块 | + +并非每个技能都需要以上所有组件。一个简单工具可能只有一个 `SKILL.md`。复杂工作流或智能体可能使用完整结构。 + +## 构建即可用 + +构建器输出一个完整的技能文件夹。将它放到你 AI 工具的 skills 目录（`.claude/skills`、`.codex/skills`、`.agent/skills` 或工具指定的位置）即可立即使用。 + +参见 [什么是智能体](../what-are-bmad-agents.md) 和 [什么是工作流](../what-are-workflows.md) 了解智能体和工作流各自如何使用这个基础。 diff --git a/docs/zh-cn/explanation/what-are-workflows.md b/docs/zh-cn/explanation/what-are-workflows.md new file mode 100644 index 0000000..415b0f5 --- /dev/null +++ b/docs/zh-cn/explanation/what-are-workflows.md @@ -0,0 +1,69 @@ +--- +title: '什么是 BMad 工作流？' +description: 工作流如何引导用户完成结构化流程、与智能体和简单技能的区别，以及何时构建工作流 +--- + +BMad 工作流是引导用户通过**结构化流程**产出特定成果的技能。它们承担了 BMad 生态中的大部分工作 —— 聚焦、可组合、通常无状态。 + +## 什么让工作流成为工作流 + +和智能体一样，工作流本质上也是技能文件。区别在于侧重点：工作流优先**达成结果**，而非维持持久身份。 + +| 特征 | 工作流 | 智能体 | +| ---- | ------ | ------ | +| **目标** | 完成定义的流程并产出制品 | 作为持续的对话伙伴 | +| **角色** | 最小化，足以促进良好对话 | 体验的核心 | +| **记忆** | 通常跨会话无状态 | 持久智能体记忆 | +| **范围** | 所有步骤服务于一个目标 | 可涵盖松散关联的能力 | + +## 工作流类型 + +BMad Builder 根据复杂度将工作流分为三个层级。 + +| 类型 | 描述 | 示例 | +| ---- | ---- | ---- | +| **简单工具** | 做好一件事的单一用途工具 | 验证 schema、转换文件格式 | +| **简单工作流** | 几个顺序步骤的短引导流程 | 创建快速技术规范 | +| **复杂工作流** | 具有分支路径、渐进式展开和多输出的多阶段流程 | 创建和管理 PRD（覆盖创建、编辑、验证、转换、润色） | + +:::tip[从简单开始] +大多数想法起初是简单工具或简单工作流。只有当你确实需要分支路径或在一个技能中执行多个相关操作时，才升级为复杂工作流。 +::: + +## 渐进式展开 + +复杂工作流使用**渐进式展开**在单个技能内处理多个操作。与其构建五个独立技能分别处理创建、编辑、验证、转换和润色，不如构建一个工作流，检测用户意图（通过对话方式或传入的参数）并在内部路由到正确路径。 + +这与 BMad 自身的多能力智能体和工作流使用的模式相同。用户体验保持简单，技能在幕后处理路由。 + +## YOLO 模式与引导模式 + +Agent Builder 和 Workflow Builder 在创建技能时都支持两种交互风格。 + +| 模式 | 工作方式 | 最适合 | +| ---- | -------- | ------ | +| **YOLO** | 你一股脑倒出想法；构建器猜测并生成成品，只在真正卡住时才提问 | 快速原型、有经验的构建者 | +| **引导** | 构建器引导你逐步做决策，澄清模糊点，确保无遗漏 | 生产级工作流、首次构建者 | + +引导模式不再是早期 BMad 版本中缓慢的多步流程。它是对话式和自适应的，但对复杂工作流的产出质量显著优于 YOLO。 + +## 无头（自主）模式 + +和智能体一样，工作流可以支持**无头模式**。通过调度器、编排器或另一个技能无头调用时，工作流跳过交互提示，端到端完成流程，无需等待用户输入。 + +## 何时构建工作流 vs 智能体 + +| 选择工作流 | 选择智能体 | +| ---------- | ---------- | +| 流程有明确的开始和结束 | 用户会跨会话反复使用 | +| 无需记住过往交互 | 记忆上下文能增加价值 | +| 所有步骤服务于一个目标 | 能力之间松散关联 | +| 你需要一个可组合的构建模块 | 你需要一个持久的对话伙伴 | + +工作流也非常适合作为智能体的**内部能力**。先构建工作流，如果需要在其上增加角色和记忆，再将其包装进智能体。 + +## 构建工作流 + +**BMad Workflow Builder**（`bmad-workflow-builder`）使用与 Agent Builder 相同的六阶段对话式发现（意图、分类、需求、起草、构建、质量优化），生成可直接使用的技能文件夹。 + +参见 [构建器命令参考](../../reference/builder-commands.md) 了解构建流程各阶段与能力的详情。 diff --git a/docs/zh-cn/how-to/distribute-your-module.md b/docs/zh-cn/how-to/distribute-your-module.md new file mode 100644 index 0000000..b4de27f --- /dev/null +++ b/docs/zh-cn/how-to/distribute-your-module.md @@ -0,0 +1,215 @@ +--- +title: '分发你的模块' +description: 配置 Git 仓库分享你的 BMad 模块，让任何人都能一条命令安装 +--- + +本指南介绍如何将 BMad 模块发布到 Git 仓库，并通过 `.claude-plugin/marketplace.json` 清单让任何人都能一条命令安装。 + +## 何时使用 + +- 你有一个准备公开或在组织内分享的模块 +- 他人应能通过 BMad 安装器安装它 +- 仓库可托管一个或多个模块 + +## 何时跳过 + +- 模块仅供个人在单一项目中使用。保留技能在项目中即可。 +- 模块尚不稳定。稳定后再分发。 + +:::note[前置条件] + +- 一个已完成并验证的 BMad 模块（参见 **[构建你的第一个模块](../../tutorials/build-your-first-module.md)**） +- 任何 Git 托管平台上的仓库（GitHub、GitLab、Bitbucket 或自托管） +- 本地已安装 Git +::: + +:::tip[快速路径] +从 [BMad Module Template](https://github.com/bmad-code-org/bmad-module-template) 开始。在 GitHub 上点击 **Use this template**，将技能添加到 `skills/` 目录，更新 `marketplace.json`，然后推送。如果你已有包含技能的仓库，使用 Create Module（CM）直接搭建清单和注册文件。 +::: + +## 步骤 1：配置插件清单 + +模块通过仓库根目录的 `.claude-plugin/marketplace.json` 清单被发现。Create Module 为你生成此文件。发布前请验证并完善。 + +:::tip[安装器支持] +BMad Method 安装器（`npx bmad-method install`）支持从任何 Git 托管平台或本地路径安装自定义模块。用户可交互式安装或通过 `--custom-source ` 安装。详见 [BMad Method 安装指南](https://docs.bmad-method.org/zh-cn/how-to/install-custom-modules/)。 +::: + +此格式适用于任何支持技能的平台，不仅限于 Claude。我们使用 claude 文件作为约定以支持任何基于技能的平台。 + +单模块的最小清单： + +```json +{ + "name": "my-module", + "owner": { "name": "Your Name" }, + "license": "MIT", + "homepage": "https://github.com/your-github/my-module", + "repository": "https://github.com/your-github/my-module", + "keywords": ["bmad", "your-domain"], + "plugins": [ + { + "name": "my-module", + "source": "./", + "description": "What your module does in one sentence.", + "version": "1.0.0", + "author": { "name": "Your Name" }, + "skills": [ + "./skills/my-agent", + "./skills/my-workflow" + ] + } + ] +} +``` + +| 字段 | 用途 | +| ---- | ---- | +| **name** | 包标识符，小写加连字符 | +| **plugins[].source** | 从仓库根到模块技能文件夹父目录的路径 | +| **plugins[].skills** | 每个技能目录的相对路径数组 | +| **plugins[].version** | 语义版本；每次发布时递增 | + +对于发布多个模块的仓库，在 `plugins` 数组中为每个模块添加条目，指向各自的技能目录。 + +## 步骤 2：组织仓库结构 + +组织仓库使技能可相对于 `marketplace.json` 被定位。 + +### 单模块仓库 + +``` +my-module/ +├── .claude-plugin/ +│ └── marketplace.json +├── skills/ +│ ├── my-agent/ +│ │ ├── SKILL.md +│ │ ├── prompts/ +│ │ └── scripts/ +│ ├── my-workflow/ +│ │ ├── SKILL.md +│ │ └── prompts/ +│ └── mymod-setup/ # 由 Create Module（CM）生成 +│ ├── SKILL.md +│ ├── assets/ +│ │ ├── module.yaml +│ │ └── module-help.csv +│ └── scripts/ +│ ├── merge-config.py +│ ├── merge-help-csv.py +│ └── cleanup-legacy.py +├── README.md +└── LICENSE +``` + +### 独立单技能模块 + +``` +my-skill/ +├── .claude-plugin/ +│ └── marketplace.json +├── skills/ +│ └── my-skill/ +│ ├── SKILL.md +│ ├── assets/ +│ │ ├── module-setup.md +│ │ ├── module.yaml +│ │ └── module-help.csv +│ ├── references/ +│ └── scripts/ +│ ├── merge-config.py +│ └── merge-help-csv.py +├── README.md +└── LICENSE +``` + +### 多模块市场仓库 + +``` +my-marketplace/ +├── .claude-plugin/ +│ └── marketplace.json # plugins[] 中包含多个条目 +├── skills/ +│ ├── module-a/ +│ │ ├── skill-one/ +│ │ ├── skill-two/ +│ │ └── moda-setup/ +│ └── module-b/ +│ └── standalone-skill/ +├── README.md +└── LICENSE +``` + +:::caution[技能路径必须匹配] +`marketplace.json` 中的 `skills` 数组必须与相对于仓库根的实际目录路径匹配。如果你重组了文件夹，请更新清单。 +::: + +## 步骤 3：验证清单 + +发布前确认清单准确。 + +### 检查技能路径 + +`skills` 数组中的每个路径必须指向包含 `SKILL.md` 文件的目录。 + +### 检查模块注册文件 + +多技能模块需要 setup 技能中的 `assets/module.yaml` 和 `assets/module-help.csv`。独立模块将这些文件保存在技能自身的 `assets/` 文件夹中。 + +### 运行 Validate Module + +``` +"Validate my module at ./skills" +``` + +Validate Module（VM）检查缺失文件、孤立条目和其他结构问题。修复标记的问题后再发布。 + +## 步骤 4：发布 + +将仓库推送到 Git 托管平台（GitHub、GitLab、Bitbucket 或自托管）。仓库可访问后，任何有权限的人都能安装。 + +### 安装你的模块 + +用户通过 BMad 安装器安装自定义模块： + +```bash +# 交互式：安装器提示输入自定义源 URL 或路径 +npx bmad-method install + +# 非交互式：直接指定源 +npx bmad-method install --custom-source https://github.com/your-org/my-module --tools claude-code --yes +``` + +安装器接受 HTTPS URL、SSH URL、带深层路径的 URL（如 `/tree/main/subdir`）和本地文件路径。 + +### 私有或组织模块 + +对于私有仓库，用户需要 Git 访问权限来克隆。安装器使用机器上配置的任何 Git 认证。 + +### 版本管理 + +用语义版本标记发布。安装默认从默认分支拉取，除非用户指定标签或分支。 + +## 你将获得 + +发布后，用户可以： + +- 通过 BMad 安装器从任何 Git URL 或本地路径安装 +- 运行 setup 技能注册到 `bmad-help` +- 通过帮助系统浏览模块能力 +- 获取 `module.yaml` 中定义的配置提示 + +## 步骤 5：在市场上架（可选） + +将模块提交到 [BMad Plugins Marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace)，与官方模块一起获得曝光。上架不是安装的必要条件，但能增加可发现性和审查后的信任层级徽章。 + +参见市场 [CONTRIBUTING.md](https://github.com/bmad-code-org/bmad-plugins-marketplace/blob/main/CONTRIBUTING.md) 了解提交流程。 + +## 建议 + +- 包含一个 `README.md`，说明模块功能、安装方式和外部依赖 +- 添加 `LICENSE` 文件。MIT 是开源 BMad 模块的常见选择 +- 保持 `marketplace.json` 版本与发布标签同步 +- 外部依赖（CLI 工具、MCP 服务器）应在 README 中记录，并由 setup 技能检测 +- 每次发布前运行 `Validate Module（VM）` 以捕获回归问题 diff --git a/docs/zh-cn/index.md b/docs/zh-cn/index.md new file mode 100644 index 0000000..399671e --- /dev/null +++ b/docs/zh-cn/index.md @@ -0,0 +1,99 @@ +--- +title: 欢迎 +description: BMad Builder —— 筑梦架构 +--- + +# BMad Builder —— BMad 方法生态模块 + +**筑梦架构（Build More, Architect Dreams）。** + +## 梦想 + +如果你的 AI 能记住一切呢？一个记录你每次 PR 的健身教练。一个比你更了解你笔下角色的写作搭档。一个已经熟悉你工作习惯的研究助手。 + +BMad Builder 让你创建： + +- **私人 AI 伙伴**：具备记忆、随时间成长的智能体 +- **领域专家**：覆盖法律、医疗、创意、技术等任何领域的专业智能体 +- **工作流自动化**：引导你完成复杂任务的结构化流程 +- **自定义模块**：将智能体和工作流打包成可分享的模块 + +## 差异化优势 + +| 特性 | 为什么重要 | +| ---- | ---------- | +| **持久记忆** | 智能体跨会话记忆，持续改进 | +| **可组合** | 你的作品与整个 BMad 生态无缝协作 | +| **技能标准兼容** | 基于开放标准，适配任何 AI 工具 | +| **可分享** | 打包并分发你的模块给 BMad 社区 | + +## 快速开始 + +### 1. 注册模块 + +首次使用时，运行 `bmad-bmb-setup` 在项目中注册 BMad Builder。它会收集你的偏好（姓名、语言、输出路径），并将构建器的能力注册到帮助系统，让 `bmad-help` 能够引导你。 + +:::tip[单技能模块] +如果你安装的模块只包含一个技能，该技能会在首次运行时自行注册，无需额外配置步骤。 +::: + +### 2. 开始构建 + +调用 **Agent Builder** 或 **Workflow Builder**，描述你想创建的内容。两者都会引导你回答一系列问题，最终生成一个可直接使用的技能文件夹。 + +| 目标 | 构建器 | 菜单代码 | +| ---- | ------ | -------- | +| 带记忆的 AI 伙伴 | Agent Builder | BA | +| 结构化流程/工具 | Workflow Builder | BW | +| 将技能打包为模块 | Module Builder | CM | + +### 3. 使用你的技能 + +构建器会生成一个完整的技能文件夹。将它复制到你 AI 工具的 skills 目录（`.claude/skills/`、`.codex/skills/`、`.agents/skills/` 或工具指定的位置）即可立即使用。 + +:::tip[自定义模块安装] +BMad Method 安装器支持从任何 Git 托管平台（GitHub、GitLab、Bitbucket、自托管）或本地路径安装自定义模块。详见 [BMad Method 安装指南](https://docs.bmad-method.org/zh-cn/how-to/install-custom-modules/)。 +::: + +:::tip[不需要打包成模块] +如果你只是为个人使用而构建，不需要打包成模块。直接复制技能文件夹即可。模块打包（包含 `bmad-help` 注册和配置）是为了分享或更丰富的可发现性。 +::: + +### 4. 了解更多 + +参见 [构建器命令参考](./reference/builder-commands.md) 了解所有能力、模式和阶段。 + +## 你能构建什么 + +| 领域 | 示例 | +| ---- | ---- | +| **个人** | 日记伙伴、习惯教练、学习导师、能记住你的友好个人伙伴 | +| **职业** | 代码审查员、文档专家、工作流自动化 | +| **创意** | 故事架构师、角色开发者、战役设计师 | +| **任意领域** | 任何你能描述为可重复流程的事物 | + +## 设计模式 + +用以下指南构建更好的技能，均来自真实的 BMad 开发经验。 + +| 指南 | 你将学到 | +| ---- | -------- | +| **[渐进式展开](./explanation/progressive-disclosure.md)** | 如何结构化技能，让它在每个时刻只加载所需上下文 | +| **[子智能体模式](./explanation/subagent-patterns.md)** | 六种并行与层级编排模式 | +| **[技能编写最佳实践](./explanation/skill-authoring-best-practices.md)** | 核心原则、质量维度与反模式 | + +## 文档 + +| 章节 | 用途 | +| ---- | ---- | +| **[构建你的第一个模块](./tutorials/build-your-first-module.md)** | 从规划、构建、脚手架到验证，完成一个完整模块 | +| **[分发你的模块](./how-to/distribute-your-module.md)** | 通过任何 Git 托管平台分享你的模块，让任何人都能安装 | +| **[概念](./explanation/)** | 智能体类型、记忆架构、工作流、技能及其关联 | +| **[设计模式](./explanation/#design-patterns)** | 渐进式展开、子智能体编排、编写最佳实践 | +| **[参考](./reference/)** | 构建器命令、工作流模式 | + +## 社区 + +- **[Discord](https://discord.gg/gk8jAdXWmj)**：获取帮助、分享你的成果 +- **[GitHub](https://github.com/bmad-code-org/bmad-builder)**：源代码 +- **[BMad 方法](https://docs.bmad-method.org/zh-cn/)**：核心框架 diff --git a/docs/zh-cn/reference/builder-commands.md b/docs/zh-cn/reference/builder-commands.md new file mode 100644 index 0000000..4bc8701 --- /dev/null +++ b/docs/zh-cn/reference/builder-commands.md @@ -0,0 +1,418 @@ +--- +title: '构建器命令参考' +description: Agent Builder、Workflow Builder 和 Module Builder 所有能力、模式和路径的完整参考 +--- + +三个核心 BMad Builder 技能的参考：Agent Builder（`bmad-agent-builder`）、Workflow Builder（`bmad-workflow-builder`）和 Module Builder（`bmad-module-builder`）。 + +## 能力概览 + +| 能力 | 菜单代码 | Agent Builder | Workflow Builder | +| ---- | -------- | ------------- | ---------------- | +| **Build Process** | BP | 构建、编辑、转换或修复智能体 | 构建、编辑、转换或修复工作流和工具 | +| **Quality Optimize** | QO | 验证和优化已有智能体 | 验证和优化已有工作流和工具 | +| **Convert** | CW | - | 将任何技能转换为 BMad 兼容的、成果驱动的等效版本，附带比较报告 | + +两项能力均支持通过 `--headless` / `-H` 标志的自主/无头模式。 + +## 技能命名 + +| 上下文 | 智能体模式 | 工作流模式 | +| ------ | ---------- | ---------- | +| **独立** | `agent-{name}` | `{name}` | +| **模块内** | `{modulecode}-agent-{name}` | `{modulecode}-{name}` | + +名称必须是 kebab-case 并与文件夹名匹配。智能体名称应包含 `agent`。模块内技能的模块代码前缀由用户在构建时选择。 + +:::caution[保留前缀] +`bmad-` 前缀保留给官方 BMad 作品。用户构建的技能不应包含它。如果转换已有 `bmad-` 前缀的技能，保留该前缀除非用户要求重命名。 +::: + +## Build Process（BP） + +核心创建路径。六个阶段的对话式发现带你从粗糙想法到完整、测试过的技能文件夹。 + +### 输入类型 + +两个构建器都接受以下任何一种作为起点。 + +| 输入 | 发生什么 | +| ---- | -------- | +| 粗糙想法或描述 | 从零开始引导发现 | +| 已有 BMad 技能路径 | 编辑模式。分析现有内容，确定要改什么 | +| 非 BMad 技能、工具或代码 | 转换为 BMad 兼容结构 | +| 文档、API 规范或代码 | 自动提取意图和需求 | + +### 交互模式 + +| 模式 | 行为 | 最适合 | +| ---- | ---- | ------ | +| **引导** | 构建器引导逐步决策、澄清模糊点、确保完整性 | 生产级技能、首次构建者 | +| **YOLO** | 一股脑倒出想法；构建器用最少提问猜测生成成品 | 快速原型、有经验的构建者 | +| **自主** | 完全无头；无交互提示，使用安全默认值 | CI/CD、批处理、编排构建 | + +### 构建阶段 + +| 阶段 | Agent Builder | Workflow Builder | +| ---- | ------------- | ---------------- | +| 1 | **发现意图**：理解愿景；通过自然提问检测智能体类型（无状态、记忆型或自主型） | **发现意图**：理解愿景；接受任何输入格式 | +| 2 | **能力策略**：内部命令、外部技能、脚本；可演进能力决策 | **分类技能类型**：简单工具、简单工作流或复杂工作流；模块归属 | +| 3 | **收集需求**：身份、角色记忆种子、初醒领域、PULSE 行为、文件夹管辖 | **收集需求**：名称、描述、阶段、配置变量、输出制品、依赖 | +| 4 | **起草与细化**：展示大纲，迭代直到就绪 | **起草与细化**：展示计划，澄清缺口，迭代直到就绪 | +| 5 | **构建**：按智能体类型生成技能结构，lint 门 | **构建**：生成技能结构，lint 门 | +| 6 | **总结**：展示结果，提供 Quality Optimize | **总结**：展示结果，如有脚本运行单元测试，提供 Quality Optimize | + +### Agent Builder：Phase 1 智能体类型检测 + +构建器通过自然提问确定智能体类型，而非菜单： + +| 问题（自然提出） | 如果否 | 如果是 | +| ---------------- | ------ | ------ | +| 此智能体需要跨会话记忆吗？ | 无状态 | 记忆型或自主型 | +| 用户应能教它新技能吗？ | 固定能力 | 可演进能力 | +| 它在会话之间自主运行吗？ | 记忆型 | 自主型 | + +对于记忆型和自主型智能体，构建器还确定**关系深度**：深度（校准式初醒，开放式发现）或聚焦（配置式初醒，引导式提问）。 + +### Agent Builder：Phase 2 能力策略 + +确定内部和外部能力的组合，以及脚本机会。 + +| 能力类型 | 描述 | +| -------- | ---- | +| **内部命令** | 提示词驱动的动作，各自在 `references/` 中有文件 | +| **外部技能** | 智能体按注册名调用的独立技能 | +| **脚本** | 从 LLM 卸载的确定性操作（验证、数据处理、文件操作） | +| **可演进能力** | 如启用：用户可通过编写参考随时间教智能体新能力 | + +### Agent Builder：Phase 3 需求 + +需求因智能体类型而异。无状态智能体需要身份和能力。记忆型和自主型智能体需要以下全部。 + +**所有智能体类型：** + +| 需求 | 描述 | +| ---- | ---- | +| **身份** | 此智能体是谁？沟通风格、决策哲学 | +| **能力** | 内部命令、外部技能、脚本 | +| **文件夹管辖** | 读边界、写边界、显式拒绝区域 | + +**记忆型和自主型智能体额外需要：** + +| 需求 | 描述 | +| ---- | ---- | +| **身份种子** | 2-3 句性格 DNA，写入 PERSONA.md | +| **物种级使命** | 领域特定的目标陈述，写入 CREED.md | +| **核心价值观** | 指导行为的 3-5 个价值观 | +| **常备指令** | 惊喜与取悦 + 自我改进，适配领域并附带示例 | +| **CREED 种子** | 哲学、边界、反模式（行为 + 操作） | +| **BOND 领域** | 关于主人需了解的领域特定方面 | +| **初醒领域** | 通用集之外的发现问题 | + +**自主型智能体额外需要：** + +| 需求 | 描述 | +| ---- | ---- | +| **PULSE 行为** | 默认唤醒行为、领域特定自主任务 | +| **命名任务路由** | 通过 `--headless {task-name}` 或 `-H {task-name}` 调用的任务 | +| **频率与安静时段** | 多久唤醒一次，何时不唤醒 | + +### Workflow Builder：Phase 2-3 详情 + +**技能类型分类**决定模板和结构。 + +| 类型 | 信号 | 结构 | +| ---- | ---- | ---- | +| **简单工具** | 可组合构建模块，清晰输入/输出，通常由脚本驱动 | 单 SKILL.md，scripts 文件夹 | +| **简单工作流** | 放在一个 SKILL.md 中，几个顺序步骤，可选自主 | SKILL.md 内联步骤，可选 prompts 和 resources | +| **复杂工作流** | 多阶段、分支提示词流、渐进式展开、长时运行 | SKILL.md 路由 + `prompts/` 阶段 + `resources/` | + +**Phase 3 收集的工作流特定需求：** + +| 需求 | 简单工具 | 简单工作流 | 复杂工作流 | +| ---- | -------- | ---------- | ---------- | +| **输入/输出格式** | 是 | - | - | +| **可组合性** | 是 | - | - | +| **步骤** | - | 编号步骤 | 命名阶段+推进条件 | +| **无头模式** | - | 可选 | 可选 | +| **配置变量** | - | 核心 + 自定义 | 核心 + 模块特定 | +| **模块排序** | 可选 | 可选 | 推荐 | + +### 构建输出 + +输出结构取决于智能体类型。 + +**无状态智能体：** + +``` +{skill-name}/ +├── SKILL.md # 完整身份 + 角色 + 能力 +├── references/ # 能力提示词 +├── agents/ # 子智能体定义（如需要） +├── scripts/ # 确定性脚本 +│ └── tests/ # 脚本单元测试 +└── assets/ # 模板（如需要） +``` + +**记忆型和自主型智能体：** + +``` +{skill-name}/ +├── SKILL.md # 精简引导器（约 30 行内容） +├── references/ +│ ├── first-breath.md # 初醒对话指南 +│ ├── memory-guidance.md # 会话关闭和策展实践 +│ ├── capability-authoring.md # 如启用可演进能力 +│ └── {capability}.md # 面向成果的能力提示词 +├── assets/ # 圣殿种子模板 +│ ├── INDEX-template.md +│ ├── PERSONA-template.md +│ ├── CREED-template.md +│ ├── BOND-template.md +│ ├── MEMORY-template.md +│ ├── CAPABILITIES-template.md +│ └── PULSE-template.md # 仅自主型智能体 +├── agents/ # 子智能体定义（如需要） +└── scripts/ + ├── init-sanctum.py # 创建圣殿文件夹、复制模板、生成 CAPABILITIES.md + └── tests/ +``` + +种子模板包含发现阶段的真实内容，而非占位符。初始化脚本以技能名、文件列表和可演进标志为参数。 + +**Workflow Builder** 输出无论智能体类型均保持不变： + +``` +{skill-name}/ +├── SKILL.md # 技能指令 +├── prompts/ # 复杂工作流的阶段提示词 +├── resources/ # 参考数据 +├── agents/ # 并行处理的子智能体定义 +├── scripts/ # 确定性脚本 +│ └── tests/ # 脚本单元测试 +└── templates/ # 生成输出的构建模块 +``` + +### Lint 门 + +完成构建前，两个构建器都运行确定性验证。 + +| 脚本 | 检查内容 | +| ---- | -------- | +| `scan-path-standards.py` | 路径约定：无 `{skill-root}`，项目范围用 `{project-root}`，技能内部用 `./`，无双前缀 | +| `scan-scripts.py` | 脚本可移植性、PEP 723 元数据、智能体设计、单元测试存在性 | + +关键问题阻止完成。警告记录但不阻止。 + +## Quality Optimize（QO） + +已有技能的验证和优化。并行运行确定性 lint 脚本进行即时结构检查和 LLM 扫描子智能体进行基于判断的分析。 + +### 预扫检查 + +在交互模式中，优化器： + +1. 检查未提交更改并建议先提交 +2. 询问技能当前是否按预期工作 + +在自主模式中，两项检查都跳过并在报告中记为警告。 + +### 扫描流水线 + +优化器运行三层分析。 + +**第 1 层：Lint 脚本**（确定性，零 token，即时）： + +| 脚本 | 焦点 | +| ---- | ---- | +| `scan-path-standards.py` | 路径约定违规 | +| `scan-scripts.py` | 脚本可移植性和标准 | + +**第 2 层：预扫脚本**（为 LLM 扫描器提取指标）： + +| 脚本 | Agent Builder | Workflow Builder | +| ---- | ------------- | ---------------- | +| 结构/完整性预扫 | `prepass-structure-capabilities.py` | `prepass-workflow-integrity.py` | +| 提示词指标预扫 | `prepass-prompt-metrics.py` | `prepass-prompt-metrics.py` | +| 执行依赖预扫 | `prepass-execution-deps.py` | `prepass-execution-deps.py` | + +**第 3 层：LLM 扫描器**（基于判断，作为并行子智能体运行）： + +| 扫描器 | Agent Builder 焦点 | Workflow Builder 焦点 | +| ------ | ------------------- | --------------------- | +| **结构/完整性** | 结构、能力、身份、记忆设置、一致性 | 逻辑一致性、描述质量、推进条件、类型适配结构 | +| **提示词技巧** | Token 效率、反模式、角色声音、概述质量 | Token 效率、反模式、概述质量、渐进式展开 | +| **执行效率** | 并行化、子智能体委派、记忆加载、上下文优化 | 并行化、子智能体委派、读取回避、上下文优化 | +| **内聚性** | 角色-能力对齐、缺口、冗余 | 阶段流连贯性、目标对齐、复杂度适当性 | +| **增强机会** | 脚本自动化、自主潜力、边缘情况、惊喜 | 创意边缘情况发现、体验缺口、假设审计 | + +### 报告综合 + +所有扫描器完成后，优化器将结果综合为统一报告，保存到 `{bmad_builder_reports}/{skill-name}/quality-scan/{timestamp}/`。 + +在交互模式中，展示严重级别计数的摘要并提供下一步选项： + +- 直接应用修复 +- 导出检查清单供手动修复 +- 讨论具体发现 + +在自主模式中，输出含严重级别计数和报告文件路径的结构化 JSON。 + +### 优化指导 + +并非每个建议都应采纳。优化器传达这些决策规则： + +- **保留措辞**，如果它捕捉了意图的声音。精简并不总是对角色驱动技能更好 +- **保留内容**，如果它为 AI 增加清晰度，即使人类觉得显而易见 +- **优先脚本化**确定性操作；**优先提示词**创意或判断任务 +- **拒绝更改**，如果它们扁平化个性，除非明确要求中性语调 + +## Convert（CW） + +一条命令将任何现有技能转换为 BMad 兼容的、成果驱动的等效版本。接受不合规技能（臃肿、结构差或不遵循 BMad 实践）并产出干净版本。与 Build Process 的编辑/重建模式不同，`--convert` 始终无头运行并产出可视化比较报告。 + +### 用法 + +``` +--convert [-H] +``` + +`--convert` 标志隐含无头模式。接受本地技能路径或 URL。 + +### 流程 + +| 步骤 | 发生什么 | +| ---- | -------- | +| **1. 捕获** | 获取或读取原始技能，保存副本用于比较 | +| **2. 重建** | 从意图完全无头重建：提取技能的成就，应用 BMad 成果驱动最佳实践 | +| **3. 报告** | 测量两个版本，分类变更内容和原因，生成交互式 HTML 比较报告 | + +### 比较报告 + +HTML 报告包含： + +| 区域 | 内容 | +| ---- | ---- | +| **横幅** | 整体 token 减少百分比 | +| **指标表** | 行数、词数、字符数、节数、文件数、估算 token，带可视化条形图 | +| **变更内容** | 分类差异（臃肿移除、结构重组、最佳实践对齐）附严重级别和示例 | +| **保留内容** | 证明其价值的内容：LLM 不被明确告知就无法正确遵循的指令 | +| **评语** | 转换的一句话总结 | + +报告保存到 `{bmad_builder_reports}/convert-{skill-name}/`。 + +### 何时使用 Convert vs Build Process + +| 场景 | 使用 | +| ---- | ---- | +| 你有任何非 BMad 兼容技能并想快速转换 | `--convert` | +| 你有臃肿技能并想要精简替换附比较报告 | `--convert` | +| 你想交互式讨论要改什么 | Build Process（编辑模式） | +| 你想从零重新思考技能，带完整发现 | Build Process（重建模式） | +| 你想要详细质量分析而不重建 | Quality Optimize | + +## Module Builder + +Module Builder（`bmad-module-builder`）处理模块级规划、脚手架和验证。它在比 Agent Builder 和 Workflow Builder 更高的层级运行；它将这些构建器产出的内容编排为连贯、可安装的模块。 + +### 能力概览 + +| 能力 | 菜单代码 | 作用 | +| ---- | -------- | ---- | +| **Ideate Module** | IM | 通过创意引导进行头脑风暴和规划模块 | +| **Create Module** | CM | 将技能打包为可安装模块：多技能用 setup 技能，独立用自注册 | +| **Validate Module** | VM | 检查多技能和独立模块的结构完整性与条目质量 | + +### Ideate Module（IM） + +帮助你从零规划模块的头脑风暴会话。构建器作为创意协作者，引出想法、探索可能性，并引导你找到正确的架构。 + +| 方面 | 详情 | +| ---- | ---- | +| **交互** | 仅交互式；无无头模式 | +| **输入** | 一个想法或粗糙描述 | +| **输出** | 计划文档保存到 `{bmad_builder_reports}` | + +**覆盖内容：** + +- 问题空间探索和创意头脑风暴 +- 架构决策：单智能体+能力 vs 多技能 vs 混合 +- 独立模块或现有模块的扩展 +- 外部依赖（CLI 工具、MCP 服务器） +- UI 和可视化机会 +- Setup 技能在配置之外的扩展 +- 每技能能力定义及帮助 CSV 元数据 +- 配置变量和合理默认值 + +计划文档使用带 YAML frontmatter 的可恢复模板，使长时头脑风暴会话能在上下文压缩后存活。 + +**构思之后：** 使用 Agent Builder（BA）或 Workflow Builder（BW）构建每个计划的技能，然后返回 Create Module（CM）搭建模块脚手架。 + +### Create Module（CM） + +将构建好的技能打包为可安装 BMad 模块。自动检测单技能 vs 多技能输入并推荐适当方式。支持 `--headless` / `-H`。 + +| 方面 | 详情 | +| ---- | ---- | +| **交互** | 引导式或无头 | +| **输入** | 技能文件夹或单技能路径（或 SKILL.md 文件），可选计划文档 | +| **输出** | 多技能模块的 setup 技能，或独立模块的自注册文件 | + +**执行内容：** + +1. 读取 SKILL.md 文件以理解每个技能 +2. 检测单技能 vs 多技能并与用户确认打包方式 +3. 收集模块身份（名称、代码、描述、版本、问候语） +4. 定义帮助 CSV 条目：能力、菜单代码、排序、关系 +5. 捕获配置变量和外部依赖 +6. 搭建模块基础设施 + +**多技能输出：** 专用 `{code}-setup/` 文件夹，含合并脚本、清理脚本和通用 SKILL.md。 + +**独立输出：** 技能中嵌入 `assets/module-setup.md`、`assets/module.yaml` 和 `assets/module-help.csv`，加上 `scripts/` 中的合并脚本和分发用的 `.claude-plugin/marketplace.json`。技能的 SKILL.md 被更新以在激活时检查注册状态。 + +### Validate Module（VM） + +验证模块结构完整且准确。自动检测带 setup 技能的多技能模块和带自注册的独立模块。结合确定性验证脚本和基于 LLM 的质量评估。 + +| 方面 | 详情 | +| ---- | ---- | +| **交互** | 交互式 | +| **输入** | 模块技能文件夹或单技能路径 | +| **输出** | 验证报告 | + +**结构检查**（脚本驱动）： + +| 检查 | 捕获什么 | +| ---- | -------- | +| 模块结构 | 缺失 setup 技能或独立文件（`module-setup.md`、合并脚本） | +| 覆盖率 | 没有 CSV 条目的技能、指向不存在技能的孤立条目 | +| 菜单代码 | 模块内重复代码 | +| 引用 | before/after 字段指向不存在的能力 | +| 必填字段 | CSV 行中缺失技能名、显示名、菜单代码或描述 | +| module.yaml | 缺失 code、name 或 description | + +**质量评估**（LLM 驱动）： + +- 描述准确性：每个条目是否匹配技能实际功能？ +- 描述质量：简洁、面向行动、具体、不过于冗长 +- 完整性：所有不同能力是否注册为独立行？ +- 排序：before/after 关系是否合理？ +- 菜单代码：是否直觉且易记？ + +## 触发短语 + +| 意图 | 短语 | 构建器 | 路由 | +| ---- | ---- | ------ | ---- | +| 新建 | "create/build/design an agent" | Agent | `prompts/build-process.md` | +| 新建 | "create/build/design a workflow/skill/tool" | Workflow | `prompts/build-process.md` | +| 编辑 | "edit/modify/update an agent" | Agent | `prompts/build-process.md` | +| 编辑 | "edit/modify/update a workflow/skill" | Workflow | `prompts/build-process.md` | +| 转换 | "convert this to a BMad agent" | Agent | `prompts/build-process.md` | +| 转换 | "convert this to a BMad skill" | Workflow | `prompts/build-process.md` | +| 转换 | `--convert ` | Workflow | `./references/convert-process.md` | +| 优化 | "quality check/validate/optimize/review agent" | Agent | `prompts/quality-optimizer.md` | +| 优化 | "quality check/validate/optimize/review workflow/skill" | Workflow | `prompts/quality-optimizer.md` | +| 构思 | "ideate module/plan a module/brainstorm a module" | Module | `./references/ideate-module.md` | +| 创建 | "create module/build a module/scaffold a module" | Module | `./references/create-module.md` | +| 验证 | "validate module/check module" | Module | `./references/validate-module.md` | diff --git a/docs/zh-cn/reference/index.md b/docs/zh-cn/reference/index.md new file mode 100644 index 0000000..497c973 --- /dev/null +++ b/docs/zh-cn/reference/index.md @@ -0,0 +1,13 @@ +--- +title: 参考 +description: BMad Builder 技术参考 +--- + +# 参考 + +BMad Builder 技术文档。 + +| 参考 | 描述 | +| ---- | ---- | +| **[构建器技能](./builder-commands.md)** | Agent Builder 和 Workflow Builder 的技能、命令与能力 | +| **[工作流与技能模式](./workflow-patterns.md)** | 结构类型、设计模式与执行模型 | diff --git a/docs/zh-cn/reference/workflow-patterns.md b/docs/zh-cn/reference/workflow-patterns.md new file mode 100644 index 0000000..d1e57d8 --- /dev/null +++ b/docs/zh-cn/reference/workflow-patterns.md @@ -0,0 +1,113 @@ +--- +title: '工作流与技能模式' +description: 三种技能类型、结构模式、决策标准与执行模型的参考 +--- + +BMad Builder 如何分类和结构化技能的参考。每个技能属于三种类型之一，各有不同的结构和信号集。 + +## 技能类型分类 + +| 类型 | 描述 | 结构 | +| ---- | ---- | ---- | +| **简单工具** | 输入/输出构建模块。无头、可组合、通常由脚本驱动。可选择不加载配置以实现真正独立 | SKILL.md + `scripts/` | +| **简单工作流** | 多步流程包含在单个 SKILL.md 中。直接从模块 config.yaml 加载配置。极少或没有 `prompts/` | SKILL.md + 可选 `resources/` | +| **复杂工作流** | 多阶段，带渐进式展开，阶段提示词在 `prompts/` 中，配置集成。可能支持无头模式 | SKILL.md（路由）+ `prompts/` 阶段 + `resources/` | + +## 决策树 + +``` +1. 它是具有清晰输入/输出的可组合构建模块吗？ + └─ 是 → 简单工具 + └─ 否 ↓ + +2. 能否放在一个 SKILL.md 中而不需要渐进式展开？ + └─ 是 → 简单工作流 + └─ 否 ↓ + +3. 它需要多个阶段、长时运行流程或渐进式展开吗？ + └─ 是 → 复杂工作流 +``` + +## 分类信号 + +### 简单工具 + +- 清晰的输入 → 处理 → 输出模式 +- 执行期间无需用户交互 +- 其他技能和工作流调用它 +- 确定性或近确定性行为 +- 可以是脚本但需要 LLM 判断 +- 示例：JSON 验证器、格式转换器、文件结构检查器 + +### 简单工作流 + +- 3-8 个编号步骤 +- 在特定节点需用户交互 +- 使用标准工具（gh、git、npm 等） +- 产出单个输出制品 +- 无需跨压缩追踪状态 +- 示例：PR 创建器、部署检查清单、代码审查 + +### 复杂工作流 + +- 多个不同阶段或阶段 +- 长时运行（可能遇到上下文压缩） +- 需要渐进式展开（内容太多放不进一个文件） +- SKILL.md 中的路由逻辑分派到阶段提示词 +- 跨阶段产出多个制品 +- 可能支持无头/自主模式 +- 示例：智能体构建器、模块构建器、项目脚手架 + +## 结构模式 + +### 简单工具 + +``` +bmad-my-utility/ +├── SKILL.md # 完整指令、输入/输出规范 +└── scripts/ # 核心逻辑 + ├── process.py + └── tests/ +``` + +### 简单工作流 + +``` +bmad-my-workflow/ +├── SKILL.md # 内联步骤、配置加载、输出规范 +└── resources/ # 可选参考数据 +``` + +### 复杂工作流 + +``` +bmad-my-complex-workflow/ +├── SKILL.md # 路由逻辑，分派到 prompts/ +├── prompts/ # 阶段指令 +│ ├── 01-discovery.md +│ ├── 02-planning.md +│ ├── 03-execution.md +│ └── 04-review.md +├── resources/ # 参考数据、模板、schema +├── agents/ # 并行工作的子智能体定义 +└── scripts/ # 确定性操作 + └── tests/ +``` + +## 执行模型 + +| 模型 | 适用类型 | 描述 | +| ---- | -------- | ---- | +| **交互式** | 全部 | 用户调用技能并对话式交互 | +| **无头/自主** | 简单工具、复杂工作流 | 无用户交互运行；接受输入，产出输出 | +| **YOLO** | 简单工作流、复杂工作流 | 用户一股脑倒出想法；构建器起草完整制品，再细化 | +| **引导** | 简单工作流、复杂工作流 | 逐节发现，过渡点带软门 | + +## 模块上下文 + +模块归属与技能类型正交。任何类型都可以是独立的或属于模块。 + +| 上下文 | 命名 | 初始化 | +| ------ | ---- | ------ | +| **模块内** | `{modulecode}-{skillname}` | 从模块 config.yaml 加载配置 | +| **独立** | `{skillname}` | 从模块 config.yaml 加载配置；简单工具可选择不加载 | diff --git a/docs/zh-cn/tutorials/build-your-first-module.md b/docs/zh-cn/tutorials/build-your-first-module.md new file mode 100644 index 0000000..da59073 --- /dev/null +++ b/docs/zh-cn/tutorials/build-your-first-module.md @@ -0,0 +1,186 @@ +--- +title: '构建你的第一个模块' +description: 使用 Module Builder 从想法到可安装包，创建一个完整的 BMad 模块 +--- + +本教程带你从最初的想法到一个可用的、可安装的 BMad 模块，包含帮助注册和配置。 + +## 你将学到 + +- 使用 Ideate Module（IM）能力规划模块 +- 在单智能体和多工作流之间选择 +- 使用 Agent Builder 和 Workflow Builder 构建单个技能 +- 使用 Create Module（CM）搭建 setup 技能脚手架 +- 使用 Validate Module（VM）验证模块 + +:::note[前置条件] + +- 项目中已注册 BMad Builder 模块（首次使用请运行 `bmad-bmb-setup`） +- 对智能体和工作流有基本了解（参见 **[什么是智能体](../../explanation/what-are-bmad-agents.md)** 和 **[什么是工作流](../../explanation/what-are-workflows.md)**） +::: + +:::tip[快速路径] +已经构建好技能？跳到 **步骤 3：搭建模块脚手架** 进行打包。只需验证已有模块？跳到 **步骤 4：验证**。 +::: + +## 理解模块 + +BMad 模块将技能打包在一起，使其可被发现和配置。Module Builder 根据你构建的内容提供两种方式： + +| 方式 | 何时使用 | 生成什么 | +| ---- | -------- | -------- | +| **Setup 技能** | 2+ 个技能的文件夹 | 专用 `{code}-setup` 技能，含配置和帮助资源 | +| **自注册** | 单个独立技能 | 注册嵌入技能自身的 `assets/` 文件夹 | + +两者产出相同的注册制品：`module.yaml`（身份和配置变量）和 `module-help.csv`（能力条目），注册到 `bmad-help`。 + +参见 **[什么是模块](../../explanation/what-are-modules.md)** 了解这些选择背后的架构。 + +## 步骤 1：规划模块 + +从 Ideate Module 能力开始。 + +:::note[示例] +**你：** "I want to ideate a module" + +**构建器：** 开始头脑风暴会话，探索模块的目的、受众和能力结构。 +::: + +构思会话覆盖： + +| 主题 | 你将决定什么 | +| ---- | ------------ | +| **愿景** | 问题空间、目标用户、核心价值 | +| **架构** | 单智能体、多工作流或混合 | +| **智能体类型** | 每个智能体：无状态、记忆型或自主型（参见 [什么是智能体](../../explanation/what-are-bmad-agents.md)） | +| **记忆** | 多智能体模块：个人记忆、共享模块记忆或两者 | +| **模块类型** | 独立或现有模块的扩展 | +| **技能** | 每个计划技能的目的、能力和关系 | +| **配置** | 自定义安装问题和变量 | +| **依赖** | 外部 CLI 工具、MCP 服务器、Web 服务 | + +输出是保存到报告文件夹的**计划文档**。构建每个技能时将引用它。 + +## 步骤 2：构建技能 + +逐个构建每个技能。 + +| 技能类型 | 构建器 | 菜单代码 | +| -------- | ------ | -------- | +| 智能体 | Agent Builder | BA | +| 工作流或工具 | Workflow Builder | BW | + +构建每个技能时分享计划文档作为上下文，让构建器知道它在模块中的位置。对于智能体，构建器通过对话式发现检测正确的类型（无状态、记忆型或自主型）并相应调整构建过程。 + +:::caution[先构建再打包] +在搭建模块脚手架之前，先构建并测试每个技能。Create Module 步骤读取你完成的技能以生成准确的帮助条目。 +::: + +## 步骤 3：搭建模块脚手架 + +运行 Create Module（CM）打包你完成的技能。 + +:::note[示例] +**你：** "I want to create a module" 或提供你的技能文件夹路径（或单个技能）。 + +**构建器：** 读取你的技能，检测是多技能还是单技能模块，确认方式，并搭建输出脚手架。 +::: + +### 多技能模块 + +构建器生成专用 setup 技能： + +``` +your-skills-folder/ +├── {code}-setup/ # 生成的 setup 技能 +│ ├── SKILL.md # 配置指令 +│ ├── scripts/ # 配置合并和清理脚本 +│ │ ├── merge-config.py +│ │ ├── merge-help-csv.py +│ │ └── cleanup-legacy.py +│ └── assets/ +│ ├── module.yaml # 模块身份和配置变量 +│ └── module-help.csv # 能力条目 +├── your-agent-skill/ +├── your-workflow-skill/ +└── ... +``` + +### 独立模块 + +构建器将注册嵌入技能本身： + +``` +your-skill/ +├── SKILL.md # 已更新，含注册检查 +├── assets/ +│ ├── module-setup.md # 自注册参考 +│ ├── module.yaml # 模块身份和配置变量 +│ └── module-help.csv # 能力条目 +├── scripts/ +│ ├── merge-config.py # 配置合并脚本 +│ └── merge-help-csv.py # 帮助 CSV 合并脚本 +└── ... +``` + +父级目录还会生成一个 `.claude-plugin/marketplace.json` 用于分发。 + +## 步骤 4：验证 + +运行 Validate Module（VM）检查结构和质量问题。 + +:::note[示例] +**你：** "Validate my module at ./my-skills-folder" + +**构建器：** 运行结构和质量检查，然后报告发现。 +::: + +| 检查类型 | 捕获什么 | +| -------- | -------- | +| **结构** | 缺失文件、孤立条目、重复菜单代码、损坏引用 | +| **质量** | 不准确的描述、缺失能力、低质量条目 | + +修复发现的问题并重新验证，直到通过。 + +## 你构建了什么 + +你的模块已准备好分发。多技能模块通过 setup 技能安装；独立模块在首次运行时自注册。无论哪种方式，能力都会出现在 `bmad-help` 中，配置自动持久化。 + +## 快速参考 + +| 能力 | 菜单代码 | 何时使用 | +| ---- | -------- | -------- | +| Ideate Module | IM | 从零规划新模块 | +| Build an Agent | BA | 创建智能体技能 | +| Build a Workflow | BW | 创建工作流或工具技能 | +| Create Module | CM | 将技能打包为可安装模块 | +| Validate Module | VM | 检查完整性和准确性 | + +## 常见问题 + +### 创建前必须先构思吗？ + +不必。如果你已经知道模块应包含什么，直接跳到 Create Module（CM）。构思在你仍在塑造概念时有帮助。 + +### 可以后续添加技能吗？ + +可以。构建新技能并在文件夹上重新运行 Create Module（CM）。反僵尸模式确保现有 setup 技能被干净替换。 + +### 如果模块只有一个技能呢？ + +Module Builder 自动处理。给它一个单技能，它会推荐**独立自注册**方式，注册直接嵌入技能并在首次运行或用户传入 `setup`/`configure` 时触发。 + +### 模块可以扩展另一个模块吗？ + +可以。在构思或创建时告诉构建器你的模块是扩展。你的帮助 CSV 条目可在 before/after 排序字段中引用父模块的能力。 + +## 获取帮助 + +- **[什么是模块](../../explanation/what-are-modules.md)**：概念和架构 +- **[模块配置](../../explanation/module-configuration.md)**：Setup 技能内部和配置模式 +- **[构建器命令参考](../../reference/builder-commands.md)**：所有构建器能力 +- **[Discord](https://discord.gg/gk8jAdXWmj)**：社区支持 + +:::tip[关键要点] +工作流是 IM，然后每个技能用 BA/BW，然后 CM 打包，然后 VM 验证。单技能模块不需要额外的 setup 基础设施。 +::: diff --git a/docs/zh-cn/tutorials/index.md b/docs/zh-cn/tutorials/index.md new file mode 100644 index 0000000..de1f9c1 --- /dev/null +++ b/docs/zh-cn/tutorials/index.md @@ -0,0 +1,14 @@ +--- +title: 教程 +description: 通过动手示例学习 BMad Builder +--- + +# 教程 + +BMad Builder 动手教程。 + +| 教程 | 描述 | +| ---- | ---- | +| **[构建你的第一个模块](./build-your-first-module.md)** | 从规划、构建、脚手架到验证，完成一个完整 BMad 模块 | + +概念与设计模式请参见 **[概念说明](../explanation/)**。能力详情请参见 **[构建器命令参考](../reference/builder-commands.md)**。 diff --git a/tools/build-docs.mjs b/tools/build-docs.mjs index 24eaf53..f628023 100644 --- a/tools/build-docs.mjs +++ b/tools/build-docs.mjs @@ -33,7 +33,9 @@ const LLM_WARN_CHARS = 500_000; const LLM_EXCLUDE_PATTERNS = [ 'changelog', 'archived', + 'zh-cn', // Note: Files/dirs starting with _ (like _STYLE_GUIDE.md, _archive/) are excluded in shouldExcludeFromLlm() + // Note: Translated locale directories (zh-cn, etc.) are excluded to keep LLM context English-only ]; // ============================================================================= diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 0c2b801..f731103 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -5,6 +5,7 @@ import sitemap from '@astrojs/sitemap'; import rehypeMarkdownLinks from './src/rehype-markdown-links.js'; import rehypeBasePaths from './src/rehype-base-paths.js'; import { getSiteUrl } from './src/lib/site-url.mjs'; +import { locales } from './src/lib/locales.mjs'; const siteUrl = getSiteUrl(); const urlParts = new URL(siteUrl); @@ -41,6 +42,10 @@ export default defineConfig({ title: 'BMad Builder', tagline: 'Tool for creating custom BMad agents and modules.', + // i18n: locale config from shared module (website/src/lib/locales.mjs) + defaultLocale: 'root', + locales, + favicon: '/favicon.ico', // Social links @@ -83,24 +88,32 @@ export default defineConfig({ // Sidebar configuration (Diataxis structure) sidebar: [ - { label: 'Welcome', slug: 'index' }, + { + label: 'Welcome', + translations: { 'zh-CN': '欢迎' }, + slug: 'index', + }, { label: 'Tutorials', + translations: { 'zh-CN': '教程' }, collapsed: false, autogenerate: { directory: 'tutorials' }, }, { label: 'How-To Guides', + translations: { 'zh-CN': '操作指南' }, collapsed: true, autogenerate: { directory: 'how-to' }, }, { label: 'Explanation', + translations: { 'zh-CN': '概念说明' }, collapsed: true, autogenerate: { directory: 'explanation' }, }, { label: 'Reference', + translations: { 'zh-CN': '参考' }, collapsed: true, autogenerate: { directory: 'reference' }, }, diff --git a/website/src/content/config.ts b/website/src/content/config.ts index 31b7476..02ea2ac 100644 --- a/website/src/content/config.ts +++ b/website/src/content/config.ts @@ -1,6 +1,7 @@ import { defineCollection } from 'astro:content'; -import { docsSchema } from '@astrojs/starlight/schema'; +import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; export const collections = { docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), }; diff --git a/website/src/content/i18n/zh-CN.json b/website/src/content/i18n/zh-CN.json new file mode 100644 index 0000000..a37ff15 --- /dev/null +++ b/website/src/content/i18n/zh-CN.json @@ -0,0 +1,28 @@ +{ + "skipLink.label": "跳到正文", + "search.label": "搜索", + "search.ctrlKey": "Ctrl", + "search.cancelLabel": "取消", + "themeSelect.accessibleLabel": "选择主题", + "themeSelect.dark": "深色", + "themeSelect.light": "浅色", + "themeSelect.auto": "自动", + "languageSelect.accessibleLabel": "选择语言", + "menuButton.accessibleLabel": "菜单", + "sidebarNav.accessibleLabel": "侧边导航", + "tableOfContents.onThisPage": "本页目录", + "tableOfContents.overview": "概览", + "i18n.untranslatedContent": "这部分内容暂未提供中文版本。", + "page.editLink": "编辑此页", + "page.lastUpdated": "最后更新：", + "page.previousLink": "上一页", + "page.nextLink": "下一页", + "page.draft": "此内容为草稿，不会出现在正式版本中。", + "404.text": "页面未找到。请检查地址，或使用站内搜索。", + "aside.note": "注意", + "aside.tip": "提示", + "aside.caution": "警告", + "aside.danger": "危险", + "fileTree.directory": "文件夹", + "builtWithStarlight.label": "由 Starlight 构建" +} diff --git a/website/src/lib/locales.mjs b/website/src/lib/locales.mjs new file mode 100644 index 0000000..8f45181 --- /dev/null +++ b/website/src/lib/locales.mjs @@ -0,0 +1,27 @@ +/** + * Shared i18n locale configuration. + * + * Single source of truth for locale definitions used by: + * - website/astro.config.mjs (Starlight i18n) + * - tools/build-docs.mjs (llms-full.txt locale exclusion) + * + * The root locale (English) uses Starlight's 'root' key convention + * (no URL prefix). All other locales get a URL prefix matching their key. + */ + +export const locales = { + root: { + label: 'English', + lang: 'en', + }, + 'zh-cn': { + label: '简体中文', + lang: 'zh-CN', + }, +}; + +/** + * Non-root locale keys (the URL prefixes for translated content). + * @type {string[]} + */ +export const translatedLocales = Object.keys(locales).filter((k) => k !== 'root'); From f16b7ed933919890b1d1abbb4248e86d23bbfa9d Mon Sep 17 00:00:00 2001 From: leon Date: Mon, 13 Apr 2026 16:50:30 +0800 Subject: [PATCH 2/2] docs(i18n): add zh-CN translations for BMad Ecosystem sidebar labels Co-Authored-By: Claude Opus 4.6 --- website/astro.config.mjs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/website/astro.config.mjs b/website/astro.config.mjs index f731103..f0f4c40 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -119,12 +119,13 @@ export default defineConfig({ }, { label: 'BMad Ecosystem', + translations: { 'zh-CN': 'BMad 生态' }, collapsed: false, items: [ - { label: 'BMad Method', link: 'https://docs.bmad-method.org/', attrs: { target: '_blank' } }, - { label: 'Creative Intelligence Suite', link: 'https://cis-docs.bmad-method.org/', attrs: { target: '_blank' } }, - { label: 'Game Dev Studio', link: 'https://game-dev-studio-docs.bmad-method.org/', attrs: { target: '_blank' } }, - { label: 'Test Architect (TEA)', link: 'https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/', attrs: { target: '_blank' } }, + { label: 'BMad Method', translations: { 'zh-CN': 'BMad 方法' }, link: 'https://docs.bmad-method.org/', attrs: { target: '_blank' } }, + { label: 'Creative Intelligence Suite', translations: { 'zh-CN': '创意智能套件' }, link: 'https://cis-docs.bmad-method.org/', attrs: { target: '_blank' } }, + { label: 'Game Dev Studio', translations: { 'zh-CN': '游戏开发工作室' }, link: 'https://game-dev-studio-docs.bmad-method.org/', attrs: { target: '_blank' } }, + { label: 'Test Architect (TEA)', translations: { 'zh-CN': '测试架构师 (TEA)' }, link: 'https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/', attrs: { target: '_blank' } }, ], }, ],