/lhm-sch-read-exec

name: lhm-sch-read-exec
description: |
  CLI tool and Agent Playbook for LHM schedule migration (schedule reading and conversion).
  Provides both a standalone CLI (`lhm-scheduler`) and an Agent-driven workflow guide.

  Triggers: lhm-scheduler commands, schedule migration tasks, PostInnerReader,
  GetInnerReadAsyncResult, PostInnerConvert, GetInnerConvertAsyncResult,
  or any request interacting with the LHM Inner Scheduler API — even without explicitly mentioning "LHM".
  Conversion-only triggers include "直接转换" (convert directly), "跳过探查" (skip exploration),
  and "只跑转换阶段" (run only the conversion stage).

  Do not trigger for: DataCheck workflows, DDL translation, SQL conversion, or other
  non-schedule-migration tasks.

LHM Scheduler CLI & Agent Playbook

This Skill is **Agent-driven**. The `lhm-sch-read-exec` CLI exposes **stateless single-step commands**: each command makes **exactly one** API call, prints structured JSON status, and exits. There is **no polling loop inside** — the **Agent** is responsible for waiting between polls and re-invoking the poll command based on the returned `status` and exit code. State (such as `task_id`) is passed explicitly via command-line arguments; the CLI itself persists nothing.

CLI Usage

Environment Prerequisites

**The environment and credentials have already been prepared by [lhm-sch-env](../lhm-sch-env/SKILL.md) at session start; this skill performs no environment validation whatsoever.** Simply run the business commands — do not run validation scripts, do not run `validate`, and do not re-confirm credentials or prompt the user about configuration.

> ⛔ **The one exception — the `aliyun-cli-lhm` plugin (hard stop)**: `read-start`, `convert-start`, and every polling command below reach the service through `aliyun lhm <command>`, so the plugin (>= 0.1.1, i.e. `~/.aliyun/plugins/aliyun-cli-lhm/manifest.json` exists) must be present. If it is not, **stop immediately**: report the environment error verbatim and terminate. > > Do **not** ask the user to choose a data source, resolve an ambiguity, or supply any conversion parameter — those clarifications are meaningful **only once the plugin is confirmed available**, because without it no `read-start` call can ever return a candidate list to disambiguate. Do **not** run `uv tool install` or `lhm-scheduler`: this CLI shells out to `aliyun lhm`, so a successful install is never proof that the flow can proceed, and never report an exploration or conversion result that did not come from a real call.

Only when a command actually reports an environment-class error (e.g., credentials not found, command not found) should it be handed to [lhm-sch-env](../lhm-sch-env/SKILL.md); when relaying its guidance, **never write secrets on behalf of the user, and never echo secret values**.

Status Code & Exit Code Contract

Each single-step command outputs a JSON object with a `status` field to **stdout** and exits with an exit code; the Agent branches on them:

| `status` | Exit code | Meaning | Agent action | |----------|-----------|---------|--------------| | `started` | `0` | The start step was accepted; the task is running | Proceed to the corresponding `*-poll` step | | `running` | `3` | Poll step — the task is still in progress | **Wait about 20 seconds, then re-invoke the same poll command** | | `completed` | `0` | Poll step — the task completed successfully | Proceed to the next step / render results | | `ambiguous` | `2` | The data source name matched multiple candidates (E610R1002) | Show the `candidates` to the user and rerun start with the exact name | | `failed` | `2` | Unrecoverable business error | Report `err_code` + `err_message` and abort | | `failed` (SDK_ServiceUnavailable) | `2` | **API-level transient server fault** (HTTP 503) | **Abort the flow immediately** and tell the user "The LHM service is temporarily unavailable; please retry later or contact operations to check the service status"; do not auto-retry | | *(config error)* | `1` | Missing credentials / invalid configuration | Fix the environment and retry |

Commands

Single-Step Migration Commands

# 1. Start exploration (PostInnerReader)
lhm-sch-read-exec read-start --source <SOURCE_DS_NAME>

# 2. Poll exploration results (GetInnerReadAsyncResult) — repeat while exit code is 3
lhm-sch-read-exec read-poll --source <SOURCE_DS_NAME>

# 3. Trigger conversion (PostInnerConvert) — returns task_id
lhm-sch-read-exec convert-start --source <SOURCE_DS_NAME> --target <TARGET_DS_NAME> [--sql-convert-map <JSON_MAP>]

# 4. Poll conversion results (GetInnerConvertAsyncResult) — repeat while exit code is 3
lhm-sch-read-exec convert-poll --task-id <TASK_ID> [--output-format text|json]

**Common options** (all commands): `--endpoint URL` / `--region ID` — attached to every `aliyun lhm` call as fixed parameters; they override the values read from the config file's `lhm` section (`lhm.endpoint` / `lhm.region_id`), which in turn fall back to the `LHM_ENDPOINT` / `REGION_ID` environment variables and then built-in defaults.

**`convert-poll --output-format`** (default `json`): when the step is `completed` and `text` is selected, the §5.4-format summary (downloaded from `metadata/convert_statistics.json` inside the result zip) is also printed to **stderr**, while the JSON status goes to stdout.

Agent Orchestration Flow

The Agent drives the full migration by chaining single-step commands. Polling is the Agent's responsibility:

Special Logic: Convert-Only Mode

If the user's semantics clearly indicate **conversion only** (e.g., "convert directly", "skip exploration", "run only the conversion stage"; the Chinese equivalents are declared in the frontmatter description), and the user has provided explicit source and target data source names, the Agent **may skip steps 1 and 2 (the exploration stage)** and start directly from step 3 (`convert-start`).

**Applicability conditions:**

• The user's intent is clear