# @ffai/agent-protocol

FFAI Agent 协议类型契约 —— 唯一事实源（PR0.5 monorepo 骨架）。

## 包含

- `SDKMessage` —— Agent QueryEngine 主循环流式消息类型
- `HostBridge` —— surface 宿主能力抽象（Web/Desktop/Mobile 各自实现）
- `A2UIComponent` —— Agent-to-UI 富组件协议（每个组件强制 fallback）

## 消费方

| 消费方 | 用法 |
|---|---|
| `frontend/`（Web） | `import { SDKMessage } from "@ffai/agent-protocol"` |
| `packages/agent-renderer-lark/` | 同上 |
| `desktop/`（Phase 2 Electron） | 同上 |
| `mobile-ios/`（Phase 3） | 通过 codegen 生成 Swift 类型 |
| `mobile-android/`（Phase 3） | 通过 codegen 生成 Kotlin 类型 |

## 不变量

- SDKMessage 字段变更必须先动这个包；下游不同步的 PR 会被 CI 卡死
- 任何 A2UI 组件必须带 `fallback` 字段（CLI / Teams Adaptive Card 降级前提）

详见 `docs/modules/agent/02-architecture.md` §1.1.1。

## 开发

```bash
cd packages/agent-protocol
npm install
npm run build       # tsc → dist/
npm run dev         # watch mode
```

## 范围（PR0.5）

只搭骨架：类型定义 + tsc 构建通过。
具体业务字段的扩充由 PR1（user/assistant/turn_done）/ PR2（model routing 元数据）/ PR3+ 渐进落地。