#!/usr/bin/env python3 # 根据 _bmad/_config/bmad-help.csv 与下行中文说明表，生成仓库根目录 bmad-help.zh-CN.md from __future__ import annotations import csv from pathlib import Path REPO = Path(__file__).resolve().parents[1] CSV_PATH = REPO / "_bmad" / "_config" / "bmad-help.csv" OUT_PATH = REPO / "bmad-help.zh-CN.md" MODULE_ZH = { "BMad Builder": "BMad 构建器", "BMad Method": "BMad 方法", "Core": "核心", "Creative Intelligence Suite": "创意智能套件（CIS）", "Game Dev Studio": "游戏开发工作室（GDS）", "Test Architecture Enterprise": "测试架构企业版（TEA）", "Web Design Studio": "网页设计工作室（WDS）", } PHASE_ZH = { "anytime": "随时", "1-analysis": "阶段 1 · 分析", "2-planning": "阶段 2 · 规划", "3-solutioning": "阶段 3 · 方案设计", "4-implementation": "阶段 4 · 实现", "0-learning": "阶段 0 · 学习", "1-preproduction": "前期制作", "2-design": "设计", "3-technical": "技术", "4-production": "制作", "gametest": "游戏测试", "0-wds-pitch": "WDS · 宣讲/对齐", "0-wds-agents": "WDS · 唤醒代理", "1-wds-strategy": "WDS · 策略", "2-wds-design": "WDS · 设计", "3-wds-build": "WDS · 构建/验证", } # 与 CSV 行顺序一致（共 114 行），对应「sequence」列的中文说明；空原文由脚本行号对应空序列行 ZH_BY_ROW = [ "通过对话式梳理，创建、编辑或重建 Agent 技能。", "对既有 Agent 做质量分析：结构、内聚、提示词工艺与改进空间。", "安装或更新 BMad Builder 模块配置与帮助条目。", "头脑风暴并规划 BMad 模块：创意、架构与构建计划。", "将模块基础设施脚手架化为可安装的 BMad 模块技能。", "检查模块结构是否完整、准确，且能力均已正确注册。", "创建、编辑或重建工作流或工具型技能。", "对既有工作流/技能做质量分析：结构、效率与改进空间。", "将任意技能转换为符合 BMad 的成果导向形态，并生成前后对比 HTML 报告。", "详细描述需求，由代理按文档最佳实践撰写；可多轮对话并子流程做调研/审阅。", "若发现文档惯例缺失，把你的偏好写入代理记忆中的 documentation-standards.md。", "根据描述生成 Mermaid 图；未指定类型时会建议合适的图类。", "对照文档规范与最佳实践审查指定文档，按优先级给出可执行的改进建议。", "为复杂概念撰写清晰技术说明，附示例与图示。", "专家引导，使用一种或多种技法进行项目头脑风暴。", "确保 PRD、UX、架构与 Epic/Story 彼此对齐。", "故事循环：若有问题退回 DS；通过后进入下一 CS，或 Epic 完成时走 ER。", "在重大变更时纠偏：可能建议重来、更新 PRD、重做架构/冲刺规划或修正 Epic 与 Story。", "引导式产出技术决策文档（架构）。", "在架构文档（CA）之后创建 Epic 与用户故事。", "专家引导完成产品需求文档（PRD）。", "故事循环起点：准备冲刺计划中「下一个」待做 Story，或指定 Epic/Story。", "在开发开始前校验 Story 是否就绪、完整。", "落实 UX 方案；若项目以 UI 为主，强烈建议使用。", "故事循环：执行 Story 实现与测试，经 CR，如需修复回到 DS。", "分析现有项目并产出可用文档。", "行业领域深度研究、专业术语与知识沉淀。", "在通过 PRD 校验流程后，编辑并改进指定路径的 PRD。", "扫描代码库生成精简、面向 LLM 的 project-context.md；棕地项目尤其重要。", "市场、竞品、客户需求与趋势分析。", "引导式厘清产品创意与核心价值。", "为已实现代码生成自动化 API 与 E2E 测试；非代码评审或 Story 校验（请用 CR）。", "统一「意图进、代码出」：澄清、实现、审阅与交付展示。", "可选：在 Epic 结束时回顾成果与经验，规划下一 Epic；重大问题考虑走 CC。", "启动实现阶段：生成实现代理将按序执行的冲刺计划。", "随时总结 Sprint 状态并路由到下一工作流。", "技术可行性、架构选项与实现路径研究。", "在创建 PRD（CP）之后校验 PRD 质量。", "在创意早期或思路卡住时做头脑风暴。", "生成节省 token 的蒸馏文，保留供下游 LLM 使用的关键信息。", "成稿后润色正文表达。", "当文档由多段子流程拼成或结构需加强时，做结构性编辑审阅。", "判断当前所处 BMad 流程位置并回答问题；推荐下一步技能与调用方式。", "在不加载全部文件的前提下为目录生成/更新索引，便于掌握文档地图。", "编排多代理/多视角讨论与协作。", "在定稿前做对抗性质量审查；其他模块的代码审也可自动调用，亦适用于文档。", "与对抗审搭配，从边界场景做正交补充，重方法而非「挑刺态度」。", "当单份文档过大（常为 >500 行）时拆分为可管理片段。", "用一种或多种技法主持头脑风暴会话。", "以同理心驱动的人本设计流程指导。", "识别颠覆机会并设计商业模式创新。", "运用系统化问题解决方法拆解复杂挑战。", "用成熟叙事框架与技巧撰写故事/叙述。", "快速游戏原型，验证机制与创意。", "在游戏语境下主持头脑风暴。", "在投产前确保 GDD、UX、架构与 Epic/Story 对齐。", "对标记为「待评审」的 Story 做干净上下文的 QA 代码审查。", "游戏开发冲刺偏离路线时进行纠偏。", "依据 GDD 需求创建 Epic 与 Story 列表，作为开发规格驱动。", "交互式游戏简报，引导用户明确游戏愿景。", "撰写游戏设计文档 GDD：机制、系统、进度与实现指引。", "为剧情向游戏撰写叙事文档：结构、人物弧与世界观。", "从 GDD 或从零撰写 PRD，供 bmad-assist 等外部工具使用。", "为开发代理准备上下文充分的 Story。", "落实游戏 UX/UI；若 UI 是核心，强烈建议使用。", "执行 Dev Story：按任务与测试实现。", "分析现有游戏项目并产出文档。", "游戏产业领域深度研究与术语沉淀。", "搭建 E2E 测试基础设施脚手架。", "改进并增强既有 PRD。", "产出可伸缩游戏架构：引擎、系统、网络与技术设计。", "生成适配所选智能体工具一致性的 project-context.md。", "游戏市场、竞品与玩家需求分析。", "设计性能测试策略。", "撰写结构化试玩/测试计划。", "兼顾游戏特性的灵活开发流程。", "实验性一体化快捷流：单工作流内完成澄清、计划、实现、审阅与展示。", "小需求、小改动、简单应用/工具，无需冗长规划。", "在游戏开发 Epic 完成后组织团队回顾。", "由 Epic 文件生成或更新 sprint-status.yaml。", "查看冲刺进度、暴露风险并给出下一步行动建议。", "游戏引擎选项与实现路径的技术可行性研究。", "生成自动化游戏测试。", "设计覆盖流程与质量要求的游戏测试场景。", "为 Unity / Unreal / Godot 等项目初始化游戏测试框架架构。", "评审测试质量与覆盖。", "按外部工具兼容标准校验 PRD。", "TEA 学院：通过 7 次课讲授测试基础（含进度与证书相关产出）。", "生成失败用例（TDD 红灯阶段）。", "扩展自动化测试覆盖。", "配置 CI/CD 质量流水线。", "初始化生产级测试框架脚手架。", "非功能需求（NFR）评估。", "基于风险的测试规划。", "质量审计（0–100 分制）。", "覆盖度可追溯与质量门禁决策。", "带设计日志与浏览器验证的迭代「构建—验证」循环。", "干系人共识 pitch 与服务协议；若做自有产品可跳过。", "详细规格前的快速视觉草图探索；直接场景可跳过。", "逐页逐元素记录设计决策，开发可直接据此实现。", "校验规格完整并打包为 DD yaml，供开发交接。", "管理组件库与设计令牌；设计系统模式为「无」时跳过。", "第 3–4 阶段 UX 设计师代理 Freya：检查前置条件并给出下一步。", "从规格抽取可复用模式为组件定义；无设计系统时跳过。", "治理代理 Idun：访谈组织以配置 Agent Space 与权限模型。", "以「人设 + 目标 + 结果」定义用户旅程，并与触发图驱动力关联。", "平台、设备、集成与约束等技术边界；简单落地页可跳过。", "持续改进：反馈 → 触发图 → 规格 → 代码 → 验证。", "定义产品愿景、定位与成功标准，设计决策应可追溯至此。", "第 1–2 阶段战略分析师代理 Saga：扫描仓库并建议下一步。", "跨界面串联用户旅程与入口、过渡、异常路径；简单场景可跳过。", "将业务目标映射到用户心理：人设、功能与驱动力打分。", "在真实用户环境中做可用性测试与回顾式出声思考。", "将规格转为带样式的 HTML 原型，可与 Figma 往返。", ] def _is_arg_cell(s: str) -> bool: """CSV 部分行在 phase 前插入了 [path] / {-H:...} 等参数列。""" if not s: return False if s == "[path]": return True if s.startswith("{-H") or s.startswith("{--"): return True if s.startswith("{description:"): return True return False def phase_token(r: list[str]) -> str: if r[5]: return r[7] or "" if _is_arg_cell(r[6] or ""): return r[7] or "" return r[6] or "" def phase_display(r: list[str]) -> str: p = phase_token(r) if not p or p in ("true", "false"): return "—" return PHASE_ZH.get(p, p) def prereq_display(r: list[str]) -> str: if r[5]: cand = r[12] elif _is_arg_cell(r[6] or ""): cand = r[8] or "" else: cand = r[7] or "" if not cand or cand in ("true", "false"): return "—" return cand def required_gate(r: list[str]) -> str: if r[5]: return r[13] if _is_arg_cell(r[6] or ""): return r[13] return r[12] def output_display(r: list[str]) -> str: if r[5]: loc, out = r[14], r[15] elif _is_arg_cell(r[6] or ""): loc, out = r[14], r[15] else: loc, out = r[13], r[14] parts = [x.replace("|", " · ") for x in (loc, out) if x] return " / ".join(parts) if parts else "—" def main() -> None: with CSV_PATH.open(newline="", encoding="utf-8") as f: rows = list(csv.reader(f))[1:] if len(rows) != len(ZH_BY_ROW): raise SystemExit(f"行数不匹配: CSV {len(rows)} vs ZH {len(ZH_BY_ROW)}") by_mod: dict[str, list[list[str]]] = {} for r in rows: by_mod.setdefault(r[0], []).append(r) lines: list[str] = [ "# BMad 帮助目录（中文版）", "", "本文档由 [`_bmad/_config/bmad-help.csv`](_bmad/_config/bmad-help.csv) 翻译并整理，便于中文读者检索 **菜单码**、**技能** 与用途。", "", "技能调用方式（斜杠命令 / 自然语言等）以本机 `npx bmad-method install` 与 Cursor 集成为准。", "", "## 表列说明", "", "| 列 | 含义 |", "| --- | --- |", "| **码** | 菜单快捷码（不同模块下可能重复，以技能名列区分） |", "| **显示名称** | CSV 英文显示名（与上游一致，便于对照） |", "| **技能** | 技能标识 / 工作流名 |", "| **说明** | 对「sequence」列的中文释义 |", "| **阶段** | 工作流阶段或触发时机（`anytime` 等为随时） |", "| **前置** | 建议先完成的技能或条件（CSV 中错位字段已尽量还原） |", "| **必选** | 是否后期阶段强制项（`true` / `false`） |", "| **产出** | 主要输出位置或产物类型（保留英文路径占位符） |", "", "---", "", ] idx = 0 for mod in [ "BMad Builder", "BMad Method", "Core", "Creative Intelligence Suite", "Game Dev Studio", "Test Architecture Enterprise", "Web Design Studio", ]: mrows = by_mod.get(mod) if not mrows: continue lines.append(f"## {MODULE_ZH.get(mod, mod)}") lines.append("") lines.append( "| 码 | 显示名称 | 技能 | 说明 | 阶段 | 前置 | 必选 | 产出 |" ) lines.append("| --- | --- | --- | --- | --- | --- | --- | --- |") for r in mrows: zh = ZH_BY_ROW[idx] idx += 1 req = required_gate(r) lines.append( "| {code} | {name} | `{skill}` | {desc} | {phase} | {pre} | {req} | {out} |".format( code=r[3].replace("|", "\\|"), name=r[2].replace("|", "\\|"), skill=r[1].replace("|", "\\|"), desc=zh.replace("|", "\\|"), phase=phase_display(r).replace("|", "\\|"), pre=prereq_display(r).replace("|", "\\|"), req=req.replace("|", "\\|"), out=output_display(r).replace("|", "\\|"), ) ) lines.append("") if idx != len(rows): raise SystemExit(f"索引错误: 写了 {idx} 行，预期 {len(rows)}") lines.append("---") lines.append("") lines.append( "*生成脚本：[`scripts/render_bmad_help_zh_cn.py`](scripts/render_bmad_help_zh_cn.py)（修改译文表后重新运行以更新本文档。）*" ) lines.append("") OUT_PATH.write_text("\n".join(lines), encoding="utf-8") print(f"Wrote {OUT_PATH}") if __name__ == "__main__": main()