init

README.md

@@ -0,0 +1,79 @@
+# xspider 模板爬虫
+
+基于 XML 配置驱动的爬虫执行引擎，可从 Redis 列表中获取模板地址，按流程控制使用 DrissionPage 浏览器执行登录和业务流程，并将抽取的数据存储到 MongoDB。
+
+## 依赖
+
+- Python 3.10+
+- [DrissionPage](https://github.com/g1879/DrissionPage)
+- `redis`, `requests`, `pymongo`, `lxml`, `cssselect`
+
+使用 pip 安装：
+
+```bash
+pip install drissionpage redis requests pymongo lxml cssselect
+```
+
+若需要验证码识别、变量服务等能力，请根据业务另行实现。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `XSPIDER_REDIS_URL` | `redis://localhost:6379/0` | Redis 连接串 |
+| `XSPIDER_REDIS_LIST_KEY` | `xspider:config` | 待处理模板所在的 `list` key |
+| `XSPIDER_REDIS_BLOCK_TIMEOUT` | `30` | `BLPOP` 阻塞秒数 |
+| `XSPIDER_MONGO_URI` | `mongodb://localhost:27017` | MongoDB 连接串 |
+| `XSPIDER_MONGO_DB` | `xspider` | MongoDB 数据库名称 |
+| `XSPIDER_VARIABLE_SERVICE` | `None` | 变量服务接口地址；GET 查询，POST 写入 |
+
+变量服务要求：
+
+- `GET {base}?name=变量名&...` 返回 JSON，包含 `value` 字段。
+- `POST {base}` 提交 JSON `{name, value, ...}`。
+
+## 运行
+
+```bash
+python main.py
+```
+
+程序将持续阻塞等待 Redis 列表推送 XML 模板地址，下载模板并执行流程。
+
+## XML 模板
+
+模板结构参考示例：
+
+```xml
+<site id="example" base="https://example.com">
+  <config enable_proxy="false" rotate_ua="false" retry="3">
+    <header name="Accept-Language" value="zh-CN,zh;q=0.9"/>
+  </config>
+
+  <login url="https://example.com/login" selector="div.dashboard" mode="css">
+    <action type="wait_dom_show" selector="form#login"/>
+    <action type="type" selector="//input[@name='username']" text="${account}" mode="xpath"/>
+    <action type="type" selector="//input[@name='password']" text="${password}" mode="xpath"/>
+    <action type="click" selector="button.submit"/>
+  </login>
+
+  <flows>
+    <flow id="orders" entry="/orders" data_type="sales" unique_keys="custom" columns="order_id">
+      <action type="wait_dom_show" selector="table.data-list"/>
+      <extract record_css="table.data-list tbody tr">
+        <field name="order_id" selector="td:nth-child(1)" mode="css"/>
+        <field name="customer" selector="td:nth-child(2)" mode="css"/>
+      </extract>
+      <paginate selector="button.next" mode="css" max_pages="10"/>
+    </flow>
+  </flows>
+</site>
+```
+
+支持的 `action` 类型见 `xspider/actions/builtin.py`，如需扩展可继承 `BaseAction` 并注册到 `ActionRegistry`。
+
+## 重要说明
+
+- `CaptchaAction` 会自动截图（元素或整页）并调用 `https://captcha.lfei007s.workers.dev`，请求体为 `{image, type}`（image 采用 `data:image/png;base64,...` 形式）。可通过 `captcha_config`（JSON 字符串）自定义 `url`、`headers`、`timeout` 或额外字段。
+- 下载文件监听、复杂的分页场景需要根据目标站点扩展。
+- 为保证可维护性，所有动作执行过程中均进行了简单日志输出并允许扩展变量解析。需要对框架进行二次开发时，可直接扩展 Action、Extractor 以及 Runner。