cliany-site 文档

v0.8.3 · 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 分钟成功路径

首次运行先验证一个真实只读 demo adapter；不需要先配置 LLM key。跑通后再进入 配置 LLM 和 explore。

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

# 2. 安装 GitHub Release 中的只读 demo adapter
cliany-site market install ./issues.apache.org.cliany-adapter-v0.14.0.tar.gz

# 3. 查看并验证 adapter
cliany-site list --json
cliany-site verify issues.apache.org --json

# 4. 执行只读命令
cliany-site issues.apache.org list-issues --project SPARK --limit 5 --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？

先运行 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，在 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_template、doctor_preflight_evidence_template_field_count、doctor_preflight_evidence_template_sha256 和 expected_adapter_package，确保贡献者先做 live LLM preflight、再执行当前 evidence task，并上传正确的 adapter release asset。普通 cliany-site cases --status candidate 输出也会展示 preflight_required、preflight_blocker 和 runbook_first，方便非 JSON 交接。若 preflight 未通过，贴回 doctor JSON 中的 summary.llm_live_preflight 与 CDP blocker 字段作为证据。若使用 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_evidence_fields 与 case_promotion_evidence_primary_runbook_steps / hash 是否漂移，再创建 GitHub 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、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 模板与 preflight 命令漂移。

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

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