Maa Project Init

Maa Project Init

Use this skill to turn a MaaFramework consumer project into a compact onboarding document for future AI sessions. It scans the project's pipeline and image resources, identifies reusable control nodes, and writes basic_info.md at the target project root.

The generated file is a producer/consumer handoff: maa-project-init produces project context, while maa-pipeline-guide, maa-pipeline-generate, maa-pipeline-graph, maa-pipeline-option, and maa-pipeline-testing consume the relevant sections before broad repository discovery.

Do not run this skill against MaaMCP itself unless the user explicitly asks to analyze MaaMCP as a consumer project. MaaMCP is the tool runtime; the normal target is a MaaFramework consumer project containing assets/interface.json or interface.json.

Core Workflow

1. Locate the target project root.

   • Prefer a user-provided path.
   • Otherwise look for assets/interface.json, then interface.json.
   • Treat assets/interface.json as the source of resource groups, controller types, task entries, and agent settings.

2. Run the analyzer in summary mode first:

   python "<skill-dir>/scripts/analyze_pipeline_project.py" "<project-root>"

3. Inspect the summary for:

   • resource groups and task entries from interface.json
   • pipeline file count and unique node count
   • high in-degree common nodes
   • Back / Return / Exit / Close / Confirm / Wait / Flag nodes
   • entry task flowcharts and primary path previews
   • unresolved references, isolated nodes, and cycle candidates
   • image directory inventory and TemplateMatch usage
   • Python context.run_task() / run_recognition() external entries
   • orphan candidates after excluding interface and Python entry points
   • agent script paths (declared child_args resolution + project_root 与 4 层 ancestor 约定入口候选 + 交叉对比)

4. Generate basic_info.md only after the summary looks reasonable:

   python "<skill-dir>/scripts/analyze_pipeline_project.py" "<project-root>" --write-basic-info

   If basic_info.md already exists, the script refuses to overwrite it. Use --overwrite only after the user explicitly confirms.

5. Report where basic_info.md was written and name the most important sections that still need human review.

6. When handing off to another Maa skill:

   • tell it to read basic_info.md section 0 and the routed sections for its task
   • treat the document as a cache, not as source of truth
   • re-check every touched node in current JSON/Python and every live claim on the current device
   • if relevant source files are newer than basic_info.md, rerun summary mode and report staleness; do not overwrite silently

What The Analyzer Reads

• assets/interface.json or interface.json
• all assets/resource/**/pipeline/**/*.json
• default_pipeline.json under resource roots
• all files under assets/resource/**/image/**
• static string targets passed to context.run_task() and context.run_recognition() under agent/**/*.py
• @AgentServer.custom_action(...) registrations under agent/**/*.py
• interface.json agent.child_args 里每条 .py 的磁盘解析状态（与运行时 maa_mcp/agent_supervisor._build_subprocess_cmd 同步上溯 4 层）
• project_root 与 4 层 ancestor 内 agent/main.py、agent/server.py 等约定入口的候选存在性（AGENT_DIR_NAMES × AGENT_ENTRY_BASENAMES，不递归子目录）

For MaaGumballs-style projects, the script should discover entries such as Start_Up, DailyTask, Reward_Execute, Shop, AutoSky, JJC, Mars, DivineForgeLand_Start, TSD_Entry, AutoCdk, and StopGumballs, then connect them to the pipeline nodes that define them.

Relationship Rules

Parse these pipeline link fields:

• next
• on_error
• interrupt

Support these node reference forms:

• plain strings: "ConfirmButton"
• lists: ["A", "B"]
• NodeAttr objects: { "name": "A", "jump_back": true }
• prefixed strings: "[JumpBack]BackText", "[Anchor]SomeNode"

Strip bracket prefixes when resolving the target node, but preserve the prefix in summaries where useful.

Entry Flowcharts

Generate bounded Mermaid flowcharts from each interface.json task entry. These diagrams are meant to orient MaaMCP and future skills quickly, not to replace a full graph database.

• Start from the task entry node.
• Expand next, on_error, and interrupt edges with edge labels.
• Preserve branch hints such as JumpBack, jump_back, and anchor in edge labels.
• Limit depth and edge count so loops and shared utility nodes do not overwhelm basic_info.md.
• Include a short primary path text summary for agents that cannot render Mermaid.
• When a reachable node uses action: Custom (including v2 object form), add a separate Python Agent block. Link the Pipeline node to the block as a CustomAction call, link the block back as returns, and show the matched @AgentServer.custom_action(...) handler and source location when available.

Public Node Detection

Treat a node as likely reusable when either condition is true:

• it has high in-degree across the merged graph
• its name or behavior indicates a common UI operation

Important common categories:

• Back / Return / Exit / Close / Logout / Stop
• Confirm / Cancel / Retry
• Wait / Loading / Communicating / PowerLack
• Flag / Check / State probe
• ClickKey with Android key 4
• shared TemplateMatch assets such as back buttons, return buttons, confirm buttons, settings buttons