init

README.md

@@ -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