紫鸟与 Chrome 浏览器 AI 自动化 — 让 AI Agent 操控紫鸟店铺与本地 Chrome

These details have not been verified by PyPI

Project description

ziniao

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

GitHub：tianyehedashu/ziniao-mcp
PyPI：ziniao — 控制台命令 ziniao；可选 MCP 服务通过 ziniao serve 启动

一等公民

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

CLI（ziniao …） — 完整的浏览器自动化命令行，人和 Agent 共享同一入口；首条命令自动拉起后台 daemon，多会话复用。
Site Presets（ziniao site …） — JSON 模板 + 浏览器登录态，免 API Key 直接调用站点接口（Rakuten 广告、评论、Amazon 后台等），支持分页、CSRF、Python 插件。
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 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_PATH`	Chrome 可执行文件路径；不设置时自动检测（注册表 > 常见路径 > PATH）
`CHROME_USER_DATA`	Chrome 用户数据目录（profile），用于复用登录态 / Cookie / 扩展；默认 `~/.ziniao/chrome-profile`
`CHROME_CDP_PORT`	Chrome CDP 调试端口；不设置时自动分配

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

环境变量	必填	说明
`ZINIAO_COMPANY`	✅	紫鸟企业名
`ZINIAO_USERNAME`	✅	紫鸟登录用户名
`ZINIAO_PASSWORD`	✅	紫鸟登录密码
`ZINIAO_CLIENT_PATH`	✅	紫鸟客户端可执行文件路径
`ZINIAO_SOCKET_PORT`	—	与客户端通信的 HTTP 端口；不设置时自动检测运行中的客户端端口，检测不到则默认 `16851`
`ZINIAO_VERSION`	—	客户端版本，默认 `v6`

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

CLI

全局选项

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

选项	说明
`--store <id>` / `--session <id>`	指定目标店铺 / 会话（互斥）
`--json`	机器可读信封 `{success, data, error}`（与 agent-browser 一致）
`--json-legacy`	daemon 原始 JSON（无信封），与 `--json` 互斥
`--content-boundaries`	JSON 加 `_boundary`；stdout 加边界行（`ZINIAO_CONTENT_BOUNDARIES=1`）
`--max-output <N>`	限制快照 / `eval` 在 stdout 的字符数；默认 2000，`0` 不截断；`-o` 写文件始终全量
`--timeout <秒>`	`0` 自动（navigate/click/snapshot 等 120s，其余 60s）

环境变量 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 的所有场景：

模式	适用	说明
`mode: fetch`	登录态 API	通过浏览器 `fetch` 发请求，声明式 header 注入（cookie / storage / eval），支持 offset / cursor 分页
`mode: js`	特殊场景	在页面里执行自定义 JS 胶水（如 GCS 签名 URL 下载、富文本交互）
`mode: ui`	非 API / 混合	声明式 UI 步骤（点击、填表、`type: secret` 安全输入、DOM `extract`、内联 `fetch`），带 bezier 轨迹反风控、失败快照自动脱敏

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 是与主仓库解耦的业务预设仓库，通过 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 技能，让 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（⭐ 强烈建议装；按需装其余）：

技能	用途
`ziniao-cli` ⭐	Agent 直接调 `ziniao` 命令完成浏览器自动化、站点预设、skill 管理
`site-development` ⭐	新站点适配器开发（6 步工作流、3 层认证、`mode: fetch/js/ui` 选型）
`store-rpa-scripting`	探索 → 固化为独立 Python 脚本（nodriver + ziniao_webdriver）
`store-management` / `amazon-operations`	多店管理 / 亚马逊后台
`rakuten-ads` / `rakuten-reviews`	Rakuten 广告报表 / 评论 CSV

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 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] [--redact-secrets]
ziniao rec replay <名> [--speed 1.0] / list / delete <名> / status

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_for 或 snapshot 验证 → 把步骤交给 store-rpa-scripting 技能，生成不依赖 daemon 的独立 Python 脚本（ziniao_webdriver + nodriver）。

录制：ziniao rec start → 在浏览器里操作 → ziniao rec stop --name my-flow 产出 .json（回放）+ .py（独立脚本），ziniao rec replay my-flow 复现。

常用示例

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）：

分组	工具
店铺	`start_client` / `stop_client` / `list_stores` / `list_open_stores` / `open_store` / `connect_store` / `close_store`
Chrome / 会话	`launch_chrome` / `connect_chrome` / `list_chrome` / `close_chrome` / `browser_session`
导航	`navigate_page` / `list_pages` / `select_page` / `new_page` / `close_page` / `wait_for`
输入	`click` / `fill` / `fill_form` / `type_text` / `press_key` / `hover` / `drag` / `handle_dialog` / `upload_file`
调试	`evaluate_script` / `take_screenshot` / `take_snapshot` / `list_console_messages` / `get_console_message`
网络 / 仿真 / 录制	`list_network_requests` / `get_network_request` / `emulate` / `resize_page` / `recorder`

文档

文档	说明
installation.md	多种安装方式、配置、故障排查
install-uv-windows.md	Windows 下安装 uv
architecture.md	三层架构、模块职责、数据流
api-reference.md	全部 MCP 工具参数与返回值
development.md	添加新工具、构建、发布
cli-json.md / cli-llm.md	`--json` 信封、与 agent-browser 对齐
cli-agent-browser-parity.md	全量命令与参数对照
site-fetch-and-presets.md	站点模板架构、`auth.type`、分页、`page_fetch`
page-fetch-auth.md	声明式 header 注入（cookie/localStorage/eval）
site-ui-flows.md	Declarative UI Flows (`mode: ui`)、反风控、`type: secret`

上游与许可证

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

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

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.2.73

May 12, 2026

0.2.72

May 12, 2026

0.2.71

Apr 29, 2026

0.2.70

Apr 25, 2026

0.2.69

Apr 21, 2026

0.2.68

Apr 20, 2026

0.2.67

Apr 20, 2026

0.2.66

Apr 20, 2026

0.2.65

Apr 20, 2026

0.2.64

Apr 20, 2026

0.2.63

Apr 20, 2026

0.2.62

Apr 20, 2026

0.2.57

Apr 19, 2026

0.2.55

Apr 17, 2026

0.2.54

Apr 17, 2026

0.2.53

Apr 17, 2026

This version

0.2.52

Apr 17, 2026

0.2.51

Apr 17, 2026

0.2.50

Apr 17, 2026

0.2.49

Apr 16, 2026

0.2.48

Apr 15, 2026

0.2.47

Apr 15, 2026

0.2.46

Apr 15, 2026

0.2.45

Apr 15, 2026

0.2.44

Apr 15, 2026

0.2.43

Apr 15, 2026

0.2.41

Apr 10, 2026

0.2.39

Apr 10, 2026

0.2.38

Apr 10, 2026

0.2.37

Apr 9, 2026

0.2.36

Apr 2, 2026

0.2.35

Apr 2, 2026

0.2.34

Apr 2, 2026

0.2.33

Apr 2, 2026

0.2.32

Apr 1, 2026

0.2.31

Apr 1, 2026

0.2.30

Mar 31, 2026

0.2.29

Mar 31, 2026

0.2.28

Mar 31, 2026

0.2.27

Mar 28, 2026

0.2.26

Mar 28, 2026

0.2.25

Mar 25, 2026

0.2.24

Mar 25, 2026

0.2.23

Mar 25, 2026

0.2.22

Mar 25, 2026

0.2.21

Mar 25, 2026

0.2.20

Mar 24, 2026

0.2.19

Mar 24, 2026

0.2.18

Mar 24, 2026

0.2.17

Mar 24, 2026

0.2.16

Mar 24, 2026

0.2.15

Mar 24, 2026

0.2.14

Mar 23, 2026

0.2.13

Mar 23, 2026

0.2.12

Mar 23, 2026

0.2.11

Mar 23, 2026

0.2.10

Mar 23, 2026

0.2.9

Mar 23, 2026

0.2.8

Mar 23, 2026

0.2.7

Mar 20, 2026

0.2.6

Mar 20, 2026

0.2.5

Mar 20, 2026

0.2.4

Mar 20, 2026

0.2.3

Mar 19, 2026

0.2.1

Mar 19, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ziniao-0.2.52.tar.gz (387.8 kB view details)

Uploaded Apr 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ziniao-0.2.52-py3-none-any.whl (273.3 kB view details)

Uploaded Apr 17, 2026 Python 3

File details

Details for the file ziniao-0.2.52.tar.gz.

File metadata

Download URL: ziniao-0.2.52.tar.gz
Upload date: Apr 17, 2026
Size: 387.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for ziniao-0.2.52.tar.gz
Algorithm	Hash digest
SHA256	`731cdbdb4659c18c9b7192f57a8f30d3b85cfa22c65935cd2c85a8b57f35830c`
MD5	`e294722e773198b8c3fb840d36d5ca66`
BLAKE2b-256	`25956bbf093a9e52615f40099e9be19694fda783edd5f40d7c2e0ae6d99aa897`

See more details on using hashes here.

File details

Details for the file ziniao-0.2.52-py3-none-any.whl.

File metadata

Download URL: ziniao-0.2.52-py3-none-any.whl
Upload date: Apr 17, 2026
Size: 273.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for ziniao-0.2.52-py3-none-any.whl
Algorithm	Hash digest
SHA256	`9fae43f953db0e83cd44f538f8f005ab582bd477d25995b0bea364bb2e739110`
MD5	`2a1d68de3852984b20041a60cd552ae9`
BLAKE2b-256	`ddd61f04bad9c76ede70f90765aaef89452bee82b20f44137e4225a5cd7482c6`

See more details on using hashes here.

ziniao 0.2.52

Navigation

Verified details

Maintainers

Unverified details

Meta

Classifiers

Project description

ziniao

一等公民

安装

三行上手

配置

CLI

全局选项

站点预设 site（一等公民）

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

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

Agent Skill 管理 skill（一等公民）

Chrome / 店铺 / 会话

导航与页面交互

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

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

RPA 与录制

常用示例

MCP 服务器（可选）

文档

上游与许可证

Project details

Verified details

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

站点预设 `site`（一等公民）

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

Agent Skill 管理 `skill`（一等公民）