maa-pipeline-graph

Pipeline 状态机图谱生成

项目初始化接力

画图前先查目标根目录的 basic_info.md。存在且包含第 0 节时，读取“0. Maa Skills 接力协议”和第 2/3/6 节，把 task entry、Pipeline 文件清单、JSON 边与 Python 外部入口作为图谱种子；随后仍须扫描当前主 interface.json / interface.jsonc、其 import[]、每个 resource[].path 声明资源根内的 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-v2
pipeline_external_entries.html	Python → Pipeline 调用图	flowchart
pipeline_utility_usage.html	工具节点反向引用图	flowchart
pipeline_<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'
    }