archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）

来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
2026-10-05 12:11:35 +00:00
commit 322b7737eb
@@ -0,0 +1,84 @@
+# Skill Hub
+
+[紫鸟开放平台](https://open.ziniao.com/) 的 **Agent Skills** 仓库，面向所有支持 Agent Skill 规范的 AI 编程助手与 Agent 运行时。
+
+仓库内有两类 Skill：
+
+- **文档型 Skill**：用 `SKILL.md` 提供定位、能力概览与按需深入的导航，用 `reference/` 存放可被精确检索的接口细节。Agent 在需要理解某个产品"是什么、能做什么、怎么对接"时加载，再按需深入到具体接口参数，既掌握全局又不被细节淹没。
+- **执行型 Skill**：面向普通用户直接完成任务，无需关心内部调用细节。Agent 按契约直接调用开放平台接口拿到最终结果。
+
+## 目录结构
+
+```
+skills/
+├── ziniao-erp-api-doc/        # 紫鸟 ERP API 文档（文档型）
+├── ziniao-sso-doc/            # 紫鸟单点登录 OpenAPI 文档（文档型）
+├── ziniao-webdriver-doc/      # 紫鸟浏览器 WebDriver 自动化接口文档（文档型）
+└── linkfoxai-image-tool/      # LinkFoxAI 图片处理工具（执行型）
+```
+
+各类型 Skill 的结构：
+
+```
+# 文档型
+<skill-name>/
+├── SKILL.md          # 入口：定位、能力边界、架构流程、按需深入导航
+└── reference/        # 细节：按模块拆分的接口请求/响应参数、示例
+
+# 执行型
+<skill-name>/
+└── SKILL.md          # 入口：触发条件、执行流程、能力分组、调用契约
+```
+
+## 已收录 Skills
+
+| Skill | 类型 | 说明 | 适用场景 |
+|-------|------|------|----------|
+| `ziniao-erp-api-doc` | 文档型 | 紫鸟 ERP REST API（Bearer API Key 认证，72 个接口） | ERP 系统对接规划、集成设计、接口权限评估 |
+| `ziniao-sso-doc` | 文档型 | 紫鸟单点登录 OpenAPI | ERP 系统 SSO 对接、身份集成设计 |
+| `ziniao-webdriver-doc` | 文档型 | 紫鸟浏览器 WebDriver 本地自动化接口 | 自动化集成选型、Selenium/Puppeteer/Playwright/DrissionPage 对接 |
+| `linkfoxai-image-tool` | 执行型 | LinkFoxAI 图片处理（图片上传、场景裂变、商品替换、自动抠图） | 用户要求直接完成图片处理任务并拿到最终结果 |
+
+## 兼容的 Agent
+
+本仓库遵循 [Agent Skill 规范](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)，`SKILL.md` 的 frontmatter（`name` + `description`）可被任何支持该规范的工具识别并按需加载。已验证/适用的 Agent 包括（不限于）：
+
+- **Claude Code**（Anthropic 官方 CLI）
+- **Codex**（OpenAI）
+- **Cursor**
+- **OpenClaw**
+- 其他兼容 Agent Skill 规范的运行时
+
+## 使用方式
+
+### 安装 Skill
+
+通过 `skills` CLI 安装。仓库地址为 `ziniao-open/skill-hub`：
+
+```bash
+# 安装全部 Skill
+npx skills add ziniao-open/skill-hub
+
+# 安装指定 Skill（@ 后跟 skills/ 下的目录名）
+npx skills add ziniao-open/skill-hub@ziniao-erp-api-doc
+npx skills add ziniao-open/skill-hub@ziniao-sso-doc
+npx skills add ziniao-open/skill-hub@ziniao-webdriver-doc
+npx skills add ziniao-open/skill-hub@linkfoxai-image-tool
+```
+
+> Tip: 使用 `--yes`（`-y`）与 `--global`（`-g`）参数可跳过确认提示并全局安装：
+> ```bash
+> npx skills add ziniao-open/skill-hub -y -g
+> ```
+
+安装完成后，Agent 会在匹配到对应 `description` 的场景下自动加载并参考相应 Skill。
+
+### 阅读约定
+
+- **先读 `SKILL.md`**：了解 Skill 的定位、能力边界与执行/深入流程。
+- **文档型**：通过 `SKILL.md` 的"按需深入"导航定位到具体文件，仅在需要查阅接口请求/响应参数、示例代码时读取对应 `reference/` 文件，避免一次性加载全部细节。
+- **执行型**：按 `SKILL.md` 中的能力分组与调用契约，优先复用本地脚本（若存在），否则直接调用开放平台接口完成任务并返回结果。
+
+## 许可证
+
+本仓库由紫鸟开放平台维护，内容包含接口文档与执行型 Skill，供开发者集成对接与自动化使用。使用本仓库即表示你已阅读并同意紫鸟开放平台的相关服务条款；接口的实际调用受开放平台的鉴权、计费与限流策略约束。
@@ -0,0 +1,301 @@
+---
+name: linkfoxai-image-tool
+description: 这是紫鸟开放平台Skill，面向普通用户直接执行任务，无需关心内部调用细节；当用户要求直接完成图片上传、场景裂变、商品替换、自动抠图等当前 Skill 覆盖能力，并希望直接拿到最终结果时使用本 Skill。执行时优先复用本地脚本（若存在），否则通过开放平台接口完成调用。
+---
+
+# linkfoxai-image-tool
+
+## Trigger Conditions
+
+- 当用户目标属于当前 Skill 覆盖的能力分组，且希望直接拿到最终结果时，可使用本 Skill。
+- 当前 Skill 覆盖的能力分组：
+- `linkfox-image-upload`: 图片上传
+- `linkfox-scene-fission`: 场景裂变
+- `linkfox-shop-replace`: 商品替换
+- `linkfox-auto-image-matting`: 自动抠图
+- 若用户目标是查询当前 Skill 覆盖任务的状态、处理进度或最终结果，也属于可直接执行的适用场景。
+
+## When Not To Use
+
+- 当用户只需要开放平台接入说明、参数解释、代码开发建议或集成设计时，不要使用本 Skill。
+- 当请求不属于当前 Skill 覆盖的能力范围时，不要强行复用本 Skill。
+- 当需要你猜测未在契约中声明的参数、字段或调用行为时，不要继续执行，应以现有契约为准。
+
+## Execution Flow
+
+- `Step 1`: 读取当前 skill 的 `scripts/` 目录，确认是否存在可用的本地脚本及 `脚本使用指导.md`。
+- `Step 2`: 若存在脚本，先读取 `scripts/脚本使用指导.md`，确认脚本的 payload、成功/失败语义与退出码规则。
+- `Step 3`: 根据当前执行环境属于 `Win`、`macOS` 还是 `Linux`，按 `tool分组名_平台` 规则组合目标脚本名；`Win` 对应 `.ps1`，`macOS` 与 `Linux` 对应 `.sh`。
+- `Step 4`: 若脚本存在且执行成功，直接使用脚本标准输出作为最终结果。
+- `Step 5`: 若脚本不存在，或脚本执行失败并返回非 `0` 退出码，则改用对应的执行型 tool 直接调用开放平台，按 `requestUrl`、`Raw Request Contract` 与 `Raw Response Contract` 完成调用。
+
+## Execution Prerequisites
+
+- `callDomain`: `https://sbappstoreapi.ziniao.com/openapi-router`
+- `apiKey`: 先确认 `ZNOPEN_API_KEY` 已可用；默认从 `~/.znopen/config.json` 读取，缺失时先提示用户提供，提供后回填文件，完成配置。
+- `Authorization`: 无需让用户手工拼接请求头，tool 在调用开放平台时会基于可用的 `apiKey` 自动注入该头。
+- `requestUrl`: 统一由 `callDomain + sourceOpenPath` 组成，调用前应直接使用已生成结果，不建议手工改写。
+
+## Capability Groups
+
+### linkfox-image-upload
+- 适用请求：图片上传
+- 开放平台执行 tool：`postImageV2UploadByBase64`
+
+### linkfox-scene-fission
+- 适用请求：场景裂变
+- 开放平台执行 tool：`postImageV2MakeSceneFission`、`postImageV2MakeInfo`
+
+### linkfox-shop-replace
+- 适用请求：商品替换
+- 开放平台执行 tool：`postImageV2MakeShopReplace`、`postImageV2MakeInfo`
+
+### linkfox-auto-image-matting
+- 适用请求：自动抠图
+- 开放平台执行 tool：`postImageV2MakeCutout`、`postImageV2MakeInfo`
+
+## Call Limits
+
+- tool 发起开放平台请求时，必须自动带上请求头：`Authorization: Bearer {ApiKey}`。
+- `Bearer` 和 `ApiKey` 之间必须有一个空格，不能省略、不能连写、也不能替换为其他前缀。
+- 请求方法必须与对应 tool 的 `sourceMethod` 保持一致，不允许自行切换调用方式。
+- 请求参数必须严格遵循 `Raw Request Contract`，响应解析与错误处理必须严格遵循 `Raw Response Contract`。
+- 当前置条件未满足、凭证缺失或开放平台返回错误时，不应继续盲目重试或猜测字段含义。
+
+## Tool Group Definitions
+
+### linkfox-image-upload
+
+#### `postImageV2UploadByBase64`
+
+- Capability Group: `linkfox-image-upload`
+- Use This Tool When: 当用户当前目标属于“图片上传”场景时使用；通过开放平台接口完成“图片上传”。
+- Required Inputs: fileName、base64
+- Returns: 重点查看返回字段：msg、traceId、code、viewUrl
+- Tool Goal: 图片上传
+
+##### Definition
+
+```yaml
+tool: postImageV2UploadByBase64
+sourceApiName: 图片上传
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/uploadByBase64
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/uploadByBase64
+```
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"fileName","id":"bzxlv5tv","type":"string","required":1,"desc":"文件名（带扩展名）支持格式：jpeg、jpg、png、webp","value":"1.png"},{"isRoot":false,"name":"base64","id":"6bzgux9i","type":"string","required":1,"desc":"图片数据base64编码 文件大小：不超过20MB","value":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"UploadByBase64ReqVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"viewUrl","id":"ohy4rmpb","type":"string","required":0,"desc":"上传成功后的图片访问地址"}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«ApiImageUploadResVo»"}]
+```
+
+### linkfox-scene-fission
+
+#### `postImageV2MakeSceneFission`
+
+- Capability Group: `linkfox-scene-fission`
+- Use This Tool When: 当用户当前目标属于“场景裂变”场景时使用；通过开放平台接口完成“场景裂变”。
+- Required Inputs: imageUrl、segImageUrl、strength、prompt
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Tool Goal: 场景裂变
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeSceneFission
+sourceApiName: 场景裂变
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/sceneFission
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/sceneFission
+```
+
+##### Input Rules
+
+- Image Input Rule: 当前契约只看到 URL 类图片字段，请按契约中的 `https` 图片地址字段传参。
+- 不要自行追加 `base64` 字段，除非它已经明确出现在 `Raw Request Contract` 中。
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"imageUrl","id":"bzxlv5tv","type":"string","required":1,"desc":"原图","value":"https://test-file-ai.linkfox.com/UPLOAD/MANAGE/CASE/SCENE_FISSION/1744309376725860352/image.jpg"},{"isRoot":false,"name":"segImageUrl","id":"6bzgux9i","type":"string","required":0,"desc":"保留区域图，不传会自动调用智能抠图"},{"id":"r8mecvca","name":"strength","type":"number","desc":"生成图与原图相似度 默认值：0.5 值越大相似度度越高 浮点数 小数点后只有一位 可选范围 [0.1,1]","isInit":true,"required":0},{"id":"grl5efmb","name":"prompt","type":"string","desc":"强化内容描述，不传会自动根据参数图提取 最长600字符，超出会截断","isInit":true,"required":0},{"id":"87njvdrs","name":"imageOutputWidth","type":"integer","desc":"输出尺寸 宽度 最长不能超过2048,最短不能低于32","isInit":true,"required":0},{"id":"ukpogp3d","name":"imageOutputHeight","type":"integer","desc":"输出尺寸 高度 最长不能超过2048,最短不能低于32","isInit":true,"required":0},{"id":"ob2j7568","name":"provider","type":"string","desc":"场景裂变模式 SCENE_FISSION_REALISTIC：写实（默认值） SCENE_FISSION_SIMPLE：简约   SCENE_FISSION_INTELLIGENT：智能","isInit":true,"value":"SCENE_FISSION_REALISTIC"},{"id":"g017pou2","name":"outputNum","type":"integer","desc":"输出张数 取值范围：[1,4] 默认值：1","isInit":true,"required":0}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"SceneFissionParamsVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«OnlyIdVo»"}]
+```
+
+#### `postImageV2MakeInfo`
+
+- Capability Group: `linkfox-scene-fission`
+- Use This Tool When: 当用户当前目标属于“场景裂变”场景时使用；通过开放平台接口完成“获取AI作图结果”。
+- Required Inputs: id
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Reuse Note: 该 tool 名称在多个能力分组中复用；当前块表示它在 `linkfox-scene-fission` 场景下的使用入口，按当前分组目标理解即可。
+- Tool Goal: 获取AI作图结果
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeInfo
+sourceApiName: 获取AI作图结果
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/info
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/info
+```
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"id","id":"bzxlv5tv","type":"string","required":1,"desc":"作图任务ID","value":"111"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"OnlyIdVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"},{"isRoot":false,"name":"status","id":"gcq4vu8w","type":"integer","required":0,"desc":"状态 1.排队中 2.生成中 3.成功 4.失败"},{"isRoot":false,"name":"errorCode","id":"6r3j5kog","type":"string","required":0,"desc":"错误码"},{"isRoot":false,"name":"errorMsg","id":"46vvp4b4","type":"string","required":0,"desc":"错误文字描述"},{"isRoot":false,"name":"resultList","id":"k0lmm7mt","type":"array","required":0,"desc":"输出结果图片数组","children":[{"isRoot":false,"name":"id","id":"item1","type":"integer","required":0,"desc":"图片ID"},{"isRoot":false,"name":"status","id":"item2","type":"integer","required":0,"desc":"状态 0.生成中 1.成功 2.失败"},{"isRoot":false,"name":"url","id":"item3","type":"string","required":0,"desc":"高清图"},{"isRoot":false,"name":"width","id":"item4","type":"integer","required":0,"desc":"宽"},{"isRoot":false,"name":"height","id":"item5","type":"integer","required":0,"desc":"高"},{"isRoot":false,"name":"format","id":"item6","type":"string","required":0,"desc":"格式"}]}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«ApiImageMakeResVo»"}]
+```
+
+### linkfox-shop-replace
+
+#### `postImageV2MakeShopReplace`
+
+- Capability Group: `linkfox-shop-replace`
+- Use This Tool When: 当用户当前目标属于“商品替换”场景时使用；通过开放平台接口完成“商品替换”。
+- Required Inputs: imageUrl、sourceImageUrl、targetOriginUrl、targetImageUrl
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Tool Goal: 商品替换
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeShopReplace
+sourceApiName: 商品替换
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/shopReplace
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/shopReplace
+```
+
+##### Input Rules
+
+- Image Input Rule: 当前契约只看到 URL 类图片字段，请按契约中的 `https` 图片地址字段传参。
+- 不要自行追加 `base64` 字段，除非它已经明确出现在 `Raw Request Contract` 中。
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"imageUrl","id":"bzxlv5tv","type":"string","required":1,"desc":"商品原图","value":"https://linkfoxai-ailab.oss-cn-shenzhen.aliyuncs.com/UPLOAD/1701144666432344064/2024/11/18/96a7a42fc965491dbc625d2db09f2478.png"},{"isRoot":false,"name":"sourceImageUrl","id":"6bzgux9i","type":"string","required":0,"desc":"原图抠出来的商品图"},{"id":"r8mecvca","name":"targetOriginUrl","type":"string","desc":"替换的目标原图","isInit":true,"required":1,"value":"https://linkfoxai-ailab.oss-cn-shenzhen.aliyuncs.com/UPLOAD/1701144666432344064/2024/11/18/9778678b4724467485346248032387ec.png"},{"id":"grl5efmb","name":"targetImageUrl","type":"string","desc":"替换的目标原图抠图结果","isInit":true,"required":0},{"id":"87njvdrs","name":"denoiseStrength","type":"string","desc":"生成图变化程度 默认值：0.5 越大越高 浮点数 可选范围 [0,1]","isInit":true,"required":0},{"id":"ukpogp3d","name":"imageOutputWidth","type":"integer","desc":"输出尺寸 宽度 最长边不能超过4096,最短边不能低于32","isInit":true,"required":0},{"id":"g017pou2","name":"imageOutputHeight","type":"integer","desc":"输出尺寸 高度 最长边不能超过4096,最短边不能低于32","isInit":true,"required":0},{"id":"vtarf9ph","name":"outputNum","type":"integer","desc":"输出张数 取值范围：[1,4] 默认值：1","isInit":true,"required":0}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ShopReplaceParamsVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«OnlyIdVo»"}]
+```
+
+#### `postImageV2MakeInfo`
+
+- Capability Group: `linkfox-shop-replace`
+- Use This Tool When: 当用户当前目标属于“商品替换”场景时使用；通过开放平台接口完成“获取AI作图结果”。
+- Required Inputs: id
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Reuse Note: 该 tool 名称在多个能力分组中复用；当前块表示它在 `linkfox-shop-replace` 场景下的使用入口，按当前分组目标理解即可。
+- Tool Goal: 获取AI作图结果
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeInfo
+sourceApiName: 获取AI作图结果
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/info
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/info
+```
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"id","id":"bzxlv5tv","type":"string","required":1,"desc":"作图任务ID","value":"111"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"OnlyIdVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"},{"isRoot":false,"name":"status","id":"gcq4vu8w","type":"integer","required":0,"desc":"状态 1.排队中 2.生成中 3.成功 4.失败"},{"isRoot":false,"name":"errorCode","id":"6r3j5kog","type":"string","required":0,"desc":"错误码"},{"isRoot":false,"name":"errorMsg","id":"46vvp4b4","type":"string","required":0,"desc":"错误文字描述"},{"isRoot":false,"name":"resultList","id":"k0lmm7mt","type":"array","required":0,"desc":"输出结果图片数组","children":[{"isRoot":false,"name":"id","id":"item1","type":"integer","required":0,"desc":"图片ID"},{"isRoot":false,"name":"status","id":"item2","type":"integer","required":0,"desc":"状态 0.生成中 1.成功 2.失败"},{"isRoot":false,"name":"url","id":"item3","type":"string","required":0,"desc":"高清图"},{"isRoot":false,"name":"width","id":"item4","type":"integer","required":0,"desc":"宽"},{"isRoot":false,"name":"height","id":"item5","type":"integer","required":0,"desc":"高"},{"isRoot":false,"name":"format","id":"item6","type":"string","required":0,"desc":"格式"}]}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«ApiImageMakeResVo»"}]
+```
+
+### linkfox-auto-image-matting
+
+#### `postImageV2MakeCutout`
+
+- Capability Group: `linkfox-auto-image-matting`
+- Use This Tool When: 当用户当前目标属于“自动抠图”场景时使用；通过开放平台接口完成“自动抠图”。
+- Required Inputs: imageUrl、subType、clothClass
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Tool Goal: 自动抠图
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeCutout
+sourceApiName: 自动抠图
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/cutout
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/cutout
+```
+
+##### Input Rules
+
+- Image Input Rule: 当前契约只看到 URL 类图片字段，请按契约中的 `https` 图片地址字段传参。
+- 不要自行追加 `base64` 字段，除非它已经明确出现在 `Raw Request Contract` 中。
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"imageUrl","id":"bzxlv5tv","type":"string","required":1,"desc":"原图","value":"https://linkfoxai-ailab.oss-cn-shenzhen.aliyuncs.com/UPLOAD/1701144666432344064/2024/11/13/bec32c4461644befb202f86b23502583.png"},{"isRoot":false,"name":"subType","id":"6bzgux9i","type":"integer","required":1,"desc":"抠图类型 1: 通用 2: 人像 3: 商品 9: 服饰 12: 头发 13:人脸","value":"1"},{"id":"r8mecvca","name":"clothClass","type":"string","desc":"服饰分类，只有抠图类型=9（服饰抠图）时才会生效, 可多选，以','号分割","isInit":true,"required":0}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"CutoutParamsVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«OnlyIdVo»"}]
+```
+
+#### `postImageV2MakeInfo`
+
+- Capability Group: `linkfox-auto-image-matting`
+- Use This Tool When: 当用户当前目标属于“自动抠图”场景时使用；通过开放平台接口完成“获取AI作图结果”。
+- Required Inputs: id
+- Returns: 重点查看返回字段：msg、traceId、code、id
+- Reuse Note: 该 tool 名称在多个能力分组中复用；当前块表示它在 `linkfox-auto-image-matting` 场景下的使用入口，按当前分组目标理解即可。
+- Tool Goal: 获取AI作图结果
+
+##### Definition
+
+```yaml
+tool: postImageV2MakeInfo
+sourceApiName: 获取AI作图结果
+sourceMethod: POST
+sourceOpenPath: /linkfox-ai/image/v2/make/info
+requestUrl: https://sbappstoreapi.ziniao.com/openapi-router/linkfox-ai/image/v2/make/info
+```
+
+##### Raw Request Contract
+
+```text
+{"headers":[{"isRoot":false,"name":"Content-Type","id":"w8pqf70e","type":"","value":"application/json","required":1,"desc":""}],"query":[],"body":[{"isRoot":true,"children":[{"isRoot":false,"name":"id","id":"bzxlv5tv","type":"string","required":1,"desc":"作图任务ID","value":"111"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"OnlyIdVo"}]}
+```
+
+##### Raw Response Contract
+
+```text
+[{"isRoot":true,"children":[{"isRoot":false,"name":"msg","id":"474ze4ft","type":"string","required":0,"desc":"结果描述"},{"isRoot":false,"name":"traceId","id":"gcq4vu8w","type":"string","required":0,"desc":"链路追踪id"},{"isRoot":false,"name":"code","id":"6r3j5kog","type":"integer","required":0,"desc":"结果编码 200成功 非200报错"},{"isRoot":false,"children":[{"isRoot":false,"name":"id","id":"ohy4rmpb","type":"integer","required":0,"desc":"作图任务ID"},{"isRoot":false,"name":"status","id":"gcq4vu8w","type":"integer","required":0,"desc":"状态 1.排队中 2.生成中 3.成功 4.失败"},{"isRoot":false,"name":"errorCode","id":"6r3j5kog","type":"string","required":0,"desc":"错误码"},{"isRoot":false,"name":"errorMsg","id":"46vvp4b4","type":"string","required":0,"desc":"错误文字描述"},{"isRoot":false,"name":"resultList","id":"k0lmm7mt","type":"array","required":0,"desc":"输出结果图片数组","children":[{"isRoot":false,"name":"id","id":"item1","type":"integer","required":0,"desc":"图片ID"},{"isRoot":false,"name":"status","id":"item2","type":"integer","required":0,"desc":"状态 0.生成中 1.成功 2.失败"},{"isRoot":false,"name":"url","id":"item3","type":"string","required":0,"desc":"高清图"},{"isRoot":false,"name":"width","id":"item4","type":"integer","required":0,"desc":"宽"},{"isRoot":false,"name":"height","id":"item5","type":"integer","required":0,"desc":"高"},{"isRoot":false,"name":"format","id":"item6","type":"string","required":0,"desc":"格式"}]}],"name":"data","id":"k0lmm7mt","type":"object","required":0},{"isRoot":false,"name":"msgKey","id":"46vvp4b4","type":"string","required":0,"desc":"错误编码"}],"name":"","id":0,"type":"object","value":"","required":0,"desc":"ResponseDto«ApiImageMakeResVo»"}]
+```
@@ -0,0 +1,132 @@
+---
+name: ziniao-erp-api-doc
+description: >
+  Use when 需要理解紫鸟ERP API 的定位、能力、权限体系或调用流程，
+  用于 ERP 系统对接规划、集成设计或接口评估。
+  不要用于直接查阅具体接口参数——查阅时读取 reference/ 下对应文件。
+---
+
+# ziniao-erp-api-doc（紫鸟ERP API 文档）
+
+## 何时使用 / 不使用
+
+| 场景 | 做法 |
+|------|------|
+| 需要了解紫鸟 API 的能力和模块 | 读本 Skill |
+| 需要了解接口权限点以申请开通 | 读本 Skill §权限点汇总 |
+| 需要做 ERP 对接的集成设计 | 读本 Skill |
+| 需要查阅某个接口的详细参数 | 读本 Skill §按需深入，再读 reference/ 文件 |
+
+---
+
+## Level 0：定位与边界
+
+### 是什么
+
+紫鸟ERP REST API，面向 ERP/第三方系统，通过"简单通用模式"（Bearer API Key）认证，实现紫鸟浏览器的企业级管理——涵盖账号、设备、访问策略、角色权限、部门员工五大模块，共 72 个接口。
+
+### 能力概览
+
+| 能力域 | 接口数 | 说明 |
+|--------|--------|------|
+| 账号管理 | 22 | 账号 CRUD、授权管理、标签体系、缓存清除 |
+| 设备管理 | 11 | 套餐/设备购买续费、绑定解绑、自有设备管理 |
+| 访问策略 | 22 | 网页/分组管理、访问规则 CRUD、账号策略绑定 |
+| 角色和权限 | 7 | 角色 CRUD、权限列表、用户角色调整 |
+| 部门员工 | 10 | 部门 CRUD/移动、员工新增/修改/查询/启禁用 |
+
+### 不做什么（边界）
+
+- 不包含 OAuth 授权模式（仅覆盖简单通用模式）
+- 不包含浏览器指纹配置或窗口管理
+- 不包含账单/支付明细（仅含设备购买/续费操作）
+- 不包含企业创建/注销等顶级管理
+
+---
+
+## Level 1：架构与流程
+
+### 核心概念
+
+**API Key 认证**：在开放平台创建"卖家自研应用"并选择"简单通用模式"获取 API Key。请求头：`Authorization: Bearer {API_Key}`。
+
+**双层响应结构**：网关层（request_id / code / msg / data(业务层)）+ 业务层（ret / status / msg + 业务字段）。网关 code="0" 到达业务层；业务 ret=0 操作成功。失败时额外返回 sub_code / sub_msg。注意：业务数据不一定在业务层的 data 字段中，部分接口的业务字段直接位于业务层根级（参见各 reference 文件中的响应说明）。
+
+**核心 ID 体系**：companyId（紫鸟企业ID，几乎所有接口必传，可在开放平台首页右侧获取）、storeId（账号ID）、userId/staffId（用户ID）、proxyId（设备ID）、tagId/tid（标签ID）、roleId（角色ID）、ruleId（规则ID）。
+
+**权限点体系**：每个接口归属一个"所属权限点"，应用需在开放平台申请开通对应权限后才能调用。多个接口可共享同一权限点。
+
+### 调用流程
+
+```mermaid
+graph LR
+  A[获取 API Key] --> B[申请权限点]
+  B --> C[构造请求头]
+  C --> D[POST 请求]
+  D --> E{网关 code=0?}
+  E -- 是 --> F{业务 ret=0?}
+  E -- 否 --> G[检查 Key/权限]
+  F -- 是 --> H[解析业务字段]
+  F -- 否 --> I[读取 msg]
+```
+
+Base URL：`https://sbappstoreapi.ziniao.com/openapi-router`
+
+### 权限点汇总
+
+应用需在开放平台申请开通以下权限点，才能调用对应接口：
+
+| 模块 | 需申请的权限点 |
+|------|-------------|
+| 账号管理 | ERP-创建与删除账号权限、ERP-账号查看权限、ERP-编辑账号基础信息、ERP-账号授权权限、ERP-清除账号授权、ERP-清除账号缓存、ERP-查询某用户有权限的账号列表、ERP-标签列表、账号标签管理权限 |
+| 设备管理 | ERP-设备套餐列表查询权限、ERP-设备购买与续费权限、ERP-设备绑定权限、ERP-设备查询、ERP-开关自动续费、ERP-查询已购设备价格接口、ERP-解绑设备、ERP-添加自有设备（新）、ERP-修改自有设备信息（新） |
+| 访问策略 | ERP-网页访问权限（覆盖全部 22 个访问策略接口） |
+| 角色权限 | ERP-角色添加、修改权限、ERP-角色列表查询、ERP-角色详情、ERP-权限列表 |
+| 部门员工 | ERP-部门与员工接口、ERP-用户的部门变更 |
+
+每个 reference 文件中标注了各接口的具体权限点归属。
+
+### 公共响应结构
+
+```json
+{
+  "request_id": "全局请求追踪ID",
+  "code": "0",
+  "msg": "SUCCESS",
+  "data": {
+    "ret": 0,
+    "status": "success",
+    "data": [],
+    "msg": "",
+    "count": 0
+  }
+}
+```
+
+> **注意**：业务数据位置因接口而异。多数接口的业务数据在 `data.data` 中，但部分接口的业务字段直接在业务层根级（与 ret/status 同级）。例如"ERP-员工新增v2"返回的 id、password 直接在业务层，不在 data 字段内。请以各 reference 文件中"响应 data"或"响应"的标注为准——标注"响应 data"表示数据在 data 字段中，标注"响应"则表示字段在业务层根级。
+
+### 环境约定
+
+- 请求编码：UTF-8，Content-Type：application/json
+- 域名：`https://sbappstoreapi.ziniao.com/openapi-router`
+- 几乎所有接口均为 POST + JSON body
+- 前提：创建"卖家自研应用"，选择"简单通用模式"，申请所需权限点，配置 IP 白名单
+
+---
+
+## 按需深入（Level 2 路由表）
+
+> **规则：以下内容不要主动加载。**
+> 仅在需要了解某个细节时，按路由表读取对应的 reference/ 文件。
+
+| 你需要了解 | 读取文件 |
+|-----------|---------|
+| 认证方式、请求构造、代码示例（Java/Python/JS）、常见错误 | `reference/api-guide.md` |
+| 账号创建/删除/编辑/列表查询/标签列表/缓存清除 | `reference/account-crud.md` |
+| 账号授权新增/删除/查询/清除/授权用户列表 | `reference/account-auth.md` |
+| 标签添加/删除/重命名/绑定/解绑/替换/移除/清空/列表 | `reference/account-tags.md` |
+| 设备套餐/购买/续费/绑定/解绑/查询/自有设备管理 | `reference/device-management.md` |
+| 网页增删改查/网页分组管理 | `reference/access-policy-web.md` |
+| 访问规则新建/编辑/删除/启禁用/详情/成员账号设置 | `reference/access-policy-rules.md` |
+| 角色增改查/权限列表/用户角色调整 | `reference/roles-permissions.md` |
+| 部门增删改查移动/员工增改查启禁用/部门变更 | `reference/department-staff.md` |
@@ -0,0 +1,219 @@
+# 访问策略 - 访问规则与账号策略接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅访问规则的新建、编辑、删除、启禁用、详情，以及规则成员/账号设置、账号策略绑定接口时加载。
+
+所有接口**权限点**均为 **ERP-网页访问权限**，方法均为 POST。
+
+---
+
+## ERP-访问规则新建
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/add`
+
+> addIds 与 addNames 可任传其一，都传取并集。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| name | 规则名称 | 是 | string |
+| desc | 规则描述 | 是 | string |
+| activeUser | 生效成员（1除boss外所有/2指定成员/3指定部门/4指定角色） | 是 | number |
+| userChange | 指定成员对象 | 是 | object |
+| userChange.addIds | 新增成员id列表（空值传[]） | 否 | string[] |
+| userChange.addNames | 新增成员用户名列表 | 否 | string[] |
+| userChange.departmentIds | 指定部门列表 | 否 | number[] |
+| userChange.roleIds | 指定角色列表 | 否 | number[] |
+| activeAccount | 生效账号（0所有/1指定） | 是 | number |
+| accountChange | 指定账号对象 | 是 | object |
+| accountChange.addIds | 账号id列表 | 否 | string[] |
+| activeRange | 生效范围（1所有网站/2黑名单/3白名单） | 是 | string |
+| configs | 配置详情数组 | 是 | array |
+| configs[].urlId | 网页ID（activeRange=1时传0） | 是 | number |
+| configs[].isAccessible | 是否可访问 | 是 | boolean |
+| configs[].isLog | 是否记录日志 | 是 | boolean |
+| configs[].functions | 操作控制配置数组 | 是 | array |
+| configs[].functions[].function | clipboard/file_upload/file_download/print/console/password/mouse_click/keyboard_input | 是 | string |
+| configs[].functions[].permission | 1允许/2允许且记录/3限制且记录/6限制 | 是 | number |
+| isSkipRuleConflictCheck | 是否跳过冲突检测 | 是 | boolean |
+| effectiveTime | 生效时间（可选） | 否 | object |
+| effectiveTime.timeType | 0永久 1限制时间 | 是 | string |
+| effectiveTime.startTime | 开始时间戳（秒），永久填0 | 是 | number |
+| effectiveTime.endTime | 结束时间戳（秒），永久填0 | 是 | number |
+| isAllowRequest | 是否允许申请访问（默认true） | 否 | boolean |
+| shareCompanyIds | 合作公司id列表 | 否 | number[] |
+| domIds | dom列表 | 否 | number[] |
+
+**响应 data**：含 id(number)。
+
+---
+
+## ERP-访问规则编辑
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/edit`
+
+> addIds/addNames 可任传其一取并集；deleteIds/deleteNames 不能与 add 重复。
+
+参数结构与「规则新建」基本一致，差异：
+- 新增 `ruleId`(number, 必须) — 规则ID
+- `userChange` / `accountChange` 增加 `deleteIds`(string[]) 和 `deleteNames`(string[]) 用于删除成员
+- 无 `activeRange`、`isSkipRuleConflictCheck` 参数
+
+**响应**：ret / msg
+
+---
+
+## ERP-访问规则删除
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/delete`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ruleIds | 规则ID列表 | 是 | number[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-访问规则启用禁用
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/active`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ruleIds | 规则ID列表 | 是 | number[] |
+| isActive | 0禁用 1启用 | 是 | string |
+
+**响应**：ret / msg
+
+---
+
+## ERP-访问规则列表
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/list`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| search | 搜索关键字 | 否 | string |
+| activeRange | 1所有网站/2黑名单/3白名单 | 否 | number |
+| isActive | 0禁用 1启用 | 否 | number |
+| ruleListType | 0全部 1账号可绑定 | 否 | number |
+| accountId | 账号id（获取可绑定规则时传） | 否 | number |
+| page | 页码 | 是 | number |
+| limit | 每页条数 | 是 | number |
+
+**响应 data**：含 list 数组（每项含 id、name、activeUser、activeRange、isActive、description、users[]、roles[]、departments[]、accounts[]、presetType、canChangeUser/Account/Url/Active/canDelete/canCopy）和 count。
+
+---
+
+## ERP-访问规则详情
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/detail`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ruleId | 规则ID | 是 | number |
+
+**响应 data**：含 id、name、description、activeUser、activeRange、activeAccount、users[{id,name,username}]、roles[{id,name}]、departments[{id,name}]、accounts[{id,name}]、configs[{urlId,urlName,groupId,groupName,tType,isAccessible,isLog,urlPattern,functions[{function,permission}]}]、effectiveTime{timeType,startTime,endTime}、shareCompanys[{id,name}]、domList[]、domIds[]。
+
+---
+
+## ERP-访问规则设置生效成员
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/change_user`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ruleId | 规则ID | 是 | number |
+| activeUser | 1所有/2指定成员/3指定部门/4指定角色 | 是 | number |
+| userChange.addIds | 新增成员id（空传[]） | 是 | string[] |
+| userChange.addNames | 新增成员用户名 | 否 | string[] |
+| userChange.deleteIds | 删除成员id（空传[]） | 是 | string[] |
+| userChange.deleteNames | 删除成员用户名 | 否 | string[] |
+| userChange.departmentIds | 指定部门 | 是 | number[] |
+| userChange.roleIds | 指定角色 | 是 | number[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-访问规则设置生效账号
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/change_account`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ruleId | 规则ID | 是 | number |
+| activeAccount | 0所有 1指定 | 是 | number |
+| accountChange.addIds | 新增账号id | 是 | string[] |
+| accountChange.deleteIds | 删除账号id | 是 | string[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-规则可绑定的账号列表
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/account/bindable_list`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| page | 页码 | 是 | number |
+| limit | 每页条数 | 是 | number |
+| ruleId | 规则id | 否 | number |
+| platformIds | 平台id列表 | 否 | number[] |
+| tagIds | 标签id列表 | 否 | number[] |
+| accountName | 账号名称 | 否 | string |
+
+**响应 data**：含 list（每项含 id、name、collocationRelation、sitePlatformName、storePlatformId、tags[{id,name}]）、count(number)、bindAccountIds(number[])。
+
+---
+
+## ERP-账号添加访问策略
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/account_ref/add_to_account`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| accountId | 账号id | 是 | string |
+| ruleIds | 访问策略id列表 | 是 | number[] |
+| isSkipRuleConflictCheck | 是否跳过冲突检测 | 是 | boolean |
+
+**响应**：ret / msg
+
+---
+
+## ERP-账号移除访问策略
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/account_ref/remove_from_account`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| accountId | 账号id | 是 | string |
+| ruleIds | 访问策略id列表 | 是 | number[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-账号绑定的访问策略列表
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule/list/one_account`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| accountId | 账号id | 是 | string |
+| page | 页码 | 是 | number |
+| limit | 每页条数 | 是 | number |
+
+**响应 data**：含 list 数组（每项含 id、name、activeRange、activeUser、isActive、users[{id,name,username}]、urlCount、isInvalid、canDelete）和 count。
@@ -0,0 +1,152 @@
+# 访问策略 - 网页与分组管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅网页增删改查、网页分组管理接口的详细参数时加载。
+
+所有接口**权限点**均为 **ERP-网页访问权限**，方法均为 POST。
+
+---
+
+## ERP-添加网页
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/add`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| name | 网页名称 | 是 | string |
+| groupId | 分组ID | 是 | number |
+| desc | 描述 | 否 | string |
+| urlPattern | URL | 是 | string |
+
+**响应 data**：含 id(number)。
+
+---
+
+## ERP-编辑网页
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/edit`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| urlId | 网页ID | 是 | number |
+| name | 网页名称 | 是 | string |
+| groupId | 分组ID | 是 | number |
+| desc | 描述 | 否 | string |
+| urlPattern | URL | 是 | string |
+
+**响应**：ret / msg
+
+---
+
+## ERP-删除网页
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/delete`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| urlIds | 网页ID列表 | 是 | number[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-网页列表
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/list`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| search | 搜索关键字 | 否 | string |
+| groupIds | 筛选分组ID | 否 | number[] |
+| tType | 1系统预置 2自定义 | 否 | number |
+| page | 页码 | 是 | number |
+| limit | 每页条数 | 是 | number |
+
+**响应 data**：含 list 数组（每项含 id、name、groupId、groupName、tType、urlPattern、description）和 count(number)。
+
+---
+
+## ERP-网页详情
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/detail`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| urlId | 网页ID | 是 | number |
+| urlPattern | 网页url（按url查详情） | 否 | string |
+
+**响应 data**：含 id、name、groupId、groupName、tType、urlPattern、description。
+
+---
+
+## ERP-网页修改分组
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url/change_group`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| groupId | 目标分组ID | 是 | number |
+| urlIds | 网页ID列表 | 是 | number[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-添加网页分组
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url_group/add`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| name | 分组名称 | 是 | string |
+| groupIdParent | 父级分组ID（0为顶级，默认0） | 否 | number |
+
+**响应 data**：含 id(number)。
+
+---
+
+## ERP-编辑网页分组
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url_group/edit`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| groupId | 分组ID | 是 | number |
+| name | 分组名称 | 是 | string |
+
+**响应**：ret / msg
+
+---
+
+## ERP-删除网页分组
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url_group/delete`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| groupId | 分组ID | 是 | number |
+
+**响应**：ret / msg
+
+---
+
+## ERP-网页分组列表
+
+- **路径**：`/superbrowser/rest/v1/erp/security/access_rule_url_group/list`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| groupIdParent | 父级id（0为顶级，默认0） | 否 | number |
+| isAll | 是否返回全部数据（默认false） | 否 | boolean |
+
+**响应 data**：含 list 数组，每项含 id(number)、name(string)、tType(1系统/2自定义)、urlCount(number)、childrenCount(number)、groupIdParent(number)、children(array，isAll=true 时返回，结构同父节点)。
@@ -0,0 +1,76 @@
+# 账号授权管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅账号授权新增、删除、查询、清除、授权用户列表接口的详细参数时加载。
+
+---
+
+## ERP-账号授权新增
+
+- **路径**：`/superbrowser/rest/v1/erp/store/auth/add`　**方法**：POST　**权限点**：ERP-账号授权权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeIdList | 账号id列表 | 是 | string[] |
+| staffId | 授权用户id | 是 | string |
+| isAuthAddtion | 是否授权附加账号（默认授权）0否 1是 | 否 | number |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-账号授权删除
+
+- **路径**：`/superbrowser/rest/v1/erp/store/auth/delete`　**方法**：POST　**权限点**：ERP-账号授权权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeIdList | 账号id列表 | 是 | string[] |
+| staffId | 授权用户id | 是 | string |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-账号授权查询
+
+- **路径**：`/superbrowser/rest/v1/erp/store/auth/query`　**方法**：POST　**权限点**：ERP-账号查看权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| userId | 用户id | 是 | number |
+
+**响应 data**：数组，每项含 storeId(number)、storeName(string)。
+
+---
+
+## ERP-清除账号授权
+
+- **路径**：`/superbrowser/rest/v1/erp/store/auth/clean`　**方法**：POST　**权限点**：ERP-清除账号授权
+
+> 清除指定账号上的所有授权关系（不指定用户）。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeIdList | 账号id数组 | 是 | string[] |
+
+**响应**：ret / msg
+
+---
+
+## ERP-账号授权用户列表查询
+
+- **路径**：`/superbrowser/rest/v1/erp/store/user/list`　**方法**：POST　**权限点**：ERP-账号查看权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeIdList | 账号id列表 | 否 | string[] |
+| page | 页码 | 否 | string |
+| limit | 每页条数 | 否 | string |
+
+**响应 data**：数组，每项含 storeId(number)、userId(number)、username(string)。另有 count。
@@ -0,0 +1,134 @@
+# 账号增删改查与状态接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅账号创建、删除、编辑、列表查询、标签列表、缓存清除接口的详细参数时加载。
+
+---
+
+## ERP-创建账号
+
+- **路径**：`/superbrowser/rest/v1/erp/store/create`　**方法**：POST　**权限点**：ERP-创建与删除账号权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeData | 账号数据数组 | 是 | array |
+| storeData[].name | 账号名 | 是 | string |
+| storeData[].username | 平台登录账号 | 否 | string |
+| storeData[].password | 平台登录密码 | 否 | string |
+| storeData[].siteId | 站点id | 否 | string |
+| storeData[].tagIds | 标签列表（不超过5个） | 否 | number[] |
+| proxyId | 设备id | 否 | number |
+| enterpriseName | 企业简称 | 否 | string |
+| defyWarning | 是否无视风险添加：1是 0否（默认1） | 否 | string |
+
+**响应 data**：数组，每项含 storeId(string)、name(string)、siteId(string)、msg(string)、riskMsgList(string[])
+
+---
+
+## ERP-删除账号
+
+- **路径**：`/superbrowser/rest/v1/erp/store/delete`　**方法**：POST　**权限点**：ERP-创建与删除账号权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeIds | 账号id数组 | 是 | number[] |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-编辑账号基础信息
+
+- **路径**：`/superbrowser/rest/v1/erp/store/update/base`　**方法**：POST　**权限点**：ERP-编辑账号基础信息
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| id | 账号id | 是 | number |
+| name | 账号名（≤64位，不传不更新） | 否 | string |
+| siteId | 平台id（不传不更新） | 否 | number |
+| tagIds | 标签id列表（不传不更新，传空清空，≤5个） | 否 | number[] |
+| defyWarning | 是否无视风险：1是 0否（默认1） | 否 | integer |
+| customerUrl | 自定义平台站点url | 否 | string |
+
+**响应**：ret / msg / status
+
+---
+
+## ERP-账号列表查询
+
+- **路径**：`/superbrowser/rest/v1/erp/store/list`　**方法**：POST　**权限点**：ERP-账号查看权限
+
+> 私有化账号建议一次最多查询 20 条。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeName | 账号名称 | 否 | string |
+| ip | 设备ip | 否 | string |
+| page | 页码 | 否 | number |
+| limit | 每页条数 | 否 | number |
+
+**响应 data**：数组，每项含 id、name、ip、proxyId、siteId、siteName、platform、platformName、username、createtime、lastuserId、lastusetime、packageName (均 string)。另有 count。
+
+---
+
+## ERP-用户的账号列表查询
+
+- **路径**：`/superbrowser/rest/v1/erp/store/list/by/user`　**方法**：POST　**权限点**：ERP-账号查看权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| userId | 用户id | 是 | number |
+| storeName | 账号名称 | 否 | string |
+| page | 页码 | 否 | number |
+| limit | 每页条数 | 否 | number |
+
+**响应 data**：数组，每项含 storeId、storeName、proxyId、ipExpiryTime、platformName (均 string)。另有 count。
+
+---
+
+## ERP-查询某用户有权限的账号列表
+
+- **路径**：`/superbrowser/rest/v1/erp/user/stores`　**方法**：POST　**权限点**：ERP-查询某用户有权限的账号列表
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| userId | 用户id | 是 | number |
+| storeName | 账号名称 | 否 | string |
+| isAccurate | 0模糊 1精确（默认精确） | 否 | number |
+| page | 页码 | 否 | number |
+| limit | 每页条数 | 否 | number |
+
+**响应 data**：数组，每项含 id(number)、name、ipId(number)、ip、platform、platformCategory、userName、lastUserId、lastUserName、lastOpenUsername、lastUsetime、ipExpiryTime、tags(string[])、regionInfo。另有 count。
+
+---
+
+## ERP-标签列表
+
+- **路径**：`/superbrowser/rest/v1/erp/tag/list`　**方法**：POST　**权限点**：ERP-标签列表
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+
+**响应 data**：对象，含 list 数组，每项含 id(string)、name(string)。
+
+---
+
+## ERP-清除账号缓存
+
+- **路径**：`/superbrowser/rest/v1/erp/store/deletecookie`　**方法**：POST　**权限点**：ERP-清除账号缓存
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| userId | 用户id | 是 | string |
+| removeStoreId | 账号id | 是 | number |
+| removeType | 1清除所有 2仅保留cookie 3仅保留二步验证状态 | 是 | number |
+
+**响应**：ret / msg / status
@@ -0,0 +1,119 @@
+# 账号标签管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅标签的添加、删除、重命名、绑定、解绑、替换、移除、清空、列表接口时加载。
+
+所有标签接口**权限点**均为 **账号标签管理权限**。标签操作路径统一为 `/superbrowser/rest/v1/store-tag/{action}`，方法均为 POST。每个账号最多绑定 5 个标签。
+
+**操作模式**：绑定/解绑为增量操作；替换为全量覆盖；清空移除所有标签。
+
+---
+
+## 添加账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/add`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 否 | string |
+| userId | 用户id | 否 | string |
+| tagName | 标签名称 | 否 | string |
+
+**响应 data**：对象，含 tag_id(string)。
+
+---
+
+## 删除账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/delete`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 否 | string |
+| tagIds | 标签id列表 | 否 | string[] |
+| userId | 用户id | 否 | string |
+
+**响应**：ret / msg
+
+---
+
+## 重命名账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/rename`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 否 | string |
+| tid | 标签id | 否 | string |
+| userId | 用户id | 否 | string |
+| name | 新标签名称 | 否 | string |
+
+**响应**：ret / status / msg
+
+---
+
+## 绑定账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/bind`（增量追加）
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 否 | string |
+| storeIds | 账号id列表 | 否 | string[] |
+| tagIds | 标签id列表 | 否 | string[] |
+| userId | 用户id | 否 | string |
+
+**响应**：ret / msg
+
+---
+
+## 解绑账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/unbind`（增量移除）
+
+请求参数同「绑定账号标签」。**响应**：ret / status / msg
+
+---
+
+## 替换账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/replace`（全量覆盖）
+
+请求参数同「绑定账号标签」。**响应**：ret / msg / status
+
+---
+
+## 移除账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/remove`
+
+请求参数同「绑定账号标签」。**响应**：ret / msg / status
+
+---
+
+## 清空账号标签
+
+- **路径**：`/superbrowser/rest/v1/store-tag/clear`（移除账号所有标签）
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 否 | string |
+| storeIds | 账号id列表 | 否 | string[] |
+| userId | 用户id | 否 | string |
+
+**响应**：ret / msg
+
+---
+
+## 账号的标签列表
+
+- **路径**：`/superbrowser/rest/v1/store-tag/list`
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| storeId | 店铺id | 是 | string |
+| userId | 用户id | 是 | string |
+| withSystem | 1带系统标签 0不带（默认0） | 否 | string |
+
+**响应 data**：含 id(string)、name(string)、is_system(string)、store_count(string)。
@@ -0,0 +1,108 @@
+# API 调用指南
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要了解认证方式、请求构造方法、代码示例或常见错误时加载。
+
+## 概述
+
+紫鸟开放平台使用"简单通用模式"进行 API 认证，通过 API Key 作为 Bearer Token 传递。
+
+## 1. 获取 companyId（紫鸟企业ID）
+
+在开放平台首页右侧可获取紫鸟企业ID（即 companyId），几乎所有接口都需要传此参数。
+
+## 2. 获取 API Key
+
+前提：在紫鸟开放平台创建"卖家自研应用"，API 身份验证方式选择**简单通用模式**。在控制台中可以找到 API Key。
+
+## 3. 配置 IP 白名单
+
+在紫鸟开放平台的**应用管理**中，点击【设置】进入该应用的【应用概览】页面，点击【安全中心】下的【IP 白名单设置】，添加调用接口的服务器 IP。建议使用一台 IP 固定的服务器发起 API 请求。
+
+## 4. 构造请求头
+
+```
+Authorization: Bearer {你的API_Key}
+Content-Type: application/json
+```
+
+`Bearer` 和 API Key 之间必须有一个空格。
+
+## 5. 请求地址
+
+Base URL：`https://sbappstoreapi.ziniao.com/openapi-router`
+
+完整请求地址 = Base URL + 接口路径。例如：
+`https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list`
+
+## 6. 响应结构
+
+### 网关层（外层）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| request_id | string | 全局请求ID |
+| code | string | "0" 表示成功 |
+| msg | string | 返回码描述 |
+| sub_code | string | 业务返回码（成功时不返回） |
+| sub_msg | string | 业务返回码描述（成功时不返回） |
+| data | object | 业务响应参数 |
+
+### 业务层（data 内部）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| ret | number | 0 成功，其他失败 |
+| status | string | "success" 或 "faile" |
+| data | array/object | 业务数据（部分接口有） |
+| msg | string | 错误信息 |
+| count | number | 列表查询时的总条数 |
+| 其他字段 | - | 部分接口的业务字段直接在此层级 |
+
+> **关键提醒**：业务数据位置因接口而异，不要假设所有业务数据都在 `data` 字段中。各 reference 文件对每个接口标注了"响应 data"或"响应"——"响应 data"表示数据在业务层的 data 字段中；"响应"后直接列出的字段（如 id、password）表示它们与 ret/status 同级，直接位于业务层根级。
+
+## 7. 代码示例
+
+### Java（OkHttp）
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder().build();
+MediaType mediaType = MediaType.parse("application/json");
+RequestBody body = RequestBody.create(mediaType, "{\"companyId\": 123456}");
+Request request = new Request.Builder()
+  .url("https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list")
+  .method("POST", body)
+  .addHeader("Authorization", "Bearer 你的API_Key")
+  .addHeader("Content-Type", "application/json")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+### Python（requests）
+
+```python
+import requests, json
+url = "https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list"
+headers = {"Authorization": "Bearer 你的API_Key", "Content-Type": "application/json"}
+response = requests.post(url, headers=headers, data=json.dumps({"companyId": 123456}))
+print(response.json())
+```
+
+### JavaScript（Fetch）
+
+```javascript
+fetch("https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list", {
+  method: "POST",
+  headers: { "Authorization": "Bearer 你的API_Key", "Content-Type": "application/json" },
+  body: JSON.stringify({ companyId: 123456 }),
+})
+  .then(r => r.json()).then(console.log).catch(console.error);
+```
+
+## 8. 常见问题
+
+**401 错误**：检查 API Key 是否正确、Authorization 格式是否含空格、接口是否支持通用模式、应用是否已申请对应权限点。
+
+**code 非 "0"**：请求未到达业务层，通常是认证或权限问题。
+
+**ret 非 0**：业务操作失败，读取 msg 或 sub_msg 获取错误详情。
@@ -0,0 +1,172 @@
+# 部门员工管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅部门增删改查移动、员工新增/修改/查询/启禁用、部门变更接口时加载。
+
+所有接口方法均为 POST。
+
+---
+
+## ERP-部门查询
+
+- **路径**：`/superbrowser/rest/v1/erp/department/list`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+
+**响应 data**：数组，每项含 id(number)、name(string)、hierarchy(number 层级)、parentId(number)、ordering(number)。另有 count。
+
+---
+
+## ERP-部门新增
+
+- **路径**：`/superbrowser/rest/v1/erp/department/add`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| name | 部门名称 | 是 | string |
+| hierarchy | 部门级别 | 是 | string |
+| parentId | 父级部门id | 是 | string |
+
+**响应 data**：含 id(string 部门id)。
+
+---
+
+## ERP-部门修改
+
+- **路径**：`/superbrowser/rest/v1/erp/department/update`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| id | 部门id | 是 | number |
+| name | 部门新名称 | 否 | string |
+| parentId | 父部门id | 否 | number |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-部门删除
+
+- **路径**：`/superbrowser/rest/v1/erp/department/delete`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| id | 部门id | 是 | string |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-部门移动
+
+- **路径**：`/superbrowser/rest/v1/erp/department/order`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| parentId | 父部门id | 是 | string |
+| order | 更新后的部门顺序（部门id数组） | 是 | string[] |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-员工查询
+
+- **路径**：`/superbrowser/rest/v1/erp/staff/list`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| page | 页码 | 是 | number |
+| limit | 每页条数 | 是 | number |
+| username | 用户账号 | 否 | string |
+| name | 真实姓名 | 否 | string |
+| departmentIds | 部门id数组 | 否 | number[] |
+| level | 角色类型（0boss/1经理/2员工/3超管） | 否 | string |
+| delflag | 0正常 1禁用 2删除（不传全部） | 否 | string |
+| isAccurate | 0模糊 1精确（默认0） | 否 | number |
+
+**响应 data**：含 username、userId、name、level、mobile、delflag、authPhone (均 string)。另有 count。
+
+---
+
+## ERP-员工新增v2
+
+- **路径**：`/superbrowser/rest/v2/erp/staff/add`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| nickname | 用户账号 | 是 | string |
+| name | 真实姓名 | 是 | string |
+| password | 密码 | 是 | string |
+| mobile | 手机号 | 否 | string |
+| departmentIds | 部门id数组 | 是 | string[] |
+| roleId | 角色id | 是 | number |
+| authDevide | 设备授权方式（1/2/3/4） | 是 | number |
+| isUpdatePersonInfo | 1允许修改个人信息 0不允许 | 是 | number |
+| isLimitLogin | 0否 1是 | 是 | number |
+| isTwoStepVerify | 0否 1是 | 是 | number |
+| authClient | 登录终端控制对象 | 是 | object |
+| authClient.allowLoginWindows | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginMac | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginAndroid | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginWeb | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginIos | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginMiniprog | 1允许 0不允许 | 是 | string |
+| authClient.allowLoginLinux | 1允许 0不允许 | 否 | string |
+| loginLimitStartTime | HH:mm（分钟仅00或30） | 否 | string |
+| loginLimitEndTime | HH:mm | 否 | string |
+| loginLimitStartDate | yyyy-MM-dd | 否 | string |
+| loginLimitEndDate | yyyy-MM-dd | 否 | string |
+| enablePhoneLogin | 0否 1是 | 否 | number |
+
+**响应**：含 id(用户id)、password(string)。
+
+---
+
+## ERP-员工修改v2
+
+- **路径**：`/superbrowser/rest/v2/erp/staff/modify`　**权限点**：ERP-部门与员工接口
+
+参数结构与「员工新增v2」基本一致，差异：
+- 新增 `id`(string, 必须) — 用户id
+- 多数字段变为非必须（不传不更新）
+- 新增 `isResetAuthPhone`(number) — 1重置登录手机号 0不重置
+- `areaCode` 和 `authPhone` 已废弃
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-员工启用禁用接口
+
+- **路径**：`/superbrowser/rest/v1/erp/staff/status`　**权限点**：ERP-部门与员工接口
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| staffIds | 用户id数组 | 是 | string[] |
+| status | 0启用 1禁用 2删除 | 是 | string |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-用户的部门变更
+
+- **路径**：`/superbrowser/rest/v1/erp/staff/department`　**权限点**：ERP-用户的部门变更
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| staffIds | 用户id列表 | 是 | number[] |
+| departmentIds | 部门id列表 | 是 | number[] |
+
+**响应**：ret / msg / status
@@ -0,0 +1,180 @@
+# 设备管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅设备套餐、购买、续费、绑定、解绑、查询、自有设备管理接口时加载。
+
+所有接口方法均为 POST，Content-Type 为 application/json。
+
+---
+
+## ERP-套餐列表查询
+
+- **路径**：`/superbrowser/rest/v1/erp/package/new`　**权限点**：ERP-设备套餐列表查询权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+
+**响应 data**：数组，每项含 regionCloudId(套餐ID)、ctype(0站群/1云平台/2自有/3本地)、networkType、areaId、areaName、city、priceOriginal、deviceConfigName、deviceType(1标准/2节能/3高配)、deviceOs、deviceSupportRemoteLogin、deviceCpuSize、deviceMemorySize、deviceBandWidth、deviceDiskSize、platformName (均 string)。
+
+---
+
+## ERP-购买设备
+
+- **路径**：`/superbrowser/rest/v1/erp/purchase`　**权限点**：ERP-设备购买与续费权限
+
+> 需要紫鸟账号上有余额。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| purchase | 购买信息对象 | 是 | object |
+| purchase.packageId | 套餐id | 是 | number |
+| purchase.periodId | 时长id（1:1月/2:3月/3:6月/4:12月） | 是 | number |
+| purchase.num | 数量（单次最多5个） | 是 | number |
+| storeIds | 要绑定的账号id（未绑设备的） | 否 | number[] |
+
+**响应 data**：含 order_id(string)、create_time(string)、proxyIdList(number[] 设备ID列表)。
+
+---
+
+## ERP-续费设备
+
+- **路径**：`/superbrowser/rest/v1/erp/renew`　**权限点**：ERP-设备购买与续费权限
+
+> 仅支持紫鸟 IP 续费；自有设备请通过开启自动续费。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | string |
+| renew | 续费信息对象 | 是 | object |
+| renew.periodId | 时长id | 是 | string |
+| renew.ipIds | proxy_id 数组 | 是 | integer[] |
+
+**响应 data**：含 id(设备id)、ip(设备ip)、expire(过期时间)。另有 orderId、createTime。
+
+---
+
+## ERP-开关自动续费
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/renewal`　**权限点**：ERP-开关自动续费
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ids | proxy_id 数组 | 是 | number[] |
+| isOpen | 0关闭 1开启 | 是 | number |
+
+**响应**：ret / msg / status
+
+---
+
+## ERP-设备查询
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/page`　**权限点**：ERP-设备查询
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| ipAddr | 设备地址 | 否 | string |
+| page | 页码 | 否 | string |
+| limit | 每页条数 | 否 | string |
+
+**响应 data**：数组，每项含 id(number)、ip、proxyName、proxyType(0站群/1云平台/2自有/3vps/4虚拟机/5本地)、port、ptype(0http/1https/2socks5)、expiry、isRenewal(0关/1开)、createtime、delflag(0正常/2回收站) (均 string)。另有 count。
+
+---
+
+## ERP-绑定设备
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/bind`　**权限点**：ERP-设备绑定权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| proxyId | 设备id | 是 | number |
+| storeIdList | 账号id列表 | 是 | number[] |
+| defyWarning | 是否无视风险：1是 0否（默认1） | 否 | number |
+
+**响应**：ret / status / msg / riskMsgList(string[])
+
+---
+
+## ERP-解绑设备
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/unbind`　**权限点**：ERP-解绑设备
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| storeId | 账号ID | 是 | number |
+
+**响应**：ret / msg / status
+
+---
+
+## ERP-查询已购设备价格接口
+
+- **路径**：`/superbrowser/rest/v1/erp/proxy/purchased_package_info`　**权限点**：ERP-查询已购设备价格接口
+
+> 仅支持查询云平台设备。
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司ID | 是 | number |
+| proxyId | 设备ID | 是 | number |
+
+**响应 data**：含 proxyId(number)、regionCloudId(number 套餐ID)、price(number 续费价格)。
+
+---
+
+## ERP-设备历史绑定记录
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/historybind`　**权限点**：ERP-设备查询
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| proxyId | 设备id | 是 | number |
+
+**响应 data**：对象含 list 数组，每项含 storeId、storeName、proxyName、unBindTime、unbindUserId、unbindUsername、cloudType (均 string)。另有 count。
+
+---
+
+## ERP-添加自有设备（新）
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/self/add/new`　**权限点**：ERP-添加自有设备（新）
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司ID | 是 | string |
+| defyWarning | 1无视风险 0风险提示 | 是 | number |
+| base | 基础信息对象 | 是 | object |
+| base.deviceName | 设备名称 | 是 | string |
+| base.isDynamic | 是否动态网络（false静态/true动态） | 是 | boolean |
+| proxy | 代理信息对象 | 是 | object |
+| proxy.type | 0http/1https/2sock5/3ssh/4ssl | 是 | string |
+| proxy.addr | 代理地址 | 是 | string |
+| proxy.port | 代理端口 | 是 | string |
+| proxy.username | 用户名 | 否 | string |
+| proxy.passwd | 密码 | 否 | string |
+| proxy.isSetAccount | 是否设密码 0否 1是 | 是 | number |
+
+**响应 data**：含 id(number 设备ID)。
+
+---
+
+## ERP-修改自有设备信息（新）
+
+- **路径**：`/superbrowser/rest/v1/erp/ip/self/edit/new`　**权限点**：ERP-修改自有设备信息（新）
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司ID | 是 | string |
+| defyWarning | 1无视风险 0风险提示 | 是 | number |
+| proxyId | 设备ID | 是 | string |
+| base | 基础信息对象 | 是 | object |
+| base.deviceName | 设备名称（不传不更新） | 否 | string |
+| base.isDynamic | 是否动态网络 | 是 | boolean |
+| proxy | 代理信息对象（字段同添加接口） | 是 | object |
+
+**响应**：ret / status / msg
@@ -0,0 +1,107 @@
+# 角色和权限管理接口
+
+> 本文件是 ziniao-erp-api-doc 的 Level 2 参考文档。
+> 仅在需要查阅角色增改查、权限列表、用户角色调整接口的详细参数时加载。
+
+所有接口方法均为 POST。
+
+---
+
+## ERP-添加角色
+
+- **路径**：`/superbrowser/rest/v1/erp/per/role/add`　**权限点**：ERP-角色添加、修改权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| roleName | 角色名称 | 是 | string |
+| identityId | 角色身份id（1管理员/2普通成员/3超级管理员） | 是 | number |
+| desc | 描述 | 否 | string |
+| permissionIds | 权限id列表 | 是 | number[] |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-修改角色
+
+- **路径**：`/superbrowser/rest/v1/erp/per/role/edit`　**权限点**：ERP-角色添加、修改权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| roleId | 角色id | 是 | string |
+| roleName | 角色名称 | 是 | string |
+| identityId | 角色身份id | 是 | number |
+| desc | 描述 | 否 | string |
+| permissionIds | 权限id列表 | 是 | number[] |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-角色列表查询
+
+- **路径**：`/superbrowser/rest/v1/erp/per/role/list`　**权限点**：ERP-角色列表查询
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| page | 页码 | 否 | number |
+| limit | 每页条数 | 否 | number |
+| filterKeyword | 搜索关键字 | 否 | string |
+
+**响应 data**：含角色信息 id、name、desc、identityType(1管理/2员工/3超管)、allPermission、users[{userId,name,username}]、permissions[{id,name,groupId,groupName,dependOn[],requiredBy[]}]。另有 count。
+
+---
+
+## ERP-角色详情
+
+- **路径**：`/superbrowser/rest/v1/erp/per/role/detail`　**权限点**：ERP-角色详情
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| roleId | 角色id | 是 | number |
+
+**响应 data**：含 id、companyId、name、desc、permissionList[{id,name,groupId,groupName}] (均 string)。
+
+---
+
+## ERP-权限列表
+
+- **路径**：`/superbrowser/rest/v1/erp/per/permission/list`　**权限点**：ERP-权限列表
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| identityId | 角色身份id（1管理员/2普通成员/3超级管理员） | 是 | number |
+
+**响应 data**：数组，每项含 id(number)、name(string)、desc(string)、order(number)、groupId(number)、groupName(string)、groupOrder(number)、dependOn(number[])、requiredBy(number[])。
+
+---
+
+## ERP-调整角色
+
+- **路径**：`/superbrowser/rest/v1/erp/staff/change/role`　**权限点**：ERP-角色添加、修改权限
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| roleId | 角色id | 是 | number |
+| staffIds | 用户id列表 | 是 | number[] |
+
+**响应**：ret / status / msg
+
+---
+
+## ERP-用户角色列表
+
+- **路径**：`/superbrowser/rest/v1/erp/staff/role/list`　**权限点**：ERP-角色列表查询
+
+| 参数 | 说明 | 必须 | 类型 |
+|------|------|------|------|
+| companyId | 公司id | 是 | number |
+| staffId | 用户id | 是 | number |
+
+**响应 data**：对象含 roleList 数组，每项含 id(string)、name(string)。
@@ -0,0 +1,127 @@
+---
+name: ziniao-sso-doc
+description: >
+  Use when 需要理解紫鸟单点登录 OpenAPI 的定位、能力、集成流程或接口清单，
+  用于 ERP 系统 SSO 对接规划、集成设计或接口评估。
+  不要用于直接查阅具体接口参数——查阅时读取 reference/ 下对应文件。
+---
+
+# ziniao-sso-doc（紫鸟单点登录 API 文档）
+
+## 何时使用 / 不使用
+
+| 场景 | 做法 |
+|------|------|
+| 需要了解紫鸟单点登录能做什么 | 读本 Skill |
+| 需要做 ERP SSO 对接的集成设计 | 读本 Skill |
+| 需要查阅某个接口的请求/响应参数 | 读本 Skill §按需深入 获取路径，再读 reference/ 文件 |
+| 需要 Schema URL 协议详细参数 | 读 `reference/client-schema.md` |
+
+---
+
+## Level 0：定位与边界
+
+### 是什么
+
+紫鸟单点登录 OpenAPI，面向 ERP/第三方系统，通过服务端 API 获取认证令牌，结合 `superbrowser://` Schema URL 协议拉起紫鸟浏览器并自动登录指定账号，实现免密单点登录。支持两种鉴权模式：简单鉴权（直接用 API Key，无需调用 get_app_token）和复杂鉴权（需额外获取 appAuthToken）。
+
+### 能力概览
+
+| 能力域 | 说明 |
+|--------|------|
+| 应用认证 | 获取应用级 Token（appAuthToken）——仅复杂鉴权模式需要，简单鉴权模式直接用 API Key |
+| 企业信息 | 获取自建应用关联的公司 ID（companyId） |
+
+| 员工查询 | 分页查询公司员工列表，支持按角色/状态/部门筛选 |
+| 账号查询 | 查询公司全部账号或指定用户有权限的账号列表 |
+| 用户登录 | 获取指定用户的登录 Token（openapiToken），用于 SSO 鉴权 |
+| 客户端控制 | 通过 Schema URL 打开/关闭账号、退出浏览器（仅 Windows） |
+
+### 不做什么（边界）
+
+- 不包含账号 CRUD（创建/删除/编辑）——见 ziniao-erp-api-doc
+- 不包含标签、授权、设备管理接口——见 ziniao-erp-api-doc
+- 不提供浏览器自动化（RPA/脚本注入）能力
+- Schema URL 仅支持 Windows 客户端
+
+---
+
+## Level 1：架构与流程
+
+### 核心概念
+
+**两种鉴权模式**：**简单鉴权模式**——直接用 API Key 放入 `Authorization: Bearer {API_Key}` 请求头，无需调用 `get_app_token`；**复杂鉴权模式**——需先调用 `get_app_token` 获取 appAuthToken 再进行后续调用。大多数场景使用简单鉴权即可。
+
+**用户登录 Token**：openapiToken，通过 `user-login` 接口获取，有过期时长，用于 Schema URL 拉起浏览器时的用户身份鉴权。
+
+**Schema URL 协议**：以 `superbrowser://` 为前缀的自定义 URL 协议，支持三个 Action：OpenStrore（打开账号）、CloseStrore（关闭账号）、exit（退出浏览器）。可通过浏览器链接或命令行 `SuperBrowser.exe "url"` 调用。
+
+**双层响应结构**：网关层（request_id / code / msg）+ 业务层（ret / status / data / msg）。网关 code="0" 表示请求到达业务层；业务 ret=0 表示操作成功。
+
+### SSO 集成全流程
+
+```mermaid
+graph LR
+  A[创建应用<br/>获取 API Key] --> B[获取 companyId]
+  B --> C[查询员工列表]
+  C --> D[查询用户有权限的账号]
+  D --> E[获取用户 openapiToken]
+  E --> F[Schema URL<br/>打开账号]
+```
+
+1. 在开放平台创建自建应用，获取 API Key（简单鉴权模式）
+2. 调用 `builtin/company` 获取 companyId（固定值，获取一次即可）
+3. 调用 `staff/list` 查询员工，获取 userId
+4. 调用 `user/stores` 查询该用户有权限的账号，获取 storeId
+5. 调用 `user-login` 获取用户的 openapiToken（需提前申请接口权限）
+6. 拼接 Schema URL：`superbrowser://OpenStrore?storeId={storeId}&openapiToken={token}&userId={userId}`
+
+> 如使用复杂鉴权模式，需在步骤 1 之后额外调用 `get_app_token` 获取 appAuthToken。
+
+### 接口摘要表
+
+| 分组 | 接口名称 | 路径 | 方法 |
+|------|---------|------|------|
+| 认证 | 获取应用 token（仅复杂鉴权模式） | /auth/get_app_token | POST |
+| 企业 | 获取公司信息 | /app/builtin/company | GET |
+| 员工 | ERP-员工查询 | /superbrowser/rest/v1/erp/staff/list | POST |
+| 账号 | ERP-账号列表查询 | /superbrowser/rest/v1/erp/store/list | POST |
+| 账号 | ERP-查询用户有权限的账号 | /superbrowser/rest/v1/erp/user/stores | POST |
+| 登录 | 获取用户登录 token | /superbrowser/rest/v1/token/user-login | POST |
+
+### 公共响应结构
+
+> **所有接口返回双层嵌套结构，解析时必须先剥离网关层再读业务层。**
+> **异常处理：请求异常时，必须将 request_id、msg 和 sub_msg 都打印出来，便于追踪定位。**
+
+```json
+{
+  "request_id": "全局请求追踪ID",
+  "code": "0",        // ← 网关层：code="0" 表示请求到达业务层
+  "msg": "SUCCESS",
+  "sub_code": "",      // ← 业务返回码，成功时不返回
+  "sub_msg": "",       // ← 业务返回码描述，成功时不返回
+  "data": { ... }     // ← 业务层：各接口文档中的响应参数均在此内部
+}
+```
+
+### 环境约定
+
+- Base URL：`https://sbappstoreapi.ziniao.com/openapi-router`
+- 请求编码：UTF-8，Content-Type：application/json
+- 前提：在开放平台创建"卖家自研应用"，获取 API Key，申请所需权限点，配置 IP 白名单
+- `user-login` 接口需联系紫鸟客服申请权限（需 Boss 验证）
+
+---
+
+## 按需深入（Level 2 路由表）
+
+> **规则：以下内容不要主动加载。**
+> 仅在你明确需要了解某个细节时，按路由表读取对应的 reference/ 文件。
+
+| 你需要了解 | 读取文件 |
+|-----------|---------|
+| 认证接口详细参数（get_app_token + user-login） | `reference/account-auth.md` |
+| 企业信息、员工查询、账号查询接口的详细参数 | `reference/account-crud.md` |
+| Schema URL 协议详细参数（OpenStrore / CloseStrore / exit） | `reference/client-schema.md` |
+| API 使用指南（基地址、公共 Headers、公共响应、curl 示例） | `reference/api-guide.md` |
@@ -0,0 +1,129 @@
+# 认证鉴权接口
+
+> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
+> 仅在需要查阅 get_app_token 或 user-login 接口的详细参数时加载。
+>
+> **响应说明**：以下各接口的"响应参数"均为业务层字段，实际位于网关响应的 `data` 内部。完整响应结构见 `api-guide.md` 公共响应参数。
+
+## 获取应用 Token
+
+> 仅在"复杂鉴权模式"下需要调用此接口。如使用"简单鉴权模式"（直接用 API Key），无需调用此接口，跳过本节即可。
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/auth/get_app_token` |
+| 方法 | POST |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+无需请求体参数。
+
+### 响应参数
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| appAuthToken | 应用授权令牌 | string |
+| expiresIn | 令牌有效期（秒），-1 表示永久有效 | string |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/auth/get_app_token' \
+--header 'Authorization: Bearer {API_Key}' \
+--header 'Content-Type: application/json' \
+--data-raw ''
+```
+
+### 响应示例
+
+```json
+{
+  "appAuthToken": "xxxxxxxxxxxxxxxx",
+  "expiresIn": "-1"
+}
+```
+
+---
+
+## 获取指定用户登录 Token
+
+> 需联系紫鸟在线客服申请接口权限（走特殊申请 OA 单，Boss 验证后生效）。
+> 目前仅支持 Windows 版客户端。
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/superbrowser/rest/v1/token/user-login` |
+| 方法 | POST |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
+|----------|----------|----------|----------|
+| companyId | 公司 ID | false | number |
+| userId | 用户 ID | false | number |
+
+### 响应参数
+
+> 注意：此接口业务层使用 `code`/`msg` 结构，与其他接口的 `ret`/`status`/`msg`/`count` 结构不同，判断成功应检查 `code == 0` 而非 `ret == 0`。
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| code | 0 表示成功 | number |
+| msg | 状态描述（成功时为 "SUCCESS"） | string |
+| data | 响应数据对象 | object |
+| data.token | 用户登录 token（即 openapiToken） | string |
+| data.expireTime | 过期时长（秒） | number |
+| data.timeUnit | 时间单位（SECONDS） | string |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/token/user-login' \
+--header 'Authorization: Bearer {API_Key}' \
+--header 'Content-Type: application/json' \
+--data-raw '{"companyId":"15393571083459","userId":"15393571087094"}'
+```
+
+### 响应示例
+
+```json
+{
+  "code": 0,
+  "msg": "SUCCESS",
+  "data": {
+    "token": "79db5b0c8d16d5d7eecded06101a7e39",
+    "expireTime": 1800,
+    "timeUnit": "SECONDS"
+  }
+}
+```
+
+### 使用说明
+
+获取到的 token 即为 Schema URL 中的 `openapiToken` 参数，拼接格式为：
+
+```
+superbrowser://OpenStrore?storeId={账号ID}&openapiToken={token}&userId={用户ID}
+```
+
+如果本地已登录紫鸟客户端，且 userId 与本地登录用户一致，可不传 openapiToken（客户端版本 v5.290 或 v6.25 以上）。
@@ -0,0 +1,256 @@
+# 企业信息与员工/账号查询接口
+
+> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
+> 仅在需要查阅企业信息、员工查询或账号查询接口的详细参数时加载。
+
+> **响应说明**：以下各接口的"响应参数"均为业务层字段，实际位于网关响应的 `data` 内部。完整响应结构见 `api-guide.md` 公共响应参数。
+
+## 获取当前自建应用的公司信息
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/app/builtin/company` |
+| 方法 | GET |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+无。
+
+### 响应参数
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| companyId | 企业 ID（固定值，获取一次后复用） | integer |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/app/builtin/company' \
+--header 'Authorization: Bearer {API_Key}'
+```
+
+### 响应示例
+
+```json
+{
+  "companyId": 15393571083459
+}
+```
+
+> companyId 为固定值，也可在开放平台首页右侧直接获取。
+
+---
+
+## ERP-员工查询
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/superbrowser/rest/v1/erp/staff/list` |
+| 方法 | POST |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
+|----------|----------|----------|----------|
+| companyId | 公司 ID | true | number |
+| page | 页码 | true | number |
+| limit | 每页条数 | true | number |
+| username | 用户账号 | false | string |
+| name | 用户真实姓名 | false | string |
+| departmentIds | 部门 ID 数组 | false | array\<number\> |
+| level | 角色类型：0=Boss，1=经理，2=员工，3=超级管理员 | false | string |
+| delflag | 删除标志：0=正常，1=禁用，2=删除（不传返回全部） | false | string |
+| isAccurate | 查询模式：0=模糊查询，1=精确查询（默认 0） | false | number |
+
+### 响应参数
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| ret | 状态码，0=成功 | number |
+| status | success / faile | string |
+| data | 员工列表 | array |
+| data[].username | 用户名 | string |
+| data[].userId | 用户 ID | number |
+| data[].name | 联系人姓名 | string |
+| data[].level | 角色类型：0=Boss，1=经理，2=员工，3=超级管理员 | string |
+| data[].mobile | 手机号 | string |
+| data[].delflag | 状态：0=正常，1=禁用，2=删除 | string |
+| data[].authPhone | 登录手机号 | string |
+| msg | 错误信息 | string |
+| count | 总条数 | string |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/staff/list' \
+--header 'Authorization: Bearer {API_Key}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "companyId": "15393571083459",
+  "page": "1",
+  "limit": "10",
+  "level": "",
+  "isAccurate": "",
+  "departmentIds": [],
+  "delflag": "",
+  "name": "",
+  "username": ""
+}'
+```
+
+---
+
+## ERP-账号列表查询
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/superbrowser/rest/v1/erp/store/list` |
+| 方法 | POST |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
+|----------|----------|----------|----------|
+| companyId | 公司 ID | true | number |
+| storeName | 账号名称 | false | string |
+| ip | 设备 IP | false | string |
+| page | 页码 | false | number |
+| limit | 每页条数（私有化账号建议传 20） | false | number |
+
+### 响应参数
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| ret | 状态码，0=成功 | number |
+| status | success / faile | string |
+| data | 账号列表 | array |
+| data[].id | 账号 ID（即 storeId） | number |
+| data[].ip | 设备 IP | string |
+| data[].lastuserId | 最后登录用户 ID | number |
+| data[].lastusetime | 最后登录时间 | string |
+| data[].name | 账号名 | string |
+| data[].platform | 账号所属平台（如"美国亚马逊"） | string |
+| data[].proxyId | 设备 ID | string |
+| data[].siteId | 平台 ID | string |
+| data[].username | 平台登录账号 | string |
+| data[].createtime | 账号创建时间 | string |
+| data[].siteName | 站点名称 | string |
+| data[].packageName | 套餐名称 | string |
+| data[].platformName | 平台名称 | string |
+| msg | 错误信息 | string |
+| count | 总条数 | string |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/store/list' \
+--header 'Authorization: Bearer {API_Key}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "companyId": "15393571083459",
+  "storeName": "",
+  "ip": "",
+  "page": "1",
+  "limit": "10"
+}'
+```
+
+---
+
+## ERP-查询某用户有权限的账号列表
+
+### 基本信息
+
+| 项目 | 值 |
+|------|------|
+| 路径 | `/superbrowser/rest/v1/erp/user/stores` |
+| 方法 | POST |
+| Content-Type | application/json |
+
+### 请求 Headers
+
+| 参数名称 | 参数值 | 是否必须 |
+|----------|--------|----------|
+| Content-Type | application/json | true |
+| Authorization | Bearer {API_Key} | true |
+
+### 请求 Body
+
+| 参数名称 | 参数说明 | 是否必须 | 数据类型 |
+|----------|----------|----------|----------|
+| companyId | 公司 ID | true | number |
+| userId | 用户 ID | true | number |
+| storeName | 账号名称 | false | string |
+| isAccurate | 查询模式：0=模糊，1=精确（默认精确） | false | number |
+| page | 页码 | false | number |
+| limit | 每页条数 | false | number |
+
+### 响应参数
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| ret | 状态码，0=成功 | number |
+| status | success / faile | string |
+| data | 账号列表 | array |
+| data[].id | 账号 ID（即 storeId） | number |
+| data[].ipId | 设备 ID | number |
+| data[].ip | 设备 IP | string |
+| data[].platform | 账号所属平台 | string |
+| data[].name | 账号名 | string |
+| data[].lastUserId | 最后登录用户 ID | string |
+| data[].lastUserName | 最后登录用户姓名 | string |
+| data[].lastOpenUsername | 最后登录用户名称 | string |
+| data[].lastUsetime | 最后登录时间 | string |
+| data[].ipExpiryTime | 设备到期时间 | string |
+| data[].tags | 账号标签列表 | array\<string\> |
+| data[].regionInfo | 套餐信息 | string |
+| data[].platformCategory | 平台类目 | string |
+| data[].userName | 登录凭证 | string |
+| msg | 错误信息 | string |
+| count | 总条数 | number |
+
+### 请求示例
+
+```bash
+curl --location 'https://sbappstoreapi.ziniao.com/openapi-router/superbrowser/rest/v1/erp/user/stores' \
+--header 'Authorization: Bearer {API_Key}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "companyId": "15393571083459",
+  "userId": "15393571087094",
+  "storeName": "",
+  "isAccurate": "",
+  "page": "1",
+  "limit": "10"
+}'
+```
@@ -0,0 +1,84 @@
+# API 使用指南
+
+> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
+> 仅在需要了解 API 基地址、公共 Headers、公共响应结构或 curl 调用示例时加载。
+
+## Base URL
+
+```
+https://sbappstoreapi.ziniao.com/openapi-router
+```
+
+所有服务端接口路径均以此为前缀拼接。
+
+## 公共请求 Headers
+
+| Header | 值 | 说明 |
+|--------|------|------|
+| Content-Type | application/json | 所有接口统一使用 JSON 格式 |
+| Authorization | Bearer {API_Key} | API Key 从开放平台自建应用获取 |
+
+## 认证方式
+
+支持两种鉴权模式：
+
+### 简单鉴权模式（推荐）
+
+1. 在紫鸟开放平台创建"卖家自研应用"
+2. API 身份验证选择"简单通用模式"
+3. 获取 API Key
+4. 每次请求在 Header 中携带 `Authorization: Bearer {API_Key}`
+
+无需调用 `get_app_token` 接口，直接用 API Key 即可调用所有业务接口。
+
+### 复杂鉴权模式
+
+1. 创建应用后获取 API Key
+2. 调用 `/auth/get_app_token` 获取 appAuthToken
+3. 后续请求使用 appAuthToken 进行身份验证
+
+## 公共响应参数
+
+所有接口的网关层返回以下统一结构：
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| request_id | 全局请求 ID，用于追踪定位 | string |
+| code | 网关返回码，`"0"` 表示成功 | string |
+| msg | 网关返回码描述 | string |
+| sub_code | 业务返回码，成功时不返回 | string |
+| sub_msg | 业务返回码描述，成功时不返回 | string |
+| data | 业务响应参数 | object |
+
+### 业务层响应（data 内部）
+
+部分接口（员工查询、账号查询等）的 data 内部有二级结构：
+
+| 参数名称 | 参数说明 | 类型 |
+|----------|----------|------|
+| ret | 状态码，0=成功，其他=失败 | number |
+| status | `"success"` 或 `"faile"` | string |
+| data | 业务数据（数组或对象） | array/object |
+| msg | 错误信息 | string |
+| count | 总条数 | string/number |
+
+### 响应判断逻辑
+
+```
+1. 检查网关层 code 是否为 "0"
+   ├── 否 → 打印 request_id、msg、sub_msg，检查 API Key 和权限配置
+   └── 是 → 检查业务层是否成功
+            ├── 否 → 打印响应获取错误原因
+            └── 是 → 解析 data 获取业务数据
+```
+
+> **异常处理要求**：请求异常（包括状态码异常）时，必须将 `request_id`、`msg` 和 `sub_msg` 都打印出来，便于追踪定位问题。
+
+## 前置准备
+
+1. 在紫鸟开放平台注册并创建"卖家自研应用"
+2. 选择鉴权模式（简单鉴权或复杂鉴权）
+3. 获取 API Key
+4. 申请所需权限点（如需使用 `user-login` 接口，需联系紫鸟在线客服走特殊申请 OA 单，Boss 验证后生效）
+5. 配置 IP 白名单
+6. 获取 companyId（调用 `/app/builtin/company` 或在开放平台首页右侧查看）
@@ -0,0 +1,88 @@
+# 客户端 Schema URL 协议
+
+> 本文件是 ziniao-sso-doc 的 Level 2 参考文档。
+> 仅在需要查阅 superbrowser:// Schema URL 的详细参数与用法时加载。
+
+## 概述
+
+通过 `superbrowser://` 自定义 URL 协议控制紫鸟浏览器，支持打开/关闭账号和退出程序。
+调用方式有两种：
+
+1. **浏览器链接**：在浏览器地址栏打开 `superbrowser://...`（需通过安装程序安装紫鸟）
+2. **命令行**：`SuperBrowser.exe "superbrowser://..."` （需主程序路径正确）
+
+---
+
+## Action: OpenStrore（打开账号）
+
+### 完整示例
+
+```
+superbrowser://OpenStrore?storeId=xxxxxxx&openapiToken=xxxxxxxxx&userId=xxxxxxx&lanuchUrl=aHR0cHM6Ly93d3cuYmFpZHUuY29t&autoopen=true&debuggPort=60001&notPromptForDownload=1&forceDownloadPath=Rjpc5a6J6KOF5YyF --disable-gpu start-maximized
+```
+
+### 必须参数
+
+| 参数 | 说明 |
+|------|------|
+| storeId | 账号 ID |
+| userId | 紫鸟的用户 ID（如果发生变化需要重新登录） |
+| openapiToken | 鉴权 token（通过 `user-login` 接口获取） |
+
+> 如果本地已登录紫鸟客户端，且 userId 与本地登录用户一致，openapiToken 可不传（客户端版本 v5.290 或 v6.25 以上）。
+
+### 可选参数
+
+| 参数 | 说明 |
+|------|------|
+| lanuchUrl | 将要打开的目标地址，需 Base64 编码（如 `https://www.baidu.com` → `aHR0cHM6Ly93d3cuYmFpZHUuY29t`） |
+| autoopen | 设为 `true` 时自动打开 lanuchUrl 配置的地址 |
+| debuggPort | 指定 debug 端口号 |
+| notPromptForDownload | `1`=下载文件不弹出选择路径提示框，直接下载；`0` 或不传则弹出选择路径提示框 |
+| forceDownloadPath | 设置默认下载路径，路径需 Base64 编码 |
+
+### 命令行参数
+
+命令参数添加在链接后面，用空格隔开，多个参数也用空格隔开。
+
+> 添加的命令参数需要向管理员申请使用权限，否则不生效。
+
+### 响应结果
+
+启动紫鸟浏览器并打开对应账号。
+
+---
+
+## Action: exit（退出浏览器）
+
+### 请求格式
+
+```
+superbrowser://exit
+```
+
+### 说明
+
+退出紫鸟浏览器程序，关闭所有账号。
+
+> 如果上次打开的程序未完全退出，下次调用打开账号将会发生异常。建议在重新打开前先调用 exit。
+
+---
+
+## Action: CloseStrore（关闭账号）
+
+### 请求格式
+
+```
+superbrowser://CloseStrore?storeId=268682156400
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| storeId | 要关闭的账号 ID |
+
+### 说明
+
+关闭指定账号，每次只能关闭 1 个账号。如需关闭多个，需多次调用。
@@ -0,0 +1,163 @@
+---
+name: ziniao-webdriver-doc
+description: >
+  Use when 需要理解紫鸟浏览器 WebDriver 自动化接口的定位、能力、架构或对接流程，
+  用于设计讨论、集成规划或工具评估。
+  不要用于执行具体自动化脚本编写——执行时直接参考 reference/ 中的接口与示例。
+---
+
+# ziniao-webdriver-doc（紫鸟 WebDriver 文档）
+
+## 何时使用 / 不使用
+
+| 场景 | 做法 |
+|------|------|
+| 需要理解紫鸟 WebDriver 是什么、能做什么 | 读本 Skill |
+| 需要做自动化集成/框架选型的设计决策 | 读本 Skill |
+| 需要查阅某个接口的请求/响应格式 | 读本 Skill 的 §按需深入 获取路径，再读对应 reference/ 文件 |
+| 需要查看各语言/框架示例代码 | 不读本 Skill → 直接读 `reference/framework-examples.md` |
+
+---
+
+## Level 0：定位与边界
+
+### 是什么
+
+紫鸟浏览器 WebDriver 是紫鸟浏览器提供的本地自动化控制接口。通过命令行参数启动紫鸟浏览器进入 WebDriver 模式后，浏览器在本地开启 HTTP 服务，开发者可通过 JSON API 管理店铺窗口，并使用 Selenium / Puppeteer / Playwright / DrissionPage 等框架对接调试端口，实现对店铺浏览器的自动化控制。
+
+### 能力概览
+
+| 能力域 | 说明 |
+|--------|------|
+| 客户端启动控制 | 命令行参数启动/退出紫鸟浏览器进入 WebDriver 模式 |
+| 认证与登录 | 通过 API 完成设备授权、账号登录、获取店铺列表 |
+| 店铺窗口管理 | 启动/关闭指定店铺窗口，获取调试端口(debuggingPort) |
+| 自动化框架对接 | 返回调试端口供 Selenium/Puppeteer/Playwright/DrissionPage 连接 |
+| 内核管理 | 检测/下载/更新浏览器内核 |
+| 缓存与会话 | 清理本地/在线缓存、管理 Cookie 策略 |
+| 插件管理 | 启动店铺时加载指定插件、查询插件安装状态 |
+
+### 不做什么（边界）
+
+- 不是通用浏览器自动化方案——仅适用于紫鸟浏览器客户端
+- 不提供 WebDriver 驱动本身——需根据返回的 `core_version` 自行下载匹配版本的 ChromeDriver
+- 不处理电商平台业务逻辑——仅提供浏览器窗口控制能力
+- 不提供云端部署——仅支持本地运行（通过 `--listen_ip` 可开放远程控制）
+
+---
+
+## Level 1：架构与流程
+
+### 核心概念
+
+**WebDriver 模式**：通过 `--run_type=web_driver` 参数启动紫鸟浏览器，使其进入自动化控制模式。此模式下浏览器在本地指定端口开启 HTTP 服务，接受 JSON 格式的 API 调用。启动前必须关闭紫鸟主进程。
+
+**HTTP IPC 通信**：所有 API 均为 POST 请求，JSON 格式，UTF-8 编码。通过 `--port` 参数指定通信端口，地址为 `http://127.0.0.1:{port}`。每个请求需携带 `action` 字段标识操作类型、`requestId` 做全局唯一标识。超时建议 120 秒以上。
+
+**店铺窗口（browserOauth / browserId）**：紫鸟以"店铺"为最小管理单位。调用 `getBrowserList` 获取店铺列表及加密 ID（`browserOauth`），然后通过 `startBrowser` 启动指定店铺窗口，返回 `debuggingPort` 用于自动化框架连接。若直接使用 `getBrowserList` 返回值打开店铺，只需传 `browserOauth`；仅当需要以明文店铺 ID 打开时才赋值 `browserId`。
+
+**内核版本匹配**：`startBrowser` 返回 `core_type`（如 Chromium）和 `core_version`（如 119.1.0.16），开发者必须使用对应大版本号的 ChromeDriver（如 119.x）连接，否则自动化将失败。
+
+### 流程全景
+
+```mermaid
+graph LR
+  A[申请权限] --> B["启动客户端<br>(先清理残留进程)"]
+  B --> C["updateCore<br>检测内核<br>⚠ 需凭据"]
+  C --> D["getBrowserList<br>获取店铺列表<br>⚠ 需凭据"]
+  D --> E["startBrowser<br>启动店铺窗口<br>⚠ 需凭据"]
+  E --> F["下载匹配的<br>ChromeDriver"]
+  F --> G["连接自动化框架<br>Selenium等"]
+  G --> H[执行自动化操作]
+  H --> I["stopBrowser<br>关闭店铺<br>⚠ 需凭据"]
+  I --> J[exit<br>退出客户端]
+```
+
+1. **申请权限**：在紫鸟开放平台开通 WebDriver 权限
+2. **启动客户端**：先清理残留进程（见§关键陷阱），再命令行启动紫鸟浏览器，必须参数：`--run_type=web_driver --ipc_type=http --port={端口}`
+3. **updateCore**：**必须携带 company/username/password**，轮询检测内核是否就绪（statusCode==0），缺失时自动下载
+4. **getBrowserList**：传入 company/username/password，获取店铺列表
+5. **startBrowser**：传入 company/username/password + browserOauth，返回 debuggingPort 和 core_version
+6. **下载 ChromeDriver**：根据 `core_version` 大版本号下载匹配的 ChromeDriver（**不是系统 Chrome 版本**）
+7. **连接框架**：用 `127.0.0.1:{debuggingPort}` + 匹配版本的 ChromeDriver 连接 Selenium 等
+8. **关闭**：`stopBrowser`（需凭据）关闭店铺窗口，`exit` 退出客户端
+
+### 能力摘要表
+
+| 接口 Action | 职责 | 关键输入 | 关键输出 | 需凭据 |
+|-------------|------|---------|---------|:------:|
+| updateCore | 检测/下载内核 | **company, username, password** | statusCode, msg(进度) | **是** |
+| applyAuth | 设备授权 | company, username, password | statusCode | **是** |
+| getBrowserList | 获取店铺列表 | company, username, password | browserList[{browserOauth, browserName, siteId...}] | **是** |
+| startBrowser | 启动店铺窗口 | company, username, password, browserOauth/browserId | debuggingPort, core_version, core_type | **是** |
+| stopBrowser | 关闭店铺窗口 | company, username, password, browserOauth/browserId | statusCode | **是** |
+| logout | 退出登录 | 无 | statusCode | 否 |
+| exit | 退出客户端进程 | 无 | statusCode | 否 |
+| ClearCache | 清理本地缓存 | browserOauths[] | statusCode | 否 |
+| ClearOnline | 清理在线缓存 | company, username, password, browserOauth, type(1/2/3) | statusCode | **是** |
+| getPluginInstalled | 查询插件安装状态 | browserId, pluginIds | install_status | 否 |
+| getRunningInfo | 获取已开启的店铺 | 无 | browsers[] | 否 |
+
+### 关键陷阱
+
+> **以下均为实战中高频踩坑点，务必在编写自动化脚本时严格遵守。**
+
+#### 陷阱 1：凭据一致性
+
+所有标记"需凭据"的接口（`updateCore`、`getBrowserList`、`startBrowser`、`stopBrowser`、`ClearOnline`）**每次调用都必须携带完整的 company/username/password**，不只是"登录类"接口。`updateCore` 尤其容易遗漏——它看似只是内核检测，但紫鸟服务端需要凭据验证身份后才返回内核状态。
+
+#### 陷阱 2：错误信息处理
+
+API 返回错误时，**优先读取 `err` 字段的内容来定位问题**，而非仅依赖 `statusCode` 数字。`err` 字段包含具体的中文错误描述，是最有价值的排障信息。
+
+编码注意：`err` 中的中文可能因响应体未正确按 UTF-8 解码而出现乱码，导致无法定位根因。**务必确保 HTTP 客户端以 UTF-8 解码响应体**（Python `requests` 库需设置 `response.encoding = 'utf-8'`，或使用 `response.content.decode('utf-8')`）。
+
+#### 陷阱 3：进程残留清理
+
+紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），如果不清理就重启会导致端口占用、反复失败。**每次启动前和失败后重试前，必须确保所有紫鸟相关进程已终止。**
+
+清理命令：
+
+```bash
+# Windows (PowerShell)
+Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force
+
+# macOS / Linux
+pkill -f ziniao || true
+```
+
+#### 陷阱 4：ChromeDriver 版本必须匹配紫鸟内核
+
+紫鸟浏览器的内核版本（`core_version`）**与系统安装的 Chrome 浏览器版本无关**。必须根据 `startBrowser` 返回的 `core_version` 提取大版本号（如 `119.1.0.16` → `119`），下载对应版本的 ChromeDriver。
+
+建议策略：
+1. 首次获取 `core_version` 后，检查本地缓存目录是否已有该大版本的 ChromeDriver
+2. 若无，从 https://googlechromelabs.github.io/chrome-for-testing/ 下载对应版本
+3. 缓存到本地目录（如 `./chromedriver_cache/{major_version}/chromedriver`），后续复用
+
+### 环境约定
+
+| 项目 | 要求 |
+|------|------|
+| Windows | 紫鸟 V5 (5.X.X.X) 或 V6 (6.16.0.126+) |
+| macOS | 紫鸟 V6 (6.15.0.44+) |
+| Linux | 紫鸟 V6 (6.25.3.3+) |
+| 通信协议 | HTTP POST, JSON, UTF-8 |
+| 超时设置 | ≥ 120 秒 |
+| 启动前提 | 紫鸟主进程必须已完全关闭 |
+| 推荐框架 | Selenium（Playwright/Puppeteer 会被检测为自动化） |
+
+---
+
+## 按需深入（Level 2 路由表）
+
+> **规则：以下内容不要主动加载。**
+> 仅在你明确需要了解某个细节时，按路由表读取对应的 reference/ 文件。
+
+| 你需要了解 | 读取文件 |
+|-----------|---------|
+| 核心工作流接口（applyAuth/getBrowserList/startBrowser） | `reference/api-core.md` |
+| 辅助管理接口（stopBrowser/logout/exit/缓存/插件/updateCore） | `reference/api-auxiliary.md` |
+| 启动客户端的命令行参数详细说明 | `reference/startup-params.md` |
+| 各语言/框架的示例代码与下载链接 | `reference/framework-examples.md` |
+| 权限开通、账号配置、常见问题排查 | `reference/prerequisites.md` |
@@ -0,0 +1,226 @@
+# 辅助管理接口
+
+> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
+> 仅在需要查阅 stopBrowser / logout / exit / 缓存清理 / 插件查询 / updateCore 等辅助接口时加载。
+
+## 4. stopBrowser — 关闭店铺窗口
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "stopBrowser",
+  "browserOauth": "店铺ID",
+  "browserId": "店铺数字ID（优先取此值）",
+  "requestId": "全局唯一标识",
+  "duplicate": 0
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "stopBrowser",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功，-10000=未知异常，-10002=参数非法，-10003=登录失败，-10013=需设备认证
+
+---
+
+## 5. logout — 退出登录
+
+**请求：**
+```json
+{
+  "action": "logout",
+  "requestId": "全局唯一标识"
+}
+```
+
+---
+
+## 6. exit — 退出客户端进程
+
+正常退出紫鸟浏览器主进程，会自动关闭已启动店铺并保持 Cookie 等信息。
+
+**请求：**
+```json
+{
+  "action": "exit",
+  "requestId": "全局唯一标识"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "exit",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功，-10005=登出失败
+
+---
+
+## 7. ClearCache — 清理本地缓存
+
+不需要登录即可调用。
+
+**请求：**
+```json
+{
+  "action": "ClearCache",
+  "browserOauths": ["店铺id1", "店铺id2"],
+  "requestId": "全局唯一标识"
+}
+```
+
+`browserOauths` 为空则删除所有本地缓存。
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "ClearCache",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功，-10000=未知异常
+
+---
+
+## 8. ClearOnline — 清理在线缓存
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "ClearOnline",
+  "browserOauth": "店铺ID",
+  "type": 2,
+  "requestId": "全局唯一标识"
+}
+```
+
+`type` 取值：1=清除所有缓存，2=仅保留cookie，3=仅保留二步认证cookie
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "statusMsg": "具体描述",
+  "err": "异常信息",
+  "action": "ClearOnline",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功，-10000=没有找到记录
+
+---
+
+## 9. getPluginInstalled — 查询插件安装状态
+
+**请求：**
+```json
+{
+  "action": "getPluginInstalled",
+  "requestId": "全局唯一标识",
+  "browserId": "店铺ID",
+  "duplicate": 0,
+  "pluginIds": "插件id,插件id"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "statusMsg": "",
+  "err": "异常信息",
+  "action": "getPluginInstalled",
+  "requestId": "全局唯一标识",
+  "install_status": true
+}
+```
+
+`install_status`：true=已通知安装，false=未通知
+
+**状态码：** 0=成功，-10000=没有找到记录
+
+---
+
+## 10. getRunningInfo — 获取当前已开启的店铺
+
+**请求：**
+```json
+{
+  "action": "getRunningInfo",
+  "requestId": "全局唯一标识"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "browsers": [],
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功
+
+---
+
+## 11. updateCore — 更新内核
+
+> **⚠ 此接口必须携带 company/username/password 凭据。** 遗漏凭据会导致请求失败——这是最常见的对接错误之一，因为 updateCore 看似只是"内核检测"，容易被误认为不需要登录态。
+
+因 HTTP 有超时限制，此接口适合循环调用直到返回成功。
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "updateCore",
+  "requestId": "全局唯一标识"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：** 0=成功，-10000=处理中
+
+**调用机制：**
+1. 客户端启动后调用 updateCore，若连接失败说明客户端还未启动成功，轮询（每2秒）直到连接成功
+2. statusCode==0 → 内核就绪，继续后续操作
+3. statusCode!=0 → 内核缺失/下载中，继续轮询并展示 `msg` 中的下载进度
+4. 建议设置总超时 300 秒，避免无限等待
+
+**错误排查：**
+- 返回错误时**优先读取 `err` 字段**获取中文错误描述，而非仅看 statusCode 数字
+- 若 `err` 内容出现乱码，说明 HTTP 响应体未正确按 UTF-8 解码——务必确保客户端以 UTF-8 解码响应
+- 常见失败原因：未携带凭据、凭据错误、客户端尚未完全启动
@@ -0,0 +1,201 @@
+# 核心工作流接口
+
+> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
+> 仅在需要查阅 applyAuth / getBrowserList / startBrowser 的请求/响应格式与状态码时加载。
+
+## 概述
+
+紫鸟 WebDriver 共提供 11 个 HTTP API，均为 POST 请求，JSON 格式，UTF-8 编码。
+请求地址：`http://127.0.0.1:{port}`（port 为启动参数 `--port` 指定的端口）。
+
+通用字段说明：
+- `action`：接口标识（必须）
+- `requestId`：全局唯一请求标识（必须）
+- `statusCode`：返回状态码，`0` 表示成功
+- `err`：异常信息
+
+---
+
+## 1. applyAuth — 申请设备授权
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "applyAuth",
+  "requestId": "全局唯一标识"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "applyAuth",
+  "requestId": "全局唯一标识"
+}
+```
+
+**状态码：**
+| 码值 | 说明 |
+|------|------|
+| 0 | 成功 |
+| -10000 | 未知异常 |
+| -10002 | Socket参数非法 |
+| -10003 | 申请流程异常 |
+| -10004 | 申请失败 |
+
+---
+
+## 2. getBrowserList — 获取店铺列表
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "getBrowserList",
+  "requestId": "全局唯一标识"
+}
+```
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "getBrowserList",
+  "requestId": "全局唯一标识",
+  "browserList": [{
+    "browserOauth": "店铺ID（加密）",
+    "browserName": "店铺名称",
+    "browserIp": "店铺IP",
+    "siteId": "店铺所属站点",
+    "isExpired": false,
+    "platform_id": "平台id",
+    "platform_name": "平台名称"
+  }]
+}
+```
+
+SiteId 说明文档：https://cdn-superbrowser-attachment.ziniao.com/webdriver/doc/SiteId%E8%AF%B4%E6%98%8E20250703.txt
+
+**状态码：**
+| 码值 | 说明 |
+|------|------|
+| 0 | 成功 |
+| -10000 | 未知异常 |
+| -10002 | Socket参数非法 |
+| -10003 | 登录失败（需开通webdriver权限/关闭登录验证） |
+| -10004 | 获取店铺列表时服务器返回异常 |
+| -10013 | 需要设备认证 |
+
+---
+
+## 3. startBrowser — 启动店铺窗口
+
+连续两次调用 startBrowser 会视为重启。关闭店铺需调用 stopBrowser。
+
+**请求：**
+```json
+{
+  "company": "公司",
+  "username": "用户名",
+  "password": "密码",
+  "action": "startBrowser",
+  "browserOauth": "店铺ID（加密）",
+  "browserId": "店铺ID（未加密，优先取此值）",
+  "isHeadless": true,
+  "isWaitPluginUpdate": true,
+  "privacyMode": true,
+  "requestId": "全局唯一标识",
+  "runMode": "运行模式 1轻量/2均衡(默认)/3极速",
+  "pluginIdList": "id1,id2,id3",
+  "pluginIdType": 0,
+  "proxyTagFiter": "name1,name2,name3",
+  "cookieTypeLoad": 0,
+  "cookieTypeSave": 0,
+  "injectJsInfo": "{\"url\":\"http://...\",\"username\":\"用户名\"}",
+  "notPromptForDownload": 1,
+  "isLoadUserPlugin": true,
+  "windowRatio": 100,
+  "forceDownloadPath": "文件下载路径（绝对路径）",
+  "preSetting": "{\"profile.managed_default_content_settings.images\": 2}"
+}
+```
+
+参数说明：
+- `browserOauth` / `browserId`：二选一指定目标店铺。如果直接使用 `getBrowserList` 返回的数据来打开店铺，**只需传 `browserOauth` 即可**（它已包含加密店铺标识）；仅当用户需要使用明文店铺 ID 打开时，才需要赋值 `browserId`。两者同时存在时 `browserId` 优先。
+- `isHeadless`：无头模式（开启后需自行检测网络）
+- `isWaitPluginUpdate`：等待插件热更新完成（仅 V5）
+- `runMode`：仅 V5 支持
+- `pluginIdType`：0=插件版本id，1=插件id
+- `cookieTypeLoad`：固定传 0
+- `cookieTypeSave`：0=默认，1=不提交
+- `notPromptForDownload`：1=不弹窗，0=弹窗
+- `windowRatio`：0-100，0=不控制，100=全屏
+- `preSetting`：浏览器配置 JSON，支持无图模式
+
+**响应：**
+```json
+{
+  "statusCode": "状态码",
+  "err": "异常信息",
+  "action": "startBrowser",
+  "browserOauth": "店铺ID",
+  "requestId": "全局唯一标识",
+  "LastError": "内部错误信息",
+  "ip": "代理IP",
+  "isDynamicIp": "是否动态IP",
+  "browserPath": "允许的下载路径",
+  "launcherPage": "平台默认启动页面",
+  "ipDetectionPage": "IP检测页地址",
+  "debuggingPort": "调试端口",
+  "reportPluginId": "报表插件id",
+  "duplicate": "副本标志",
+  "proxyTag": "当前启动的代理标志",
+  "proxyType": 5,
+  "mainHandle": "窗口句柄",
+  "core_version": "内核版本",
+  "core_type": "内核类型",
+  "coreVersion": "内核版本",
+  "coreType": "内核类型",
+  "downloadPath": "文件下载路径"
+}
+```
+
+`proxyType` 取值：-1=错误数据，0=站群，1=云平台，2=自有IP，5=本地IP
+
+使用 Selenium 连接时需根据 `core_type` 及 `core_version` 选取对应版本 ChromeDriver：
+```java
+ChromeOptions options = new ChromeOptions();
+options.setExperimentalOption("debuggerAddress", "127.0.0.1:" + debuggingPort);
+```
+
+**状态码：**
+| 码值 | 说明 |
+|------|------|
+| 0 | 成功 |
+| -10000 | 未知异常 |
+| -10001 | 内核窗口创建失败 |
+| -10002 | Socket参数非法 |
+| -10003 | 登录失败 |
+| -10004 | browserOauth缺失 |
+| -10006 | 上次 startBrowser 还未执行结束 |
+| -10013 | 需要设备认证 |
+| 1 | 初始化数据失败 |
+| 2 | 当前IP无法正常使用 |
+| 4 | 初始化时区失败 |
+| 5 | 初始化代理失败 |
+| 6 | 初始化黑白名单失败 |
+| 7 | 启动内核失败 |
+| 8 | 初始化浏览器个人目录失败 |
+| 9 | 初始化Cookies失败 |
+| 11 | 初始化浏览器设置文件失败 |
+| 13 | 初始化代理信息配置失败 |
+
+`LastError` 字段包含具体错误信息。
@@ -0,0 +1,159 @@
+# 自动化框架示例
+
+> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
+> 仅在需要查看各语言/框架的示例代码与下载链接时加载。
+
+## 概述
+
+紫鸟 WebDriver 支持多种自动化框架和编程语言。所有示例代码均需替换以下信息后运行：
+- 驱动程序路径（ChromeDriver 等）
+- 客户端可执行程序路径
+- Socket 端口号
+- 用户登录信息（company, username, password）
+
+**推荐使用 Selenium**：Playwright 和 Puppeteer 会被平台检测为自动化，需自行处理特征问题。
+
+## 框架支持矩阵
+
+| 框架 | 语言 | 示例文件 | 下载链接 | 备注 |
+|------|------|---------|---------|------|
+| Selenium | Python | ziniao_webdriver_http_py3.py | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/ziniao_webdriver_http_py3.py) | 基础店铺访问示例，适合初学者 |
+| Selenium | Python | ziniao_webdriver_demo | [GitHub](https://github.com/ziniao-open/ziniao_webdriver_demo) | 开源示例集：订单拉取、报表下载、评价导出 |
+| Selenium | Java | webdriver-java-demo.zip | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/webdriver-java-demo.zip) | 用 IDEA 打开后运行 |
+| Selenium | C#.NET | webdriver-C#.net-demo.zip | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/webdriver-CSharp-demo.zip) | Windows 环境 |
+| Puppeteer | JavaScript | puppeteer_js_demo.zip | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/puppeteer_js_demo.zip) | 通过 Puppeteer API 控制 |
+| Playwright | Python | ziniao_playwright_http_py3.py | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/ziniao_playwright_http_py3.py) | 会被检测为自动化，建议用 Selenium |
+| Playwright | Java | playwright-java-demo.zip | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/playwright-java-demo.zip) | 会被检测为自动化，建议用 Selenium |
+| Playwright | JavaScript | playwright_js_demo.zip | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/playwright_js_demo.zip) | 会被检测为自动化，建议用 Selenium |
+| DrissionPage | Python | ziniao_drissionpage_http_py3.py | [下载](https://cdn-superbrowser-attachment.ziniao.com/webdriver/demo/20260119/ziniao_drissionpage_http_py3.py) | 通过 DrissionPage API 控制 |
+
+## 连接示例（以 Selenium 为例）
+
+### Python + Selenium
+
+```python
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.chrome.service import Service
+
+# startBrowser 返回的 debuggingPort 和 core_version
+debugging_port = 12345
+core_version = "119.1.0.16"
+
+# 根据 core_version 的大版本号选择对应 ChromeDriver
+chrome_driver_path = "/path/to/chromedriver-119"
+
+options = Options()
+options.add_experimental_option("debuggerAddress", f"127.0.0.1:{debugging_port}")
+
+service = Service(executable_path=chrome_driver_path)
+driver = webdriver.Chrome(service=service, options=options)
+
+# 现在可以操作店铺浏览器窗口
+print(driver.title)
+```
+
+### Java + Selenium
+
+```java
+ChromeOptions options = new ChromeOptions();
+options.setExperimentalOption("debuggerAddress", "127.0.0.1:" + debuggingPort);
+
+// 根据 core_version 选择对应版本 ChromeDriver
+System.setProperty("webdriver.chrome.driver", "/path/to/chromedriver-" + majorVersion);
+
+WebDriver driver = new ChromeDriver(options);
+System.out.println(driver.getTitle());
+```
+
+## ChromeDriver 版本匹配
+
+> **⚠ 紫鸟内核版本 ≠ 系统 Chrome 版本。** 不要使用系统安装的 Chrome 浏览器对应的 ChromeDriver，必须根据紫鸟 `startBrowser` 返回的 `core_version` 来匹配。
+
+`startBrowser` 响应中的 `core_type` 和 `core_version` 决定了需要使用的 ChromeDriver 版本：
+- `core_type: "Chromium"`, `core_version: "119.1.0.16"` → 使用 ChromeDriver 119.x
+- 下载地址：https://googlechromelabs.github.io/chrome-for-testing/
+- JSON API（自动化脚本可直接解析）：https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json
+
+版本不匹配会导致连接失败，务必检查。
+
+### 自动下载与缓存策略（Python 伪代码）
+
+```python
+import os, re, json, zipfile, io, platform
+import requests
+
+CACHE_DIR = "./chromedriver_cache"
+
+def get_chromedriver_path(core_version: str) -> str:
+    """根据紫鸟 core_version 获取匹配的 ChromeDriver 路径，自动下载缓存。"""
+    major = core_version.split(".")[0]  # "119.1.0.16" → "119"
+    
+    exe_name = "chromedriver.exe" if platform.system() == "Windows" else "chromedriver"
+    cached = os.path.join(CACHE_DIR, major, exe_name)
+    
+    if os.path.exists(cached):
+        return cached
+    
+    # 查询可用版本
+    resp = requests.get(
+        "https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json"
+    )
+    resp.encoding = "utf-8"
+    data = resp.json()
+    
+    # 找到该大版本的最新 chromedriver
+    plat = {
+        "Windows": "win64", "Darwin": "mac-x64", "Linux": "linux64"
+    }[platform.system()]
+    
+    download_url = None
+    for v in reversed(data["versions"]):
+        if v["version"].startswith(major + ".") and "chromedriver" in v["downloads"]:
+            for d in v["downloads"]["chromedriver"]:
+                if d["platform"] == plat:
+                    download_url = d["url"]
+                    break
+            if download_url:
+                break
+    
+    if not download_url:
+        raise RuntimeError(f"未找到大版本 {major} 的 ChromeDriver 下载地址")
+    
+    # 下载并解压
+    os.makedirs(os.path.join(CACHE_DIR, major), exist_ok=True)
+    zip_resp = requests.get(download_url)
+    with zipfile.ZipFile(io.BytesIO(zip_resp.content)) as zf:
+        for name in zf.namelist():
+            if name.endswith(exe_name):
+                with open(cached, "wb") as f:
+                    f.write(zf.read(name))
+                break
+    
+    if platform.system() != "Windows":
+        os.chmod(cached, 0o755)
+    
+    return cached
+```
+
+### 缓存目录结构
+
+```
+chromedriver_cache/
+├── 119/
+│   └── chromedriver.exe
+├── 120/
+│   └── chromedriver.exe
+└── ...
+```
+
+## GitHub 开源示例项目
+
+仓库地址：https://github.com/ziniao-open/ziniao_webdriver_demo
+
+包含以下场景示例：
+1. **Demo 1**：电商订单自动拉取（热门推荐）
+2. **Demo 2**：销售与流量业务报表下载
+3. **Demo 3**：电商平台用户评价导出
+
+克隆后替换配置信息即可运行。
@@ -0,0 +1,141 @@
+# 前置条件与排障
+
+> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
+> 仅在需要了解权限开通、账号配置、常见问题排查时加载。
+
+## 概述
+
+使用紫鸟 WebDriver 前需完成权限开通和环境准备。本文档覆盖权限申请、账号配置和常见问题排查。
+
+## 1. 开通 WebDriver 权限
+
+首次使用 WebDriver 时，需先在紫鸟开放平台开通权限。
+
+详细步骤见官方文档：[如何开通webdriver权限](https://open.ziniao.com/docSupport?docId=99)
+
+## 2. 客户端版本要求
+
+| 操作系统 | 最低版本 |
+|---------|---------|
+| Windows | 紫鸟 V5 (5.X.X.X) 或 V6 (6.16.0.126+) |
+| macOS | 紫鸟 V6 (6.15.0.44+) |
+| Linux | 紫鸟 V6 (6.25.3.3+) |
+
+## 3. 环境准备清单
+
+### 3.1 关闭主进程
+
+启动 WebDriver 前**务必**确保紫鸟浏览器主进程已完全关闭，避免端口占用或冲突。
+
+### 3.2 清理残留进程
+
+紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），不清理直接重启会导致端口占用、反复失败。**每次启动前和失败后重试前，都必须执行清理。**
+
+已知的紫鸟相关进程名：`ziniao`、`ZiNiao`、`ziniao.exe`、`ZiNiaoBrowser` 等（不同版本命名可能不同，建议用模糊匹配）。
+
+清理命令：
+
+```bash
+# Windows (PowerShell)
+Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force
+
+# macOS / Linux
+pkill -f ziniao || true
+```
+
+验证清理结果：
+
+```bash
+# Windows (PowerShell) — 应无输出
+Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' }
+
+# macOS / Linux — 应无输出
+pgrep -f ziniao
+```
+
+### 3.3 创建自动化专用账号
+
+- 创建专用的自动化成员账号（命名建议：`自动化_Robot`）
+- 正式使用前验证该账号能否正常登录紫鸟浏览器客户端
+
+### 3.4 配置账号权限
+
+**问题场景**：自动化账号登录后无法获取店铺列表。
+
+**解决方案**：
+1. 登录企业管理后台
+2. 检查该账号的权限配置
+3. 授予查看对应账号/店铺的权限
+4. 建议新建包含此权限的自定义角色并分配给自动化账号
+
+### 3.5 超时设置
+
+将所有 HTTP 请求的超时时间设为 **120 秒或以上**，因为启动店铺环境可能耗时较长。
+
+### 3.6 系统资源管理
+
+- 启动店铺窗口 CPU 消耗较大
+- 根据设备配置合理控制并发启动数量
+- 建议错开各任务的启动时间，避免瞬时负载过高
+
+### 3.7 ChromeDriver 版本管理
+
+> **关键：紫鸟内核版本 ≠ 系统 Chrome 版本。** 必须根据 `startBrowser` 返回的 `core_version` 匹配 ChromeDriver，不能使用系统 Chrome 对应的版本。
+
+**匹配规则：**
+- `core_version` 格式为 `X.Y.Z.W`（如 `119.1.0.16`），取第一段 `X` 作为大版本号
+- 下载该大版本号对应的 ChromeDriver（如大版本 `119` → ChromeDriver 119.x）
+
+**下载地址：**
+- Chrome for Testing：https://googlechromelabs.github.io/chrome-for-testing/
+- JSON API（便于自动化脚本解析）：https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json
+
+**本地缓存建议：**
+
+```
+chromedriver_cache/
+├── 119/
+│   └── chromedriver.exe    # 对应 core_version 119.x
+├── 120/
+│   └── chromedriver.exe    # 对应 core_version 120.x
+└── ...
+```
+
+自动化脚本应实现以下逻辑：
+1. 从 `startBrowser` 响应中提取 `core_version` 大版本号
+2. 检查缓存目录 `chromedriver_cache/{major_version}/` 是否存在
+3. 若不存在，从 Chrome for Testing 下载对应版本并解压到缓存目录
+4. 使用缓存中的 ChromeDriver 路径连接 Selenium
+
+## 4. 通信注意事项
+
+1. 请求/响应均为 JSON 格式，收发消息统一 UTF-8 编码
+2. HTTP 模式下超时时长必须 ≥120 秒
+3. 调用任何接口后务必检查 `statusCode`（0 表示成功），**出错时优先读取 `err` 字段获取中文错误描述**，这是最有价值的排障信息
+4. **启动后必须首先调用 `updateCore` 接口**（需携带凭据），否则打开店铺可能出现内核缺失
+5. **务必确保 HTTP 客户端以 UTF-8 解码响应体**，否则 `err` 中的中文会乱码，严重影响错误定位（Python `requests` 库需设置 `response.encoding = 'utf-8'`）
+6. 所有标记"需凭据"的接口（`updateCore`、`getBrowserList`、`startBrowser`、`stopBrowser`、`ClearOnline`）每次调用都必须携带 company/username/password
+
+## 5. 常见问题
+
+| 现象 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| 连接接口失败 | 客户端未启动完成 | 轮询 updateCore 直到连接成功 |
+| getBrowserList 返回 -10003 | 未开通权限或未关闭登录验证 | 检查权限开通状态 |
+| getBrowserList 返回 -10013 | 新设备未授权 | 调用 applyAuth 进行设备授权 |
+| 店铺列表为空 | 账号无店铺权限 | 在企业管理后台配置角色权限 |
+| startBrowser 返回 -10006 | 上次启动未完成 | 等待或调用 stopBrowser 后重试 |
+| startBrowser 返回 7 | 内核缺失 | 确保先调用 updateCore 等待成功 |
+| Selenium 连接失败 | ChromeDriver 版本不匹配 | 根据 core_version 下载匹配版本 |
+| 请求超时 | 超时设置过短 | 设置超时 ≥120 秒 |
+| 多账号冲突 | 端口/缓存冲突 | V5 使用 `--multip` + `--enforce-cache-path` |
+| updateCore 返回错误 | 未携带凭据（company/username/password） | 所有需凭据的接口必须携带完整凭据 |
+| err 字段内容乱码 | HTTP 响应体未以 UTF-8 解码 | 设置 `response.encoding = 'utf-8'` 或用 `response.content.decode('utf-8')` |
+| 重启失败 / 端口占用 | 上次失败后残留紫鸟进程 | 清理所有紫鸟相关进程后重试（见§3.2） |
+| Selenium 连接失败（版本不匹配） | 使用了系统 Chrome 对应的 ChromeDriver | 必须根据紫鸟 `core_version` 大版本号下载匹配的 ChromeDriver（见§3.7） |
+
+## 6. 技术支持
+
+如在对接过程中遇到问题，可通过以下渠道获取支持：
+- 微信添加紫鸟生态管家，备注 "紫鸟webdriver"
+- 官方 FAQ：https://open.ziniao.com/docSupport?docId=257
@@ -0,0 +1,122 @@
+# 启动参数详细说明
+
+> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
+> 仅在需要了解紫鸟浏览器 WebDriver 模式的启动命令行参数时加载。
+
+## 概述
+
+通过命令行参数启动紫鸟浏览器客户端，使其进入 WebDriver 模式。
+启动前**必须**关闭紫鸟浏览器的主进程，否则可能端口占用或冲突。
+
+## 必选参数
+
+| 参数 | 版本支持 | 说明 |
+|------|---------|------|
+| `--run_type=web_driver` | V5 / V6 全平台 | 指定以 WebDriver 模式运行主进程 |
+| `--ipc_type=http` | V5 / V6 全平台 | 约定通信方式为 HTTP，超时建议 ≥120 秒 |
+| `--port=端口号` | V5 / V6 全平台 | 指定通讯端口，紫鸟在本机以此端口启动 HTTP 服务 |
+
+## 可选参数
+
+| 参数 | 版本支持 | 说明 |
+|------|---------|------|
+| `--port_exception=1886,1567` | V5 only | 店铺内允许连接到本地的端口号，逗号分隔 |
+| `--multip` | V5 only | 去除干扰自动化的功能，多账号建议与 `--enforce-cache-path` 一起使用 |
+| `--enforce-cache-path=路径` | V5 only | 指定独立缓存目录，允许多账号同时运行，需自行调整 `--port` 避免冲突 |
+| `--listen_ip=IP` | V5 only | 设置监听地址，默认 127.0.0.1。非本机时允许远程控制 |
+| `--dns=DNS服务器` | V5 only | 设置 DNS，默认使用本机 DNS。示例：`--dns=223.5.5.5` |
+
+## 启动命令示例
+
+### Python
+
+```python
+import subprocess, platform, time
+
+client_path = "紫鸟浏览器可执行文件路径"
+socket_port = 9515
+
+is_windows = platform.system() == 'Windows'
+is_mac = platform.system() == 'Darwin'
+is_linux = platform.system() == 'Linux'
+
+def start_browser():
+    try:
+        if is_windows:
+            cmd = [client_path,
+                   '--run_type=web_driver',
+                   '--ipc_type=http',
+                   '--port=' + str(socket_port)]
+        elif is_mac:
+            cmd = ['open', '-a', client_path, '--args',
+                   '--run_type=web_driver',
+                   '--ipc_type=http',
+                   '--port=' + str(socket_port)]
+        elif is_linux:
+            cmd = [client_path, '--no-sandbox',
+                   '--run_type=web_driver',
+                   '--ipc_type=http',
+                   '--port=' + str(socket_port)]
+        else:
+            exit()
+        subprocess.Popen(cmd)
+        time.sleep(5)
+    except Exception:
+        import traceback
+        print('start browser process failed: ' + traceback.format_exc())
+        exit()
+```
+
+### JavaScript (Node.js)
+
+```javascript
+const childProcess = require('child_process');
+const util = require('util');
+const os = require('os');
+const execFile = util.promisify(childProcess.execFile);
+
+const clientPath = '紫鸟浏览器可执行文件路径';
+const socketPort = 9515;
+
+const is_windows = os.platform() === 'win32';
+const is_mac = os.platform() === 'darwin';
+const is_linux = os.platform() === 'linux';
+
+async function startBrowser() {
+    try {
+        if (is_windows) {
+            const cmd = [clientPath,
+                '--run_type=web_driver',
+                '--ipc_type=http',
+                `--port=${socketPort}`];
+            execFile(cmd[0], cmd.slice(1));
+        } else if (is_mac) {
+            const cmd = ['open', '-a', clientPath, '--args',
+                '--run_type=web_driver',
+                '--ipc_type=http',
+                `--port=${socketPort}`];
+            execFile(cmd[0], cmd.slice(1));
+        } else if (is_linux) {
+            const cmd = [clientPath, '--no-sandbox',
+                '--run_type=web_driver',
+                '--ipc_type=http',
+                `--port=${socketPort}`];
+            execFile(cmd[0], cmd.slice(1));
+        } else {
+            process.exit();
+        }
+        await new Promise(resolve => setTimeout(resolve, 5000));
+    } catch (error) {
+        console.log(`start browser process failed: ${error}`);
+        process.exit();
+    }
+}
+```
+
+## 各操作系统差异
+
+| 操作系统 | 启动方式 | 特殊参数 |
+|---------|---------|---------|
+| Windows | 直接调用可执行文件 | 无 |
+| macOS | 通过 `open -a` 启动，`--args` 传参 | 无 |
+| Linux | 直接调用可执行文件 | 需追加 `--no-sandbox` |