ac-diagram

name	ac-diagram
description	面向软件工程师生成代码结构图、调用链图和业务映射图，并按需导出 Mermaid 图文件。
disable-model-invocation	true

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

[模式：准备]

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：自检

[模式：审查]

交付前检查：

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

---

输出模板

## 🗺️ 图谱结果

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