maa-pipeline-history-audit

name

maa-pipeline-history-audit

description

Audit a MaaFramework/Maa-series project's Git history to learn how Pipeline JSON, interface options, Python AgentServer CustomAction code, and related data tables evolved. Use when asked to review a Maa project from initial commit through a target commit, map `action: Custom` pipeline nodes to `@AgentServer.custom_action(...)` implementations, find pipeline/custom/option patterns or breakages, and produce a report plus skill-improvement recommendations.

Pipeline History Audit

Overview

Use this skill to let a Maa project "teach" its Pipeline and CustomAction conventions from real Git history. The output is an audit report, not a code change, unless the user explicitly asks to fix findings afterward.

Default to the current repository and current HEAD unless the user provides a path or commit. If the target checkout is not at the requested commit, read from git show <target>:<path> and git log <target> instead of moving the user's branch.

Workflow

1. Ground the target.

   • Record repo root, current branch, HEAD, requested target commit, root commit, and git status --short.
   • Treat uncommitted changes as user work. Do not reset, checkout, clean, or format them.
   • If the user names a future/other commit that is not checked out, audit that commit object directly.

2. Classify every commit.

   • Traverse with git log --reverse --date=short --format=%H%x00%h%x00%ad%x00%s <target>.
   • For each commit, inspect git diff-tree --root --no-commit-id --name-status -r <commit>.
   • Mark a commit as relevant if it touches:
     • assets/resource/**/pipeline*.json
     • assets/resource/**/pipeline/**/*.json
     • assets/resource/**/default_pipeline.json
     • assets/interface.json
     • agent/**/*.py
     • assets/table/**/*.json or intelligence_data/**
   • skills/maa-pipeline-* or legacy .claude/skills/pipeline-*
   • Relevant type labels are Pipeline, Option, Agent, Table, and Skill; labels may overlap.
   • List all commits in an appendix, including irrelevant commits.

3. Scan historical change themes.

   • Use git log -G over the relevant pathspecs for:
     • "action": "Custom"
     • custom_action and @AgentServer.custom_action
     • custom_action_param
     • "next": and [JumpBack]
     • pipeline_override
     • enable / enabled
     • OCR, TemplateMatch, ColorMatch, color_filter
     • run_task(, run_recognition(, get_node_data(
   • Use these counts as navigation aids, not as the final conclusion.

4. Parse the target tree.

   • Load every target pipeline JSON and count files, nodes, action types, recognition types, next entries, and [JumpBack] entries.
   • Extract action: Custom nodes with custom_action and custom_action_param.
   • Parse agent/**/*.py with Python ast. Walk both ast.ClassDef and ast.FunctionDef decorator lists because Maa projects commonly register CustomAction implementations by decorating classes. Extract:
     • @AgentServer.custom_action("Name")
     • context.run_task("Node")
     • context.run_recognition("Node")
     • context.get_node_data("Node")
   • Build a Pipeline node -> custom_action -> Python registration table and explicitly list missing registrations.
   • Parse assets/interface.json for option/task counts and pipeline_override usage.

5. Review key commits.

   • Always sample major introduction/refactor/fix commits found by history, especially commits that introduce CustomAction, new pipeline files, options, ColorMatch/color_filter, or skill updates.
   • Use git show --stat --oneline <commit> plus targeted git show <commit>:<path> reads.
   • Explain what the commit teaches, not just which files changed.

6. Validate the target.

   • Run JSON parsing on all pipeline files.
   • If a resource checker exists, run it against the target commit. For this repo family, prefer:

     python tools\ci\check_resource.py assets\resource\base
     

   • If checking an un-checked-out target commit, create a temporary detached worktree, run validation there, then remove the worktree. Verify the temp path before recursive deletion.
   • Note that resource loading may not detect missing Python CustomAction registrations; report both results separately.

7. Write the report.

   • Prefer docs/zh_cn/develop/pipeline_history_audit.md in the target repo if that path exists; otherwise use docs/pipeline_history_audit.md.
   • Include:
     • Method and target commit
     • Coverage stats
     • Historical keyword counts
     • Current pipeline/custom/option asset snapshot
     • Custom mapping table
     • Key timeline
     • Findings by subsystem
     • Skill improvement recommendations
     • Validation results
     • Full commit index appendix
     • Registered custom action appendix

Report Judgement Rules

• Do not claim "all Custom nodes are valid" unless every custom_action has a matching decorator in the target tree.
• Do not treat context.run_task() result .nodes as proof of a hit. Prefer completed or recognition.hit when describing good patterns.
• Treat pipeline_override as a merge into existing nodes; flag cases where the target node is missing or Python reads a different field path.
• Call out enable vs enabled explicitly. Recommend compatibility helpers only when history already uses both.
• Prefer JSON state machines (next + [JumpBack]) for finite UI flows. Reserve Python orchestration for runtime loops, counters, event libraries, screenshot parsing, and business decisions.
• For OCR stability, look for ROI narrowing, expected text changes, ColorMatch, and color_filter before recommending TemplateMatch.
• Distinguish resource loading from end-to-end execution. A resource check can pass while CustomAction registration is missing.

Useful Commands

git -C <repo> status --short
git -C <repo> rev-list --count <target>
git -C <repo> log --reverse --date=short --format="%H%x00%h%x00%ad%x00%s" <target>
git -C <repo> diff-tree --root --no-commit-id --name-status -r <commit>
git -C <repo> log --format=%H -G'"action"\s*:\s*"Custom"' <target> -- assets/resource agent assets/interface.json
git -C <repo> show --stat --oneline <commit>
git -C <repo> show <target>:assets/interface.json

When generating analysis scripts, keep them temporary unless the user asks for a reusable script. Do not leave generated helper scripts in the repo.