---
name: maa-project-init
description: Scan and initialize a MaaFramework game or app automation project for Maa skills and MaaMCP workflows. Use when asked for maa-project-init, project-pipeline-init, basic_info.md, researching a Maa project, scanning pipeline nodes, finding common Back/Return/Exit/Confirm nodes, mapping node relationships, generating entry flowcharts, summarizing image assets and OCR conventions, or reducing discovery cost for later Maa skill work.
---

# 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:

   ```bash
   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:

   ```bash
   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

## `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, discovered-but-unreferenced candidates, and orphan declarations (resolved paths outside the convention list).

Warnings are emitted when `child_args` is empty, has no `.py` entries, has unresolved paths, references a non-convention name, or when a convention candidate exists but is not referenced by `child_args`. 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.