From fda996031f4ec1664947d1a942cfbbbaa3fd73ea Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 11 May 2026 14:29:53 +0800
Subject: [PATCH] docs: add BDD skill

---
 .codex/skills/behavior-driven-development     |   1 +
 .../behavior-driven-development/SKILL.md      | 392 ++++++++++++++++++
 2 files changed, 393 insertions(+)
 create mode 120000 .codex/skills/behavior-driven-development
 create mode 100644 .hermes/skills/behavior-driven-development/SKILL.md

diff --git a/.codex/skills/behavior-driven-development b/.codex/skills/behavior-driven-development
new file mode 120000
index 00000000..31fbb4e7
--- /dev/null
+++ b/.codex/skills/behavior-driven-development
@@ -0,0 +1 @@
+C:/proj/Genarrative/.hermes/skills/behavior-driven-development
\ No newline at end of file
diff --git a/.hermes/skills/behavior-driven-development/SKILL.md b/.hermes/skills/behavior-driven-development/SKILL.md
new file mode 100644
index 00000000..7d2f5a02
--- /dev/null
+++ b/.hermes/skills/behavior-driven-development/SKILL.md
@@ -0,0 +1,392 @@
+---
+name: behavior-driven-development
+description: 在 Genarrative 中需要用 BDD/行为驱动方式把 PRD、用户故事、验收标准转成可执行场景、Gherkin 用例、测试计划或 TDD 落地顺序时使用。
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [BDD, Gherkin, 验收标准, 用户故事, 测试, Genarrative]
+    related_skills: [writing-plans, test-driven-development, systematic-debugging, requesting-code-review]
+---
+
+# BDD 行为驱动开发流程
+
+用于在 Genarrative 项目中，把产品需求、用户故事、业务规则和验收标准沉淀成清晰、可讨论、可验证的行为场景，并进一步映射到前端测试、API 测试、领域服务测试或 E2E 测试。
+
+BDD 的重点不是“先写一堆 UI 自动化脚本”，而是让团队先对“用户在什么上下文下做什么，系统应该给出什么可观察结果”达成一致。
+
+## 适用场景
+
+- 从 PRD、设计文档、用户故事中提炼验收标准。
+- 功能需求容易产生理解偏差，需要先把行为边界说清楚。
+- 涉及前端、后端、运行态、异步任务、权限、埋点或状态流转的跨层功能。
+- 需要把“完成标准”写成 Given / When / Then 场景。
+- 需要在编码前规划测试覆盖：单元测试、组件测试、API 测试、E2E 测试。
+- 希望和 TDD 配合：先写行为场景，再把场景拆到 RED-GREEN-REFACTOR。
+- 需要给产品、测试、前后端开发共同评审的一份中文验收说明。
+
+不适用：
+
+- 纯重构且对外行为不变，只需要 characterization tests 或回归测试。
+- 一次性小改动，验收规则非常明确且无跨层状态。
+- 只想记录实现细节、代码结构或技术方案；这类内容更适合技术设计文档。
+
+## 必读约束
+
+1. 先描述用户可观察行为，再讨论实现细节。
+2. 场景必须可验证，避免“体验更好”“更智能”“合理展示”等不可判定表述。
+3. 不要把 Gherkin 写成低层 UI 点击脚本；UI 细节只在确实属于业务行为时出现。
+4. 中文 PRD、中文 UI 文案、中文剧情和注释不要擅自改成英文。
+5. 如果项目文档不足以支持准确落地，应先补齐 `docs/` 下的 PRD/设计/技术文档，再进入编码。
+6. BDD 场景要覆盖主要成功路径、关键失败路径、权限/登录态、边界条件和回归风险。
+
+## 核心格式
+
+推荐使用中文 Gherkin：
+
+```gherkin
+功能: <业务能力名称>
+  为了 <用户/业务价值>
+  作为 <角色>
+  我希望 <能力>
+
+  背景:
+    假如 <所有场景共享的前置条件>
+
+  场景: <具体行为名称>
+    假如 <上下文/已有状态>
+    当 <用户动作或系统事件>
+    那么 <可观察结果>
+    而且 <额外可观察结果>
+
+  场景大纲: <带参数的行为名称>
+    假如 <上下文中包含 <变量>>
+    当 <动作>
+    那么 <结果>
+
+    例子:
+      | 变量 | 期望 |
+      | A    | X    |
+      | B    | Y    |
+```
+
+英文关键字也可以使用：
+
+```gherkin
+Feature: Work publish permission
+  Scenario: Anonymous user attempts to publish a draft
+    Given an anonymous user has a generated draft
+    When the user clicks publish
+    Then the login modal should be shown
+    And the draft should remain unchanged
+```
+
+在 Genarrative 项目内，若参与评审的人主要使用中文，优先中文场景；测试框架要求英文命名时，可以保留中文场景标题并在测试文件中使用英文 describe/it。
+
+## 从需求提炼 BDD 场景
+
+### Step 1: 识别角色和业务目标
+
+先回答：
+
+- 谁在使用？游客、已登录用户、创作者、管理员、审核人员、系统任务？
+- 用户想完成什么？创建、生成、保存、发布、试玩、查看、兑换、导出？
+- 业务价值是什么？降低创作门槛、保护权限、保证数据一致性、提升运营可见性？
+
+### Step 2: 抽取领域词汇
+
+建立统一术语，避免同一概念多种叫法：
+
+- work / 作品
+- draft / 草稿
+- session / 创作会话
+- runtime / 运行态
+- publish / 发布
+- profile / 我的页签
+- invite code / 邀请码
+- analytics event / 埋点事件
+
+场景中优先使用业务词，不要直接写组件名、函数名、数据库表名，除非这些就是用户可见对象。
+
+### Step 3: 列出行为切片
+
+按用户旅程切分：
+
+1. 入口是否出现、是否可点击。
+2. 进入页面或工作台后的初始状态。
+3. 用户提交输入后的成功路径。
+4. 失败路径：未登录、参数无效、权限不足、网络/API 失败、异步任务失败。
+5. 状态持久化：刷新、返回、重新进入、跨设备或重新登录。
+6. 对外副作用：保存、发布、埋点、通知、导出、生成资产。
+7. 回归风险：旧入口、旧数据、移动端布局、中文编码。
+
+### Step 4: 把每个切片写成 Given / When / Then
+
+检查每个场景：
+
+- Given 只描述前置状态，不写动作过程。
+- When 只描述一个主要触发动作或事件。
+- Then 描述可观察结果，可以被测试或人工验收。
+- 一个场景只验证一个核心行为；不要把完整长流程塞进一个巨型场景。
+
+## Genarrative 场景模板
+
+### 前端入口 / 页面行为
+
+```gherkin
+功能: 我的页签反馈入口
+  为了让用户能从个人中心提交问题
+  作为已登录用户
+  我希望在我的页签打开独立的帮助与反馈页面
+
+  场景: 已登录用户从我的页签进入反馈页面
+    假如用户已登录并停留在我的页签
+    当用户点击“帮助与反馈”入口
+    那么系统应进入独立的反馈页面
+    而且底部 tab 应保持选中“我的”
+    而且页面不应展开在我的页签当前面板下方
+
+  场景: 用户从反馈页面返回我的页签
+    假如用户正在反馈页面
+    当用户点击返回按钮
+    那么系统应回到平台主页面
+    而且当前 tab 应为“我的”
+```
+
+### 登录态 / 权限行为
+
+```gherkin
+功能: 需要登录的发布能力
+  为了保护作品归属和发布链路
+  作为游客
+  我不能在未登录时发布作品
+
+  场景: 游客尝试发布生成草稿
+    假如游客已经生成一个草稿
+    当游客点击发布按钮
+    那么系统应打开登录弹窗
+    而且不应创建正式作品
+    而且草稿内容应保留在当前会话中
+```
+
+### 后端 API / 领域规则
+
+```gherkin
+功能: 作品正式游玩开始埋点
+  为了统计不同玩法的正式游玩行为
+  作为数据分析人员
+  我希望每次用户进入正式作品运行态时记录统一事件
+
+  场景大纲: 支持的玩法进入正式游玩
+    假如存在一个已发布的 <玩法> 作品
+    当用户从作品详情进入正式游玩
+    那么后端应记录 work_play_start 事件
+    而且 scope_kind 应为 work
+    而且 metadata 应包含 playType、workId、sourceRoute 和 userId
+
+    例子:
+      | 玩法 |
+      | puzzle |
+      | match3d |
+      | square-hole |
+      | custom-world |
+      | big-fish |
+      | visual-novel |
+```
+
+### 异步生成 / SSE 行为
+
+```gherkin
+功能: AI 创作会话流式回复
+  为了让用户看到生成进度
+  作为创作者
+  我希望提交创作指令后能收到流式反馈并最终得到可编辑草稿
+
+  场景: 成功生成草稿
+    假如用户已登录并创建了创作会话
+    当用户提交有效的创作指令
+    那么系统应开始展示流式回复
+    而且生成结束后应展示草稿结果
+    而且会话快照应包含最新用户输入和 AI 回复
+
+  场景: 生成失败
+    假如用户已登录并创建了创作会话
+    当用户提交创作指令但后端生成失败
+    那么系统应展示可理解的失败状态
+    而且用户应能够重试
+    而且不应覆盖上一次成功生成的草稿
+```
+
+## 映射到测试类型
+
+| BDD 场景关注点 | 推荐测试层级 | 示例 |
+| --- | --- | --- |
+| 纯领域规则、状态机、校验 | Rust/TS 单元测试 | reducer、module-*、schema validator |
+| DTO 契约、API 请求响应 | API/contract 测试 | Axum handler、shared-contracts serde |
+| 页面渲染、按钮状态、表单校验 | 组件测试 | Vitest + Testing Library |
+| 路由、tab、页面阶段切换 | 前端集成测试 | appPageRoutes、FlowShell 行为 |
+| 登录态、发布、运行态完整链路 | E2E/smoke | Playwright 或项目 smoke 脚本 |
+| 埋点、副作用、后台导出 | 后端集成/API 测试 | tracking event、admin export |
+
+原则：
+
+- 不是每个 BDD 场景都必须落成 E2E。
+- 能在低层稳定验证的规则，不要强行放到脆弱的浏览器自动化里。
+- E2E 只覆盖最关键的用户旅程和跨层集成风险。
+
+## 与 TDD 的配合方式
+
+BDD 先回答“行为是什么”，TDD 再推动“代码怎么长出来”。
+
+推荐顺序：
+
+1. 写 BDD 场景，确认业务行为和验收标准。
+2. 给每个场景标注测试层级：unit / component / API / E2E。
+3. 选择一个最小场景进入 TDD。
+4. RED：先写失败测试，测试名称对应场景标题。
+5. GREEN：实现最小代码让测试通过。
+6. REFACTOR：清理重复、命名、边界和文档。
+7. 回到下一个场景，直到主要路径和关键失败路径覆盖。
+
+测试命名建议：
+
+```ts
+describe('帮助与反馈入口', () => {
+  it('已登录用户从我的页签进入独立反馈页面', () => {
+    // Given ...
+    // When ...
+    // Then ...
+  })
+})
+```
+
+Rust 测试命名建议：
+
+```rust
+#[test]
+fn anonymous_user_cannot_publish_generated_draft() {
+    // Given
+    // When
+    // Then
+}
+```
+
+## 推荐产物
+
+根据任务复杂度选择产物位置。使用本 skill 产出 Gherkin/BDD 场景时，必须先决定落点，不要把正式验收场景随手写在聊天记录里。
+
+### Gherkin/BDD 场景默认落点
+
+| 产物类型 | 推荐路径 | 适用场景 |
+| --- | --- | --- |
+| 实施前分析 / 临时计划 | `.hermes/plans/<task-name>-bdd-scenarios.md` | 某次 Hermes 开发任务前，用于澄清行为、拆测试、辅助实现；不一定作为长期产品依据。 |
+| 正式产品验收 / PRD 场景 | `docs/prd/<FEATURE>_BDD_YYYY-MM-DD.md` | 产品、测试、开发都需要长期参考的验收标准、用户故事、功能边界。 |
+| 技术/API/领域行为场景 | `docs/technical/<FEATURE>_BDD_YYYY-MM-DD.md` | 后端 API、领域规则、状态机、SpacetimeDB reducer/table、SSE/异步任务、埋点副作用。 |
+| 自动化 Gherkin feature 文件 | `tests/features/*.feature` 或 `e2e/features/*.feature` | 项目已接入 Cucumber/Playwright BDD 等 Gherkin runner 时。未接入前不要随意新建测试 runner 目录。 |
+| 稳定流程或团队经验 | `.hermes/shared-memory/` 或 `.hermes/skills/` | 不是某个功能验收，而是长期可复用的团队流程、坑点、执行规范。 |
+
+默认规则：
+
+1. 用户只说“先用 BDD 梳理一下/写场景/写 Gherkin”，默认写到 `.hermes/plans/<task-name>-bdd-scenarios.md`。
+2. 用户说“正式验收标准/PRD/产品文档/给测试验收”，写到 `docs/prd/<FEATURE>_BDD_YYYY-MM-DD.md`。
+3. 用户说“API 行为/后端规则/状态机/埋点/异步任务/SpacetimeDB”，写到 `docs/technical/<FEATURE>_BDD_YYYY-MM-DD.md`。
+4. 用户明确要求“可执行 feature 文件”且项目已有 runner，再写 `.feature` 文件；否则先写 Markdown BDD 文档，并在测试映射中标注未来自动化落点。
+5. 如果 BDD 场景会作为编码依据，文档中必须包含“测试映射”表，标注场景要落到哪些测试文件。
+
+命名建议：
+
+```text
+.hermes/plans/profile-feedback-bdd-scenarios.md
+docs/prd/PROFILE_FEEDBACK_BDD_2026-05-11.md
+docs/technical/WORK_PLAY_TRACKING_BDD_2026-05-11.md
+tests/features/profile-feedback.feature
+e2e/features/invite-code.feature
+```
+
+### 其他配套产物
+
+除 BDD/Gherkin 场景外，相关配套内容可放在：
+
+- 实施计划：`.hermes/plans/<task-name>.md`
+- 产品/验收文档：`docs/prd/<FEATURE>_PRD_YYYY-MM-DD.md`
+- 技术设计：`docs/technical/<FEATURE>_TECHNICAL_YYYY-MM-DD.md`
+- 共享经验或稳定流程：`.hermes/shared-memory/` 或 `.hermes/skills/`
+
+BDD 文档建议包含：
+
+```markdown
+# <功能名> BDD 验收场景
+
+## 背景
+- 需求来源：
+- 相关文档：
+- 相关入口/接口：
+
+## 角色与目标
+- 角色：
+- 目标：
+- 非目标：
+
+## 场景清单
+
+### 功能: <能力>
+
+```gherkin
+场景: <场景名>
+  假如 ...
+  当 ...
+  那么 ...
+```
+
+## 测试映射
+
+| 场景 | 测试层级 | 目标文件 | 状态 |
+| --- | --- | --- | --- |
+| ... | component | ... | planned |
+
+## 开放问题
+- ...
+```
+
+注意：上面的 Markdown 模板中如果嵌套代码块，需要在真实文档里调整围栏长度，避免代码块提前闭合。
+
+## 评审检查清单
+
+- [ ] 每个场景都有清晰角色或业务上下文。
+- [ ] Given / When / Then 没有混入过多实现细节。
+- [ ] Then 都是可观察、可测试、可人工验收的结果。
+- [ ] 覆盖成功路径、失败路径、权限/登录态、边界条件。
+- [ ] 明确哪些场景需要自动化，哪些只需人工验收。
+- [ ] 自动化测试层级合理，没有把所有行为都塞进 E2E。
+- [ ] 中文文案、剧情、注释、文档没有被无意翻译或改写成英文。
+- [ ] 涉及中文文件修改时计划运行编码检查。
+
+## 常见坑
+
+1. **把 BDD 写成 UI 操作流水账。** 例如“点击第一个按钮，再点第二个按钮”。应改为用户意图和业务结果。
+2. **Then 不可验证。** “体验更顺滑”不是验收标准；要写成加载状态、错误提示、数据状态、页面阶段等可观察结果。
+3. **一个场景塞太多断言。** 长流程应拆成多个小场景，避免失败时不知道真正坏在哪里。
+4. **只写 happy path。** Genarrative 常见风险在登录态、刷新恢复、异步失败、端口/后端不可用、旧数据兼容和移动端布局。
+5. **把实现方案当成业务规则。** “调用某函数”通常不是用户行为；除非是 API/技术验收，否则放到技术设计或测试实现里。
+6. **BDD 和 TDD 脱节。** 写完场景后要映射测试层级和目标文件，否则场景容易停留在文档层。
+7. **场景词汇不统一。** work、draft、session、runtime、publish 等概念要和项目现有文档/代码保持一致。
+8. **忽略文档先行约束。** 若 PRD 不足以编码落地，先补文档，再开始工程修改。
+
+## 验证与收口
+
+执行 BDD 相关任务后，至少确认：
+
+- [ ] 已产出或更新 BDD 场景文档/计划。
+- [ ] 场景已映射到具体测试层级和目标文件。
+- [ ] 若进入编码，已按 TDD 或等价方式先补测试。
+- [ ] 已运行相关验证命令，例如：
+
+```bash
+npm run check:encoding
+npm run typecheck
+npm run test -- --run <相关测试文件>
+```
+
+- [ ] 若涉及后端 Rust/API，按相关 DDD/SpacetimeDB 文档运行对应 cargo/npm/API smoke 验证。
+- [ ] 若产生长期有效经验，已同步到 `.hermes/shared-memory/` 或合适的仓库级 skill。