# 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, // 统一存储 // 事件 pub event_bus: EventBus, // 发布订阅 // 执行 pub workflows: WorkflowEngine, // 工作流 pub triggers: TriggerEngine, // 触发器 pub background: BackgroundExecutor, // 后台任务 // 安全 pub audit_log: Arc, // 审计日志 pub auth: AuthManager, // RBAC pub capabilities: CapabilityManager, // 权限 // 计量 pub metering: Arc, // 成本追踪 // LLM pub default_driver: Arc, pub model_catalog: RwLock, // 扩展 pub skill_registry: RwLock, pub hand_registry: HandRegistry, pub extension_registry: RwLock, pub mcp_connections: Mutex>, // 网络 pub peer_registry: Option, pub peer_node: Option>, pub channel_adapters: DashMap>, // ... 更多字段 } ``` #### 关键流程 **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, ) -> Result { 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 { 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, 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, pub steps: Vec, pub outputs: HashMap, } 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 // 模板展开 pub fn expand_template(template: &str, ctx: &TemplateContext) -> Result // 验证工作流 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) - 完整的反应系统