agent/docs/production-roadmap.md

从课堂 MVP 到生产 Harness

目标架构

flowchart LR
  Web --> Gateway[Gateway / Auth / CSRF / Rate Limit]
  Gateway --> API[Stateless API]
  API --> DB[(Postgres)]
  API --> Redis[(Redis Streams / Locks)]
  API --> KMS[KMS / Secret Manager]
  API --> Blob[Object Storage]
  Redis --> Workers[Agent Workers]
  Workers --> Sandbox[Per-run Container / microVM]
  Sandbox --> Egress[Egress Proxy / Allowlist]
  Workers --> Audit[Immutable Audit Log]
  Redis --> SSE[Distributed SSE Gateway]
  SSE --> Web

阶段 1：身份与持久化

• 引入用户、组织、Session 所有权与 RBAC。
• Postgres 保存 Session、Run、Message、Event、ToolCall 和 Approval 的不可变记录。
• 以 (session_id, sequence) 唯一约束保证事件顺序；命令使用幂等键。
• Redis 保存短期锁、队列和 fan-out，避免同 Session 多 Worker 并发。
• 为迁移和清理任务定义明确的数据保留周期。

阶段 2：凭证与 Web 安全

• API Key 进入 KMS / Secret Manager，应用只持有短期解密结果。
• OAuth 或短期 provider token 优先于长期静态密钥。
• Secure、HttpOnly、SameSite cookie；CSRF token；严格 CSP 与 frame-ancestors。
• 对 Session、模型测试、消息、上传和审批分别限速并设置租户配额。
• 所有错误响应使用稳定 code，不回显 provider body 或敏感 headers。

阶段 3：文件与执行隔离

• 原图和规范化图进入私有对象存储，使用租户前缀、服务端加密和生命周期规则。
• 图片扫描、解码超时、内存限制和异步规范化。
• 每个 run 在低权限容器或 microVM 内执行；只挂载该 Session 工作区。
• 使用只读根文件系统、CPU/内存/文件数/时长配额、seccomp 和无特权用户。
• 出站流量经过代理，只允许已批准的模型域名；禁止 metadata 和横向内网访问。

阶段 4：可靠 Agent 运行

• Durable queue 驱动 run 状态机，Worker 崩溃后可重试或终止。
• Approval request 持久化并使用 compare-and-set 解决重复、冲突和超时竞态。
• 工具 side effect 使用幂等键或事务 outbox；审批不等于可以重复执行。
• 版本化 Prompt、Skill、模型配置和工具 schema，以便重放与审计。
• 对 token、费用、延迟、tool error、approval time 和 cancellation 建立指标。

阶段 5：分布式事件与审计

• Redis Streams、Kafka 或数据库 outbox 发布事件。
• SSE Gateway 按租户鉴权、从持久 cursor 重放，并支持跨实例 fan-out。
• 审计日志记录操作者、决策、策略版本、输入摘要和 side effect，不记录秘密或原始敏感内容。
• 定期验证删除任务确实清除了数据库、对象存储、缓存、凭证与 Sandbox volume。

上线门槛

生产发布前需要威胁建模、依赖与镜像扫描、SSRF/路径/上传模糊测试、故障注入、备份恢复演练、租户逃逸测试和第三方安全评审。课堂测试套件应保留，并新增真实 provider 的隔离式 smoke test；后者不能进入默认 CI，也不能使用个人密钥。