opencli-generate

CLI-GENERATE — 検証済み CLI 生成スキル

ワンショットの CLI 自動生成：URL を渡すと、検証済みのコマンド、または生成できない理由を構造化して説明します。

---

このスキルを使う場面

• ユーザーが「帮我生成 xxx.com 的 cli」などと言った場合
• ユーザーが opencli にウェブサイトを自動で追加したい場合
• ユーザーが URL を提示し、動作する CLI コマンドを期待している場合

対象外：手動での API 調査（opencli-explorer を使用）、単一ページのクイック生成（opencli-oneshot を使用）、ブラウザーを使ったデバッグ（opencli-operate を使用）。

---

入力

フィールド	必須	型	説明
url	はい	文字列	対象ウェブサイトの URL
goal	いいえ	文字列	自然言語による意図のヒント（例：「热榜」、「搜索」、「最新帖子」）

goal はユーザーの意図を示すヒントであり、コマンド名、機能スキーマ、実行パラメーターではありません。

---

呼び出し方法

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

このスキルは内部で generateVerifiedFromUrl を呼び出します。エージェントが 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)

メッセージテンプレート

結論	理由	メッセージ
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}，需要人工审查"

---

ガードレール

1. スキルは内部パイプラインの各ステージをオーケストレーションしません。 探索、統合、カスケード、検証のいずれを行うかは判断しません。それはコード層の役割です。

2. スキルは操作へ自動的にエスカレーションしません。 needs-human-check の場合、スキルは推奨事項を報告しますが、opencli-operate を自動的に呼び出しません。判断するのは上位レベルのエージェントです。

3. 新しい分類体系は導入しません。 すべての reason、suggested_action、reusability の値は、コード層（GenerateOutcome）と共通です。スキルは新しいステータス用語を作りません。

4. 機械可読フィールドが契約であり、message は単なる要約です。 呼び出し側は、意思決定のために message を解析してはなりません。

5. goal は自然言語による意図のヒントです。 コマンド名でも、機能スキーマでも、実行パラメーターでもありません。

---

他のプリミティブとの関係

P1：ターミナル契約（GenerateOutcome）

• 最終判断におけるスキルの唯一の信頼できる情報源
• スキルは GenerateOutcome → SkillOutput にマッピングします（薄い変換のみで、再オーケストレーションは行いません）

P2：早期ヒント契約（EarlyHint）

• オーケストレーター内に存在し、スキルからは透過的です
• 検証ステージの前に早期終了（コスト最適化）を促します
• スキルは v1 では EarlyHint を直接利用しません
• 将来のバージョンでは、オプションの進捗チャネルとして公開される可能性があります

v1 の範囲

• JSON API + PUBLIC/COOKIE 認証 + 構造化配列結果 + 読み取り専用のリスト型機能
• 単一のブラウザーセッションのライフサイクル（probe と verify でセッションを共有）
• 範囲を限定した修復：itemPath の再配置のみ、試行は 1 回