gyxx-flow/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

GYXX Flow is a Python 3.12 src-layout modular monolith: LangGraph workflow orchestration, a Python-resident scheduler, and per-run audit (journal, locks, effect ledger). Docs, commit messages, and config descriptions are largely Chinese — follow the existing language of each file.

• src/gyxx_flow/core/, workflow/, adapters/ — shared framework: settings/RunContext/journal/locks (core), validated workflow models + build_catalog_workflow + WorkflowEngine (workflow), and the only sanctioned bridges to PostgreSQL/Feishu/Hermes/browser (adapters).
• src/gyxx_flow/modules/<module>/ — business code for content_marketing, product_commerce, shop_intelligence, supply_chain. Modules depend only on shared contracts, never on another module's internals. The runtime/ subpackages are legacy import-compatibility namespaces only; new production code goes directly in the module directory.
• config/ — the validated configuration quartet: workflows.json (scheduled workflows only, exactly one schedule each), schedules.json (time rules), commands.json (manual-command whitelist), runtime-bindings.json (browser bindings + accounts).
• tests/, docs/, deploy/ — tests, runbooks, deployment. var/ is generated state (gitignored); production must set an external GYXX_DATA_ROOT.

Build, Test, and Development Commands

Everything runs through uv from the repository root:

uv sync --python 3.12 --group dev      # create/update the dev environment
uv run pytest                          # full suite
uv run pytest tests/test_cli.py        # single file
uv run ruff check src tests            # lint (E4, E7, E9, F, I)
uv build                               # distribution artifacts
uv run gyxx doctor --json              # environment/config preflight
uv run gyxx acceptance status --json   # acceptance evidence
uv run gyxx sources status --source-root <module>=<dir>   # upstream drift check

Manual execution is dry-run by default; real external side effects require explicit --execute:

uv run gyxx list                                          # scheduled workflows only
uv run gyxx run product.daily --date 2026-08-01 [--execute]
uv run gyxx backfill content.metrics.daily --from <d> --to <d> [--execute]
uv run gyxx scripts run <script_id> --date <d> [--execute]
uv run gyxx schedule run [--dry-run] [--once]             # executes enabled jobs unless --dry-run
uv run gyxx accounts login|sync [account_id]

Constraints (preserve these contracts)

• gyxx schedule run is the only production scheduling path; never add Windows Task Scheduler entries or duplicate cron rules.
• Manual/backfill/maintenance commands must be declared in config/commands.json; never reintroduce recursive executable-script discovery.
• Each executable workflow_id compiles to a LangGraph StateGraph. Preserve the public contracts of the workflow model, RunJournal, LockManager, shadow comparison, and EffectLedger when changing graph execution.
• External systems: PostgreSQL via runtime-injected cloud DSN (GYXX_POSTGRES_DSN; no address/credential defaults in source, loopback rejected in cloud mode); Hermes loopback-only roles on 127.0.0.1:8642/8643 (key GYXX_HERMES_API_KEY); Feishu keeps its existing identity. Every browser binding keeps a unique CDP port plus isolated Profile/Cookie/storage-state; scripts sharing an account declare it under accounts in runtime-bindings.json — the vault state/accounts/<id>/ is the single login authority (gyxx accounts login/sync) and its cookies merge read-only into member scripts while profiles stay isolated.
• 启动或重启工作流控制台（gyxx console）必须携带 --env-file D:\product-collector-analyze-flow\.env（与调度器进程一致），否则 PG_HOST/PG_PORT/PG_DB/PG_USER/PG_PASSWORD 等云端 PostgreSQL 凭据和账号配置不会注入，「商品经营日报采集」「聚水潭全店铺款式日报」等正式执行会报“缺少 PostgreSQL 运行时凭据”。参考启动脚本：var/tmp/start-console.ps1。
• Source sync (gyxx sources status/apply): manifest-driven three-way hash drift check; only untransformed, conflict-free one-sided changes may be auto-copied, and only with --execute. Credentials, cookies, logs, and collected data never enter sync manifests.

Coding Style & Testing

• Ruff enforces E4, E7, E9, F, I. pyproject.toml excludes src/gyxx_flow/modules/*/** from lint (legacy baseline); CI additionally lints a focused list of critical module scripts — add newly critical module scripts there rather than removing the exclusion.
• Tests are pytest under tests/ (test_*.py); never require live credentials or mutate production services. Changes to workflows, schedules, manifests, runtime paths, or CLI behavior need acceptance or boundary coverage.
• Commits use short Conventional Commit subjects (e.g. feat: consolidate legacy workflows); never commit secrets, cookies, .env files, or generated var/ contents.
• Operational detail: docs/architecture.md, docs/deployment.md, docs/runbook.md, docs/acceptance-report.md.