lidorshimoni/visualize

Visualize：架构与流程可视化模式

意图

将文本形式的架构、复杂算法、多智能体交互和数据模型转换为使用标准 Mermaid 语法的明确可视化图表。

理论基础

植根于认知负荷理论和 C4 软件架构模型（Brown, 2018）。可视化模型将抽象的系统描述具体化，使人（和 AI 代理）能够即时验证边界、数据流和状态转换。

标准图表原型

1. 组件与边界架构（C4 容器/组件）

使用 flowchart TD 或 flowchart LR 配合子图来描绘架构层：

flowchart TD
    subgraph Client["客户端层"]
        Web["Web 应用程序 (React)"]
        CLI["CLI 工具 (Python)"]
    end

    subgraph Gateway["API 网关"]
        Proxy["反向代理 / Nginx"]
        Auth["认证服务 (JWT)"]
    end

    subgraph Core["核心服务"]
        App["应用引擎"]
        Worker["异步后台工作进程"]
    end

    subgraph Data["持久化层"]
        DB[("PostgreSQL")]
        Queue[("Redis 队列")]
    end

    Web --> Proxy
    CLI --> Proxy
    Proxy --> Auth
    Auth --> App
    App --> Queue
    Queue --> Worker
    Worker --> DB
    App --> DB

2. 请求/响应与协议流程（序列图）

使用 sequenceDiagram 配合激活生命线来展示时间顺序的交互：

sequenceDiagram
    autonumber
    actor User
    participant Agent as 编码代理
    participant Tool as 工具运行器
    participant Git as 版本控制

    User->>Agent: 请求实现功能
    Agent->>Tool: 运行失败测试 (红色)
    Tool-->>Agent: 测试如预期失败
    Agent->>Tool: 编写最小化代码 (绿色)
    Agent->>Tool: 运行测试套件
    Tool-->>Agent: 所有测试通过
    Agent->>Git: 提交原子变更
    Git-->>Agent: 生成提交哈希
    Agent-->>User: 报告任务完成

3. 状态机与生命周期（状态图）

使用 stateDiagram-v2 表示实体状态、任务状态或连接生命周期：

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview: 提交审核
    InReview --> Approved: 验证通过
    InReview --> NeedsChanges: 发现阻塞问题
    NeedsChanges --> InReview: 重新提交修复
    Approved --> InProgress: 开始实现
    InProgress --> Completed: 所有测试通过
    Completed --> [*]

4. 数据模型与关系（实体关系图）

使用 erDiagram 表示关系型模式和领域模型：

erDiagram
    PROJECT ||--o{ SPECIFICATION : 包含
    SPECIFICATION ||--o{ TICKET : 分解为
    TICKET ||--o{ COMMIT : 由…实现
    TICKET {
        string id PK
        string title
        string status
        string blocked_by
    }

Mermaid 语法安全规则

1. 始终引用包含特殊字符的节点标签：
   • 使用 id["Label (Extra Info)"] 而不是 id[Label (Extra Info)]。
2. 仅支持这些图表类型：
   • 流程图 (flowchart TD)、序列图 (sequenceDiagram)、状态图 (stateDiagram-v2)、类图 (classDiagram)、实体关系图 (erDiagram)。
3. 避免在节点文本中使用原始 HTML：在节点字符串中使用纯 Markdown 或干净的文本。

---

引用与出处

1. C4 软件架构模型：Brown, S. (2018). Software Architecture for Developers: Visualise, document and explore your software architecture. Leanpub.
2. Mermaid 图形标准：Sveidqvist, K., 等. (2014-2026). Mermaid: Markdown-inspired syntax for generating charts and diagrams (https://mermaid.js.org/).
3. 软件可视化中的认知负荷理论：Sweller, J. (2011). Cognitive Load Theory. Psychology of Learning and Motivation, Vol. 55.