cli-anything-cvviewer 0.1.0

CLI-Anything harness for the CVViewer Qt desktop application.

cli-anything-cvviewer

Python Click CLI harness for the CVViewer Qt desktop application.

Install

From PyPI, use pipx for an isolated command-line installation:

pipx install cli-anything-cvviewer

Then verify the command:

cli-anything-cvviewer --json contract check

For local development, install from agent-harness:

python -m pip install -e .

If your current directory is agent-harness\cli_anything\cvviewer, the same command is also supported:

python -m pip install -e .

Publish to PyPI

Release from agent-harness only:

cd E:\QT\CVViewer\agent-harness
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload --repository testpypi dist/*
python -m twine upload dist/*

Use __token__ as the username when twine upload asks for credentials, and paste the PyPI API token as the password. Bump the version in setup.py and cli_anything\cvviewer\__init__.py before every new upload; PyPI rejects reusing the same version.

The package includes the built-in scenario files under cli_anything\cvviewer\scenarios. Runtime artifacts such as runs, tasks, dist, and *.egg-info should not be uploaded or committed.

Commands

cli-anything-cvviewer --json info --source E:\QT\CVViewer
cli-anything-cvviewer --json project open E:\QT\CVViewer --role loader
cli-anything-cvviewer --json status --project E:\QT\CVViewer\.cvviewer-cli-session.json
cli-anything-cvviewer --json export --project E:\QT\CVViewer\.cvviewer-cli-session.json --format json --output E:\tmp\cvviewer-summary.json
cli-anything-cvviewer --json doctor env
cli-anything-cvviewer --json doctor cvviewer --source E:\QT\CVViewer
cli-anything-cvviewer --json doctor webapi
cli-anything-cvviewer --json webapi routes
cli-anything-cvviewer --json webapi health --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi version --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi protocol --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi errors --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi task-status --task-no T001 --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi task-events --task-no T001 --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi validate task-pack --file E:\tmp\task-pack.json
cli-anything-cvviewer --json webapi validate task-pack --file agent-harness\scenarios\pack-add-order.json
cli-anything-cvviewer --json webapi post task-pack --file E:\tmp\task-pack.json --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi smoke --role loader --host 127.0.0.1
cli-anything-cvviewer --json contract check
cli-anything-cvviewer --json contract export
cli-anything-cvviewer --json scenario list
cli-anything-cvviewer --json scenario show pack-add-order
cli-anything-cvviewer --json scenario validate pack-add-order
cli-anything-cvviewer --json scenario create-task pack-add-order --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task create --route task-pack --file agent-harness\scenarios\pack-add-order.json --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task create --route task-pack --file E:\tmp\task-pack.json --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task submit agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task start agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task status agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --events
cli-anything-cvviewer --json task replay agent-harness\tasks\T001.json
cli-anything-cvviewer --json task wait agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --timeout 30
cli-anything-cvviewer --json webapi post task-pack --file E:\tmp\task-pack.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json run list --root agent-harness\runs
cli-anything-cvviewer --json analyze run agent-harness\runs\RUN_ID
cli-anything-cvviewer --json analyze runs --root agent-harness\runs
cli-anything-cvviewer --json diagnose run agent-harness\runs\RUN_ID
cli-anything-cvviewer report run agent-harness\runs\RUN_ID --format html --output E:\tmp\cvviewer-run-report.html
cli-anything-cvviewer --json report run agent-harness\runs\RUN_ID --format json --output E:\tmp\cvviewer-run-report.json
cli-anything-cvviewer --json report run agent-harness\runs\RUN_ID --format zip --output E:\tmp\cvviewer-run-report.zip
cli-anything-cvviewer --json workflow check-runtime --host 127.0.0.1 --port 8090 --role loader
cli-anything-cvviewer --json workflow inspect-task agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --events
cli-anything-cvviewer --json workflow run-scenario pack-add-order --host 127.0.0.1 --port 8090 --tasks-root agent-harness\tasks --run-root agent-harness\runs --report E:\tmp\cvviewer-workflow-report.html

Scope

This harness inspects project metadata and can probe CVViewer's existing Web API when loader.exe or unloader.exe is already running. It does not modify Qt C++ source and does not run CMake, npm, or pnpm.

Future algorithm commands should call a real CVViewer C++ backend executable rather than reimplementing PCL, Modbus, ZeroMQ, or cargo-placement logic in Python.

Web API Routes

Known route names:

• start-pack: /api/vision/startPack, loader default port 8090
• task-pack: /api/vision/taskPack, loader default port 8090
• start-unpack: /api/vision/startUnPack, unloader default port 8092
• task-unpack: /api/vision/taskUnPack, unloader default port 8092
• vision-data: /webapi/visionData, default port 8090
• health: GET /api/vision/health
• version: GET /api/vision/version
• protocol: GET /api/vision/protocol
• error-codes: GET /api/vision/errorCodes
• task-status: GET /api/vision/taskStatus?taskNo=...
• task-events: GET /api/vision/taskEvents?taskNo=...

webapi validate checks required fields locally before sending. webapi post sends the JSON payload to the running CVViewer process. webapi smoke sends a minimal startPack or startUnPack request for connectivity probing. The read-only commands query a running CVViewer process without emitting Qt signals or sending task mutation payloads.

Automation Workflow

The expanded CLI-side workflow keeps CVViewer as the source of truth while making interface test evidence repeatable:

• contract check/export: inspect the static CLI-side protocol contract.
• doctor env/cvviewer/webapi: run read-only checks for Python/Click/CLI installation, CVViewer source layout, and static Web API assumptions.
• webapi post --run-root: send a request and persist meta.json, request.json, and response.json under a run directory.
• scenario list/show/validate/create-task: discover standard payloads, inspect them, validate them against a Web API route, and turn them into local task records.
• task create: create a local task record from a payload file.
• task submit: send the task payload to its configured route and optionally save run evidence.
• task start: send startPack or startUnPack with taskNo and optionally save run evidence.
• task status/replay/wait: inspect the local task record, print the payload for replay, and optionally query/wait on CVViewer's read-only task status API.
• run list/show: inspect saved run records.
• analyze run/runs: normalize raw run evidence into stable facts and summarize pass/fail categories across a run root.
• diagnose run: classify deterministic failures such as connection refused, timeout, missing required fields, HTTP errors, and known CVViewer response codes.
• report run: generate Markdown, HTML, JSON, or ZIP reports from a run directory. ZIP reports include rendered report files plus raw artifacts.
• workflow check-runtime: call read-only runtime APIs and surface protocol completeness warnings.
• workflow inspect-task: combine a local task record with optional runtime taskStatus/taskEvents.
• workflow run-scenario: validate a standard scenario, create a local task, submit/start it, collect status/events, analyze evidence, diagnose failures, and optionally export a report.

Scenarios

agent-harness/scenarios/pack-add-order.json is the repository copy of a small standard task-pack payload for装车加单 workflows. PyPI installations also ship the same built-in payload under cli_anything/cvviewer/scenarios, so scenario list, scenario show, scenario validate, and workflow run-scenario work without a source checkout.

Recommended standard flow:

cli-anything-cvviewer --json scenario list
cli-anything-cvviewer --json scenario validate pack-add-order
cli-anything-cvviewer --json scenario create-task pack-add-order --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task submit agent-harness\tasks\pack-add-order-demo.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task start agent-harness\tasks\pack-add-order-demo.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json analyze runs --root agent-harness\runs
cli-anything-cvviewer --json workflow run-scenario pack-add-order --host 127.0.0.1 --port 8090 --tasks-root agent-harness\tasks --run-root agent-harness\runs

CVViewer-side read-only APIs such as /api/vision/health, /api/vision/version, /api/vision/protocol, /api/vision/errorCodes, /api/vision/taskStatus, and /api/vision/taskEvents can be queried through the webapi command group when loader.exe or unloader.exe is running.

Task Management Limits

task commands are intentionally CLI-side orchestration helpers. They do not delete or mutate CVViewer internal state, and they do not invent a completion status that CVViewer has not reported. Without --host, task status reports local CLI evidence only. With --host, task status and task wait query the running CVViewer read-only task APIs.