MyClaw.NET 设计方案

1. 项目概述

1.1 项目目标

将基于 Go 语言和 agentsdk-go 的 myclaw 项目 1:1 复刻到 C# .NET 平台，使用 AgentScope.NET 作为底层框架。

1.2 参考项目

• 源项目: stellarlinkco/myclaw

- 语言：Go - 框架：agentsdk-go - 特点：个人 AI 助手，支持多渠道、定时任务、长期记忆等

• 底层框架: 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 核心组件映射

3. 模块设计

3.1 CLI 模块

命名空间: MyClaw.CLI

职责:

• 提供命令行接口
• 支持 agent, gateway, onboard, status 子命令
• 参数解析和验证

技术栈:

• System.CommandLine (命令行框架)
• Spectre.Console (美化输出)

主要类:

class Program
class AgentCommand
class GatewayCommand
class OnboardCommand
class StatusCommand

3.2 Agent 模块

命名空间: MyClaw.Agent

职责:

• 实现单次消息处理和 REPL 交互模式
• 集成 AgentScope.NET 的 ReAct Agent
• 处理用户输入和 AI 响应

核心类:

class MyClawAgent : EnhancedReActAgent
{
    // 使用 AgentScope.NET 的 EnhancedReActAgent 作为基类
    // 添加 myclaw 特定功能
}

class ReplLoop
{
    // 实现交互式循环
}

3.3 Gateway 模块

命名空间: MyClaw.Gateway

职责:

• 协调所有服务（Channels, Cron, Heartbeat）
• 消息总线管理
• 生命周期管理

核心类:

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

接口设计:

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

核心类:

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 系统集成

核心类:

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 (成熟的调度框架)

核心类:

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 读取配置

核心类:

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 + 环境变量）
• 配置验证
• 敏感信息保护

核心类:

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 关键库

5.3 开发工具

• IDE: Visual Studio 2022 / Rider / VS Code
• 版本控制: Git
• 包管理: NuGet

6. 兼容性设计

6.1 与 myclaw (Go) 的兼容性

6.2 与 AgentScope.NET 的集成

7. 安全设计

7.1 敏感信息保护

• 配置文件权限：600 (仅所有者可读写)
• 优先使用环境变量存储 API 密钥
• .gitignore 排除敏感文件

7.2 渠道安全

• Telegram: allowFrom 白名单
• Feishu: Verification Token 验证
• WeCom: 消息加密解密
• WebUI: 可选身份验证

7.3 数据安全

• 本地 SQLite 数据库
• 敏感数据加密存储（如需要）

8. 性能考虑

8.1 并发处理

• 使用 async/await 异步模式
• Channel 实现消息队列
• 并行处理多个渠道消息

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. 风险与挑战

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