Skip to main content Home Creators kqcoxn maadudul maa-pipeline-graph
maa-pipeline-graph 生成 MaaFramework Pipeline 项目的可交互状态机图谱。当用户想"看 Pipeline 节点关系"、"画状态机图"、"画 Mermaid 图"、"看 node 间关系"、"找孤立节点 / orphan node"、"看 Python 怎么驱动 Pipeline"、"看 interface.json 入口"、"调试跨文件 next 引用"、"重构前理清架构" 时使用。**任何涉及 MaaFramework 节点关系可视化的需求都用这个 skill**,即便用户没明确说"画图"。
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/kqcoxn/MaaDuDuL --skill maa-pipeline-graphThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
name maa-pipeline-graph description 生成 MaaFramework Pipeline 项目的可交互状态机图谱。当用户想"看 Pipeline 节点关系"、"画状态机图"、"画 Mermaid 图"、"看 node 间关系"、"找孤立节点 / orphan node"、"看 Python 怎么驱动 Pipeline"、"看 interface.json 入口"、"调试跨文件 next 引用"、"重构前理清架构" 时使用。**任何涉及 MaaFramework 节点关系可视化的需求都用这个 skill**,即便用户没明确说"画图"。
Pipeline 状态机图谱生成
项目初始化接力
画图前先查目标根目录的 basic_info.md。存在且包含第 0 节时，读取“0. Maa Skills 接力协议”和第 2/3/6 节，把 task entry、Pipeline 文件清单、JSON 边与 Python 外部入口作为图谱种子；随后仍须扫描当前 interface.json、全部目标 Pipeline 文件，以及 agent/**/*.py 的 run_task() / run_recognition()，不能把缓存当完整图数据库。文件缺失或没有第 0 节时直接扫描当前项目；不得自动调用 $maa-project-init，只有用户明确要求初始化或刷新时才调用。源码比文档新时以源码为准并报告缓存过期，不自动刷新或覆盖已有非空文档。
TL;DR
把"声明式 JSON 节点 + 命令式 Python 调度"的项目(Pipeline 节点 + context.run_task() / context.override_pipeline() 调用 + option/task 入口)整理成状态机图或关系表。
先发现真实工具，不要假设脚本存在 。历史审查发现 MaaGumballs 计划中提到的 tools/pipeline_to_mermaid.py 在目标提交并不存在；因此本 skill 不能默认承诺一键运行该脚本。
rg --no-ignore --files -g '!.git/**' -g '!.venv/**' |
Where-Object {
[IO.Path]::GetFileName($_) -match
'pipeline.*(mermaid|graph)|(mermaid|graph).*pipeline|migrate_pipeline'
}
如果仓库已有图谱脚本，先读脚本参数再运行。
如果没有脚本，只做分析、临时 Mermaid 草图或工具设计建议，不要声称生成了持久化图谱工具。
任何 HTML/图谱产物都应输出到已忽略目录，或先确认 .gitignore。
When to use
理解陌生项目 :新接手一个 MaaFramework 项目,想一眼看清节点、调用、入口重构前盘点 :大改某个 Pipeline 文件前,先看图,免得改完不知道影响了哪些边调试"孤儿"节点 :某节点在 Pipeline 里没 next 指向它,想知道是 bug 还是被 Python 调用加新节点后 :新加了一个 Pipeline 节点或 run_task 调用,刷新图看新边
Code review :看 PR 时,先看图理解结构再看代码,效率翻倍
写文档 / 培训新人 :把图当 on-boarding 资料
What it can produce 如果项目已有图谱脚本，通常会产出这些文件；如果项目没有脚本，本 skill 只负责设计这些产物或生成临时草图，不默认创建工具：
文件 用途 语法 index.html主目录(卡片导航 + 全局统计) HTML 卡片 pipeline_overview.html全局状态机，按实际文件数生成复合状态 stateDiagram-v2pipeline_external_entries.htmlPython → Pipeline 调用图 flowchartpipeline_utility_usage.html工具节点反向引用图 flowchartpipeline_<file>.html × N每个实际 Pipeline 文件的状态机细节 stateDiagram-v2
多文件图谱应带顶部导航栏和主页；是否支持 --open / --watch 取决于真实脚本能力。
How to use
发现并运行现有工具 rg --no-ignore --files -g '!.git/**' -g '!.venv/**' |
Where-Object {
[IO.Path]::GetFileName($_) -match
'pipeline.*(mermaid|graph)|(mermaid|graph).*pipeline|migrate_pipeline'
}
若发现真实脚本，例如 tools/pipeline_to_mermaid.py，先打开脚本看参数，再运行：
python tools/pipeline_to_mermaid.py --help
python tools/pipeline_to_mermaid.py
没有工具时 先不要生成大量 HTML。用临时分析脚本或手写 Mermaid 草图回答当前问题；后续确认要实现工具时再单独新增脚本，并配套 .gitignore、导航页和校验。
Key design decisions 本节是踩过的坑 + 解法 。下次再写类似工具时照搬。
1️⃣ 状态机 ≠ 子例程调用:用不同语义 坑 :MaaFramework Pipeline 不是纯 FSM,有 2 种边:
next: "X" — 真·状态转移,A → X 后,X 接管[JumpBack]X — 子例程调用,执行 X,自动返回 A ,X 不接管 为什么重要 :如果用同一种箭头画两种边,看图的人会误以为有环。状态机会被画成"循环依赖"。
flowchart 用 ==>(粗箭头)画 [JumpBack],-->(细箭头)画 nextstateDiagram-v2 用显式标签 : calls / : returns(画成两条边:调用方 → 被调方 → 调用方)永远不要把 [JumpBack] 画成"返回当前节点"的回环——它本就是临时离开
2️⃣ 孤儿子图 = Python 调用的入口 坑 :Pipeline 里很多节点没 next 指向它们(无入边),新手以为是 bug。
Python 代码里的 context.run_task("X")
assets/interface.json 的 task[].entry(MaaPiCli 暴露给用户的入口)
Python :用 ast 解析 agent/**/*.py,在 ast.Call 里找 func.attr == "run_task",记录 Class.method 调用方interface.json :读 task[] 数组,每个 entry 字段就是用户级入口
3️⃣ 双遍解析:先建索引,再画边 坑 :Pipeline 节点会跨文件 next,按文件名排序处理时,后面的文件引用前面的节点,边会丢 。
举例 :auto_task.json 按字母序排第一,里面有 OpenCityTaskPanel.next = ["FindCityTask_OCR"],但 FindCityTask_OCR 定义在 city.json(字母序更后)。处理 auto_task.json 时,目标还没解析,直接 continue 跳过这条边。
Pass 1: 扫所有文件,建立 name → file 索引
Pass 2: 扫所有文件的 next,根据完整索引解析目标
4️⃣ Mermaid 语法选型:stateDiagram vs flowchart 场景 选 为什么 真·FSM(节点 + 转移 + 初始/终止) stateDiagram-v2原生支持 [*] 初始/终止、复合状态、转移标签 调用图 / 反向引用图 flowchartstateDiagram 不支持"被谁调用"这种语义 节点形状区分(Stadium / Circle) flowchartstateDiagram 形状统一,只能用 classDef 染色 跨文件复杂关系 stateDiagram-v2 + 复合状态state X { ... } 把每个文件折叠起来
口诀 :状态机用 stateDiagram,其他用 flowchart 。
5️⃣ ID 冲突:中文/emoji 节点必须加 hash 后缀 坑 :Mermaid 节点 ID 由你写,内部是字符串。但整个图里不能有两个同 ID 的节点 。
中文/emoji 节点名(如 📲 启动游戏 和 📲 推年计划)用 re.sub(r'[^A-Za-z0-9_]', '_', name) 过滤后,都会变成 iface________ ,Mermaid 解析失败,图直接黑屏。
def mid (file: str , name: str ) -> str :
h = hash ((file, name)) & 0xFFFF
return f"{re.sub(r'[^A-Za-z0-9_]' , '_' , f'{file} __{name} ' )[:50 ]} _{h:04x} "
永远不要 只靠字符串规范化生成 Mermaid ID,必须带 hash 后缀保证唯一性。
6️⃣ 产物必须 .gitignore 坑 :自动生成的 HTML 会被 git 当成"新增文件"跟踪,每次重生都会改 commit,PR diff 爆掉。
docs/zh_cn/graph/ 加入 .gitignore脚本每次全量清空再重生 (无缓存、无 diff)
队友各跑各的,互不冲突
7️⃣ 16+ 张图必须有导航栏 + index 主页 坑 :第一次版就只输出每张图,没导航 。用户要从一个文件跳到另一个,得手动记路径或重新打开 IDE。
每张 HTML 顶部固定深色 navbar(4 个常驻链接 + 当前页高亮橙色)
一个 index.html 主目录,卡片网格展示所有图
卡片显示节点数、入边/出边数(让人快速判断要不要点开看)
对 skill 的启示 :任何会生成多文件的工具,都要有导航机制 ,否则用户每用一次就骂一次。
Common pitfalls
跨文件 next 解析漏边 症状 :总边数比手动数少,某些 next 字段在图里看不到。
跑脚本时打印 next count = 67, jumpback = 32,如果比预期少,基本是双遍解析没做
临时加个 assert all(target in all_names for target in nexts) 找未解析的悬挂引用
目标节点在另一个文件且字母序靠前 → 字母序靠后的文件 next 引用它会丢
ID 冲突导致图渲染失败 症状 :浏览器控制台报 SyntaxError: Duplicate id 或图直接空白。
节点名包含中文/emoji
多个节点规范化后 ASCII 形式相同
解决 :用 hash 后缀,见 5️⃣
状态名包含 ASCII 非法字符 症状 :stateDiagram-v2 不允许节点名带 . 或 -,会解析失败。
节点名如 CastleMarry_AgeCheck(_ 合法) OK
节点名如 BigMap-MarketStart(- 非法) 必须转成 BigMap_MarketStart
解决 :用 re.sub(r'[^A-Za-z0-9_]', '_', name) 转换
把生成物 commit 进 git 症状 :git status 出现一堆 pipeline_*.html untracked。
.gitignore 加了 docs/zh_cn/graph/ 吗git check-ignore -v docs/zh_cn/graph/pipeline_marry.html 看是否被忽略如果没忽略,加完 gitignore 后 git rm --cached docs/zh_cn/graph/*.html 清理已跟踪文件
Implementation reference 不要假设参考实现一定在项目里。 先用上面的忽略规则无关目录的发现命令查找真实脚本；只有脚本存在时才把它当实现参考。若脚本不存在，下列结构是未来实现图谱工具时的建议设计。
load_pipeline() # Pass 1: 建 name→file 索引;Pass 2: 解析 next
scan_python_calls() # ast 扫 agent/**/*.py 的 context.run_task()
scan_interface_tasks() # 读 interface.json 的 task[].entry
build_state_overview() # stateDiagram-v2 复合状态
build_state_per_file() # 单文件 stateDiagram
build_external_entries()# Python 调用 flowchart
build_utility_usage() # 反向引用 flowchart
build_index_html() # 主目录
wrap_html() # HTML 模板 + 导航栏
main() # --open / --watch 处理
删改 :7️⃣ 经验任意一条 → 改对应章节新增场景 :如果要给别的项目类型(非 MaaFramework)用,把"4️⃣ Mermaid 语法"和"3️⃣ 双遍解析"通用化即可,其他都是 MaaFramework 特化
移植到其他项目 如果你的项目是其他"声明式 + 命令式"系统(比如 Airflow DAG + Python、Terraform resources + tfvars、Ansible playbook + roles),核心思路一致 :
把声明式部分当 FSM(节点 + 边)
把命令式部分当外部触发器(扫 context.run_task() 类似物)
用双遍解析处理跨文件引用
ID 加 hash 后缀防冲突
产物 gitignore
Mermaid 语法选择(stateDiagram vs flowchart)同样适用。
