外部 AI 集成技能

该技能提供了一系列模式，用于将外部 AI 模型作为工具按需调用。它扩展了现有的浏览器自动化与 API 集成技能，使助手能够：

• 自动化交互：通过 Chrome Relay（浏览器自动化）与 ChatGPT、Claude、Gemini 或其他基于 Web 的大语言模型（LLM）交互。
• 调用 Hugging Face 推理 API：对接托管在 Hugging Face Spaces 上的模型（如文本生成、摘要、翻译等任务）。
• 将外部推理能力整合进助手自身工作流：例如，向 ChatGPT 请求第二意见、使用 Claude 进行深度分析，或借助 Hugging Face 完成特定领域任务。
• 避免启动孤立的子代理：将外部模型视为工具而非独立代理，从而确保控制权与上下文始终保留在主助手会话中。

适用场景

• 你需要额外的推理能力、不同模型的视角，或你的主模型所不具备的专业化能力（例如代码生成、翻译）。
• 该任务受益于第二意见或并行评估（例如代码审查、策略分析）。
• 你希望使用具备更大上下文窗口、更强编程能力或特定领域知识的模型（如 Claude、ChatGPT、Hugging Face 模型）。
• 你被明确要求“通过浏览器集成外部 AI”或“将 ChatGPT/Claude 作为工具使用”。
• 你需要调用 Hugging Face 推理 API 来运行某个特定模型（例如摘要、情感分析），并将结果整合进最终响应中。

核心模式

1. 基于浏览器自动化（Chrome Relay）调用 Web 端 LLM

使用 Chrome Relay 自动化访问 ChatGPT、Claude、Gemini 或任何需要浏览器界面的 Web 端 LLM。

前提条件：

• 已安装 Chrome Relay 扩展，并已连接一个标签页（用户需点击 OpenClaw Browser Relay 工具栏图标）。
• 目标 LLM 网站（例如 chatgpt.com、claude.ai）已完成登录（存在有效会话 Cookie）。
• 熟悉浏览器自动化操作手册（memory/patterns/playbooks.md 中的 “Browser Automation (Chrome Relay)”）。

操作步骤：

1. 连接至 Chrome Relay 配置文件（指定 profile="chrome"）。
2. 导航至目标 LLM 页面（或复用已打开的标签页）。
3. 执行快照以定位输入框与发送按钮（建议使用 refs="aria" 获取稳定 DOM 引用）。
4. 向输入框输入提示词并提交（点击发送按钮或按 Enter 键）。
5. 等待响应返回（轮询新元素、检测打字指示器，或设置固定超时）。
6. 从对应 DOM 元素中提取响应文本。
7. 将响应返回给助手工作流。

示例工作流：

# 此为概念性示例；实际实现使用浏览器工具调用。
def ask_chatgpt(prompt):
    # 1. 确保 Chrome Relay 已连接
    browser(action="open", profile="chrome", targetUrl="https://chatgpt.com")
    # 2. 执行快照以获取引用
    snap = browser(action="snapshot", refs="aria")
    # 3. 查找输入框（aria role="textbox"）和发送按钮
    input_ref = snap.find_element(role="textbox", name="Message")
    send_ref = snap.find_element(role="button", name="Send")
    # 4. 输入提示词并点击发送
    browser(action="act", request={"kind":"type", "ref":input_ref, "text":prompt})
    browser(action="act", request={"kind":"click", "ref":send_ref})
    # 5. 等待响应（简化处理）
    time.sleep(10)
    # 6. 再次执行快照，从最后一条消息气泡中提取响应
    snap2 = browser(action="snapshot", refs="aria")
    response_element = snap2.find_last_message()
    return response_element.text

关键注意事项：

• 会话持久性：已连接的标签页必须保持登录状态；避免触发登出的操作。
• 速率限制：注意目标 LLM 的调用频率限制及服务条款。
• 错误处理：识别验证码、“网络错误”提示或“请重试”按钮，并优雅降级。
• 多轮对话支持：通过复用同一标签页且不刷新页面来维持对话上下文。

2. Hugging Face 推理 API 集成

对于托管在 Hugging Face Spaces 或 Hugging Face 推理 API 上的模型，可直接通过 HTTP 请求调用。

前提条件：

• Hugging Face API Token（存储于 1Password 或环境变量中）。
• 模型标识符（例如 "gpt2"、"google/flan-t5-large"、"microsoft/DialoGPT-medium"）。
• 了解该模型预期的输入/输出格式。

操作步骤：

1. 获取 API Token（使用 1Password 技能或读取 ~/.huggingface/token）。
2. 构造请求（URL、Headers、JSON 负载）。
3. 发送请求：使用 curl 或 exec 调用 Python requests 模块。
4. 解析响应并提取生成的文本。
5. 错误处理（如速率限制、模型加载失败、Token 无效等）。

示例脚本（使用 curl）：

#!/bin/bash
set -e

MODEL="google/flan-t5-large"
PROMPT="Translate English to German: How are you?"
API_TOKEN=$(op read "op://Personal/HuggingFace/api_token")

curl -s "https://api-inference.huggingface.co/models/$MODEL" 
  -H "Authorization: Bearer $API_TOKEN" 
  -H "Content-Type: application/json" 
  -d "{"inputs": "$PROMPT"}" | jq -r '.[0].generated_text'

示例 Python 函数（使用 requests）：

import requests
import os

def hf_inference(model, inputs, parameters=None):
    api_token = os.getenv("HF_TOKEN")  # 或通过 1Password 获取
    url = f"https://api-inference.huggingface.co/models/{model}"
    headers = {"Authorization": f"Bearer {api_token}"}
    payload = {"inputs": inputs}
    if parameters:
        payload.update(parameters)
    resp = requests.post(url, headers=headers, json=payload)
    resp.raise_for_status()
    return resp.json()

关键注意事项：

• 成本：推理 API 可能产生费用，请监控用量。
• 模型就绪状态：部分模型需预热加载；可在参数中加入 {"options":{"wait_for_model":true}}。
• 输出格式：不同模型返回结构各异；首次调用前应先测试确认格式。

3. 将外部 AI 编排为工具

不启动子代理，而是在助手自身的推理流程中直接调用外部 AI。

模式：

1. 判断需求：确定适合的外部模型（如创意类任务用 ChatGPT，分析类任务用 Claude，专业任务用 Hugging Face 模型）。
2. 准备提示词：包含清晰指令、必要上下文及期望输出格式。
3. 调用工具：对 Web 端 LLM 使用浏览器自动化，对 Hugging Face 模型使用 API 调用。
4. 整合结果：解析、校验并将外部响应融入自身答案中。
5. 备用方案：若外部调用失败，则继续使用自身推理能力，或尝试替代方案。

示例决策逻辑：

def external_ai_assist(task_type, prompt):
    if task_type == "code_review":
        # 通过浏览器自动化调用 Claude
        return ask_claude(prompt)
    elif task_type == "translation":
        # 使用 Hugging Face 翻译模型
        return hf_inference("Helsinki-NLP/opus-mt-en-de", prompt)
    elif task_type == "creative_writing":
        # 通过浏览器自动化调用 ChatGPT
        return ask_chatgpt(prompt)
    else:
        raise ValueError(f"未为 {task_type} 配置外部 AI")

4. 面向外部模型的提示工程

外部模型所需的提示风格可能与其原生模型不同。

• ChatGPT / Claude：采用对话式风格、系统提示（system prompt）及 Markdown 格式化。
• Hugging Face 模型：遵循模型预期的输入格式（例如 T5 模型需使用 "Translate English to German: ..."）。
• 包含上下文：在提示中提供必要的背景信息、约束条件与示例。
• 明确输出格式：要求返回 JSON、项目符号列表、代码块等结构化内容。

代码审查提示示例：

You are an expert software engineer reviewing the following code snippet. Please:
1. Identify potential bugs or security issues.
2. Suggest performance improvements.
3. Comment on code style and readability.
4. Output your review as a JSON with keys "bugs", "performance", "style".

Code:
```python
def calculate_average(numbers):
    total = 0
    for n in numbers:
        total += n
    return total / len(numbers)
```

5. 错误处理与备用方案

外部服务可能失败；需设计优雅降级策略。

• 浏览器自动化失败：如出现验证码、要求重新登录、网络错误等。备用方案：改用 Hugging Face API 或跳过外部调用。
• API 失败：如遭遇速率限制、模型未找到、Token 无效等。备用方案：切换至其他模型，或跳过外部步骤。
• 超时：设置合理超时时间（例如浏览器自动化 30 秒，API 调用 10 秒）。备用方案：继续由助手自身完成推理。
• 记录失败：将外部 AI 调用失败事件记录至 memory/YYYY‑MM‑DD.md，并添加标签 external‑ai‑failure，便于后续分析。

示例备用结构：

try:
    response = ask_chatgpt(prompt)
except (BrowserError, TimeoutError) as e:
    log_failure("ChatGPT", e)
    # 切换至 Hugging Face
    response = hf_inference("google/flan-t5-xxl", prompt)
except Exception as e:
    log_failure("All external AI", e)
    response = None

if response:
    integrate(response)
else:
    # 继续由助手自身完成推理
    pass

示例

示例 1：使用 Claude 进行代码审查

场景：助手被要求审查一个复杂的 React 组件。它通过 Chrome Relay 调用 Claude，获取详细的第二意见。

步骤：

1. 助手准备包含组件代码与审查说明的提示词。
2. 调用 ask_claude(prompt)（基于浏览器自动化）。
3. Claude 返回结构化审查结果。
4. 助手将 Claude 的反馈整合进最终回答中。

示例 2：通过 Hugging Face 实现翻译

场景：用户提供一段英文段落，要求翻译为德语。助手调用 Hugging Face 翻译模型。

步骤：

1. 助手构建提示词："Translate English to German: "。
2. 调用 hf_inference("Helsinki-NLP/opus-mt-en-de", prompt)。
3. 解析生成的文本。
4. 将翻译结果返回给用户。

示例 3：使用 ChatGPT 进行创意头脑风暴

场景：用户需要一篇关于 AI 助手的博客文章标题建议。助手调用 ChatGPT 生成 10 个选项。

步骤：

1. 助手导航至 ChatGPT 标签页，输入：“Generate 10 catchy blog post titles about AI assistants”。
2. 等待响应并提取列表。
3. 向用户呈现该列表，并附加自身点评。

示例 4：联合分析（助手 + 外部 AI）

场景：用户请求对某项商业决策进行战略分析。助手先自行完成分析，再向 ChatGPT 提问以识别潜在盲点。

步骤：

1. 助手生成自身分析结论。
2. 助手向 ChatGPT 提问：“以下分析中可能存在哪些盲点？”。
3. 将 ChatGPT 返回的盲点列表整合进最终答案。

反模式

• 过度依赖外部 AI：对简单任务也调用外部模型，会增加延迟与依赖风险。仅在收益明显高于成本与风险时才使用。
• 忽略上下文长度限制：Web 端 LLM 存在上下文容量限制；传递过大上下文可能导致截断或失败。应提前摘要或分块处理。
• 泄露敏感信息：切勿将 API Token、密码或敏感数据粘贴至外部 AI 提示中（尤其 Web 端）。应使用 1Password 管理 Token。
• 盲目信任输出：外部 AI 可能出错、存在偏见或产生幻觉。对关键输出务必人工校验。
• 破坏对话连续性：浏览器自动化过程中若导致登出或丢失标签页，将影响后续调用。应维持会话活跃，并避免破坏性操作。
• 忽视成本因素：Hugging Face 推理 API 可能产生费用；应持续监控用量并设定预算。
• 忽略备用机制：未规划外部 AI 失败情形，将导致助手陷入停滞。必须始终配置备用路径。

相关模式

• 浏览器自动化（Chrome Relay）操作手册：Chrome Relay 自动化的详细步骤。
• Hugging Face 技能：结合 Hugging Face Hub、Spaces 与推理 API 的使用方法，含预算管理。
• 1Password 技能：安全地检索 API Token。
• API 工具集成技能：调用外部 API 的通用模式。
• 错误恢复自动化技能：处理外部服务失败的通用机制。
• 健康监控技能：监控外部服务可用性。

参考资料

• docs/browser-automation.md — Chrome Relay 的安装与命令说明。
• skills/huggingface/SKILL.md — Hugging Face API 使用指南。
• skills/1password/SKILL.md — 密钥安全获取方式。
• memory/patterns/playbooks.md — 浏览器自动化操作手册。
• scripts/external_ai_integration.py — 本技能的核心实现。
• playbooks/external-ai-integration-playbook.md — 外部 AI 编排操作手册。

技能集成

当某项任务可从外部 AI 推理中获益时，请查阅本技能以决定选用哪个模型及如何调用。将验证有效的模式存入 memory/patterns/tools.md。若外部 AI 反复失败且需人工干预配置，请更新 pending.md。

本技能通过将外部 AI 模型纳入助手工具集，显著提升了其自主性——无需启动子代理即可应对更广泛的任务类型，同时全程掌控工作流。