Back to Details

opencli-generate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLI-GENERATE — Verified CLI Generation Skill

CLI-GENERATE — 经过验证的CLI生成技能

One-shot automated CLI generation: give a URL, get a verified command or a structured explanation of why not.
一站式自动化CLI生成：提供一个URL，即可得到经过验证的命令，或是结构化的失败原因说明。

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
).
  • 用户说出「帮我生成 xxx.com 的 cli」或类似表述
  • 用户想要自动将某个网站添加到opencli中
  • 用户提供URL并期望得到可用的CLI命令
不适用场景：手动API探索（请使用
opencli-explorer
）、单页面快速生成（请使用
opencli-oneshot
）、基于浏览器的调试（请使用
opencli-operate
）。

Input

输入

FieldRequiredTypeDescription
url
YesstringTarget website URL
goal
NostringNatural language intent hint (e.g. "热榜", "搜索", "最新帖子")
goal
is a user-intent hint, not a command name, capability schema, or execution parameter.
字段必填类型描述
url
是string目标网站URL
goal
否string自然语言意图提示（如："热榜", "搜索", "最新帖子"）
goal
是用户意图提示，而非命令名称、能力schema、或执行参数。

How to Invoke

如何调用

bash
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.
bash
opencli generate <url> [--goal <goal>] [--format json]
该技能内部会调用
generateVerifiedFromUrl
，Agent无需了解探索、合成、级联或验证阶段的细节。

Output: SkillOutput

输出：SkillOutput

typescript
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;
}
typescript
interface SkillOutput {
  // 机器可读决策字段（Agent用于路由）
  conclusion: 'success' | 'blocked' | 'needs-human-check';
  reason?: StopReason | EscalationReason;
  suggested_action?: SuggestedAction;
  reusability?: Reusability;

  // 结构化数据
  command?: string;      // 例："demo/hot"
  strategy?: string;     // "public" | "cookie"
  path?: string;         // YAML产物路径

  // 人类可读摘要（Agent可直接转发给用户）
  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
StopReason（阻塞）：
  • no-viable-api-surface
    — 站点没有可发现的JSON API
  • auth-too-complex
    — 所有端点所需的认证方式超出PUBLIC/COOKIE范围
  • no-viable-candidate
    — 已发现API，但未能合成有效的CLI候选
  • execution-environment-unavailable
    — 浏览器未连接
EscalationReason（需要人工检查）：
  • empty-result
    — 流水线已运行但无返回结果
  • sparse-fields
    — 结果填充的字段过少
  • non-array-result
    — 结果不是数组格式
  • unsupported-required-args
    — 候选需要无法自动填充的参数
  • timeout
    — 执行超时
  • selector-mismatch
    — DOM/JSON路径不匹配
  • verify-inconclusive
    — 验证不明确的兜底原因
SuggestedAction（后续操作建议）：
  • stop
    — 无需更多尝试
  • inspect-with-operate
    — 使用opencli-operate技能调试
  • ask-for-login
    — 需要用户先登录
  • ask-for-sample-arg
    — 需要用户提供真实的参数值
  • manual-review
    — 需要人工通用审核
Reusability（产物是否值得保留）：
  • verified-artifact
    — 已完全验证，可直接使用
  • unverified-candidate
    — 存在候选但未经验证
  • not-reusable
    — 无值得保留的内容

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)
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: (见下方消息模板)
  |     → 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  (可选，仅当存在可复用候选时返回)
        message: (见下方消息模板)
        → END (上层Agent决定下一步操作)

Message Templates

消息模板

conclusionreasonmessage
success
—"已生成 {command}，可直接使用。策略: {strategy}"
blocked
no-viable-api-surface
"该站点没有发现可用的 JSON API 接口，无法自动生成 CLI"
blocked
auth-too-complex
"所有接口都需要超出自动化能力的认证方式（如 signature/bearer），无法自动生成"
blocked
no-viable-candidate
"发现了 API 接口，但未能合成有效的 CLI 候选"
blocked
execution-environment-unavailable
"浏览器未连接，请先运行 opencli doctor 检查环境"
needs-human-check
unsupported-required-args
"候选需要参数 {args}，请提供示例值后重试"
needs-human-check
empty-result
"候选验证返回空结果，建议用 opencli-operate 检查"
needs-human-check
sparse-fields
"候选验证结果字段不足，建议人工检查"
needs-human-check
non-array-result
"返回结果不是数组格式，建议用 opencli-operate 检查接口返回结构"
needs-human-check
timeout
"验证超时，建议用 opencli-operate 手动检查接口响应"
needs-human-check
selector-mismatch
"数据路径不匹配，建议用 opencli-operate 检查实际返回结构"
needs-human-check
verify-inconclusive
"验证结果不确定，候选已保存在 {path}，需要人工审查"
conclusionreasonmessage
success
—"已生成 {command}，可直接使用。策略: {strategy}"
blocked
no-viable-api-surface
"该站点没有发现可用的 JSON API 接口，无法自动生成 CLI"
blocked
auth-too-complex
"所有接口都需要超出自动化能力的认证方式（如 signature/bearer），无法自动生成"
blocked
no-viable-candidate
"发现了 API 接口，但未能合成有效的 CLI 候选"
blocked
execution-environment-unavailable
"浏览器未连接，请先运行 opencli doctor 检查环境"
needs-human-check
unsupported-required-args
"候选需要参数 {args}，请提供示例值后重试"
needs-human-check
empty-result
"候选验证返回空结果，建议用 opencli-operate 检查"
needs-human-check
sparse-fields
"候选验证结果字段不足，建议人工检查"
needs-human-check
non-array-result
"返回结果不是数组格式，建议用 opencli-operate 检查接口返回结构"
needs-human-check
timeout
"验证超时，建议用 opencli-operate 手动检查接口响应"
needs-human-check
selector-mismatch
"数据路径不匹配，建议用 opencli-operate 检查实际返回结构"
needs-human-check
verify-inconclusive
"验证结果不确定，候选已保存在 {path}，需要人工审查"

Guardrails

防护规则

  1. 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.
  2. 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.
  3. No new taxonomy. All 
    reason
    , 
    suggested_action
    , 
    reusability
    values are shared with the code layer (
    GenerateOutcome
    ). Skill does not invent new status words.
  4. Machine-readable fields are the contract; 
    message
    is just a summary.     Callers must not parse 
    message
    for decision-making.
  5. goal
    is a natural language intent hint.     Not a command name, not a capability schema, not an execution parameter.
  1. 该技能不编排内部流水线阶段。它不会决定是否进行探索、合成、级联或验证，该逻辑属于代码层职责。
  2. 该技能不自动升级调用operate。当返回
    needs-human-check
    状态时，技能仅上报建议，不会自动调用
    opencli-operate
    ，由上层Agent决策后续操作。
  3. 无新增分类。所有
    reason
    、
    suggested_action
    、
    reusability
    的值都与代码层（
    GenerateOutcome
    ）共享，技能不会自定义新的状态值。
  4. 机器可读字段是契约，
    message
    仅为摘要    。调用方不得通过解析
    message
    内容做决策。
  5. goal
    是自然语言意图提示    。不是命令名称，不是能力schema，也不是执行参数。

Relationship to Other Primitives

与其他原语的关系

P1: Terminal Contract (
GenerateOutcome
)

P1: 最终契约（
GenerateOutcome
）

  • Skill's single source of truth for final decisions
  • Skill maps 
    GenerateOutcome
    → 
    SkillOutput
    (thin translation, no re-orchestration)
  • 技能最终决策的唯一可信源
  • 技能将
    GenerateOutcome
    映射为
    SkillOutput
    （仅做薄转换，无重新编排逻辑）

P2: Early-Hint Contract (
EarlyHint
)

P2: 早期提示契约（
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版本中技能不会直接消费
    EarlyHint
  • 未来版本可能会作为可选进度通道暴露

v1 Scope

v1 版本范围

  • 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
  • 支持JSON API + PUBLIC/COOKIE认证 + 结构化数组结果 + 只读类列表能力
  • 单浏览器会话生命周期（探测+验证共享同一会话）
  • 有限修复：仅支持itemPath重定位，仅尝试1次