Mutsumi 项目开发指南（精简版）

本文件面向 AI 编码 Agent，介绍 Mutsumi 项目的架构设计理念和开发原则。 Mutsumi（若叶睦）是一款 VS Code 多 Agent 笔记本环境插件。

项目概述

Mutsumi 是一款基于 VS Code 的 LLM Agent 插件，采用子母 Agent 范式，将复杂任务拆解为多个子任务并行处理。

核心特性

• 🥳 子母 Agent 范式：支持任务分治，避免长对话导致的注意力稀释
• 📝 Notebook 原生体验：利用 VS Code Notebook API 实现 .mtm 文件格式的 Agent 对话
• 🔄 动态上下文系统：支持 @[文件引用] 语法、工具预执行和宏定义
• 🛠️ 预处理器支持：实现条件编译和宏替换
• 🌐 多工作区原生支持：兼容多根工作区和 FileSystemProvider 特殊 schema

技术栈

项目架构

分层架构

src/
├── adapters/          # 适配器层 - UI/传输解耦
├── agent/             # Agent 核心逻辑（执行循环、编排、LLM 客户端）
├── codebase/          # 代码库服务（RAG 向量搜索）
├── contextManagement/ # 动态上下文管理（模板引擎）
├── httpServer/        # HTTP API 服务
├── notebook/          # Notebook UI 实现
├── sidebar/           # 侧边栏视图
├── tools.d/           # 内置工具实现
└── 入口及类型定义

架构设计原则

1. 适配器模式：通过抽象接口，Agent 核心与 UI 完全解耦
2. URI 优先：所有文件操作使用 vscode.Uri，支持多工作区和远程文件系统
3. 工作区 [0] 约定：Mutsumi 自身数据存储在工作区列表 [0] 的 .mutsumi 目录
4. 分层工具系统：工具注册 → 工具集 → 权限 → 具体实现

构建和开发

常用命令

npm i           # 安装依赖
npm run compile # 编译 TypeScript
vsce package    # 打包为 VSIX 文件

开发调试

1. 按 F5 启动 Extension Development Host
2. 在新窗口中测试插件功能

编码规范

文件操作规范

必须使用 vscode.Uri 而非字符串路径：

// ✅ 正确
const uri = vscode.Uri.file('/absolute/path');
const content = await vscode.workspace.fs.readFile(uri);

// ❌ 错误
const content = fs.readFileSync('/absolute/path');

工具函数位于 tools.d/utils，提供 URI 解析和权限检查能力。

错误处理

工具执行应返回统一格式：

try {
    const result = await operation();
    return { status: 'success', result };
} catch (error) {
    return { 
        status: 'error', 
        error: error instanceof Error ? error.message : String(error) 
    };
}

核心模块概念

1. Notebook 系统 (.mtm 文件)

• .mtm 文件是 JSON 格式，包含 Agent 元数据和对话历史
• Code Cell → 用户输入 / Markup Cell → 助手回复
• 临时引用内容使用 Ghost Block 机制，保存时自动剥离

2. 动态上下文系统

文件引用语法：

@[path/to/file]                    # 引用整个文件
@[path/to/file:10:20]             # 引用行范围
@[toolName{"arg": "value"}]       # 预执行工具

处理流程： 提取宏定义 → 扫描标签 → 递归处理嵌套引用 → 输出

3. 工具系统

能力模型：

工具能力由配置中的 toolSets 字段定义，基础组合包括：

• read - 文件读取、搜索、信息查询（只读）
• deliver - 文件写入、编辑、shell 执行（写入操作）
• dispatch - Agent 编排（dispatch_subagents, get_agent_types）

AgentType 通过组合这些工具集定义能力边界。例如：

• chat: []
• orchestrator: ['read', 'deliver', 'dispatch']
• planner: ['read', 'dispatch']
• implementer: ['read', 'deliver', 'dispatch']
• reviewer: ['read']

非根 Agent 的完成义务：

存在 parent_agent_id 的 Agent（即通过 dispatch_subagents 创建的 Agent）运行时额外获得 task_finish 工具，用于向父 Agent 报告完成状态。

审批流程：

工具调用请求 → 检查自动审批 → 
  是 → 直接执行
  否 → 创建审批请求 → 侧边栏显示 → 用户批准/拒绝 → 执行或返回错误

4. 子母 Agent 范式

生命周期：

父 Agent
    ↓ dispatch_subagents
创建子 Agent (多个并行)
    ↓ 各自执行
子 Agent 调用 task_finish
    ↓ 通知父 Agent
父 Agent 收集结果 → 继续执行

5. RAG 向量搜索

• 内存 SQLite + 向量扩展
• 自动持久化到 .mutsumi/cache/
• 基于哈希的增量更新
• 语义分块（函数/类边界）优先，固定窗口回退

6. HTTP Server

提供 RESTful API 管理 Agent 和聊天，支持 SSE 流式响应。

重要参考

类型定义

参见 src/types.ts 中的核心类型：

• AgentMetadata - Agent 元数据
• AgentMessage - 消息格式
• ITool / ToolContext - 工具接口

工具实现规范

新工具需实现 ITool 接口，包括：

• name - 工具名称
• definition - JSON Schema 描述
• execute - 执行函数（含权限检查）
• prettyPrint (可选) - 自定义渲染

配置优先级

模型选择优先级（从高到低）：

1. 请求参数中的 model
2. Notebook 元数据中的 model
3. VS Code 配置 mutsumi.defaultModel

文件命名约定

开发注意事项

多工作区支持

所有涉及工作区的操作应使用工作区 [0] 作为 Mutsumi 主工作区：

const workspaceRoot = vscode.workspace.workspaceFolders?.[0];
if (workspaceRoot) {
    const mutsumiDir = vscode.Uri.joinPath(workspaceRoot.uri, '.mutsumi');
}

权限控制

• 工具执行前必须检查 allowedUris 权限
• 文件操作必须解析为绝对 URI 后检查

扩展阅读

• VS Code Notebook API
• VS Code Extension API

许可证

本项目采用 Apache License 2.0 开源许可证。