307 lines
14 KiB
Python
307 lines
14 KiB
Python
#!/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()
|