CLI自动化框架

Explore web workflow (requires LLM)

cliany-site explore "https://github.com" "Search and view results" --json

Fail fast if all rows are empty or required fields are blank

cliany-site browser extract \ --selector ".result-card" \ --mode list \ --fields-json '{"title": ".title", "url": "a@href"}' \ --strict-quality \ --json ```

Structured extraction responses include data.quality. Generated list-, search-, read-, and extract- adapter commands, plus any command containing an extract action, enforce that summary. Their expects_nonempty contract defaults to true: zero data, missing required fields, and partial rows return E_EMPTY_RESULT. A command may declare expects_nonempty=false only when zero matches are a valid outcome; it then returns ok=true for that outcome while retaining data.quality as the machine-readable row-count and data-quality signal. For failed structured object rows, data.quality.field_blank_rows identifies the affected 1-based row numbers for each missing or blank field, so a field mapping or page-content problem can be located without guessing. Re-running explore for a command applies this rule to its newly generated code, but existing installed adapters are not silently rewritten. Missing required fields and partial results, including partially missing required fields, remain failures even when zero matches are permitted, so automation can distinguish "command ran", "no matching data was expected", and "data needs review".

Installation

```bash

Install via PyPI

pip install cliany-site

Or install from source

git clone https://github.com/pearjelly/cliany.site.git cd cliany.site pip install -e . ```

Server and Docker Browser Setup

--headless and --cdp-url are root CLI options, so they must appear before the command they configure, including explore and serve.

```bash

1. Install Obscura binary (version >= 0.1.0)

cliany-site obscura install 0.1.0 --json

1. Install adapter

cliany-site market install https://github.com/pearjelly/cliany.site/releases/download/v0.14.1/demo.suiteondemand.com-0.14.1.cliany-adapter.tar.gz --sha256 1671dd92d3828cecb1f04f41eefceb7bdc727d0dee1f35d4f14ca360432ced31

2. Strictly verify the installed adapter before login or replay

cliany-site verify demo.suiteondemand.com --strict --json

ASF Jenkins (Build Status)

cliany-site market install https://github.com/pearjelly/cliany.site/releases/download/v0.14.1/builds.apache.org-0.14.1.cliany-adapter.tar.gz --sha256 b09710acbabfb5465a6e04b5b140a4ffa4aa24795a2b4ada60eeabbddddea0c2
cliany-site verify builds.apache.org --strict --json
cliany-site builds.apache.org list-jobs --json

Disclaimer: These demo sites are operated by third parties and may be temporarily unavailable. cliany-site only provides the CLI shim; we do not control the demo data or uptime.

{"status":"ok","service":"cliany-site","version":"<installed-version>"}

curl -i http://localhost:8080/doctor

Preflight or install a publisher-provided remote package with a pinned digest

cliany-site market install https://publisher.example/releases/github.com-1.0.0.cliany-adapter.tar.gz --sha256 <64-hex-sha256> --dry-run --json

A successful dry run only validates the package. Remove --dry-run to install before verify <domain>.

Install adapter after reviewing dry_run, package_sha256, version, installed_version, files, would_replace, would_create_backup, and requires_force

Quick Start (v0.11.0+)

For a guided first run, see 10-minute success path. It guides you from installation through doctor to maintained cases, then points successful users toward the Real Demo Case Proposal path for contributing new public read-only cases.

For upcoming work, see the user-facing public roadmap and the maintainer Q3 roadmap.

Usage Examples

Discover maintained real demo cases

cliany-site cases --json cliany-site cases --status candidate --promotion-plan cliany-site cases --json --status candidate --promotion-plan cliany-site cases --case-id pypi-project-search --json cliany-site cases --case-id pypi-project-search --issue-template cliany-site cases --case-id pypi-project-search --evidence-bundle cliany-site cases --case-id pypi-project-search --evidence-bundle --json

Try Real Demos

The following adapters are available as downloadable assets on GitHub Release v0.14.1. The maintained case index lives in cases/README.md and cases/manifest.json. The install commands below use the published HTTPS asset and its release SHA-256. Add --dry-run --json first when you want to verify a package without installing it. For the doctor-guided active demo path, execute data.summary.demo_adapter_quickstart.recommended_commands, not the compatibility commands list: it uses verify --strict, so a static validation failure, including a missing or unloadable commands.py, exits nonzero and prevents the following read-only command from running in a sequential script. An occupied install target starts at that gate and never triggers an automatic overwrite. The compatibility verify_command remains available for diagnostic, exit-zero reporting. For a human first run, cliany-site doctor now prints that same three-command path when the active demo target is absent: fixed-SHA published install, verify --strict, then the read-only command. It only prints guidance; it never installs, executes, or overwrites an adapter for the user. Use cliany-site cases --json to inspect active demos, candidate workflows, offline validation commands, and candidate promotion next actions from the CLI; promotion_evidence_summary.primary_next_task points automation at the first candidate task to advance, while promotion_evidence_summary.primary_next_task_acceptance_criteria states the proof required for that task. Add --promotion-plan to print the candidate promotion queue across all matched candidates; combine it with --json to read promotion_plan.primary_next_item, promotion_plan.primary_runbook, promotion_plan.primary_issue_template_command, per-candidate primary tasks, the expected release asset name in expected_adapter_package, per-candidate issue_template_json_command, and the incomplete task_queue. Use cliany-site cases --case-id pypi-project-search --json to open one case with validation and promotion details, including promotion_command_plan_summary; omit --json for a copy-friendly human handoff with Promotion Tasks. The candidate human handoff also renders preflight_required, preflight_blocker, and runbook_first, so contributors see the live LLM gate before starting a real explore. Add --issue-template to print a GitHub issue body for a candidate promotion task, including Acceptance Criteria, expected_adapter_package, a Primary Runbook, LLM preflight Command SHA-256, Promotion Command Plan Summary, Promotion Command Plan command_sha256 sub-lines plus source / missing metadata, standard LLM/doctor blocker comments, Doctor Preflight Evidence Fields, and a Doctor Preflight Evidence Template with paste-ready placeholders for cliany-site doctor --llm-live --require-capability generate_adapters --json output; combine it with --json to also read issue_template_primary_task, issue_template_promotion_command_plan_summary, the same acceptance, runbook, preflight fields, structured doctor_preflight_evidence_template, plus doctor_preflight_evidence_template_field_count / doctor_preflight_evidence_template_sha256 without parsing Markdown. Add --evidence-bundle to print a structured local evidence checklist; combine it with --json for a machine-readable evidence bundle, including promotion_command_plan_summary and a promotion_command_plan that starts with llm_live_preflight before adapter package, metadata validation, and online smoke commands, per-step promotion_command_plan[*].command_sha256 drift checks, primary_next_task_runbook and primary_next_task_runbook_first_command for the current ordered checklist, llm_live_preflight_required, llm_live_preflight_command_sha256, doctor_preflight_evidence_fields, doctor_preflight_evidence_template, doctor_preflight_state_fields, doctor_preflight_state_statuses, and the template/state count/hash aliases on the adapter package task, expected_adapter_package for the package artifact, plus acceptance_criteria for the proof each evidence task must attach. Use python scripts/plan_next_iteration.py --issues-dir /tmp/cliany-candidate-issues to generate reviewable candidate issue artifacts; planner JSON exposes candidate_promotions[*].issue_template_command, candidate_promotions[*].issue_template_json_command, candidate_promotions[*].promotion_command_plan_summary, candidate_promotions[*].doctor_preflight_evidence_template, candidate_promotions[*].doctor_preflight_state_statuses, and template/state hash aliases, while issue-metadata.json and the artifacts README show the same Issue Template / Issue Template JSON handoff and promotion_command_plan_summary alongside Primary Evidence Status, Primary Acceptance Criteria, primary_next_task_acceptance_criteria, compact case_promotion_evidence_primary_runbook_steps / hash fields, case_promotion_evidence_primary_runbook_first_command, case_promotion_evidence_primary_llm_live_preflight_required, case_promotion_evidence_primary_llm_live_preflight_command_sha256, case_promotion_evidence_primary_llm_live_preflight_blocker_comment, case_promotion_evidence_primary_doctor_preflight_blocker_comment, case_promotion_evidence_primary_doctor_preflight_evidence_template_sha256, case_promotion_doctor_preflight_evidence_template_sha256, doctor_preflight_evidence_fields, doctor_preflight_state_fields, doctor_preflight_state_statuses, required_labels, required_label_count, required_labels_sha256, and case_promotion_llm_live_preflight_evidence_fields count/hash aliases before maintainers create issues or compare artifact drift. Candidate human output labels an eventual adapter command as not runnable until its package has been published and installed and verify --strict has passed; it is never an active demo quick command. When planner artifacts include --doctor-json, their public issue body uses the same distinction: attached doctor preflight evidence is shown separately from pending adapter package evidence, and a blocked provider produces a recovery-and-rerun handoff without making candidate explore runnable. --promotion-plan --json also mirrors doctor template drift metadata onto promotion_plan.primary_doctor_preflight_evidence_template_field_count, promotion_plan.primary_doctor_preflight_evidence_template_sha256, promotion_plan.primary_llm_live_preflight_command_sha256, each candidate's primary_doctor_preflight_evidence_template_sha256, and each incomplete task_queue[*].doctor_preflight_evidence_template_sha256 / task_queue[*].llm_live_preflight_command_sha256, so queue-only bots can compare the current doctor evidence contract without opening a full evidence bundle. scripts/validate_cases.py --json now carries the same drift signal on promotion_evidence_summary.primary_next_task.doctor_preflight_evidence_template_sha256 plus the doctor_preflight_state_fields / doctor_preflight_state_statuses contract; scripts/validate_cases.py --report renders primary_doctor_preflight_evidence_template_field_count and primary_doctor_preflight_evidence_template_sha256 in the Candidate Promotion Evidence Summary table; plain scripts/validate_cases.py --strict also prints promotion_evidence_primary_doctor_preflight_evidence_template_field_count, promotion_evidence_primary_doctor_preflight_evidence_template_sha256, and promotion_evidence_primary_llm_live_preflight_command_sha256 for stdout-only validation logs. Evidence bundles also expose doctor_preflight_evidence_selectors, mapping semantic fields such as checks[llm_live].details.error_code to actual doctor JSON selectors such as data.checks[name="llm_live"].details.error_code; doctor_preflight_state_statuses mirrors the extractor states ready, blocked, and missing_fields. The doctor_preflight_state_fields contract lists preflight_state.status, preflight_state.ready_for_adapter_package, preflight_state.primary_reason, preflight_state.reason_codes, and preflight_state.next_action; doctor_preflight_state_statuses is limited to ready, blocked, and missing_fields, so README-only maintainers can tell whether to continue to explore or attach blocker evidence first. Candidate promotion treats summary.capabilities.run_browser_workflows.ready=false, summary.llm_live_preflight.ready=false, generate_adapters.ready=false, or any llm_live warning/error such as E_LLM_UNAVAILABLE provider connection failures as blocker evidence; keep adapter_package pending or blocked instead of fabricating adapter package proof. When the live gate blocks promotion, save the doctor result with cliany-site doctor --llm-live --require-capability generate_adapters --json > /tmp/cliany-doctor-preflight.json, then run cliany-site cases --case-id pypi-project-search --evidence-bundle --doctor-json /tmp/cliany-doctor-preflight.json --json or cliany-site cases --case-id pypi-project-search --issue-template --doctor-json /tmp/cliany-doctor-preflight.json; the output includes doctor_preflight_evidence_values, doctor_preflight_evidence_ok, doctor_preflight_evidence_missing_count, doctor_preflight_evidence_null_count, doctor_preflight_evidence_null_fields, and doctor_preflight_state on the bundle and primary adapter_package task. A nullable field is present in doctor JSON with value null; a missing field has no matching selector, so automation can handle connection-level failures without conflating them with schema drift.

To keep already-open candidate issues aligned with the current strict handoff, run python scripts/audit_candidate_issues.py --repo pearjelly/cliany.site --json. It is read-only by default and reports current, stale, missing, duplicate, and unexpected labeled issue states with body hashes. When a saved live-preflight result is available, add --doctor-json /tmp/cliany-doctor-preflight.json so the audit compares bodies against that exact gate state and includes its source path, value hash, and runnable state in local JSON output. Public issue bodies retain the value hash and extracted gate evidence, but omit the local source path. When that evidence is attached, the primary task labels package evidence separately and tells contributors to wait for provider recovery before rerunning the strict preflight; it never turns a blocked preflight into package or explore evidence. The human-readable report also prints an unexpected issue's actual title and URL so the blocker can be located without parsing JSON. Only use --apply --confirm-rewrite after reviewing stale bodies and resolving missing, duplicate, or unexpected issues; it will not create, close, or promote issues.

If a stale public candidate issue already contains a Doctor Preflight Evidence snapshot, audit_candidate_issues.py --apply --confirm-rewrite refuses to replace it without the current --doctor-json; the JSON report returns doctor_json_required_before_rewrite and lists the protected issue numbers. This prevents a no-evidence placeholder template from erasing a real blocker snapshot.

If the GitHub API or network is unavailable while auditing, the JSON result returns retryable E_GITHUB_UNAVAILABLE with a retry action. Treat that as “remote issue state not read”, not as missing; do not run --apply until a later read succeeds.

The doctor evidence contract includes summary.capabilities.generate_adapters.local_ready and summary.capabilities.generate_adapters.local_blockers. These fields show whether local prerequisites remain healthy when the live provider is blocked; they do not replace summary.llm_live_preflight.ready=true as the gate for candidate explore.

When the audit reports a missing candidate issue, read its issue_template_command (for example cliany-site cases --case-id pypi-project-search --issue-template --json) and review the generated body before creating anything. The audit only supplies the handoff; it never creates a public issue.

If the GitHub GraphQL request ends with an EOF, the audit reports retryable E_GITHUB_UNAVAILABLE rather than synthesizing issue state. Wait for the remote API and rerun; do not apply changes while the issue list was not read.

SuiteCRM Demo (Enterprise CRM)

```bash

3. Login (opens browser — use demo account from https://demo.suiteondemand.com/)

cliany-site login https://demo.suiteondemand.com/

Check environment

cliany-site doctor --json

Configuration

```bash

Verify Environment

cliany-site doctor --json
cliany-site doctor --llm-live --require-capability generate_adapters --json

By default, doctor checks local configuration, CDP, directories, and keys without calling the LLM provider. data.summary.ready_for_explore and data.summary.capabilities.generate_adapters.local_ready remain local configuration signals; local_blockers explains only those local prerequisites, while live_blockers separately reports an omitted or failed provider preflight. Automation must require data.summary.ready_for_live_explore=true (or the equivalent capability field) before a real explore. A retryable provider failure can therefore leave local_ready=true while overall ready=false and live_blockers=["llm_live"]. The capability's next_step gives the exact strict retry command. Before a longer explore, use --llm-live --require-capability generate_adapters for a strict provider gate; a missing key returns nonzero with E_LLM_DISABLED, an upstream outage returns E_LLM_UNAVAILABLE, and both preserve the full checks in error.details. Ordinary doctor --json also returns a stable code such as E_CDP_UNAVAILABLE when a hard check fails, instead of collapsing the diagnostic into E_UNKNOWN. Human output names the missing-key configuration fix separately from an upstream retry.

Optional live provider preflight for automation before explore

curl -i "http://localhost:8080/doctor?llm_live=true&require_capability=generate_adapters" curl -i http://localhost:8080/adapters

Python SDK

import asyncio

from cliany_site.sdk import ClanySite


async def main():
    async with ClanySite() as cs:
        result = await cs.verify("github.com")

    if not result["success"]:
        error = result["error"] or {}
        raise RuntimeError(f"{error.get('code')}: {error.get('message')}")

    print(result["data"]["results"][0])


asyncio.run(main())

SDK methods return the standard {success, data, error} envelope. doctor() now exposes the same structured checks and summary contract as the CLI, including stable hard-blocker error codes and error.details diagnostics. It does not call a provider by default; use doctor(llm_live=True, require_capability="generate_adapters") only when an automation explicitly needs the live preflight before explore. llm_live must be an actual Python boolean: strings, numbers, and None return E_INVALID_PARAM before CDP or provider checks, so a truthy string cannot accidentally start a live preflight. explore(url, workflow_description) requires a non-blank text workflow and navigate(url) accepts only whitespace-free HTTP(S) URLs with a host; invalid input returns an error envelope before creating an explorer or browser session. Direct SDK control values are equally strict: explore(force=...), execute(..., params=..., dry_run=..., sandbox=...), and list_adapters(detail=...) reject malformed values with E_INVALID_PARAM before adapter lookup or browser work. save_session(domain) also accepts only a host with an optional valid port, rejecting credentials, paths, whitespace, and invalid ports before it opens Chrome. The synchronous execute() helper also accepts sandbox=True and forwards the same local preflight. verify(domain) performs the same strict static checks as cliany-site verify <domain> --strict: metadata, generated module safety, manifest integrity, and whether commands.py actually exports a loadable Click group. It does not open Chrome or contact an LLM. An adapter directory, metadata.json, commands.py, manifest, or manifest-declared file that is a symbolic link is rejected as security_issue before its contents are read or a module is imported. Direct root CLI adapter dispatch now also applies the generated-module source scan before importing commands.py: banned patterns and non-UTF-8 modules return E_VERIFY_STATIC with security_issue. When a manifest is present, it also checks every declared file hash before import; a mismatch returns E_VERIFY_STATIC with manifest_error. It returns ADAPTER_NOT_FOUND for an absent adapter and E_VERIFY_STATIC with data.results-compatible diagnostics when verification fails. Run the strict live-provider preflight before calling explore; configured credentials alone are not evidence that adapter generation is available.

The synchronous save_session(domain, cdp_url=..., headless=...) helper has the same host validation and browser configuration path as await ClanySite(...).save_session(domain); it does not bypass Chrome or session safeguards.

HTTP API

Sandbox preflight

Newly generated adapter commands honor root --sandbox before any atom command starts. SDK callers can use execute(domain, command, sandbox=True), while POST /execute accepts a boolean sandbox field. The parameter-resolved action list is checked locally before Chrome starts. Cross-domain navigation, dangerous URL schemes, JavaScript execution, and downloads return E_SANDBOX_VIOLATION / 422; this local result does not prove Chrome, LLM, or third-party workflow readiness.

```bash

Start a local API server with the default Chrome connection

cliany-site serve --port 8080

Call API

curl -i http://localhost:8080/health

Command Reference

Global Options: --json --verbose --debug --cdp-url <ws://host:port> --headless --sandbox --explain --force-browser --diagnose

Ecosystem Integration

• Python SDK — from cliany_site import explore, execute for programmatic calls.
• HTTP API — cliany-site serve --port 8080 starts a REST API service.
• Adapter Marketplace — Pack, install, uninstall, and rollback adapters to share automation capabilities within teams.
• TUI Management Interface — A Textual-based terminal UI for visual adapter management.
• iframe/Shadow DOM — Recursive AXTree collection with cross-origin iframe and Shadow DOM penetration.

Basic Workflow

```bash

1. Explore workflow

cliany-site explore "https://github.com" "Search repository and view README" --json

Include adapter metadata when it is needed by an integration

curl -i "http://localhost:8080/adapters?detail=true" curl -i "http://localhost:8080/verify?domain=github.com" curl -X POST http://localhost:8080/explore \ -H "Content-Type: application/json" \ -d '{"url": "https://github.com", "workflow": "搜索仓库"}' ```

GET /health confirms that the HTTP service is reachable and returns its service name plus installed package version. It is a liveness probe, not proof that CDP or an LLM provider is ready; GET /doctor returns the same structured checks, summary, stable hard-blocker codes, and repair guidance as the CLI. It does not contact the provider unless llm_live=true is explicit; require_capability=generate_adapters requires that flag. GET /adapters?detail=true includes adapter metadata. The llm_live, detail, require_capability, and domain query keys may each appear at most once. llm_live and detail accept only true/false, 1/0, or yes/no; invalid booleans or repeated keys return 400 instead of silently changing the selected response shape, capability, or adapter domain. Unavailable Chrome, LLM, or a required capability returns 503. Choose exactly one browser path: --headless starts Chrome for this process, while --cdp-url connects to an existing remote Chrome. Do not place either option after serve.

GET /verify requires exactly one safe domain query parameter and runs the strict static adapter checks without connecting to Chrome or an LLM. A repeated domain returns BAD_REQUEST / 400; invalid directory names return E_INVALID_PARAM / 400; missing adapters return 404; and an installed adapter with unsafe, missing, unreadable, unloadable, or symbolic-link core files returns E_VERIFY_STATIC / 422 with the cliany-site verify <domain> --strict --json repair path. Before browser startup, POST /execute applies the same local static contract: it rejects a symbolic-link adapter directory, metadata, command module, or manifest before reading or importing it, and a present manifest must have ordinary declared files with matching hashes. This does not prove Chrome, LLM, or third-party workflow readiness. Mutating endpoints accept JSON objects only and reject unknown fields with BAD_REQUEST / 400: POST /explore accepts url, workflow, legacy workflow_description, and force; POST /execute accepts domain, command, params, dry_run, and sandbox; POST /login accepts url. params must be an object, force / dry_run / sandbox must be booleans, and required url, workflow, domain, and command fields must be non-empty strings. For POST /explore and POST /login, url must also be an http or https URL with a host and no whitespace; unsupported schemes, missing hosts, and malformed URLs return BAD_REQUEST / 400 before the SDK or browser runs. Direct ClanySite.explore() and ClanySite.login() use that same URL contract and return INVALID_URL before constructing an explorer or browser session. Arrays, objects, and blank strings return BAD_REQUEST / 400 before reaching the HTTP API SDK boundary, so malformed JSON cannot become an unexpected server error. Other responses preserve the SDK envelope: 503 for unavailable Chrome or LLM dependencies, and 500 for an unexpected server failure.

YAML Workflow Orchestration

```yaml

workflow.yaml

name: GitHub Search Process steps: - name: Search Repository adapter: github.com command: search params: query: "cliany-site" - name: View Details adapter: github.com command: view params: repo: "$prev.data.results[0].name"

Preflight the local adapter package (no runtime writes)

cliany-site market install ~/.cliany-site/packages/github.com-1.0.0.cliany-adapter.tar.gz --dry-run --json

If requires_force is true, use would_replace to confirm presence and compare version with installed_version when available; the dry run stayed read-only, so use --force only when you intend to replace the installed adapter.

cliany-site market install ~/.cliany-site/packages/github.com-1.0.0.cliany-adapter.tar.gz