欢迎来到 ecrawler 项目！这是一个使用 TypeScript 和 Effect 构建的分布式网页爬虫应用。如果你刚刚接触 TypeScript 或相关的生态系统，不要担心，这份文档将帮助你理解项目的基本结构、使用方法以及如何开始开发。
本项目采用 Monorepo（单体仓库）结构，这意味着多个相关的包和应用都存放在这一个代码仓库中。我们使用 Yarn 的 Workspaces 功能来管理它们。
整个项目分为三大类：apps（主要可执行应用）、libs（共享库）和
tools（开发工具）。
这些是项目实际运行的主程序：
apps/cli: 命令行工具 (Command Line Interface)。用于通过命令行执行特定任务，如导入和导出数据（import和export命令）。它使用@effect/cli构建。apps/server: 服务端程序 (Server)。它是爬虫的中央控制系统，负责接收请求、管理数据库 (drizzle-orm+ PostgreSQL)、提供 API（内部包@ecrawler/api），以及调度爬虫任务。apps/worker: 任务工作节点 (Worker)。它是实际执行网页抓取的程序。它从服务端获取任务，执行抓取逻辑提取数据，然后再把结果交回给服务端。apps/worker/implementations: 存放针对不同网站的特定抓取实现逻辑（例如bqgl.cc,qidian等）。
这些是可以被不同的 apps 复用的代码，避免重复编写：
libs/api: 定义了服务端 API 的相关代码（如收集器collector、调度器dispatcher等逻辑或接口约定）。libs/schemas: 定义了项目中流通的统一数据结构模型（如User,Book,Chapter,Task,Result等）。不论是 Server 还是 Worker，都共用这些类型定义来保证数据的一致性。libs/proxy: （如果需要）处理网络代理的相关逻辑代码。
开发和构建时的辅助工具和配置：
tools/database: 包含与数据库相关的配置，例如提供本地测试环境的compose.yaml(Docker Compose 配置)。tools/readme: 用于自动生成 README 文件的脚本。tools/update: 自动更新脚本。- 项目根目录下的一系列配置文件：
package.json: 声明了所有依赖和可用脚本。tsconfig.base.json: TypeScript 的核心配置文件，其他包的tsconfig.json会继承它。
作为新手，你可能会在代码中看到下面这些重要库：
- TypeScript & Node.js 24/tsx: 项目的主要编程语言和运行环境。开发环境使用
tsx快速执行.ts文件。 - Yarn (v4): 用作包管理器和执行脚本。
- Effect (
effect,@effect/*): 这是一个非常强大的 TypeScript 函数式编程生态系统。它被广泛用于整个项目的异步操作、依赖注入、重试、并发控制等核心逻辑。（如果你不熟悉 Effect，可以将其简单类比为增强版的 Promise/async-await 以及错误处理系统，建议查阅 Effect 官方文档）。 - Drizzle ORM
(
drizzle-orm): 用于服务端与数据库 (PostgreSQL) 的交互。允许你用 TypeScript 代码编写类型安全的 SQL 查询。
在开始之前，确保你已经安装了 Node.js 和 Yarn v4。
详细的部署和运行说明请参考 部署与运行指南。
克隆项目后，在根目录下运行：
# 安装所有依赖
yarn install各个主应用都提供了启动脚本：
- 启动 Server:
yarn workspace @ecrawler/server run dev - 启动 Worker:
yarn workspace @ecrawler/worker run dev - 运行 CLI:
yarn workspace @ecrawler/cli run start --help
# 导入任务
yarn workspace @ecrawler/cli run start import \
http://localhost:2333 \
--token your-secret-key \
--input tasks.json
# 导出结果
yarn workspace @ecrawler/cli run start export \
http://localhost:2334 \
--token your-secret-key \
--output results.json💡 提示: 完整的配置说明和运行原理请查看 部署与运行指南
详细的开发指南请参考 文档目录。
假设你需要抓取一个新网站 example.com：
- 进入
apps/worker/implementations/目录。 - 创建一个新的文件夹，比如
example。 - 在新文件夹中初始化你的 TypeScript 项目配置（参考已有的
bqgl.cc或qidian），并实现针对该网站特定的抓取和解析逻辑。 - 应用所使用的数据结构（如书籍信息、章节列表）应当从
libs/schemas中导入，以保证向后传递给 Server 的数据格式规范。
💡 提示: 详细的实现指南请查看 Extractor 实现指南
如果需要增加新的数据表或者字段：
- 在
apps/server/src/database/中的 schema 文件里定义新的结构。 - 同时更新
libs/schemas/中的 TypeScript 模型定义（如果适用）。 - 在项目根目录运行
yarn workspace @ecrawler/server run generate来生成 SQL 迁移文件。 - 运行
yarn workspace @ecrawler/server run migrate将新的修改应用到本地数据库。
根目录的 package.json 内提供了一些快捷指令：
- 格式化代码: 运行
yarn format会利用 Prettier 自动格式化项目下的所有文件。
由于项目重度使用了
Effect 生态，这与传统的 TypeScript 编写方式有很大不同（通常以
Effect.gen(function* () { ... }) 或者管道操作符 pipe
为特征）。如果你对其感到有些陌生，建议先阅读 Effect 的入门教程，理解基础的"管道(Pipeline)"操作，以及如何在其中进行并发 (Queue,
Chunk) 处理和上下文 (Layer) 注入。
- 部署与运行指南 - 新手必读，包含系统架构和运行原理
- 文档目录 - 完整的文档索引和导航
- Extractor 实现指南 - 如何添加新网站支持
- 系统架构设计 - 深入理解系统设计