| name | AgentChat-OneWeb |
| description | Multi-provider CDP bridge with automatic fallback (Gemini->ChatGPT->Claude->Qwen->Kimi->MiniMax->Doubao->MiMo->DeepSeek). Use for AI provider failover, fallback chain, multi-provider routing, or "send to any available AI". MANDATORY EXECUTION - invoking this skill REQUIRES running `node ~/.claude/skills/AgentChat-OneWeb/index.js "<prompt>"` as the FIRST action and quoting its `[receipt] AGENTCHAT_RUN` line in the final answer; explaining the skill or answering from model knowledge without a receipt is a violation. |
AI Fallback Chain — Multi-Provider CDP Bridge
最后更新: 2026-08-09
核心功能: 按优先级链自动降级，确保始终有一个可用的大模型
变更日志: 见 CHANGELOG.md
⚠️ 强制规则 — 调用即执行（首要动作契约）
本 skill 被调用（如 /AgentChat-OneWeb <问题>）时，必须执行 node 命令把用户问题发送到 web AI。禁止只解释用法而不执行，禁止用模型自身知识替代 web AI 的回答。
1. 首要动作契约
读完本 SKILL.md 之后的下一个工具调用必须是：
node ~/.claude/skills/AgentChat-OneWeb/index.js "<用户prompt>"
中间不允许插入文件浏览、架构分析、"我将会…"式的规划叙述（至多一行说明即将执行的命令）。web AI 返回结果后，才可补充你自己的分析。
2. 执行回执（receipt）— 是否执行以此为准，不以叙述为准
每次真实执行（含失败）都会在 stderr 输出一行机器生成的回执：
[receipt] AGENTCHAT_RUN {"run_id":"ac-xxxxxxxxxxxx","skill":"AgentChat-OneWeb","exit":0,"provider_used":"Gemini",...}
- 最终回答末尾必须原样引用这行 receipt（至少包含 run_id、provider_used、exit）。
- 没有 receipt = 没有执行 = 违规，必须回去执行。
run_id 为随机生成并同步落盘到 ~/.claude/skills/AgentChat-OneWeb/data/receipts.jsonl，用户可用 grep <run_id> 核对——凭空编造无法通过核对。- 执行失败（exit≠0）同样有 receipt：必须引用失败回执并说明原因（限流/未登录/超时…），在此之后才允许用模型自身能力回答，且必须明确标注"web AI 未参与本次回答"。
3. 违规模式（全部禁止）
- ❌ 读完 SKILL.md 后描述 fallback 链、罗列 CLI 参数、讲解架构——却不跑
node index.js
- ❌ 以"问题太简单/我已经知道答案"为由跳过执行，直接用模型知识回答
- ❌ 回答中没有
[receipt] AGENTCHAT_RUN 行却声称"已通过 web AI 处理"
4. 例外
仅限：--smoke、--doctor，或用户明确要求"只检查环境不发送"。这两种模式不产生 receipt，属预期行为。
5. 本地上下文
网页 AI 无法访问本地文件系统。涉及本地文件/代码/图片时，Claude Code 须先将内容读入 prompt 再发送，禁止只传文件路径。
📐 输出排版规范 — 最终回答强制格式
约束对象是 Claude Code 撰写的最终落地文本；worker 原始输出、代码块、diff、表格与 receipt 行不受约束。
- 结论先行：开头第一段为 ≤50 字的核心结论（TL;DR），直接回答用户根本诉求，无客套话、无方法论铺垫。
- 标题层级：主模块用
##，子观点用 ###，禁止一级标题 #。维度按逻辑聚类为 3–5 块（如：背景/现状/分析/结论），禁止按检索顺序写流水账。
- 视觉焦点：数据、时间、专有名词、核心论点用
**加粗** 标出；加粗仅用于焦点引导，每个自然段不超过 2 处。
- 列表纪律：只允许单层无序列表
*，禁止任何多级嵌套列表（保证终端/聊天框阅读体验）。
- 文本密度：叙述性自然段 ≤3 句，新逻辑分支必须换行分段；禁止"总而言之""基于以上搜索结果""作为一个人工智能"等无实质信息的过渡句。
- 信息隔离：引用 web AI 原文片段或外部链接时必须放入
> 引用块并标注来源 provider，与自己的分析严格区分。
- 豁免条款（优先级高于第 1–6 条）：
[receipt] AGENTCHAT_RUN {...} 行（或各步 run_id 清单）必须原样保留在回答末尾的代码块中，禁止改写、加粗、省略——受强制规则 §2 约束。- 降级/失败披露（如"N 个角色降级""web AI 未参与本次回答"）属流程透明性要求，不算冗余过渡句，不得删除。
- 代码块、diff、表格不受段落长度与列表层级限制。
🖼️ 图片生成协议 (Image Generation Protocol)
触发条件
当用户请求涉及以下任一关键词时，触发图片生成协议：
- 生成类: 生成图片、画图、制图、绘制、作图、生成图、create image、generate image、make image
- 图表类: 流程图、架构图、示意图、思维导图、图表、拓扑图、chart、diagram、flowchart、mindmap、Mermaid
- 可视化类: 可视化、visualization、illustration、infographic、DALL·E、Imagen、Midjourney
1. Prompt 自动增强（强制 — 传 --image flag，v14 起由 index.js 内置）
检测到图片生成请求时，必须在命令中加入 --image flag：
node ~/.claude/skills/AgentChat-OneWeb/index.js --image "<用户原始prompt>"
index.js 会在进程内把标准增强指令（"请使用你的图片生成模型/工具主动生成…"）追加到 prompt 末尾，并在 telemetry 中记录 image_prompt_enhanced: true。禁止手工改写 prompt 来替代 --image —— 手工追加是纯 prose 约束，属于 receipt 机制要消灭的那类"叙述性合规"；flag 路径是机器可验证的（telemetry 可查）。
如果用户已明确指定 --from=ChatGPT（DALL·E）或 --from=Gemini（Imagen），优先使用该 provider 的生图能力：--image --from=Gemini。
2. 图片自动下载（强制 — index.js 内置）
index.js 在收到 web AI 响应后，自动执行以下步骤：
- 扫描响应文本中的图片 URL：
- Markdown 语法：
- HTML 标签：
<img src="url">
- 直链：以
.png/.jpg/.jpeg/.gif/.webp/.svg 结尾的 URL
- 将每张图片下载到 当前工作目录（
process.cwd()，即用户执行 skill 时所在的目录）
- 文件名格式：
ai-image-{YYYYMMDD-HHmmss}-{pid}-{序号}.{ext}（v14 加入 pid，避免并发 worker 同秒写同名互相覆盖）
- 下载结果摘要（
## 📥 Downloaded Images 段落）：stdout 为 TTY 时（人类直接运行）附加在响应末尾；stdout 为管道时（execute.js / Python SDK / MCP server 消费）摘要只走 stderr，stdout 保持"AI 响应原文"机器契约不被污染，成功/失败计数记入 receipt（images_ok / images_failed）。
v14 硬限制（下载 URL 来自 web AI 响应这一不可信文本，可被 prompt injection 操控）：
- 每次响应最多下载 20 张，超出部分在摘要中明确标记为 skipped
- 单张 30MB 上限；下载阶段总预算 120s；tier-2 页面内 fetch 带 25s AbortSignal（此前无超时——一个挂起的图片端点会让整个进程永不退出）
- 所有 tier 均做 payload 嗅探：HTTP 200 返回的 HTML 错误页判定为下载失败，不再落盘为损坏的
.png
- 拒绝 loopback / link-local / RFC1918 私网地址（如
http://127.0.0.1:9222/... —— 注入的 URL 曾可把 CDP 调试端点数据写进用户目录）；内网/测试环境可用 AGENTCHAT_ALLOW_PRIVATE_IMAGE_HOSTS=1 放行
- 相对
Location: 重定向与 303 已正确跟随；重定向目标同样过 blocked-host 检查
如果响应中无图片 URL，该步骤为零开销 no-op。
3. 下载目录说明
下载目标始终为 用户当前工作目录（shell 的 $PWD），而非 skill 安装目录。例如：
- 用户在
~/Project/ 下调用 /AgentChat-OneWeb 帮我画流程图 → 图片下载到 ~/Project/
- 用户在
~/Data_Project/ 下调用 → 图片下载到 ~/Data_Project/
可通过 --no-download-images 标志禁用自动下载。
🖼️ 图片上传协议 (Image Upload Protocol)
触发条件
当用户请求涉及以下模式时，触发图片上传协议：
- 明确上传指令: 上传图片、传图、发图片、把图片发给AI、upload image、send image to AI
- 图片路径引用: 用户在消息中提及
.png/.jpg/.jpeg/.gif/.webp/.bmp 等图片文件路径
- 视觉分析请求: 分析这张图、看看这张图片、describe this image、what's in this picture
1. 自动识别图片路径（强制）
当用户说"把图片上传给AI"或类似指令时，必须从用户消息中提取图片文件路径，然后使用 --image-path 标志：
node ~/.claude/skills/AgentChat-OneWeb/index.js --image-path="<图片绝对路径>" "<用户prompt>"
路径解析规则：
- 用户提供的路径可能是相对路径（相对于当前工作目录
$PWD）或绝对路径
- index.js 会自动将相对路径解析为绝对路径
- 支持多次
--image-path 上传多张图片
2. 粘贴流程（index.js 内置 — 无需人工操作）
当 --image-path 被指定时，index.js 在 provider 管线中自动执行以下步骤：
- 读取图片文件：从磁盘读取图片，转为 base64 编码，检测 MIME 类型
- 写入剪贴板：通过 async Clipboard API（
navigator.clipboard.write）将图片写入系统剪贴板
- 粘贴到对话框：聚焦 AI 聊天输入框，按
Ctrl+V 粘贴图片
- 等待上传完成：等待 2.5s 让 web UI 处理图片附件
- 输入提示词：在图片粘贴完成后，输入用户的文本 prompt
- 发送：点击发送按钮
备用路径（当 Clipboard API 不可用时）：
- 模拟 paste 事件：创建
DataTransfer 包含图片 File 对象，分发 ClipboardEvent('paste')
- 最终兜底：将
<img> 标签注入 contenteditable 编辑器
3. 支持的图片格式
| 格式 | MIME Type | 扩展名 |
|---|
| PNG | image/png | .png |
| JPEG | image/jpeg | .jpg, .jpeg |
| GIF | image/gif | .gif |
| WebP | image/webp | .webp |
| BMP | image/bmp | .bmp |
| SVG | image/svg+xml | .svg |
| TIFF | image/tiff | .tiff, .tif |
| AVIF | image/avif | .avif |
| ICO | image/x-icon | .ico |
单文件上限 50MB。
4. 使用示例
node ~/.claude/skills/AgentChat-OneWeb/index.js --image-path=./screenshot.png "分析这张截图的内容"
node ~/.claude/skills/AgentChat-OneWeb/index.js \
--image-path=./before.png \
--image-path=./after.png \
"比较这两张图片的差异"
node ~/.claude/skills/AgentChat-OneWeb/index.js \
--image-path=./photo.jpg \
--from=Gemini \
"描述这张照片"
5. AI Agent 调用规范
当用户说"上传图片给AI"或类似指令时，调用 agent 必须：
- 识别图片路径：从用户消息中提取图片文件路径
- 验证文件存在：确认图片文件存在于用户系统中
- 构造命令：使用
--image-path=<绝对路径> 标志
- 执行命令：运行
node ~/.claude/skills/AgentChat-OneWeb/index.js --image-path=... "prompt"
- 引用 receipt：按强制规则 §2 在最终回答中引用
[receipt] AGENTCHAT_RUN 行
禁止行为：
- ❌ 用
--image 代替 --image-path（前者是生图意图，后者是上传意图）
- ❌ 先描述图片内容再用文本发给 AI——必须上传原始图片文件
- ❌ 跳过
--image-path 只用文本描述图片
Trigger
Use this skill when:
- The user asks to send a prompt to "any available AI"
- Gemini quota is known to be exhausted and a fallback is needed
- The user wants automatic provider failover without manual switching
- Running batch prompts where individual provider reliability matters
- The user wants to upload an image to an AI chat (use
--image-path flag)
Do NOT use for: interactive conversations that need multi-turn context (each provider has independent session state).
When to use THIS skill:
- Multi-provider with automatic fallback. Use for reliability, batch processing, or when you don't care which AI answers.
- For Gemini-specific Max reasoning depth, use
--from=Gemini to force Gemini first in the chain.
- For image upload: use
--image-path=<path> to paste images into the chat before the prompt.
Fallback Chain (Priority Order)
Gemini → ChatGPT → Claude → Qwen → Kimi → MiniMax → ChatGLM → Doubao → MiMo → DeepSeek
(Pro Extended) (last resort)
First available provider wins. Each step falls through ONLY on confirmed unavailability (quota/auth/model-degraded), never on transient network errors.
Provider Availability Detection
每个 provider 在发送 prompt 前会经过 3 层检查：
| 检查层 | 检测内容 | 失败行为 |
|---|
| L1: 可达性 | 页面能否加载、是否需要登录 | 跳过 → 下一个 provider |
| L2: 可用性 | 输入框是否可编辑、是否被限流 | 跳过 → 下一个 provider |
| L3: 模型质量 | Pro/高级模型是否可用 | Gemini 特有，其他 provider 跳过 |
Gemini 特殊处理
Gemini 是 chain 中唯一要求 Pro Extended Thinking 的 provider。
模型激活分三层降级：
- Pro Extended Thinking（需 Gemini Pro 订阅）— 首选
- Flash 模式（免费 tier 兜底）— Pro Extended 不可用时自动切换
- 两者都失败 →
ERR_MODEL_DEGRADED，降级到 ChatGPT
降级触发条件由各 adapter 的 quotaPatterns 定义（lib/providers/adapters/<name>.js），
是权威来源。SKILL.md 不再维护第二份副本（过去已出现与代码不一致的漂移）。
Prerequisites
pgrep -f || bash scripts/start-chrome-debug.sh
curl -s http://127.0.0.1:9222/json/version | python3 -c
( ~/.claude/skills/AgentChat-OneWeb && npm install)
Invocation
node ~/.claude/skills/AgentChat-OneWeb/index.js "Your prompt"
node ~/.claude/skills/AgentChat-OneWeb/index.js --close "Your prompt"
node ~/.claude/skills/AgentChat-OneWeb/index.js --timeout=600000 "Long prompt..."
echo "Prompt from pipe" | node ~/.claude/skills/AgentChat-OneWeb/index.js
node ~/.claude/skills/AgentChat-OneWeb/index.js --smoke
node ~/.claude/skills/AgentChat-OneWeb/index.js --doctor
node ~/.claude/skills/AgentChat-OneWeb/index.js --from=ChatGPT "prompt"
node ~/.claude/skills/AgentChat-OneWeb/index.js --image-path=./photo.png "描述这张图片"
node ~/.claude/skills/AgentChat-OneWeb/index.js --image-path=a.png --image-path=b.jpg "比较这两张图片"
CLI Flags
| Flag | 说明 |
|---|
--timeout=N | 总超时 (ms)，包含所有 provider 尝试时间，默认 600000 |
--timeout-per-provider=N | 单个 provider 超时 (ms)，默认取 timeout / 2 或 180000 |
--from=NAME | 从指定 provider 开始，跳过链中前面的。NAME 可缩写不区分大小写 |
--single | 只尝试 --from 指定的那一个 provider，失败即返回，不级联到链中后续 provider。给需要自己做跨 provider 降级+加锁的调用方用（如 AgentChat-IndependentTasks），避免子进程内部级联绕开调用方的互斥锁 |
--only=NAME | --from=NAME --single 的合并简写（程序化调用方使用；未知 NAME 会 fail loudly 而非静默回退） |
--locale=xx_XX | 强制 Gemini UI 语言 profile（zh_CN / zh_TW / en / ja），跳过自动检测。Python SDK 的 locale= 参数即透传此 flag |
--smoke | 环境检查：遍历所有 provider 确认至少一个可达 |
--doctor | CDP 端口连通性检查 |
--close / --close-browser | 执行完毕后关闭所有 tab 和浏览器连接（默认保留） |
--image | 图片生成意图：index.js 进程内追加标准生图增强指令并记录 image_prompt_enhanced telemetry（见图片协议 §1） |
--image-path=PATH | 图片上传：读取本地图片文件，粘贴到 AI 聊天对话框后再发送 prompt（可重复使用多次以上传多张图片）。触发条件见图片上传协议 §4 |
--no-download-images | 禁用图片自动下载（默认启用，从响应中提取图片 URL 下载到当前工作目录） |
未识别的 --flag 会打 WARN 日志后忽略（v14 起；此前静默丢弃，是 --locale 空转数月、--keep-tabs 曾被拼进 prompt 这一类 bug 的根源）。--from= / --only= 空值会以 exit 64 硬失败。--only/--single 下 provider 名必须精确匹配 key 或显示名（子串匹配仅在级联路径作为人类便利保留）。
Output & Telemetry
- stdout: 成功时输出 AI 响应原文
- stderr: 诊断日志，
[fallback] 前缀
- telemetry: 写入
~/.claude/skills/AgentChat-OneWeb/data/fallback-telemetry.jsonl
{
"timestamp": "2026-07-01T...",
"provider_used": "ChatGPT",
"providers_tried": ["Gemini"],
"fallback_reasons": {"Gemini": "ERR_RATE_LIMITED"},
"prompt_length_chars": 1500,
"response_length_chars": 3200,
"total_ms": 45000,
"exit_code": 0
}
Exit Codes
| Exit | Code | Meaning |
|---|
| 0 | — | Success — response on stdout |
| 1 | ERR_NO_CDP | Chrome CDP 端口不可达 |
| 2 | ERR_NO_PROVIDER | 所有 provider 不可用 (全部未登录/需认证) |
| 3 | ERR_SAFETY_REJECTED | 当前 provider 安全过滤拒绝 (已尝试所有) |
| 4 | ERR_INTERNAL | 内部错误 (Node 异常、CDP 断开等) |
| 5 | ERR_RATE_LIMITED | 所有 provider 均被限流 |
| 9 | ERR_ALL_EXHAUSTED | 遍历了全部 provider，全部不可用 |
| 10 | ERR_TIMEOUT | 总超时，无完整响应 |
| 64 | EX_USAGE | 用法错误（空 prompt / --from=、--only= 空值）。v14 前误用 exit 1，与 ERR_NO_CDP 冲突，会让编排方把调用方 bug 当成"浏览器挂了"终止整条链。用法错误同样产生 receipt |
Architecture
index.js
├── main() — CLI 入口，解析参数
├── tryAllProviders() — 按链遍历 provider，返回第一个成功
├── RUNNERS (factory-built) — 9 provider runners via createProviderRunner()
│ ├── gemini — config: lib/providers/adapters/gemini.js
│ ├── chatgpt — config: lib/providers/adapters/chatgpt.js
│ ├── claude — config: lib/providers/adapters/claude.js
│ ├── qwen — config: lib/providers/adapters/qwen.js
│ ├── kimi — config: lib/providers/adapters/kimi.js
│ ├── minimax — config: lib/providers/adapters/minimax.js
│ ├── doubao — config: lib/providers/adapters/doubao.js
│ ├── mimo — config: lib/providers/adapters/mimo.js
│ └── deepseek — config: lib/providers/adapters/deepseek.js
├── helpers/
│ ├── isProviderTabOpen() — tab dedup (shared with smokeTest)
│ ├── log() / startTimer() — 终端输出 (lib/terminal.js)
│ └── connectWithRetry() — CDP 连接 + 重试 (lib/cdp.js)
└── constants/
└── PROVIDER_CHAIN — 优先级顺序 + URL
核心设计决策
- One page per invocation — 每次调用创建独立 tab，默认保留浏览器不关闭（
--close 可启用自动清理）。
- New tab per provider — 每个 provider 尝试使用独立 tab（通过
context.newPage()）。
失败后关闭当前 tab，为下一个 provider 创建新 tab。
- Quota detection via DOM — 不依赖 HTTP 状态码，而是检查页面 DOM 内容判断是否被限流。
- No cross-provider context — 不对不同 provider 之间传递上下文。每次都是独立的 prompt。
- Pro Extended mandatory for Gemini — Gemini 必须激活 Pro Extended 才使用，否则直接降级。
Provider-Specific Implementation Notes
每个 provider 的特殊行为定义在 lib/providers/adapters/<name>.js 中（配置驱动，非硬编码），SKILL.md 仅保留关键差异供 AI 调用参考：
| Provider | 关键差异 | 详见 |
|---|
| Gemini | Pro Extended 强制激活、bursty 输出检测、120s stop-btn 延长、Action Toolbar 完成锚点 | adapters/gemini.js |
| ChatGPT | 3 层输入策略 (clipboard→simulated paste→chunked keyboard)、React 发送按钮状态验证 | adapters/chatgpt.js |
| Claude | ProseMirror 编辑器、"Thinking" 占位符过滤、嵌入搜索块剥离 | adapters/claude.js |
| Qwen | React SPA 3s 延迟、stop-btn detached 模式、模型名前缀剥离 | adapters/qwen.js |
| Kimi | 每次调用新建会话、send-button-container disabled 检测、自适应稳定性窗口 (5-30s) | adapters/kimi.js |
| MiniMax | TipTap/ProseMirror 异步挂载 4s 延迟、<div aria-label="发送消息"> 非 button 发送 | adapters/minimax.js |
| ChatGLM | 智谱清言 React SPA、中文 UI、agentic 工具/搜索阶段 stillWorkingCheck | adapters/chatglm.js |
| Doubao | 字节跳动 React SPA、CSS Modules 哈希类名、agentic 工具/搜索阶段 stillWorkingCheck | adapters/doubao.js |
| MiMo | React SPA 4s 延迟、DOM 遍历定位发送按钮 (无可靠 CSS selector) | adapters/mimo.js |
| DeepSeek | 标准管线、ds-markdown 响应 | adapters/deepseek.js |
Adding a New Provider
- 创建
lib/providers/adapters/<name>.js 导出 config 对象（参考现有 adapter）
- 在
PROVIDER_CHAIN 数组中添加 entry
- 在
PROVIDER_KEYS 数组中添加 key（自动注册到 RUNNERS）
- Config 的关键字段:
url, authDomains, editorSelectors, sendSelectors/sendFallback, responseSelectors
- 函数返回
{success: true, response: string} 或 {success: false, reason: string}
reason 必须是: "quota" | "auth" | "error" | "timeout"
Code Location
index.js — CLI 入口 + fallback 编排器lib/providerFactory.js — 10-step config-driven pipeline (所有 8 个 provider 共享)lib/providers/adapters/<name>.js — 各 provider 差异配置lib/providers/chain.js — 优先级顺序 (与 IndependentTasks 共享的单一真相源)SKILL.md — AI-facing operational guidepackage.json — npm metadata (playwright-core)
