1. 项目概述：为AI智能体装上“眼睛和手”

如果你正在尝试让AI智能体帮你完成一些网页操作，比如自动处理邮件、在招聘网站投递简历，或者从复杂的后台系统里提取数据，你很可能已经发现了一个残酷的现实：这些在人类看来简单的点击、输入、滚动操作，对AI来说却像在布满陷阱的迷宫里行走。一个看似简单的“点击提交按钮”指令，可能会因为页面使用了动态加载框架、按钮的CSS类名每周一变、或者需要先处理一个弹窗而彻底失败。这正是Hanzi Browse要解决的核心痛点——它不是一个传统的、编写死板脚本的自动化工具，而是一个为大型语言模型（LLM）设计的“上下文增强层”。

简单来说，Hanzi Browse为你的AI智能体（无论是Claude Code、Cursor还是其他）配备了一本针对24个主流网站的“实战操作手册”。这本手册不是替AI做决定，而是告诉它：“嘿，你现在在Gmail页面，记住，按 j 和 k 可以快速在邮件间导航，批量操作按钮在加载后3秒才会出现。” 它让AI具备了理解真实、动态、复杂网页环境的能力，从而真正可靠地完成你交给它的浏览任务。

2. 核心设计思路：从“硬编码”到“智能提示”

2.1 传统自动化工具的困境

在深入Hanzi Browse之前，我们先看看为什么传统的自动化方案（如Selenium、Puppeteer脚本，甚至一些RPA工具）在AI时代显得力不从心。

2.1.1 脆弱的选择器 传统自动化严重依赖CSS选择器、XPath等定位元素。一旦网站前端改版，哪怕只是调整了一个 div 的类名，整个脚本就会崩溃。维护成本极高，尤其是在面对像LinkedIn、X（原Twitter）这类频繁进行A/B测试和UI迭代的网站时。

2.1.2 缺乏环境感知 脚本是线性的、预设的。它无法处理预期之外的状况，比如：“如果登录后出现了双因素认证弹窗怎么办？”、“如果页面加载缓慢，元素还没出现就点击了怎么办？” 你需要编写大量的 try-catch 、 wait 逻辑，让脚本变得异常臃肿。

2.1.3 与LLM的协作断层 当你希望用自然语言指挥AI去浏览网页时，AI本身并不具备上述的“网站特异性知识”。你可能会对AI说：“去LinkedIn上找到所有机器学习工程师的招聘信息。” AI可以理解这个意图，但它不知道LinkedIn的搜索框在哪里、如何过滤职位、如何翻页，更不知道如何避开那些反爬虫机制。结果往往是AI生成了一段根本无法执行的代码，或者尝试操作后卡在某个环节。

2.2 Hanzi Browse的解决方案：Playbook（操作手册）模式

Hanzi Browse的创新在于，它没有试图用更复杂的代码去“硬解”这些问题，而是转换了思路： 将网站特定的、隐性的操作知识，显式地提供给LLM 。

2.2.1 什么是Site Playbook？ 你可以把它想象成游戏攻略。每个Playbook对应一个网站（如 linkedin.com ），里面包含了LLM成功在该网站导航和操作所需的关键信息：

• 页面结构提示 ：例如，“主页的‘动态’信息流位于 main 标签下，但前三条可能是推广内容。”
• 交互模式 ：例如，“Gmail中，使用键盘快捷键 e 来归档邮件比寻找鼠标点击按钮更可靠。”
• 反模式与陷阱 ：例如，“X（Twitter）的‘转发’按钮在动态加载后，其 aria-label 属性才会被正确设置，直接通过文本查找会失败。”
• 等待策略 ：例如，“等待‘加载更多’按钮出现，但点击后需要额外等待2-3秒让新内容完全渲染。”

这些Playbook以结构化的JSON格式存储，在AI智能体访问对应域名时自动加载，成为其决策上下文的一部分。

2.2.2 智能体与执行器的分离架构 Hanzi Browse采用了清晰的架构分离：

1. 规划层（你的主AI智能体） ：负责理解你的自然语言指令，制定高级任务计划（如“登录 -> 搜索 -> 筛选 -> 收集”）。
2. 执行层（Hanzi Browse子智能体） ：接收主智能体的子任务（如“在当前页面点击搜索框”），结合当前页面的Playbook，决定具体的操作指令（点击、输入、滚动），并通过Chrome扩展程序执行。
3. 观察层 ：执行后，自动捕获页面变化（DOM、截图），反馈给执行层，形成“感知-决策-执行”的闭环。

这个架构的精妙之处在于， 决策权始终在LLM手中 。Playbook只是提供了“地图”和“工具使用说明”，LLM根据实时观察决定下一步怎么走。当网站发生微小变化时，具备推理能力的LLM有可能自行调整策略，而无需等待Playbook更新，系统的鲁棒性因此大大增强。

3. 两种核心使用模式详解

Hanzi Browse提供了两种入口，适应不同的用户角色和使用场景，但其底层引擎和Playbook是共享的。

3.1 模式一：作为AI智能体的浏览器子代理（For Your Agent）

这是面向 开发者或高级用户 的模式。你已经在使用Claude Code、Cursor等AI编码助手，现在想赋予它们直接操作浏览器完成任务的能力。

3.1.1 核心组件：MCP（模型上下文协议）集成 MCP是新兴的、允许外部工具与AI智能体安全通信的协议。Hanzi Browse通过 npx hanzi-browse setup 一键式安装，其核心就是将自己注册为AI智能体的一个MCP工具。

安装过程做了以下几件关键事：

• 检测与配置 ：自动扫描你系统上已安装的、支持MCP的AI智能体（如Claude Code, Cursor, Windsurf等）。
• 注入工具 ：将 browser_start , browser_message 等工具函数添加到智能体的“工具箱”中。
• 注入技能 ：将一系列“技能”文档（如 hanzi-browse.md , data-extractor.md ）添加到智能体的知识库。这些技能教会智能体 何时 以及 如何 调用浏览器工具。

3.1.2 工作流示例 假设你在Cursor中聊天框输入：“帮我检查一下我的Gmail，把过去一周所有的推广邮件都退订。”

1. Cursor（主智能体）理解任务后，意识到需要操作浏览器。
2. 它查阅已加载的 hanzi-browse 技能，知道应该调用 browser_start 工具，并生成一个具体的子任务描述：“导航至mail.google.com，登录后，识别并退订过去7天内来自‘promotion’类别的所有邮件。”
3. Hanzi Browse子智能体被唤醒。它首先加载 gmail.com 的Playbook，然后开始执行：
   • 打开Chrome，导航到Gmail。
   • （Playbook提示：Gmail登录后可能重定向，需要检查URL）。
   • 使用键盘快捷键 g 然后 t 快速跳转到“推广”标签页。
   • （Playbook提示：列表是懒加载的，需要滚动到底部触发加载）。
   • 识别每一封邮件的退订链接（Playbook提示：链接通常包含‘unsubscribe’文本，且可能在邮件尾部）。
   • 依次点击退订，并处理可能出现的确认弹窗。
4. 任务完成后，子智能体将结果（如“已成功退订15封推广邮件”）返回给Cursor，Cursor再总结给你。

3.1.3 模式选择：Managed vs. BYOM

• Managed模式（托管模式） ：Hanzi Browse服务端提供AI模型（默认是Gemini）来驱动子智能体。你按任务次数付费（前20次免费，之后$0.05/次）。优势是开箱即用，无需自己拥有或管理AI API密钥。
• BYOM模式（自带模型） ：使用你自己的AI模型（如Claude Pro的API、GPT-4等）。任务完全在本地运行，数据不出你的机器， 永久免费 。这适合注重隐私、已有强大API订阅或需要特定模型能力的用户。

实操心得 ：对于初步尝试和轻量使用，Managed模式非常方便，能快速验证想法。一旦你确定了工作流并希望大规模、私有化地运行，切换到BYOM模式是更经济和安全的选择。安装向导会引导你选择模式。

3.2 模式二：作为产品后端的浏览器自动化服务（For Your Product）

这是面向 软件开发者或创业者 的模式。你想在自己的SaaS产品、内部工具或工作流平台中集成浏览器自动化能力，让 你的用户 能够通过自然语言指挥他们自己的浏览器。

3.2.1 核心价值：用户上下文与免爬虫 传统方案下，如果你想为用户提供“一键下载银行流水”功能，你需要：

1. 让用户提供银行账号密码（安全风险极高）。
2. 在你的服务器上运行一个“无头浏览器”来模拟登录（可能触发风控，且无法处理用户独有的安全验证如手机令牌）。
3. 承担数据安全和法律合规的巨大压力。

Hanzi Browse的API模式提供了颠覆性的思路：

• 执行在用户环境 ：任务在 用户自己的Chrome浏览器 中执行，浏览器处于登录状态，包含所有cookies、本地存储和安全证书。
• 用户授权可控 ：通过一次性的“配对”流程，用户授权你的应用在特定时间段内控制其浏览器的一个标签页。用户随时可以断开。
• 自然语言接口 ：你的后端只需通过API发送一个自然语言任务描述，无需关心具体网站的操作逻辑。

3.2.2 集成步骤详解

// 1. 初始化SDK客户端
import { HanziClient } from '@hanzi-browse/sdk';
const client = new HanziClient({ apiKey: '你的API_KEY' });

// 2. 为用户创建配对令牌
async function setupUserSession(userId) {
  const { pairingToken } = await client.createPairingToken();
  // 将这个配对链接发送给用户前端
  const pairingUrl = `https://api.hanzilla.co/pair/${pairingToken}`;
  // 用户点击链接，其浏览器会安装扩展（如果未安装）并完成配对
  return pairingUrl;
}

// 3. 查询已配对的浏览器会话
async function getUserSessions(userId) {
  const sessions = await client.listSessions();
  // 通常一个用户对应一个session，你可以将session.id与你的用户ID关联存储
  return sessions;
}

// 4. 向已配对的用户浏览器发送任务
async function runBankStatementTask(userSessionId) {
  const result = await client.runTask({
    browserSessionId: userSessionId,
    task: '登录我的网银，进入交易明细页面，选择上月日期范围，下载PDF格式的流水单，并将文件保存到默认下载位置。',
    // 你可以附加更多上下文，比如账户昵称（如果用户在你产品中设置了）
    // context: { accountNickname: '我的主储蓄卡' }
  });
  
  if (result.status === 'completed') {
    // 任务成功，result.answer可能包含摘要，如“已下载statement_202405.pdf”
    console.log('任务成功:', result.answer);
    // 注意：文件实际下载到了用户的本地，你的服务器并未存储。
    // 你可以让用户在前端确认下载完成，或通过其他方式（如邮箱）发送。
  } else {
    console.error('任务失败:', result.error);
  }
}

3.2.3 典型应用场景

• 金融科技 ：用户连接自己的券商账户，自动下载交易报告用于税务申报。
• 电商管理 ：商家连接自己的Shopify后台，用自然语言生成销售数据周报。
• 人力资源 ：HR让系统自动从多个招聘网站同步候选人申请到ATS（申请人跟踪系统）。
• 个人生产力工具 ：开发一个让用户自动化处理重复性网页工作的个人助手。

注意事项 ：虽然任务在用户浏览器执行，但任务描述和结果（非敏感摘要）会经过Hanzi Browse的服务器（Managed模式）或你指定的AI API（BYOM模式）。在设计产品时，务必向用户清晰说明数据流向，并遵守相关隐私法规（如GDPR）。对于极高敏感操作，BYOM模式是更优选择。

4. Site Playbook的构建与扩展机制

Playbook是Hanzi Browse的“智慧核心”。理解其结构和如何贡献，对于深度使用或定制化至关重要。

4.1 Playbook的JSON结构剖析

Playbook文件（ domain-skills.json ）是一个数组，每个元素对应一个域名或域名模式。其结构设计旨在为LLM提供高信息密度、可操作的上下文。

{
  "domain": "linkedin.com",
  "skill": {
    "description": "LinkedIn是一个职业社交网站，包含个人资料、公司页面、招聘信息和工作申请流程。",
    "known_quirks": [
      "页面大量使用异步JavaScript加载内容。直接查找元素可能失败，需要等待或监听DOM变化。",
      "'连接'按钮的CSS选择器会因A/B测试频繁变化。更可靠的方法是查找包含'Connect'文本的按钮，并检查其祖先元素的特定属性。",
      "消息发送界面有速率限制和反垃圾检测。快速连续发送相同消息会导致账户受限。"
    ],
    "interaction_patterns": [
      {
        "action": "搜索职位",
        "steps_hint": "使用顶部导航栏的'职位'链接或搜索框。搜索后，利用左侧边栏进行筛选（如地点、经验级别）。职位列表为无限滚动。"
      },
      {
        "action": "申请职位（Easy Apply）",
        "steps_hint": "点击'Easy Apply'按钮。表单通常以模态框弹出。提前准备好简历文本和个人信息以进行自动填充。注意每一步都可能需要手动点击'下一步'或'提交'。"
      }
    ],
    "keyboard_shortcuts": {
      "j/k": "在feed中上下移动焦点",
      "enter": "打开焦点所在的项目"
    },
    "selectors": {
      "primary_nav": "nav.global-nav",
      "messaging_input": "div.msg-form__contenteditable[role='textbox']"
    },
    "wait_strategies": {
      "feed_load": "等待包含'feed'或'activity'类名的元素出现，然后额外等待2秒以确保内容渲染完成。"
    }
  }
}

4.1.1 各字段设计意图

• known_quirks ：这是最重要的部分。它直接告诉LLM这个网站的“坑”在哪里，避免其陷入常见的失败模式。这相当于把无数小时的手动调试经验编码了进去。
• interaction_patterns ：提供了常见工作流的高级指引，帮助LLM规划任务步骤，而不是盲目尝试。
• selectors ：提供相对稳定的元素定位参考，但强调其可能变化，引导LLM结合其他策略（如文本内容、ARIA属性）进行定位。
• wait_strategies ：针对该网站特定交互的等待建议，比通用的“等待5秒”更智能、更高效。

4.2 如何为新的网站贡献Playbook

Hanzi Browse的Playbook是开源的，社区贡献是它支持更多网站的关键。

4.2.1 信息收集过程

1. 手动探索 ：亲自在目标网站上完成你想要自动化的任务。用开发者工具（F12）观察网络请求、DOM变化。
2. 识别关键元素 ：记录下按钮、输入框、列表容器的HTML结构、类名、ID、文本内容。特别注意那些通过JS动态添加的元素。
3. 测试稳定性 ：刷新页面，或在隐身模式下访问，观察这些选择器是否稳定。寻找更稳定的定位方式，如 data-testid 属性、ARIA角色、或在DOM树中的相对位置。
4. 总结模式与陷阱 ：在操作过程中，哪里容易出错？是否需要处理弹窗？是否有加载状态？表单提交后有怎样的成功/失败反馈？

4.2.2 编写与提交

1. Fork Hanzi Browse的GitHub仓库。
2. 在 server/src/agent/domain-skills.json 文件中，添加一个新的JSON对象到数组末尾。
3. 遵循现有格式，用英文清晰、简洁地描述。 known_quirks 和 interaction_patterns 是灵魂，务必写详细。
4. 提交Pull Request。项目维护者会审核，并可能用实际的AI智能体进行测试。

实操心得 ：编写一个高质量的Playbook，与其说是编程，不如说是“传授经验”。你需要像一位老师一样，预判一个聪明的但对该网站陌生的“学生”（LLM）可能犯的所有错误，并提前给出提示。一个好的Playbook能显著降低任务的失败率。

5. 开发环境搭建与深度调试指南

虽然 npx hanzi-browse setup 为终端用户提供了极简体验，但作为开发者，理解其本地运行和开发机制能帮助你进行定制、调试或贡献代码。

5.1 本地开发环境全流程解析

5.1.1 前置条件检查 确保你的环境满足：

• Node.js 18+ ：这是运行服务端和CLI的基础。
• Docker Desktop ：用于运行PostgreSQL数据库。务必在运行 make fresh 前启动Docker。
• Chrome/Chromium浏览器 ：用于加载开发版扩展。

运行 make check-prereqs 可以快速验证环境。

5.1.2 make fresh 背后发生了什么 这条命令是项目的一键初始化脚本，它依次执行：

# 1. 安装所有Node.js依赖 (server, dashboard, extension)
npm install

# 2. 构建所有子项目
npm run build:all
# 这包括用TypeScript编译服务器代码，打包前端仪表盘，构建Chrome扩展包。

# 3. 启动Docker容器运行PostgreSQL
docker-compose up -d postgres
# 数据库配置定义在`docker-compose.yml`中，数据会持久化在本地卷。

# 4. 运行数据库迁移
npm run db:migrate
# 使用Drizzle ORM或类似的工具，创建所有必要的表（用户、API密钥、任务记录、会话等）。

# 5. 启动开发服务器
npm run dev
# 通常这会启动一个基于Nodemon的服务器，监听在localhost:3456，并带有热重载功能。

整个过程大约需要90秒。完成后，一个功能完整的本地Hanzi Browse实例就运行起来了。

5.1.3 加载开发版Chrome扩展

1. 在Chrome地址栏输入 chrome://extensions 。
2. 打开右上角的“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择Hanzi Browse项目根目录（包含 manifest.json 的文件夹）。 此时，扩展图标应出现在浏览器工具栏。开发模式下，扩展会自动连接本地 localhost:3456 的服务器。

5.2 核心组件联调测试

5.2.1 测试MCP/CLI路径（模拟用户场景） 这是验证“智能体集成”是否正常工作的关键。

# 在项目根目录下
node server/dist/cli.js start "访问 https://example.com 并告诉我页面标题"

预期成功流程 ：

1. 命令触发本地API服务器。
2. 服务器通过WebSocket或类似技术与已安装的Chrome扩展通信。
3. 扩展程序打开一个新标签页，导航到example.com。
4. 本地运行的AI子智能体（根据你的模式选择，可能是Managed调用的远端模型，或BYOM调用的本地模型）开始工作：它获取页面内容，解析出标题。
5. 结果通过CLI返回给你。 如果失败，检查：服务器是否在运行？扩展是否已加载并显示“已连接”？Chrome是否允许扩展程序运行？

5.2.2 测试API路径（模拟开发者集成） 这验证了后端服务和SDK的可用性。

# 1. 健康检查
curl http://localhost:3456/v1/health
# 应返回 {"status":"ok"}

# 2. 创建API密钥（需要先配置Google OAuth并登录仪表盘）
# 或者，为了方便开发，可以在数据库种子脚本中预置一个测试密钥。
# 假设你有一个测试API_KEY: `test_key_123`

# 3. 创建配对令牌
curl -X POST http://localhost:3456/v1/browser-sessions/pair \
  -H "Authorization: Bearer test_key_123" \
  -H "Content-Type: application/json"
# 返回 `{ "pairingToken": "tok_abc...", "pairingUrl": "http://localhost:3456/pair/tok_abc..." }`

# 4. 手动在已加载扩展的Chrome中打开上述pairingUrl。扩展会捕获此请求，完成配对。
# 5. 查询会话列表
curl -H "Authorization: Bearer test_key_123" http://localhost:3456/v1/browser-sessions
# 应能看到刚刚配对的会话ID。

# 6. 运行一个测试任务
curl -X POST http://localhost:3456/v1/tasks \
  -H "Authorization: Bearer test_key_123" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "去百度首页，看看搜索框里默认的placeholder文本是什么？",
    "browser_session_id": "你的会话ID"
  }'
# 返回任务ID，用于查询结果。

通过这个流程，你可以完整地走通从授权到执行的数据流。

避坑指南 ：本地开发最常见的两个问题是 端口冲突 （3456被占用）和 Chrome扩展连接失败 。对于端口冲突，使用 make stop 停止服务，或 lsof -i :3456 查找占用进程。对于扩展连接问题，检查扩展的弹出窗口（点击图标）是否显示“Connected to local server”，并查看Chrome开发者工具中“Service Worker”控制台是否有错误。

6. 实战案例与高级技巧

6.1 案例：构建一个LinkedIn潜在客户挖掘工具

假设我们想利用Hanzi Browse的API模式，构建一个帮助销售团队自动发送个性化LinkedIn连接请求的工具。

6.1.1 产品设计思路 我们不存储用户的LinkedIn密码，也不在我们的服务器上模拟登录。而是：

1. 用户在我们的SaaS平台点击“连接LinkedIn”。
2. 后端调用Hanzi Browse API生成一个配对链接，引导用户完成一次性浏览器授权。
3. 用户此后可以在我们平台输入目标公司、职位等条件。
4. 我们向用户已配对的浏览器发送任务：“在LinkedIn上搜索[某公司]的[某职位]，打开前10个人的资料，根据他们的个人简介草拟一段个性化的连接请求，并发送。”
5. 任务在用户自己的、已登录LinkedIn的浏览器中执行。

6.1.2 技术实现要点

// 伪代码示例
class LinkedInProspector {
  constructor(hanziClient) {
    this.client = hanziClient;
  }

  async findAndConnect(userSessionId, company, title, personalNoteTemplate) {
    const taskDescription = `
      任务：在LinkedIn上寻找并连接潜在客户。
      具体步骤：
      1. 确保当前在LinkedIn首页。
      2. 在顶部的搜索栏中，使用“人员”过滤器，搜索公司为“${company}”，职位头衔包含“${title}”的人。
      3. 浏览搜索结果列表，依次打开前10个符合条件的人的个人资料页面。
      4. 对每个人，执行以下子任务：
        a. 阅读其“关于”部分和最近的工作经历。
        b. 基于以下模板，生成一段个性化的连接请求信息。模板：“${personalNoteTemplate}”。请用从个人资料中提取的具体信息（如共同技能、项目、公司）替换[具体内容]部分。
        c. 点击“连接”按钮。
        d. 在弹窗中，选择“添加备注”，并填入上一步生成的个性化信息。
        e. 点击“发送”。
      5. 每发送一个请求后，等待3-5秒再处理下一个，以避免触发LinkedIn的速率限制。
      6. 任务完成后，汇总已发送连接请求的人员名单。
    `;

    const result = await this.client.runTask({
      browserSessionId: userSessionId,
      task: taskDescription,
      // 可以设置超时，因为LinkedIn操作可能较慢
      timeoutMs: 600000 // 10分钟
    });

    return result;
  }
}

6.1.3 注意事项与伦理考量

• 速率限制 ：必须严格遵守Playbook中关于等待时间的提示，模拟人类操作速度，避免账号被限制。
• 信息质量 ：个性化模板需要精心设计，避免生成垃圾信息。AI草拟的信息必须经过用户确认或有一套审核规则。
• 用户知情与控制 ：必须明确告知用户该工具将代表他们在LinkedIn上执行哪些操作，并提供随时停止任务的选项。
• 合规性 ：确保符合LinkedIn的用户协议以及各地的反垃圾邮件法规。

6.2 高级技巧：优化任务指令与上下文

要让Hanzi Browse发挥最大效能，编写好的任务指令（ task ）是一门艺术。

6.2.1 指令的清晰度与约束

• 差 ：“整理我的邮箱。”
• 好 ：“登录我的Gmail（账号已保存），进入‘收件箱’，找到所有来自‘newsletter@example.com’且标题包含‘促销’的未读邮件，将它们移动到名为‘Newsletters’的标签中，然后标记为已读。”

好的指令明确了：1) 目标网站；2) 初始状态假设；3) 具体的筛选条件；4) 要执行的具体操作序列。

6.2.2 提供额外上下文 runTask 方法允许传递 context 参数。你可以利用它提供静态的、任务相关的信息，减少对AI的模糊要求。

await client.runTask({
  browserSessionId: sessionId,
  task: '为我申请这个职位。',
  context: {
    resumeText: '...我的简历纯文本...',
    personalInfo: {
      name: '张三',
      phone: '+86 13800138000',
      email: 'zhangsan@email.com'
    }
  }
});

这样，当AI需要填写申请表时，可以直接引用 context 中的信息，而无需再向你索要或进行猜测。

6.2.3 处理多步骤与状态管理 对于非常长的任务（如申请20个职位），可以考虑将其分解为多个子任务，并利用 browser_message 进行交互。

// 第一步：搜索并列出职位
const listResult = await client.runTask({
  browserSessionId: sessionId,
  task: '在LinkedIn上搜索“远程 前端开发”职位，将前5个职位的标题、公司名称和申请链接提取出来，以JSON格式返回给我。'
});

const jobs = JSON.parse(listResult.answer);

// 第二步：循环申请每个职位
for (const job of jobs) {
  const applyResult = await client.runTask({
    browserSessionId: sessionId,
    task: `请访问 ${job.applyLink} 并尝试申请“${job.title}”职位。使用我之前提供的简历和个人信息。如果遇到需要额外回答的问题，请根据职位描述合理填写。`
  });
  // 处理每个申请的结果...
}

这种方式更灵活，允许你在每个步骤后检查结果并决定是否继续，也便于错误处理和重试。

7. 常见问题排查与性能优化

7.1 问题排查清单

问题现象	可能原因	排查步骤
npx hanzi-browse setup 失败或卡住	1. 网络问题（无法访问Chrome商店或npm）。 2. 未检测到兼容的AI智能体。 3. 权限不足（无法写入智能体配置目录）。	1. 检查网络连接，尝试科学上网环境。 2. 确认已安装Claude Code、Cursor等并已启动至少一次。 3. 尝试在管理员/root权限下运行，或手动检查 ~/.cursor/mcp.json 等配置路径。
任务执行失败，AI无法找到元素	1. 目标网站的Playbook缺失或过时。 2. 页面加载状态异常（如网络错误、需要登录）。 3. 任务指令过于模糊。	1. 检查Hanzi Browse是否支持该网站。不支持则需等待或贡献Playbook。 2. 手动访问目标页面，确认能正常加载且处于预期状态。 3. 细化任务指令，明确网站、页面和操作目标。
任务超时	1. 网站响应慢或操作步骤多。 2. AI模型“思考”时间过长。 3. 陷入重试循环（如始终找不到元素）。	1. 增加 timeoutMs 参数。 2. 对于BYOM模式，尝试更换更快或更擅长规划的模型（如GPT-4 Turbo）。 3. 查看任务日志（如果提供），确认卡在哪一步。考虑将大任务拆分成小任务。
Chrome扩展显示“未连接”	1. 本地开发服务器未运行。 2. 扩展版本与服务器API版本不兼容。 3. 浏览器安全策略阻止了本地连接。	1. 运行 make dev 确保服务器在 localhost:3456 运行。 2. 确保扩展是从当前代码库加载的开发版，而非商店版。 3. 尝试在Chrome中访问 http://localhost:3456/v1/health ，确认服务可达。
API调用返回认证错误	1. API密钥无效或已过期。 2. 请求头格式错误。 3. 尝试访问未授权的资源。	1. 在仪表盘重新生成API密钥。 2. 确认请求头为 Authorization: Bearer <your_api_key> 。 3. 确认 browser_session_id 属于当前API密钥所属的工作区。

7.2 性能与成本优化建议

7.2.1 对于Managed模式用户（按任务付费）

• 任务设计精细化 ：将一个大任务（如“整理我所有的书签”）拆分成多个明确的小任务，反而可能更便宜、更可靠。因为大任务失败重试的成本更高。
• 利用免费额度 ：20个免费任务/月可用于测试和原型验证。在投入生产前，充分测试不同网站和指令的稳定性。
• 监控与告警 ：集成时，对任务失败率进行监控。失败任务不收费，但高频失败可能意味着指令或Playbook需要调整。

7.2.2 对于BYOM模式用户（使用自有API）

• 模型选择 ：任务执行涉及大量的上下文（网页HTML）和多次的“思考-行动”循环，对模型的上下文长度和推理能力要求高。Claude 3.5 Sonnet或GPT-4是可靠选择，但成本也高。对于简单、模式固定的任务，可以尝试成本更低的模型（如Claude Haiku），并通过更精确的Playbook来弥补模型能力的不足。
• 上下文管理 ：Hanzi Browse会向模型发送页面HTML。对于非常大的页面，这可能导致令牌数激增。未来版本可能会引入智能截断或摘要功能。目前，可以通过指令让AI优先关注页面的特定区域（如“只看 #main-content 这个div里的内容”）。
• 缓存策略 ：如果你的应用频繁对同一网站执行类似任务（例如，每天从同一仪表盘抓取数据），可以考虑在AI调用层之前，增加一个结果缓存层。对于完全相同的页面和指令，直接返回缓存结果。

7.2.3 通用优化

• 错误处理与重试 ：在SDK调用层实现指数退避的重试机制，特别是对于网络超时或网站临时性错误（如429 Too Many Requests）。
• 会话复用 ：一个配对的浏览器会话可以执行多个连续任务。保持会话活跃，避免为每个任务都重新配对和打开新浏览器窗口，可以节省大量初始化时间。
• 异步处理 ：对于可能长时间运行的任务，不要同步阻塞等待。使用 client.runTask 返回的 taskId ，然后通过Webhook或轮询 client.getTaskStatus 来获取结果，构建异步任务队列。

Hanzi Browse代表了一种新的范式：不是用自动化取代人类，也不是用AI生成脆弱的脚本，而是让AI成为人类在数字世界中的“超级执行伙伴”。它通过将深度的、领域特定的知识（Playbook）与强大的通用推理能力（LLM）相结合，正在让“用自然语言操作一切软件”这个愿景变得触手可及。无论是作为提升个人效率的神器，还是作为构建下一代人机交互产品的基石，它都提供了一个极具潜力的起点。