FFAI Agent 实现架构全解剖

00全景架构：六层 vs 六层

CC 是「React 渲染到终端的前端 + while(true) 引擎 + 工具执行器」；FFAI 是「多组织服务端的同一个 while(true)，外面包一圈企业治理」。

两者内核惊人一致：没有计划器，只有一个 while(true)——模型不停要工具，循环不停喂结果。根本差异只有一个：信任边界的位置。CC 跑在用户自己的机器上，信任边界是「这台机器的主人」，安全靠权限弹窗；FFAI 跑在公司服务端、服务全组织员工，信任边界是「RBAC + 多组织隔离 + 不可篡改审计」，安全必须焊死在代码结构里（收口点、fail-closed、哈希链），不能依赖任何人点弹窗。

01一条消息的一生 ★

与 CC 篇同构的主线：从前端 POST 到 SSE 流回完整回复，共 12 站。每站底部灰绿色小字是 CC 的对应站点。

02TAOR 主循环：runTurnStream

整个产品的心脏。2947 行的 messages.service.ts 里是一个 while(true)，每次迭代 = 一次「调模型 + 执行工具」的回合。

2.1 调用栈对照

FFAI vs CC 调用关系
── FFAI ──────────────────────────────────────────────────
POST /agent/messages(/stream)
 └─ MessagesController.postMessageStream()   [messages.controller.ts:124]  SSE 壳 + 心跳
     └─ runTurnStream()                    [messages.service.ts:1024]   AsyncGenerator，真正的 while(true)
         ├─ QueryEngine（只做 compaction）    [engine/query-engine.service.ts]
         └─ runTurn() = 同步 wrapper 内部 drain 同一个 generator  [:965，Teams/cron 用]

── Claude Code ───────────────────────────────────────────
用户输入
 └─ QueryEngine.submitMessage()   [QueryEngine.ts:209]  会话经理
     └─ query()                   [query.ts:219]        薄壳生成器
         └─ queryLoop()           [query.ts:241]        while(true)

2.2 一轮迭代的完整步骤

终止条件汇总：end_turn（无 tool_use）/ MAX_ITER=100 / cancelled / permission_required / ask_user / turn 硬超时。ask_user 是 FFAI 特有的第一类终态——CC 的 AskUserQuestion 是阻塞式弹窗（循环原地等），FFAI 的 ask_user 直接结束 turn、把问题作为事件推给前端/Teams 卡片，用户回答开启新 turn。这是「终端同步交互」与「Web/IM 异步交互」的形态差异。

2.3 取消、硬超时与多副本

• 取消广播：CC 是单进程，ESC → abortController.abort() 就完了。FFAI 部署多副本（pm2 cluster），取消要跨进程：TurnCancelBroker 本地 Map 命中直接 abort，miss 则 publish Redis 频道 agent:turn:cancel 广播其他副本；跨 org 取消被 CrossOrgCancelError 拒绝。services/turn-cancel-broker.service.ts:82-108
• 端到端穿透（I-40）：signal 透传到 LLM 流（4 家 provider）、web_fetch/web_search（AbortSignal.any 合并）、cli 容器（abort → container.kill()）、MCP（RequestOptions.signal）。CC 同款设计（signal 传 API + 所有工具），两边都补了「合成收尾」——CC 给未执行工具补 is_error tool_result 保消息序列合法，FFAI 把 partial text 落库标 partial:true。
• turn 硬超时：FFAI_AGENT_TURN_HARD_TIMEOUT_MS 默认 15 分钟，setTimeout 到期 abort 复用取消清理路径——防「idle watchdog 每次都差一点不触发但累积挂一小时」。CC 无此层（终端用户自己会按 ESC）。messages.service.ts:83-90,1067-1076
• 无 session 级互斥锁：并发写靠 @@unique([sessionId,sequence]) + P2002 jitter 重试（最多 24 次）原子分配 sequence，而非 Redis 锁。messages.service.ts:625-661

03上下文组装与压缩

FFAI 的 compaction 设计了 5 层，实装 4 层；CC 是 3 级机制。两边的 auto-compact 阈值常量逐字相同。

3.1 压缩层级对照

3.2 CLAUDE.md 的对应物是什么

CC 的分层记忆（Managed → ~/.claude → 项目逐级向上）在 FFAI 里被拆成了结构化的几段，全部进 system prompt：

04工具系统：四轨 + 装饰器注册

85 个 @AgentTool 装饰器（35 个文件）+ MCP 动态注册。一个工具 = 元数据 + 执行 + 可用性 + 治理标志，与 CC 的 Tool 对象同构。

4.1 ToolDescriptor vs CC Tool 接口

4.2 四轨执行器（CC 只有一轨：本机）

4.3 治理流水线：ToolRegistry.invoke 的 11 个 stage

这是 FFAI 相对 CC 最大的结构增量——所有工具调用（业务/MCP/子 agent/桥接）必经这一条收口，不存在旁路（I-21，Hermes 踩过「裸 dispatch 绕过治理」的坑后焊死）：

tools/tool-registry.service.ts:175-275
stage 0  解析工具（NotFound throw）
stage 1  zod 入参校验（bootstrap adapter 内，失败返 INPUT_INVALID 给模型自修）
stage 3  PreHook（占位 → E20 S5）
stage 4  IAM 授权 hook（AIToolGrant，flag 控 fail-open 渐进；LOCKED_SET 4 项恒放行）
stage 4b destructive 二次确认 → 返 PERMISSION_REQUIRED（不执行，turn 中断等用户）
stage 5  幂等去重（写且非幂等：Redis 120s，key 含 org+user+turnId+sha256(入参)）
stage 7  执行（dispatchKey→桌面 WS / 否则 tool.invoke）+ 异常三档分类
         （Forbidden→security / BadRequest→business / 其余→system，真实 message 都回模型）
stage 8  出口脱敏 redactSensitiveText/redactDeep（sk-/ghp_/AKIA/PEM/JWT/DB 连接串，
         force 模式，REDACT_ENABLED import 时冻结——prompt injection 关不掉）
stage 9  超 50_000 字符 → 全文落 org 隔离 blob，LLM 只拿 <persisted-output> preview

4.4 四个代表性工具（对照 CC 的四个）

05权限、沙箱与审计

CC 的问题是「模型想做 X，允许吗？→ 问用户」；FFAI 的问题是「这个员工的这个 agent 想做 X，制度允许吗？→ 查 RBAC/配额/审计，实在要问才问」。

5.1 协作模式两轴（直接借 CC）

FFAI 明确选了 CC 的两轴正交而非 Codex 的一维 4 模式：planMode（OFF/REQUIRED，REQUIRED 时 writeAction 工具全不可见）× permissionMode（DEFAULT / ACCEPT_EDITS / BYPASS / READ_ONLY / ASK_EVERY_TIME），session 级字段 + org 级 allowedPermissionModes 白名单（admin 可禁 BYPASS）。切换走 EnterPlanMode/ExitPlanMode/SetPermissionMode 工具（controlTool 不受自身 mode 过滤——否则切不回去）。tools/tool-registry.service.ts:502-520 · prisma platform_ai.prisma:57-58

5.2 双层授权门（CC 无对应）

• RBAC 权限码门（恒 fail-closed，I-41）：声明 availability.permissions 的工具（agent_tools:web/cli/cloud_exec/sql_read…），ctx.permissions 缺省即不可见。#1887 修的正是旧 fail-open 让主 chat 流绕过全部权限门的洞；配套 seed：web/knowledge 授全员 Employee，cli/cloud_exec 仅 Administrator。
• IAM 逐工具 grant/revoke 门（flag 控 fail-open 渐进，I-22）：AIToolGrant 按角色/用户 grant∪revoke，allow 姿态只拦显式 revoke——让授权机制先安全上线再运营收紧。LOCKED_SET 4 项（sessions_send 等）任何姿态恒放行——源自 openclaw「admin 误关 sessions_send，Teams 机器人连『无权限』都发不出」的一年踩坑。

5.3 沙箱对照

5.4 审计：HMAC 哈希链（CC 完全没有的一层）

每个关键事件（TURN_STARTED / ROUTING_DECIDED / TOOL_CALL / STREAM_STALLED… 17 类）append-only 落 agent_trajectory_events，eventHash = HMAC-SHA256(macKey, prevHash + canonicalJson(payload))，macKey 从 KMS root HKDF 派生。用 HMAC 不用裸 sha256：裸哈希链持 DB 写权限者可改 payload 顺链重算蒙混，HMAC 把「能改数据」与「能伪造审计」解耦（对齐 CloudTrail）；verifyChain 不做 legacy 回退防 downgrade。trajectory/trajectory.service.ts:42-137 · GET /agent/trajectory/verify/:sessionId。CC 的 transcript 是本地 JSONL——可读、可回放，但无防篡改语义（也不需要：机主改自己的日志没有审计意义）。

06模型侧：Provider / IR / 路由 / 配额

CC 是「一家厂商 × 四条认证路径」；FFAI 是「五家厂商 × 一个中立 IR × 两个协议编解码器 × 一个路由器」。

6.1 Provider 与协议层

providers/ + protocols/ 结构
Provider 层（5 家 + mock）
  OpenAIProvider     gpt-5.5/5.4/5/5-mini/4o…      openai.provider.ts:29
  AnthropicProvider  claude-opus-4-7/sonnet/haiku   anthropic.provider.ts:25
  GeminiProvider     （走 Google 的 OpenAI 兼容端点） gemini.provider.ts:28
  QwenProvider       （走 dashscope 兼容端点）        qwen.provider.ts:28
  MockProvider       mock-echo/fast/strong           mock.provider.ts:23
       │  每家静态声明 14 项 ProviderCapabilities（vision/audio/pdf/thinking/caching…）
       ▼
Normalized IR（厂商中立，protocols/types.ts）
  NormalizedRequest / NormalizedMessage / ContentPart(text|image|audio|document)
  ProviderStreamChunk: text_delta · tool_call_start/args_delta/done · thinking_* · usage · stop
       │
       ▼  仅 2 个 ProtocolClient 承载全部 5 家
  OpenAIProtocolClient     → OpenAI / Qwen / Gemini（+DeepSeek/Moonshot 预留）
  AnthropicProtocolClient  → Anthropic（+Bedrock/Vertex 预留）
  共用 sse-line-reader（45s stall watchdog）+ retry.ts（5 次指数退避 ±25% jitter）

• 出网合规门：openai/anthropic/gemini 的 isAvailable() 要求 API key 且 FFAI_LLM_EGRESS_COMPLIANCE_CLEARED='true'；qwen（国内）只查 key。CC 无此概念。
• 错误归一化：13 个 NormalizedErrorCode（rate_limit/overloaded/auth_failed/context_overflow/stream_stalled…），HTTP 分类器 429→rate_limit、529→overloaded、400 body 关键词升级 context_overflow/content_filter。CC 的 withRetry 做同样的分类，但不需要归一化——只有一家的错误格式。
• 重试对照：FFAI 5 次 / base 500ms / 2^n / ±25% jitter / Retry-After 优先 / background 遇 overloaded 直接 bail / 连续 3 次 overloaded 触发降级 hook。CC 10 次 / 500ms / 2^n / 0-25% jitter / Retry-After 优先 / 后台请求 529 放弃 / 连续 3 次 529 触发模型 fallback。连「后台请求不重试防容量雪崩」和「3 次过载换模型」这两个细节都对齐了。流式都遵守「已 yield 过就不再重试」（流不幂等）。
• failover 形态：CC 是同厂商换模型（FallbackTriggeredError → fallbackModel）；FFAI 是跨厂商候选链（RoutingDecision.fallbacks），只在 pre-first-chunk 降级、mid-stream 不重放，mock 候选被剔除防「真故障返假输出」。messages.service.ts:2933-2945,1729-1836

6.2 ModelRouter：CC 没有的一整层（G10）

6.3 配额与成本（CC cost-tracker 的企业版）

• 双 scope 月度配额：USER + ORG 并查（USER 拒绝优先），三维额度 tokens/costUsd/containerSeconds（沙箱机时单独记账——换模型不减机时所以不入软上限）；软上限不拒绝只降级（degradeRequested → costPriority='budget' → 路由选便宜模型），硬上限 403。quota/quota.service.ts:45-218
• 预算告警：hitRatio ≥ softLimitRatio 发 soft、≥1.0 发 hard；Redis setNx 去重（同月同档只发一次），USER 走邮件+Teams 私聊、ORG 走 admin 邮箱。CC 无告警（成本显示在 /status）。
• 计价：MODEL_PRICING 前缀匹配价目表（USD/1M token，4 类 token 累加——input/output/cacheRead/cacheCreation，与 CC calculateUSDCost 同款拆分）；未知模型 fallback gpt-4o 量级 + warn 提示补表。sub-agent 成本自动上溯 parent session（CC 的 sidechain 成本也归并主会话——同思路）。quota/model-pricing.ts:33-86 · quota/cost-tracker.service.ts:38-66

07记忆系统：文件化个人记忆 + DB 组织记忆

这一章 FFAI 是 CC 的「学生」——E26 明写移植 Hermes / 对齐 CC memdir，连截断常量都一样；差异全部来自多租户。

08扩展生态：同样的机制，收紧的口径

CC 的七种扩展机制收敛为两种本质（注入文本 / 可调工具），FFAI 全盘继承了这个收敛，然后把每个口子按多租户标准收紧。

8.1 总表对照

另有 CC 没有的一个内置 hook：audit.hook 给全部 13 事件挂 priority 10 的审计钩子，writeAction 工具执行一对一 emit 审计事件（destructive→HIGH），输入截断 4000 字符 + 敏感键 REDACT。hooks/audit.hook.ts:69-138

09多端通道：CC 没有的整个 L0

CC 的 surface 是终端（+SDK）；FFAI 的 surface 是 Web、Teams、桌面、定时任务——同一个 runTurnStream，四种消费方式。

CC 侧最接近的对应物：print 模式（headless 消费同一引擎）≈ FFAI 的 runTurn 同步 wrapper；Agent SDK 控制协议 ≈ FFAI 的 REST+SSE 契约；CronCreate/ScheduleWakeup ≈ FFAI 的 AgentCron（但 CC 的 cron 由 harness 宿主执行，FFAI 是产品功能带投递可靠性不变量）。

10逐层对比总表

一屏看完。粗体 = 该侧独有或明显更强。

11文件索引速查

按「我想看 X」检索，路径相对 backend/src/modules/agent/。