Skip to content

project.md

Latest commit

 

History

History
139 lines (103 loc) · 7.82 KB

project.md

File metadata and controls

139 lines (103 loc) · 7.82 KB
Raw

ACF 项目上下文

项目名称

ACF — Agentic Crawler Framework（智能体爬虫框架）

项目愿景

构建一个 Agentic AI 驱动的电商数据采集系统，核心理念为：

把"爬虫工程师"产品化 —— 让 AI Agent 承担探索、蒸馏、自愈职责，让 Playwright 脚本承担高频稳定运行职责。

三态运行模型：

  1. 首次探索：Agent（Pi）对话式探索目标站点，人在环辅助验证码等复杂场景，产出 Playwright 脚本
  2. 稳定运行：纯 Playwright 脚本批量执行，不依赖 LLM，低成本高效率
  3. 故障自愈：脚本失败时，Agent 读取证据包（trace/截图/DOM），定位根因并修复脚本

技术栈

统一使用 TypeScript / Node.js 全栈。Playwright 和 Pi 均为 TypeScript 原生开发，同语言消除跨进程通信层，显著降低架构复杂度。

层级 技术 说明
编程语言 TypeScript 5.x + Node.js 22 LTS 全栈统一语言
浏览器自动化 Playwright (Node.js) 脚本执行层，官方主力版本
Agent 框架 Pi (pi-mono) @mariozechner/pi-coding-agent SDK 集成（含内置编码工具 + Extension 系统）
LLM 提供商 Anthropic / OpenAI / Google 通过 Pi 的 @mariozechner/pi-ai 统一接入
数据库 PostgreSQL + Drizzle ORM 脚本版本、会话、任务元数据
任务队列 BullMQ (Redis) 定时调度、分布式执行、重试策略
配置管理 YAML + Zod 类型安全的配置校验
代码质量 Biome (lint + format) + tsc 统一检查与格式化
包管理 pnpm monorepo 友好的包管理器
运行时校验 Zod / TypeBox Schema 定义与运行时校验
终端 UI @mariozechner/pi-tui Pi 的 TUI 库，用于 CLI 交互和 HITL

Pi 框架在 ACF 中的角色

Pi（badlogic/pi-mono）是一套 TypeScript AI Agent 工具链，核心包括：

  • @mariozechner/pi-ai：统一多 LLM 提供商 API，支持工具调用、流式输出、跨模型切换
  • @mariozechner/pi-agent-core：有状态的 Agent 运行时，支持工具执行、事件流、会话管理
  • @mariozechner/pi-coding-agent：交互式编码 Agent CLI/SDK，内置 7 个文件操作工具 + Extension 扩展系统
  • @mariozechner/pi-tui：终端 UI 库，提供 Component 模型、Editor、Select List 等 UI 原语

Pi SDK 集成方式（关键！）

ACF 使用 @mariozechner/pi-coding-agent SDK（而非低层 pi-agent-core）集成 Pi，核心 API 为 createAgentSession()。这一决策基于对 Pi 源码的深度调研：

  1. 内置 codingTools（read/write/edit/bash/grep/find/ls）——Healer/Distiller 修改脚本无需重建文件操作能力
  2. Extension 系统——ACF 通过 pi.registerTool() 注册浏览器操作工具（navigate/screenshot/click 等），与内置工具无缝共存
  3. Extension 事件钩子——通过 pi.on() 拦截危险操作、记录 ActionLog、注入额外上下文
  4. SessionManager——支持持久化会话（.create()）和内存会话（.inMemory()），Explorer 长对话可恢复
  5. DefaultResourceLoader——覆写 system prompt、注入 ACF Extension
  6. Extension UI API——ctx.ui.confirm()/ctx.ui.input() 实现 HITL 人工介入交互
  7. InteractiveMode——开发调试阶段的 TUI 交互界面

ACF 的三大 Agent 模块使用差异：

  • Explorer：codingTools + 浏览器工具 Extension + SessionManager.create()（持久化）+ thinkingLevel: "medium"
  • Distiller：codingTools + 蒸馏工具 Extension + SessionManager.inMemory()（一次性）+ thinkingLevel: "high"
  • Healer：codingTools + grep/find + 自愈工具 Extension + SessionManager.create()（可恢复）+ thinkingLevel: "high"

重要：Pi 处于活跃开发期（截至 2026-02-11 为 v0.52.9），应将其视为可升级依赖，锁定版本号并定期评估升级。

项目约定

代码风格

  • TypeScript：使用 Biome 统一 lint + format
  • 类名 PascalCase，函数/变量 camelCase，常量 UPPER_SNAKE_CASE
  • 文件名 kebab-case（如 crawler-spec.ts）
  • 所有公共 API 必须有 JSDoc 注释
  • 使用 ES Module（import/export），不使用 CommonJS
  • 严格模式 "strict": true

架构模式

  • Monorepo：使用 pnpm workspace 组织，各模块为独立 package
  • 模块化：7 个核心模块（Studio / Explorer / Distiller / Runner / Validator / Healer / Registry），每个模块独立 package
  • Policy 插件化：反爬对抗能力（代理、指纹、行为、会话）封装为可插拔 Policy，不硬编码在脚本中
  • 证据驱动自愈：FailureBundle（trace.zip + 截图 + 状态 + 报告）是自愈的唯一输入
  • 回归门禁：脚本修复必须通过回归测试才允许发布
  • 配置即代码：CrawlerSpec（任务定义）使用 YAML + Zod 校验

测试策略

  • 单元测试：vitest，覆盖核心业务逻辑（蒸馏器、校验器、策略引擎）
  • 集成测试：Playwright 脚本的回归测试，使用 mock 站点或快照
  • 端到端测试：完整的 Explorer → Distiller → Runner → Validator 流程
  • 测试文件命名 *.test.ts，与源码同目录或 __tests__/ 子目录

Git 工作流

  • 主分支 main，功能分支 feat/<change-id>，修复分支 fix/<change-id>
  • 提交信息格式：<type>(<scope>): <简要中文说明> [change-id]
    • type: feat / fix / refactor / docs / test / chore
    • scope: 模块名（studio / explorer / distiller / runner / validator / healer / registry）
  • 一个或一组紧密相关任务对应一次原子提交

领域知识

电商爬虫核心挑战

  1. 反爬/风控：指纹识别、行为分析、TLS 特征、请求图谱
  2. 会话管理：登录态失效、跨域 token、多账号池、会话污染
  3. 验证码：Turnstile / reCAPTCHA / 滑块 / 图形验证
  4. 静默脏数据：页面返回 200 但内容是挑战页或空数据
  5. 改版频繁：DOM 变动、AB 实验、懒加载策略变更

关键术语

术语 含义
CrawlerSpec 任务定义，包含目标 URL、字段 Schema、成功标准、策略集
ScriptPackage 可发布脚本包，含脚本 + 校验器 + 回归用例 + 策略 + 变更日志
FailureBundle 失败证据包，含 trace.zip + 状态快照 + 截图 + 校验报告
ActionLog Explorer 阶段产出的高层动作序列
Policy 可插拔的策略插件（代理/会话/行为/指纹/挑战处理）
Regression Gate 回归门禁，脚本修复后必须通过的测试集
HITL Human-in-the-Loop，需要人工介入的场景（验证码、2FA）

重要约束

  • 合规边界：爬取行为必须在合法授权范围内，CrawlerSpec 中需声明数据用途和授权来源
  • 成本控制：LLM 调用仅在探索/自愈阶段使用，稳定运行阶段纯脚本执行零 LLM 成本
  • Pi 版本管理：Pi 高频发布可能带来 breaking changes，需锁定版本 + 灰度升级
  • Playwright 版本纪律：Playwright 有 breaking changes 历史（如移除 _react/_vue 选择器等），Runner 环境锁定版本，升级走全量回归

外部依赖

依赖 用途 备注
Pi (pi-mono) Agent 框架 @mariozechner/pi-coding-agent SDK 集成（含 pi-ai / pi-agent-core / pi-tui），锁定版本
Playwright 浏览器自动化 Node.js 版本，锁定版本
playwright-extra + stealth plugin 反指纹检测 Playwright 的 stealth 插件
Drizzle ORM 数据库访问 TypeScript 原生 ORM，PostgreSQL
BullMQ 任务队列 基于 Redis 的生产级队列
Zod Schema 校验 CrawlerSpec / FailureBundle 等模型定义
第三方打码平台 API 验证码处理 2Captcha / YesCaptcha 等，按需接入