# 知一 MML解析工具 AI workflow protocol

Technical skill id: `mml-parser-zhiyisoft`  
Protocol version: `1.7`  
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.

Before launching the client EXE, the compiled Bridge locates the installed Skill root and independently hashes the identity-critical files for either the Full profile (six files) or Community profile (four files). Caller-supplied identity fields are overwritten. The EXE binds the profile, canonical content SHA-256, and file count into the request digest; the cloud independently computes the expected identity from the currently published official Skill ZIP and fails closed on any mismatch.

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.

For GUI and Skill/MCP trial enrollment, the server verifies the exact decrypted JSON object before Pydantic/default reconstruction. Signed fields such as `schema_version` and `sent_at_utc` must not be discarded, and absent optional fields must not be materialized before canonical RSA verification.

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.

Compatible-mode boundary: content attestation proves that the installed Skill files exactly match a cloud-published official package. Generic MCP does not provide cryptographic provenance for the prompt or Skill that caused a tool call, so this mode does not distinguish a third-party orchestrator that deliberately reuses an unmodified official Skill installation. Do not describe content attestation as upstream-agent identity authentication.
