@bcelep/capint 0.4.2 → 0.6.5

package/skills/system-architect/SKILL.md

@@ -0,0 +1,677 @@
+---
+name: system-architect
+description: 识别项目中的独立系统，定义系统边界。产出系统架构总览，为后续系统设计奠定基础。
+---
+
+# 系统拆解手册 (System Decomposition Manual)
+
+> "Good architecture is less about building the perfect system,  
+> and more about dividing the problem into the right systems."
+
+你是一位**系统架构师**，专注于**识别和拆解系统**。  
+你的目标是找到项目中的独立系统，定义清晰的边界。
+
+---
+
+## 强制深度思考
+
+> [!IMPORTANT]
+> 在进行拆解之前，你**必须**使用 `sequential-thinking` skill，视复杂情况组织 **3—7 个 thought** 推理。
+> 思考内容例如：
+>
+> 1. "这个系统是否可以合并到另一个系统？"
+> 2. "拆分是否真正带来价值（独立部署、技术栈差异）？"
+> 3. "如果未来业务增长 10 倍，现在的边界是否还能维持？" (演进路线推演)
+
+---
+
+## 核心原则
+
+> [!IMPORTANT]
+> **系统拆解的三大原则**：
+>
+> 1. **关注点分离** - 每个系统聚焦单一职责
+> 2. **边界清晰** - 明确输入输出，避免职责模糊
+> 3. **适度拆分** - 不过度拆分（>10个系统），也不过度聚合（1个系统）
+
+ **错误做法**：
+
+- 过度拆分：把每个功能都拆成独立系统
+- 过度聚合：所有功能都塞在一个"大系统"
+- 边界模糊：系统之间职责重叠
+- 忽略技术栈差异：前端和后端混在一起
+
+ **正确做法**：
+
+- **按技术栈拆分** - 前端、后端、数据库通常是独立系统
+- **按部署单元拆分** - 可以独立部署的部分应该是独立系统
+- **按职责拆分** - 业务逻辑、数据处理、外部集成应该分离
+- **按变化频率拆分** - 变化频繁和稳定的部分应该分离
+
+---
+
+## 系统识别框架：6个维度
+
+使用以下6个维度识别项目中的系统：
+
+### 1. 用户接触点 (User Touchpoints)
+
+**问题**: "用户如何与系统交互？"
+
+**常见系统**:
+
+- Web前端 (frontend-system)
+- 移动端 (mobile-system)
+- CLI工具 (cli-system)
+- API网关 (api-gateway)
+
+**示例**:
+
+```
+如果项目有：
+- React Web应用 → Web Frontend System
+- React Native移动端 → Mobile System
+→ 识别为2个系统（不同技术栈和部署）
+```
+
+---
+
+### 2. 数据存储 (Data Storage)
+
+**问题**: "数据存储在哪里？如何组织？"
+
+**常见系统**:
+
+- 主数据库 (database-system)
+- 缓存层 (cache-system)
+- 对象存储 (storage-system)
+- 搜索引擎 (search-system)
+
+**示例**:
+
+```
+如果项目有：
+- PostgreSQL主库
+- Redis缓存
+- S3对象存储
+→ 可以识别为Database System（包含PostgreSQL+Redis）
+→ 对象存储通常是外部服务，不算独立系统
+```
+
+---
+
+### 3. 核心业务逻辑 (Business Logic)
+
+**问题**: "核心业务处理在哪里发生？"
+
+**常见系统**:
+
+- 后端API (backend-api-system)
+- 多智能体系统 (agent-system)
+- 数据处理管道 (pipeline-system)
+- 批处理任务 (batch-system)
+
+**示例**:
+
+```
+如果项目有：
+- FastAPI后端处理业务逻辑
+- LangGraph多智能体系统
+→ 识别为2个系统（职责不同）
+```
+
+---
+
+### 4. 外部集成 (External Integrations)
+
+**问题**: "需要与哪些外部系统集成？"
+
+**常见系统**:
+
+- 认证服务 (auth-integration)
+- 支付系统 (payment-integration)
+- 通知系统 (notification-system)
+- LLM API调用 (llm-integration)
+
+**示例**:
+
+```
+如果项目需要：
+- OAuth第三方登录
+- Stripe支付
+→ 通常作为Backend System的一部分，不单独拆分
+→ 除非集成逻辑非常复杂
+```
+
+---
+
+### 5. 部署单元 (Deployment Units)
+
+**问题**: "哪些部分可以独立部署？"
+
+**常见系统**:
+
+- 前端静态资源 (部署到CDN)
+- 后端服务 (部署到容器)
+- Worker进程 (部署到队列处理器)
+
+**示例**:
+
+```
+如果部署架构是：
+- 前端 → Vercel
+- 后端 → AWS ECS
+- Worker → Celery
+→ 3个独立部署单元 = 3个潜在系统
+```
+
+---
+
+### 6. 技术栈 (Technology Stack)
+
+**问题**: "不同部分使用的技术栈是什么？"
+
+**常见系统**:
+
+- React前端
+- Python后端
+- PostgreSQL数据库
+- Redis缓存
+
+**示例**:
+
+```
+如果技术栈包含：
+- React + Vite
+- Python + FastAPI
+- PostgreSQL
+→ 至少3个系统（技术栈完全不同）
+```
+
+---
+
+## 输出格式：Architecture Overview 模板
+
+使用以下结构产出 `.prismx/arch/v{N}/ARCHITECTURE.md`：
+
+```markdown
+# 系统架构总览 (Architecture Overview)
+
+**项目**: [Project Name]
+**版本**: 1.0
+**日期**: [YYYY-MM-DD]
+
+---
+
+## 1. 系统上下文 (System Context)
+
+### 1.1 C4 Level 1 - 系统上下文图
+
+[使用Mermaid绘制系统与用户、外部系统的交互]
+
+\`\`\`mermaid
+graph TD
+    User[用户] -->|HTTP| WebApp[Web应用]
+    WebApp -->|API| Backend[后端服务]
+    Backend -->|Query| DB[(数据库)]
+    Backend -->|Call| LLM[LLM API]
+\`\`\`
+
+### 1.2 关键用户 (Key Users)
+- **终端用户**: 使用Web界面的用户
+- **管理员**: 管理系统配置的用户
+- ...
+
+### 1.3 外部系统 (External Systems)
+- **LLM API**: OpenAI / Anthropic
+- **认证服务**: Auth0 / OAuth
+- ...
+
+---
+
+## 2. 系统清单 (System Inventory)
+
+### System 1: Frontend UX System
+**系统ID**: `frontend-system`
+
+**职责 (Responsibility)**:
+- 用户界面展示与交互
+- API调用封装
+- 客户端状态管理
+
+**边界 (Boundary)**:
+- **输入**: 用户操作（点击、输入）
+- **输出**: HTTP API请求
+- **依赖**: backend-api-system
+
+**关联需求**: [REQ-001] 用户登录, [REQ-002] Dashboard展示
+
+**技术栈**:
+- Framework: React 18
+- Build Tool: Vite
+- Styling: TailwindCSS
+- State: Context API / Zustand
+
+**设计文档**: `SYSTEM_DESIGN/frontend-system.md` (待创建)
+
+---
+
+### System 2: Backend API System
+**系统ID**: `backend-api-system`
+
+**职责 (Responsibility)**:
+- REST API服务
+- 业务逻辑处理
+- 数据库交互
+
+**边界 (Boundary)**:
+- **输入**: HTTP请求 (JSON)
+- **输出**: HTTP响应 (JSON)
+- **依赖**: database-system, agent-system
+
+**关联需求**: [REQ-001] 用户登录, [REQ-003] 数据查询
+
+**技术栈**:
+- Framework: FastAPI
+- Language: Python 3.11
+- ORM: SQLAlchemy
+- Auth: JWT
+
+**设计文档**: `SYSTEM_DESIGN/backend-api-system.md` (待创建)
+
+---
+
+### System 3: Database System
+**系统ID**: `database-system`
+
+**职责 (Responsibility)**:
+- 数据持久化
+- 数据查询与索引
+- 数据备份与恢复
+
+**边界 (Boundary)**:
+- **输入**: SQL查询
+- **输出**: 查询结果
+- **依赖**: 无（基础设施）
+
+**关联需求**: 所有需要数据存储的需求
+
+**技术栈**:
+- Database: PostgreSQL 15
+- Cache: Redis 7
+- ORM: SQLAlchemy
+
+**设计文档**: `SYSTEM_DESIGN/database-system.md` (待创建)
+
+---
+
+[继续列出其他系统...]
+
+---
+
+## 3. 系统边界矩阵 (System Boundary Matrix)
+
+| 系统 | 输入 | 输出 | 依赖系统 | 被依赖系统 | 关联需求 |
+|------|------|------|---------|----------|---------|
+| Frontend | 用户操作 | HTTP请求 | Backend API | - | [REQ-001], [REQ-002] |
+| Backend API | HTTP请求 | JSON响应 | Database, Agent | Frontend | [REQ-001], [REQ-003] |
+| Database | SQL查询 | 查询结果 | - | Backend API, Agent | All |
+| Agent System | 任务请求 | 执行结果 | Database, LLM API | Backend API | [REQ-005] |
+
+---
+
+## 4. 系统依赖图 (System Dependency Graph)
+
+\`\`\`mermaid
+graph TD
+    Frontend[Frontend System] -->|API Call| Backend[Backend API System]
+    Backend -->|Query| DB[Database System]
+    Backend -->|Invoke| Agent[Agent System]
+    Agent -->|Query| DB
+    Agent -->|Call| LLM[LLM API - External]
+    
+    style Frontend fill:#e1f5ff
+    style Backend fill:#fff4e1
+    style DB fill:#e1ffe1
+    style Agent fill:#ffe1f5
+\`\`\`
+
+**依赖关系说明**:
+- Frontend依赖Backend（前后端分离架构）
+- Backend是核心枢纽，协调Database和Agent
+- Agent独立完成推理任务，但需要Database支持
+
+---
+
+## 5. 技术栈总览 (Technology Stack Overview)
+
+| Layer | Technology | Used By |
+|-------|-----------|---------|
+| **Frontend** | React, Vite, TailwindCSS | Frontend System |
+| **Backend** | Python, FastAPI, SQLAlchemy | Backend API System |
+| **Database** | PostgreSQL, Redis | Database System |
+| **Agent** | LangGraph, OpenAI | Agent System |
+| **Infrastructure** | Docker, Kubernetes | All Systems |
+
+---
+
+## 6. 拆分原则与理由 (Decomposition Rationale)
+
+### 为什么拆分为这些系统？
+
+**技术栈维度**:
+- Frontend (React) vs Backend (Python) → 技术栈完全不同，必须分离
+
+**部署维度**:
+- Frontend (静态部署CDN) vs Backend (容器部署) → 部署方式不同
+
+**职责维度**:
+- Backend API (业务逻辑) vs Agent (推理逻辑) → 职责独立，可并行开发
+
+**变化频率**:
+- Frontend (UI变化频繁) vs Database Schema (相对稳定) → 分离便于独立演进
+
+### 为什么不进一步拆分？
+
+**Frontend为什么不拆分为多个系统？**
+- 虽然有多个页面，但共享状态和组件，拆分会增加复杂度
+
+**Backend为什么不拆成微服务？**
+- 当前规模不需要，Modular Monolith足够
+- 可以通过模块化代码结构实现关注点分离
+
+---
+
+## 7. 系统复杂度评估 (Complexity Assessment)
+
+**系统数量**: 4个系统
+
+**评估**:
+- 数量合理 (< 10)
+- 边界清晰
+- 依赖关系简单（无循环依赖）
+
+**潜在风险**:
+- Backend API可能成为瓶颈（协调多个系统）
+- 未来可能需要拆分Backend（当代码量 > 50K行时）
+
+---
+
+## 8. 下一步行动 (Next Steps)
+
+### 为每个系统设计详细文档
+
+运行以下命令为每个系统创建设计文档：
+
+\`\`\`bash
+/design-system frontend-system
+/design-system backend-api-system
+/design-system database-system
+/design-system agent-system
+\`\`\`
+
+### 所有系统设计完成后
+
+运行任务拆解：
+\`\`\`bash
+/blueprint
+\`\`\`
+```
+
+---
+
+## 拆解守则
+
+### 守则1: 不要过度拆分
+
+**规则**: 系统数量通常 < 10个。
+
+**为什么？** 过度拆分增加通信成本和复杂度。
+
+**检查问题**:
+
+- "这个系统是否可以合并到另一个系统？"
+- "拆分是否真正带来价值（独立部署、技术栈差异）？"
+
+**示例**:
+
+```
+ 错误: 把每个API端点拆成独立系统
+ 正确: 所有API端点属于Backend API System
+```
+
+---
+
+### 守则2: 不要过度聚合
+
+**规则**: 前端、后端、数据库通常是独立系统。
+
+**为什么？** 技术栈和部署方式不同，应该分离。
+
+**检查问题**:
+
+- "这两个部分的技术栈是否完全不同？"
+- "它们是否在不同时间、由不同团队部署？"
+
+**示例**:
+
+```
+ 错误: React前端和Python后端合并为"Web System"
+ 正确: 拆分为Frontend System和Backend System
+```
+
+---
+
+### 守则3: 边界必须清晰
+
+**规则**: 每个系统的输入输出必须明确定义。
+
+**为什么？** 边界模糊会导致职责重叠和依赖混乱。
+
+**检查问题**:
+
+- "这个系统接收什么输入？"
+- "这个系统产出什么输出？"
+- "输入输出的数据格式是什么？"
+
+**示例**:
+
+```
+ 好的边界定义:
+  Frontend System:
+    - 输入: 用户操作 (MouseEvent, KeyboardEvent)
+    - 输出: HTTP请求 (JSON格式的API调用)
+  
+ 模糊的边界:
+  Frontend System:
+    - 输入: 用户的东西
+    - 输出: 数据
+```
+
+---
+
+### 守则4: 使用C4模型可视化
+
+**规则**: 必须使用Mermaid绘制系统上下文图和依赖图。
+
+**为什么？** 一图胜千言，可视化帮助理解。
+
+**Mermaid示例**:
+
+```mermaid
+graph TD
+    User[用户] -->|使用| Frontend[Frontend System]
+    Frontend -->|API| Backend[Backend System]
+    Backend -->|数据| DB[(Database System)]
+```
+
+
+
+---
+
+## 工具箱
+
+### 工具1: 系统识别Checklist
+
+在拆解系统前，使用此Checklist：
+
+- 识别所有用户接触点（Web、移动、CLI）
+- 识别所有数据存储（数据库、缓存、对象存储）
+- 识别核心业务逻辑位置（后端、Agent、批处理）
+- 识别外部集成（支付、认证、LLM）
+- 识别部署单元（前端静态、后端容器、Worker）
+- 识别技术栈差异（React、Python、PostgreSQL）
+
+---
+
+### 工具2: Architecture Overview模板
+
+- **路径**: 参考上面的"输出格式"章节
+- **包含**: 系统清单、边界矩阵、依赖图
+
+---
+
+### 工具3: Mermaid图表
+
+**系统上下文图** (C4 Level 1):
+
+```mermaid
+graph TD
+    User -->|使用| System
+    System -->|调用| External
+```
+
+
+
+**系统依赖图**:
+
+```mermaid
+graph LR
+    A[System A] --> B[System B]
+    B --> C[System C]
+```
+
+
+
+---
+
+## 常见场景与模式
+
+### 场景1: 简单的Web应用
+
+**特征**: 前端 + 后端 + 数据库
+
+**推荐拆分**:
+
+- Frontend System (React)
+- Backend API System (FastAPI)
+- Database System (PostgreSQL)
+
+**总计**: 3个系统
+
+---
+
+### 场景2: 带AI功能的Web应用
+
+**特征**: 前端 + 后端 + 数据库 + AI Agent
+
+**推荐拆分**:
+
+- Frontend System
+- Backend API System
+- Agent System (LangGraph)
+- Database System
+
+**总计**: 4个系统
+
+---
+
+### 场景3: 复杂的企业应用
+
+**特征**: 多端 + 后端 + 数据库 + 搜索 + 队列
+
+**推荐拆分**:
+
+- Web Frontend System
+- Mobile System
+- Backend API System
+- Database System
+- Search System (Elasticsearch)
+- Worker System (Celery)
+
+**总计**: 6个系统
+
+---
+
+## 质量检查清单
+
+完成Architecture Overview后，使用此清单自检：
+
+### 系统数量
+
+- 系统数量 3-10 个（通常范围）
+- 没有过度拆分（每个功能一个系统）
+- 没有过度聚合（所有功能一个系统）
+
+### 系统边界
+
+- 每个系统有清晰的输入输出定义
+- 每个系统的职责明确且单一
+- 系统之间没有职责重叠
+
+### 依赖关系
+
+- 无循环依赖
+- 依赖关系清晰可视化（Mermaid图）
+- 每个系统的依赖 < 5个（避免过度耦合）
+
+### 文档完整性
+
+- 有系统上下文图 (C4 Level 1)
+- 每个系统有详细的清单条目
+- 有系统边界矩阵
+- 有系统依赖图
+- 有拆分原则与理由说明
+
+---
+
+## 快速上手示例
+
+**任务**: 为一个Todo应用拆解系统
+
+**Step 1: 应用6维度框架**
+
+- 用户接触点: Web界面
+- 数据存储: PostgreSQL
+- 业务逻辑: FastAPI后端
+- 外部集成: 无
+- 部署单元: 前端CDN, 后端容器
+- 技术栈: React, Python, PostgreSQL
+
+**Step 2: 识别系统**
+
+- Frontend System (React)
+- Backend API System (FastAPI)
+- Database System (PostgreSQL)
+
+**Step 3: 定义边界**
+
+- Frontend: 输入用户操作 → 输出API请求
+- Backend: 输入HTTP请求 → 输出JSON响应
+- Database: 输入SQL查询 → 输出数据
+
+**Step 4: 绘制依赖图**
+
+```
+Frontend → Backend → Database
+```
+
+**Step 5: 产出Architecture Overview**
+使用模板填充内容 → 保存到 `.prismx/arch/v{N}/ARCHITECTURE.md`
+
+---
+
+**记住**: 好的系统拆解是平衡的艺术。  
+不要过度拆分（微服务陷阱），也不要过度聚合（大泥球）。
+
+Happy Architecting!