@miniidealab/openlogos 0.2.0 → 0.3.0

package/skills/product-designer/SKILL.md

@@ -0,0 +1,228 @@
+# Skill: Product Designer
+
+> 基于 Phase 1 需求文档中的场景，细化交互流程和功能规格，生成产品原型。原型形式根据产品类型自动适配（Web/CLI/Library 等）。场景编号与 Phase 1 保持一致。
+
+## 触发条件
+
+- 用户要求写产品设计文档或功能规格
+- 用户要求画原型或设计交互
+- 用户提到 "Phase 2"、"产品设计层"、"WHAT"
+- 已有需求文档（含场景定义），需要开始设计解决方案
+
+## 核心能力
+
+1. **识别产品类型**，确定对应的原型形式（见下方产品类型与原型策略）
+2. 设计信息架构（页面结构 / 命令结构 / API 结构）
+3. 以 Phase 1 场景为骨架，细化交互流程和功能规格
+4. 为每个场景补充交互级 GIVEN/WHEN/THEN 验收条件
+5. 生成适合产品类型的原型
+6. 当场景粒度过大时，拆分为子场景（`S01.1`, `S01.2`）
+
+## 产品类型与原型策略
+
+执行本 Skill 前，先判断产品类型（可从需求文档的约束与边界、`logos-project.yaml` 的 `tech_stack` 推断），选择对应的原型形式：
+
+| 产品类型 | 典型特征 | 原型形式 | 交互规格重点 |
+|---------|---------|---------|-------------|
+| **Web 应用** | 有 UI 页面、用户登录 | HTML 可交互页面 | 页面流转、表单校验、状态变化 |
+| **CLI 工具** | 终端命令、无 GUI | 终端交互示例（命令 + 输出模拟） | 命令格式、参数设计、输出格式、错误提示 |
+| **AI Skills / 对话式产品** | 用户通过自然语言与 AI 交互 | 对话流程图 + 示例对话脚本 | 对话步骤、AI 提问策略、产出物格式 |
+| **库 / SDK** | 被其他程序调用 | API 使用示例（代码片段） | 公开接口、参数设计、返回值、错误码 |
+| **移动应用** | 手机端 UI | HTML 页面（移动视口） | 手势交互、导航模式、离线状态 |
+| **混合型** | 多种交付物组合 | 按交付物分别选择对应形式 | 各交付物间的交互衔接 |
+
+## 执行步骤
+
+### Step 1: 读取需求文档，识别产品类型
+
+读取 Phase 1 需求文档，提取：
+- 场景清单（`S01`, `S02`...）及优先级
+- 约束与边界 → 判断产品类型
+- `logos-project.yaml` 的 `tech_stack` → 确认技术形态
+
+输出产品类型判断和原型策略选择理由。
+
+### Step 2: 设计信息架构
+
+根据产品类型设计不同层面的架构：
+
+- **Web 应用**：页面结构、导航层级、路由设计
+- **CLI 工具**：命令树结构、子命令层级、全局选项
+- **AI Skills**：Skill 触发关系、对话步骤编排、产出物依赖链
+- **库 / SDK**：模块结构、公开 API 分组
+
+### Step 3: 逐场景细化交互规格
+
+为每个场景定义完整的交互细节（格式见下方示例）。不同产品类型侧重不同的交互维度。
+
+### Step 4: 补充交互级验收条件
+
+在 Phase 1 的 GIVEN/WHEN/THEN 基础上，细化到交互元素级别。
+
+### Step 5: 生成原型
+
+根据产品类型生成对应形式的原型（见示例）。
+
+### Step 6: 输出产品设计文档
+
+按场景组织，每个场景包含交互规格 + 对应原型。
+
+## 场景展开示例
+
+### Web 应用示例
+
+```markdown
+### S01: 邮箱注册 — 交互规格
+
+**涉及页面**：注册页、邮件验证等待页、验证成功页
+
+**交互流程**：
+1. 用户在首页点击「注册」→ 跳转注册页
+2. 注册页包含：邮箱输入框、密码输入框、确认密码输入框、注册按钮
+3. 实时校验：邮箱格式、密码长度 ≥ 8、两次密码一致
+4. 提交成功 → 跳转邮件验证等待页
+
+#### 验收条件（交互级）
+
+##### 正常：成功注册
+- **GIVEN** 用户在注册页面，所有字段为空
+- **WHEN** 用户填写 test@example.com、密码 "Pass1234"、确认密码 "Pass1234"，点击「注册」按钮
+- **THEN** 「注册」按钮变为 loading 状态，1-3 秒后跳转到邮件验证等待页
+```
+
+**原型**：`01-register-prototype.html`（可交互的 HTML 页面）
+
+### CLI 工具示例
+
+````markdown
+### S01: CLI 初始化项目 — 交互规格
+
+**命令格式**：`openlogos init [name]`
+
+**参数设计**：
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| name | string | 否 | 当前目录名 | 项目名称 |
+
+**交互流程**：
+1. 用户在终端运行 `openlogos init my-project`
+2. CLI 检查 `logos/logos.config.json` 是否已存在
+3. 不存在 → 创建目录结构，逐行输出创建的文件清单
+4. 存在 → 输出错误提示并退出
+
+**终端输出模拟**：
+
+正常路径：
+```
+$ openlogos init my-project
+
+Creating OpenLogos project structure...
+
+  ✓ logos/resources/prd/1-product-requirements/
+  ✓ logos/resources/prd/2-product-design/
+  ✓ logos/resources/prd/3-technical-plan/1-architecture/
+  ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/
+  ✓ logos/resources/api/
+  ✓ logos/resources/database/
+  ✓ logos/resources/scenario/
+  ✓ logos/changes/
+  ✓ logos/logos.config.json
+  ✓ logos/logos-project.yaml
+  ✓ AGENTS.md
+  ✓ CLAUDE.md
+
+Project initialized. Next steps:
+  1. Edit logos/logos.config.json to configure your project
+  2. Start with Phase 1: tell AI "帮我写需求文档"
+  3. Run `openlogos status` to check progress at any time
+```
+
+错误路径：
+```
+$ openlogos init
+Error: logos/logos.config.json already exists in current directory.
+This directory has already been initialized as an OpenLogos project.
+```
+
+#### 验收条件（交互级）
+
+##### 正常：全新项目
+- **GIVEN** 当前目录无 `logos/logos.config.json`
+- **WHEN** 用户运行 `openlogos init my-project`
+- **THEN** 终端逐行输出创建的 12 个文件/目录，最后输出 "Next steps" 引导，退出码为 0
+
+##### 异常：已初始化
+- **GIVEN** 当前目录已存在 `logos/logos.config.json`
+- **WHEN** 用户运行 `openlogos init`
+- **THEN** 终端输出红色错误提示，不创建任何文件，退出码为 1
+````
+
+**原型**：`01-init-terminal.md`（终端交互模拟文档）
+
+### AI Skills / 对话式产品示例
+
+```markdown
+### S02: AI 辅助写需求文档 — 交互规格
+
+**触发方式**：用户在 AI 编程工具中输入自然语言
+
+**对话流程**：
+1. 用户说「帮我写需求文档」
+2. AI 读取 prd-writer Skill
+3. AI 追问：「请先告诉我你的产品定位——这个产品要解决什么人的什么问题？」
+4. 用户描述产品想法
+5. AI 追问：「核心用户是谁？能描述一个具体的人吗？」
+6. 用户描述用户画像
+7. AI 汇总信息，开始输出结构化需求文档
+8. AI 输出后询问：「需求文档初稿已生成，请 review 后告诉我需要修改的地方」
+
+**AI 行为规范**：
+- 追问不超过 3 轮，每轮聚焦 1 个关键信息
+- 如果用户在第一条消息中提供了充分信息，跳过追问直接输出
+- 输出的文档格式严格遵循 prd-writer 规范
+
+#### 验收条件（交互级）
+
+##### 正常：信息充分
+- **GIVEN** 用户在第一条消息中描述了产品定位、目标用户和核心痛点
+- **WHEN** AI 开始执行 prd-writer Skill
+- **THEN** AI 直接输出结构化需求文档，不进行追问
+
+##### 正常：信息不足
+- **GIVEN** 用户只说了「帮我写需求文档」
+- **WHEN** AI 开始执行 prd-writer Skill
+- **THEN** AI 追问产品定位（第 1 轮）→ 用户回答 → AI 追问目标用户（第 2 轮）→ 用户回答 → AI 输出需求文档
+```
+
+**原型**：`02-prd-writer-dialogue.md`（对话流程脚本）
+
+## 输出规范
+
+- 功能规格：`logos/resources/prd/2-product-design/1-feature-specs/`
+- 原型：`logos/resources/prd/2-product-design/2-page-design/`
+- 设计文档与原型成对出现：`{序号}-{名称}-design.md` + `{序号}-{名称}-prototype.{ext}`
+  - Web 应用：`.html`
+  - CLI 工具：`-terminal.md`（终端交互模拟）
+  - AI Skills：`-dialogue.md`（对话流程脚本）
+  - 库 / SDK：`-api-examples.md`（使用示例）
+- **场景编号必须与 Phase 1 一致**，如需拆分使用子编号（`S01.1`）
+
+## 实践经验
+
+- **场景是骨架**：不要按"页面"或"命令"组织文档，按"场景"组织
+- **Phase 1 的验收条件是输入**：Phase 2 不是重写验收条件，而是在 Phase 1 的基础上细化到交互元素级别
+- **子场景拆分要有理由**：只在 Phase 1 的场景确实包含两条独立的交互路径时才拆分
+- **CLI 的"原型"是终端输出模拟**：不需要 HTML，用代码块模拟终端的输入输出即可
+- **AI Skills 的"原型"是对话脚本**：模拟用户和 AI 的多轮对话，明确 AI 在每个节点的行为
+- **混合型产品按场景分**：同一个产品中 CLI 场景用终端模拟、Web 场景用 HTML，不需要统一形式
+- **Markdown 嵌套代码块**：当文档内容本身包含 ` ``` ` 代码围栏时（如对话脚本中 AI 输出代码片段、终端模拟中嵌套命令输出），**外层围栏必须使用 4 个反引号**（` ```` `），内层保持 3 个。这是 Markdown 标准语法，避免解析器误判层级导致格式错乱。上方 CLI 工具示例已体现此规则
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `基于需求文档做产品设计`
+- `帮我设计 S01 的交互流程和原型`
+- `帮我把所有场景的产品设计做出来`
+- `帮我设计 CLI 命令的交互流程`
+- `帮我设计 AI Skill 的对话流程`

package/skills/project-init/SKILL.md

@@ -0,0 +1,163 @@
+# Skill: Project Init
+
+> 初始化一个遵循 OpenLogos 方法论的项目结构，生成配置文件、AI 指令文件和标准目录。
+
+## 触发条件
+
+- 用户要求创建新项目或初始化项目结构
+- 用户提到 "openlogos init" 或 "初始化项目"
+- 当前目录下没有 `logos/logos.config.json`
+
+## 核心能力
+
+1. 创建 `logos/` 目录及其标准子结构
+2. 生成 `logos/logos.config.json` 配置文件
+3. 生成 `logos/logos-project.yaml` AI 协作索引
+4. 生成 `AGENTS.md` / `CLAUDE.md` AI 指令文件（根目录）
+5. 创建 `logos/changes/` 变更管理目录
+
+## 执行步骤
+
+### Step 1: 收集项目信息
+
+向用户确认以下信息：
+
+- **项目名称**：用于 `logos/logos.config.json` 的 `name` 字段
+- **项目描述**：一句话描述
+- **技术栈**：主框架、语言、数据库、部署平台
+- **文档模块**：除默认的 prd/api/scenario/database 外，是否需要额外模块
+
+如果用户没有提供，使用合理的默认值。
+
+### Step 2: 创建目录结构
+
+```
+project-root/
+└── logos/
+    ├── resources/
+    │   ├── prd/
+    │   │   ├── 1-product-requirements/
+    │   │   ├── 2-product-design/
+    │   │   │   ├── 1-feature-specs/
+    │   │   │   └── 2-page-design/
+    │   │   └── 3-technical-plan/
+    │   │       ├── 1-architecture/
+    │   │       └── 2-scenario-implementation/
+    │   ├── api/
+    │   ├── database/
+    │   └── scenario/
+    └── changes/
+```
+
+### Step 3: 生成 logos/logos.config.json
+
+```json
+{
+  "name": "{项目名称}",
+  "description": "{项目描述}",
+  "documents": {
+    "prd": {
+      "label": { "en": "Product Docs", "zh": "产品文档" },
+      "path": "./resources/prd",
+      "pattern": "**/*.{md,html,htm,pdf}"
+    },
+    "api": {
+      "label": { "en": "API Docs", "zh": "API 文档" },
+      "path": "./resources/api",
+      "pattern": "**/*.{yaml,yml,json}"
+    },
+    "scenario": {
+      "label": { "en": "Scenarios", "zh": "业务场景" },
+      "path": "./resources/scenario",
+      "pattern": "**/*.json"
+    },
+    "database": {
+      "label": { "en": "Database", "zh": "数据库" },
+      "path": "./resources/database",
+      "pattern": "**/*.sql"
+    }
+  }
+}
+```
+
+> `path` 字段相对于 `logos.config.json` 自身所在目录（即 `logos/`），因此 `./resources/prd` 指向 `logos/resources/prd`。
+
+### Step 4: 生成 logos/logos-project.yaml
+
+```yaml
+project:
+  name: "{项目名称}"
+  description: "{项目描述}"
+  methodology: "OpenLogos"
+
+tech_stack:
+  framework: "{用户提供的框架}"
+  language: "{用户提供的语言}"
+  # ... 根据用户提供的信息填充
+
+resource_index: []
+  # 初始为空，随着文档产出逐步添加
+
+conventions:
+  - "遵循 OpenLogos 三层推进模型（Why → What → How）"
+  - "每次变更必须先创建 logos/changes/ 变更提案"
+```
+
+### Step 5: 生成 AGENTS.md（根目录）
+
+根据 Step 3 和 Step 4 的内容生成 AGENTS.md，放在**项目根目录**：
+
+```markdown
+# AI Assistant Instructions
+
+This project follows the **OpenLogos** methodology.
+Read `logos/logos-project.yaml` first to understand the project resource index.
+
+## Project Context
+- Config: `logos/logos.config.json`
+- Resource Index: `logos/logos-project.yaml`
+- Tech Stack: {从 logos-project.yaml 提取}
+
+## Methodology Rules
+1. Never write code without first completing the design documents
+2. Follow the Why → What → How progression
+3. All API designs must originate from scenario sequence diagrams
+4. All code changes must have corresponding API orchestration tests
+5. Use the Delta change workflow for iterations (see logos/changes/ directory)
+
+## Conventions
+{从 logos-project.yaml 的 conventions 提取}
+```
+
+同时生成 `CLAUDE.md`，内容与 AGENTS.md 一致。
+
+### Step 6: 输出初始化报告
+
+向用户报告创建了哪些文件和目录，并给出下一步建议：
+
+1. 编辑 `logos/logos.config.json` 完善项目配置
+2. 从 Phase 1 开始：编写需求文档
+3. 使用 `prd-writer` Skill 辅助撰写
+
+## 输出规范
+
+- `logos/logos.config.json`：有效的 JSON，符合 `spec/logos.config.schema.json`
+- `logos/logos-project.yaml`：有效的 YAML
+- `AGENTS.md` / `CLAUDE.md`：Markdown 格式，位于项目根目录
+- `logos/` 下所有目录已创建，空目录包含 `.gitkeep`
+
+## 实践经验
+
+- **不要过度配置**：初始化时保持最少配置，让用户在使用过程中逐步完善
+- **resource_index 初始为空**：随着文档产出再添加条目，避免生成无意义的占位内容
+- **AGENTS.md 保持简洁**：只包含项目特有的信息，通用的方法论规则使用固定模板
+- **优先创建目录结构**：`logos/` 目录结构是方法论落地的第一步，比任何文档都重要
+- **低侵入**：所有方法论资产收纳在 `logos/` 内，不污染项目自身结构
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我初始化 OpenLogos 项目`
+- `用 OpenLogos 初始化这个项目，项目名叫 xxx`
+- `帮我给现有项目接入 OpenLogos`

package/skills/scenario-architect/SKILL.md

@@ -0,0 +1,214 @@
+# Skill: Scenario Architect
+
+> 将 Phase 1/2 已定义的业务场景展开为技术时序图，让 API 设计自然浮现，并设计完整的异常用例。场景编号沿用 Phase 1 定义。
+
+## 触发条件
+
+- 用户要求画时序图、设计业务场景或进行场景建模
+- 用户提到 "Phase 3 Step 1"、"场景驱动"、"技术方案设计"
+- 已有需求文档和产品设计文档（含场景定义），需要开始技术实现
+- 用户指定某个场景编号（如 S01）需要展开为时序图
+
+## 核心能力
+
+1. 读取 Phase 1/2 的场景定义和验收条件，作为时序图的输入
+2. 为每个场景绘制 Mermaid 时序图（严格遵循编号规范）
+3. 为关键步骤撰写说明文字（解释"为什么"而非"做什么"）
+4. 识别每个步骤的异常情况，设计结构化的异常用例
+5. 生成场景概览文档（场景地图 + 场景索引）
+
+## 与 Phase 1/2 的衔接
+
+**Phase 3 不再从零识别场景。** 场景在 Phase 1 已定义（`S01`, `S02`...），Phase 2 已细化交互流程，Step 0 已确定技术架构和选型。Phase 3 Step 1 的工作是将同一个场景从"交互视角"展开为"技术视角"，时序图的参与方应与架构图中的系统组件一致：
+
+| 输入（来自 Phase 1/2） | 输出（Phase 3） |
+|------------------------|----------------|
+| 场景编号和名称 | 时序图标题保留编号 |
+| 触发条件 | 时序图的起始箭头 |
+| 主路径描述 | 时序图的 Step 序列 |
+| GIVEN/WHEN/THEN（业务级） | 时序图步骤的行为描述 |
+| 异常验收条件 | EX 异常用例（技术级） |
+| 涉及的页面和交互（Phase 2） | 参与方识别 |
+
+## 执行步骤
+
+### Step 1: 加载场景上下文
+
+读取 Phase 1 需求文档、Phase 2 产品设计文档和 Phase 3 Step 0 技术架构概要中的场景定义。**不要重新发明场景**——直接沿用已有编号和描述。参与方命名应与架构图中的系统组件保持一致。
+
+确认每个场景的：
+- **场景编号**：沿用 Phase 1 的 `S01`, `S02`...（或 Phase 2 的子场景 `S01.1`）
+- **参与方**：从 Phase 2 的交互流程中识别涉及哪些系统组件
+- **主路径**：从 Phase 1/2 的验收条件中提取正常流程
+- **已知异常**：从 Phase 1/2 的异常验收条件中提取
+
+### Step 2: 绘制时序图
+
+为每个场景绘制 Mermaid 时序图，**严格遵循以下规范**：
+
+**编号规范**：
+- 每个箭头必须带 `Step N:` 编号前缀
+- 编号从 1 开始连续递增
+- 每个箭头附一行行为描述：`HTTP方法 /api/路径 — 一句话说明`
+
+**参与方规范**：
+- 使用短别名：`U`（User/Browser）、`W`（Web/Frontend）、`SB`（Supabase）、`DB`（Database）
+- 每个参与方的全名在 `participant` 声明中注明
+
+**场景编号规范**：
+- 文档标题格式：`S01: 邮箱注册 — 时序图`
+- 一个场景一个文件，编号对应 Phase 1
+
+**格式示例**：
+
+```mermaid
+sequenceDiagram
+    participant U as User/Browser
+    participant W as Web (Astro)
+    participant SB as Supabase Auth
+    participant DB as Supabase DB
+
+    U->>W: Step 1: POST /api/auth/register — 提交 {email, password, referral_code?}
+    W->>SB: Step 2: supabase.auth.signUp(email, password, metadata) — 发起用户创建
+    SB-->>W: Step 3: 返回 {user, session} 或 error
+    W->>DB: Step 4: INSERT INTO profiles — 写入用户扩展信息
+    DB-->>W: Step 5: 返回写入结果
+    W-->>U: Step 6: 返回注册结果 + 提示验证邮件
+```
+
+### Step 3: 撰写步骤叙事
+
+在时序图之后，用**连续编号列表**将所有步骤逐一写出来，形成人类可以从头到尾流畅阅读的线性叙事。
+
+**格式规范**：
+
+1. **每一步都必须写出来**——不跳步，不省略。简单步骤一行带过，复杂步骤在下方用 `>` blockquote 补充说明
+2. **每一步必须有明确的主语**——读者不需要猜"这是谁做的"。主语使用参与方表中的别名或全名
+3. **编号与时序图的 Step N 严格对应**
+4. **正常流程和异常用例分开写**——正常流程在前，异常用例在后。正常流程中只在触发异常的步骤后标注 `→ 见 EX-N.M` 引用，不展开异常内容
+
+**正常流程格式示例**：
+
+````markdown
+## 步骤说明
+
+1. **开发者**在终端输入 `openlogos init my-project`。
+2. **CLI** 检查 `logos/logos.config.json` 是否已存在。如果已存在 → 见 EX-2.1。
+3. **CLI** 在终端显示语言选择菜单（1. English / 2. 中文）。如果终端为非 TTY → 见 EX-3.1。
+
+> 语言选择放在 `init` 阶段（而非全局配置），因为这是用户与 OpenLogos 的第一次接触，此时确认语言最自然。
+
+4. **开发者**选择语言（输入 1 或 2）。
+5. **CLI** 从 `package.json` / `Cargo.toml` / `pyproject.toml` / 目录名中探测项目名。如果用户传入的 name 与配置文件名不一致 → 见 EX-5.1。
+
+> 优先级链：命令行参数 > package.json > Cargo.toml > pyproject.toml > 目录名。scoped name 自动去掉 `@org/` 前缀。
+
+6. **CLI** 依次创建 11 个目录（`logos/resources/prd/...` 等），每个目录写入 `.gitkeep`。
+7. **CLI** 写入 `logos/logos.config.json`（含 locale + 5 个文档模块定义）。
+8. **CLI** 写入 `logos/logos-project.yaml`（含空 tech_stack + conventions）。
+9. **CLI** 写入 `AGENTS.md` 和 `CLAUDE.md`（含 Phase detection logic）。
+10. **CLI** 在终端输出创建的文件清单和下一步建议。
+````
+
+**异常用例格式示例**：
+
+````markdown
+## 异常用例
+
+### EX-2.1: 项目已初始化
+
+- **触发条件**：Step 2 检测到 `logos/logos.config.json` 已存在
+- **期望响应**：stderr 输出 `Error: logos/logos.config.json already exists in current directory.`，exit(1)
+- **副作用**：不创建任何文件，不覆盖已有配置
+
+### EX-3.1: 非 TTY 环境
+
+- **触发条件**：Step 3 检测到 `process.stdin.isTTY` 为 false（CI 管道 / 管道输入）
+- **期望响应**：跳过语言选择交互，默认 `locale = 'en'`
+- **副作用**：无，流程直接进入 Step 5
+
+### EX-5.1: 项目名冲突
+
+- **触发条件**：Step 5 中用户传入的 `name` 与 `package.json`（或其他配置文件）中的名称不一致
+- **期望响应**：显示两个选项让用户选择，非 TTY 环境自动使用用户传入的名称
+- **副作用**：无，选择后继续 Step 6
+````
+
+**叙事原则**：
+- **不跳步**：哪怕一个步骤只值一行（如"CLI 写入文件"），也要写出来，保持编号连续
+- **主语先行**：每一步以粗体主语开头，让读者一眼看到"谁在做"
+- **补充说明用 blockquote**：需要解释"为什么"或设计决策时，在步骤下方用 `>` blockquote 展开，不打断阅读节奏
+- **异常用例独立成段**：正常流程中只放 `→ 见 EX-N.M` 引用，异常的触发条件、期望响应、副作用在文档下方的「异常用例」章节展开
+
+### Step 4: 设计异常用例
+
+将 Phase 1/2 中已识别的异常验收条件展开为技术级异常用例，并补充 Phase 1/2 未覆盖的技术异常（如服务不可用、数据库写入失败等）：
+
+```markdown
+#### 异常用例
+
+##### EX-2.1: 邮箱已注册（← Phase 1 S01 异常验收条件）
+- **触发条件**：提交的 email 已存在于 auth.users 表
+- **期望响应**：HTTP 409 `{ code: "EMAIL_EXISTS", message: "邮箱已注册" }`
+- **副作用**：不创建任何记录，不发送邮件
+
+##### EX-2.2: Supabase Auth 服务不可用（技术异常，Phase 1 未覆盖）
+- **触发条件**：Supabase Auth 服务超时或返回 5xx
+- **期望响应**：HTTP 503 `{ code: "AUTH_SERVICE_UNAVAILABLE", message: "认证服务暂时不可用" }`
+- **副作用**：记录错误日志，触发告警
+
+##### EX-4.1: profiles 写入失败（技术异常，Phase 1 未覆盖）
+- **触发条件**：INSERT INTO profiles 违反唯一约束或 RLS 拒绝
+- **期望响应**：HTTP 500 `{ code: "PROFILE_CREATE_FAILED", message: "用户配置创建失败" }`
+- **副作用**：auth.users 中的记录已创建但 profiles 未创建（需要补偿机制）
+```
+
+**异常用例编号规则**：`EX-{步骤编号}.{序号}`
+
+### Step 5: 生成场景概览文档
+
+汇总所有场景的技术实现状态：
+
+```markdown
+# 业务场景概览（技术实现）
+
+## 场景地图
+| 编号 | 场景名称 | Phase 1 | Phase 2 | Phase 3 时序图 | API | 编排 | 状态 |
+|------|---------|---------|---------|--------------|-----|------|------|
+| S01  | 邮箱注册 | ✅ | ✅ | ✅ | ✅ | 🔲 | 进行中 |
+| S02  | 密码登录 | ✅ | ✅ | 🔲 | 🔲 | 🔲 | 待开始 |
+
+## 场景依赖关系
+[说明场景之间的前置/后置关系]
+
+## 场景索引
+[每个场景的文件链接，贯穿三个 Phase]
+```
+
+## 输出规范
+
+- **场景概览**：`logos/resources/prd/3-technical-plan/2-scenario-implementation/00-scenario-overview.md`
+- **场景文档**：`logos/resources/prd/3-technical-plan/2-scenario-implementation/{场景编号}-{场景名}.md`
+- 时序图使用 Mermaid 格式（可在 Markdown 中直接渲染）
+- 异常用例使用 `EX-N.M` 编号，全局唯一
+- 每个场景文档包含：时序图 + 步骤说明 + 异常用例
+- **场景编号必须与 Phase 1/2 一致**
+
+## 实践经验
+
+- **不要从零识别场景**：Phase 3 的场景来自 Phase 1 的需求文档。如果发现了 Phase 1 没有的场景，应该回到 Phase 1 补充
+- **Phase 1/2 的异常是输入**：Phase 1 写的"异常：邮箱已注册"，在 Phase 3 要展开为带 HTTP 状态码和响应体的技术规格
+- **先画主路径再补异常**：不要试图在第一遍就画出所有分支，先把主路径画清楚
+- **异常用例的覆盖策略**：每个涉及外部调用（数据库、第三方服务）的步骤至少 1 个异常用例
+- **步骤编号维护**：当需要在中间插入步骤时，重新编号所有后续步骤，并同步更新所有 EX 引用
+- **参与方粒度**：在微服务架构中，每个服务是一个参与方；在单体应用中，按逻辑层划分（Web、Auth、DB）
+- **时序图是 API 的来源**：时序图中跨系统边界的箭头就是需要设计的 API——如果一个 API 在时序图中找不到出处，它很可能不应该存在
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我画 S01 的时序图`
+- `帮我对所有 P0 场景做场景建模`
+- `帮我给 S03 补充异常用例的时序图`
+- `基于产品设计，帮我做技术场景建模`