# 从课堂 MVP 到生产 Harness

## 目标架构

```mermaid
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，也不能使用个人密钥。