openfang/plans/radiant-yawning-raven.md

# OpenFang 项目深度分析与头脑风暴报告

## 目录
1. [项目概览](#1-项目概览)
2. [架构深度分析](#2-架构深度分析)
3. [核心优势识别](#3-核心优势识别)
4. [潜在改进领域](#4-潜在改进领域)
5. [技术创新机会](#5-技术创新机会)
6. [生态系统扩展](#6-生态系统扩展)
7. [商业化路径](#7-商业化路径)
8. [头脑风暴：未来方向](#8-头脑风暴未来方向)

---

## 1. 项目概览

### 1.1 基本信息
- **项目名称**: OpenFang - 开源 Agent 操作系统
- **版本**: v0.1.0 (2026-02-24 发布)
- **语言**: Rust (2021 edition)
- **架构**: 14-crate 工作空间
- **测试覆盖**: 1731+ 测试用例

### 1.2 核心定位
OpenFang 是一个用 Rust 编写的 Agent 操作系统，提供完整的 Agent 生命周期管理、多 LLM 提供商支持、40+ 消息渠道集成，以及可视化工作流构建能力。

### 1.3 竞争格局
| 维度 | OpenClaw | OpenFang | 优势方 |
|------|----------|----------|--------|
| 性能/内存 | Node.js (~200MB) | Rust (~30MB) | **OpenFang** |
| 消息渠道 | ~15 | **40+** | **OpenFang** |
| 内置工具 | ~19 | **41** | **OpenFang** |
| 安全系统 | Token + sandbox | **16 层防御** | **OpenFang** |
| Agent 模板 | 手动配置 | **30 预配置** | **OpenFang** |
| 工作流引擎 | Cron + webhooks | **完整 DAG** | **OpenFang** |
| 知识图谱 | 扁平向量存储 | **实体关系图** | **OpenFang** |
| P2P 网络 | 无 | **OFP 协议** | **OpenFang** |
| WASM 沙箱 | 仅 Docker | **双计量 WASM** | **OpenFang** |
| 桌面应用 | Electron (~200MB) | **Tauri (~30MB)** | **OpenFang** |
| LLM 提供商 | ~15 | **27/130+ 模型** | **OpenFang** |
| 可视化构建器 | 无 | **拖拽式** | **OpenFang** |
| 移动应用 | iOS + Android | 仅 Web 响应式 | OpenClaw |
| 语音唤醒 | 有 | 基础语音 | OpenClaw |

**结论**: OpenFang 在 18 个类别中领先 15 个。

---

## 2. 架构深度分析

### 2.1 工作空间结构

```
┌─────────────────────────────────────────────────────────────────┐
│                        表现层 (Presentation)                     │
│         CLI (openfang-cli) / Desktop (Tauri) / HTTP API         │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                         服务层 (Service)                         │
│                      openfang-api (Axum)                        │
│            HTTP/WebSocket/SSE/OpenAI-Compat/A2A                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                          核心层 (Kernel)                         │
│                      openfang-kernel                            │
│     Registry / Scheduler / Supervisor / EventBus / Metering     │
└──────┬────────────────────────────────────────────────┬─────────┘
       │                                                │
┌──────▼──────┐  ┌──────────────┐  ┌───────────────────▼─────────┐
│  Runtime    │  │    Memory    │  │      Integrations           │
│ (LLM/WASM)  │  │ (SQLite/向量)│  │ (channels/skills/hands/ext) │
└──────┬──────┘  └──────────────┘  └─────────────────────────────┘
       │
┌──────▼──────────────────────────────────────────────────────────┐
│                       基础类型层 (Types)                         │
│                     openfang-types                              │
│         Agent / Message / Tool / Config / Error                 │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 Crate 职责矩阵

| Crate | 职责 | 依赖数 | 关键特性 |
|-------|------|--------|----------|
| `openfang-types` | 基础类型定义 | 0 | 零依赖，被所有 crate 使用 |
| `openfang-memory` | 存储层 | 1 | SQLite + 语义搜索 + 知识图谱 |
| `openfang-runtime` | Agent 运行时 | 3 | LLM 驱动 + 工具执行 + WASM |
| `openfang-kernel` | 核心协调器 | 8+ | 组装所有子系统 |
| `openfang-api` | HTTP 服务 | 10+ | 100+ 端点 + WebSocket |
| `openfang-wire` | P2P 协议 | 1 | OFP + HMAC 认证 |
| `openfang-channels` | 消息渠道 | 2 | 40+ 适配器 |
| `openfang-skills` | 技能系统 | 1 | 4 运行时 + 60 技能 |
| `openfang-hands` | 自主能力包 | 2 | 7 预构建 Agent |
| `openfang-extensions` | 集成系统 | 2 | 25+ MCP 模板 |
| `openfang-cli` | 命令行 | 5 | 14+ 子命令 |
| `openfang-desktop` | 桌面应用 | 6 | Tauri 2.0 |
| `openfang-migrate` | 迁移工具 | 2 | OpenClaw 导入 |

### 2.3 关键设计模式

1. **KernelHandle Trait** - 解决 runtime ↔ kernel 循环依赖
2. **Plugin Architecture** - Skills/Hands/Extensions 可扩展
3. **Event-Driven** - EventBus 发布订阅模式
4. **Capability-Based Security** - 细粒度权限控制
5. **Dual Metering** - WASM fuel + epoch 双重限制

---

## 3. 核心优势识别

### 3.1 技术优势

#### 性能优势
- **内存占用**: 30MB vs Electron 200MB (85% 减少)
- **单二进制部署**: 无运行时依赖
- **异步高效**: Tokio 运行时，支持高并发

#### 安全优势 (16 层防御)
1. Capability-based access control
2. Path traversal protection
3. SSRF protection (私有 IP 阻断)
4. Ed25519 signed manifests
5. Merkle hash chain audit
6. Information flow taint tracking
7. HMAC-SHA256 mutual auth
8. API key Bearer auth
9. GCRA rate limiter
10. Security headers (CSP/HSTS/X-Frame-Options)
11. Secret zeroization
12. Subprocess environment isolation
13. Health endpoint redaction
14. Loop guard with SHA256 detection
15. Session repair
16. Circuit breaker thresholds

#### 架构优势
- **模块化**: 清晰的 crate 边界
- **可扩展**: Plugin 系统设计
- **可观测**: Prometheus metrics + audit log

### 3.2 功能优势

| 功能领域 | 具体优势 |
|----------|----------|
| LLM 支持 | 27 提供商 / 130+ 模型 / 智能路由 / Fallback |
| 工具系统 | 41 内置工具 / 动态加载 / Profile 过滤 |
| 工作流 | DAG 引擎 / 并行 / 条件 / 循环 / 可视化构建 |
| 渠道 | 40+ 平台 / 统一抽象 / RBAC |
| Agent | 30 模板 / 多模式调度 / 父子关系 |
| 记忆 | SQLite + 向量 + 知识图谱 |

### 3.3 生态优势

- **SDK**: JavaScript + Python 官方客户端
- **迁移**: OpenClaw 一键导入
- **兼容**: OpenAI API / MCP / A2A 协议
- **桌面**: Tauri 2.0 原生应用

---

## 4. 潜在改进领域

### 4.1 当前短板

| 领域 | 问题描述 | 优先级 |
|------|----------|--------|
| 移动端 | 无原生 iOS/Android 应用 | 高 |
| 语音唤醒 | 缺少 wake word 检测 | 中 |
| 多租户 | 无 SaaS 多租户隔离 | 中 |
| 集群 | 无分布式部署支持 | 中 |
| 可视化调试 | Agent 决策过程不透明 | 低 |
| 测试覆盖 | 缺少 E2E 自动化测试 | 中 |

### 4.2 技术债务

1. **Agent Registry** - 仅内存存储，重启丢失 (部分 SQLite 持久化)
2. **Peer Registry** - 无服务发现，需手动配置节点
3. **知识图谱** - `max_depth` 未完全实现递归遍历
4. **Channels** - 部分适配器未完整测试
5. **WASM** - 仅支持 wasi, 不支持 wasip2

### 4.3 文档缺口

- 缺少架构决策记录 (ADR)
- API 文档未自动生成
- 缺少贡献者指南详细版
- 缺少性能调优指南

---

## 5. 技术创新机会

### 5.1 短期机会 (1-3 个月)

#### A. Agent 编排语言 (Agent Orchestration Language)
```
概念: DSL for multi-agent workflows
价值: 简化复杂 Agent 协作场景
实现: 扩展现有 workflow TOML
示例:
  parallel:
    - agent: researcher
      task: "搜索最新 AI 论文"
    - agent: analyst
      task: "分析市场趋势"
  collect: merge_results
  then:
    agent: writer
    task: "生成报告"
```

#### B. 实时协作层
```
概念: WebSocket-based multi-user sessions
价值: 团队共享 Agent 会话
实现: 扩展 WebSocket 协议
功能:
  - 会话共享/移交
  - 实时光标/选区
  - 评论/批注
```

#### C. Agent 市场
```
概念: 去中心化 Agent 分发
价值: 社区驱动的 Agent 生态
实现:
  - Agent Card 扩展
  - IPFS/去中心化存储
  - 信誉/评分系统
```

### 5.2 中期机会 (3-6 个月)

#### D. 自适应工具学习
```
概念: Agent 自动学习新工具
价值: 减少手动配置
实现:
  - 工具 schema 推断
  - API 文档解析
  - 示例学习
```

#### E. 联邦 Agent 网络
```
概念: 跨组织的 Agent 协作
价值: 隐私保护的分布式 AI
实现:
  - 扩展 OFP 协议
  - 同态加密 (可选)
  - 差分隐私
```

#### F. 多模态 Agent 记忆
```
概念: 图像/音频/视频记忆存储
价值: 更丰富的上下文
实现:
  - 扩展 memory substrate
  - 多模态嵌入
  - 跨模态检索
```

### 5.3 长期机会 (6-12 个月)

#### G. Agent 操作系统内核
```
概念: 真正的 "Agent OS"
价值: 独立的 Agent 运行环境
实现:
  - unikernel 设计
  - 硬件加速
  - 形式化验证
```

#### H. 神经符号 Agent
```
概念: LLM + 规则引擎混合
价值: 可解释 + 灵活
实现:
  - 规则 DSL
  - 神经接口
  - 推理链追踪
```

#### I. Agent 沙箱云
```
概念: 云原生 Agent 执行环境
价值: 弹性扩展 + 隔离
实现:
  - Firecracker microVM
  - Kubernetes operator
  - 按需冷启动
```

---

## 6. 生态系统扩展

### 6.1 技能生态

#### 当前状态
- 60 个内置技能
- 4 种运行时 (Python/WASM/Node/Builtin)
- FangHub 市场

#### 扩展方向
1. **社区技能仓库** - GitHub-based skill distribution
2. **技能版本管理** - 语义化版本 + 依赖解析
3. **技能测试框架** - 自动化技能验证
4. **技能性能分析** - 资源使用监控

### 6.2 渠道生态

#### 当前状态
- 40+ 消息渠道
- 统一 ChannelAdapter trait
- Bridge 管理器

#### 扩展方向
1. **协议适配器** - MQTT/CoAP/AMQP
2. **IoT 网关** - Home Assistant/Philips Hue
3. **企业系统** - SAP/Salesforce/ServiceNow
4. **区块链** - Ethereum/Solana 智能合约

### 6.3 工具生态

#### 当前状态
- 41 个内置工具
- MCP 客户端/服务器
- 动态工具加载

#### 扩展方向
1. **数据库工具** - PostgreSQL/MySQL/MongoDB
2. **云服务工具** - AWS/GCP/Azure SDK
3. **数据分析工具** - Pandas/Polars 集成
4. **安全工具** - 漏洞扫描/渗透测试

---

## 7. 商业化路径

### 7.1 开源核心模式 (Open Core)

| 层级 | 功能 | 授权 |
|------|------|------|
| 核心 | Agent 运行时 + 基础工具 | MIT/Apache |
| Pro | 高级工作流 + 企业渠道 | 商业 |
| Enterprise | SSO + 审计 + SLA | 商业 |
| Cloud | 托管服务 + 自动扩展 | SaaS |

### 7.2 潜在收入流

1. **企业许可** - 大规模部署授权
2. **云托管** - OpenFang Cloud (类似 OpenAI Assistants)
3. **专业服务** - 咨询/定制开发/培训
4. **市场抽成** - Hands/Skills 市场交易费
5. **支持订阅** - 技术支持 + SLA

### 7.3 竞争定位

```
价格
  │
  │     ┌──────────────────┐
  │     │   OpenAI         │
  │     │   Assistants     │
  │     └──────────────────┘
  │           ▲
  │     ┌─────┴────────┐
  │     │  OpenFang    │
  │     │  Cloud       │
  │     └──────────────┘
  │           ▲
  │     ┌─────┴────────┐
  │     │  OpenFang    │
  │     │  Enterprise  │
  │     └──────────────┘
  │           ▲
  │     ┌─────┴────────┐
  │     │  OpenFang    │ ◄── 开源免费
  │     │  Core        │
  │     └──────────────┘
  └──────────────────────────────────► 功能
        基础    Pro    Enterprise
```

---

## 8. 头脑风暴：未来方向

### 8.1 产品愿景

**"成为 Agent 时代的 Linux"**

- 像 Linux 是服务器操作系统一样
- OpenFang 成为 Agent 操作系统
- 开放、可扩展、高性能

### 8.2 技术路线图建议

#### Phase 1: 巩固基础 (Q2 2026)
- [ ] 完善测试覆盖率 (目标 90%+)
- [ ] 性能基准测试 + 优化
- [ ] 文档自动化 (API/架构)
- [ ] 移动端 Web PWA

#### Phase 2: 生态扩展 (Q3 2026)
- [ ] 社区技能市场
- [ ] 第三方工具 SDK
- [ ] Agent 模板贡献流程
- [ ] 多语言 SDK (Go/Java/Rust)

#### Phase 3: 企业就绪 (Q4 2026)
- [ ] 多租户架构
- [ ] SSO 集成 (SAML/OIDC)
- [ ] 合规认证 (SOC2/GDPR)
- [ ] 企业支持计划

#### Phase 4: 云原生 (2027)
- [ ] Kubernetes Operator
- [ ] Serverless Agent 执行
- [ ] 多区域部署
- [ ] 联邦学习支持

### 8.3 创新实验项目

#### 项目 A: Agent 梦境
```
概念: Agent 空闲时自主探索/学习
实现:
  - 后台思考循环
  - 知识整合
  - 技能优化
启发: 人类睡眠学习
```

#### 项目 B: Agent 人格持久化
```
概念: 可移植的 Agent 身份/记忆
实现:
  - 加密身份包
  - 跨平台迁移
  - 人格市场
启发: 数字孪生
```

#### 项目 C: Agent 宪法
```
概念: 可配置的行为准则
实现:
  - 宪法 DSL
  - 行为审计
  - 违规纠正
启发: AI 对齐研究
```

#### 项目 D: 群体智能
```
概念: Agent 蜂群协作
实现:
  -涌现行为
  - 自组织
  - 分布式决策
启发: 蚁群/蜂群算法
```

### 8.4 关键成功因素

| 因素 | 当前状态 | 目标状态 |
|------|----------|----------|
| 社区活跃度 | 起步阶段 | 活跃贡献者 100+ |
| 企业采用 | 无 | 10+ 企业客户 |
| 文档质量 | 基础 | 完整 + 示例 |
| 性能 | 优秀 | 行业领先 |
| 安全 | 16 层 | 认证级别 |
| 生态 | 60 技能 | 500+ 技能 |

### 8.5 风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| LLM 提供商封锁 | 中 | 高 | 多提供商 + 本地模型 |
| 竞争对手复制 | 高 | 中 | 快速迭代 + 社区壁垒 |
| 安全漏洞 | 中 | 高 | 审计 + 赏金计划 |
| 许可证纠纷 | 低 | 高 | 法律审查 + CLA |
| 核心开发者流失 | 中 | 高 | 文档 + 知识传递 |

---

## 总结

OpenFang 是一个技术扎实、架构清晰的 Agent 操作系统。它在性能、安全、功能丰富度方面相比竞争对手有显著优势。未来的成功取决于：

1. **生态建设** - 社区驱动的技能/Agent/工具生态
2. **企业采用** - 从开源项目到企业解决方案
3. **持续创新** - 在 Agent 编排、多模态、群体智能等方向探索
4. **商业模式** - 找到可持续的开源商业化路径

**核心建议**: 专注于 "开发者体验" 和 "企业就绪" 两条主线，同时保持开源社区的活力。

---

# 附录：详细执行计划

以下是根据用户需求制定的四个详细方向计划。

---

## 附录 A: 具体功能实现计划

### A.1 Agent 编排语言 (AOL) - 详细设计

#### 目标
创建一种声明式 DSL，简化多 Agent 协作场景的配置。

#### 核心语法设计
```toml
# workflow.toml
[workflow]
name = "research-pipeline"
description = "研究 -> 分析 -> 写作 流水线"

[workflow.steps]
# 并行执行阶段
[[workflow.steps.parallel]]
agent = "researcher"
task = "搜索关于 {{topic}} 的最新研究论文"
output = "papers"

[[workflow.steps.parallel]]
agent = "analyst"
task = "分析 {{topic}} 的市场趋势"
output = "market_analysis"

# 收集阶段
[workflow.steps.collect]
strategy = "merge"  # merge, concatenate, first_non_empty
inputs = ["papers", "market_analysis"]
output = "combined_research"

# 串行阶段
[[workflow.steps.sequential]]
agent = "writer"
task = "基于 {{combined_research}} 生成报告"
output = "final_report"

# 条件分支
[workflow.steps.condition]
if = "{{complexity_score}} > 0.8"
then = { agent = "expert", task = "审核报告" }
else = { agent = "editor", task = "编辑报告" }
```

#### 实现计划

| 阶段 | 任务 | 文件 | 预估时间 |
|------|------|------|----------|
| 1 | 定义 AST 类型 | `openfang-types/src/workflow_dsl.rs` | 2 天 |
| 2 | TOML 解析器 | `openfang-runtime/src/workflow/parser.rs` | 3 天 |
| 3 | 变量展开引擎 | `openfang-runtime/src/workflow/variables.rs` | 2 天 |
| 4 | 并行执行器 | `openfang-runtime/src/workflow/parallel.rs` | 3 天 |
| 5 | 条件分支 | `openfang-runtime/src/workflow/condition.rs` | 2 天 |
| 6 | API 端点 | `openfang-api/src/routes.rs` | 1 天 |
| 7 | UI 集成 | `static/js/pages/workflows.js` | 2 天 |
| 8 | 测试 | `tests/workflow_dsl_test.rs` | 2 天 |

**总计**: ~17 天

#### API 设计
```
POST /api/workflows/compile
  Body: { "toml": "..." }
  Response: { "ast": {...}, "validation_errors": [] }

POST /api/workflows/{id}/execute
  Body: { "variables": {...} }
  Response: { "execution_id": "...", "status": "running" }

GET /api/workflows/{id}/executions/{exec_id}
  Response: { "status": "...", "steps": [...], "outputs": {...} }
```

---

### A.2 实时协作层 - 详细设计

#### 目标
支持多用户实时共享 Agent 会话。

#### 协议设计
```json
// 客户端 -> 服务器
{
  "type": "session_join",
  "session_id": "uuid",
  "user_id": "uuid",
  "cursor": { "line": 10, "column": 5 }
}

// 服务器 -> 客户端 (广播)
{
  "type": "presence_update",
  "users": [
    { "id": "uuid", "name": "Alice", "cursor": {...}, "color": "#ff0000" }
  ]
}

// 评论/批注
{
  "type": "annotation",
  "message_id": "uuid",
  "user_id": "uuid",
  "content": "这个回答不准确",
  "range": { "start": 0, "end": 50 }
}
```

#### 实现计划

| 阶段 | 任务 | 文件 | 预估时间 |
|------|------|------|----------|
| 1 | 扩展 WebSocket 协议 | `openfang-api/src/ws.rs` | 2 天 |
| 2 | Presence 管理器 | `openfang-kernel/src/presence.rs` | 2 天 |
| 3 | 注释存储 | `openfang-memory/src/annotations.rs` | 2 天 |
| 4 | 前端 Presence UI | `static/js/components/presence.js` | 3 天 |
| 5 | 前端注释 UI | `static/js/components/annotations.js` | 2 天 |
| 6 | 测试 | `tests/collab_test.rs` | 2 天 |

**总计**: ~13 天

---

### A.3 Agent 市场 - 详细设计

#### 目标
创建去中心化的 Agent 分发平台。

#### Agent Card 扩展
```json
{
  "schema_version": "2.0",
  "id": "com.example.researcher",
  "name": "Research Agent",
  "description": "高级研究助手",
  "version": "1.2.0",
  "author": { "name": "OpenFang Team", "verified": true },
  "category": "research",
  "tags": ["web-search", "analysis", "citations"],
  "rating": { "average": 4.8, "count": 1250 },
  "downloads": 15000,
  "price": "free",
  "license": "MIT",
  "manifest_url": "ipfs://QmXxx...",
  "signature": "ed25519:..."
}
```

#### 实现计划

| 阶段 | 任务 | 预估时间 |
|------|------|----------|
| 1 | Agent Card v2 schema | 1 天 |
| 2 | IPFS 集成 | 3 天 |
| 3 | 签名验证 | 2 天 |
| 4 | 评分系统 | 2 天 |
| 5 | 搜索索引 | 2 天 |
| 6 | UI 市场页面 | 3 天 |
| 7 | 一键安装 | 2 天 |

**总计**: ~15 天

---

## 附录 B: 深入架构分析

### B.1 Kernel 模块深度分析

#### 核心结构
```rust
// openfang-kernel/src/kernel.rs
pub struct OpenFangKernel {
    // 配置
    pub config: KernelConfig,

    // Agent 管理
    pub registry: AgentRegistry,        // Agent 注册表
    pub scheduler: AgentScheduler,       // 资源调度
    pub supervisor: Supervisor,          // 进程监控

    // 存储
    pub memory: Arc<MemorySubstrate>,    // 统一存储

    // 事件
    pub event_bus: EventBus,             // 发布订阅

    // 执行
    pub workflows: WorkflowEngine,       // 工作流
    pub triggers: TriggerEngine,         // 触发器
    pub background: BackgroundExecutor,  // 后台任务

    // 安全
    pub audit_log: Arc<AuditLog>,        // 审计日志
    pub auth: AuthManager,               // RBAC
    pub capabilities: CapabilityManager, // 权限

    // 计量
    pub metering: Arc<MeteringEngine>,   // 成本追踪

    // LLM
    pub default_driver: Arc<dyn LlmDriver>,
    pub model_catalog: RwLock<ModelCatalog>,

    // 扩展
    pub skill_registry: RwLock<SkillRegistry>,
    pub hand_registry: HandRegistry,
    pub extension_registry: RwLock<IntegrationRegistry>,
    pub mcp_connections: Mutex<Vec<McpConnection>>,

    // 网络
    pub peer_registry: Option<PeerRegistry>,
    pub peer_node: Option<Arc<PeerNode>>,
    pub channel_adapters: DashMap<String, Arc<dyn ChannelAdapter>>,

    // ... 更多字段
}
```

#### 关键流程

**1. Agent 创建流程**
```
spawn_agent_with_parent()
  │
  ├─→ 生成 AgentId (UUID v4)
  ├─→ 创建 Session (MemorySubstrate)
  ├─→ 创建工作区目录结构
  │     ├── data/
  │     ├── output/
  │     ├── sessions/
  │     ├── skills/
  │     ├── logs/
  │     └── memory/
  ├─→ 生成身份文件
  │     ├── SOUL.md
  │     ├── USER.md
  │     ├── TOOLS.md
  │     ├── MEMORY.md
  │     ├── AGENTS.md
  │     ├── BOOTSTRAP.md
  │     └── IDENTITY.md
  ├─→ 注册能力 (CapabilityManager)
  ├─→ 注册调度 (AgentScheduler)
  ├─→ 创建 AgentEntry
  ├─→ 持久化到 SQLite
  ├─→ 记录审计日志
  └─→ 发布 AgentSpawned 事件
```

**2. 消息处理流程**
```
send_message_streaming()
  │
  ├─→ 检查配额 (Scheduler)
  ├─→ 获取 Agent Entry (Registry)
  ├─→ 构建系统提示词 (PromptBuilder)
  │     ├── 基础提示词
  │     ├── 召回记忆 (MemorySubstrate)
  │     ├── 身份文件
  │     └── 技能上下文
  ├─→ 准备工具定义 (CapabilityManager)
  ├─→ 调用 run_agent_loop_streaming()
  │     │
  │     ├─→ 上下文管理
  │     │     ├── Token 估算
  │     │     ├── 溢出恢复
  │     │     └── 紧急压缩
  │     │
  │     ├─→ LLM 调用 (带重试/熔断)
  │     │     ├── call_with_retry()
  │     │     └── stream_with_retry()
  │     │
  │     └─→ 响应处理
  │           ├── EndTurn → 返回结果
  │           ├── ToolUse → 执行工具 → 循环
  │           └── MaxTokens → 继续生成
  │
  ├─→ 保存会话 (MemorySubstrate)
  ├─→ 更新计量 (MeteringEngine)
  └─→ 返回响应
```

### B.2 Runtime 模块深度分析

#### Agent Loop 核心逻辑
```rust
// openfang-runtime/src/agent_loop.rs

pub async fn run_agent_loop_streaming(
    kernel: &dyn KernelHandle,
    agent_id: AgentId,
    session_id: SessionId,
    user_message: String,
    tx: Sender<StreamEvent>,
) -> Result<AgentLoopResult, AgentLoopError> {

    let mut iterations = 0;
    let mut messages = load_history(&session_id)?;

    // 添加用户消息
    messages.push(Message {
        role: Role::User,
        content: MessageContent::Text(user_message),
    });

    loop {
        iterations += 1;

        // 安全检查
        if iterations > MAX_ITERATIONS {
            return Err(AgentLoopError::MaxIterationsExceeded);
        }

        // 上下文管理
        if needs_compaction(&messages)? {
            messages = compact_messages(&messages)?;
        }

        // 构建 LLM 请求
        let request = CompletionRequest {
            model: model_id.clone(),
            messages: messages.clone(),
            tools: available_tools.clone(),
            max_tokens,
            temperature,
            system_prompt: build_system_prompt()?,
        };

        // 调用 LLM (流式)
        let response = driver.stream(request, tx.clone()).await?;

        // 处理响应
        match response.stop_reason {
            StopReason::EndTurn => {
                // 保存会话
                save_session(&session_id, &messages)?;
                return Ok(AgentLoopResult {
                    response: response.content,
                    iterations,
                });
            }

            StopReason::ToolUse => {
                // 执行工具
                for tool_call in response.tool_calls {
                    let result = execute_tool(&tool_call, kernel).await?;
                    messages.push(Message {
                        role: Role::User,
                        content: MessageContent::Blocks(vec![
                            ContentBlock::ToolResult(result)
                        ]),
                    });
                }
                // 继续循环
            }

            StopReason::MaxTokens => {
                // 继续生成
                continue;
            }
        }
    }
}
```

### B.3 Memory 模块深度分析

#### 三层存储架构
```
┌─────────────────────────────────────────────────────────────┐
│                    MemorySubstrate                          │
│                    (统一接口层)                              │
└───────────────────────────┬─────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Structured  │   │   Semantic    │   │   Knowledge   │
│   (SQLite)    │   │   (Vector)    │   │   (Graph)     │
└───────────────┘   └───────────────┘   └───────────────┘
        │                   │                   │
        ▼                   ▼                   ▼
  KV Store            Embedding            Entity-Relation
  Sessions            Similarity           Graph Queries
  Agent State         Search               Traversal
```

#### 知识图谱实现
```rust
// openfang-memory/src/knowledge.rs

pub struct KnowledgeGraph {
    conn: rusqlite::Connection,
}

impl KnowledgeGraph {
    // 添加实体
    pub fn add_entity(&self, entity: &Entity) -> Result<String, Error> {
        let id = uuid();
        self.conn.execute(
            "INSERT INTO entities (id, entity_type, name, properties) VALUES (?1, ?2, ?3, ?4)",
            params![id, entity.entity_type, entity.name, json!(entity.properties)]
        )?;
        Ok(id)
    }

    // 添加关系
    pub fn add_relation(&self, relation: &Relation) -> Result<(), Error> {
        self.conn.execute(
            "INSERT INTO relations (source_id, target_id, relation_type, properties)
             VALUES (?1, ?2, ?3, ?4)",
            params![relation.source_id, relation.target_id,
                    relation.relation_type, json!(relation.properties)]
        )
    }

    // 图查询
    pub fn query(&self, pattern: &GraphPattern) -> Result<Vec<GraphMatch>, Error> {
        // 支持: 实体类型过滤、关系类型过滤、属性匹配
        // TODO: max_depth 递归遍历
    }
}
```

### B.4 架构改进建议

| 问题 | 当前状态 | 建议改进 | 优先级 |
|------|----------|----------|--------|
| Agent Registry 持久化 | 部分持久化 | 完全持久化 + WAL | 高 |
| 知识图谱递归遍历 | 未实现 | 实现 `max_depth` 遍历 | 中 |
| Peer 服务发现 | 手动配置 | mDNS/DNS-SD 自动发现 | 中 |
| WASM 运行时 | wasi only | 升级到 wasip2 | 低 |
| 热重载粒度 | 文件级别 | 字段级别 diff | 低 |

---

## 附录 C: 商业策略规划

### C.1 产品分层设计

#### OpenFang Core (开源免费)
```
功能:
- 完整 Agent 运行时
- 41 个内置工具
- 27 个 LLM 提供商
- 基础工作流引擎
- SQLite 存储
- 命令行工具
- Web UI
- 40 个消息渠道

限制:
- 单租户
- 无 SSO
- 社区支持
```

#### OpenFang Pro ($99/月)
```
额外功能:
- 高级工作流模板
- 企业渠道 (SAP/Salesforce)
- 优先级支持
- 月度功能抢先体验
- 技能市场高级内容
```

#### OpenFang Enterprise (定制报价)
```
额外功能:
- 多租户架构
- SSO (SAML/OIDC)
- 完整审计日志
- SLA 保证
- 专属客户经理
- 定制开发
- 培训服务
```

#### OpenFang Cloud (按使用计费)
```
定价模型:
- Agent 执行: $0.001/请求
- LLM 代理: 成本 + 10%
- 存储: $0.10/GB/月
- 带宽: $0.05/GB

免费层:
- 10,000 请求/月
- 1 GB 存储
- 5 GB 带宽
```

### C.2 市场进入策略

#### 第一阶段: 开发者采用 (0-6 个月)
```
目标: 1,000+ GitHub Stars, 100+ 活跃用户

策略:
1. Hacker News / Reddit 发布
2. AI/ML 会议演讲
3. 技术博客系列
4. 开发者文档完善
5. 社区 Discord/论坛

KPI:
- GitHub Stars: 1,000+
- 周活跃用户: 100+
- PR 贡献者: 20+
```

#### 第二阶段: 中小企业 (6-12 个月)
```
目标: 10+ 付费客户, $10K MRR

策略:
1. 产品引导式试用
2. 案例研究发布
3. 合作伙伴计划
4. 内容营销 (SEO)
5. 网络研讨会

KPI:
- 付费客户: 10+
- MRR: $10K
- 转化率: 5%
```

#### 第三阶段: 企业市场 (12-24 个月)
```
目标: 5+ 企业客户, $100K MRR

策略:
1. 企业销售团队
2. 合规认证 (SOC2)
3. Gartner/CB Insights 报道
4. 行业会议赞助
5. 咨询合作伙伴

KPI:
- 企业客户: 5+
- MRR: $100K
- 客户留存: 90%+
```

### C.3 竞争差异化

| 维度 | OpenAI Assistants | LangChain | AutoGPT | OpenFang |
|------|-------------------|-----------|---------|----------|
| 开源 | ❌ | ✅ | ✅ | ✅ |
| 自托管 | ❌ | ✅ | ✅ | ✅ |
| 性能 | 云端 | Python | Python | **Rust** |
| 工具生态 | 有限 | 丰富 | 中等 | **41+40 渠道** |
| 工作流 | 基础 | 链式 | 自主 | **DAG+可视化** |
| 安全 | 云端信任 | 用户负责 | 用户负责 | **16 层** |
| 成本 | 高 | LLM 费用 | LLM 费用 | **透明** |

### C.4 收入预测

```
年份          2026      2027      2028
─────────────────────────────────────
Pro 订阅      $50K      $200K     $500K
Enterprise    $100K     $500K     $2M
Cloud         $20K      $300K     $1M
服务收入      $30K      $200K     $500K
─────────────────────────────────────
总计          $200K     $1.2M     $4M
```

---

## 附录 D: 技术债务修复计划

### D.1 高优先级债务

#### D.1.1 Agent Registry 完全持久化
```
问题: Agent 元数据重启后部分丢失
影响: 用户体验差，生产环境不可靠

修复方案:
1. 所有 AgentEntry 写入 SQLite
2. 启动时从 SQLite 恢复
3. 使用 WAL 模式提高可靠性
4. 添加定期快照备份

文件:
- crates/openfang-kernel/src/registry.rs
- crates/openfang-memory/src/structured.rs

预估: 3 天
```

#### D.1.2 E2E 测试框架
```
问题: 缺少端到端自动化测试
影响: 回归风险高，发布信心不足

修复方案:
1. 使用 Playwright/Cypress
2. 覆盖核心用户流程:
   - Agent 创建/对话/删除
   - 工作流创建/执行
   - 渠道配置/测试
3. CI/CD 集成
4. 每日运行

文件:
- tests/e2e/

预估: 5 天
```

### D.2 中优先级债务

#### D.2.1 知识图谱递归遍历
```
问题: max_depth 参数未实现
影响: 复杂关系查询不支持

修复方案:
1. 实现递归 CTE 查询
2. 添加深度限制保护
3. 性能优化 (索引)

文件:
- crates/openfang-memory/src/knowledge.rs

预估: 2 天
```

#### D.2.2 Peer 服务发现
```
问题: 需手动配置节点地址
影响: P2P 网络扩展困难

修复方案:
1. mDNS/DNS-SD 本地发现
2. Bootstrap 节点列表
3. DHT 分布式发现 (可选)

文件:
- crates/openfang-wire/src/discovery.rs (新建)

预估: 4 天
```

#### D.2.3 文档自动化
```
问题: API 文档手动维护
影响: 文档与代码不同步

修复方案:
1. utoipa 自动生成 OpenAPI
2. cargo-doc 自动化
3. CI 自动部署

预估: 2 天
```

### D.3 低优先级债务

#### D.3.1 WASM wasip2 支持
```
问题: 仅支持 wasi preview 1
影响: 部分现代 WASM 模块不支持

修复方案:
1. 升级 Wasmtime
2. 测试兼容性
3. 更新文档

预估: 3 天
```

#### D.3.2 配置热重载优化
```
问题: 文件级别重载，粒度粗
影响: 不必要的重启

修复方案:
1. 字段级别 diff
2. 精确热更新
3. 变更通知

预估: 2 天
```

### D.4 技术债务修复时间线

```
周次    任务
────────────────────────────────
W1      Agent Registry 持久化
W2      E2E 测试框架搭建
W3      E2E 核心流程覆盖
W4      知识图谱递归遍历
W5      Peer 服务发现
W6      文档自动化
W7-8    WASM 升级 + 热重载优化
```

---

## 附录 E: 行动计划总结

### 优先级矩阵

```
                    高业务价值
                        │
         ┌──────────────┼──────────────┐
         │              │              │
    Agent 市场      实时协作      企业功能
    创新功能        用户粘性      商业化
         │              │              │
低复杂度 ─┼──────────────┼──────────────┼─ 高复杂度
         │              │              │
    技术债务        AOL DSL      云原生
    稳定性          生产力        扩展性
         │              │              │
         └──────────────┼──────────────┘
                        │
                    低业务价值
```

### 推荐执行顺序

1. **立即开始** (Week 1-4)
   - Agent Registry 持久化
   - E2E 测试框架
   - 实时协作层

2. **短期目标** (Month 2-3)
   - Agent 编排语言 (AOL)
   - Agent 市场
   - 企业功能 (SSO/多租户)

3. **中期目标** (Month 4-6)
   - 云原生架构
   - 联邦 Agent 网络
   - 多模态记忆

4. **长期愿景** (Month 7-12)
   - Agent OS 内核
   - 神经符号 Agent
   - 群体智能

---

## 附录 F: 实施记录

### F.1 添加智谱 GLM-5 和百炼 Coding Plan 支持 (2026-03-01)

#### 变更摘要

本次更新为 OpenFang 添加了对以下新模型和提供商的支持：

1. **智谱 GLM-5** - 智谱 AI 最新旗舰模型
   - GLM-5: 744B 总参数，40B 激活参数，200K 上下文
   - GLM-5 Flash: 轻量级版本

2. **阿里云百炼 Coding Plan** - 编程订阅服务
   - qwen3.5-plus
   - qwen3-coder-next
   - glm-5-bailian
   - minimax-m2.5-bailian
   - kimi-k2.5-bailian

#### 修改的文件

| 文件 | 更改 |
|------|------|
| `crates/openfang-types/src/model_catalog.rs` | 添加 `BAILIAN_BASE_URL` 常量 |
| `crates/openfang-runtime/src/model_catalog.rs` | 添加 GLM-5 模型、百炼提供商和 Coding Plan 模型 |
| `crates/openfang-runtime/src/drivers/mod.rs` | 添加百炼提供商支持和测试 |

#### 配置示例

```toml
# 使用智谱 GLM-5
[default_model]
provider = "zhipu"
model = "glm-5"
api_key_env = "ZHIPU_API_KEY"

# 使用百炼 Coding Plan
[default_model]
provider = "bailian"
model = "qwen3-coder-next"
api_key_env = "BAILIAN_API_KEY"
```

#### 新增模型列表

**智谱 GLM 系列 (新增 2 个)**:
- `glm-5` - 旗舰模型，200K 上下文
- `glm-5-flash` - 快速版本

**百炼 Coding Plan (新增 5 个)**:
- `qwen3.5-plus` - Qwen 3.5 Plus
- `qwen3-coder-next` - Qwen 3 Coder Next
- `glm-5-bailian` - GLM-5 (通过百炼)
- `minimax-m2.5-bailian` - MiniMax M2.5 (通过百炼)
- `kimi-k2.5-bailian` - Kimi K2.5 (通过百炼)

#### 验证步骤

```bash
# 1. 构建项目
cargo build --workspace --lib

# 2. 运行测试
cargo test --workspace

# 3. 启动守护进程
ZHIPU_API_KEY=your_key target/release/openfang.exe start

# 4. 测试 GLM-5
curl -s -X POST "http://127.0.0.1:4200/api/agents" \
  -H "Content-Type: application/json" \
  -d '{"name": "glm5-test", "model": {"provider": "zhipu", "model": "glm-5"}}'

# 5. 测试百炼 Coding Plan
BAILIAN_API_KEY=your_key target/release/openfang.exe start

curl -s -X POST "http://127.0.0.1:4200/api/agents" \
  -H "Content-Type: application/json" \
  -d '{"name": "bailian-test", "model": {"provider": "bailian", "model": "qwen3-coder-next"}}'
```

---

## 附录 G: Agent Registry 持久化修复 (2026-03-01)

### 问题分析

原有实现中，以下 Agent 修改操作只更新内存中的 DashMap，不持久化到 SQLite：
- `set_mode` - Agent 模式切换
- `set_state` - Agent 状态更新
- `update_identity` - Agent 身份信息更新
- `update_name` - Agent 名称更新
- `update_description` - Agent 描述更新

这导致重启后这些修改会丢失。

### 解决方案

1. **在 `kernel.rs` 添加包装方法**：每个方法先更新 registry（内存），然后调用 `memory.save_agent()` 持久化

2. **更新 `routes.rs` 调用**：将直接调用 `registry.xxx()` 改为调用 `kernel.xxx()` 方法

### 修改的文件

| 文件 | 更改 |
|------|------|
| `crates/openfang-kernel/src/kernel.rs` | 添加 5 个新方法: `set_agent_state`, `set_agent_mode`, `update_agent_identity`, `update_agent_name`, `update_agent_description` |
| `crates/openfang-api/src/routes.rs` | 更新调用: `registry.set_mode` → `kernel.set_agent_mode`, `registry.update_identity` → `kernel.update_agent_identity`, 等 |
| `crates/openfang-kernel/src/registry.rs` | 添加 8 个新测试用例 |

### 新增的 Kernel 方法

```rust
/// Set an agent's state with persistence.
pub fn set_agent_state(&self, agent_id: AgentId, state: AgentState) -> KernelResult<()>

/// Set an agent's mode with persistence.
pub fn set_agent_mode(&self, agent_id: AgentId, mode: AgentMode) -> KernelResult<()>

/// Update an agent's identity with persistence.
pub fn update_agent_identity(&self, agent_id: AgentId, identity: AgentIdentity) -> KernelResult<()>

/// Update an agent's name with persistence.
pub fn update_agent_name(&self, agent_id: AgentId, name: String) -> KernelResult<()>

/// Update an agent's description with persistence.
pub fn update_agent_description(&self, agent_id: AgentId, description: String) -> KernelResult<()>
```

### 验证

```bash
# 运行 registry 测试
cargo test -p openfang-kernel registry

# 预期输出
# test_register_and_get ... ok
# test_find_by_name ... ok
# test_duplicate_name ... ok
# test_remove ... ok
# test_set_state ... ok
# test_set_mode ... ok
# test_update_identity ... ok
# test_update_name ... ok
# test_update_description ... ok
# test_update_model ... ok
# test_update_skills ... ok
# test_update_mcp_servers ... ok
```

### 已验证的持久化操作

| 操作 | 内存 | SQLite | 状态 |
|------|------|--------|------|
| `spawn_agent` | ✅ | ✅ | 正常 |
| `kill_agent` | ✅ | ✅ | 正常 |
| `set_agent_state` | ✅ | ✅ | **已修复** |
| `set_agent_mode` | ✅ | ✅ | **已修复** |
| `update_agent_identity` | ✅ | ✅ | **已修复** |
| `update_agent_name` | ✅ | ✅ | **已修复** |
| `update_agent_description` | ✅ | ✅ | **已修复** |
| `update_agent_model` | ✅ | ✅ | 正常 |
| `update_agent_system_prompt` | ✅ | ✅ | 正常 |
| `set_agent_skills` | ✅ | ✅ | 正常 |
| `set_agent_mcp_servers` | ✅ | ✅ | 正常 |

---

## 附录 H: 知识图谱递归遍历设计 (2026-03-01)

### 问题分析

当前 `query_graph` 方法的 `max_depth` 参数完全未实现，只支持单跳查询 (depth=1)。

### 解决方案: 递归 CTE 查询

```sql
WITH RECURSIVE graph_path AS (
    -- 基础情况: depth = 1
    SELECT r.id, r.source_entity, r.relation_type, r.target_entity,
           r.properties, r.confidence, 1 as depth
    FROM relations r
    WHERE 1=1
    {source_filter}
    {relation_filter}

    UNION ALL

    -- 递归情况
    SELECT r.id, r.source_entity, r.relation_type, r.target_entity,
           r.properties, r.confidence, gp.depth + 1
    FROM relations r
    INNER JOIN graph_path gp ON r.source_entity = gp.target_entity
    WHERE gp.depth < ?1
)
SELECT ... FROM graph_path ...
```

### 安全限制

- 最大深度: 10 (防止滥用)
- 环路检测: 使用 HashSet 或 CTE 路径追踪
- 结果限制: LIMIT 1000

### 修改文件

- `crates/openfang-memory/src/knowledge.rs` - 实现递归 CTE

---

## 附录 I: 实时协作层架构设计 (2026-03-01)

### 核心组件

1. **PresenceManager** - 管理用户在线状态
2. **CollabSession** - 协作会话状态
3. **AnnotationStore** - 评论/批注存储

### WebSocket 协议扩展

```json
// 客户端 -> 服务器
{"type": "collab_join", "session_id": "uuid"}
{"type": "cursor", "line": 10, "column": 5}
{"type": "handover_request", "target_user_id": "..."}

// 服务器 -> 客户端
{"type": "presence_update", "users": [...]}
{"type": "cursor_update", "connection_id": "...", "cursor": {...}}
{"type": "user_joined", "connection_id": "...", "display_name": "..."}
```

### 数据库扩展 (Migration v8)

```sql
CREATE TABLE annotations (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    annotation_type TEXT NOT NULL DEFAULT 'comment',
    content TEXT NOT NULL,
    message_index INTEGER NOT NULL,
    char_start INTEGER, char_end INTEGER,
    parent_id TEXT,
    status TEXT DEFAULT 'open',
    created_at TEXT NOT NULL
);
```

### 实现阶段

1. Phase 1: Presence 基础设施
2. Phase 2: 会话共享
3. Phase 3: 注释存储
4. Phase 4: 前端集成
5. Phase 5: 测试与优化

---

## 附录 J: Agent 编排语言 (AOL) 设计 (2026-03-01)

### DSL 语法 (TOML)

```toml
[workflow]
name = "research-pipeline"
version = "1.0.0"

[workflow.input]
topic = { type = "string", required = true }

[[workflow.steps.parallel]]
id = "search_papers"
agent = "researcher"
task = "Search for papers about {{input.topic}}"
output = "papers"

[workflow.steps.collect]
strategy = "merge"
inputs = ["papers", "market_data"]
output = "combined"

[[workflow.steps.conditional]]
id = "expert_review"
condition = "{{input.depth}} == 'exhaustive'"
agent = "reviewer"
task = "Review: {{draft_report}}"
```

### AST 核心类型

```rust
pub struct AolWorkflow {
    pub id: WorkflowDefId,
    pub name: String,
    pub input: HashMap<String, InputParam>,
    pub steps: Vec<AolStep>,
    pub outputs: HashMap<String, String>,
}

pub enum AolStep {
    Parallel(ParallelStepGroup),
    Sequential(SequentialStep),
    Conditional(ConditionalStep),
    Loop(LoopStep),
    Collect(CollectStep),
    Subworkflow(SubworkflowStep),
}
```

### 执行引擎

- DAG 构建与拓扑排序
- 并行执行支持
- 模板变量展开
- 错误处理与重试

### 新增文件

- `crates/openfang-types/src/aol.rs` - AST 类型定义
- `crates/openfang-kernel/src/aol_executor.rs` - 执行引擎
- `crates/openfang-kernel/src/aol/template.rs` - 模板引擎

---

## 附录 K: CLAUDE.md 开发规则更新 (2026-03-01)

### 新增规则类别

1. **架构规则** - 14-crate 结构、依赖关系、职责边界
2. **持久化规则** - 内存+SQLite 双写模式
3. **API 开发规则** - 路由注册、类型匹配、错误处理
4. **安全规则** - 16 层安全架构清单
5. **测试规则** - 单元测试、集成测试、E2E 测试
6. **前端规则** - Alpine.js SPA 开发模式
7. **LLM 提供商规则** - 添加新提供商的步骤

### 关键规则摘要

| 规则 | 描述 |
|------|------|
| 双写模式 | 所有修改操作必须同时更新内存和 SQLite |
| Kernel 包装 | API 层调用 kernel 方法，不直接调用 registry |
| 路由注册 | 新路由必须在 server.rs 和 routes.rs 两处注册 |
| 配置字段 | 需要 struct 字段 + `#[serde(default)]` + Default impl |
| 类型位置 | 共享类型放 openfang-types，特有类型放对应 crate |

---

## 附录 L: 实现完成记录 (2026-03-01)

### 知识图谱递归遍历实现 ✅

**文件**: `crates/openfang-memory/src/knowledge.rs`

**实现内容**:
- 迭代 BFS 遍历算法
- 最大深度限制: 10 (防止滥用)
- 环路检测: HashSet 追踪已访问关系
- 结果限制: 1000 条

**新增方法**:
- `query_recursive()` - 递归遍历主逻辑
- `resolve_entity_ids()` - 解析实体 ID
- `get_all_entity_ids()` - 获取所有实体
- `query_from_sources()` - 从源实体集查询

**测试用例**:
- `test_recursive_traversal_depth_2` - 两层遍历
- `test_recursive_traversal_with_cycle` - 环路处理
- `test_recursive_traversal_with_relation_filter` - 关系过滤
- `test_max_depth_safety_limit` - 安全限制

---

### AOL AST 类型定义 ✅

**文件**: `crates/openfang-types/src/aol.rs` (新建, 1074 行)

**定义的类型**:
- `WorkflowDefId` - 工作流定义 ID
- `ParamType` - 参数类型枚举
- `InputParam` - 输入参数规格
- `ErrorMode` - 错误处理模式
- `AgentRef` - Agent 引用
- `CollectStrategy` - 收集策略
- `WorkflowConfig` - 工作流配置
- `AolStep` - 步骤类型枚举
- `AolWorkflow` - 完整工作流定义

**特性**:
- 所有类型 Serialize + Deserialize
- Builder 模式支持
- 40+ 单元测试

---

### E2E 测试框架 ✅

**新建文件**:
- `tests/e2e_test.rs` - 主测试入口
- `tests/e2e_common.rs` - 测试工具函数
- `tests/e2e_api_test.rs` - API 端点测试
- `tests/e2e_fixtures.rs` - 测试 fixtures
- `tests/fixtures/manifests.rs` - Agent manifest fixtures

**测试工具**:
- `spawn_daemon()` / `spawn_daemon_with_config()`
- `wait_for_health()` / `wait_for_health_with_timeout()`
- `create_test_agent()` / `kill_agent()`
- `send_message()` / `list_agents()`
- `get()` / `post()` / `put()` / `delete()`

**测试覆盖**:
- Health & Status (4 tests)
- Agent CRUD (7 tests)
- Error Handling (3 tests)
- Auth (4 tests)
- Integration (12 tests)
- LLM Integration (2 tests, ignored)

---

### 实时协作层 Migration v8 ✅

**文件**: `crates/openfang-memory/src/migration.rs`

**新增表**:
```sql
-- 注释/批注表
annotations (
    id, session_id, agent_id, connection_id, author_name,
    annotation_type, content, message_index, char_start, char_end,
    parent_id, status, priority, created_at, updated_at
)

-- 注释反应表
annotation_reactions (
    id, annotation_id, connection_id, reaction_type, reaction_value
)

-- 协作会话表
collab_sessions (
    id, session_id, owner_connection_id, share_mode, max_participants
)

-- 在线状态日志表
presence_log (
    id, collab_session_id, connection_id, display_name, status,
    joined_at, left_at, last_activity
)
```

**SCHEMA_VERSION**: 7 → 8

---

### 实现统计

| 功能 | 文件 | 代码行数 | 测试数 |
|------|------|----------|--------|
| 知识图谱递归遍历 | knowledge.rs | +200 | +4 |
| AOL AST 类型 | aol.rs | 1074 | 40+ |
| E2E 测试框架 | tests/e2e_*.rs | ~800 | 30+ |
| Migration v8 | migration.rs | +80 | +2 |
| **总计** | | **~2154** | **~76** |

---

## 附录 M: AOL 解析器与执行引擎实现 (2026-03-01)

### AOL 解析器 (TOML → AST) ✅

**新建文件**:
- `crates/openfang-kernel/src/aol/mod.rs` - 模块入口
- `crates/openfang-kernel/src/aol/parser.rs` - TOML 解析器 (~600 行)
- `crates/openfang-kernel/src/aol/template.rs` - 模板变量展开 (~200 行)
- `crates/openfang-kernel/src/aol/validator.rs` - 工作流验证 (~400 行)

**核心功能**:
- 完整的 TOML 工作流解析
- 支持所有步骤类型: parallel, sequential, conditional, loop, collect, subworkflow, fallback
- 模板变量展开: `{{input.xxx}}`, `{{output.xxx}}`, `{{loop.xxx}}`
- 工作流验证: 重复 ID 检测、空步骤检测、循环深度限制

**API 设计**:
```rust
// 解析 TOML 工作流
pub fn parse_aol_workflow_from_str(toml: &str) -> Result<AolWorkflow, AolParseError>

// 模板展开
pub fn expand_template(template: &str, ctx: &TemplateContext) -> Result<String, TemplateError>

// 验证工作流
pub fn validate_workflow(workflow: &AolWorkflow) -> Result<(), ValidationError>
```

**测试用例** (parser.rs):
- `test_parse_simple_workflow` - 基础工作流解析
- `test_parse_parallel_workflow` - 并行步骤组
- `test_parse_conditional_workflow` - 条件分支
- `test_parse_loop_workflow` - 循环步骤
- `test_parse_workflow_config` - 配置解析
- `test_parse_agent_ref_variants` - Agent 引用变体
- `test_duplicate_step_id_error` - 重复 ID 错误
- `test_parse_collect_step` - 收集步骤
- `test_parse_subworkflow_step` - 子工作流
- `test_parse_fallback_step` - 回退步骤
- `test_parse_complex_workflow` - 复杂工作流

---

### AOL 执行引擎 ✅

**新建文件**:
- `crates/openfang-kernel/src/aol/executor.rs` (~550 行)

**核心类型**:
- `ExecutionId` - 执行实例 ID
- `ExecutionStatus` - 执行状态 (Pending, Running, Completed, Failed, Cancelled)
- `ExecutionResult` - 执行结果
- `StepExecutionResult` - 单步执行结果
- `AolExecutor` - 执行器
- `AgentExecutor` trait - Agent 任务执行接口

**执行特性**:
- 并行步骤组执行 (支持并发限制)
- 条件分支评估
- 循环迭代执行
- 收集策略 (Merge, First, Last, Aggregate)
- 回退链支持
- 重试机制
- 超时控制

**API 设计**:
```rust
// 创建执行器
let executor = AolExecutor::with_mock();

// 执行工作流
let result = executor.execute(&compiled_workflow, inputs).await?;

// 获取执行结果
let execution = executor.get_execution(execution_id).await;
```

---

### AOL API 端点 ✅

**新建文件**:
- `crates/openfang-api/src/aol_routes.rs` (~400 行)

**端点列表**:
| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/aol/compile` | POST | 编译 (解析+验证) 工作流 |
| `/api/aol/validate` | POST | 仅验证工作流 |
| `/api/aol/execute` | POST | 执行已编译的工作流 |
| `/api/aol/workflows` | GET | 列出所有已编译工作流 |
| `/api/aol/workflows/{id}` | GET/DELETE | 获取/删除工作流 |
| `/api/aol/executions` | GET | 列出所有执行 |
| `/api/aol/executions/{id}` | GET | 获取执行详情 |

**使用示例**:
```bash
# 编译工作流
curl -X POST http://localhost:4200/api/aol/compile \
  -H "Content-Type: application/json" \
  -d '{"toml": "[workflow]\nname = \"test\"\n..."}'

# 执行工作流
curl -X POST http://localhost:4200/api/aol/execute \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "uuid", "inputs": {"topic": "AI"}}'
```

---

### 更新的文件

| 文件 | 更改 |
|------|------|
| `crates/openfang-kernel/src/lib.rs` | 添加 `pub mod aol;` |
| `crates/openfang-api/src/lib.rs` | 添加 `pub mod aol_routes;` |
| `crates/openfang-api/src/server.rs` | 添加 AOL 路由注册 |

---

### 实现统计 (更新)

| 功能 | 文件 | 代码行数 | 测试数 |
|------|------|----------|--------|
| 知识图谱递归遍历 | knowledge.rs | +200 | +4 |
| AOL AST 类型 | aol.rs (types) | 1074 | 40+ |
| E2E 测试框架 | tests/e2e_*.rs | ~800 | 30+ |
| Migration v8 | migration.rs | +80 | +2 |
| AOL 解析器 | aol/parser.rs | ~600 | 15+ |
| AOL 模板引擎 | aol/template.rs | ~200 | 15+ |
| AOL 验证器 | aol/validator.rs | ~400 | 15+ |
| AOL 执行引擎 | aol/executor.rs | ~550 | 10+ |
| AOL API 路由 | aol_routes.rs | ~400 | 2+ |
| PresenceManager | presence.rs | ~1380 | 28 |
| **总计** | | **~5684** | **~161** |

---

## 附录 N: PresenceManager 实现 ✅ (2026-03-01)

**新建文件**:
- `crates/openfang-kernel/src/presence.rs` (~1380 行)

**核心类型**:
- `ConnectionId` - WebSocket 连接 ID (Uuid)
- `CollabSessionId` - 协作会话 ID (Uuid)
- `PresenceStatus` - 用户状态枚举 (Active, Idle, Away)
- `PresenceCursor` - 光标位置 (message_index, char_start, char_end)
- `PresenceUser` - 用户信息 (connection_id, display_name, status, cursor, last_activity, color)
- `CollabSession` - 协作会话
- `PresenceConfig` - 配置 (超时设置)
- `PresenceStats` - 统计信息

**核心功能**:
- 会话管理: create_session, get_session, remove_session, list_sessions
- 用户加入/离开: join_session, leave_session
- 状态更新: update_cursor, clear_cursor, update_status, heartbeat
- 查询: get_session_users, get_user, get_session_user_count
- 自动清理: update_idle_statuses, cleanup_inactive_users

**测试用例**: 28 个测试覆盖所有功能

**设计特点**:
- 使用 DashMap 支持高并发
- 自动生成用户颜色 (HSL-based)
- 可配置超时设置
- 完整的错误处理

---

## 附录 O: AnnotationStore 实现 ✅ (2026-03-01)

**新建文件**:
- `crates/openfang-memory/src/annotations.rs` (~800 行)

**核心类型**:
- `AnnotationId` - 注释唯一 ID (Uuid)
- `AnnotationType` - 类型枚举 (Comment, Question, Suggestion, Issue, Highlight)
- `AnnotationStatus` - 状态枚举 (Open, Resolved, Dismissed)
- `AnnotationPriority` - 优先级枚举 (Low, Normal, High, Urgent)
- `Annotation` - 注释实体
- `AnnotationReaction` - 注释反应
- `AnnotationStats` - 统计信息
- `AnnotationError` - 错误类型
- `AnnotationStore` - 存储管理器

**核心功能**:
- 创建注释: create_annotation
- 获取注释: get_annotation, list_annotations, list_annotations_for_message
- 线程管理: get_thread, list_root_annotations
- 更新操作: update_annotation_content, update_annotation_status
- 状态变更: resolve_annotation, dismiss_annotation, reopen_annotation
- 删除操作: delete_annotation, delete_session_annotations
- 反应管理: add_reaction, remove_reaction, get_reactions, get_reaction_summary
- 统计: get_session_stats

**测试用例**: 20+ 测试覆盖所有功能

**设计特点**:
- SQLite 持久化存储
- 支持线程回复 (parent_id)
- 支持行号范围 (line_start, line_end)
- 完整的反应系统