# Ac Diagram

> 面向软件工程师生成代码结构图、调用链图和业务映射图，并按需导出 Mermaid 图文件。

- Skill: `yz0812/ac-diagram` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yz0812/ac-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yz0812/ac-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yz0812 (https://skillmd.com/u/yz0812)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yz0812/ac-diagram

---


# Diagram - 代码关系 + 业务映射 + Mermaid 导出

面向软件工程师读取代码与业务上下文，生成可解释的 Mermaid 图。默认输出结构化结论 + Mermaid 源码；当用户要求图片、PDF 或分享链接时，再按需使用 `mermaid-live` MCP 导出本地文件或生成可视化链接。

## 使用方法

```bash
/ac-diagram [模块|文件|函数|业务流程描述] [--type architecture|callflow|mapping|all] [--format code|svg|png|pdf|url]
```

## 参数说明

| 参数 | 说明 |
|------|------|
| `模块｜文件｜函数｜业务流程描述` | 图谱分析范围。可以是模块名、文件路径、类/函数名，或业务流程描述。 |
| `--type architecture` | 生成代码结构 / 模块上下文图。 |
| `--type callflow` | 生成调用方 → 被调用方关系图。 |
| `--type mapping` | 生成业务目标 ↔ 代码实现映射图。 |
| `--type all` | 在范围可控时一次生成上述全部视图。 |
| `--format code` | 仅输出 Mermaid 源码与说明。默认值。 |
| `--format svg/png/pdf` | 导出本地图文件。 |
| `--format url` | 生成 Mermaid Live 可分享链接。仅在用户明确要求或确认内容不敏感时使用。 |

## 角色分工

| 角色 | 职责 |
|------|------|
| Claude（主线程） | 澄清需求、读取代码与业务上下文、提炼关系、生成 Mermaid 图、调用 `mermaid-live` MCP 导出产物、输出最终说明 |
| subagents | 只读检索代码上下文、调用链、业务映射线索，不修改文件、不直接交付最终结果 |

---

## 执行约束

**工作目录**：
- 使用当前工作目录作为图谱分析根目录
- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定目标工作区
- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区

**图谱边界**：
- 默认先画最小可解释范围，不为了“全景图”把无关模块塞进同一张图
- 若用户请求 `--type all` 且范围过大，先拆成多张图，必要时要求缩小范围
- 生成业务映射图时，若缺少业务目标、业务动作、角色或流程信息，必须先提问，禁止猜测业务含义

**subagents 使用条件**：
- 适用：目标范围较大、模块较多、调用链不明确、需要并行摸排多个子模块
- 优先：`Explore` 用于代码路径、调用链、依赖边界的只读检索
- 不适用：已知文件路径、单函数调用关系、主线程几次读取即可收敛的场景

**导出与安全**：
- 默认输出 Mermaid 源码，不默认生成外部分享链接
- 若用户要求图片或 PDF，优先使用 `mermaid-live` MCP 导出本地文件
- 若用户要求 URL，或需要可视化链接，必须先确认内容不敏感；涉及代码结构、内部系统、业务链路时默认谨慎处理
- 已委托给 subagents 的检索内容，主线程不要重复执行

---

## 执行工作流

**图谱任务**：$ARGUMENTS

### 🔍 阶段 0：需求增强与收敛

`[模式：准备]`

1. 识别用户真正想看的图类型：
   - **architecture**：模块、入口、依赖关系
   - **callflow**：调用方、被调用方、关键调用链
   - **mapping**：业务动作、业务目标与代码实现的映射
2. 识别范围：项目、模块、文件、类、函数、接口、任务链路、业务流程
3. 识别输出：仅 Mermaid 源码、图片/PDF、本地文件、可分享链接
4. 若以下任一项不清晰，必须使用 `AskUserQuestion`：
   - 图类型不明确
   - 范围过大或过宽
   - 业务映射缺少业务上下文
   - 用户要求导出文件但未说明目标格式

### 🔎 阶段 1：上下文检索

`[模式：研究]`

1. 已知路径、文件或符号时，主线程直接读取相关文件
2. 模糊搜索时：
   - 优先使用 `ace-tool` 做语义检索
   - 范围较大或需要并行摸排时，使用 `Agent(Explore)` 启动只读 subagents
3. 至少提炼以下证据：
   - 入口文件 / 核心模块
   - 关键类、函数、接口
   - 调用方与被调用方
   - 与业务动作对应的代码入口、服务、任务、存储或外部系统
4. 所有结论都尽量落到 `file_path:line_number` 证据

### 🧭 阶段 2：关系建模

`[模式：建模]`

按用户目标组织关系数据：

1. **代码上下文联系**
   - 模块边界
   - 入口与核心组件
   - 上下游依赖
2. **调用方 / 被调用方**
   - 谁发起调用
   - 调到哪里
   - 调用类型：调用 / 读取 / 写入 / 发布 / 订阅 / 返回
3. **代码与业务关联**
   - 业务动作或业务目标
   - 对应 API / 服务 / Job / Repository / 外部系统
   - 每个技术节点在业务中的职责
4. 若范围允许：
   - `architecture`、`callflow`、`mapping` 可分别输出独立 Mermaid 图
   - 若用户只要一张综合图，主线程需先控制节点数量，避免图不可读

### 🧩 阶段 3：生成 Mermaid 图

`[模式：绘图]`

根据场景优先选择以下图法：

| 场景 | 默认图法 | 说明 |
|------|----------|------|
| 代码结构 / 模块上下文 | `flowchart TD` | 自上而下展示模块、入口、依赖关系 |
| 调用链 | `flowchart LR` | 左到右展示调用方 → 被调用方；若强调时序，可改 `sequenceDiagram` |
| 业务映射 | `flowchart TD` 或 `mindmap` | 业务动作 → 技术实现 → 下游系统 |

生成 Mermaid 图时：
- 节点 ID 使用驼峰命名
- 边标签尽量用动词：`calls`、`reads`、`writes`、`publishes`、`uses`、`maps to`
- 一个节点只表达一个明确职责
- 复杂范围优先多图，不拼接成超大单图

### 📦 阶段 4：导出与交付

`[模式：输出]`

1. 默认输出：
   - 范围说明
   - 关键上下文摘要
   - 调用关系表
   - 业务映射表（若适用）
   - Mermaid 源码
2. 若用户要求 `svg/png/pdf`：
   - 使用 `mermaid-live` MCP 导出本地图文件
   - 返回实际输出路径
3. 若用户要求 `url`：
   - 仅在用户明确要求或确认内容不敏感时，生成 Mermaid Live URL
4. 若 `mermaid-live` MCP 不可用：
   - 退化为只输出 Mermaid 源码和建议的手动导出方式

### ✅ 阶段 5：自检

`[模式：审查]`

交付前检查：
- 图节点和边是否都能对应到代码或业务证据
- 是否明确体现调用方 / 被调用方
- 是否明确体现代码与业务的关联
- 是否超出用户要求范围
- 是否错误暴露了不应外发的内部结构

---

## 输出模板

```markdown
## 🗺️ 图谱结果

### 范围
- 图类型：<architecture / callflow / mapping / all>
- 分析范围：<模块 / 文件 / 函数 / 业务流程>

### 关键上下文
| 类型 | 内容 | 证据 |
|------|------|------|
| 入口 | <描述> | `path/to/file:line` |
| 核心模块 | <描述> | `path/to/file:line` |

### 调用关系
| 调用方 | 被调用方 | 关系 | 证据 |
|--------|----------|------|------|
| A | B | calls | `path/to/file:line` |

### 业务映射
| 业务动作 | 代码元素 | 职责 | 证据 |
|----------|----------|------|------|
| 下单 | OrderService.create | 创建订单 | `path/to/file:line` |

### Mermaid 图
```mermaid
flowchart TD
    A --> B
```

### 导出产物
- `<本地图文件路径 或 Mermaid Live URL>`
```

---

## 规则

1. **证据优先** – 所有关系尽量回到 `file_path:line_number`
2. **先问后画** – 图类型、范围、业务上下文不清晰时必须先提问
3. **主线程交付** – 最终 Mermaid 图与导出产物由主线程统一生成
4. **subagents 只读辅助** – 仅做检索与关系提炼，不直接交付最终图
5. **默认谨慎外发** – 默认不生成 URL，优先本地文件或 Mermaid 源码