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：采购确认、补货、库存预警和采购单更新。

智能工作台（dsh-refact 分支）

workbench/ 以 deepseek-harness 为 agent 底座，把现有工作流以 dsh 插件形式接入 Web UI：侧边栏选中任意工作流即可提问、 诊断、修复，支持监控告警与受控启动。使用与设计见 workbench/README.md 与 docs/workbench.md。

powershell -File workbench\bin\start-workbench.ps1

开发环境

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、凭据、日志和采集结果不会进入 源码同步清单。

详细操作见 架构说明、部署手册、 运维手册 和 验收报告。