opencli-generate

CLI-GENERATE — Verified CLI Generation Skill

One-shot automated CLI generation: give a URL, get a verified command or a structured explanation of why not.

When to Use This Skill

User says "帮我生成 xxx.com 的 cli" or similar
User wants to add a website to opencli automatically
User provides a URL and expects a working CLI command

Not for: manual API exploration (use opencli-explorer), single-page quick generation (use opencli-oneshot), or browser-based debugging (use opencli-operate).

Input

Field	Required	Type	Description
`url`	Yes	string	Target website URL
`goal`	No	string	Natural language intent hint (e.g. "热榜", "搜索", "最新帖子")

goal is a user-intent hint, not a command name, capability schema, or execution parameter.

How to Invoke

opencli generate <url> [--goal <goal>] [--format json]

The skill calls generateVerifiedFromUrl internally. The agent does not need to know about explore, synthesize, cascade, or verify stages.

Output: SkillOutput

interface SkillOutput {
  // Machine-readable decision fields (agent uses these for routing)
  conclusion: 'success' | 'blocked' | 'needs-human-check';
  reason?: StopReason | EscalationReason;
  suggested_action?: SuggestedAction;
  reusability?: Reusability;

  // Structured data
  command?: string;      // e.g. "demo/hot"
  strategy?: string;     // "public" | "cookie"
  path?: string;         // YAML artifact path

  // Human-readable summary (agent can relay to user directly)
  message: string;
}

Decision Language (shared with code layer)

StopReason (blocked):

no-viable-api-surface — site has no discoverable JSON APIs
auth-too-complex — all endpoints require auth beyond PUBLIC/COOKIE
no-viable-candidate — APIs found but no valid CLI candidate synthesized
execution-environment-unavailable — browser not connected

EscalationReason (needs-human-check):

empty-result — pipeline ran but returned nothing
sparse-fields — result has too few populated fields
non-array-result — result is not an array
unsupported-required-args — candidate needs args we can't auto-fill
timeout — execution timed out
selector-mismatch — DOM/JSON path didn't match
verify-inconclusive — catch-all for ambiguous verify failures

SuggestedAction (what to do next):

stop — nothing more to try
inspect-with-operate — use opencli-operate skill to debug
ask-for-login — user needs to log in first
ask-for-sample-arg — user needs to provide a real argument value
manual-review — general human review needed

Reusability (is the artifact worth keeping?):

verified-artifact — fully verified, can be used directly
unverified-candidate — candidate exists but not verified
not-reusable — nothing worth keeping

Decision Tree

Input: url + goal?
  |
  v
Call generateVerifiedFromUrl(url, goal)
  |
  v
Receive GenerateOutcome
  |
  +-- status = 'success'
  |     conclusion: 'success'
  |     reusability: 'verified-artifact'
  |     command: outcome.adapter.command
  |     strategy: outcome.adapter.strategy
  |     path: outcome.adapter.path
  |     message: "已生成 {command}，可直接使用 (策略: {strategy})"
  |     → END
  |
  +-- status = 'blocked'
  |     conclusion: 'blocked'
  |     reason: outcome.reason
  |     message: (see message templates below)
  |     → END
  |
  +-- status = 'needs-human-check'
        conclusion: 'needs-human-check'
        reason: outcome.escalation.reason
        suggested_action: outcome.escalation.suggested_action
        reusability: outcome.reusability
        path: outcome.escalation?.candidate?.path  (optional, only when reusable candidate exists)
        message: (see message templates below)
        → END (upper-level agent decides next step)

Message Templates

conclusion	reason	message
`success`	—	"Generated {command}, ready to use. Strategy: {strategy}"
`blocked`	`no-viable-api-surface`	"No usable JSON API endpoint found on this site, cannot auto-generate CLI"
`blocked`	`auth-too-complex`	"All endpoints require authentication methods beyond automation capabilities (such as signature/bearer), cannot auto-generate"
`blocked`	`no-viable-candidate`	"API endpoints found, but failed to synthesize a valid CLI candidate"
`blocked`	`execution-environment-unavailable`	"Browser not connected, please run opencli doctor first to check the environment"
`needs-human-check`	`unsupported-required-args`	"Candidate requires parameter {args}, please provide example values and retry"
`needs-human-check`	`empty-result`	"Candidate validation returned empty results, suggest checking with opencli-operate"
`needs-human-check`	`sparse-fields`	"Candidate validation results have insufficient fields, suggest manual inspection"
`needs-human-check`	`non-array-result`	"Returned result is not in array format, suggest using opencli-operate to check the endpoint response structure"
`needs-human-check`	`timeout`	"Validation timed out, suggest using opencli-operate to manually check the endpoint response"
`needs-human-check`	`selector-mismatch`	"Data path mismatch, suggest using opencli-operate to check the actual response structure"
`needs-human-check`	`verify-inconclusive`	"Validation result is uncertain, candidate has been saved at {path}, manual review required"

Guardrails

Skill does not orchestrate internal pipeline stages. It does not decide whether to explore, synthesize, cascade, or verify. That is the code layer's job.
Skill does not auto-escalate to operate. When needs-human-check, skill reports the recommendation but does not automatically invoke opencli-operate. The upper-level agent decides.
No new taxonomy. All reason, suggested_action, reusability values are shared with the code layer (GenerateOutcome). Skill does not invent new status words.
Machine-readable fields are the contract; message is just a summary. Callers must not parse message for decision-making.
goal is a natural language intent hint. Not a command name, not a capability schema, not an execution parameter.

Relationship to Other Primitives

P1: Terminal Contract (`GenerateOutcome`)

Skill's single source of truth for final decisions
Skill maps GenerateOutcome → SkillOutput (thin translation, no re-orchestration)

P2: Early-Hint Contract (`EarlyHint`)

Lives inside the orchestrator, transparent to skill
Drives early exit (cost optimization) before verify stage
Skill does not consume EarlyHint directly in v1
May be exposed as optional progress channel in future versions

v1 Scope

JSON API + PUBLIC/COOKIE auth + structured array result + read-only list-like capabilities
Single browser session lifecycle (probe + verify share one session)
Bounded repair: only itemPath relocation, one attempt