@miniidealab/openlogos 0.2.0 → 0.3.0

package/skills/api-designer/SKILL.md

@@ -0,0 +1,209 @@
+# Skill: API Designer
+
+> 基于时序图设计 OpenAPI 3.0+ YAML 规格，让 API 从场景中自然浮现而非凭空定义。每个端点可追溯到时序图的 Step 编号，确保"无场景不设计 API"。
+
+## 触发条件
+
+- 用户要求设计 API 或编写 API 文档
+- 用户提到 "Phase 3 Step 2"、"API 设计"
+- 已有场景时序图，需要细化 API 规格
+- 用户提供了一个 API 端点需要详细设计
+
+## 前置依赖
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图
+- `logos/resources/prd/3-technical-plan/1-architecture/` 中包含架构概要（确认前后端分离方式、认证方案等）
+- `logos-project.yaml` 的 `tech_stack` 已填写
+
+如果时序图目录为空，提示用户先完成 Phase 3 Step 1（scenario-architect）。
+
+## 核心能力
+
+1. 从时序图中提取所有跨系统边界的 API 调用
+2. 去重、合并、按领域分组，形成端点清单
+3. 设计 OpenAPI 3.0+ YAML 规格（路径、参数、请求体、响应结构）
+4. 定义统一的错误响应格式和错误码体系
+5. 设计认证方案（Bearer Token / API Key / Cookie）
+6. 设计分页、排序、过滤的标准化参数
+
+## 执行步骤
+
+### Step 1: 读取场景上下文
+
+读取以下文件建立完整上下文：
+
+- **场景时序图**（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）：提取所有跨系统边界的箭头
+- **架构概要**（`logos/resources/prd/3-technical-plan/1-architecture/`）：确认认证方案、前后端分离方式、API 网关等
+- **`logos-project.yaml`**：读取 `tech_stack` 确认后端框架和部署方式
+
+### Step 2: 提取端点清单
+
+遍历所有场景时序图，收集每个跨系统边界的调用箭头：
+
+1. 识别"跨系统边界"的箭头——客户端到服务端、服务端到外部服务、服务间调用
+2. 为每个箭头提取：HTTP 方法、路径、所属场景编号和 Step 编号
+3. 去重合并——同一个端点可能在多个场景中出现（如 `POST /api/auth/login` 可能在 S02 和 S03 都有）
+4. 输出端点清单摘要供用户确认：
+
+```markdown
+从时序图中识别到 N 个 API 端点：
+
+| # | 方法 | 路径 | 来源场景 | 领域 |
+|---|------|------|---------|------|
+| 1 | POST | /api/auth/register | S01 Step 2 | auth |
+| 2 | POST | /api/auth/login | S02 Step 1 | auth |
+| 3 | GET  | /api/projects | S04 Step 1 | projects |
+```
+
+### Step 3: 按领域分组
+
+将端点按业务领域分组，每组对应一个 YAML 文件：
+
+- `auth.yaml` — 认证相关（注册、登录、登出、重置密码）
+- `projects.yaml` — 核心业务对象的 CRUD
+- `billing.yaml` — 支付和订阅
+
+分组原则：
+- 同一数据实体的操作放在一起
+- 认证/授权独立分组
+- 第三方服务回调（如支付回调）放在对应业务领域
+
+### Step 4: 设计统一约定
+
+在生成具体端点前，先确定全局约定：
+
+**认证方案**（从架构概要中读取）：
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+**统一错误响应**：
+
+```yaml
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: 机器可读的错误码（如 EMAIL_EXISTS）
+        message:
+          type: string
+          description: 人类可读的错误描述
+        details:
+          type: object
+          description: 附加错误信息（如字段级校验错误）
+```
+
+**分页参数**（适用于列表端点）：
+
+```yaml
+parameters:
+  - name: page
+    in: query
+    schema: { type: integer, minimum: 1, default: 1 }
+  - name: per_page
+    in: query
+    schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+```
+
+### Step 5: 逐端点设计详细规格
+
+为每个端点设计完整的 OpenAPI 规格，**逐领域输出**，每完成一个领域暂停让用户 review：
+
+每个端点必须包含：
+- `operationId`：唯一标识符，用于代码生成
+- `summary`：一句话描述
+- `description`：标注来源时序图步骤（如 `来源：S01 Step 2 → Step 3`）
+- `requestBody`：包含所有字段的 schema（含 required、类型、校验规则如 minLength/format）
+- `responses`：覆盖正常响应 + 所有已知异常（从时序图的 EX 用例中提取）
+
+**示例**：
+
+```yaml
+paths:
+  /api/auth/register:
+    post:
+      operationId: register
+      summary: 用户注册
+      description: "来源：S01 Step 2 → Step 3"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email: { type: string, format: email }
+                password: { type: string, minLength: 8 }
+      responses:
+        '201':
+          description: 注册成功，发送验证邮件
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId: { type: string, format: uuid }
+                  message: { type: string }
+        '409':
+          description: "邮箱已被注册（EX-2.1）"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: 请求参数校验失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+```
+
+### Step 6: 验证追溯完整性
+
+输出完成后，做一次追溯检查：
+
+1. **正向检查**：每个时序图中的跨系统箭头都有对应的 API 端点
+2. **反向检查**：每个 API 端点的 `description` 都标注了来源 Step
+3. **异常覆盖**：时序图中的每个 EX 用例都有对应的 HTTP 错误响应
+
+如果发现遗漏，补充后再输出最终版本。
+
+## 输出规范
+
+- 文件格式：OpenAPI 3.1 YAML
+- 存放位置：`logos/resources/api/`
+- 按领域分文件：`auth.yaml`、`projects.yaml`、`billing.yaml`
+- 每个文件包含完整的 `openapi`、`info`、`paths`、`components` 段
+- 错误响应统一引用 `$ref: '#/components/schemas/ErrorResponse'`
+- 每个端点的 `description` 必须标注来源时序图步骤
+
+## 实践经验
+
+- **API 从时序图浮现**：如果一个 API 在时序图中找不到出处，它大概率不应该存在。先画时序图再设计 API，而非反过来
+- **路径命名**：RESTful 风格，使用复数名词，`/api/{resource}`
+- **版本前缀**：初期不加版本前缀（`/api/auth/register`），需要版本管理时再加 `/api/v2/`
+- **状态码语义**：严格遵循 HTTP 状态码语义——200 成功、201 创建、400 参数错误、401 未认证、403 无权限、404 不存在、409 冲突、422 校验失败、500 服务错误
+- **幂等设计**：PUT/DELETE 操作必须幂等
+- **敏感数据**：响应中不包含密码、token 等敏感信息的明文
+- **逐领域输出**：不要一次输出所有端点——按领域分批输出，每批让用户 review 后再继续
+- **字段命名一致**：API 中的字段名要与后续 DB 设计中的列名保持一致（或有明确的映射规则），避免代码层出现不必要的字段转换
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计 API`
+- `基于时序图帮我生成 OpenAPI YAML`
+- `帮我设计 S01 相关的 API 规格`
+- `帮我把所有时序图中的跨系统调用提取为 API`

package/skills/architecture-designer/SKILL.md

@@ -0,0 +1,181 @@
+# Skill: Architecture Designer
+
+> 在逐场景的技术实现之前，建立项目的技术全局视图——系统架构、技术选型、部署拓扑和非功能性约束。确保后续的时序图、API 和代码生成在一致的架构约束下进行。
+
+## 触发条件
+
+- 用户要求设计技术架构、做技术选型或规划系统架构
+- 用户提到 "Phase 3 Step 0"、"架构设计"、"技术方案"
+- Phase 2 产品设计文档已完成，需要开始 Phase 3
+- 用户想要确定技术栈或部署方案
+
+## 核心能力
+
+1. 读取 Phase 1 需求文档和 Phase 2 产品设计文档，理解产品全貌
+2. 基于产品复杂度和场景特征，推荐适合的系统架构
+3. 为每项技术选型提供选型理由和替代方案对比
+4. 绘制系统架构图（Mermaid）和部署拓扑图
+5. 更新 `logos-project.yaml` 的 `tech_stack` 字段
+
+## 与 Phase 1/2 的衔接
+
+架构设计是 Phase 2（产品设计）到 Phase 3（技术实现）的桥梁。它的输入来自 Phase 1/2，输出影响 Phase 3 所有后续步骤：
+
+| 输入（来自 Phase 1/2） | 输出（影响 Phase 3 后续步骤） |
+|------------------------|------------------------------|
+| 场景清单和复杂度 | 系统边界划分 → 时序图的参与方 |
+| 非功能性需求（性能、安全） | 技术选型约束 → API 设计决策 |
+| 产品交互方式（Web/Mobile/API） | 前端技术栈 → 原型实现方式 |
+| 数据量和访问模式 | 数据库选型 → DB 设计 |
+| 第三方服务依赖（支付、邮件等） | 集成方式 → 时序图中的外部参与方 |
+
+## 执行步骤
+
+### Step 1: 理解产品全貌
+
+读取以下文档，建立对项目的整体认知：
+
+- **需求文档**（Phase 1）：产品定位、核心场景、约束与边界
+- **产品设计文档**（Phase 2）：信息架构、页面结构、交互复杂度
+- **已有的 `logos-project.yaml`**：当前 `tech_stack` 中是否已有初始选型
+
+重点提取：
+- 核心场景数量和复杂度
+- 是否有实时性需求（WebSocket、SSE）
+- 是否有后台任务（定时任务、消息队列）
+- 第三方服务依赖清单
+- 用户规模预期
+
+### Step 2: 确定系统架构
+
+根据产品复杂度选择架构模式：
+
+**简单项目**（个人 SaaS、工具类产品）：
+- 单体架构 + 单数据库
+- 架构概要可以用一段文字 + 一张简图
+
+**中等项目**（团队 SaaS、多角色系统）：
+- 前后端分离 + 单体后端 + 单数据库
+- 可能需要对象存储、缓存等辅助服务
+
+**复杂项目**（多服务、高并发、多端）：
+- 微服务 / 模块化单体
+- 需要详细的架构决策记录（ADR）
+
+用 Mermaid 绘制系统架构图：
+
+```mermaid
+graph TB
+    subgraph Frontend
+        Web[Web App - Next.js]
+    end
+    subgraph Backend
+        API[API Server - Node.js]
+        Worker[Background Worker]
+    end
+    subgraph Data
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+        S3[Object Storage]
+    end
+    subgraph External
+        Auth[Supabase Auth]
+        Email[SendGrid]
+    end
+
+    Web -->|REST API| API
+    API --> DB
+    API --> Cache
+    API --> S3
+    API --> Auth
+    Worker --> DB
+    Worker --> Email
+```
+
+### Step 3: 技术选型
+
+为每个技术维度给出选型和理由：
+
+```markdown
+| 维度 | 选型 | 理由 | 备选方案 |
+|------|------|------|---------|
+| 语言 | TypeScript | 前后端统一、类型安全 | Go（性能优先时） |
+| 前端框架 | Next.js 15 | SSR + RSC、生态成熟 | Astro（内容站）、Nuxt（Vue 生态） |
+| 后端框架 | Hono | 轻量、边缘优先、TS 原生 | Express（生态）、Fastify（性能） |
+| 数据库 | PostgreSQL | 功能丰富、JSONB、RLS | MySQL（简单场景） |
+| 认证 | Supabase Auth | 开箱即用、RLS 集成 | NextAuth（自托管） |
+| 部署 | Vercel + Supabase | 零运维、自动扩容 | AWS（自主控制） |
+```
+
+**选型原则**：
+- 优先选择团队已熟悉的技术
+- 在无明显差异时，选择社区更大的方案
+- 选型理由必须关联到具体的产品需求或约束
+
+### Step 4: 非功能性约束
+
+明确关键的非功能性要求：
+
+- **性能目标**：核心 API 响应时间、页面加载时间
+- **安全要求**：认证方式、数据加密、CORS 策略
+- **可扩展性**：预期用户规模、数据增长估算
+- **可观测性**：日志、监控、告警方案
+- **开发体验**：本地开发环境、CI/CD 流程
+
+### Step 5: 外部依赖与测试策略
+
+梳理项目的所有外部服务依赖，为每个依赖确定编排测试阶段的隔离策略。此步骤的产出直接影响 Phase 3 Step 3（编排测试）能否顺利执行。
+
+1. 从架构图和时序图参与方中识别外部依赖（邮件、短信、验证码、支付、OAuth 等）
+2. 与用户确认每个依赖的测试策略
+
+可选的测试策略：
+
+| 策略 | 说明 | 典型场景 |
+|------|------|---------|
+| `test-api` | 测试环境提供后门 API | 邮件/短信验证码 |
+| `fixed-value` | 特定测试数据使用固定值 | 测试手机号固定验证码 |
+| `env-disable` | 环境变量关闭该功能 | 图形验证码、滑块 |
+| `mock-callback` | 编排中主动调用模拟回调 | 支付回调、Webhook |
+| `mock-service` | 本地 mock 服务替代 | OAuth Provider |
+
+如果项目没有外部服务依赖（如纯 CLI 工具），可跳过此步骤。
+
+### Step 6: 更新 logos-project.yaml
+
+将确认的技术选型写入 `logos-project.yaml` 的 `tech_stack` 字段，将外部依赖和测试策略写入 `external_dependencies` 字段，确保后续所有 Skill 和 AI 工具都能读取到统一的技术栈和测试约定。
+
+```yaml
+external_dependencies:
+  - name: "邮件服务"
+    provider: "SendGrid"
+    used_in: ["S01-用户注册", "S03-忘记密码"]
+    test_strategy: "test-api"
+    test_config: "GET /api/test/latest-email?to={email}"
+```
+
+## 输出规范
+
+- 架构概要文档：`logos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md`
+- 架构图使用 Mermaid 格式
+- 技术选型使用表格格式，每项必须有理由
+- 更新 `logos-project.yaml` 的 `tech_stack` 和 `external_dependencies` 字段
+- 简单项目允许精简输出（不强制所有章节）
+
+## 实践经验
+
+- **不要过度设计**：独立开发者做 SaaS，单体 + PostgreSQL + Vercel 够用就行，不要上来就微服务
+- **选型理由比选型本身重要**：写清楚"为什么选 X"比"选了 X"更有价值，因为项目演进时需要重新评估
+- **架构图是时序图的前提**：架构图中的系统组件就是后续时序图的参与方，两者必须一致
+- **tech_stack 是 AI 的锚**：后续 AI 生成代码时会读取 `logos-project.yaml` 的 `tech_stack`，选型不准确会导致生成的代码无法使用
+- **非功能性约束宁可先宽后紧**：初期不要定太严格的性能目标，随着实际数据再收紧
+- **测试策略必须在架构阶段决定**：验证码、支付等外部依赖的测试方案如果等到编排测试时才想，往往发现没有预留后门 API，导致编排测试无法全自动执行
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计技术架构`
+- `基于产品设计帮我做技术选型`
+- `帮我画系统架构图`
+- `帮我确定技术栈并更新 logos-project.yaml`

package/skills/change-writer/SKILL.md

@@ -0,0 +1,146 @@
+# Skill: Change Writer
+
+> 辅助填写变更提案——分析变更影响范围，生成结构化的 proposal.md 和按阶段拆解的 tasks.md，确保变更可追溯、影响可控。
+
+## 触发条件
+
+- 用户刚运行完 `openlogos change <slug>` 并希望 AI 帮忙填写提案
+- 用户描述需要修改、新增或删除某个场景/功能
+- 用户提到"变更提案"、"change proposal"、"迭代"、"改需求"
+
+## 前置依赖
+
+1. 项目已初始化（`logos/logos.config.json` 存在）
+2. 变更提案目录已由 CLI 创建（`logos/changes/<slug>/` 存在）
+3. 主文档可读（`logos/resources/` 中有已生效的文档）
+
+如果前置条件不满足，提示用户先运行 `openlogos change <slug>` 创建提案目录。
+
+## 核心能力
+
+1. 理解用户描述的变更意图
+2. 扫描 `logos/resources/` 中的现有文档，定位受影响范围
+3. 根据变更传播规则判断变更类型（需求级 / 设计级 / 接口级 / 代码级）
+4. 生成符合规范的 proposal.md
+5. 按变更类型自动拆解 tasks.md
+
+## 执行步骤
+
+### Step 1: 理解变更意图
+
+与用户确认以下信息（信息不足则追问，最多 2 轮）：
+
+- **变更是什么**：要新增、修改还是删除什么？
+- **变更原因**：为什么要做这个变更？来自需求反馈、Bug 还是优化？
+- **关联场景**：涉及哪些已有场景编号（S01, S02...）？
+
+### Step 2: 分析影响范围
+
+扫描 `logos/resources/` 中的文档，确定影响范围：
+
+1. 读取需求文档（`prd/1-product-requirements/`），检查相关场景定义
+2. 读取产品设计（`prd/2-product-design/`），检查相关功能规格和原型
+3. 读取技术方案（`prd/3-technical-plan/`），检查相关时序图
+4. 读取 API 文档（`api/`），检查相关端点
+5. 读取 DB 文档（`database/`），检查相关表结构
+6. 读取编排测试（`scenario/`），检查相关测试用例
+
+### Step 3: 判断变更类型
+
+参照变更传播规则确定变更类型及最小更新范围：
+
+| 变更类型 | 最少需要更新 |
+|---------|------------|
+| 需求级变更 | 全链路（需求 → 设计 → 架构 → API/DB → 编排 → 代码） |
+| 设计级变更 | 原型 + 场景 + API/DB + 编排 + 代码 |
+| 接口级变更 | API/DB + 编排 + 代码 |
+| 代码级修复 | 代码 + 重新验收 |
+
+### Step 4: 生成 proposal.md
+
+按以下模板生成，写入 `logos/changes/<slug>/proposal.md`：
+
+```markdown
+# 变更提案：[变更名称]
+
+## 变更原因
+[为什么要做这个变更？来源于哪个需求/反馈/Bug？]
+
+## 变更类型
+[需求级 / 设计级 / 接口级 / 代码级]
+
+## 变更范围
+- 影响的需求文档：[列表，精确到文件名和章节]
+- 影响的功能规格：[列表]
+- 影响的业务场景：[场景编号列表]
+- 影响的 API：[端点列表]
+- 影响的 DB 表：[表名列表]
+- 影响的编排测试：[列表]
+
+## 变更概述
+[用 1-3 段话概述具体改什么]
+```
+
+### Step 5: 生成 tasks.md
+
+根据变更类型和影响范围，自动拆解任务清单。只列出需要更新的阶段：
+
+```markdown
+# 实现任务
+
+## Phase 1: 文档变更
+- [ ] 更新需求文档中 S0x 的验收条件
+- [ ] 在场景总览表中新增/修改场景
+
+## Phase 2: 设计变更
+- [ ] 更新功能规格中 S0x 的交互设计
+- [ ] 更新原型
+
+## Phase 3: 技术变更
+- [ ] 更新 S0x 的时序图
+- [ ] 更新 API YAML
+- [ ] 更新 DB DDL
+- [ ] 更新编排测试用例
+- [ ] 实现代码变更
+```
+
+### Step 6: 引导后续操作（链式驱动）
+
+提供一条可直接执行的提示词，让用户一句话启动全部任务的链式执行：
+
+- **需求级 / 设计级变更**（多任务）：建议用户说「按 tasks.md 帮我逐步更新 S0x 的所有受影响文档」
+- **代码级修复**（少任务）：建议用户说「帮我修复 S0x 的 [问题描述] 并重新验收」
+
+链式执行的行为规范：
+1. AI 读取 `tasks.md`，按顺序逐项执行
+2. 每完成一项任务，汇报修改摘要，并自动提示「继续下一项？」
+3. 用户说「继续」或给出调整意见后，执行下一项
+4. 全部任务完成后，提醒用户运行 `openlogos merge <slug>`
+
+**关键原则**：不要让用户手动跟踪任务清单——AI 应主动驱动流程。
+
+## 输出规范
+
+- 文件格式：Markdown
+- 存放位置：`logos/changes/<slug>/`
+- 文件名：`proposal.md` 和 `tasks.md`（覆盖 CLI 生成的模板）
+
+## 实践经验
+
+- **宁可高估影响范围**：漏掉一个环节的更新比多检查一遍更危险
+- **变更类型决定工作量**：帮助用户在动手前理解改一个需求可能需要全链路更新
+- **tasks.md 是执行清单**：每完成一项打一个 `[x]`，方便追踪进度
+- **小变更也走流程**：看似"只改一行 API"的变更，可能影响编排测试和代码
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+**填写提案**：
+- `帮我填写变更提案 <slug>`
+- `我要给 S02 登录场景加一个记住密码功能，帮我分析影响范围`
+- `这个 Bug 修复只涉及代码层，帮我快速写个提案`
+
+**执行任务（提案填写完成后）**：
+- `按 tasks.md 帮我逐步更新 S02 的所有受影响文档`
+- `帮我修复 S02 登录接口的 500 错误并重新验收`