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 with a main interface.json or interface.jsonc.

Project Discovery Contract

The main Interface is the source of truth. Do not infer a MaaFramework project from an assets/... directory convention.

• Accept a root-level interface.json / interface.jsonc or an assets/interface.json / assets/interface.jsonc as the main Interface. Both are common valid project layouts. If both locations exist, use the root-level Interface first as a deterministic tie-breaker.
• Resolve every import[] path relative to the main Interface directory. Imports may contribute only top-level task, option, and preset; controller, resource, agent, and other project-level declarations remain in the main Interface.
• Resolve every resource[].path relative to the main Interface directory. Pipeline and image files are read from those declared resource roots.
• Resolve languages[] relative to the main Interface directory when it is present.
• Accept agent in either object form or array form; collect .py paths from every config's child_args.
• If the main Interface or an import is missing or malformed, report the diagnostic and continue with the declarations that can be loaded. Do not silently guess resource or task roots from unrelated directories.

M9A is a standard root-Interface project: the root interface.json imports tasks/**/*.json, declares resource combinations such as resource/base plus channel overlays, and uses array-form agent with agent/bootstrap.py. Boilerplate-family projects such as MAAPVZ, MaaDuDuL, and MaaNTE commonly place the main Interface at assets/interface.json or assets/interface.jsonc; their task entries may live in the main Interface or come entirely from imports. Treat both shape families as valid acceptance cases.

Core Workflow

1. Locate the target project root.

   • Prefer a user-provided path.
   • Otherwise look for the main Interface using the Project Discovery Contract above.
   • Treat the loaded Interface bundle as the source of resource groups, controller types, task entries, options, 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
   • Interface import diagnostics and warnings
   • 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 约定入口候选 + 交叉对比)

Task counts describe the merged Interface bundle's total top-level task[] entries after imports. Separator and other display-only task entries remain counted; if a report separately claims a functional-task count, it must state the filter used.

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

• the main interface.json / interface.jsonc and its direct import[] declaration files
• pipeline/**/*.json and default_pipeline.json under each resource path declared by the main Interface
• all files under each declared resource root's image/**
• static string targets passed to context.run_task() and context.run_recognition() under agent/**/*.py
• @AgentServer.custom_action(...) registrations under agent/**/*.py
• Interface agent[] / 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 a legacy MaaGumballs-style layout, 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. For M9A, the same acceptance check is root interface.json, all loaded task imports, all declared resource roots, and the declared bootstrap agent. For boilerplate-family projects, the equivalent check is the assets/ main Interface, all loaded task imports, declared resource roots, and the declared agent path.

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

basic_info.md Contents

The generated document must be concise and useful to an AI agent. Include:

1. Project overview
2. Resource groups and task entries
3. Main pipeline inventory
4. Common public nodes
5. Back / Return / Exit / popup handling
6. Node relationship summary
7. OCR expected text conventions
8. TemplateMatch image inventory
9. Resolution and ROI conventions
10. Risks and TODOs
11. Maa skill handoff routing and live verification status

For section 2, the "Agent script paths" subsection includes three parts:

• Declared: each child_args .py with Status (resolved / unresolved / non-py / absolute) and the absolute path of resolution (if any).
• Discovered: every AGENT_DIR_NAMES × AGENT_ENTRY_BASENAMES candidate under root + 4 ancestor levels with an Exists column.
• Cross-check: unresolved declarations and discovered-but-unreferenced candidates. A resolved declaration is authoritative even when its filename is outside the conventional candidate list; do not call agent/bootstrap.py an orphan.

Warnings are emitted when an agent config has malformed child_args, when the aggregate child_args is empty or has no .py entries, or when a declared .py cannot be resolved. Discovered-but-unused conventional entries are compatibility context, not warnings. The scanner mirrors maa_mcp/agent_supervisor._build_subprocess_cmd's parent-walk semantics (AGENT_PARENT_WALK_LIMIT = 4); keep the two limits in sync if you change one.

Keep automatically detected facts separate from TODOs. Do not invent game semantics that are not present in the project files.

Optional Live MaaMCP Research

If a device or window is available and the user wants deeper game research, use MaaMCP after file scanning:

1. connect to the simulator/window
2. take a default screencap
3. infer portrait or landscape from image width/height
4. use OCR for visible text and key buttons
5. add stable UI facts to basic_info.md

Live observations must include time, controller/device, screenshot size/orientation, visible page evidence, tested node, score, and whether an action ran. If OCR and screenshot catch different frames during a transition, record them as separate observations and do not promote either one to a stable project fact.

For safe initialization validation, prefer a temporary DoNothing recognition probe derived from a known public node. Run it with start_agent=false when Custom code is unnecessary, inspect recognition.all_results, call stop_pipeline, and remove the temporary file.

This is an enhancement, not a blocker. File scanning must work without a live device.

Do Not

• Do not overwrite an existing non-empty basic_info.md without explicit confirmation.
• Do not commit generated basic_info.md from another repository into MaaMCP.
• Do not modify unrelated target-project files while scanning.
• Do not treat OCR/image guesses as facts unless they came from files or live MaaMCP verification.