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

执行器统一为 `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