ziniao

紫鸟与 Chrome 浏览器 AI 自动化 — 让 AI Agent（Cursor、Claude 等）和终端用户共用同一套 CLI 操控紫鸟店铺与本地 Chrome。

• GitHub：tianyehedashu/ziniao-mcp
• PyPI：[ziniao](https://pypi.org/project/ziniao/) — 控制台命令 ziniao；可选 MCP 服务通过 ziniao serve 启动

一等公民

本项目围绕四个一等公民构建，按优先级使用即可：

1. CLI（ziniao …） — 完整的浏览器自动化命令行，人和 Agent 共享同一入口；首条命令自动拉起后台 daemon，多会话复用。
2. Site Presets（ziniao site …） — JSON 模板 + 浏览器登录态，免 API Key 直接调用站点接口（Rakuten 广告、评论、Amazon 后台等），支持分页、CSRF、Python 插件。
3. RPA Flows（ziniao flow …） — kind: rpa_flow 声明式浏览器流程，支持控制流、重试、文件 IO、HTTP/MCP 外呼、失败工件与断点恢复。
4. Skills（ziniao skill …） — 把 ziniao-cli 等业务技能一键安装到 Cursor / Claude Code / Trae / OpenClaw 等 Agent 的全局目录。

MCP 工具集是可选的备选路径，仅在 Agent 无终端权限或你明确需要 MCP 协议时使用，能力覆盖小于 CLI，详见文末「MCP 服务器（可选）」。

安装

# 1) 安装 uv（推荐：已有 Python 时用 pipx/pip，免过 PowerShell / curl|sh 执行策略）
pipx install uv                                # 推荐
python -m pip install --user uv               # 没有 pipx 时
# 备选（官方 standalone 安装器，升级走 uv self update）
#   Windows:      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
#   macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) 安装 ziniao CLI
uv tool install ziniao

# 3) 必装两件套：ziniao-cli（Agent 调 CLI） + site-development（新站点适配）
#    默认装到 Cursor，`-a claude` / `-a all` 可指定 Agent
ziniao skill install ziniao-cli
ziniao skill install site-development
# 可选：业务 skills，用到哪个装哪个
ziniao skill install rpa-flows                # 声明式 RPA flow 设计与调试
ziniao skill install rakuten-ads              # Rakuten 广告报表
ziniao skill install store-rpa-scripting      # RPA 脚本固化
# 更多：ziniao skill list

为什么 ziniao-cli 和 site-development 是必装：前者让 Agent 知道如何正确调 ziniao 全部命令与 JSON 输出约定；后者是站点扩展的"入场券"——用户要你加一个新站点适配时，Agent 会按它的 6 步工作流（逆向 → 选 Tier → 写 preset → 可选 plugin → CLI 测试 → 提交 site-hub）来工作，避免瞎写。

若终端识别不到 ziniao，把 uv tool dir 输出的目录加入 PATH；升级用 ziniao update（Windows 默认新窗口延迟执行以避开 ziniao.exe 自占用，脚本/CI 用 --sync）。

uv 升级：脚本/WinGet/Scoop 安装的 uv 用 uv self update；pipx / pip 安装的 uv 不支持 uv self update，请改用 pipx upgrade uv 或 pip install -U uv。

紫鸟店铺（可选）：安装 紫鸟客户端 并开启 WebDriver 权限，再执行 ziniao config init 写入账号信息。仅用 Chrome 时无需任何紫鸟配置。

三行上手

ziniao launch --url https://example.com        # 启动 Chrome
ziniao snapshot --interactive                  # 查看可交互元素（自动给出 CSS selector）
ziniao click "#submit" && ziniao screenshot after.png

配置

纯 Chrome 场景零配置即可跑。需要 profile 复用、紫鸟账号或 CDP 端口控制时，ziniao config init 写入 ~/.ziniao/.env / config.yaml（CLI 与 MCP 共用）。

ziniao config init [--force]                  # 交互向导 → ~/.ziniao/config.yaml + .env
ziniao config show                            # 查看生效配置及来源
ziniao config set chrome.user_data_dir "C:\Users\me\.ziniao\chrome-profile"
ziniao config env --shell powershell|bash|json|mcp
ziniao config path

生效优先级：环境变量 > CLI 参数 > ~/.ziniao/.env > 项目 config/config.yaml > ~/.ziniao/config.yaml。

Chrome 环境变量（纯 Chrome 场景可全部省略）：

紫鸟环境变量（使用紫鸟店铺功能时必需，仅用 Chrome 可全部省略）：

使用紫鸟需先安装 紫鸟客户端 并开启 WebDriver 权限（开通说明）。

CLI

全局选项

ziniao [全局选项] <命令> [参数]

环境变量 ZINIAO_JSON=1 等价 --json，NO_COLOR 关闭着色。详见 docs/cli-json.md、docs/cli-llm.md。

站点预设 site（一等公民）

JSON 模板 + 浏览器登录态，免 API Key 直接调站点接口。一个预设就是一个 JSON 文件，声明 URL / 方法 / 变量 / 鉴权 / 分页 / 输出约定，执行时复用当前浏览器 Cookie、localStorage、CSRF token。预设支持三种模式，覆盖从纯接口到纯 UI 的所有场景：

ziniao site list                        # 列出所有预设
ziniao site show rakuten/rpp-search     # 查看预设详情
ziniao site repos                       # 已注册仓库
ziniao site update                      # 拉取仓库最新预设（含 skills）
ziniao site skills                      # 列出仓库内 AI skills

运行预设（顶层快捷自动生成为 ziniao <site> <action>）：

ziniao rakuten rpp-search -V start_date=2026-03-01 -V end_date=2026-03-07
ziniao rakuten reviews-csv -o reviews.csv
ziniao network fetch -p rakuten/rpp-search -V start_date=2026-03-01 --all -o out.json

site-hub — 业务预设 + 业务 skills 仓库

[site-hub](https://github.com/tianyehedashu/site-hub) 是与主仓库解耦的业务预设仓库，通过 ziniao site update 按需拉取，避免主仓库膨胀：

• 按站点组织：site-hub/<site>/<action>.json（如 rakuten/rpp-search.json、google-flow/imagen-generate.json），附配套 README.md、plugin.py、Flow demos。
• 随预设发布 AI skills：site-hub/skills/<skill>/SKILL.md 与预设版本强绑定，ziniao skill install <name> 一键装到 Agent；站点作者想让 Agent 怎么用自己的站点，就写一份 skill 进去。
• 独立版本与 Tag：子仓库自己管版本，主 CLI 向后兼容即可升级预设。

开发新站点 → 用 site-development 技能

想给新站点（如自家 ERP、Shopee、Lazada）加预设，用 [site-development](https://github.com/tianyehedashu/site-hub/tree/main/skills/site-development) 技能，让 Agent 帮你按 6 步工作流产出代码：

ziniao skill install site-development           # 装到 Cursor / Claude Code
# 在 Agent 里说："帮我给 xxx.com 的订单导出接口加一个预设"

技能里沉淀了：三层认证（cookie / header_inject / 插件）选择决策树、mode 选型、分页约定、错误处理、反风控注意事项、落盘复用 ziniao_mcp.sites.save_media、Next.js API 逆向方法（docs/next-app-reverse-engineering.md）等。

架构与鉴权细节见 docs/site-fetch-and-presets.md、docs/page-fetch-auth.md、docs/site-ui-flows.md。

Agent Skill 管理 skill（一等公民）

ziniao skill agents                        # 支持的 agent（cursor / trae / claude / openclaw …）
ziniao skill list                          # 可安装的 skills
ziniao skill install ziniao-cli            # 默认 Cursor
ziniao skill install rakuten-ads -a all    # 全部 agent
ziniao skill update                        # 刷新已安装的 symlink
ziniao skill remove rakuten-ads -a all
ziniao skill installed                     # 已安装

刷新策略：ziniao site update 拉取 site-hub 全量文件（含根目录 skills/ 与各站点 <site>/skills/）并自动 refresh_symlinks，Agent 目录无需再手动刷。ziniao update（升级 CLI 自身）只替换 built-in skills 的文件内容，不自动建立新增 skill 的 symlink——若升级后想让新内置 skill 出现在 Agent 里，再跑一次 ziniao skill update。

内置与业务 skills（⭐ 强烈建议装；按需装其余）：

Chrome / 店铺 / 会话

ziniao launch [--url <url>] [--name <名]  # chrome launch，外部未被占用时自动启动进程
ziniao connect <cdp_port>                 # chrome connect，连接外部 Chrome
ziniao chrome list / close <sid>
ziniao list-stores / open-store <id> / close-store <id>
ziniao store start-client / stop-client
ziniao session list / switch <sid> / info <sid>

launch 由 ziniao 启动的 Chrome 在 close 时会被终止；connect 连接的外部 Chrome 仅断开 CDP。若 launch 发现 profile 已被占用会自动降级为 connect。

导航与页面交互

ziniao navigate <url> / back / forward / reload [--ignore-cache]
ziniao tab list / new [url] / switch --index <i> / close
ziniao nav frame list
ziniao wait <selector>

ziniao click / dblclick / hover <selector>
ziniao fill <selector> <value>
ziniao type <text> [-s <selector>]
ziniao press <key>                        # Enter / Tab / Ctrl+a
ziniao act drag <src> <dst>
ziniao act upload <selector> <file...>
ziniao upload-hijack <file...> [--trigger SEL]  # SPA 隐藏 input 上传
ziniao act focus / select / check / uncheck / dialog / keydown / keyup

页面信息 / 取值 / 查找 / 状态 / 滚动 / 鼠标

ziniao snapshot [-o file.html] [--interactive|--compact]
ziniao screenshot [file.png]
ziniao eval <js>                          # --await 等待 Promise
ziniao url / title
ziniao info console [--level error] / network / errors / highlight / cookies / storage / clipboard

ziniao get text / html / value / attr / count <selector> [<attr>]
ziniao find text <文本> [--action click] / role <角色> [--name <名称>] / first / last / nth
ziniao is visible / enabled / checked <selector>
ziniao scroll down / up / left / right [--pixels N]
ziniao scroll into <selector>
ziniao mouse move <x> <y> / down / up [--button left|right] / wheel --delta-y <n>

网络、录制、批量、系统、升级

ziniao network list [--filter <pattern>|--id <id>]
ziniao network route <pattern> --abort / unroute / routes
ziniao network har-start / har-stop [<file>]

ziniao rec start [--engine legacy|dom2] [--scope active|all] [--max-tabs N]
ziniao rec stop [--name <名>] [--emit nodriver,playwright,preset] [--redact-secrets]
ziniao rec replay <名> [--speed 1.0] / list / delete <名> / status

ziniao flow validate ./flow.json
ziniao flow dry-run ./flow.json --plan
ziniao flow run ./flow.json --var key=value [--vars-from data.csv] [--run-dir ./.runs/demo]
ziniao flow list / flow show <run_id> / flow diagnose <run_id> --emit nodriver
ziniao flow step ./flow.json step_id --state <run_id>

echo '[{"command":"navigate","args":{"url":"https://example.com"}}]' | ziniao batch run

ziniao quit / emulate --device "iPhone 15" / emulate --width 800 --height 600
ziniao update [--git] [--sync] [--dry-run]

rec 默认 dom2 引擎（CDP Runtime.addBinding 缓冲到 daemon，跨标签不丢），--engine legacy 走页内 Symbol 缓冲。

RPA 与录制

遵循「探索 → 验证 → 固化」：snapshot --interactive 选择器 → click / fill → wait 或 snapshot 验证 → 写成 kind: rpa_flow JSON，或交给 store-rpa-scripting 技能生成不依赖 daemon 的独立 Python 脚本（ziniao_webdriver + nodriver）。

声明式 RPA Flow 适合交付给用户或 Agent 重复运行：

ziniao flow dry-run examples/rpa/minimal-rpa-flow.json --plan
ziniao flow run examples/rpa/flow-demo-login-and-extract.rpa-flow.json --var username=demo

失败会在 ~/.ziniao/runs/<run_id>/ 写出 state.json / report.json / 截图 / HTML；用 ziniao flow diagnose <run_id> --emit nodriver 生成复现脚本，用 --replay <run_id> --resume-from step_id 从指定步骤恢复。完整说明见 docs/rpa-flows.md。

录制：ziniao rec start → 在浏览器里操作 → ziniao rec stop --name my-flow --emit nodriver,preset 产出 .json（回放）+ .py（独立脚本）+ .rpa-flow.draft.json（RPA 草稿），ziniao rec replay my-flow 复现。草稿需要人工补变量、断言、循环和 output_contract 后再投入生产。

常用示例

ziniao launch --url https://www.baidu.com
ziniao navigate https://example.com && ziniao wait ".loaded" && ziniao screenshot page.png
ziniao fill "#email" "u@test.com" && ziniao fill "#pass" "secret" && ziniao click "#login"

# 页面内登录态接口（架构见 docs/site-fetch-and-presets.md）
ziniao rakuten rpp-search -V start_date=2026-03-01 -V end_date=2026-03-07
ziniao rakuten reviews-csv -o reviews.csv

# JSON 输出
ziniao --json session list
ziniao --json --content-boundaries --max-output 8000 info snapshot

所有命令支持 --help，如 ziniao chrome launch --help。

MCP 服务器（可选）

仅在 Agent 不方便走终端命令、或你明确需要 MCP 协议时使用；功能是 CLI 的子集。

Cursor 配置（Cursor Settings → MCP → New MCP Server）：

{
  "mcpServers": {
    "ziniao": { "command": "ziniao", "args": ["serve"] }
  }
}

账号与 Chrome 路径写入 ~/.ziniao/.env / config.yaml 即可与 MCP 共用；仅在 IDE 内覆盖时再在 mcp.json 增 env（可用 ziniao config env --shell mcp 导出）。

MCP 进程里已有的环境变量不会被 .env 覆盖；终端的 ziniao 走独立 daemon，不读 mcp.json。

MCP 工具集速览（完整参数见 docs/api-reference.md）：

文档

上游与许可证

主仓库：github.com/tianyehedashu/ziniao-mcp。以 submodule 嵌入时请在上游提 PR，再更新父仓库指针。

许可证以根目录 LICENSE 为准（MIT）。调试时注意 ~/.ziniao/mcp_debug.log 在 DEBUG 级别可能含 URL 等敏感信息。