yz0812 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-liveMCP 导出本地文件 - 若用户要求 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-liveMCP 导出本地图文件 - 返回实际输出路径
- 使用
- 若用户要求
url：- 仅在用户明确要求或确认内容不敏感时，生成 Mermaid Live URL
- 若
mermaid-liveMCP 不可用：- 退化为只输出 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 源码