diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..5b5e72f --- /dev/null +++ b/agents.md @@ -0,0 +1,415 @@ +# 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. 技术文档参考 +- [JSON-RPC 2.0规范](https://www.jsonrpc.org/specification) +- [Electron进程通信指南](https://www.electronjs.org/docs/latest/tutorial/ipc) +- [Zustand状态管理文档](https://docs.pmnd.rs/zustand/getting-started/introduction) + +### 3. 外部API文档 +- [企业微信机器人API](https://developer.work.weixin.qq.com/document/path/91770) +- [钉钉机器人API](https://open.dingtalk.com/document/robots/robot-overview) +- [飞书机器人API](https://open.feishu.cn/document/client-docs/bot-v3/overview) + +--- + +**文档版本**：v1.0 +**创建时间**：2026-04-08 +**最后更新**：2026-04-08 +**负责人**：zn-ai开发团队 \ No newline at end of file diff --git a/package.json.backup b/package.json.backup deleted file mode 100644 index 88bd001..0000000 --- a/package.json.backup +++ /dev/null @@ -1,86 +0,0 @@ -{ - "name": "zn-ai", - "productName": "NIANXX", - "version": "1.0.0", - "description": "智念AI - 一款应用智能的多功能桌面应用", - "main": ".vite/build/main.js", - "scripts": { - "start": "dotenv -e .env -- electron-forge start", - "package": "electron-forge package", - "make": "electron-forge make", - "publish": "electron-forge publish", - "lint": "eslint --ext .ts,.tsx .", - "generate-prod-entry": "node build/scripts/generateProdEntry.js", - "clean": "node build/scripts/clean.js", - "openapi": "dotenv -e .env -- openapi-ts", - "build:encrypt": "npm run clean && npm run package && npm run generate-prod-entry" - }, - "keywords": [], - "author": { - "name": "duanshuwen", - "email": "duanshuwen@gogpay.cn" - }, - "license": "MIT", - "devDependencies": { - "@electron-forge/cli": "^7.8.3", - "@electron-forge/maker-deb": "^7.10.2", - "@electron-forge/maker-dmg": "^7.11.1", - "@electron-forge/maker-rpm": "^7.10.2", - "@electron-forge/maker-squirrel": "^7.10.2", - "@electron-forge/maker-wix": "^7.11.1", - "@electron-forge/maker-zip": "^7.10.2", - "@electron-forge/plugin-auto-unpack-natives": "^7.10.2", - "@electron-forge/plugin-fuses": "^7.10.2", - "@electron-forge/plugin-vite": "^7.10.2", - "@electron/fuses": "^1.8.0", - "@tailwindcss/typography": "^0.5.19", - "@tailwindcss/vite": "^4.1.17", - "@types/electron-squirrel-startup": "^1.0.2", - "@types/lodash-es": "^4.17.12", - "@types/node": "^24.0.8", - "@typescript-eslint/parser": "^5.62.0", - "@vitejs/plugin-vue": "^6.0.3", - "electron": "38.2.2", - "esbuild": "^0.27.4", - "openapi-ts-request": "^1.10.1", - "tailwindcss": "^4.1.11", - "typescript": "^5.8.3", - "unplugin-auto-import": "^20.3.0", - "vite": "^7.1.9" - }, - "dependencies": { - "@iconify-json/material-symbols": "^1.2.50", - "@iconify/vue": "^5.0.0", - "@remixicon/vue": "^4.7.0", - "@types/crypto-js": "^4.2.2", - "@types/js-cookie": "^3.0.6", - "@vueuse/core": "^14.1.0", - "axios": "^1.13.2", - "browser-use-sdk": "^2.0.12", - "bytenode": "^1.5.7", - "chromium-bidi": "^15.0.0", - "crypto": "^1.0.1", - "crypto-js": "^4.2.0", - "dexie": "^4.2.1", - "dotenv-cli": "^11.0.0", - "electron-log": "^5.4.3", - "electron-squirrel-startup": "^1.0.1", - "element-plus": "^2.12.0", - "highlight.js": "^11.11.1", - "js-base64": "^3.7.8", - "js-cookie": "^3.0.5", - "lodash-es": "^4.17.21", - "log4js": "^6.9.1", - "markdown-it": "^14.1.0", - "mitt": "^3.0.1", - "openai": "^6.14.0", - "pinia": "^2.3.1", - "playwright": "^1.58.2", - "ts-node": "^10.9.2", - "uuid": "^13.0.0", - "vue": "^3.5.22", - "vue-i18n": "^11.1.9", - "vue-markdown-render": "^2.3.0", - "vue-router": "^4.5.1" - } -} \ No newline at end of file diff --git a/src/components/HeaderBar/index.vue b/src/components/HeaderBar/index.vue index f5650a0..9391a91 100644 --- a/src/components/HeaderBar/index.vue +++ b/src/components/HeaderBar/index.vue @@ -6,14 +6,16 @@
- - -