B-agent

面向外贸企业的 AI 获客、调研、沟通与安全执行平台。

B-agent 把企业调研、海外潜客发现、ICP 评分、AI 对话、知识检索、人工审批、可靠投递和异常处置整合进同一个中英文工作台。它不是一个只会生成文案的聊天机器人，而是一套带身份边界、持久记忆、可恢复任务、证据链和运营控制面的 Agent 工程基线。

模型既可以走固定直连供应商，也可以通过内网中的 OmniRoute 统一路由。浏览器永远只访问 B-agent API，不持有 OmniRoute、Hunter、Gmail 或 Microsoft Graph 的服务端凭据。

项目状态：可运行、可测试、可继续产品化的单组织工程基线。它还不是开箱即用的开放式多租户 SaaS；正式上线前仍需按目标环境完成密钥托管、备份恢复、容量、合规与灾备验收。

产品界面

当前前端采用 ChatGPT 式中性 AI 工作台语言：浅色与深色主题共享同一套语义令牌，侧栏提供快速新建对话入口，业务页面使用克制的边框、留白和扁平层级。下方截图重点展示业务信息架构；界面样式以当前分支运行结果为准。

Agent 中心

统一查看 Agent 运行模式、已注册 Skill、企业调研队列、触达草稿、审批投递以及近期可恢复运行。

AI 对话

AI 对话通过 B-agent 后端提交 detached run，并使用持久事件游标恢复输出；刷新页面不会把连接中断等同于任务失败。

智能获客

支持域名搜索、指定联系人、批量补全、联系人验证、ICP 评分和人工确认；只有满足验证策略的联系人才能进入后续触达链路。

已实现能力

• Agent 中心：展示真实运行时、13 个业务 Skill、业务流水线、企业调研和执行状态。
• 企业调研：创建带版本和证据引用的企业调研任务，补充市场信号并进行人工复核。
• 智能获客：通过 Hunter 进行域名搜索、联系人查找和验证，支持可续跑的批量富化任务。
• ICP 评分：保存评分依据、缺失信号和过期状态，由业务人员确认后进入触达链路。
• AI 对话：保存会话和消息，以 202 Accepted 创建可脱离浏览器连接的运行，并通过 durable SSE、Last-Event-ID 和 stream.reset 恢复输出。
• fast/deep 路由：短、低风险请求使用受限 fast 档案；被当前规则识别的敏感信息、业务证据关键词、工具动作、长输入和长会话自动 deep。路由异常或未知版本默认 deep。
• 上下文与 Prompt：不可变 Prompt 版本、严格变量契约、token 预算、可信度分区和 prompt injection 边界。
• 三层记忆底座：working、session、long-term 持久记忆，包含准入策略、版本修正、逻辑失效 epoch 和异步清理任务。
• 企业 RAG 底座：知识文档版本、组织命名空间、ACL 后置复核、敏感级别过滤、证据快照、安全缓存和独立知识检索 API。
• 并发与恢复：全局、组织、用户、Provider 和 Tool 五级原子并发租约；Agent Run、Tool Run 与 LLM Invocation 使用租约和 fencing token 防止旧 Worker 回写。
• AI 路由控制：支持直连供应商或 OmniRoute；管理员可在设置页热更新固定模型别名、供应商白名单和超时参数。
• 人工审批投递：调研、文案和发送分阶段审批，发送前重新校验联系人、ICP、草稿版本、邮箱状态和额度。
• 可靠执行：事务 Outbox、幂等键、Worker 租约、失败分类、死信队列和双管理员异常处置。
• 邮箱连接：Gmail 与 Microsoft OAuth，使用 PKCE 和一次性 state；令牌只保存在后端权限为 0600 的凭据文件中。
• 投递验证：Gmail 校验 SENT 标签；Microsoft 使用 Immutable ID 在 Sent Items 中验证同一封邮件。
• 管理工作台：ChatGPT 风格的中性响应式界面，支持中文/英文、深浅主题、运行时后端地址和 Vite HMR。
• 安全媒体资产面：S3 隔离上传、ClamAV/FFprobe 自动检查、证据驱动晋级、敏感级别受控下载、异步安全缩略图、资产血缘、软删除和延迟对象清理。
• 视频规划与 Persona：不可变 Persona/Storyboard 版本、独立审批、固定项目快照、RAG 证据白名单、编译时 ACL 回查、注入隔离和安全 GenerationIntent 回执。
• 媒体 Provider Runtime：fal 能力白名单、不可变运行时 revision、逐版本 0600 密钥、健康探测与显式激活；队列适配器支持 submit/status/result/cancel，拒绝重定向、未知模型、超限响应和非批准媒体域名。
• 持久媒体生成任务：Generation Job/Attempt/Event、月度微美元预算预留与 append-only 账本、提交与对账双 fencing、运行时版本固定、终态单调转换，以及禁止自动重发的 submission_unknown 协调边界；provider 完成后必须先获得隔离摄取回执才能结算成功。
• 安全媒体提交 Worker：AES-GCM 加密不可变 GenerationIntent，Celery 仅扫描 Job ID；Worker 逐条领取后从实时用户、Persona、Storyboard、扫描、权利、同意及其证据重新授权，使用任务固定 runtime 提交，并在网络调用前后重新检查租约时间。
• 单素材图生视频（I2V）：浏览器只提交已审核素材 ID；Worker 在外部 effect 前重新锁定合规证据，强制 assets/{org_id}/ 组织命名空间，复核对象 SHA-256、大小、MIME 与 S3 VersionId，随后生成仅供 fal image_url 使用的短效读取凭据。签名 URL 不落库、不写事件、不返回前端。
• 媒体 Job API：认证用户可用只含幂等键与 Storyboard version 的请求创建单 Shot Job；服务端编译 Prompt、固定 runtime/model、写入加密意图仓并预留管理员配置的预算上限。详情与 after_sequence 事件游标按组织/所有者隔离并过滤内部请求 ID 和证据引用。
• 可恢复媒体时间线：认证 SSE 使用 Last-Event-ID 从持久事件游标续传，heartbeat 返回安全 Job 状态后主动结束本轮连接；视频工作室用稳定幂等键恢复创建中断，展示任务状态、模式、模型、预算预留上限和脱敏事件，刷新或断网不会自动重发供应商请求。同一浏览器会话在活动 Job 终态前禁止切换到另一 Shot，避免任务继续计费却丢失跟踪。
• Provider 结果隔离摄取：对 fal 输出重新执行允许域和 DNS 校验，并核对实际 socket peer；拒绝重定向、私网地址、未知 MIME、超限和截断响应，使用 0600 临时文件计算 SHA-256 后幂等写入 S3 quarantine，生成资产保持待扫描/版权/同意复核状态。
• 媒体对账 Worker：Celery Beat 按配置唤醒 submitted Job；Worker 逐个即时领取、递增 fencing，严格重建任务固定的 runtime revision，安全读取逐版本密钥，查询 fal 状态并把完成结果摄取到隔离区。读取失败只退避重试，不重发生成请求。
• 提交不确定态人工协调：submission_unknown 只能由两名不同超级管理员基于白名单证据引用确认；确认已提交时绑定全局唯一 provider request ID 并进入安全对账，确认未提交时终止任务并仅释放预留预算，两个路径都不会自动重发。
• Video Studio：中英文创建 Persona、项目和单 Shot 分镜，查看版本与证据，执行管理员审批；所有请求自动使用设置页可热切换的后端地址。

当前能力边界

当前通用 AI Chat 主链路默认装配 System Prompt 与会话历史。记忆与 RAG 已具备持久化服务、API、迁移和测试，但仍需按调研、报价、跟进等业务流明确接入策略，README 不把“底座存在”等同于“所有对话已自动使用”。

项目架构图

flowchart TB
    USER["外贸团队 / 管理员"]

    subgraph EXPERIENCE["体验层"]
        UI["Vue 3 工作台<br/>Agent / Chat / Video / CRM / Operations"]
        RUNTIME_URL["运行时 API 地址<br/>同源代理或管理员配置"]
    end

    subgraph CONTROL["API 与控制面"]
        API["FastAPI API"]
        AUTH["JWT / RBAC<br/>单组织信任边界"]
        BUSINESS["客户 / 会话 / 获客<br/>调研 / ICP / 工作流"]
        ADMIN["AI / Media Runtime 配置<br/>连接器 / 可靠执行 / 死信处置"]
    end

    subgraph AGENT["Agent Runtime"]
        RUN["Durable Run / Turn<br/>幂等键 + 租约 + Fencing"]
        POLICY["DLP / fast-deep 路由<br/>Provider 白名单"]
        CONTEXT["Prompt Registry<br/>上下文预算 / 不可信输入隔离"]
        MEMORY["Working / Session / Long-term"]
        RAG["Versioned RAG<br/>ACL / 敏感级别 / 证据快照"]
        TOOLS["Durable Tool Runtime<br/>提案 / 审批 / 执行"]
    end

    subgraph MODEL["模型访问层"]
        LLM["统一 LLM Service<br/>审计 / TTFT / E2E 指标"]
        DIRECT["固定直连 Provider"]
        OMNI["OmniRoute 内部网关<br/>固定别名 + 响应后复核"]
    end

    subgraph ASYNC["异步执行层"]
        CELERY["Celery Worker / Beat"]
        OUTBOX["Transactional Outbox"]
        DELIVERY["审批投递 / Sent 验证<br/>失败分类 / Dead Letter"]
        MEDIA["媒体检查 / 缩略图 / 生命周期<br/>固定命令 + 证据门禁"]
        MEDIA_RUNTIME["Media Runtime Revision<br/>能力快照 / 探测 / 激活"]
        MEDIA_SUBMIT["安全提交 / 对账 Worker<br/>实时授权 + 双 Fencing"]
    end

    subgraph DATA["数据与协调层"]
        PG[("PostgreSQL<br/>业务与持久事件")]
        REDIS[("Redis<br/>队列 / 租约 / 协调")]
        CACHE[("独立 Redis Cache<br/>无 AOF 的 RAG 候选缓存")]
        SECRETS["后端凭据目录<br/>0600 文件权限"]
        INTENT_VAULT["AES-GCM 意图仓<br/>不可变引用 / AAD 完整性"]
        OBJECTS[("S3 兼容对象存储<br/>隔离桶 / 资产桶 / 短效签名")]
    end

    subgraph EXTERNAL["外部服务"]
        HUNTER["Hunter / 数据连接器"]
        GMAIL["Gmail API"]
        OUTLOOK["Microsoft Graph"]
        WHATSAPP["WhatsApp"]
        FAL["fal Queue API<br/>submit / status / result / cancel"]
    end

    USER --> UI
    UI --> RUNTIME_URL -->|"REST + Durable SSE"| API
    API --> AUTH
    API --> BUSINESS
    API --> ADMIN
    API --> RUN

    RUN --> POLICY --> CONTEXT --> LLM
    CONTEXT -.->|"按业务策略读取"| MEMORY
    CONTEXT -.->|"按业务策略检索"| RAG
    RUN --> TOOLS

    LLM --> DIRECT
    LLM --> OMNI
    TOOLS --> CELERY --> OUTBOX --> DELIVERY
    CELERY --> MEDIA
    CELERY --> MEDIA_SUBMIT
    ADMIN --> MEDIA_RUNTIME
    MEDIA_RUNTIME -.->|"Job 创建时固定"| MEDIA_SUBMIT

    BUSINESS --> PG
    RUN --> PG
    MEMORY --> PG
    RAG --> PG
    RUN --> REDIS
    CELERY --> REDIS
    RAG --> CACHE
    SECRETS --> LLM
    SECRETS --> CELERY
    SECRETS --> INTENT_VAULT
    INTENT_VAULT --> MEDIA_SUBMIT
    MEDIA --> OBJECTS
    MEDIA_SUBMIT -->|"I2V 即时签名读取 / 结果隔离写入"| OBJECTS
    MEDIA --> PG
    MEDIA_SUBMIT --> PG
    MEDIA_RUNTIME --> PG
    SECRETS --> MEDIA_RUNTIME

    BUSINESS --> HUNTER
    DELIVERY --> GMAIL
    DELIVERY --> OUTLOOK
    DELIVERY --> WHATSAPP
    MEDIA_SUBMIT --> FAL

架构分层与职责

核心设计原则

1. 浏览器零供应商密钥：前端只持有 B-agent 登录令牌和可公开的运行状态，不接触模型、Hunter 或邮箱服务端密钥。
2. 所有外部副作用可追踪：调研、草稿、审批、Tool Run、Outbox 和供应商确认都使用持久记录串联。
3. 执行可以恢复，但不能越权恢复：租约过期后任务可重新领取，旧 Worker 的 fencing token 不能提交结果。
4. 路由默认收紧：未知路由版本、策略异常、敏感数据或工具动作进入 deep 或 fail-closed，不自动放宽。
5. 记忆和 RAG 不是隐式全开：长期记忆需要可信来源和准入，RAG 结果需要版本、ACL、组织和敏感级别复核。
6. 不可逆动作保留人工控制：外发、审批和死信结论均有明确的人机边界。

Agent Runtime 设计

一次 AI 对话的执行链路

sequenceDiagram
    participant UI as Vue 工作台
    participant API as FastAPI
    participant DB as PostgreSQL
    participant W as Agent Worker
    participant P as Policy / Context
    participant L as Direct LLM / OmniRoute

    UI->>API: POST /messages/runs + Idempotency-Key
    API->>P: 分类敏感信息并选择 fast/deep
    API->>DB: 原子写入 Turn、用户消息、Run 与执行档案
    API-->>UI: 202 Accepted + run_id
    W->>DB: 使用租约与 fencing token 领取 Run
    W->>P: 装配 Prompt、对话历史与 token 预算
    P->>L: 发送脱敏请求和固定 use-case 路由
    L-->>W: 流式 token / 完整响应
    W->>DB: 持久化 route、delta、完成事件与审计指标
    UI->>API: GET /agent/runs/{id}/events + Last-Event-ID
    API-->>UI: 从 durable cursor 回放 SSE

系统链路

flowchart LR
    UI["Vue 3 双语工作台"] --> API["FastAPI 控制面"]
    API --> AUTH["JWT / RBAC / 单组织边界"]
    API --> BUSINESS["调研 / 获客 / ICP / 会话"]
    API --> RUN["Durable Agent Run"]

    RUN --> POLICY["DLP + fast/deep + Context Budget"]
    POLICY -.->|按业务流接入| MEMORY["Working / Session / Long-term Memory"]
    POLICY -.->|按业务流接入| RAG["Versioned RAG + ACL Snapshot"]
    POLICY --> LLM["LLM Service"]
    LLM --> DIRECT["固定直连模型"]
    LLM --> OMNI["OmniRoute 内部网关"]

    RUN --> TOOLS["Durable Tool Runtime + Approval"]
    TOOLS --> OUTBOX["Transactional Outbox"]
    OUTBOX --> WORKER["Celery Worker / Beat"]
    WORKER --> MAIL["Gmail / Microsoft Graph"]

    BUSINESS --> DB[("PostgreSQL")]
    RUN --> DB
    MEMORY --> DB
    RAG --> DB
    RUN --> REDIS[("Redis Leases / Cache / Queue")]
    SECRETS["后端 0600 凭据文件"] --> LLM
    SECRETS --> WORKER

浏览器不会接收 OmniRoute、Hunter 或邮箱供应商凭据。外部邮件只有在供应商 Sent 副本验证成功后才会被记录为已发送；无法确认的结果进入人工处置链路，不会自动重试造成重复触达。

当前 OmniRoute 集成固定在提交 e0ce95c592c00f100f5141371dbda976d678ddee。B-agent 禁止 auto/* 模型别名，并在网关响应后再次校验实际 Provider 是否属于管理员白名单，避免 PII 或企业数据被 fail-open 到未批准供应商。

前端工作台与 API 对接

前端热加载机制

• 源码热更新：开发容器使用 Vite HMR 和源码 bind mount，Vue、TypeScript 与 SCSS 修改后不需要重建镜像。
• 后端地址热切换：默认使用同源 /api 代理；管理员可在设置页保存 HTTP(S) Base URL，新的 Axios 和 SSE 请求立即使用该地址。
• AI 路由热更新：管理员通过 GET/PUT /api/v1/ai/config 读取和更新 Direct/OmniRoute 模式、固定模型别名、Provider 白名单和超时；POST /api/v1/ai/config/test 用于连通性探测。
• 媒体运行时热更新：设置页从服务端能力白名单选择 T2I/I2V/T2V 模型，创建不可变 revision；只有健康探测成功的 revision 才能显式激活，且激活指针只供后续新 Job 固定使用。
• 密钥写入不回显：前端可提交新的网关 API Key，但读取配置时只得到 api_key_configured 布尔值，不会获得密钥本身或服务端文件位置。
• 权限边界不热降级：浏览器 Base URL 和 AI 路由可热更新，JWT、RBAC、DLP、审批、Provider 白名单和 Tool 安全策略仍由后端强制执行。

Docker 服务拓扑

技术栈

目录结构

.
├── backend/
│   ├── alembic/             # 数据库迁移
│   ├── app/
│   │   ├── api/v1/          # Auth、Agent、AI、CRM、Admin 等 FastAPI 路由
│   │   ├── core/            # Agent、Skill 注册表与工作流引擎
│   │   ├── integrations/    # AI、邮件、WhatsApp 与数据集成
│   │   ├── models/          # 数据库与 API 模型
│   │   ├── services/
│   │   │   ├── agent_runtime/ # Prompt、Context、Turn 与 Runtime
│   │   │   ├── llm/         # 模型契约、Factory、审计与运行时池
│   │   │   └── ...          # 记忆、RAG、工具、调研、投递和可靠执行
│   │   ├── skills/          # 可插拔业务 Skill
│   │   └── tasks/           # Celery Worker 与调度任务
│   ├── scripts/             # 管理员、知识库、基准和负载测试脚本
│   └── tests/               # API、服务、安全、并发和持久化测试
├── frontend/
│   ├── src/
│   │   ├── api/             # 类型化 API Client 与运行时 Base URL
│   │   ├── components/      # 工作流编辑器等复用组件
│   │   ├── i18n/            # 中英文文案与语言切换
│   │   ├── layouts/         # ChatGPT 风格工作台外壳
│   │   ├── stores/          # Auth 与 Theme 状态
│   │   ├── styles/          # 全局语义令牌和 Element Plus 主题
│   │   └── views/           # Agent、Chat、CRM、Operations 等页面
│   └── tests/               # 页面契约、安全边界与类型检查测试
├── docs/
│   ├── adr/                 # 架构决策记录
│   ├── brand/               # README 产品截图与品牌资产
│   └── runbooks/            # OmniRoute 与可靠执行运维手册
├── plans/                   # 架构与实施计划
├── docker-compose.yml
├── docker-compose.gateway-production.yml
├── THIRD_PARTY_NOTICES.md
└── .env.example

快速启动

Docker Compose

1. 创建本地配置并检查需要启用的集成：

cp .env.example .env

当前 docker-compose.yml 是本机开发基线，其中数据库口令和 SECRET_KEY 仍是显式的开发示例值。根目录 .env 只会替换 Compose 文件中通过 ${...} 引用的变量；生产部署必须通过 Compose override 或密钥管理系统覆盖所有示例凭据。

2. 启动数据库迁移、API、Worker、前端和监控服务：

docker compose config
docker compose up --build

migrate 是一次性 schema owner，会在应用启动前执行 alembic upgrade head。应用进程不会自行调用 create_all。

3. 使用明确的强密码创建管理员账号：

docker compose exec backend python scripts/create_admin.py \
  --username admin \
  --email admin@example.com \
  --password 'replace-with-a-strong-password'

4. 打开服务：

• 前端：http://localhost:3000
• 后端健康检查：http://localhost:8000/health
• OpenAPI：http://localhost:8000/docs
• Flower：http://localhost:5555

前端容器运行 Vite development server，源码通过 bind mount 挂载，修改 Vue、TypeScript 或 SCSS 后会通过 HMR 更新页面。

启用 OmniRoute

OmniRoute 默认不启动，也不向宿主机发布端口。使用固定版本的内部网关配置：

docker compose --profile gateway up --build

在 .env 中把 LLM_BACKEND 设置为 omniroute，并配置非空的 OMNIROUTE_ALLOWED_PROVIDERS 以及各业务用途的固定模型或组合别名。系统会拒绝 auto/* 动态路由，避免请求被 fail-open 到未批准的供应商。

完整部署、升级和回滚步骤见 OmniRoute Runbook。

本地开发

后端

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cp .env.example backend/.env
cd backend
alembic upgrade head
uvicorn app.main:app --reload --port 8000

如需运行异步任务，在另一个已激活虚拟环境的终端中执行：

cd backend
celery -A app.tasks.celery_worker worker --loglevel=info

前端

cd frontend
npm ci
npm run dev

开发服务器默认把 /api 和 /health 代理到 VITE_API_PROXY_TARGET。登录后也可以在“设置”页面保存浏览器专用的后端 Base URL，该值会立即应用，无需重新构建前端。

开发命令

后端常用验证命令：

cd backend
pytest -q
alembic current

关键环境变量

完整清单和示例值以 .env.example 为准。

Gmail / Microsoft OAuth

在供应商控制台登记与 .env 完全一致的服务端回调地址：

http://localhost:8000/api/v1/mailboxes/oauth/callback/gmail
http://localhost:8000/api/v1/mailboxes/oauth/callback/outlook

配置客户端 ID 和 Secret、重启后端，然后在“设置 → 已连接账号”中发起授权。OAuth Client Secret 不支持从浏览器热加载，这是刻意的安全边界；前端只读取供应商是否已配置以及授权 URL。

本地 Python 运行时可把这些值写入 backend/.env。Docker Compose 部署必须把 OAuth 客户端变量同时注入 backend 和 celery_worker 容器，并让两个服务共享 MAILBOX_SECRET_DIR；只写入宿主机根目录 .env、但不在 Compose 中映射变量，不会把它们自动传入容器。

数据库迁移 0013_secure_mailbox_oauth 会清除旧 Gmail/Outlook 账号中嵌入的令牌，并把账号标记为“需要重新连接”。系统不会把旧明文令牌静默复制到新的凭据目录。

主要 API

接口字段和当前响应模型以运行中的 http://localhost:8000/docs 为准。

测试与质量门禁

cd backend
pytest -q

cd ../frontend
npm test
npm run lint:check
npm run build

最近的完整工程验证基线（2026-08-13，b-agent-enterprise-platform）：后端 698 passed, 2 skipped；前端 49 passed，ESLint、Vue/TypeScript 检查和 Vite 生产构建通过；Python 全量编译与 docker compose config --quiet 通过。两个跳过项需要 PostgreSQL 测试库执行行锁并发验证。这里的数量是版本验证记录，不替代 GitHub Actions、真实 Provider/S3 并发压测或目标环境验收。

Agent 性能与发布门禁

确定性的本地基准用于发现框架开销回归：

cd backend
PYTHONPATH=. python scripts/benchmark_agent_runtime.py \
  --scenario all \
  --samples 50 \
  --output ../artifacts/agent-benchmark.json

预生产发布候选还应运行真实 detached API 负载门禁。它会走完整的创建会话、202 入队、durable SSE、首 token、完成和清理链路，并按错误率、p95 TTFT 和 p95 E2E 返回 CI 可用的退出码：

cd backend
export B_AGENT_LOAD_TOKEN='<short-lived-staging-token>'
PYTHONPATH=. python scripts/load_test_agent_chat.py \
  --base-url https://staging.example.com \
  --target-environment staging \
  --expected-deployment-id staging-primary \
  --requests 100 \
  --concurrency 8 \
  --max-error-rate 0.01 \
  --max-p95-ttft-ms 3000 \
  --max-p95-e2e-ms 15000 \
  --output ../artifacts/agent-load.json

负载令牌只从环境变量读取。脚本会先使用无认证请求验证服务端 environment 与唯一 deployment_id，成功后才构造 Bearer 客户端；远程目标必须使用 HTTPS，生产目标还需要 --confirm-production-load。

安全边界

• OmniRoute 使用固定供应商白名单和固定模型别名；不允许 auto/* 动态路由。
• fast path 只减少历史与输出预算，不放宽 DLP、RAG ACL、Provider 白名单、Prompt 或审批规则；无法验证的执行档案默认 deep。
• 供应商密钥与邮箱令牌只存放在后端，API 响应不会返回密钥或文件引用。
• 被当前分类器识别为 Restricted 的数据不会进入外部模型或长期记忆；邮箱、电话和 API key 等已覆盖字段会在模型边界前按策略拦截或脱敏。未命中的商业机密仍需调用方提供敏感级别，不能把规则分类器当作完整 DLP 产品。
• RAG 候选即使来自缓存，也必须重新通过组织、文档版本、ACL 版本、索引版本和敏感级别校验。
• Redis 并发协调不可用时拒绝新 Agent 工作，不使用不可靠的本地计数继续执行。
• Compose 的知识检索缓存使用无 AOF、无宿主机端口的独立 Redis；逻辑 TTL 不代表主存储删除，生产环境仍需制定缓存内存、快照和备份边界。
• Gmail/Microsoft 连接使用 PKCE、哈希 state、短时会话和一次性回调。
• 发件动作由事务 Outbox 驱动，无法确认是否发送的结果不会自动重试。
• 调研、文案和发送保留人工审批点；死信结论需要两名不同管理员批准。
• 当前部署模型是单组织信任边界，不应在未完成租户隔离审计前作为开放式多租户 SaaS 运行。
• 媒体下载只对已晋级且扫描、版权、同意证据完整的资产签发最长 300 秒凭据；隔离区、软删除和越权资产不会获得签名。
• I2V 生产环境的资产桶必须启用对象版本化，并通过 Bucket/IAM 策略禁止覆盖或提前删除审核版本；缺失 VersionId、组织命名空间不匹配或对象完整性漂移都会在外部 effect 前失败关闭。
• 缩略图参数完全由服务端固定，媒体二进制不进入 API/Celery payload；派生资产继承敏感级别并保存血缘。对象清理默认关闭，启用后仍需真实超级管理员维护身份与保留期。
• fal API Key 按 runtime revision 写入后端 0600 文件，数据库与 API 只保存配置和 api_key_configured；对账 Worker 使用 O_NOFOLLOW 和打开后的文件元数据复核阻断符号链接替换。Provider 返回的控制 URL 不被信任，队列 URL 始终由固定 origin 与已批准模型 ID 构造。
• 对账 Worker 不读取“当前激活”指针，而只使用 Job 提交时固定的 revision、能力快照 hash、模式与模型别名；逐个即时领取避免大文件下载耗尽批次中后续任务的租约。
• 提交 Worker 的 Celery 任务没有业务参数；完整 Prompt 只存在 AES-GCM 加密意图仓，密钥与密文必须是后端私有权限。每次 effect 前会重查活跃用户、批准快照、扫描哈希、权利/同意有效期和同意证据资产，并重新签发短期策略决策。
• text_to_video 只提交服务端编译的 Prompt；image_to_video 只接受一个已晋级图片资产 ID。Worker 在 effect 前重新锁定并读取素材、扫描、版权、同意证据与敏感级别，强制对象键属于 assets/{org_id}/，再从资产桶复核 SHA-256、大小与 MIME，并把具体 S3 VersionId 绑定到最长 24 小时、默认 1 小时的供应商读取凭据，映射到 fal 的 image_url。资产桶必须启用版本化并禁止覆盖审核版本；浏览器不能提交 URL，凭据不写入数据库、事件或 API 响应。签名基础设施临时失败只延后任务，完整性/版本错误在 effect 前拒绝。
• reference_to_video 和多素材 I2V 仍在 effect 前失败关闭，不会降级成文生视频；这两类模式需要单独完成模型字段白名单、人物一致性/肖像同意和组合素材策略。
• 成功任务的成本结算器 basis 是 pinned_provider_usage：fal 结果响应的 X-Fal-Billable-Units 会先作为请求级用量凭据持久化，再乘以任务固定 Runtime Revision 中由同一账户查询并哈希锁定的微美元单价。缺失、歧义格式、Request/Model 不匹配、价格哈希变化、非整数微美元结果或超过预算预留都会失败关闭。
• Runtime 管理 API 仅回传 pricing_configured 和 pricing_snapshot_hash，不会把账户折扣单价下发浏览器。旧 Revision 没有价格快照时不能结算，必须创建并激活新 Revision；已有任务仍坚持自己的旧 Revision，不会套用最新价格。
• Provider 失败任务通常没有结果级单位回执，当前保持对账重试/人工核销，不擅自记 0，也不再用预算预留上限冒充实际支出。
• submission_unknown 不提供直接重试操作；协调结论需要两名不同超级管理员，证据引用仅允许 provider-audit/、provider-support/ 或 billing-audit/，API 响应与 Job Event 不回显证据路径。
• MEDIA_SUBMIT_ENABLED 与 MEDIA_CALLBACK_ENABLED 仍默认关闭；安全提交/对账 Worker、固定运行时、实时策略复核、单素材 I2V 即时签名、实际 peer 校验、S3 结果隔离、submission_unknown 人工协调、fal 认证回调、请求级用量凭据和成功任务的版本化账户价格核销已落地，但生产开放仍要等待失败请求账单对账、Reference-to-Video/多素材参数解析和故障注入验收。
• 不要提交 .env、OAuth 凭据、导出客户数据或 data/secrets 内容。

相关文档

• B-agent × OmniRoute 二次改造实施蓝图
• Agent Runtime 优化蓝图
• 视频生成 Persona 与媒体生产链路蓝图
• 外贸 Agent API 蓝图
• OmniRoute 生产部署与回滚 Runbook
• 可靠执行与 Outbox 运维 Runbook
• 共享网关架构 ADR
• 单组织信任边界 ADR
• 项目代码落实方案

许可证

本项目采用 MIT License，Copyright (c) 2026 EricHong123。

MIT 许可证允许商业使用、修改、分发、再许可和销售，但复制或分发本软件及其重要部分时必须保留版权声明和许可证声明。软件按“原样”提供，不附带任何明示或暗示担保。第三方组件、模型、数据、字体、媒体资产和服务仍分别受其自身许可证及服务条款约束，详见 THIRD_PARTY_NOTICES.md。