{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://agentdock.local/schemas/adapter.schema.json",
  "title": "AgentDock Adapter",
  "description": "Agent CLI 适配器定义（v1，对齐架构 §3.1）。首批 14 工具在 Wave 1 仅保留 id/name/name_zh/vendor/status 五字段占位；其余字段（platforms/official/runtime_deps/install/detect/update/uninstall/authorization/configuration/diagnostics/documentation）为可选，供 Wave 2 起逐工具填充。所有 command 必须是 argv 数组，禁止 shell 元字符与字符串拼接。",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "name", "name_zh", "vendor", "status"],
  "properties": {
    "id": {
      "type": "string",
      "description": "稳定 ID，如 codex",
      "pattern": "^[a-z0-9][a-z0-9-]*$"
    },
    "name": {
      "type": "string",
      "description": "展示名"
    },
    "name_zh": {
      "type": "string",
      "description": "中文展示名"
    },
    "vendor": {
      "type": "string",
      "description": "厂商"
    },
    "status": {
      "type": "string",
      "enum": ["available", "watch"],
      "description": "目录状态：available=可安装列表；watch=观察中（第二批）"
    },
    "adapter_version": {
      "type": "string",
      "description": "适配器自身版本（semver，如 1.2.0）",
      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$"
    },
    "license": {
      "type": "string",
      "description": "展示用许可；专有许可注明「仅官方渠道安装、不重打包」"
    },
    "platforms": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "windows": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "architectures": {
              "type": "array",
              "items": { "type": "string", "enum": ["x64", "arm64"] }
            },
            "notes": {
              "type": "string",
              "description": "如 Gemini 要求 Win11 24H2+"
            }
          }
        },
        "linux": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "distributions": {
              "type": "array",
              "items": { "type": "string", "enum": ["ubuntu", "debian"] }
            },
            "architectures": {
              "type": "array",
              "items": { "type": "string", "enum": ["x64", "arm64"] }
            },
            "min_ubuntu": {
              "type": "string",
              "description": "最低 Ubuntu 版本，如 22.04"
            }
          }
        }
      }
    },
    "official": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "homepage": { "type": "string", "format": "uri" },
        "docs": { "type": "string", "format": "uri" },
        "icon": { "type": "string", "format": "uri", "description": "官方图标地址（识别/许可说明与本地打包来源，不热链）" },
        "allowed_hosts": {
          "type": "array",
          "items": { "type": "string" },
          "description": "网络白名单（诊断/下载仅可访问这些主机）"
        }
      }
    },
    "runtime_deps": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id"],
        "properties": {
          "id": { "type": "string", "enum": ["node", "python", "git", "powershell", "uv", "bash"] },
          "semver_range": { "type": "string", "description": "如 >=20" },
          "required_for": {
            "type": "array",
            "items": { "type": "string", "enum": ["install", "run"] }
          }
        }
      }
    },
    "install": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "preferred": { "type": "string", "description": "默认渠道 channel id" },
        "channels": {
          "type": "array",
          "items": { "$ref": "#/definitions/channel" }
        }
      }
    },
    "detect": {
      "type": "object",
      "additionalProperties": false,
      "required": ["executable"],
      "properties": {
        "executable": { "type": "string", "description": "PATH 上的命令名；Cursor 为 agent" },
        "version_args": { "type": "array", "items": { "type": "string" } },
        "version_regex": { "type": "string" },
        "version_unconfirmed": { "type": "boolean", "description": "调研标注「文档未能确认」时 true" },
        "path_hints": { "type": "array", "items": { "type": "string" }, "description": "非 PATH 常见位置" }
      }
    },
    "update": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "method": {
          "type": "string",
          "enum": ["npm_update", "self_update_cmd", "channel_reinstall", "winget_upgrade", "pypi_upgrade", "manual"]
        },
        "command": { "type": "array", "items": { "type": "string" } },
        "source": {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind"],
          "properties": {
            "kind": { "type": "string", "enum": ["npm", "pypi", "github"] },
            "package": { "type": "string", "description": "npm / pypi 包名" },
            "repo": { "type": "string", "description": "GitHub 仓库 owner/repo" }
          }
        }
      }
    },
    "uninstall": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "method": { "type": "string", "enum": ["npm_uninstall", "package_manager", "manual_delete"] },
        "command": { "type": "array", "items": { "type": "string" } },
        "keep_config_default": { "type": "boolean", "default": true }
      }
    },
    "authorization": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "modes": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["mode"],
            "properties": {
              "mode": { "type": "string", "enum": ["browser_oauth", "device_code", "api_key", "local_tui"] },
              "command": { "type": "array", "items": { "type": "string" } },
              "env_keys": { "type": "array", "items": { "type": "string" } },
              "status_command": { "type": "array", "items": { "type": "string" } },
              "notes_zh": { "type": "string" }
            }
          }
        },
        "credential_files": {
          "type": "array",
          "items": { "type": "string" },
          "description": "登录态/OAuth 凭据文件或目录（存在任一即视为已授权，如 kimi-code ~/.kimi-code/credentials）"
        },
        "test": {
          "type": "object",
          "additionalProperties": false,
          "required": ["url"],
          "properties": {
            "url": { "type": "string", "format": "uri", "description": "测试连通端点 URL" },
            "key_header": { "type": "string", "description": "API Key 注入头名（如 x-api-key / Authorization）" },
            "bearer": { "type": "boolean", "default": false, "description": "Authorization 头是否带 Bearer 前缀" },
            "extra_headers": { "type": "array", "items": { "type": "string" }, "description": "额外请求头" }
          }
        }
      }
    },
    "configuration": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "files": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["path", "format"],
            "properties": {
              "path": { "type": "string", "description": "支持 ~ 与平台变量" },
              "format": { "type": "string", "enum": ["toml", "json", "jsonc", "yaml", "env", "crushrc"] },
              "scope": { "type": "string", "enum": ["user", "project", "system"] },
              "platforms": {
                "type": "array",
                "items": { "type": "string", "enum": ["windows", "linux"] },
                "description": "适用平台；空数组 = 全平台适用（同一 CLI 不同平台路径不同时用于按平台选型）"
              }
            }
          }
        },
        "environment": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["key"],
            "properties": {
              "key": { "type": "string" },
              "sensitive": { "type": "boolean", "default": false },
              "maps_to_field": { "type": "string" }
            }
          }
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "label_zh", "type", "storage"],
            "properties": {
              "id": { "type": "string" },
              "label_zh": { "type": "string" },
              "help_zh": { "type": "string" },
              "required": { "type": "boolean", "default": false },
              "sensitive": { "type": "boolean", "default": false },
              "type": { "type": "string", "enum": ["string", "url", "enum", "bool"] },
              "storage": { "type": "string", "enum": ["file", "env", "keyring"], "description": "keyring 永不进普通备份" },
              "platforms": { "type": "array", "items": { "type": "string", "enum": ["windows", "linux"] } },
              "docs_url": { "type": "string", "format": "uri" },
              "options": {
                "type": "array",
                "description": "enum 类型的可选值（value + 中文名）",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["value", "label_zh"],
                  "properties": {
                    "value": { "type": "string" },
                    "label_zh": { "type": "string" }
                  }
                }
              },
              "group": {
                "type": "string",
                "description": "表单分组：auth（授权/登录）| common（常用配置）| advanced（高级配置，默认折叠）"
              }
            }
          }
        }
      }
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["rule_id"],
        "properties": {
          "rule_id": { "type": "string", "description": "引用规则库或内联" }
        }
      }
    },
    "documentation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "quickstart_zh": { "type": "string" },
        "install_zh": { "type": "string", "description": "安装说明（中文）" },
        "auth_zh": { "type": "string", "description": "授权说明（中文）" },
        "commands": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "cmd": { "type": "string" },
              "desc_zh": { "type": "string" }
            }
          }
        },
        "params": {
          "type": "array",
          "description": "常用参数（中文）",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "param": { "type": "string" },
              "desc_zh": { "type": "string" }
            }
          }
        },
        "updated_at": { "type": "string", "format": "date" },
        "risks_zh": { "type": "array", "items": { "type": "string" } }
      }
    },
    "models": {
      "type": "object",
      "additionalProperties": false,
      "description": "该 CLI 可加载的模型（模型列表来源：CLI 自带列举命令或适配器按官方文档维护的清单）",
      "properties": {
        "command": { "type": "array", "items": { "type": "string" }, "description": "CLI 自带的模型列举命令（如 agent --list-models）" },
        "list": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id"],
            "properties": {
              "id": { "type": "string" },
              "label_zh": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "channel": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "enum": ["npm", "official_script", "winget", "choco", "scoop", "brew", "apt", "pypi_uv", "github_release"]
        },
        "platforms": {
          "type": "array",
          "items": { "type": "string", "enum": ["windows", "linux"] }
        },
        "command": {
          "type": "array",
          "items": { "type": "string" },
          "description": "命令必须是 argv 数组，禁止字符串拼接与 shell 元字符（| & ; $ \\ > < ( `）"
        },
        "script": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "url": { "type": "string", "format": "uri" },
            "kind": { "type": "string", "enum": ["powershell_irm", "bash_pipe", "ps1_file"] },
            "integrity": {
              "type": "object",
              "additionalProperties": false,
              "properties": { "sha256": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } }
            }
          }
        },
        "package": { "type": "string", "description": "npm/pypi 包名" },
        "elevate": { "type": "string", "enum": ["never", "if_needed", "required"] },
        "elevate_reason_zh": { "type": "string" },
        "post_checks": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}