duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c16fc9368570f97a49439457bc172883aedef9bf
zn-ai/agents.md
duanshuwen c3825e6d43 feat(ui): add hover effects to window control buttons 
Add hover background and text color changes to minimize, maximize, and close buttons in the header bar for better visual feedback. The close button now turns red on hover for clearer destructive action indication.

Remove backup package.json file and add comprehensive agent system development plan document (agents.md) detailing architecture analysis and implementation roadmap.
2026-04-08 21:24:51 +08:00

15 KiB
Raw Blame History

ClawX项目Agent实现分析报告与zn-ai Agent开发计划

一、ClawX项目Agent实现全面分析报告

1. 架构概述

ClawX项目采用模块化多Agent架构，每个Agent拥有独立的工作区隔离机制、文件系统空间和会话管理系统。该架构旨在为OpenClaw AI代理运行时提供图形化管理界面，支持多Agent并发执行、任务可视化展示和外部频道集成。

2. 核心组件

组件 文件路径 功能描述
Agent配置管理器 electron/utils/agent-config.ts 管理Agent的工作区、文件系统、配置读写、频道绑定
Agent API路由层 electron/api/routes/agents.ts 提供RESTful API接口（创建、更新、删除、绑定频道等）
Agent状态管理 src/stores/agents.ts 使用Zustand管理Agent状态，提供类型安全的操作函数
Agent类型定义 src/types/agent.ts 定义AgentSummary、AgentsSnapshot等核心数据结构
Agent UI管理界面 src/pages/Agents/index.tsx 图形化Agent管理界面，支持创建、配置、删除Agent
Gateway连接管理器 electron/gateway/manager.ts 管理与OpenClaw Gateway的WebSocket连接和进程生命周期
任务可视化系统 src/pages/Chat/task-visualization.ts 解析Agent执行步骤，生成可视化任务执行树
会话管理API electron/api/routes/sessions.ts 处理会话数据加载、删除和转录文件管理

3. 工作流程

3.1 Agent创建流程

用户通过UI输入Agent名称和选项
系统生成唯一Agent ID和独立工作区目录
创建配置文件并初始化文件系统结构
可选择从主Agent继承工作区内容

3.2 消息路由流程

用户通过频道（Telegram、Slack等）发送消息
系统根据频道绑定规则路由到对应Agent
支持`@agent`语法直接指定目标Agent
消息通过Gateway转发给OpenClaw运行时

3.3 任务执行流程

Agent接收任务后创建会话
执行过程中生成任务步骤（思考、工具调用、系统操作）
支持创建子Agent处理复杂任务，形成执行树结构
任务状态实时可视化展示

3.4 工作区隔离机制

~/.openclaw/
├── agents/
│   ├── {agentId}/
│   │   ├── agent/          # Agent运行时目录
│   │   ├── sessions/       # 会话存储
│   │   └── config.json     # Agent配置
├── workspace-{agentId}/    # Agent专用工作区目录
│   ├── .clawx-managed/     # ClawX管理标记
│   ├── tasks/             # 任务数据
│   └── files/             # 工作文件

4. 关键技术

4.1 JSON-RPC 2.0通信协议

  • 使用标准化协议与OpenClaw Gateway通信
  • 支持双向通信和事件通知机制
  • 消息格式：{ type: "req", id: "...", method: "...", params: {...} }

4.2 任务可视化系统

  • 从消息历史解析任务执行步骤
  • 支持thinking、tool、system、subagent等步骤类型
  • 自动构建执行树拓扑结构，展示父子关系

4.3 子Agent执行树

  • 支持sessions_spawn工具创建子Agent
  • 父子Agent形成任务执行树结构
  • 子Agent可独立工作并返回结果给父Agent

4.4 频道绑定机制

  • Agent可绑定到多种外部频道（Telegram、Slack、Discord、WeChat等）
  • 支持账号级别的精细绑定控制
  • 消息自动路由到对应Agent

4.5 工作区文件系统隔离

  • 每个Agent拥有独立的文件系统环境
  • 支持工作区克隆和继承
  • 确保任务执行的隔离性和安全性

4.6 会话管理系统

  • 支持会话历史持久化存储
  • 会话文件使用JSONL格式存储
  • 支持会话删除和转录文件管理

5. 设计模式

5.1 配置驱动设计

  • Agent行为通过JSON配置文件管理
  • 支持运行时配置更新
  • 配置变更触发Gateway重新加载

5.2 关注点分离

  • 前端UI与后端逻辑分离
  • Agent管理与任务执行分离
  • 通信协议与业务逻辑分离

5.3 可扩展架构

  • 支持多Agent并发执行
  • 支持自定义技能和工具
  • 支持多种外部频道集成

5.4 安全性设计

  • 工作区文件系统隔离
  • 敏感数据加密存储
  • API密钥的安全管理

5.5 用户友好性

  • 图形化Agent管理界面
  • 任务可视化展示
  • 多语言国际化支持

6. 技术栈

技术领域 具体技术
桌面框架 Electron 40+
前端框架 React 19 + TypeScript
样式系统 Tailwind CSS + shadcn/ui
状态管理 Zustand
构建工具 Vite + electron-builder
测试框架 Vitest + Playwright
动画库 Framer Motion
图标库 Lucide React
国际化 i18next + react-i18next
OpenClaw集成 @openclaw/gateway-client

7. 应用场景

  1. 多Agent协作：多个Agent分工合作处理复杂任务
  2. 频道集成：通过外部通讯平台与用户交互
  3. 任务可视化：实时监控AI任务执行过程
  4. 工作区管理：为不同任务类型创建专用工作环境
  5. 模型配置：为不同Agent配置专用AI模型

8. 总结与评估

8.1 技术优势

  1. 完整的工作区隔离：为每个Agent提供独立的文件系统环境，确保任务执行的隔离性和安全性
  2. 灵活的通信机制：基于JSON-RPC 2.0的标准化协议，支持复杂的消息路由和会话管理
  3. 可视化任务管理：创新的任务可视化系统，使复杂的AI任务执行过程透明化、可监控
  4. 模块化架构设计：清晰的层次结构，便于功能扩展和维护

8.2 创新亮点

  1. @agent直接路由：用户可以直接通过@agent语法将消息路由到特定Agent，提高交互效率
  2. 子Agent执行树：支持创建子Agent处理复杂任务，形成任务执行树结构
  3. 多通道绑定：Agent可以绑定到多种通信渠道，实现统一的管理界面
  4. 智能配置继承：支持Agent工作区和配置的克隆与继承，便于Agent模板化管理

8.3 架构成熟度

ClawX的Agent架构展现了较高的工程成熟度：

  • 完整的类型安全：TypeScript全面覆盖，提供编译时类型检查
  • 完善的测试覆盖：包含单元测试、集成测试和E2E测试
  • 良好的文档支持：详细的代码注释和架构说明
  • 国际化支持：多语言界面，支持中文、英文、日文等

二、zn-ai项目Agent系统开发计划

基于ClawX项目的先进架构分析，结合zn-ai项目的实际需求，制定以下Agent系统开发计划。

1. 项目背景与目标

1.1 项目背景

zn-ai项目目前已具备基础的Electron应用框架、构建系统、国际化支持和基本的AI功能。为提升产品竞争力，需要引入多Agent系统，支持以下功能：

  • 多任务并行处理能力
  • 任务执行过程可视化
  • 外部渠道集成（如企业微信、钉钉等）
  • 工作区隔离管理

1.2 核心目标

  1. 构建模块化Agent系统：借鉴ClawX的架构设计，实现可扩展的多Agent管理框架
  2. 集成任务可视化：提供用户友好的任务执行监控界面
  3. 支持工作区隔离：为不同任务类型创建独立的工作环境
  4. 实现频道绑定：支持与企业通讯工具集成

2. 技术选型与架构设计

2.1 技术选型

技术组件 选型方案 说明
前端框架 React + TypeScript 保持与现有技术栈一致
状态管理 Zustand 轻量级状态管理，与ClawX保持一致
UI组件库 shadcn/ui + Tailwind CSS 使用现有样式系统
通信协议 JSON-RPC 2.0 标准化协议，便于与后端集成
数据存储 本地文件系统 + SQLite 会话历史和配置存储
国际化 i18next 与现有国际化方案集成

2.2 架构设计

zn-ai Agent系统架构
├── 前端层 (Renderer)
│   ├── Agent管理界面
│   ├── 任务可视化组件
│   ├── 频道绑定配置
│   └── 工作区浏览器
├── 业务逻辑层 (Main Process)
│   ├── Agent配置管理器
│   ├── 会话管理器
│   ├── 频道路由引擎
│   └── Gateway通信代理
├── 数据存储层
│   ├── 配置文件 (JSON)
│   ├── 会话文件 (JSONL)
│   ├── 工作区文件系统
│   └── SQLite数据库 (可选)
└── 外部集成层
    ├── 企业微信API
    ├── 钉钉机器人
    ├── 飞书Webhook
    └── 自定义Webhook

3. 核心功能模块

3.1 Agent管理模块

  • Agent创建/删除：支持创建新Agent，分配独立工作区
  • Agent配置：模型选择、参数设置、技能配置
  • Agent状态监控：运行状态、资源使用、任务队列

3.2 任务可视化模块

  • 执行步骤解析：从AI响应中提取思考过程、工具调用
  • 拓扑结构展示：父子Agent关系、任务依赖关系
  • 实时状态更新：任务进度、错误信息、执行结果

3.3 工作区管理模块

  • 工作区创建：为每个Agent创建独立文件空间
  • 文件同步：支持工作区内容克隆和同步
  • 资源隔离：确保不同Agent间的文件系统隔离

3.4 频道集成模块

  • 多渠道支持：企业微信、钉钉、飞书、自定义Webhook
  • 消息路由：根据规则将消息路由到指定Agent
  • 账号绑定：支持多账号、多群组绑定

3.5 会话管理模块

  • 会话持久化：保存完整的对话历史
  • 会话恢复：支持从历史记录恢复执行状态
  • 会话分析：提供会话统计数据和分析报告

4. 实施路线图

第一阶段：基础框架搭建 (预计2-3周)

  1. 项目分析与规划

    • 分析zn-ai现有架构，确定集成点
    • 设计Agent系统数据库 schema
    • 制定详细的技术方案

  2. 核心组件开发

    • Agent配置管理器 (参考ClawX agent-config.ts)
    • 基础类型定义 (Agent, Session, Channel等)
    • 状态管理Store (使用Zustand)

  3. 基础界面开发

    • Agent列表页面
    • Agent创建/编辑表单
    • 基础的任务展示组件

第二阶段：核心功能实现 (预计3-4周)

  1. 工作区隔离系统

    • 实现工作区目录管理
    • 文件系统隔离机制
    • 工作区同步功能

  2. 任务可视化系统

    • 消息解析引擎 (参考ClawX task-visualization.ts)
    • 执行步骤可视化组件
    • 实时状态更新机制

  3. 会话管理系统

    • 会话存储格式设计 (JSONL)
    • 会话历史管理界面
    • 会话导入/导出功能

第三阶段：高级功能集成 (预计3-4周)

  1. 频道绑定系统

    • 企业微信集成
    • 钉钉机器人集成
    • 消息路由引擎

  2. 子Agent系统

    • 子Agent创建与管理
    • 任务分解与分配
    • 结果汇总机制

  3. 性能优化与稳定性

    • 大规模会话性能优化
    • 错误处理与恢复机制
    • 内存和资源管理

第四阶段：测试与优化 (预计2周)

  1. 功能测试

    • 单元测试覆盖核心组件
    • 集成测试验证系统交互
    • E2E测试模拟用户场景

  2. 性能测试

    • 多Agent并发性能测试
    • 大文件工作区性能测试
    • 长时间运行稳定性测试

  3. 用户体验优化

    • 界面交互优化
    • 错误提示改进
    • 文档编写与用户引导

5. 技术挑战与应对策略

5.1 技术挑战

  1. 工作区隔离安全性：确保不同Agent间的完全隔离
  2. 大规模会话管理：高效存储和检索大量会话数据
  3. 实时任务可视化：复杂执行步骤的实时解析和展示
  4. 多频道同步：多平台消息的同步和一致性

5.2 应对策略

  1. 采用进程级隔离：对于高安全需求场景，考虑使用独立进程
  2. 分页和索引优化：会话数据采用分页加载和高效索引
  3. 增量更新机制：任务可视化采用增量更新，减少渲染开销
  4. 消息队列和去重：频道消息使用队列处理和去重机制

6. 成功指标与验收标准

6.1 功能指标

  • 支持至少5个Agent并发执行
  • 工作区隔离100%安全
  • 任务可视化延迟 < 500ms
  • 支持至少3种外部频道集成
  • 会话加载时间 < 2秒 (100条记录)

6.2 性能指标

  • Agent创建时间 < 3秒
  • 内存占用增量 < 50MB/Agent
  • 消息路由延迟 < 100ms
  • 系统可用性 > 99.9%

6.3 用户体验指标

  • 界面响应时间 < 200ms
  • 操作成功率 > 99%
  • 用户满意度评分 > 4.5/5
  • 新手引导完成率 > 90%

7. 风险管理

7.1 技术风险

  • 风险：工作区隔离机制可能影响性能
  • 缓解：采用轻量级隔离方案，性能关键路径优化
  • 备选：提供配置选项，允许用户选择隔离级别

7.2 时间风险

  • 风险：复杂功能开发可能超出预期时间
  • 缓解：采用敏捷开发，分阶段交付核心功能
  • 备选：优先级排序，非核心功能延后实现

7.3 兼容性风险

  • 风险：新系统可能与现有功能冲突
  • 缓解：充分测试，逐步集成
  • 备选：提供兼容性开关，可回退到旧模式

8. 下一步行动计划

  1. 立即行动 (本周)

    • 组建开发团队，分配角色
    • 搭建开发环境，创建分支
    • 编写详细的技术设计文档

  2. 短期计划 (1-2周)

    • 实现Agent配置管理基础功能
    • 开发Agent管理界面
    • 建立基础测试框架

  3. 中期计划 (3-5周)

    • 完成工作区隔离系统
    • 实现任务可视化核心功能
    • 集成第一种外部频道

  4. 长期计划 (6-8周)

    • 完成所有核心功能
    • 进行全面测试和优化
    • 准备发布版本

三、附录：参考实现与资源

1. ClawX项目关键文件参考

  • electron/utils/agent-config.ts - Agent配置管理核心
  • src/stores/agents.ts - 状态管理最佳实践
  • src/pages/Chat/task-visualization.ts - 任务可视化实现
  • electron/gateway/manager.ts - Gateway通信管理

2. 技术文档参考

3. 外部API文档

文档版本：v1.0
创建时间：2026-04-08
最后更新：2026-04-08
负责人：zn-ai开发团队