opencli-generate

CLI-GENERATE — 已验证的 CLI 生成技能

一次性自动生成 CLI：提供 URL，即可获得已验证的命令，或获得无法生成的结构化说明。

---

何时使用此技能

• 用户说“帮我生成 xxx.com 的 cli”或类似内容
• 用户希望自动将网站添加到 opencli 中
• 用户提供 URL，并期望得到可用的 CLI 命令

不适用于：手动 API 探索（使用 opencli-explorer）、单页快速生成（使用 opencli-oneshot），或基于浏览器的调试（使用 opencli-operate）。

---

输入

字段	必填	类型	说明
url	是	string	目标网站 URL
goal	否	string	自然语言意图提示（例如“热榜”、“搜索”、“最新帖子”）

goal 是用户意图提示，不是命令名称、能力 schema 或执行参数。

---

调用方式

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

该技能在内部调用 generateVerifiedFromUrl。Agent 无需了解 explore、synthesize、cascade 或 verify 等阶段。

---

输出：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;
}

决策语言（与代码层共享）

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 — 没有保留价值

---

决策树

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)

消息模板

conclusion	reason	message
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 不编排内部流水线阶段。 它不决定是否探索、综合、级联或验证。这些属于代码层的职责。

2. Skill 不会自动升级为 operate。 当结果为 needs-human-check 时，skill 只报告建议，不会自动调用 opencli-operate。由上层 Agent 决定。

3. 不引入新的分类体系。 所有 reason、suggested_action、reusability 的取值都与代码层（GenerateOutcome）共享。Skill 不会自行创造新的状态词。

4. 机器可读字段是契约；message 只是摘要。 调用方不得解析 message 来做决策。

5. goal 是自然语言的意图提示。 它不是命令名、不是能力 schema，也不是执行参数。

---

与其他原语的关系

P1：终态契约（GenerateOutcome）

• Skill 的唯一最终决策来源
• Skill 将 GenerateOutcome 映射为 SkillOutput（薄层转换，不做重新编排）

P2：早期提示契约（EarlyHint）

• 位于编排器内部，对 skill 透明
• 在验证阶段之前驱动提前退出（成本优化）
• v1 中 skill 不直接消费 EarlyHint
• 未来版本中可能作为可选的进度通道对外暴露

v1 范围

• JSON API + PUBLIC/COOKIE 认证 + 结构化数组结果 + 只读的列表类能力
• 单一浏览器会话生命周期（probe 与 verify 共享同一会话）
• 有界修复：仅支持 itemPath 重定位，且只尝试一次