cliany-site 文档

v0.16.269 · Python ≥ 3.11 · MIT License · GitHub · PyPI

cliany-site 基于 LLM 和 Chrome CDP 协议，将任意网页操作自动化为可重复调用的 CLI 命令。核心流程：explore（探索）→ generate（生成适配器）→ run（执行）。

安装

PyPI 安装（推荐）

pip install cliany-site

源码安装

git clone https://github.com/pearjelly/cliany.site.git
cd cliany.site
pip install -e .

依赖 Python ≥ 3.11 和 Chrome/Chromium 浏览器（工具会自动检测并启动）。

配置 LLM

支持 Anthropic（Claude）和 OpenAI（GPT-4o）两种 provider，二选一：

# Anthropic Claude（推荐）
export CLIANY_LLM_PROVIDER=anthropic
export CLIANY_ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI GPT-4o
export CLIANY_LLM_PROVIDER=openai
export CLIANY_OPENAI_API_KEY="sk-..."

也可以写入 .env 文件，查找顺序：~/.config/cliany-site/.env → ~/.cliany-site/.env → 项目目录 .env → 系统环境变量。

explore --json 遇到 LLM 网关、限流或服务暂不可用时会返回 E_LLM_UNAVAILABLE，并在 details.retryable、details.status_code 和 details.phase 中给出可重试上下文；错误消息会清洗原始 HTML 网关页。

10 分钟成功路径

首次运行先确认 CLI 可用并查看维护中的公开案例；不需要先配置 LLM key。准备好生成自己的命令时，再进入 配置 LLM 和 explore。

# 1. 查看 human 摘要和下一步
cliany-site doctor

# 2. 查看维护中的公开案例和各自的验证路径
cliany-site cases

# 3. 脚本使用机器可读案例目录
cliany-site cases --json

# 4. 准备好后再配置 LLM 并生成自己的命令

发布者也可以提供直接 HTTPS adapter 包；远程安装必须固定完成归档的 64 个字符小写十六进制 SHA-256，并会复用同一套包校验：

cliany-site market publish github.com --version 1.0.0 --json

发布成功 JSON 中的 data.package_sha256 是完成归档的 64 个字符小写十六进制 SHA-256 摘要；将该值填入发布者提供的通用 HTTPS 安装命令：

cliany-site market install https://publisher.example/releases/adapter.cliany-adapter.tar.gz --sha256 <64-hex-sha256> --dry-run --json

doctor — 环境检查

检查 Chrome CDP 连通性、LLM Key 有效性、目录结构。

cliany-site doctor [--json]

返回示例：

{"success": true, "data": {"cdp": true, "llm": true, "adapters_dir": true}}

login — 保存登录状态

打开目标 URL，等待用户在浏览器中完成登录，然后持久化 Cookie / LocalStorage。

cliany-site login "https://your-site.com" [--json]

explore — 探索工作流

核心命令。指定 URL 和任务描述，LLM 自动分析页面 AXTree，规划并执行操作路径，将结果生成为 Python/Click CLI 适配器。

cliany-site explore <url> <workflow> [OPTIONS]

Options:
  --json          JSON 输出
  --interactive   交互式探索，每步手动确认
  --extend <domain>  增量扩展已有适配器
  --headless      无头模式（服务器/CI 环境）
  --cdp-url <ws://host:port>  连接远程浏览器

示例：

# 基础探索
cliany-site explore "https://github.com" "搜索仓库并查看 README" --json

# 交互式（每步确认）
cliany-site explore "https://github.com" "管理 Issues" --interactive

# 增量扩展（不覆盖已有命令）
cliany-site explore "https://github.com" "创建 PR" --extend github.com

list — 查看适配器

cliany-site list [--json]

列出 ~/.cliany-site/adapters/ 目录下所有已生成的域名适配器及其命令。

执行适配器命令

生成适配器后，通过 cliany-site <domain> <command> 执行：

# 查看 github.com 适配器的所有命令
cliany-site github.com --help

# 执行搜索命令
cliany-site github.com search --query "browser automation" --json

# 从断点恢复
cliany-site github.com search --query "browser automation" --resume --json

Python SDK

from cliany_site.sdk import ClanySite
import asyncio

async def main():
    async with ClanySite() as cs:
        # 探索
        result = await cs.explore("https://github.com", "搜索仓库")
        print(result)

        # 列出适配器
        adapters = await cs.list_adapters()
        print(adapters)

asyncio.run(main())

HTTP API

启动本地 REST API 服务：

cliany-site serve --port 8080

curl -X POST http://localhost:8080/explore \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com", "workflow": "搜索仓库"}'

YAML 工作流编排

# workflow.yaml
name: GitHub 搜索并查看详情
steps:
  - name: 搜索仓库
    adapter: github.com
    command: search
    params:
      query: "cliany-site"
  - name: 查看第一个结果
    adapter: github.com
    command: view
    params:
      repo: "$prev.data.results[0].name"

cliany-site workflow run workflow.yaml --json
cliany-site workflow validate workflow.yaml --json

批量执行

从 CSV/JSON 文件批量驱动适配器命令：

cliany-site workflow batch github.com search data.csv --concurrency 3 --json

环境变量参考

常见问题

Chrome 无法连接怎么办？

运行 cliany-site doctor --json 检查 CDP 状态。默认检查不会真实调用 LLM provider；在耗时较长的 explore 前，可以运行 cliany-site doctor --llm-live --json 做一次真实 provider 预检。若上游网关、限流、provider 连接或服务不可用，输出会包含 llm_live warning 和 details.error_code=E_LLM_UNAVAILABLE。Candidate 晋级时，如果 generate_adapters.ready=false，或 llm_live 返回 warning/error（例如 E_LLM_UNAVAILABLE provider connection failure），请停止本轮真实 explore，把 doctor JSON / 错误摘要作为 blocker 证据。工具会自动尝试启动 Chrome；如果失败，可手动启动：

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

页面改版后命令失效？

小幅页面变化由 AXTree 模糊匹配和自愈机制自动处理。大幅改版时，用 --extend 增量重新探索即可：

cliany-site explore "https://your-site.com" "原有任务" --extend your-site.com

如何创建 candidate promotion issue？

推进 PyPI candidate 前，先按 Candidate Promotion Runbook（docs/candidate-promotion-runbook.md）跑 cliany-site doctor --llm-live --json、adapter package、metadata validation 和 online smoke。PyPI 搜索案例的目标包名应保持 pypi.org-<version>.cliany-adapter.tar.gz，online smoke 使用 cliany-site pypi.org search-projects --query cliany-site --limit 5 --json。

先运行 cliany-site cases --status candidate --promotion-plan --json 读取 primary_issue_template_command 和 issue_template_json_command，再运行 cliany-site cases --case-id <id> --issue-template 生成带 Primary Runbook、Command SHA-256、Promotion Command Plan Summary、Promotion Command Plan command_sha256 子行、source / missing 子行、Doctor Preflight Evidence Fields 和 Doctor Preflight Evidence Template 的 issue body。随后先保留基础 cliany-site cases --case-id <id> --evidence-bundle --json 输出，再运行 cliany-site doctor --llm-live --json > /tmp/cliany-doctor-preflight.json 和 cliany-site cases --case-id <id> --evidence-bundle --doctor-json /tmp/cliany-doctor-preflight.json --json，在 issue 摘要中引用 primary_next_task_runbook、llm_live_preflight_required、llm_live_preflight_command_sha256、promotion_command_plan[*].command_sha256、doctor_preflight_evidence_fields、doctor_preflight_evidence_values、doctor_preflight_evidence_ok、doctor_preflight_evidence_missing_count、doctor_preflight_state、doctor_preflight_state_fields、doctor_preflight_state_statuses 和 expected_adapter_package，确保贡献者先做 live LLM preflight、再执行当前 evidence task，并上传正确的 adapter release asset。doctor_preflight_state_fields 固定为 preflight_state.status、preflight_state.ready_for_adapter_package、preflight_state.primary_reason、preflight_state.reason_codes、preflight_state.next_action；doctor_preflight_state_statuses 只允许 ready、blocked、missing_fields。普通 cliany-site cases --status candidate 输出也会展示 preflight_required、preflight_blocker 和 runbook_first，方便非 JSON 交接。若 preflight 未通过，贴回 doctor JSON 中的 summary.llm_live_preflight 与 CDP blocker 字段作为证据；若 --doctor-json 已生成 evidence，则读取 doctor_preflight_state.status，只在 ready 且 preflight_state.ready_for_adapter_package=true 时继续 explore，blocked 或 missing_fields 时先贴证据。若使用 python scripts/plan_next_iteration.py --issues-dir /tmp/cliany-candidate-issues 生成 artifacts，先对比 candidate_promotions[*].issue_template_command、candidate_promotions[*].issue_template_json_command、issue-metadata.json、case_promotion_evidence_primary_llm_live_preflight_required、case_promotion_evidence_primary_llm_live_preflight_command_sha256、case_promotion_evidence_primary_llm_live_preflight_blocker_comment、case_promotion_evidence_primary_doctor_preflight_blocker_comment、case_promotion_evidence_primary_doctor_preflight_evidence_template_sha256、case_promotion_doctor_preflight_evidence_template_sha256、doctor_preflight_state_fields、doctor_preflight_state_statuses、required_labels、required_label_count、required_labels_sha256 与 case_promotion_evidence_primary_runbook_steps / hash 是否漂移，再创建 GitHub issue。

如果已经保存 doctor JSON，可运行 python scripts/plan_next_iteration.py --doctor-json /tmp/cliany-doctor-preflight.json --issues-dir /tmp/cliany-candidate-issues。生成的 issue-metadata.json 和 candidate issue body 会直接带上当前 doctor_preflight_state、extracted values、source path，以及包含 --doctor-json 的 issue/evidence bundle commands，适合在 live LLM blocked 时生成 blocker-ready issue 草稿。

如果维护工具只读取 promotion queue，可直接比对 promotion_plan.primary_doctor_preflight_evidence_template_field_count、promotion_plan.primary_doctor_preflight_evidence_template_sha256、promotion_plan.primary_llm_live_preflight_command_sha256、candidate primary_doctor_preflight_evidence_template_sha256 和 task_queue[*].doctor_preflight_evidence_template_sha256 / task_queue[*].llm_live_preflight_command_sha256，无需展开完整 evidence bundle 也能发现 doctor 证据模板与 preflight 命令漂移。

如果维护工具只读取 case validation，可从 scripts/validate_cases.py --json 的 promotion_evidence_summary.primary_next_task.doctor_preflight_evidence_template_sha256、doctor_preflight_state_fields、doctor_preflight_state_statuses，scripts/validate_cases.py --report 的 primary_doctor_preflight_evidence_template_sha256，或纯文本 scripts/validate_cases.py --strict stdout 的 promotion_evidence_primary_doctor_preflight_evidence_template_sha256 / promotion_evidence_primary_llm_live_preflight_command_sha256 比对同一 doctor 模板、state contract 与 preflight 命令漂移。

如何在服务器/Docker 中使用？

cliany-site explore "https://github.com" "搜索仓库" \
  --headless \
  --cdp-url "ws://localhost:9222" \
  --json