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

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

使用方法

/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：需求增强与收敛

[模式：准备]

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

🔎 阶段 1：上下文检索

[模式：研究]

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

🧭 阶段 2：关系建模

[模式：建模]

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

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

🧩 阶段 3：生成 Mermaid 图

[模式：绘图]

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

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

生成 Mermaid 图时：

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

📦 阶段 4：导出与交付

[模式：输出]

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

✅ 阶段 5：自检

[模式：审查]

交付前检查：

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

输出模板

## 🗺️ 图谱结果

### 范围
- 图类型：<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 源码

ac-diagram