GYXX Flow

GYXX Flow 是面向业务自动化的模块化工作流平台，统一管理数据采集、经营分析、供应链处理、定时调度和外部系统集成。

content_marketing：内容与营销采集
product_commerce：商品、平台和经营分析
shop_intelligence：店铺与竞店采集
supply_chain：供应链采集与通知

项目采用模块化单体结构。框架能力位于 src/gyxx_flow，各业务模块运行时代码位于 src/gyxx_flow/modules/<module>/runtime。工作流、脚本、数据目录和外部系统配置均由统一入口管理，同时保持模块间高内聚、低耦合。

核心能力

声明式工作流目录、依赖编排、超时、重试和失败恢复
计划任务生成、漂移检查和逐任务部署
手工执行、定时执行、日期回填、dry-run 和 shadow 模式
每次运行使用稳定的 run_id，记录步骤状态、日志、产物和外部写入
JSON、Markdown、CSV、Excel、下载文件和截图统一分层存储
每个浏览器脚本独立 CDP 端口、Profile、Cookie 和 storage state
飞书、云端 PostgreSQL、本机 Hermes 和浏览器能力统一接入

安装与验证

要求 Python 3.12，推荐使用 uv：

cd D:\gyxx-flow
uv sync --python 3.12 --extra test
uv run pytest
uv run gyxx doctor --json
uv run gyxx acceptance status --json

运行工作流

uv run gyxx list
uv run gyxx run product.daily --date 2026-07-27
uv run gyxx run product.daily --date 2026-07-27 --execute

run、backfill 和 scripts run 默认都是无副作用 dry-run；只有显式加 --execute 才会启动项目内的业务脚本。

运行任意脚本

uv run gyxx scripts list
uv run gyxx scripts list --module content_marketing
uv run gyxx scripts run content_marketing:run_all.py --date 2026-07-27
uv run gyxx scripts run content_marketing:run_all.py --date 2026-07-27 --execute

脚本 ID 格式为 <module>:<runtime 内相对路径>。Python、BAT/CMD 和 PowerShell 入口均受统一项目根、数据根、业务日期、run_id 和 shadow 环境约束。

浏览器与外部系统绑定

config/runtime-bindings.json 为当前 131 个脚本各自分配固定且唯一的 CDP 端口。无论从 workflow、scripts run 还是嵌套脚本启动，目标脚本都会重新取得自己的端口和 state/browser/<module>/<script>/ 下的 Profile、Cookie、storage state；同一脚本下次运行会复用登录态，不同脚本不会共享浏览器状态。

飞书继续走原来的 lark-cli/OpenAPI 身份；数据库继续走现有云端 PostgreSQL；Hermes 继续走本机服务。运行时会拒绝 localhost 数据库和非本机 Hermes 地址。不要在源码或 runtime-bindings.json 中写入 Cookie、数据库密码、飞书密钥或 Hermes token。

数据目录

默认数据根为 D:\gyxx-flow\var，可用 GYXX_DATA_ROOT 配置到其他磁盘或服务器目录。业务数据按模块写入 data/raw、data/normalized、data/curated、data/exports 和 data/evidence；运行状态、日志和临时文件分别进入 state、logs 和 tmp。原始 JSON/CSV/XLS/XLSX/下载文件进 raw，清洗结果进 normalized，聚合数据进 curated，最终 Markdown/Excel 报告进 exports。浏览器 Profile、Cookie 和 storage state 位于 state/browser/<module>/<script>/ 并按脚本复用。源码与运行数据相互隔离，部署或更换数据磁盘时只需调整环境变量。

定时任务

uv run gyxx schedule plan `
  --output D:\gyxx-flow\var\schedule-plan\candidate `
  --start-date 2026-07-27 `
  --python-executable D:\gyxx-flow\.venv\Scripts\python.exe

该命令只生成 21 个任务定义和审核脚本，不会直接注册、禁用或修改系统任务。生产启用时应先执行环境检查和 dry-run，再按工作流逐项应用调度配置。

关键文件

design.md：系统架构和模块边界
plan.md：逐项验收清单
config/workflows.json：工作流定义与本地执行入口
config/schedules.json：定时调度配置
config/runtime-bindings.json：脚本 CDP 端口与外部服务策略
docs/：部署、运行和回滚手册

4.2 KiB Raw Blame History Unescape Escape