ACF — Agentic Crawler Framework

智能体驱动的电商数据采集框架：Agent 探索生成 → 固化为 Playwright 脚本 → 异常时 Agent 介入自愈

愿景

ACF 将"爬虫工程师"产品化——用 AI Agent 处理探索、蒸馏、自愈等高认知负荷工作，用 Playwright 脚本承担高频低成本的稳定运行。

用户意图 → Studio(对话建模) → Explorer(Agent探索) → Distiller(脚本蒸馏)
    → Registry(版本管理) → Runner(批量执行) → Validator(结果校验)
    → [通过] → 数据输出
    → [失败] → FailureBundle → Healer(Agent自愈) → Registry ↩

核心特性

• 对话式建模：自然语言描述采集需求，Agent 自动生成 CrawlerSpec
• Agent 探索 + 人在环：Pi Agent 驱动浏览器探索，遇到验证码等交由人工一次性处理
• 脚本蒸馏：将探索过程自动提炼为稳健的 Playwright 脚本（语义化 Locator、事件等待、失败分支）
• 零 LLM 成本运行：稳定期纯 Playwright 脚本执行，不调用 LLM
• 证据驱动自愈：失败时自动生成 FailureBundle（trace + 截图 + 状态），Agent 读取证据修复脚本
• 回归门禁：修复后必须通过回归测试才允许发布
• 策略插件化：代理、指纹、行为、会话、挑战处理等能力封装为 Policy 插件

技术栈

全栈 TypeScript，统一语言消除跨进程通信复杂度。

组件	技术
语言	TypeScript 5.x + Node.js 22 LTS
浏览器自动化	Playwright (Node.js)
Agent 框架	Pi (pi-mono) — @mariozechner/pi-coding-agent SDK 集成（含内置编码工具 + Extension 系统）
LLM 接入	通过 Pi 统一 API（Anthropic / OpenAI / Google 等）
终端 UI	@mariozechner/pi-tui — Pi TUI 库（交互式调试 + HITL）
数据库	PostgreSQL + Drizzle ORM
任务队列	BullMQ (Redis)
配置校验	Zod
代码质量	Biome (lint + format)

项目结构

acf/
├── README.md                   # 本文件
├── AGENTS.md                   # AI 助手项目指令
├── package.json                # 根 package（pnpm workspace）
├── pnpm-workspace.yaml
├── tsconfig.base.json          # 共享 TS 配置
├── biome.json                  # 统一 lint/format 配置
│
├── openspec/                   # Spec 驱动开发
│   ├── project.md              # 项目上下文与约定
│   ├── AGENTS.md               # OpenSpec 工作流指令
│   ├── specs/                  # 当前已实现的能力规格
│   └── changes/                # 变更提案
│
├── docs/                       # 项目文档
│   ├── architecture.md         # 整体架构设计
│   ├── module-design.md        # 模块详细设计
│   ├── roadmap.md              # 落地路线图
│   ├── 产品规划和架构.md        # 初始产品规划（参考文档）
│   └── 技术蓝图设计v1.md       # 技术蓝图 v1（参考文档）
│
├── packages/                   # Monorepo 各模块（规划中）
│   ├── core/                   # 共享类型、工具函数、配置定义
│   ├── studio/                 # 对话建模
│   ├── explorer/               # Agent 探索
│   ├── distiller/              # 脚本蒸馏
│   ├── runner/                 # 脚本执行
│   ├── validator/              # 结果校验
│   ├── healer/                 # Agent 自愈
│   ├── registry/               # 资产与版本管理
│   └── policies/               # 策略插件
│
├── scripts/                    # 开发与运维脚本
└── configs/                    # 配置模板

快速开始

项目处于架构规划阶段，代码实现即将开始。

# 克隆项目
git clone <repo-url> acf && cd acf

# 安装依赖
pnpm install

# 安装 Playwright 浏览器
npx playwright install chromium

# 安装 Pi（Agent 框架）
npm install -g @mariozechner/pi-coding-agent

# 设置 LLM API Key
export ANTHROPIC_API_KEY=sk-ant-...

# 构建所有包
pnpm build

# 运行测试
pnpm test

文档导航

文档	内容
架构设计	系统整体架构、模块关系、数据流
模块设计	7 个核心模块 + Policy 层详细设计
落地路线图	P0 → P1 → P2 分阶段实施计划
项目约定	技术栈、代码风格、领域知识

许可证

MIT