--- name: mi-ripple description: Diagnose and restore grid-like, granular, scale-like, tiled, or ripple artifacts in AI-generated images. Use when a user asks to remove digital ripple, decoder grids, repeating scales, honeycomb texture, granular AI texture, or degradation caused by iterative image-to-image editing. license: MIT compatibility: Requires Python 3.11+, local file access, and permission to run shell commands. Network access and a MIYANG API key are optional and only needed for explicitly authorized regeneration. metadata: author: MIYANG version: "0.1.0" repository: "https://github.com/miyang-ai/Mi-Ripple" --- # Restore digital-ripple artifacts Use the MIYANG `mi_ripple` package to diagnose first, choose only a compatible treatment, inspect the visual evidence, and return the actual output files to the user. Do not treat this as a generic denoiser. The workflow distinguishes: 1. isolated periodic lattice artifacts, which can be selectively notched; 2. granular artifacts in unstructured areas, which can receive masked reduction; 3. artifacts entangled with hair, foliage, fabric, stone, or other content, which require human review or optional cleaned-reference regeneration. ## Non-negotiable rules - Work on the original image at native resolution. Do not resize, recompress, or screenshot it before diagnosis. - Run the deterministic local pipeline before proposing regeneration. - Never run paid or content-changing regeneration without the user's explicit approval in the current conversation. - Never ask the user to paste an API key into chat. Ask them to set `MIYANG_API_KEY` in their environment. - Files containing `_refclean` are model references, not deliverable images. - Do not claim an artifact is removed only because a numeric score decreased. Inspect the heat map and comparison boards. - Preserve generated JSON sidecars and the XML trace with the output. - A pipeline `passed` result means measured filtering damage stayed within the configured limits. It does not mean a person has accepted the image. ## Locate or install the tool First check whether the command is available: ```bash mi-ripple --help ``` If this skill is being used from a checkout of the repository, install that checkout into an isolated environment: ```bash python3 -m venv .venv .venv/bin/python -m pip install -e . ``` Otherwise install from the canonical repository into an isolated environment: ```bash python3 -m venv .mi-ripple-venv .mi-ripple-venv/bin/python -m pip install \ "git+https://github.com/miyang-ai/Mi-Ripple.git" ``` Use the corresponding environment's `mi-ripple` executable for subsequent steps. Do not modify the user's global Python environment. ## Inputs Obtain: - the exact local path of one source image; - an output directory that will not overwrite the source; - optional user priorities such as preserving hair, paper texture, foliage, or color. If the image path is missing or ambiguous, ask for it. Do not choose a recently used image on the user's behalf. Supported image decoding is provided by Pillow. Prefer PNG for intermediate and final files. ## Step 1: run the local pipeline ```bash mi-ripple "/absolute/path/input.png" "/absolute/path/output" ``` This performs diagnosis, deterministic routing, safe local treatment when available, aligned verification, and provenance recording. Read: - `_restored.json` for the outcome and action sequence; - `_input_diag.json` for measurements and selected windows; - `_input_diag_board.png` for native-pixel diagnostic crops; - `_input_scaleheat.png` for whole-frame flagged tiles; - `_verify_board.png` when filtering was applied; - `_restored.png` when a final local result was delivered. Open the generated boards with the agent's image-reading capability. Do not interpret JSON without checking the images. ## Step 2: handle the outcome ### `delivered` Inspect the source, final image, heat map, and verification board. Check specifically: - hair remains continuous rather than becoming smooth blocks; - foliage, flowers, gravel, fabric, stone, and paper texture were not erased; - flat gradients did not gain cloudy stains or ringing; - no new repeated scales, honeycomb cells, woven meshes, or wave bands appeared; - framing, dimensions, and color remain unchanged on local filtering routes. If the visual check passes, give the user: 1. the final image path or attachment; 2. the comparison/verification board; 3. a short statement of the route taken; 4. any remaining suspected artifact. ### `needs_human_decision` This normally means the measured artifact overlaps image content and filtering cannot safely separate it. Show the diagnosis board and heat map. Explain which regions triggered review. Then ask whether the user authorizes one regeneration attempt, explicitly stating that it: - can incur API cost; - can change semantic details and identity; - can change dimensions, framing, and color; - still requires visual acceptance afterward. Do not proceed until the user explicitly agrees. ### `failed` Read the final JSON and the last step's error. Report the concrete failure and retain all artifacts already written. Do not silently switch providers or repeat a possibly billable request. ### `cancelled` or `step_limit` Report that no deliverable was produced. Preserve the trace for diagnosis. ## Step 3: optional regeneration Only after explicit approval, verify that `MIYANG_API_KEY` is set without printing its value: ```bash test -n "$MIYANG_API_KEY" ``` Run one bounded attempt by default: ```bash mi-ripple "/absolute/path/input.png" "/absolute/path/output-regenerated" \ --allow-regen --max-regen 1 ``` Never increase `--max-regen` without separate user approval. A timeout or interrupted response can have unknown billing state; do not automatically retry it. After regeneration, inspect both the full image and the relevant native-pixel windows. Compare identity, composition, geometry, hair, textured materials, and color against the source. Report semantic or color changes separately from artifact reduction. ## Interpretation guide - `lattice.detected`: isolated periodic spectral components were detected. The flag may remain true after safe attenuation near the sampling limit. - `granule.level=flat`: multiple unstructured windows support masked local reduction. - `granule.level=pervasive`: broad evidence; regeneration or human review is normally safer than stronger filtering. - `scale_index.level=structured`: similarly sized components cover at least 6% of grading tiles on the canonical canvas. - `suspected`: report for inspection; it is not sufficient evidence for aggressive automatic treatment. Legitimate repeated objects can trigger these measurements. Conversely, directional wide scales, woven hair, and long wave bands can look severe while receiving a low scale index. Visual evidence has final authority. ## User-facing completion format Keep the handoff short: ```text 处理完成。 路径：诊断 → [实际步骤] → 验收 结果： 对比： 备注： ``` Embed or attach the final image and board when the interface supports it; do not only print filesystem paths if the user cannot access those paths.