long_articles_agentic_supply

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         → 支持深翻/增量

快速开始

# 安装
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 任务

执行器统一为 long-articles-agentic-src，参数格式 key=value。

供给管道

处理器	阶段	参数	说明	建议超时
demandEnqueue	入队	dt=20260706 limit=500	ODPS 拉取 → 解构 → MySQL 入队	≥300s
articleSearch	Phase 1	dt=20260706 limit=500	队列取词 → 微信搜索 → relation（写入 title_md5）	≥1800s
articleQualityTitle	质量	limit=100	relation 取标题 → 5 并发 LLM 评分 → 回写 quality_score	≥600s
articleFetchDetail	Phase 2	limit=100	relation(status=0, score≥40) → 详情 API → detail	≥600s
accountFetch	Phase 3	limit=100	relation(biz, score≥40) → 账号 API → accounts	≥600s
accountArticleFetch	Phase 4	limit=10	accounts 取 gh_id → 文章列表 → articles（深翻/增量）	≥1800s
accountArticleUpdate	Phase 5	limit=10	已完成深翻账号 → 第一页 → UPDATE 文章指标	≥600s

质量评估

处理器	参数	说明	建议超时
articleQualityQuantify	limit=500	按已深翻账号校验 detail → 入库 quantile → 量化计算（阅读比/点赞率）	≥300s
articleQualityTitle	limit=100	relation → title 种子同步 → 5 并发 LLM → 回写 quality_score	≥600s
articleQualityCategory	limit=100	relation → category 种子同步 → 5 并发 LLM → 品类识别	≥600s

调度顺序：articleQualityTitle 在 articleSearch 之后、articleFetchDetail 之前执行，详情和账号拉取按 quality_score DESC 优先级排序，低于 40 分自动跳过。

核心设计模式

• 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。

Git 分支规范

功能分支:  feature_YYYYMMDD_username_description
修复分支:  hotfix_YYYYMMDD_username_description

• 日期格式 YYYYMMDD，从 main 分支拉出
• 描述使用小写英文 + 下划线，简短清晰（如 account_fetch_rate_limit）
• 功能分支合并到 main 后删除；修复分支同理

编码原则

• 可读性第一：代码的第一性原理是让人快速看懂，认知负担是衡量标准
• 设计模式是手段不是目的：先问"解决什么真实问题"，再选模式
• 显式优于隐式：依赖、数据流、错误处理都走显式路径

技术栈

Python 3.11+ · Quart + Hypercorn · aiomysql + asyncpg · Redis + Milvus · pydantic-settings · XXL-JOB · 阿里云 SLS/ODPS/OSS · 火山引擎 DeepSeek · Apollo 配置中心 · 飞书 API