hanifalkauni/uml-architect

UML-Architect 技能指令

本指令指导AI Agent生成100%与UML-Architect MCP服务器确定性机器输出一致的架构分析与UML图输出。

---

1. 五阶段执行协议（Execution Pipeline）

阶段1：目标解析与代码库检测

1. 识别目标：
   • 输入是API端点（例如：POST /api/v1/orders/checkout）、函数名（例如：processPayment）还是文件/模块路径（例如：src/controllers/order.controller.ts）？
2. 清单扫描（无需编译）：
   • 检查项目中的清单文件：package.json、go.mod、pom.xml、pyproject.toml、Cargo.toml、composer.json、Gemfile 或 *.csproj。
   • 识别所用框架：Express/NestJS、FastAPI/Django、Gin/Fiber、Spring Boot、Axum/Actix、ASP.NET、Laravel 或 Rails。

阶段2：真实调用图追踪（严格追踪 - 零幻觉）

从实际源代码追踪执行流程：

1. 入口点：打开相关路由/控制器文件。
2. 中间件与守卫：追踪JWT令牌检查、会话、请求Schema验证（Zod、Joi、Pydantic、DTO校验器）。
3. 控制器/处理器：检查请求参数提取逻辑并委托给服务层。
4. 服务/领域层：追踪核心业务逻辑、辅助函数调用和数据计算。
5. 数据库与ORM：追踪查询/变更操作（SELECT、INSERT、UPDATE、事务提交/回滚）。
6. 外部集成：追踪HTTP调用（Stripe、银行API、SendGrid、OAuth）或RPC调用。
7. 消息队列/事件：追踪异步事件发布到Kafka、RabbitMQ、SQS、Redis PubSub或Celery。
8. 错误分支：将try/catch、if err != nil、except或错误守卫映射到替代分支（alt）。

---

2. 标准参与者与别名图

使用标准参与者命名方案，确保图表整洁、一致且易读：

类别	参与者ID	参与者标签格式	参与者类型
客户端/调用方	Client	Client / Frontend App（或 User / Mobile App）	actor
控制器/处理器	Ctrl	<文件名/控制器> (Controller)	participant
服务层	Svc	<服务名称>（例如：OrderService）	participant
第三方/外部	ExtAPI	<供应商名称/网关> (External API)（例如：Stripe API）	participant
数据库/存储	DB	Database (Storage / ORM)（例如：PostgreSQL Database）	participant
队列/事件代理	Queue	Message Broker (Kafka / Queue)	participant

---

3. Mermaid.js 语法与视觉主题规则

1. 主题指令（必填，位于图表第一行）： 默认使用现代 tokyo-night 主题：

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. 序列图：
   • 必须包含 sequenceDiagram 和 autonumber。
   • 同步使用 ->>，返回/响应使用 -->>，异步/队列事件使用 -)。
   • 将验证失败与成功的分支包裹在 alt 和 else 块中：

     alt 输入验证 / 认证失败
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else 验证通过（快乐路径）
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. 语法自修复（防错误）：
   • 避免在消息中使用未加引号的方括号字符。
   • 参与者ID中不要直接使用斜杠（/）（始终使用干净的别名如 Ctrl、Svc）。

---

4. 强制输出契约格式（Canonical Output Contract）

每个图表生成的响应必须遵循下方的Markdown结构，以确保与MCP服务器输出一致：

# UML 图：<目标/端点名称>

> *由 **UML-Architect 技能代理**（v1.0.0）自动生成*

## 可视化图表
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Frontend App
    participant Ctrl as <控制器名称> (Controller)
    participant Svc as <服务名称>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <HTTP_METHOD> <URL_PATH>
    alt 输入验证 / 认证失败
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else 验证通过（快乐路径）
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: 保存/查询事务记录
        DB-->>Svc: 数据库提交成功
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (成功负载)
    end
```

<details>
<summary>查看替代格式（PlantUML）</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<控制器名称> (Controller)" as Ctrl
participant "<服务名称>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <HTTP_METHOD> <URL_PATH>
alt 输入验证 / 认证失败
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else 验证通过（快乐路径）
Ctrl -> Svc: processRequest(payload)
Svc -> DB: 保存/查询事务记录
DB --> Svc: 数据库提交成功
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (成功负载)
end
@enduml
```
</details>

### 架构流程说明（<目标/端点名称>）

该执行流程涉及 **<N> 个主要组件**：

* **Client / Frontend App**（`Client`）：作为用户/调用方实体。
* **<控制器名称> (Controller)**（`Ctrl`）：作为请求和响应的控制实体。
* **<服务名称>**（`Svc`）：作为领域业务逻辑提供者。
* **Database (Storage / ORM)**（`DB`）：作为事务数据持久化存储媒介。
* **Message Broker (Kafka / Queue)**（`Queue`）：作为异步事件的接收者。

#### 详细执行步骤：
1. **Client** 将请求 `<HTTP_METHOD> <URL_PATH>` 发送到 **Ctrl**。
   * *条件检查*：如果参数无效或认证失败，流程直接中断并返回 HTTP 400/401 响应。
2. **Ctrl** 将有效负载委托给 **Svc**。
3. **Svc** 向 **DB** 执行查询/变更操作并接收存储确认。
4. **Ctrl** 向 **Queue** 触发事件通知。
5. **Ctrl** 向 **Client** 返回 HTTP 200/201 成功响应。

#### 错误与异常处理（Error Pathways）：
* **ValidationException**：如果负载不满足Schema约束，产生 HTTP `400` 响应。
* **UnauthorizedException**：如果授权令牌无效或过期，产生 HTTP `401` 响应。
* **InternalException**：如果发生网络故障或数据库回滚，产生 HTTP `500` 响应。

---

5. 其他图表类型（如用户要求）

• 流程图/活动图：使用 flowchart TD，包含圆形开始/结束节点 ([ ... ])、决策菱形 { "条件?" } 和过程方框 [ ... ]。
• 状态机图：使用 stateDiagram-v2，包含初始状态 [*]、状态转换、守卫和终止状态 [*]。
• 组件/架构图：使用 graph TD 和嵌套 subgraph（表示层、业务逻辑层、数据与持久化层）。