7.6 KiB
GYXX Flow
GYXX Flow 是一个 Python 3.12 业务自动化平台，用 LangGraph 编排内容营销、商品经营、 店铺分析和供应链工作流，并由项目内 Python 调度器统一定时运行。
项目采用模块化单体：公共调度、工作流、数据和外部系统契约集中维护，业务实现留在各自 模块内。运行时不依赖其他源码目录，也不使用 Windows Task Scheduler。
能力概览
- 23 条调度工作流（内容 8、商品 8、店铺 4、供应链 3），当前全部启用。
- 工作流目录只保存定时任务；补采、重试、映射刷新和受保护写操作统一由手动命令承载。
- Python 常驻调度支持日、周、月、间隔日、错过触发补偿、防重复和优雅停止。
- 31 个显式命令覆盖工作流节点和手动补偿入口；138 条内部浏览器绑定继续使用唯一 CDP、Profile、Cookie 和 storage state。
- PostgreSQL 使用运行时注入的云端 DSN；地址、数据库、用户和密码均不在源码中提供默认值。
- Hermes 保持本机
data-collector、data-analyzer两个角色；飞书保持既有身份和接口。 - JSON、Markdown、CSV、Excel、下载文件和截图统一写入可迁移的数据根。
run、backfill、scripts run默认 dry-run，只有--execute允许真实副作用。
目录
config/ 工作流、时间表、脚本绑定和服务策略
deploy/ PostgreSQL 与调度服务部署文件
docs/ 部署、运维、源码同步和回滚手册
src/gyxx_flow/
adapters/ PostgreSQL、Hermes、飞书、浏览器适配边界
core/ 配置、运行上下文、日志、锁、产物
workflow/ LangGraph 模型、工厂与执行引擎
modules/<module>/ 四个业务域的工作流入口与内部实现
scheduler_service.py Python 常驻调度器
tests/ 项目级契约与回归测试
var/ 默认运行数据；不属于源码
业务模块：
content_marketing：内容指标、达人、评论和营销报告。product_commerce：商品数据、人群画像、市场排行、主图和经营分析。shop_intelligence：店铺、竞店和京东自营业绩。supply_chain：采购确认、补货、库存预警和采购单更新。
开发环境
cd D:\gyxx-flow
uv sync --python 3.12 --group dev
uv run ruff check src tests
uv run pytest
uv build
uv run gyxx doctor --json
uv run gyxx acceptance status --json
云端 PostgreSQL
由密钥系统向当前进程注入完整云端 DSN：
# 示例只展示变量名；真实 DSN 由部署环境提供
$env:GYXX_POSTGRES_DSN = '<secret-manager-provided-postgresql-dsn>'
应用优先从 GYXX_POSTGRES_DSN 读取云端连接，并映射到各业务模块使用的 PG_*、DB_* 和
AUTOFLOW_PG_* 变量。源码、示例文件和运行报告均不保存真实地址或凭据；云端模式会拒绝回环数据库地址。
本机 Hermes
运行时使用两个本机业务 API base：
- analyzer：
http://127.0.0.1:8642/v1 - collector：
http://127.0.0.1:8643/v1
28790/28791 不作为工作流业务端点。
密钥通过 GYXX_HERMES_API_KEY 注入。非回环 Hermes 地址会在业务脚本启动前被拒绝。
不使用 Hermes 的纯采集工作流可在无 AI 环境运行；依赖分析或通知的工作流需要对应本机
角色可用。
工作流与脚本
uv run gyxx list
uv run gyxx run product.daily --date 2026-08-01
uv run gyxx run product.daily --date 2026-08-01 --execute
uv run gyxx scripts list --module shop_intelligence
uv run gyxx scripts run shop.jd_self_operated.collect_product --date 2026-08-01
gyxx list 只展示调度工作流。手动补采和维护操作使用 gyxx scripts run；已配置的业务日期参数会从 --date 自动渲染，仍然只有显式添加 --execute 才会真实执行。
主图定时采集只注册为 product.main_image.weekly：每周日 08:30 同时启动京东和天猫两个独立分支。每个平台都在各自的采集完成后调用对应插入脚本，分别写入云端 PostgreSQL main_image_creatives 和飞书主图表；任一分支失败都不会取消、跳过或回滚另一分支的采集与写入，两个分支结束后工作流再汇总状态，并在失败摘要中标明具体平台和错误。真实写入仍受 --execute、凭据、登录态和副作用门禁约束。
| 场景 | 当前入口 |
|---|---|
| 内容映射重建 | gyxx scripts run content.mapping.rebuild --date <日期> |
| 内容失败任务重试 | gyxx scripts run content.failed.retry --date <日期> |
| 内容日报按日期重跑 | gyxx backfill content.metrics.daily --from <日期> --to <日期> |
| 京东自营品牌单日回采 | gyxx scripts run shop.jd_self_operated.collect_brand --date <日期> |
| 商品历史补采 | gyxx scripts run product.backfill.run --date <日期> |
| 商品评价补采 | gyxx scripts run product.review.orchestrate --date <日期> |
| 采购单更新 | gyxx scripts run supply.workflow.run --date <日期> |
每次运行生成稳定 run_id，并记录图节点状态、日志、产物、资源锁和外部副作用账本。
业务脚本通过共享适配器取得项目根、数据根、业务日期和服务配置，不应导入其他业务
模块的内部代码。旧 module:entry 脚本 ID 暂时保留为兼容别名。
Python 定时调度
uv run gyxx schedule run --dry-run --once
uv run gyxx schedule status
uv run gyxx schedule run
时间规则集中在 config/schedules.json：23 条声明全部启用，统一使用
Asia/Shanghai；单个日计划可以声明多个执行时间。服务器只托管一个 gyxx schedule run 进程，不要把业务规则复制为
Windows 任务或多条 cron。状态位于 state/scheduler，子任务日志位于 logs/scheduler。
数据目录
开发环境默认数据根是项目下的 var；生产环境必须通过 GYXX_DATA_ROOT 外置，例如
Linux 使用 /var/lib/gyxx-flow。现有数据可以整体迁移，不应删除或写回源码目录。
<GYXX_DATA_ROOT>/
data/raw/<module>/ 原始 JSON/CSV/XLS/XLSX、下载文件、截图
data/normalized/<module>/ 清洗与标准化结果
data/curated/<module>/ 聚合和业务事实
data/exports/<module>/ Markdown、Excel 等最终报告
data/evidence/<module>/ 验收及对账证据
state/browser/<module>/ 每脚本 Profile、Cookie、storage state
state/ 调度、工作流和幂等状态
logs/ 运行日志
tmp/ 可清理临时文件
业务源码同步
源码同步采用清单驱动的三方哈希比较，状态检查默认只读。源目录只用于发现更新，不是项目 运行依赖：
uv run gyxx sources status `
--source-root content_marketing=<内容源码目录> `
--source-root product_commerce=<商品源码目录> `
--source-root shop_intelligence=<店铺源码目录> `
--source-root supply_chain=<供应链源码目录>
只有未转换、无冲突的源端单边变化可通过 sources apply --execute 自动复制；经过统一适配
的文件必须人工复核并更新来源/目标哈希。Cookie、Profile、凭据、日志和采集结果不会进入
源码同步清单。