MimoAgent

Imported from XWJDream/MimoAgent (AGENTS.md). Install upstream with npx skills add XWJDream/MimoAgent. Copyright stays with the author.

MimoAgent Desktop - AGENTS.md

本文档记录 MimoAgent 的 Agent 系统架构、工具链、技能系统、Hook 机制和扩展方式，供开发者和 AI Agent 参考。

项目概览

MimoAgent 是一个基于 MiMo v2.5 Pro 模型的 AI 编程桌面助手。采用 Electron + React 前端 + 独立 Agent 引擎的双层架构。

mimo-desktop/
├── src/                    # Electron 应用层
│   ├── main/               # 主进程（IPC、窗口、AgentService）
│   ├── preload/            # 安全桥接层
│   ├── renderer/           # React UI（组件、状态、样式）
│   └── shared/             # 共享类型和 IPC 通道
├── engine/                 # Agent 引擎（独立 npm 包）
│   └── src/
│       ├── core/           # Agent 循环、子 Agent、Hook、校验
│       ├── tools/          # 内置工具（文件、Shell、Git、Web）+ 截断器
│       ├── llm/            # LLM 客户端、流式处理、Token 估算、多 Provider、Prompt 缓存
│       ├── context/        # System Prompt、上下文压缩、压力检测、溢出处理
│       ├── config/         # 配置加载、校验、默认值
│       ├── permissions/    # 权限检查（通配符模式匹配）
│       ├── sandbox/        # Docker 沙盒
│       ├── skills/         # 技能注册、匹配引擎
│       ├── supervisor/     # 督导规则引擎
│       ├── sub-agents/     # 子 Agent 定义
│       ├── memory/         # 记忆系统（SQLite FTS5 全文搜索）
│       ├── task/           # 任务系统（五状态状态机 + Gate 机制）
│       ├── plugin/         # 插件系统（Hook 机制）
│       └── mcp/            # MCP 集成（JSON-RPC 2.0 客户端）
├── scripts/                # 构建辅助脚本
└── resources/              # 应用图标

1. Agent 核心架构

1.1 Agent 类 (engine/src/core/agent.ts)

顶层编排器，组装所有子系统：

class Agent {
  constructor(config: MimoConfig, workspace?: string)
  initialize(): Promise<void>      // 加载记忆、注册工具、构建 System Prompt
  run(prompt, options): AsyncGenerator<LoopEvent>  // 主运行循环
  clearConversation(): void        // 重置对话
  setHooks(hooks: AgentHooks): void
  getUsageTracker(): UsageTracker
}

1.2 Agent Loop (engine/src/core/agent-loop.ts)

核心循环，AsyncGenerator<LoopEvent>：

1. 发送消息 + 工具定义到 LLM（流式/非流式）
2. StreamCollector 收集响应（组装 tool_call delta）
3. 无工具调用 → yield done → 结束
4. 有工具调用 → 逐个执行：
   a. 权限检查
   b. 参数校验
   c. 执行工具
   d. 运行 Hook
5. 循环检测：相同 tool+args 重复 3+ 次 → 中止
6. 错误反思：生成反思提示，继续循环
7. 上限：maxTurns（硬限制 100）

1.3 LoopEvent 类型

1.4 AgentHooks

interface AgentHooks {
  beforeTool?: (name: string, args: Record<string, unknown>) =>
    Promise<{ skip?: boolean; modifiedArgs?: Record<string, unknown> } | void>;
  afterTool?: (name: string, result: ToolResult) =>
    Promise<{ modifiedResult?: ToolResult } | void>;
}

2. 内置工具（22+ 个）

工具基类

abstract class BaseTool {
  abstract name: string;
  abstract description: string;
  abstract parameters: ToolDefinition;  // OpenAI function-calling schema
  abstract riskLevel: 'read' | 'write' | 'execute' | 'destructive';
  abstract categories: string[];
  abstract execute(args: unknown, context: ToolContext): Promise<ToolResult>;
}

工具列表

工具预设

3. 子 Agent 系统（5 个）

子 Agent 通过 sub_agents_run 工具调用，每个子 Agent 有独立的 System Prompt 和工具集。

子 Agent 配置

// MimoConfig.subAgents
interface SubAgentConfig {
  enabled: boolean;
  maxConcurrent: number;    // 默认 3
  maxTurns: number;         // 默认 10
}

4. 技能系统（7 个内置）

技能通过关键词匹配自动推荐，也可手动激活。

技能匹配算法

1. 将用户输入转小写
2. 遍历所有技能的 triggers 数组
3. 计算置信度：0.5 + matchedTriggers.length * 0.2（上限 1.0）
4. 按置信度降序排列，返回前 3 个

5. 督导系统（Supervisor）

规则引擎，检查 Agent 输出的代码质量。

规则类型

配置

// MimoConfig 中无独立配置，通过 IPC 控制
window.api.supervisor.getViolations()
window.api.supervisor.setEnabled(true/false)

6. LLM 客户端 (engine/src/llm/)

配置

interface LLMClientConfig {
  apiKey: string;
  baseUrl: string;       // "https://api.xiaomimimo.com/v1"
  model: string;         // "mimo-v2.5-pro"
  maxTokens: number;     // 4096
  temperature: number;   // 0.2
  timeout: number;       // 60000ms
  reasoningEffort?: 'low' | 'medium' | 'high';
}

流式处理

• 使用 stream_options: { include_usage: true } 获取 token 统计
• StreamCollector 组装 delta，ToolCallAssembler 缓存 argumentsDelta
• 最后一个 chunk（choices=[]，usage 在顶层）优先检查 usage

Token 估算（engine/src/llm/tokenizer.ts）

CJK:      1.5 token/char
Hangul:   0.8 token/char
ASCII:    0.25 token/char + 1 per word
Symbol:   1.0 token/char
Space:    0.2 token/char

重试策略（engine/src/llm/retry.ts）

指数退避，默认 3 次重试，初始延迟 1s。

7. 上下文管理

System Prompt 构建

buildSystemPrompt(config, memory, cwd) 动态生成，包含：

1. 身份定义（"You are MimoAgent..."）
2. 环境信息（工作目录、平台、Git 状态、日期）
3. 项目文件树（顶层）
4. 项目记忆（.mimo-agent/memory.md）
5. 项目上下文文件（MIMO.md, .mimo-rules, CLAUDE.md）
6. 编码规范
7. 工具使用策略
8. 权限模式说明
9. 用户追加（systemPromptAppend）

上下文压缩

当 token 超过 contextWindow * 0.7 时自动压缩：

8. 权限系统

风险等级

路径权限规则

// 内置规则
{ pattern: '**/.env*', actions: ['write', 'edit', 'shell'], policy: 'confirm' }
{ pattern: '**/.git/**', actions: ['*'], policy: 'deny' }
{ pattern: '**/node_modules/**', actions: ['*'], policy: 'deny' }

权限模式

9. IPC 通信

通道分组

AgentService 桥接

src/main/agent-service.ts 是 Electron 和引擎的桥梁：

1. 动态导入 Agent 类（pathToFileURL + import()）
2. 翻译 AppConfig → MimoConfig
3. 消费 agent.run() 的 AsyncGenerator，转发 LoopEvent 到渲染进程
4. 管理 AbortController 实现停止功能
5. 连接 PermissionChecker 到 Electron 原生对话框

10. 配置系统

配置合并顺序（深覆盖）

1. 内置默认值 (engine/src/config/defaults.ts)
2. 全局配置 ~/.mimo-agent/config.json
3. 项目配置 <workspace>/.mimo-agent/config.json
4. 环境变量 MIMO_*
5. 编程传入参数

关键配置项

{
  model: 'mimo-v2.5-pro',
  apiBase: 'https://api.xiaomimimo.com/v1',
  apiKey: '',
  maxTokens: 4096,
  temperature: 0.2,
  reasoningEffort: 'medium',
  contextWindow: 1_048_576,      // 1M tokens
  permissionMode: 'suggest',
  toolPreset: 'act',
  maxTurns: 50,
  stream: true,
  sandbox: { enabled: false },
  subAgents: { enabled: true, maxConcurrent: 3, maxTurns: 10 },
}

11. 扩展指南

添加新工具

// 1. 继承 BaseTool
import { BaseTool } from '../base.js';

export class MyTool extends BaseTool {
  name = 'my_tool';
  description = 'Does something useful';
  riskLevel = 'read';
  categories = ['file'];
  parameters = {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input value' },
    },
    required: ['input'],
  };

  async execute(args: { input: string }, context: ToolContext) {
    return { output: `Processed: ${args.input}`, isError: false };
  }
}

// 2. 注册到 builtin/index.ts
registry.register(new MyTool());

添加新技能

// engine/src/skills/builtin/index.ts
{
  id: 'my-skill',
  name: '我的技能',
  description: '技能描述',
  triggers: ['关键词1', 'keyword2'],
  icon: 'MyIcon',
  priority: 5,
}

添加新子 Agent

// engine/src/sub-agents/index.ts
export const SUB_AGENTS: Record<string, SubAgentDef> = {
  // ... 现有子 Agent
  my_agent: {
    name: 'My Agent',
    systemPrompt: 'You are a specialized agent for...',
    tools: ['read_file', 'grep', 'glob'],
    maxTurns: 5,
  },
};

添加 Hook

agent.setHooks({
  beforeTool: async (name, args) => {
    if (name === 'shell' && args.command.includes('rm -rf')) {
      return { skip: true };  // 跳过危险命令
    }
  },
  afterTool: async (name, result) => {
    if (name === 'write_file' && !result.isError) {
      console.log(`File written successfully`);
    }
  },
});

13. 记忆系统 (engine/src/memory/)

SQLite FTS5 全文搜索

基于 SQLite FTS5 的全文搜索索引，支持 BM25 排名算法和相对分数过滤。

class MemoryManager {
  constructor(dbPath: string)
  async initialize(): Promise<void>
  async search(query: string, options?: SearchOptions): Promise<MemoryEntry[]>
  async add(entry: MemoryEntry): Promise<void>
  async reconcile(): Promise<void>  // 磁盘-数据库增量同步
}

记忆分层

14. 任务系统 (engine/src/task/)

五状态状态机

open → in_progress → done
                  → blocked
                  → abandoned

层级任务 ID

支持层级任务 ID：T1, T1.1, T1.1.1

Gate 机制

Agent 结束前检查未完成任务，确保所有任务都被处理。

统一 task 工具（9 种操作）

15. 工具输出截断 (engine/src/tools/truncator.ts)

默认配置

• 阈值：50K 字符
• 保留策略：头尾各保留 40%

特殊策略

截断后保存到磁盘，前端可查看完整输出。

16. 压力检测 (engine/src/context/overflow.ts)

4 级压力指示

自动微压缩

保留 tool_use，清空可再生结果。

17. 通配符权限系统 (engine/src/permissions/)

glob 风格模式匹配

支持 *, ?, ** 通配符。

最后规则优先（last-match-wins）

三层合并

1. 默认规则
2. Agent 模式（build/plan/explore）
3. 用户配置

18. 溢出检测 (engine/src/llm/errors.ts)

上下文溢出自动处理

• 20+ 正则模式覆盖主流 Provider
• 溢出 → 自动压缩 → 重试

19. 插件系统 (engine/src/plugin/)

本地插件加载

从 ~/.mimo-agent/plugins/ 加载本地插件。

6 种 Hook

链式处理 + 错误隔离。

20. MCP 集成 (engine/src/mcp/)

JSON-RPC 2.0 客户端

支持 HTTP/SSE + stdio 传输。

多服务器管理

• 工具适配器
• serverName:toolName 格式避免冲突

21. 多 Provider 支持 (engine/src/llm/providers/)

内置 Provider

Provider 注册中心

• 模型发现
• 配置扩展：MIMO_PROVIDER 环境变量

22. Prompt 缓存 (engine/src/llm/cache.ts)

3 个缓存断点

1. system
2. 中点
3. 最后用户消息

自动检测

自动检测模型缓存支持，缓存命中率统计。

23. 斜杠命令系统

8 个内置命令

24. 用户体验增强

输入历史

上下箭头回忆，100 条历史记录。

交互式权限对话框

• Diff 预览
• once/always/reject 选项

响应式布局

超宽屏自适应。

25. 测试

# 全部测试（668 个）
npm test

# 分模块
npm run test:engine     # 488 个
npm run test:main       # 82 个
npm run test:renderer   # 98 个

# 类型检查
npm run typecheck

# Lint
npm run lint

测试覆盖率

13. 构建和发布

# 开发模式
npm run start:dev

# 清理 + 构建
npm run clean
npm run build

# 打包 Windows
npx electron-builder --win --publish never

# CI/CD
# push tag v* 触发 GitHub Actions Release
# 自动执行: Lint → Typecheck → Test → Build → Package → Create Release

14. 相关资源

最后更新：2026-06-15 | 版本：v0.4.0