# 知一 MML解析工具 AI workflow protocol

Technical skill id: `mml-parser-zhiyisoft`  
Protocol version: `1.6`  
Skill/MCP/EXE release: `1.3.8`

The official Skill fallback invokes the bundled `MML解析工具_MCP_Server_V1.3.8.exe` Bridge. MCP uses the same compiled bridge path. The Bridge becomes the direct parent of the client EXE; direct script-to-client invocation is rejected before the request is read.

For every cloud status/preflight operation, the client hashes the verified parent image and the canonical request. The cloud compares the component SHA-256 with its currently published MCP/Bridge release and returns an RSA-signed authorization bound to the device public key, exact component versions, request digest, and a random challenge. The authorization expires after 90 seconds and is consumed once.

Direct parsing CLI remains disabled. Cloud checks EXE, Skill, and MCP versions before identity or quota evaluation; any missing or non-equal component fails closed with HTTP 426.

## Workflow contract

Every response may contain:

- `workflow_stage`: completed/current stage.
- `next_action`: the only valid next operation.
- `must_relay`: whether the AI must explain `user_message` before continuing.
- `user_message`: user-facing explanation or instruction.
- `required_inputs`: values the AI must obtain before the next call.
- `recommended_defaults` and `parameter_options`: valid choices and security-oriented defaults.
- `poll_after_seconds`: minimum suggested job polling interval.
- `user_update_after_seconds`: maximum interval between user-facing progress updates.

Clients must reject or stop on unknown `next_action` values instead of guessing.

## State sequence

| Completed stage | Expected next action |
|---|---|
| `identity_verified` | collect TXT paths, then `mml_preflight` |
| `entitlement_exchange_decision` | ask user, then confirm exchange or stop |
| `entitlement_verified` | `mml_scan_start` |
| `scanning_reports` | poll `mml_job_status` |
| `report_selection` | show all reports and collect explicit selection |
| `parsing` / `exporting` | poll and periodically report progress |
| `completed` | immediately report outputs and statistics |
| any blocked/failed stage | explain and stop |

## EXE actions

### `status`

Require `ai_model_name`, `skill_version`, and MCP integration fields when applicable. Return identity and quota status. On valid identity, require local TXT paths next.

### `preflight`

Require `input_files`, `ai_model_name`, and `request_id`. The EXE resolves files and computes actual sizes; never trust model-provided size numbers. It signs and sends:

- requested file count
- requested file sizes
- total batch bytes
- maximum single-file bytes

If entitlement is sufficient, return `preflight_completed` and direct the client to report scanning. If insufficient and exchangeable, return `overage_consent_required`, the signed offer, and calculation details.

Exactly one TXT is a single-file request, not a batch. Do not apply `batch_bytes_limit`, `batch_file_limit`, or `daily_batch_limit`; continue to apply the single-file limit and projected daily TXT bytes/files. Two or more TXT files form a batch and apply all relevant dimensions.

For confirmed exchange, additionally require literal `overage_consent=true` and the bound one-time `offer_id`. The cloud atomically consumes the offer and activation days. Never synthesize or reuse an offer.

### `scan`

Require the same local inputs after entitlement passes. Revalidate quota, scan report names without exporting, and return `available_reports`. Direct the AI to show the complete list and collect explicit selection.

### `parse`

Require `input_files`, `output_path`, `ai_model_name`, and exactly one report-selection mode:

- non-empty `reports`; or
- `select_all_reports=true` after explicit user choice.

Optional settings and recommended defaults:

- `output_format`: `csv` recommended; alternatives `xlsx`, `db`.
- `split_mode`: `partial` recommended; alternatives `all`, `none`.
- `compress_output`: `false` recommended; alternative `true`.
- `instruction`, `request_id`, and `progress_path`.

If `progress_path` is present, the EXE writes atomic JSON progress with `stage`, `progress_percent`, `status_text`, elapsed time, and polling guidance. The MCP Server reads it; it never estimates progress.

The parse job is created at 0%. Concurrent workers report actual consumed bytes, aggregated across all input files. Whole-job progress reserves 0–95% for parsing and 95–99.5% for export; only successful publication of every final output may set 100%. `stage_progress_percent` reports progress inside the current stage.

Final parse authorization creates or updates the entitlement audit row as `processing`. A signed `ai_skill_parse` result changes it to `completed` and then contributes TXT files/bytes to daily usage; only multi-file successful results contribute one daily batch. A signed `ai_skill_parse_failed` result changes it to `failed` and contributes no daily quota usage. Both result types are idempotent by event/request id and may be retried from the protected local queue.

## Entitlement calculation

The cloud computes the minimum exchange that covers every exceeded dimension. It returns:

- `requested_values`
- `current_limits`
- `required_units_by_dimension`
- `required_units` as the maximum units needed across dimensions
- `unit_days_cost`
- `days_cost = required_units × unit_days_cost`
- `target_limits_after_exchange`
- daily/user caps and minimum remaining-term constraints

The AI must relay the full calculation before asking for consent. Only the native Windows confirmation authorizes the exchange.

## Progress policy

- Poll at `poll_after_seconds`, normally 5 seconds.
- Give user-facing updates at least every `user_update_after_seconds`, normally 30 seconds.
- Report stage changes, failures, and completion immediately.
- Report only returned progress. Do not invent percentages or ETA.
- A running job must never report 100%; 100% means all final outputs were published successfully.

## Security boundary

The EXE and Skill/MCP both sanitize AI-visible responses. They exclude credentials, key material, raw device/hardware identity, customer/order data, input path lists, tracebacks, and logs. TXT bodies never leave the machine; stored path metadata is reduced to basenames.

Plain Python/PowerShell code is orchestration only and is never trusted as a caller identity. Only the cloud-published Bridge/MCP binary hash can obtain authorization. Modified bridges, copied requests, expired authorizations, and replayed authorizations fail closed.
