ziniao 0.2.22

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

ziniao

紫鸟与 Chrome 浏览器 AI 自动化 — 让 AI Agent（Cursor、Claude 等）操控紫鸟店铺与本地 Chrome，统一会话、统一工具。

GitHub：https://github.com/tianyehedashu/ziniao-mcp

PyPI 包名：ziniao（与仓库名 ziniao-mcp 不同；控制台命令为 ziniao，另提供 ziniao-mcp 作为 python -m ziniao_mcp 的兼容入口）。

快速使用

只需两步即可在 Cursor 中使用全部 MCP 工具。紫鸟配置可选——不配置紫鸟也能使用全部 Chrome 浏览器功能。

1. 安装 uv

# Windows (PowerShell)
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

uv tool install ziniao

若终端无法识别 ziniao，请将 uv tool dir 输出的目录加入 PATH（见下方「命令行全局使用」）。

3. 配置 MCP

打开 Cursor Settings → MCP → New MCP Server，根据你的使用场景选择配置：

仅使用 Chrome 浏览器（无需紫鸟账号）：

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

Chrome 路径与用户数据目录（登录态、Cookie 等）：用 ziniao config init 或 ziniao config set chrome.executable_path / chrome.user_data_dir 写入 ~/.ziniao/config.yaml（亦可用 ~/.ziniao/.env 中的 CHROME_PATH、CHROME_USER_DATA，见下表），MCP 与 CLI 共用。仅在 IDE 内覆盖时，再在 mcp.json 增加 env。

配置完成后即可使用 launch_chrome、connect_chrome 及所有页面操作、录制回放等工具。

紫鸟店铺 + Chrome 浏览器（完整功能）：MCP 配置与上方「仅 Chrome」相同，紫鸟账号与客户端路径请用 ziniao config init 写入 ~/.ziniao/.env（或 config.yaml），启动 MCP 时会自动加载，并与终端 CLI 共用。若仅在 IDE 内覆盖，可在 mcp.json 增加 env 块，键名见下表；也可用 ziniao config env --shell mcp 导出后粘贴。

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

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

Chrome 环境变量（可选，紫鸟配置和 Chrome 配置可同时使用）：

环境变量	说明
CHROME_PATH	Chrome 可执行文件路径。不设置时自动检测（注册表 > 常见路径 > PATH）
CHROME_USER_DATA	Chrome 用户数据目录（profile）。设置后可复用登录态、Cookie、扩展等状态。不设置时使用 ~/.ziniao/chrome-profile
CHROME_CDP_PORT	（可选）Chrome CDP 调试端口，不设置时自动分配

MCP env 与终端 CLI：mcp.json 里的 env 只注入 Cursor 启动的 MCP 服务进程，会参与配置解析；与 ~/.ziniao/.env 并存时，进程里已有的变量不会被 .env 覆盖。终端执行 ziniao … 时走独立的后台 daemon，不读取 mcp.json。需要 IDE 与命令行行为一致时，优先用 ziniao config init 写入 ~/.ziniao/.env / config.yaml，或用 ziniao config env --shell mcp 导出后粘贴到 MCP 配置。

配置完成后，在 Cursor 对话框中试试：

启动 Chrome 浏览器，打开百度

列出我所有的紫鸟店铺

打开第一个亚马逊店铺，截图看看当前页面

版本：ziniao --help。升级 CLI：优先 ziniao update（从 PyPI 升级；Windows 下默认会新开控制台、延迟约 2 秒后执行 uv，并让当前进程立即退出，从而避免 ziniao.exe 自占用导致的错误 32；需要在本终端同步执行并得到退出码时用 ziniao update --sync）。若要从 GitHub main 安装，使用 ziniao update --git。升级后请 ziniao quit 并新开终端，使用 MCP 时重启 Cursor MCP。若仍有其它进程占用 ziniao.exe（多开终端、Cursor MCP 等），请先关闭后再试；失败时 ziniao update 会打印可复制的 uv 命令。

紫鸟前提：使用紫鸟店铺功能需安装 紫鸟客户端 并开启 WebDriver 权限（开通说明）。不使用紫鸟功能时无需安装。

更多安装方式与故障排查见 安装与使用。

命令行全局使用（ziniao）

若希望在任意目录直接使用 ziniao 命令（而不通过 Cursor MCP），推荐用 uv 工具安装，一次配置、全局可用：

# 从 PyPI 安装（推荐）
uv tool install ziniao

# 或从源码安装（克隆后在该目录执行）
uv tool install .

已安装后升级（需本机 PATH 中有 uv）：

ziniao update              # PyPI 最新版（Windows 默认新窗口延迟安装并退出本进程）
ziniao update --sync       # 在当前进程同步执行 uv（脚本/CI；Win 上可能遇 exe 占用）
ziniao update --git        # GitHub 仓库 main 最新提交
ziniao update --dry-run    # 仅打印将执行的 uv 命令（可在另一终端手动执行）

安装后会在 uv 工具目录生成 ziniao 可执行文件。若终端提示「无法将 ziniao 项识别为…」，请将 uv 工具目录加入 PATH：

• 查看工具目录：uv tool dir（Windows 常见为 %APPDATA%\uv\tools 或 %USERPROFILE%\.local\bin）
• 将该目录加入 用户环境变量 Path
  新开终端后即可直接运行 ziniao --help、ziniao serve 等。

快速配置（ziniao config）

安装后可通过交互式向导一键生成全局配置，CLI 和 MCP Server 共享：

ziniao config init          # 交互式向导 → 生成 ~/.ziniao/config.yaml 和 .env
ziniao config show          # 查看当前生效配置及来源
ziniao config set chrome.executable_path "C:\Program Files\Google\Chrome\Application\chrome.exe"
ziniao config env --shell mcp   # 输出可粘贴到 mcp.json 的 env 配置

向导会自动检测 Chrome 路径，询问是否配置紫鸟，然后生成两个文件：

• ~/.ziniao/config.yaml — 全局配置（CLI daemon + MCP Server 自动读取）
• ~/.ziniao/.env — 环境变量版本（自动加载，也可复制到 MCP json env 中）

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

仅用 Chrome（零配置）：不需要任何配置，直接 ziniao launch 即可。Chrome 路径自动检测。

Chrome + 状态复用：设置 user_data_dir 即可跨次启动复用登录态、Cookie、扩展：

ziniao config set chrome.user_data_dir "C:\Users\你的用户名\.ziniao\chrome-profile"

紫鸟 + Chrome 全功能：ziniao config init 向导中选择配置紫鸟即可。

CLI 命令行工具

除了 MCP 工具（给 AI Agent 用），ziniao 还提供完整的命令行界面，可在终端直接操控浏览器。首次执行任意命令时会自动启动后台 daemon。

全局选项

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

选项	说明
--store <id>	指定目标紫鸟店铺（不切换活动会话）；与 --session 互斥
--session <id>	指定目标会话（店铺或 Chrome）；与 --store 互斥
--json	机器可读 JSON，固定信封 {"success": bool, "data": object|null, "error": string|null}（与 agent-browser CLI 一致）；成功时 data 为 daemon 返回体
--json-legacy	输出 daemon 原始 JSON（无信封）；与 --json 互斥
--content-boundaries	与 agent-browser 相同：JSON 增加 _boundary；页面类 stdout 加边界行。环境变量 ZINIAO_CONTENT_BOUNDARIES=1
--max-output <N>	限制快照 HTML / eval 在 stdout 的字符数；未设置时默认 2000（终端安全）；0 表示不截断。ZINIAO_MAX_OUTPUT。-o 写文件为全量
--timeout <秒>	命令超时；0 表示自动（navigate/click/snapshot/screenshot 等慢命令 120s，其余 60s）
--help	查看帮助；根命令底部会列出上述全局选项摘要

环境变量 ZINIAO_JSON=1 等价于 --json（对齐 AGENT_BROWSER_JSON）。终端着色遵循 NO_COLOR（与 agent-browser 文档一致）。

详见 docs/cli-json.md、docs/cli-llm.md（Agent 如何用 CLI，不引入自创 JSON 字段）。

命令概览

店铺管理 store

ziniao store list [--opened-only]        # 列出店铺
ziniao store open <store_id>             # 打开店铺
ziniao store close <store_id>            # 关闭店铺
ziniao store start-client                # 启动紫鸟客户端
ziniao store stop-client                 # 停止紫鸟客户端

顶层快捷：ziniao list-stores、ziniao open-store <id>、ziniao close-store <id>

Chrome 管理 chrome

ziniao chrome launch [--url <url>] [--name <名称>]    # 启动 Chrome
ziniao chrome connect <cdp_port> [--name <名称>]      # 连接已有 Chrome
ziniao chrome list                                     # 列出 Chrome 会话
ziniao chrome close <session_id>                       # 关闭 Chrome 会话

顶层快捷：ziniao launch、ziniao connect <port>

launch vs connect：launch 由 ziniao 启动 Chrome 进程，close 时会终止该进程；connect 连接外部已有 Chrome，close 时仅断开 CDP 连接，不杀进程。若 launch 检测到 profile 已被占用（如 Chrome 已在运行），会自动降级为 connect 模式。

Chrome 路径和 profile 目录通过环境变量 CHROME_PATH / CHROME_USER_DATA 配置（见上方环境变量表），设置 CHROME_USER_DATA 可跨次启动复用登录态和 Cookie。

会话管理 session

ziniao session list                      # 列出所有会话（紫鸟 + Chrome）
ziniao session switch <session_id>       # 切换活动会话
ziniao session info <session_id>         # 查看会话详情

导航 nav

ziniao nav go <url>                      # 导航到 URL
ziniao nav tab list                      # 标签页列表
ziniao nav tab new [url]                 # 新建标签页
ziniao nav tab switch --index <i>        # 切换标签页
ziniao nav tab close                     # 关闭当前标签页
ziniao nav frame list                    # iframe 列表
ziniao nav wait <selector>               # 等待元素
ziniao nav back                          # 后退
ziniao nav forward                       # 前进
ziniao nav reload [--ignore-cache]       # 刷新

顶层快捷：ziniao navigate <url>、ziniao tab、ziniao wait、ziniao back、ziniao forward、ziniao reload

页面交互 act

ziniao act click <selector>              # 点击
ziniao act fill <selector> <value>       # 填写输入框
ziniao act type <text> [-s <selector>]   # 逐字输入
ziniao act press <key>                   # 按键（Enter, Tab, Ctrl+a 等）
ziniao act hover <selector>              # 悬停
ziniao act dblclick <selector>           # 双击
ziniao act drag <source> <target>        # 拖拽
ziniao act upload <selector> <file...>   # 上传文件
ziniao act dialog [accept|dismiss]       # 弹窗处理
ziniao act focus <selector>              # 聚焦
ziniao act select <selector> <value>     # 下拉选择
ziniao act check <selector>              # 勾选
ziniao act uncheck <selector>            # 取消勾选
ziniao act keydown <key>                 # 按下键
ziniao act keyup <key>                   # 释放键

顶层快捷：ziniao click、ziniao fill、ziniao type、ziniao press、ziniao hover、ziniao dblclick

页面信息 info

ziniao info snapshot [-o file.html]      # HTML 快照
ziniao info screenshot [file.png]        # 截图
ziniao info eval <js_expression>         # 执行 JavaScript
ziniao info url                          # 当前 URL
ziniao info console [--level error]      # 控制台消息
ziniao info network [--id <id>]          # 网络请求
ziniao info errors                       # 页面错误
ziniao info highlight <selector>         # 高亮元素
ziniao info cookies [--action list|set|clear]   # Cookie 管理
ziniao info storage [--type local|session]      # Storage 管理
ziniao info clipboard [--action read|write]     # 剪贴板

顶层快捷：ziniao snapshot、ziniao screenshot、ziniao eval、ziniao url

获取元素信息 get

ziniao get text <selector>               # 元素文本
ziniao get html <selector>               # 元素 HTML
ziniao get value <selector>              # 输入框值
ziniao get attr <selector> <attribute>   # 元素属性
ziniao get title                         # 页面标题
ziniao get url                           # 页面 URL
ziniao get count <selector>              # 匹配元素数量

顶层快捷：ziniao title、ziniao url（即 get title / get url）

查找元素 find

ziniao find text <文本> [--action click]       # 按文本查找
ziniao find role <角色> [--name <名称>]        # 按 ARIA 角色查找
ziniao find first <selector>                   # 第一个匹配元素
ziniao find last <selector>                    # 最后一个匹配元素
ziniao find nth <selector> --index <n>         # 第 N 个匹配元素

状态检查 is

ziniao is visible <selector>             # 是否可见
ziniao is enabled <selector>             # 是否可用
ziniao is checked <selector>             # 是否选中

滚动 scroll

ziniao scroll down [--pixels 300]        # 向下滚动
ziniao scroll up [--pixels 300]          # 向上滚动
ziniao scroll left / right               # 左右滚动
ziniao scroll into <selector>            # 滚动到元素

顶层快捷：ziniao scrollinto <selector>

鼠标 mouse

ziniao mouse move <x> <y>               # 移动到坐标
ziniao mouse down [--button left|right]  # 按下
ziniao mouse up [--button left|right]    # 释放
ziniao mouse wheel --delta-y <n>         # 滚轮

网络拦截 network

ziniao network list [--filter <pattern>] # 请求列表
ziniao network list --id <request_id>    # 请求详情
ziniao network route <pattern> --abort   # 拦截请求
ziniao network unroute [<pattern>]       # 移除拦截
ziniao network routes                    # 查看拦截规则
ziniao network har-start                 # 开始 HAR 录制
ziniao network har-stop [<file>]         # 停止并保存 HAR

录制回放 rec

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]   # 回放
ziniao rec list                          # 列出录制
ziniao rec delete <名称>                 # 删除录制
ziniao rec status                        # 录制中引擎、scope、缓冲条数等

• dom2（默认）：CDP Runtime.addBinding 将事件送入 daemon 缓冲，避免切错标签导致空录；scope=all 可挂多个标签（受 --max-tabs 限制）；轮询会为新开页面补挂桩。
• legacy（--engine legacy）：页内 Symbol 缓冲，stop 时从当前活动页读取（旧行为）。

批量执行 batch

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

从 stdin 读取 JSON 命令数组，依次执行。配合 --bail 可在首个错误时停止。

系统 sys

ziniao sys quit                          # 关闭 daemon
ziniao sys emulate --device "iPhone 15"  # 设备模拟
ziniao sys emulate --width 800 --height 600   # 自定义视口

顶层快捷：ziniao quit、ziniao emulate

配置管理 config

ziniao config init [--force]             # 交互式向导 → 生成 ~/.ziniao/config.yaml
ziniao config show                       # 显示当前生效配置及来源
ziniao config set <key> <value>          # 修改配置（dotted key: chrome.path）
ziniao config path                       # 显示配置文件路径
ziniao config env [--shell powershell|bash|json|mcp]  # 输出环境变量导出语句

升级 update

ziniao update [--git] [--sync] [--dry-run]  # 用 uv 升级 CLI（Windows 默认新窗口避免 exe 自占用）

MCP 服务 serve

ziniao serve [--config config.yaml]      # 启动 MCP Server

常用示例

# 启动 Chrome 并打开百度
ziniao launch --url https://www.baidu.com

# 连接已有 Chrome（需以 --remote-debugging-port 启动）
ziniao connect 9222

# 查看当前所有会话
ziniao session list

# 导航、交互、获取信息
ziniao navigate https://example.com
ziniao click "button.submit"
ziniao fill "input[name=search]" "关键词"
ziniao press Enter
ziniao title
ziniao --json url

# 截图与快照
ziniao screenshot page.png
ziniao snapshot -o page.html

# 执行 JavaScript
ziniao eval "document.title"
ziniao --json eval "document.querySelectorAll('a').length"

# 网络监控
ziniao --json network list --limit 10
ziniao network route "*.ads.*" --abort

# 录制操作
ziniao rec start
# ...在浏览器中操作...
ziniao rec stop --name my-flow
ziniao rec replay my-flow

# JSON 输出（与 agent-browser 相同信封；业务字段在 .data）
ziniao --json session list
ziniao --json get title
# 与 agent-browser 一致：边界标记 + 截断
ziniao --json --content-boundaries --max-output 8000 info snapshot
# 旧脚本扁平 JSON：ziniao --json-legacy session list

提示：所有命令均支持 --help 查看详细参数，如 ziniao chrome launch --help。

特性

• 紫鸟可选：不配置紫鸟也能使用全部 Chrome 浏览器功能（启动/连接/页面操作/录制回放），零配置即可上手
• 统一浏览器支持：紫鸟店铺（多店铺、WebDriver）与本地 Chrome（启动/连接 CDP）同一套 MCP 工具
• 全部 MCP 工具：店铺管理、Chrome 管理、统一会话、页面导航、输入自动化、录制回放、网络监控、调试截图等
• 4 个 AI 技能（Skills）：浏览器自动化、店铺管理、亚马逊运营、店铺运营 RPA 脚本生成
• 1 个专用 Agent：紫鸟运营专家角色，具备跨境电商领域知识
• 2 个快捷命令（Commands）：一键检查店铺状态、批量截图
• 跨会话状态持久化：MCP 进程重启后可恢复已打开店铺或 Chrome 的 CDP 连接
• 多会话并行：同时打开多个紫鸟店铺或 Chrome 实例，按需切换活动会话
• 跨平台：支持 Windows / macOS / Linux

工具列表

店铺管理（紫鸟，7 个）

工具	说明
start_client	启动紫鸟客户端（WebDriver 模式）
list_stores	获取所有店铺列表（自动启动客户端）
list_open_stores	查询当前已打开的店铺（通过 CDP 端口验证）
open_store	打开店铺并建立 CDP 连接
connect_store	连接已运行的店铺（不重启，推荐）
close_store	关闭店铺并断开 CDP
stop_client	退出紫鸟客户端

Chrome 管理（4 个）

工具	说明
launch_chrome	启动本地 Chrome 并通过 CDP 连接
connect_chrome	连接已运行的 Chrome（需带 --remote-debugging-port 启动）
list_chrome	列出当前所有 Chrome 会话
close_chrome	关闭指定 Chrome 会话

统一会话（1 个）

工具	说明
browser_session	列出/切换/查看所有浏览器会话（紫鸟 + Chrome）

输入自动化（9 个）

工具	说明
click	点击元素
fill	清空并填写输入框
fill_form	批量填写表单
type_text	逐字输入文本（模拟真实键盘）
press_key	按键（如 Enter、Tab、Ctrl+A）
hover	悬停
drag	拖拽元素
handle_dialog	设置弹窗处理策略
upload_file	上传文件

导航（6 个）

工具	说明
navigate_page	导航到 URL
list_pages	列出所有标签页
select_page	切换标签页
new_page	新建标签页
close_page	关闭标签页
wait_for	等待元素/页面加载

仿真（2 个）

工具	说明
emulate	模拟设备（iPhone、iPad、Pixel 等）
resize_page	调整视口大小

网络（2 个）

工具	说明
list_network_requests	列出捕获的网络请求
get_network_request	获取请求详情（含请求头/响应头）

调试（5 个）

工具	说明
evaluate_script	执行 JavaScript
take_screenshot	截图（支持元素截图和全页截图）
take_snapshot	获取页面 HTML 快照
list_console_messages	列出控制台消息
get_console_message	获取消息详情

录制与回放（1 个）

工具	说明
recorder	录制浏览器操作（点击/输入/按键/导航），停止后生成 .json + 可独立运行的 .py 脚本；支持回放、列表、删除

RPA 与录制

RPA 自动化技巧

用 MCP 做店铺或 Chrome 的 RPA 时，建议遵循「探索 → 验证 → 固化」的思路：

• 选择器优先：#id > [name="x"] > [data-testid="x"] > 有唯一性的 class，避免依赖复杂 DOM 层级。
• 每步验证：每次 click / fill / press_key 后，用 wait_for(结果元素) 或 take_snapshot() 确认页面状态，再继续下一步，避免脚本在页面未就绪时操作。
• 异常与弹窗：操作前可 handle_dialog(action="accept") 预设弹窗策略；对懒加载/分页，先滚动或点击下一页再 wait_for 新内容。
• 数据与 API：需要批量取数时，可用 list_network_requests / get_network_request 抓接口，评估用接口还是页面操作更稳。
• 多店铺一致：多店铺场景下用 list_stores、connect_store 切换店铺，在同一流程上验证各站点差异并记录。

配合 store-rpa-scripting 技能，可把探索好的步骤整理成文档，再生成不依赖 MCP 的独立 Python 脚本（ziniao_webdriver + nodriver），用于定时任务或本地直接运行。

录制与回放

recorder 工具提供「录操作 → 停录保存 → 回放或生成脚本」的完整能力，对紫鸟店铺和 Chrome 通用（需先有活动会话）。

操作	说明
开始录制	recorder(action='start')：在当前页注入监听，之后在浏览器中的点击、输入、按键、导航都会被记录。支持跨页：点击链接导致整页跳转时，会自动在新页重新注入并记录一次 navigate。
停止并保存	recorder(action='stop', name='可选名称')：停止录制，将操作序列保存到 ~/.ziniao/recordings/，并生成 .json（供 MCP 回放）与可独立运行的 .py 脚本（基于 nodriver）。
回放	recorder(action='replay', name='录制名称') 或传入 actions_json 直接回放；可用 speed 调节回放速度。
管理	recorder(action='list') 列出已保存录制，recorder(action='delete', name='...') 删除指定录制。

典型用法：先 open_store 或 launch_chrome 打开目标页面，再让 Agent 调用 recorder(action='start')，你在浏览器里操作一遍，最后 recorder(action='stop') 即可得到可复用的脚本与回放数据。

典型使用流程

基本流程

在 Cursor 中对 Agent 说：

打开我的紫鸟店铺列表，打开第一个亚马逊店铺，然后截图看看当前页面

Agent 会依次调用：

1. list_stores → 获取店铺列表（自动启动客户端）
2. open_store("xxx") → 打开店铺并建立 CDP 连接
3. take_screenshot() → 截图返回

恢复已打开的店铺

连接我之前打开的店铺，导航到亚马逊后台

Agent 调用：

1. list_open_stores → 查看哪些店铺还在运行
2. connect_store("xxx") → 恢复 CDP 连接（不重启店铺）
3. navigate_page("https://sellercentral.amazon.com") → 导航

表单自动化

帮我在当前页面填写商品标题和价格

Agent 调用：

1. take_snapshot() → 获取页面 HTML 分析表单结构
2. fill_form('[{"selector": "#title", "value": "商品名"}, {"selector": "#price", "value": "99.99"}]') → 批量填写

项目结构

ziniao-mcp/
├── .cursor-plugin/
│   └── plugin.json          # Cursor Plugin manifest
├── .mcp.json                # MCP Server 配置（Plugin 自动发现）
├── skills/                  # AI 技能指南
│   ├── ziniao-browser/      # 核心浏览器自动化技能
│   │   └── SKILL.md
│   ├── store-management/    # 多店铺管理技能
│   │   └── SKILL.md
│   ├── amazon-operations/   # 亚马逊运营技能
│   │   └── SKILL.md
│   └── store-rpa-scripting/ # 店铺运营 RPA 脚本生成（探索→确认→生成脚本+过程文档）
│       ├── SKILL.md
│       ├── tools-reference.md
│       ├── doc-template.md
│       └── examples.md
├── agents/                  # 自定义 Agent 角色
│   └── ziniao-operator.md   # 紫鸟运营专家
├── commands/                # 快捷命令
│   ├── quick-check-stores.md
│   └── batch-screenshot.md
├── ziniao_webdriver/        # 紫鸟客户端 HTTP 通信层
│   ├── __init__.py
│   └── client.py            # ZiniaoClient 类
├── ziniao_mcp/              # MCP 服务器 + CLI
│   ├── __init__.py
│   ├── __main__.py          # python -m ziniao_mcp 入口
│   ├── server.py            # 配置解析 + 工具注册 + 启动
│   ├── session.py           # 会话管理 + CDP 连接 + 状态持久化
│   ├── cli/                 # CLI 命令行工具（90 个子命令）
│   │   ├── __init__.py      # Typer 主入口 + 全局选项
│   │   ├── connection.py    # daemon 连接层
│   │   ├── dispatch.py      # 命令分发（daemon 侧）
│   │   └── commands/        # 16 个命令组
│   └── tools/               # MCP 工具集
│       ├── store.py         # 店铺管理 (7)
│       ├── input.py         # 输入自动化 (9)
│       ├── navigation.py    # 导航 (6)
│       ├── emulation.py     # 仿真 (2)
│       ├── network.py       # 网络 (2)
│       └── debug.py         # 调试 (5)
├── config/
│   └── config.yaml          # 默认配置文件
├── docs/                    # 项目文档
│   ├── installation.md      # 安装与使用
│   ├── architecture.md      # 架构设计
│   ├── api-reference.md     # API 参考
│   └── development.md       # 开发指南
├── pyproject.toml
└── README.md

Plugin 组件

Skills（AI 技能）

技能	触发场景
ziniao-browser	浏览器自动化操作、页面交互、截图调试
store-management	多店铺管理、会话恢复、批量操作
amazon-operations	亚马逊 Listing 管理、订单处理、广告分析
store-rpa-scripting	RPA 脚本生成：用 MCP 工具探索页面 → 确认步骤 → 生成可独立运行的 Python 脚本（nodriver + ziniao_webdriver）及复现文档

Agents（专用角色）

Agent	说明
ziniao-operator	跨境电商运营专家，具备多平台操作经验和安全意识

Commands（快捷命令）

命令	说明
quick-check-stores	一键检查所有店铺状态
batch-screenshot	对所有已打开店铺截图

技术栈

组件	技术
MCP 协议	mcp (FastMCP)
CLI 框架	typer + rich
浏览器自动化	nodriver (CDP)
客户端通信	requests (HTTP)
CDP 探测	httpx (异步)
配置解析	PyYAML
包管理	uv + hatchling

CDP 调试端口说明

• open_store 调用紫鸟的 startBrowser API，紫鸟自动为店铺浏览器实例开启 CDP 端口
• MCP 服务器通过 nodriver 的 Browser.create() 连接到该端口
• 所有浏览器自动化工具通过此连接操作店铺页面
• 已打开店铺的 CDP 信息持久化在 ~/.ziniao/sessions.json，支持跨进程恢复

文档

文档	说明
安装与使用	Plugin / MCP / PyPI 多种安装方式、配置、故障排查
Windows 下安装 uv	在 Windows 上安装 uv（PowerShell / WinGet / Scoop）
架构设计	三层架构、模块职责、数据流
API 参考	全部 MCP 工具的详细参数和返回值
开发指南	添加新工具、调试、构建发布、GitHub 自动发布 PyPI
CLI JSON 输出	--json / --json-legacy 与 jq 字段路径
CLI 与 LLM	与 agent-browser 对齐：--json + --content-boundaries + --max-output、ZINIAO_*、快照语义
与 agent-browser CLI 对照	全量命令、参数语义、batch/snapshot 差异与 daemon 命令表

上游与贡献

本仓库主托管于 github.com/tianyehedashu/ziniao-mcp。若以 submodule 或 vendor 方式嵌入其他项目，建议在 上游仓库 提交 PR，再于父仓库更新 submodule 指针（git submodule update --remote third_party/ziniao-mcp 等），以便 PyPI 包 ziniao 与文档单一来源。

许可证

以仓库根目录 LICENSE 为准（当前为 MIT）。pyproject.toml 中的 license 字段与之一致，便于 PyPI 元数据展示。

调试时请注意：~/.ziniao/mcp_debug.log 在 DEBUG 级别下可能包含 URL 等敏感信息，勿随意分享。