ZeroToken: Instructions file for Claude Code

ZeroToken 项目开发指南

项目概述

ZeroToken 是一个面向 AI Agent 的浏览器自动化 MCP 引擎，核心目标是：

• 降低 Token 消耗 - 通过轨迹记录与 AI 提示导出，供 Skills 等模块分析
• 详细执行上下文 - 每次操作记录完整状态、截图、模糊点
• 模糊点标记 - 显式标记需 AI/人判断的步骤

核心架构

设计思路

AI Agent (ReAct 模式)
       ↓
   MCP 工具调用 (原子能力)
       ↓
   返回结构化 OperationRecord (含 fuzzy_point)
       ↓
   记录完整 Trajectory
       ↓
   trajectory.to_ai_prompt_format() 导出含模糊点的 AI 提示
       ↓
   Skills 或外部模块进一步处理

模块职责

1. BrowserController (controller.py)

• 职责: 浏览器控制，返回详细的 OperationRecord
• 关键特性:
  • 全局单例模式
  • 每个操作返回完整上下文（页面状态、截图、结果）
  • 自动等待机制
  • 操作历史追踪

# 核心方法
- open(url) → OperationRecord
- click(selector) → OperationRecord
- input(selector, text) → OperationRecord
- get_text(selector) → OperationRecord
- extract_data(schema) → OperationRecord  # AI 节点能力

2. TrajectoryRecorder (trajectory.py)

• 职责: 记录完整的操作轨迹，导出 AI 提示
• 关键特性:
  • 绑定 BrowserController 自动记录
  • 导出 AI 友好的提示格式（含模糊点 [需判断: {reason}]）
  • 轨迹持久化存储

# 核心方法
- start_trajectory(task_id, goal)
- record_operation(record)
- complete_trajectory() → Trajectory
- trajectory.to_ai_prompt_format() → str  # AI 提示格式

数据结构

OperationRecord

{
    "step": int,
    "action": str,
    "params": dict,
    "result": {
        "success": bool,
        "navigated": bool,  # click 专属
        "value": any,  # extract 专属
        ...
    },
    "page_state": {
        "url": str,
        "title": str,
        "timestamp": str
    },
    "screenshot": str,  # base64
    "error": str,
    "fuzzy_point": {  # 可选，需 AI/人判断时存在
        "requires_judgment": bool,
        "reason": str,
        "hint": str
    },
    "timestamp": str
}

Trajectory

{
    "task_id": str,
    "goal": str,
    "start_time": str,
    "end_time": str,
    "operations": List[OperationRecord],
    "metadata": {
        "total_steps": int,
        "successful_steps": int,
        "failed_steps": int
    }
}

开发规范

代码风格

• 使用 async/await 异步编程
• 所有浏览器操作必须等待元素就绪
• 错误处理要返回统一的响应格式
• 操作记录必须包含完整上下文