|
|
@@ -0,0 +1,126 @@
|
|
|
+# long-articles-agentic-supply
|
|
|
+
|
|
|
+Agentic 架构**基础设施供给层**，为上层业务 Agent 系统提供通用能力底座。
|
|
|
+
|
|
|
+不作为独立服务运行，而是作为共享库被业务项目依赖引入。
|
|
|
+
|
|
|
+## 能力全景
|
|
|
+
|
|
|
+| 模块 | 能力 |
|
|
|
+|---|---|
|
|
|
+| 数据库 | MySQL / PostgreSQL / Redis / Milvus 连接池与统一路由（Ports/Adapters） |
|
|
|
+| 任务调度 | XXL-JOB 分布式调度，装饰器注册 + 自动发现 |
|
|
|
+| 可观测性 | 结构化日志 → 阿里云 SLS（asyncio.Queue 非阻塞推送） |
|
|
|
+| Agent 内核 | Agent / Tool / Memory / Orchestrator 抽象契约 |
|
|
|
+| 外部集成 | Apollo 配置中心、飞书 Bot/Sheet、火山引擎 DeepSeek、ODPS |
|
|
|
+| 爬虫 | 微信公众号文章搜索、详情、账号信息、文章列表 |
|
|
|
+
|
|
|
+## 业务管道
|
|
|
+
|
|
|
+4 个阶段串联的数据管道，由 XXL-JOB 定时驱动：
|
|
|
+
|
|
|
+```
|
|
|
+Phase 1 Phase 2 Phase 3 Phase 4
|
|
|
+fetch_demand → demand_search_article → demand_search_account
|
|
|
+──────────────── ────────────────────── ─────────────────────
|
|
|
+ODPS 拉取白名单 队列取搜索词 relation 中提 biz accounts 取 gh_id
|
|
|
+→ PG 查搜索词 → 微信搜索 API → 账号 API → 文章列表 API
|
|
|
+→ 视频解构 → 写入 relation → 写入 accounts → 写入 articles
|
|
|
+→ 入队 MySQL → 拉取详情到 detail → 回填 status → 支持深翻/增量
|
|
|
+```
|
|
|
+
|
|
|
+## 快速开始
|
|
|
+
|
|
|
+```bash
|
|
|
+# 安装
|
|
|
+pip install -e ".[server,dev]"
|
|
|
+
|
|
|
+# 启动
|
|
|
+hypercorn app:app --bind 0.0.0.0:7800 --workers 1
|
|
|
+
|
|
|
+# 测试
|
|
|
+python -m pytest src/handlers/test_hello_world.py -v
|
|
|
+```
|
|
|
+
|
|
|
+## 架构
|
|
|
+
|
|
|
+```
|
|
|
+server Quart/Hypercorn + XXL 端点 应用服务（路由、生命周期）
|
|
|
+handlers @xxl_job 任务入口 薄层，编排 domain service
|
|
|
+domains 领域服务 + 数据模型 业务逻辑（fetch_demand →
|
|
|
+ demand_search_article →
|
|
|
+ demand_search_account）
|
|
|
+core Agent / Tool / Memory / Orchestrator 框架抽象（跨项目复用）
|
|
|
+infra DB / HTTP / 日志 / XXL / 外部服务 基础设施实现
|
|
|
+config pydantic-settings 配置管理（环境变量驱动）
|
|
|
+```
|
|
|
+
|
|
|
+依赖方向：`server → handlers → domains → core/infra → config`，上层可依赖下层，反之不可。
|
|
|
+
|
|
|
+## 目录结构
|
|
|
+
|
|
|
+```
|
|
|
+├── app.py # 应用入口
|
|
|
+├── pyproject.toml
|
|
|
+├── requirements.txt
|
|
|
+├── server.toml # Hypercorn 配置
|
|
|
+├── scripts/ # 工具脚本
|
|
|
+├── docs/ # 文档
|
|
|
+└── src/
|
|
|
+ ├── config/ # GlobalConfig + 子配置
|
|
|
+ │ ├── _global_config.py
|
|
|
+ │ ├── database.py / aliyun.py / apollo.py / odps.py / volcengine.py / xxljob.py
|
|
|
+ ├── infra/
|
|
|
+ │ ├── database/ # MySQL / PG / Redis / Milvus 后端 + DatabaseManager
|
|
|
+ │ ├── observability/ # LogService → 阿里云 SLS
|
|
|
+ │ ├── xxl_jobs/ # XxlJobExecutor + @xxl_job 装饰器
|
|
|
+ │ ├── spider/ # 微信爬虫（gzh.py）
|
|
|
+ │ ├── external/ # Apollo / 飞书 / ODPS / 火山引擎
|
|
|
+ │ └── shared/ # AsyncHttpClient / safe_json_parse / retry
|
|
|
+ ├── core/ # Agent / Tool / Memory / Orchestrator / AppContext
|
|
|
+ ├── domains/
|
|
|
+ │ ├── fetch_demand/ # Phase 1: 需求获取 → 搜索词入队
|
|
|
+ │ ├── demand_search_article/ # Phase 2: 搜索 + 详情
|
|
|
+ │ └── demand_search_account/ # Phase 3-4: 账号 + 文章
|
|
|
+ ├── handlers/ # XXL-JOB Handler（@xxl_job 装饰，自动发现）
|
|
|
+ └── server/ # Quart app 工厂 / XXL 端点
|
|
|
+```
|
|
|
+
|
|
|
+## XXL-JOB 任务
|
|
|
+
|
|
|
+| 处理器 | 阶段 | 说明 | 建议超时 |
|
|
|
+|---|---|---|---|
|
|
|
+| `demandEnqueue` | Phase 1 | ODPS 拉取 → 解构 → MySQL 入队 | ≥300s |
|
|
|
+| `articleSearch` | Phase 1 | 队列取词 → 微信搜索 → relation | ≥1800s |
|
|
|
+| `articleFetchDetail` | Phase 2 | relation 取待拉 → 微信详情 → detail | ≥600s |
|
|
|
+| `accountFetch` | Phase 3 | relation 提 biz → 账号 API → accounts | — |
|
|
|
+| `accountArticleFetch` | Phase 4 | accounts 取 gh_id → 文章列表 → articles | ≥1800s |
|
|
|
+
|
|
|
+## 核心设计模式
|
|
|
+
|
|
|
+- **Ports/Adapters** — DB 抽象契约（`ports.py`），domain 只依赖接口
|
|
|
+- **Mapper/Service 分离** — Mapper 纯 DB I/O，Service 业务逻辑，Handler 薄编排
|
|
|
+- **装饰器注册 + 自动发现** — `@xxl_job` 声明式注册，`discover_and_register()` 扫描导入
|
|
|
+- **工厂函数** — `create_app()` / `create_backend()` 集中组装依赖
|
|
|
+- **门面模式** — `DatabaseManager` 统一多后端生命周期
|
|
|
+
|
|
|
+## 开发指南
|
|
|
+
|
|
|
+### 新增 XXL-JOB Handler
|
|
|
+
|
|
|
+1. 在 `src/domains/` 创建 domain service（Service + Mapper + Const）
|
|
|
+2. 在 `src/handlers/xxx.py` 创建 handler：`set_db(db)` + `@xxl_job("handlerName")`
|
|
|
+3. 在 `src/server/app.py` 中 `import set_db_xxx` 并调用 `set_db_xxx(db)`
|
|
|
+4. 在 XXL-JOB Admin 控制台注册执行器和处理器
|
|
|
+
|
|
|
+Handler 模板见 `src/handlers/article_search.py`。
|
|
|
+
|
|
|
+### 编码原则
|
|
|
+
|
|
|
+- **可读性第一**：代码的第一性原理是让人快速看懂，认知负担是衡量标准
|
|
|
+- **设计模式是手段不是目的**：先问"解决什么真实问题"，再选模式
|
|
|
+- **显式优于隐式**：依赖、数据流、错误处理都走显式路径
|
|
|
+
|
|
|
+## 技术栈
|
|
|
+
|
|
|
+Python 3.11+ · Quart + Hypercorn · aiomysql + asyncpg · Redis + Milvus · pydantic-settings · XXL-JOB · 阿里云 SLS/ODPS/OSS · 火山引擎 DeepSeek · Apollo 配置中心 · 飞书 API
|
luojunhui