@miniidealab/openlogos 0.2.0 → 0.3.0

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,204 @@
+# Skill: Code Reviewer
+
+> 审查 AI 生成的代码，基于 OpenLogos 全链路规格（API YAML、时序图 EX 用例、DB DDL）进行系统性校验，确保代码与设计文档完全一致，覆盖所有异常路径，满足安全要求。
+
+## 触发条件
+
+- 用户要求审查代码或 Code Review
+- 用户提到 "Phase 3 Step 4"、"代码审核"、"代码审查"
+- AI 刚生成了一段代码，需要验证其质量
+- 部署前的最终检查
+- 编排测试失败后需要定位代码问题
+
+## 前置依赖
+
+- `logos/resources/api/` 中包含 API YAML 规格
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图（含 EX 用例）
+- `logos/resources/database/` 中包含 DB DDL
+- 待审查的代码已可读取
+
+无 API 的项目（纯 CLI / 库）可省略 API 一致性检查，聚焦时序图覆盖和异常处理。
+
+## 核心能力
+
+1. 校验代码实现与 API YAML 规格的一致性
+2. 检查异常处理是否覆盖所有 EX 用例
+3. 检查 DB 操作是否符合 DDL 设计
+4. 检查安全策略（认证、RLS、输入校验）
+5. 检查代码风格和最佳实践
+6. 输出结构化的审查报告
+
+## 执行步骤
+
+### Step 1: 加载规格上下文
+
+读取以下文件，建立代码审查的"参照基准"：
+
+- **API YAML**（`logos/resources/api/*.yaml`）：提取端点清单，记录每个端点的路径、方法、请求体 schema、响应 schema、状态码
+- **场景时序图**（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）：提取所有 EX 异常用例编号和预期行为
+- **DB DDL**（`logos/resources/database/`）：提取表结构、字段类型、约束、索引
+- **`logos-project.yaml`**：读取 `tech_stack` 确认技术栈，`external_dependencies` 确认外部依赖
+
+汇总为审查检查清单：
+
+```markdown
+审查范围：S01 相关代码
+- API 端点：4 个（auth.yaml）
+- EX 异常用例：7 个（EX-2.1 ~ EX-5.2）
+- DB 表：2 张（users, profiles）
+- 安全策略：RLS 2 条
+```
+
+### Step 2: API 一致性审查
+
+逐个端点对比代码实现与 API YAML 规格：
+
+**检查项**：
+
+| 检查项 | 说明 | 严重程度 |
+|--------|------|---------|
+| 路径匹配 | 代码中的路由路径是否与 YAML 中的 `paths` 完全一致 | Critical |
+| HTTP 方法 | GET/POST/PUT/DELETE 是否匹配 | Critical |
+| 请求体字段 | 代码是否读取了 YAML 中 `requestBody.schema` 定义的所有 required 字段 | Critical |
+| 请求体校验 | 字段类型、format（email/uuid）、minLength 等约束是否在代码中有校验 | Warning |
+| 响应字段 | 代码返回的 JSON 字段名和类型是否与 YAML 中 `responses.schema` 一致 | Critical |
+| 状态码 | 正常和异常情况下返回的 HTTP 状态码是否与 YAML 定义一致 | Critical |
+| 错误响应格式 | 错误响应是否遵循 `{ code, message, details? }` 统一格式 | Warning |
+
+**输出格式**：
+
+```markdown
+### API 一致性
+
+| 端点 | 检查项 | 状态 | 说明 |
+|------|--------|------|------|
+| POST /api/auth/register | 请求体字段 | ✅ | email, password 均已读取 |
+| POST /api/auth/register | 响应状态码 | ❌ Critical | 注册成功返回 200，YAML 定义为 201 |
+| POST /api/auth/register | 错误码 | ❌ Warning | 邮箱重复返回通用 400，YAML 定义为 409 |
+```
+
+### Step 3: 异常处理覆盖审查
+
+将时序图中的所有 EX 异常用例与代码中的错误处理逐一对应：
+
+1. 列出该场景所有 EX 编号及其预期行为
+2. 在代码中查找对应的 try/catch、if/else、error handler
+3. 标注未覆盖的 EX 用例
+
+**检查重点**：
+
+- 每个 EX 用例是否有对应的代码分支
+- 异常情况下是否返回了正确的 HTTP 状态码和错误码
+- 是否有"静默吞掉异常"的情况（catch 块为空或只打日志不返回错误）
+- 外部服务调用（DB、第三方 API）是否都有超时和错误处理
+- 是否存在时序图中没有但代码中多出的异常处理（可能意味着时序图遗漏）
+
+**输出格式**：
+
+```markdown
+### 异常处理覆盖
+
+| EX 编号 | 异常描述 | 代码覆盖 | 说明 |
+|---------|---------|---------|------|
+| EX-2.1 | 邮箱已注册 | ✅ | 返回 409，格式正确 |
+| EX-2.2 | Auth 服务不可用 | ❌ Critical | 无 try/catch 包裹 supabase.auth.signUp 调用 |
+| EX-4.1 | profiles 写入失败 | ❌ Critical | INSERT 失败后未回滚 auth.users 记录 |
+```
+
+### Step 4: DB 操作审查
+
+检查代码中的数据库操作是否符合 DDL 设计：
+
+**检查项**：
+
+- **表名和列名**：代码中引用的表名/列名是否与 DDL 一致（无拼写错误、大小写差异）
+- **字段类型**：代码中传入的值类型是否与 DDL 定义匹配（如 DDL 中 `INTEGER` 的金额字段，代码是否传入分值而非元）
+- **约束遵守**：NOT NULL 字段是否确保有值、UNIQUE 字段是否做了冲突处理、CHECK 约束中的枚举值是否在代码中有对应常量
+- **事务使用**：涉及多表写入的操作是否包裹在事务中
+- **迁移一致**：DDL 中的最新字段是否在代码中已使用（避免 DDL 更新了但代码忘记跟进）
+
+### Step 5: 安全审查
+
+检查代码的安全实现：
+
+| 检查项 | 说明 | 严重程度 |
+|--------|------|---------|
+| 认证检查 | 需认证的端点是否在处理逻辑前验证了 token/session | Critical |
+| 授权检查 | 用户是否只能访问自己的数据（owner check） | Critical |
+| 输入校验 | 用户输入是否做了类型校验和长度限制（防注入、防 XSS） | Critical |
+| 敏感数据 | 响应中是否泄露了密码哈希、内部 ID、堆栈信息 | Critical |
+| RLS 依赖 | 如果依赖 PostgreSQL RLS，代码是否正确设置了 `auth.uid()` 上下文 | Warning |
+| SQL 注入 | 是否使用参数化查询（禁止字符串拼接 SQL） | Critical |
+| 速率限制 | 关键端点（登录、注册）是否有防暴力破解的速率限制 | Warning |
+
+### Step 6: 输出审查报告
+
+按严重程度汇总所有发现，生成结构化报告：
+
+```markdown
+# 代码审查报告：S01 用户注册
+
+## 审查范围
+- 场景：S01
+- 端点：4 个
+- EX 用例：7 个
+- 代码文件：src/api/auth/register.ts, src/api/auth/login.ts
+
+## 审查摘要
+
+| 严重程度 | 数量 |
+|---------|------|
+| 🔴 Critical | 2 |
+| 🟡 Warning | 3 |
+| 🔵 Info | 1 |
+
+## Critical 发现
+
+### [C1] POST /api/auth/register 状态码不匹配
+- **规格来源**：auth.yaml → register → responses.201
+- **问题**：代码返回 200，规格定义为 201
+- **修复建议**：将 `res.status(200)` 改为 `res.status(201)`
+
+### [C2] EX-2.2 未处理：Auth 服务不可用
+- **规格来源**：S01 时序图 → EX-2.2
+- **问题**：`supabase.auth.signUp()` 调用未包裹 try/catch
+- **修复建议**：添加 try/catch，超时或 5xx 时返回 503
+
+## Warning 发现
+...
+
+## Info 发现
+...
+```
+
+**报告原则**：
+- Critical 必须修复后才能进入编排验收
+- Warning 建议修复，但不阻塞交付
+- Info 为改进建议，可后续处理
+- 每条发现都必须引用规格来源（API YAML、EX 编号、DDL）
+
+## 输出规范
+
+- 审查报告直接输出到对话中（不写文件）
+- 按严重程度分类：Critical / Warning / Info
+- 每条发现格式：编号 + 规格来源 + 问题描述 + 修复建议
+- 末尾给出总结和下一步建议（如"修复 2 个 Critical 后可运行编排验收"）
+
+## 实践经验
+
+- **一致性优先**：代码必须与 API YAML 完全一致——字段名、类型、状态码都不能偏差。大部分线上 Bug 来自代码和规格的微妙不一致
+- **异常处理是重点**：大部分 Bug 都出在异常路径上，仔细检查每个 EX 用例是否有对应的 catch/error handler
+- **安全不打折**：认证检查、RLS 策略、输入校验，任何一项缺失都是 Critical
+- **不要过度审查**：代码风格问题标记为 Info，不阻塞交付。审查的核心目标是"代码与规格一致"，不是"代码完美"
+- **审查前先跑一遍**：如果代码能跑起来，先运行一次编排测试，用失败的 case 反向定位问题，比逐行看代码高效
+- **关注补偿逻辑**：多步写入（如先创建 auth user 再写 profile）如果中途失败，是否有回滚或补偿机制——这是最容易遗漏的 Critical 问题
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我做代码审查`
+- `帮我检查这段代码是否符合 API YAML 规格`
+- `Review 一下 S01 相关的代码实现`
+- `帮我检查异常处理是否完整`
+- `帮我检查安全策略是否到位`

package/skills/db-designer/SKILL.md

@@ -0,0 +1,212 @@
+# Skill: DB Designer
+
+> 从 API 规格推导数据库表结构，生成对应方言的 SQL DDL。数据库类型由 Phase 3 Step 0 技术选型确定，确保字段类型、约束、索引和安全策略与 API 端点完全对齐。
+
+## 触发条件
+
+- 用户要求设计数据库或编写 SQL
+- 用户提到 "Phase 3 Step 2"、"DB 设计"、"表结构"
+- 已有 API YAML 规格，需要推导数据库设计
+- 用户提供了数据模型需要转化为 DDL
+
+## 核心能力
+
+1. 从 API 请求/响应结构推导表结构
+2. 读取 `logos-project.yaml` 的 `tech_stack.database` 确定数据库类型
+3. 生成对应数据库方言的 SQL DDL
+4. 设计索引并说明设计理由
+5. 设计安全策略（RLS / 应用层权限）
+6. 为每张表、每个字段添加注释
+
+## 前置依赖
+
+- `logos/resources/api/` 中包含 API YAML 规格（api-designer 产出）
+- `logos-project.yaml` 的 `tech_stack.database` 已填写
+
+如果 API 目录为空，提示用户先完成 Phase 3 Step 2 的 API 设计（api-designer）。如果 `tech_stack.database` 未填写，提示用户先完成 Phase 3 Step 0（architecture-designer）。
+
+## 执行步骤
+
+### Step 1: 确认数据库类型
+
+读取 `logos/logos-project.yaml` 的 `tech_stack` 字段，确定数据库类型和方言：
+
+- PostgreSQL → 使用 UUID、TIMESTAMPTZ、RLS、JSONB 等特性
+- MySQL → 使用 InnoDB、utf8mb4、TIMESTAMP 等特性
+- SQLite → 使用 INTEGER PRIMARY KEY、TEXT 等简化类型
+- 其他 → 与用户确认后选择最接近的方言
+
+### Step 2: 提取数据实体
+
+从 API YAML 中提取所有需要持久化的数据实体：
+
+1. 扫描所有端点的 `requestBody` 和 `responses`，识别核心数据对象
+2. 区分"需要持久化"与"仅传输用"的数据：
+   - 有 CRUD 操作的对象 → 需要建表（如 `users`、`projects`）
+   - 只出现在请求/响应中但不直接存储的 → 不建表（如 `loginRequest`）
+3. 为每个对象标注来源 API 端点
+
+输出实体清单供用户确认：
+
+```markdown
+从 API 规格中识别到 N 个需要持久化的数据实体：
+
+| # | 实体 | 来源端点 | 核心字段 |
+|---|------|---------|---------|
+| 1 | users | auth.yaml → register, login | email, password, status |
+| 2 | projects | projects.yaml → create, list, get | name, description, owner_id |
+| 3 | subscriptions | billing.yaml → subscribe | plan, status, expires_at |
+```
+
+### Step 3: 设计表结构
+
+为每个实体设计完整的表结构，遵循当前数据库方言：
+
+**每张表必须包含**：
+- 主键（UUID 或自增 ID，视方言决定）
+- 业务字段（从 API schema 映射，类型转换为数据库类型）
+- 审计字段：`created_at`、`updated_at`
+- 软删除字段：`deleted_at`（按需）
+- 字段约束：`NOT NULL`、`UNIQUE`、`CHECK`、`DEFAULT`
+
+**类型映射原则**：
+- API `string + format: email` → `TEXT NOT NULL`（配合 CHECK 约束或应用层校验）
+- API `string + format: uuid` → `UUID`（PostgreSQL）/ `CHAR(36)`（MySQL）
+- API `integer` → `INTEGER` / `BIGINT`
+- API `boolean` → `BOOLEAN`（PostgreSQL）/ `TINYINT(1)`（MySQL）
+- API `string + enum` → `TEXT + CHECK` 约束（列出枚举值）
+- 金额字段 → `INTEGER`（存分值），**禁止 DECIMAL/FLOAT**
+
+**示例（PostgreSQL）**：
+
+```sql
+-- 用户表（来源：auth.yaml → register, login）
+CREATE TABLE users (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email       TEXT NOT NULL UNIQUE,
+  password    TEXT NOT NULL,
+  status      TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending', 'active', 'disabled')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Step 4: 设计表间关联
+
+根据 API 中的实体关系设计外键：
+
+1. 从 API 端点的嵌套路径和引用字段推导关联（如 `/api/projects/:projectId/members` → `project_members` 表关联 `projects` 和 `users`）
+2. 确定关联类型（一对多、多对多）
+3. 设计外键约束和级联策略：
+   - `ON DELETE CASCADE`：父记录删除时子记录跟随删除（如用户删除 → 项目删除）
+   - `ON DELETE SET NULL`：父记录删除时子记录保留但外键置空
+   - `ON DELETE RESTRICT`：父记录有子记录时禁止删除
+
+### Step 5: 设计安全策略
+
+根据数据库类型设计对应的安全机制：
+
+**PostgreSQL — 行级安全（RLS）**：
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY projects_owner_policy ON projects
+  USING (owner_id = auth.uid());
+```
+
+- 所有包含用户数据的表启用 RLS
+- 为每张表设计至少一条 Policy（owner / admin / public）
+- 注明 RLS 策略与 API 认证方案的对应关系
+
+**MySQL — 应用层权限**：
+
+- 在表注释中标注数据访问权限（owner-only / admin / public）
+- 不在 DDL 中实现权限控制，交由应用层处理
+
+### Step 6: 设计索引
+
+为常见查询模式设计索引，每个索引附设计理由：
+
+```sql
+-- 用户按邮箱查找（登录场景，来源 S02）
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- 项目按 owner 查找（项目列表，来源 S04 Step 1）
+CREATE INDEX idx_projects_owner ON projects(owner_id);
+```
+
+索引设计原则：
+- 外键列：必须建索引（避免 JOIN 全表扫描）
+- 唯一约束列：自动创建唯一索引
+- 高频查询列：根据 API 的查询参数判断
+- 复合索引：多条件查询时考虑（最左前缀原则）
+- 不过度索引：写多读少的表控制索引数量
+
+### Step 7: 输出完整 DDL
+
+按以下顺序组织 DDL 文件：
+
+1. 文件头注释（来源、数据库类型、生成时间）
+2. 基础表（无外键依赖的表先建）
+3. 关联表（有外键依赖的表后建）
+4. 索引
+5. 安全策略（RLS / Policy）
+6. 表和字段注释（PostgreSQL 使用 `COMMENT ON`）
+
+每段 DDL 上方用注释标注来源 API 端点。
+
+## 输出规范
+
+- 文件格式：SQL（方言由 `tech_stack.database` 决定）
+- 存放位置：`logos/resources/database/`
+- 单文件输出：`schema.sql`（简单项目）；或按领域分文件：`auth.sql`、`billing.sql`（复杂项目）
+- 每张表必须有注释（PostgreSQL: `COMMENT ON TABLE`；MySQL: `COMMENT = '...'`）
+- 每个字段必须有注释（PostgreSQL: `COMMENT ON COLUMN`；MySQL: 字段定义后 `COMMENT '...'`）
+- 每段 DDL 上方用 SQL 注释标注来源 API 端点
+
+## 数据库方言差异速查
+
+| 特性 | PostgreSQL | MySQL |
+|------|-----------|-------|
+| UUID 主键 | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` 或使用 `BINARY(16)` |
+| 时间类型 | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP`（注意时区处理） |
+| JSON 支持 | `JSONB`（可索引） | `JSON`（功能受限） |
+| 行级安全 | RLS (`ENABLE ROW LEVEL SECURITY`) | 不支持，需在应用层实现 |
+| 表注释 | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` |
+| 字段注释 | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` |
+
+## 实践经验
+
+### 通用（所有数据库）
+
+- **金额一律 INTEGER 存分值**：禁止 DECIMAL/FLOAT，避免浮点精度问题
+- **软删除**：优先使用 `deleted_at` 时间字段而非物理删除
+- **审计字段**：每张表包含 `created_at` 和 `updated_at`
+- **时间字段带时区**：避免时区陷阱
+- **字段名与 API 一致**：DB 列名尽量与 API YAML 中的字段名对齐（如 API 用 `userId` → DB 用 `user_id`，映射规则明确即可），减少代码层的无谓转换
+- **先出核心表再补辅助表**：不要试图一次设计所有表——先输出核心业务表让用户 review，再补充辅助表
+
+### PostgreSQL 特有
+
+- **主键**：`id UUID DEFAULT gen_random_uuid() PRIMARY KEY`
+- **时间类型**：使用 `TIMESTAMPTZ`
+- **RLS**：所有表启用 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY;`
+- **JSONB**：需要非结构化存储时优先使用 JSONB 并建 GIN 索引
+
+### MySQL 特有
+
+- **主键**：`id CHAR(36) DEFAULT (UUID()) PRIMARY KEY` 或自增 BIGINT
+- **时间类型**：使用 `TIMESTAMP`（自动时区转换）或 `DATETIME`（原样存储）
+- **字符集**：建表时指定 `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`
+- **引擎**：一律使用 `ENGINE=InnoDB`
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计数据库`
+- `基于 API 规格帮我推导数据库 DDL`
+- `帮我设计 S01 涉及的数据库表`
+- `帮我给现有表结构补充索引和 RLS 策略`

package/skills/merge-executor/SKILL.md

@@ -0,0 +1,84 @@
+# Skill: Merge Executor
+
+> 读取 CLI 生成的 MERGE_PROMPT.md 指令文件，将变更提案中的 delta 文件逐个合并到主文档，确保变更准确落地。
+
+## 触发条件
+
+- 用户运行完 `openlogos merge <slug>` 后要求 AI 执行合并
+- 用户提到"执行合并"、"merge"、"把 delta 合进主文档"
+- 用户提到"读取 MERGE_PROMPT.md 并执行"
+
+## 前置依赖
+
+1. `logos/changes/<slug>/MERGE_PROMPT.md` 存在（由 `openlogos merge` 命令生成）
+2. MERGE_PROMPT.md 中引用的 delta 文件和目标主文档均存在
+
+如果 MERGE_PROMPT.md 不存在，提示用户先运行 `openlogos merge <slug>`。
+
+## 核心能力
+
+1. 解析 MERGE_PROMPT.md 中的合并指令
+2. 逐个读取 delta 文件，理解 ADDED / MODIFIED / REMOVED 标记
+3. 精准定位主文档中的对应章节并执行合并
+4. 保持主文档的格式和风格一致性
+5. 输出变更摘要
+
+## 执行步骤
+
+### Step 1: 读取合并指令
+
+读取 `logos/changes/<slug>/MERGE_PROMPT.md`，解析出：
+- 变更提案名称和概述
+- 每个 delta 文件的路径、对应的目标主文档路径、操作类型
+
+### Step 2: 逐个 Delta 文件执行合并
+
+按 MERGE_PROMPT.md 中列出的顺序，逐个处理 delta 文件：
+
+1. **读取 delta 文件**：理解 ADDED / MODIFIED / REMOVED 标记及内容
+2. **读取目标主文档**：定位需要修改的章节
+3. **执行合并**：
+   - `ADDED`：在主文档的指定位置插入新内容
+   - `MODIFIED`：替换主文档中同名章节的内容
+   - `REMOVED`：从主文档中删除对应章节
+4. **输出摘要**：列出对该文件做了哪些修改
+
+### Step 3: 输出总体变更报告
+
+所有 delta 处理完毕后，输出：
+
+```
+合并完成：
+- [文件路径 1]：新增 x 节，修改 y 节，删除 z 节
+- [文件路径 2]：...
+
+请确认修改无误后，运行 `openlogos archive <slug>` 归档提案。
+```
+
+## 合并原则
+
+1. **保持格式一致**：合并后的内容必须与主文档的现有格式、缩进、标题层级保持一致
+2. **不改动无关内容**：只修改 delta 指定的部分，不重新格式化整个文档
+3. **冲突时询问**：如果主文档中找不到 delta 引用的章节（可能已被其他变更修改），暂停并询问用户如何处理
+4. **逐文件确认**：处理完每个 delta 文件后展示修改摘要，等待用户确认后再处理下一个
+
+## 输出规范
+
+- 直接修改 `logos/resources/` 中的主文档（就地编辑）
+- 不修改 `logos/changes/` 中的任何文件
+- 合并过程中不创建新文件（除非 delta 指定新增一个全新的文档）
+
+## 实践经验
+
+- **先全部读完再动手**：先通读所有 delta 文件和目标文档，理解全貌后再逐个合并
+- **MODIFIED 是最容易出错的**：章节标题可能有微小差异（大小写、空格），需要模糊匹配
+- **保留变更痕迹**：如果主文档有"最后更新"时间戳，记得同步更新
+- **delta 的顺序有意义**：需求文档的变更应在 API 文档之前处理，确保上下游一致
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `读取 logos/changes/<slug>/MERGE_PROMPT.md 并执行合并`
+- `帮我把 add-remember-me 的变更合并到主文档`
+- `执行变更合并`

package/skills/prd-writer/SKILL.md

@@ -0,0 +1,171 @@
+# Skill: PRD Writer
+
+> 辅助撰写场景驱动的需求文档——从用户痛点出发，识别核心业务场景，为每个场景定义 GIVEN/WHEN/THEN 验收条件。场景编号将贯穿后续所有阶段。
+
+## 触发条件
+
+- 用户要求写需求文档、产品需求或 PRD
+- 用户讨论产品定位、目标用户、功能需求
+- 用户提到 "Phase 1"、"需求层"、"WHY"
+- 当前处于项目的需求分析阶段
+
+## 核心能力
+
+1. 引导用户梳理产品定位和目标用户
+2. 提炼用户痛点，建立因果链
+3. 从痛点中识别和定义业务场景（分配 `S01`, `S02`... 编号）
+4. 为每个场景编写 GIVEN/WHEN/THEN 验收条件
+5. 排列场景优先级
+6. 识别约束和"不做"清单
+7. 生成符合 OpenLogos 规范的场景驱动需求文档
+
+## 执行步骤
+
+### Step 1: 理解产品定位
+
+与用户确认以下核心问题（如果信息不足则主动追问）：
+
+- **一句话定位**：这个产品是什么？为谁？解决什么问题？
+- **目标用户画像**：具体到可以描述一个真实的人
+- **核心目标**：产品要达成什么，用什么指标衡量成功
+
+### Step 2: 提炼用户痛点
+
+引导用户从以下维度梳理痛点：
+
+- 用户当前是怎么做的？（现状）
+- 做的过程中遇到什么困难？（痛点）
+- 困难导致了什么后果？（影响）
+- 用户期望怎么被解决？（期望）
+
+**每条痛点必须有因果链**：因为 [原因] → 导致 [痛点] → 造成 [后果]
+
+为每条痛点分配编号（`P01`, `P02`...），便于场景追溯。
+
+### Step 3: 识别和定义场景
+
+**场景是贯穿整个研发周期的锚。** 这一步至关重要。
+
+从痛点和需求中提取业务场景。每个场景是一个**完整的用户操作路径**：
+
+- **谁**在**什么情况下**触发
+- 经过**什么步骤**
+- 达到**什么结果**
+
+为每个场景分配全局唯一编号（`S01`, `S02`...），这个编号将一路带到 Phase 2 和 Phase 3。
+
+输出场景清单表：
+
+```markdown
+| 编号 | 场景名称 | 触发条件 | 关联痛点 | 优先级 |
+|------|---------|---------|---------|--------|
+| S01  | 邮箱注册 | 新用户首次访问 | P01 | P0 |
+| S02  | 密码登录 | 已注册用户返回 | P01 | P0 |
+| S03  | 忘记密码 | 用户无法登录 | P02 | P1 |
+```
+
+### Step 4: 编写场景验收条件
+
+为每个 P0 和 P1 场景编写验收条件：
+
+```markdown
+### S01: 邮箱注册
+
+- **触发条件**：新用户首次访问，点击注册
+- **用户价值**：快速创建账号开始使用产品（← P01）
+- **优先级**：P0
+- **主路径**：用户填写邮箱和密码，提交后收到验证邮件，点击验证完成注册
+
+#### 验收条件
+
+##### 正常：完整注册流程
+- **GIVEN** 用户未注册过，且在注册页面
+- **WHEN** 用户填写有效邮箱和密码（≥8位），点击「注册」
+- **THEN** 系统创建账号，发送验证邮件，页面显示「请查收验证邮件」
+
+##### 异常：邮箱已注册
+- **GIVEN** 邮箱 test@example.com 已注册
+- **WHEN** 用户使用 test@example.com 尝试注册
+- **THEN** 显示「该邮箱已注册，请直接登录」，不发送任何邮件
+
+##### 异常：密码不符合要求
+- **GIVEN** 用户在注册页面
+- **WHEN** 用户填写有效邮箱但密码少于 8 位，点击「注册」
+- **THEN** 显示「密码至少 8 位」，不提交请求
+```
+
+**验收条件编写原则**：
+
+- 每个场景至少 1 个正常 + 1 个异常验收条件
+- GIVEN 描述初始状态，要具体到可复现
+- WHEN 描述用户操作，要精确到按钮级别
+- THEN 描述期望行为，要具体到可验证
+- 避免模糊词汇："快速"、"友好"、"合理" → 量化为具体指标
+
+### Step 5: 识别约束和边界
+
+- **技术约束**：技术栈限制、第三方服务限制
+- **资源约束**：团队规模、时间窗口
+- **"不做"清单**：明确列出本阶段不做的功能和场景，避免范围蠕变
+
+### Step 6: 组装需求文档
+
+按标准结构输出完整文档：
+
+```markdown
+# [产品名称] 需求文档
+
+> 最后更新：[日期]
+
+## 一、产品背景与目标
+### 1.1 产品定位
+### 1.2 核心目标
+### 1.3 目标用户画像
+
+## 二、用户痛点分析
+### P01: [痛点名称]
+因为 [原因] → 导致 [痛点] → 造成 [后果]
+### P02: ...
+
+## 三、场景总览
+[场景清单表：编号 / 名称 / 触发条件 / 关联痛点 / 优先级]
+
+## 四、核心场景详述
+### S01: [场景名称]
+[触发条件 + 用户价值 + 优先级 + 主路径 + 验收条件]
+### S02: ...
+
+## 五、约束与边界
+### 5.1 技术约束
+### 5.2 资源与时间约束
+### 5.3 "不做"清单
+```
+
+## 输出规范
+
+- 文件格式：Markdown
+- 存放位置：`logos/resources/prd/1-product-requirements/`
+- 文件命名：`{序号}-{英文名}.md`，如 `01-requirements.md`
+- 每个场景必须可追溯到至少一个用户痛点
+- P0/P1 场景必须有 GIVEN/WHEN/THEN（≥1 正常 + ≥1 异常）
+- 场景编号全局唯一，将贯穿 Phase 2 和 Phase 3
+
+## 实践经验
+
+- **先宽后窄**：第一轮尽可能多地识别场景，然后在优先级排序时砍掉非核心的
+- **场景 ≠ 功能**：一个功能（如"用户认证"）可能包含多个场景（注册、登录、找回密码）；一个场景（如"首次购买"）可能跨多个功能（浏览、加购、支付）。场景是"用户视角的完整路径"
+- **场景粒度**：Phase 1 阶段保持适中粒度。过细（"用户点击输入框"）没有意义，过粗（"用户使用产品"）无法验收。好的粒度是：一个场景能在 1-2 分钟内走完主路径
+- **验收条件是需求的精确表达**：如果写不出 GIVEN/WHEN/THEN，说明场景还没想清楚
+- **异常场景同等重要**：用户不可能总是走正常路径，异常处理往往决定产品体验
+- **"不做"清单是最难写的**：克制是产品经理最重要的能力
+- **场景编号一旦分配不复用**：即使场景被废弃，编号也不回收，避免混淆
+- **需求文档是活文档**：随着产品演进持续更新，通过 Delta 变更管理跟踪每次变化
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我写需求文档`
+- `我要做一个 xxx 产品，帮我梳理需求`
+- `帮我把这些想法整理成结构化的需求文档`
+- `帮我给现有需求文档补充异常场景的验收条件`