FOH ContentFlow is an evidence-first, compliance-controlled short-video workflow for a clearly labeled synthetic demo. It takes a Brief through evidence review, structured script generation, claim binding, hard-rule checks, storyboard, asset authorization, deterministic FFmpeg rendering, G0/G1/G2 human gates, evaluation, and append-only audit.
It does not publish content, connect to a real FOH production system, certify legal compliance, or turn synthetic evidence into product claims.
SYNTHETIC / DEMO — 机器预审，不构成法律意见，最终发布由授权人员负责。
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2, Alembic, PostgreSQL 16/pgvector, Redis, HTTPX, pytest, Ruff, and strict mypy.
- React 19, TypeScript, Vite, React Router, 16 operable H5 views, demo RBAC, and live API flows.
- A code-owned 19-state transition table and typed N01–N12 coordinator with immutable checkpoints.
- Six stateless controlled Agents with real AI Studio and deterministic mock adapters.
- Retrieval, ClaimBinder, ten-family YAML RuleEngine, AssetValidator, RenderService, MetricsService, RepositoryService, Feishu real/mock adapters, and local storage/media ports.
- Frozen ClaimBench 120, RetrievalBench 30, VideoBench 12, nine Briefs, 32 evidence claims, nine scripts, three storyboards, and valid/expired/unauthorized asset examples.
- A real 9:16 MP4 with burned and embedded subtitles, silent audio fallback, synthetic labels,
pre-final watermark, SHA-256, and
asset_manifest.json.
The authoritative design is in docs/ARCHITECTURE.md, the workflow decision is in docs/ADR-001-workflow.md, and requirement evidence is in docs/REQUIREMENTS_TRACEABILITY.md.
Prerequisites: Python 3.12, Node.js 22+, npm, and Git. FFmpeg is supplied by the pinned
imageio-ffmpeg dependency, so a host FFmpeg installation is optional.
Linux/macOS:
python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"
npm ci --prefix apps/web
.venv/bin/python -m alembic upgrade head
.venv/bin/python scripts/seed_demo.py
.venv/bin/python scripts/run_demo.py
.venv/bin/python scripts/run_evals.pyWindows PowerShell:
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install --upgrade pip
.venv\Scripts\python.exe -m pip install -e ".[dev]"
npm.cmd ci --prefix apps\web
.venv\Scripts\python.exe -m alembic upgrade head
.venv\Scripts\python.exe scripts\seed_demo.py
.venv\Scripts\python.exe scripts\run_demo.py
.venv\Scripts\python.exe scripts\run_evals.pyRun the API and H5 in two terminals:
.venv/bin/python -m uvicorn apps.api.main:app --host 127.0.0.1 --port 8000
npm --prefix apps/web run dev -- --host 127.0.0.1Open http://127.0.0.1:5173. API health is at http://127.0.0.1:8000/health, readiness at
/ready, and interactive OpenAPI at /docs.
The role selector sends one of these fixed server-recognized demo tokens. A client-supplied role header is ignored.
| Role | Bearer token |
|---|---|
| operator | demo-operator |
| evidence_reviewer | demo-evidence-reviewer |
| science_reviewer | demo-science-reviewer |
| content_reviewer | demo-content-reviewer |
| director | demo-director |
| final_reviewer | demo-final-reviewer |
| auditor | demo-auditor |
| admin | demo-admin |
Every non-callback POST requires an Idempotency-Key. The Feishu callback derives its internal
key from the verified event_id.
The repository provides the required targets:
make bootstrap
make up
make down
make migrate
make seed
make test
make lint
make typecheck
make eval
make demo
make check-live-modelmake lint runs Ruff check and format verification. make typecheck runs strict Python mypy and
TypeScript. make eval writes artifacts/evaluation/evaluation_results.json; make demo writes
artifacts/demo/demo_run_result.json and a real MP4.
Docker Compose starts exactly api, worker, web, postgres, and redis:
cp .env.example .env
# Replace demo placeholders locally; never commit .env.
docker compose config
docker compose up --build -d
docker compose exec api python scripts/seed_demo.py
docker compose psThe web UI is at http://localhost:5173 and the API at http://localhost:8000. The API container
runs alembic upgrade head before Uvicorn. Stop with docker compose down; add -v only when you
intentionally want to delete local demo volumes.
This repository was finalized on a Windows host without Docker/Compose or GNU Make. Their source
contracts were statically validated and every underlying Python/npm command was run directly, but
container build/start and literal make invocation are recorded as host-unverified in
docs/KNOWN_LIMITATIONS.md, not represented as passing.
Default and CI mode is CONTENTFLOW_MODEL_ADAPTER=mock. A live call is allowed only when all
settings are supplied through the process environment and the opt-in flag is explicit:
export CONTENTFLOW_MODEL_ADAPTER=aistudio
export AISTUDIO_API_KEY='set-in-secret-manager'
export AISTUDIO_BASE_URL='https://provider.example/v1'
export AISTUDIO_CHAT_MODEL='provider-model'
export RUN_LIVE_MODEL_TEST=1
.venv/bin/python scripts/check_aistudio.pyThe check sends one minimal strict-JSON request and prints classification/telemetry without the key or raw prompt. Missing settings, authentication, rate limit, timeout, upstream, and protocol errors are diagnosed distinctly. The live check is skipped otherwise.
CONTENTFLOW_FEISHU_MODE=mock requires no credentials and exposes FEISHU_MOCK_MODE in readiness
and UI. Real mode requires FEISHU_APP_ID, FEISHU_APP_SECRET, callback verification token/key,
and a configured enterprise application. Network failure falls back only to an explicitly labeled
mock result; it is never reported as a real Feishu write. See
docs/FEISHU_INTEGRATION.md.
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format --check .
.venv/bin/python -m mypy apps contentflow scripts tests
npm --prefix apps/web run typecheck
npm --prefix apps/web run build
.venv/bin/python -m alembic upgrade head
.venv/bin/python scripts/check_compose.py
.venv/bin/python scripts/export_schemas.py
.venv/bin/python scripts/run_evals.py
.venv/bin/python scripts/run_demo.pyMeasured results and command evidence are recorded in docs/TEST_REPORT.md and docs/EVALUATION_REPORT.md. Frozen synthetic scores are not claims about production data, real brand performance, or legal acceptance.