MyClaw.NET 设计方案

## 1. 项目概述 ### 1.1 项目目标 将基于 Go 语言和 agentsdk-go 的 myclaw 项目 1:1 复刻到 C# .NET 平台，使用 AgentScope.NET 作为底层框架。 ### 1.2 参考项目 - **源项目**: [stellarlinkco/myclaw](https://github.com/stellarlinkco/myclaw) - 语言：Go - 框架：agentsdk-go - 特点：个人 AI 助手，支持多渠道、定时任务、长期记忆等 - **底层框架**: [linkerlin/agentscope.net](https://github.com/linkerlin/agentscope.net) - 语言：C# - 平台：.NET 9.0 - 特点：LLM 驱动的应用框架，支持 Agent、Memory、Tool 等核心组件 ## 2. 系统架构 ### 2.1 总体架构 ``` ┌─────────────────────────────────────────────────────────┐ │ CLI (CommandLine) │ │ agent | gateway | onboard | status │ └──────┬──────────────────┬───────────────────────────────┘ │ │ ▼ ▼ ┌──────────────┐ ┌───────────────────────────────────────┐ │ Agent Mode │ │ Gateway │ │ (single / │ │ │ │ REPL) │ │ ┌─────────┐ ┌──────┐ ┌─────────┐ │ └──────┬───────┘ │ │ Channel │ │ Cron │ │Heartbeat│ │ │ │ │ Manager │ │ │ │ │ │ │ │ └────┬────┘ └──┬───┘ └────┬────┘ │ │ │ │ │ │ │ ▼ │ ▼ ▼ ▼ │ ┌──────────────┐ │ ┌─────────────────────────────────┐ │ │ AgentScope │ │ │ Message Bus │ │ │ Runtime │◄─┤ │ Inbound ←── Channels │ │ │ │ │ │ Outbound ──► Channels │ │ └──────────────┘ │ └──────────────┬──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ AgentScope.NET Runtime │ │ │ │ (ReAct loop + tool execution) │ │ │ └──────────────────────────────────┘ │ │ │ │ ┌──────────┐ ┌────────────────────┐ │ │ │ Memory │ │ Config │ │ │ │ (SQLite │ │ (JSON + env vars) │ │ │ │ + daily)│ │ │ │ │ └──────────┘ └────────────────────┘ │ └───────────────────────────────────────┘ ``` ### 2.2 核心组件映射 | myclaw (Go) | MyClaw.NET (C#) | AgentScope.NET 基础 | |-------------|------------------|-------------------| | agentsdk-go Runtime | AgentScope Runtime | EnhancedReActAgent | | Message Bus | MessageBus | Msg + IMessage | | Channel Manager | ChannelManager | 自定义实现 | | Memory System | MemorySystem | SqliteMemory | | Tool System | ToolSystem | ITool + ToolBase | | Config | Configuration | Configuration | | Cron Jobs | CronScheduler | 自定义实现 | | Heartbeat | HeartbeatService | 自定义实现 | ## 3. 模块设计 ### 3.1 CLI 模块 **命名空间**: `MyClaw.CLI` **职责**: - 提供命令行接口 - 支持 agent, gateway, onboard, status 子命令 - 参数解析和验证 **技术栈**: - System.CommandLine (命令行框架) - Spectre.Console (美化输出) **主要类**: ```csharp class Program class AgentCommand class GatewayCommand class OnboardCommand class StatusCommand ``` ### 3.2 Agent 模块 **命名空间**: `MyClaw.Agent` **职责**: - 实现单次消息处理和 REPL 交互模式 - 集成 AgentScope.NET 的 ReAct Agent - 处理用户输入和 AI 响应 **核心类**: ```csharp class MyClawAgent : EnhancedReActAgent { // 使用 AgentScope.NET 的 EnhancedReActAgent 作为基类 // 添加 myclaw 特定功能 } class ReplLoop { // 实现交互式循环 } ``` ### 3.3 Gateway 模块 **命名空间**: `MyClaw.Gateway` **职责**: - 协调所有服务（Channels, Cron, Heartbeat） - 消息总线管理 - 生命周期管理 **核心类**: ```csharp class GatewayService { ChannelManager ChannelManager { get; } CronScheduler CronScheduler { get; } HeartbeatService HeartbeatService { get; } MessageBus MessageBus { get; } Task StartAsync(CancellationToken ct); Task StopAsync(); } class MessageBus { Channel<IMessage> InboundChannel { get; } Channel<IMessage> OutboundChannel { get; } Task ProcessLoopAsync(CancellationToken ct); } ``` ### 3.4 Channel 系统 **命名空间**: `MyClaw.Channels` **职责**: - 抽象多渠道消息接收和发送 - 支持 Telegram, Feishu, WeCom, WhatsApp, WebUI **接口设计**: ```csharp interface IChannel { string Name { get; } bool IsEnabled { get; } Task StartAsync(CancellationToken ct); Task StopAsync(); Task SendAsync(IMessage message); } abstract class ChannelBase : IChannel { // 基础实现 } class TelegramChannel : ChannelBase class FeishuChannel : ChannelBase class WeComChannel : ChannelBase class WhatsAppChannel : ChannelBase class WebUIChannel : ChannelBase ``` **实现优先级**: 1. WebUI (最简单，本地测试) 2. Telegram (API 成熟) 3. Feishu (企业场景) 4. WeCom (企业场景) 5. WhatsApp (最复杂) ### 3.5 Memory 系统 **命名空间**: `MyClaw.Memory` **基于 AgentScope.NET**: - 使用 `SqliteMemory` 作为基础 - 扩展支持 daily memories 和 MEMORY.md **核心类**: ```csharp class MyClawMemory : SqliteMemory { // 长期记忆 (MEMORY.md) Task<string> LoadLongTermMemoryAsync(); Task SaveLongTermMemoryAsync(string content); // 每日记忆 Task<List<DailyMemory>> GetDailyMemoriesAsync(DateTime date); Task AddDailyMemoryAsync(DailyMemory memory); } class DailyMemory { DateTime Timestamp { get; set; } string Content { get; set; } string Category { get; set; } } ``` ### 3.6 Skills 系统 **命名空间**: `MyClaw.Skills` **职责**: - 加载和管理自定义技能 - 从 SKILL.md 文件解析技能定义 - 与 AgentScope.NET 的 Tool 系统集成 **核心类**: ```csharp class SkillManager { string SkillsDirectory { get; } List<ISkill> LoadedSkills { get; } Task LoadSkillsAsync(); ISkill GetSkill(string name); } interface ISkill : ITool { string Name { get; } string Description { get; } List<string> Keywords { get; } } class SkillLoader { static ISkill LoadFromMarkdown(string path); } ``` ### 3.7 Cron 系统 **命名空间**: `MyClaw.Cron` **职责**: - 定时任务调度 - JSON 持久化 **技术栈**: - Quartz.NET (成熟的调度框架) **核心类**: ```csharp class CronScheduler { IScheduler Scheduler { get; } Task AddJobAsync(CronJob job); Task RemoveJobAsync(string jobId); Task<List<CronJob>> GetJobsAsync(); } class CronJob { string Id { get; set; } string Name { get; set; } string CronExpression { get; set; } string Action { get; set; } Dictionary<string, object> Parameters { get; set; } } ``` ### 3.8 Heartbeat 系统 **命名空间**: `MyClaw.Heartbeat` **职责**: - 周期性任务 - 从 HEARTBEAT.md 读取配置 **核心类**: ```csharp class HeartbeatService { TimeSpan Interval { get; } List<HeartbeatTask> Tasks { get; } Task StartAsync(CancellationToken ct); Task StopAsync(); } class HeartbeatTask { string Name { get; set; } Func<Task> Action { get; set; } } ``` ### 3.9 Configuration 系统 **命名空间**: `MyClaw.Configuration` **职责**: - 配置加载（JSON + 环境变量） - 配置验证 - 敏感信息保护 **核心类**: ```csharp class MyClawConfiguration { ProviderConfig Provider { get; set; } AgentConfig Agent { get; set; } ChannelsConfig Channels { get; set; } SkillsConfig Skills { get; set; } static MyClawConfiguration Load(string path); static MyClawConfiguration LoadFromEnvironment(); } class ProviderConfig { string Type { get; set; } // "anthropic" | "openai" string ApiKey { get; set; } string BaseUrl { get; set; } } ``` ## 4. 数据流设计 ### 4.1 Gateway 模式数据流 ``` Telegram/Feishu/etc ──► Channel ──► MessageBus.Inbound │ ▼ ProcessLoop │ ▼ AgentScope Runtime.Run() │ ▼ MessageBus.Outbound ──► Channel ──► Telegram/Feishu/etc ``` ### 4.2 Agent 模式数据流 ``` User Input ──► MyClawAgent.CallAsync() ──► AgentScope Runtime ──► AI Response ``` ## 5. 技术选型 ### 5.1 核心框架 - **.NET 9.0**: 最新 LTS 版本 - **AgentScope.NET**: 底层 Agent 框架 ### 5.2 关键库 | 功能 | 库 | 说明 | |------|-----|------| | 命令行 | System.CommandLine | 微软官方 CLI 框架 | | 控制台美化 | Spectre.Console | 彩色输出、进度条等 | | HTTP 客户端 | System.Net.Http | 内置 | | WebSocket | System.Net.WebSockets | WebUI 通信 | | JSON | System.Text.Json | 高性能 JSON | | 数据库 | EF Core + SQLite | AgentScope.NET 已使用 | | 调度 | Quartz.NET | Cron 任务调度 | | Telegram | Telegram.Bot | 官方 SDK | | 配置 | Microsoft.Extensions.Configuration | 标准配置框架 | | DI | Microsoft.Extensions.DependencyInjection | 依赖注入 | | 日志 | Microsoft.Extensions.Logging | 标准日志框架 | ### 5.3 开发工具 - **IDE**: Visual Studio 2022 / Rider / VS Code - **版本控制**: Git - **包管理**: NuGet ## 6. 兼容性设计 ### 6.1 与 myclaw (Go) 的兼容性 | 方面 | 兼容性策略 | |------|-----------| | 配置文件 | 相同的 JSON 结构 | | 环境变量 | 相同的命名 (MYCLAW_*) | | 工作区结构 | 相同的目录布局 | | SKILL.md 格式 | 完全兼容 | | API 接口 | 如果实现 HTTP API，保持兼容 | ### 6.2 与 AgentScope.NET 的集成 | AgentScope 组件 | 使用方式 | |-----------------|---------| | EnhancedReActAgent | 继承并扩展 | | SqliteMemory | 直接使用或扩展 | | ITool | 实现 Skill 接口 | | Msg | 作为消息基础类型 | | IModel | 支持 Anthropic/OpenAI | | Hook System | 用于扩展 Agent 行为 | ## 7. 安全设计 ### 7.1 敏感信息保护 - 配置文件权限：600 (仅所有者可读写) - 优先使用环境变量存储 API 密钥 - .gitignore 排除敏感文件 ### 7.2 渠道安全 - Telegram: allowFrom 白名单 - Feishu: Verification Token 验证 - WeCom: 消息加密解密 - WebUI: 可选身份验证 ### 7.3 数据安全 - 本地 SQLite 数据库 - 敏感数据加密存储（如需要） ## 8. 性能考虑 ### 8.1 并发处理 - 使用 async/await 异步模式 - Channel<T> 实现消息队列 - 并行处理多个渠道消息 ### 8.2 资源管理 - IDisposable 模式管理资源 - CancellationToken 支持优雅关闭 - 连接池复用 ## 9. 可扩展性 ### 9.1 插件系统 - Skill 作为插件动态加载 - 新 Channel 易于添加 - 自定义 Tool 支持 ### 9.2 配置驱动 - 通过配置启用/禁用功能 - 运行时配置热重载（可选） ## 10. 测试策略 ### 10.1 单元测试 - xUnit 测试框架 - 每个模块独立测试 - Mock 外部依赖 ### 10.2 集成测试 - 测试模块间交互 - 测试实际 Channel 集成 - 测试数据库操作 ### 10.3 端到端测试 - Agent 模式完整流程 - Gateway 模式消息流转 - 多渠道协同工作 ## 11. 文档策略 ### 11.1 代码文档 - XML 注释 - README 文件 - 架构图 ### 11.2 用户文档 - 快速开始指南 - 配置说明 - Channel 设置指南（Telegram, Feishu, WeCom 等） ## 12. 部署方案 ### 12.1 本地部署 - 编译为单一可执行文件 - 包含所有依赖 - 跨平台支持 (Windows, Linux, macOS) ### 12.2 Docker 部署 - Dockerfile 构建镜像 - docker-compose.yml 编排 - 持久化卷挂载 ### 12.3 云部署 - 支持 Azure App Service - 支持 AWS ECS - 支持 Kubernetes ## 13. 开发阶段划分 ### Phase 1: 基础设施 (Week 1-2) - 项目结构搭建 - 配置系统 - CLI 框架 - 依赖注入和日志 ### Phase 2: Core Agent (Week 3-4) - MyClawAgent 实现 - Memory 集成 - Agent 模式（single + REPL） ### Phase 3: Gateway 基础 (Week 5-6) - MessageBus 实现 - ChannelManager 框架 - Gateway 服务协调 ### Phase 4: Channels (Week 7-10) - WebUI Channel (Week 7) - Telegram Channel (Week 8) - Feishu Channel (Week 9) - WeCom Channel (Week 10) ### Phase 5: Skills & Tools (Week 11-12) - Skill 加载系统 - 示例 Skills - Tool 集成 ### Phase 6: Scheduling (Week 13-14) - Cron 系统 - Heartbeat 服务 ### Phase 7: Testing & Polish (Week 15-16) - 完整测试 - 文档完善 - Bug 修复 - 性能优化 ## 14. 风险与挑战 | 风险 | 影响 | 缓解措施 | |------|------|---------| | AgentScope.NET 功能不完整 | 高 | 必要时扩展框架 | | Channel SDK 兼容性 | 中 | 选择成熟的 .NET SDK | | 性能问题 | 中 | 性能测试和优化 | | 安全漏洞 | 高 | 安全审计和最佳实践 | | 跨平台兼容性 | 低 | .NET 天然支持 | ## 15. 成功标准 ### 15.1 功能完整性 - ✅ 所有 myclaw 核心功能已实现 - ✅ Agent 和 Gateway 模式均正常工作 - ✅ 至少支持 3 个 Channel ### 15.2 质量标准 - ✅ 单元测试覆盖率 > 70% - ✅ 所有集成测试通过 - ✅ 无严重 Bug ### 15.3 性能标准 - ✅ 消息响应时间 < 2s - ✅ 支持并发处理多个渠道 - ✅ 内存占用合理 ### 15.4 可用性标准 - ✅ 文档完善 - ✅ 配置简单 - ✅ 易于部署 ## 16. 未来展望 ### 16.1 短期 (3 months) - 添加更多 Skills - 完善 WebUI 功能 - 性能优化 ### 16.2 中期 (6 months) - 支持更多 LLM Provider - 插件市场 - 云服务集成 ### 16.3 长期 (1 year) - 企业版功能 - 多 Agent 协作 - 高级 RAG 支持 --- **文档版本**: 1.0 **创建日期**: 2026-02-19 **作者**: MyClaw.NET Team