Mutsumi AGENTS.md

Mutsumi 项目开发指南（Agent 贡献者版）

本文件面向参与 Mutsumi 开发的 AI 编码 Agent，介绍各模块职责、模块间的接线方式，以及非平凡/反直觉的设计约束。 Mutsumi（若叶睦）是一款 VS Code 多 Agent 笔记本环境插件：Agent 会话以 .mtm（JSON）文件持久化，经 VS Code Notebook API 呈现，工具/上下文/编排围绕该模型展开。

---

1. 架构总览

src/
├── adapters/          # 适配器层：把 AgentRunner 与 UI/传输解耦（Notebook / HTTP / Lite）
├── agent/             # Agent 核心逻辑（执行循环、LLM 客户端、编排、标题生成）
├── codebase/          # 代码库服务（RAG 向量搜索）
├── config/            # 配置系统（AgentType、toolSets、MCP Server 的合并/校验/解析）
├── contextManagement/ # 动态上下文管理（模板引擎、历史装配、幽灵块、Skills）
├── httpServer/        # HTTP API 服务（复用同一套 Agent 执行链路）
├── mcp/               # MCP 宿主（连接 registry、ITool 适配、结果投影）
├── notebook/          # Notebook UI 实现（serializer、自定义渲染器、工具栏命令）
├── sidebar/           # 侧边栏视图（Agent / 审批 / Context / Shell 任务）
├── registry/          # 配置运行时注册表（ToolSetRegistry、AgentTypeRegistry）
├── tools.d/           # 内置工具实现与工具运行时（ToolRegistry、ToolSet、权限）
└── types.ts / utils.ts / i18n.ts / controller.ts / extension.ts

核心分层原则

1. 适配器解耦：AgentRunner 只依赖 IAgentSession 接口，不感知 Notebook 还是 HTTP。Notebook/HTTP 各自通过 adapter 复用同一执行链路。
2. URI 优先：所有文件操作使用 vscode.Uri，支持多根工作区与其他扩展的 FileSystemProvider 特殊 schema。Mutsumi 自身数据（.mutsumi/）固定在工作区列表 [0]。
3. 工具分层：内置工具（静态注册）与 MCP 工具（动态发现）是两套体系，在 ToolSet 构建时组合；task_finish 独立于一切工具集配置。
4. 装配点唯一：extension.ts 是唯一激活/装配入口（初始化顺序、配置监听、事件订阅都在这里）。
5. 禁止反向依赖：mcp 不 import sidebar/notebook；serializer/fileOps 不发起 MCP 连接；ToolExecutor 对 MCP 零特判；sidebar 只读依赖 mcp registry 状态。

---

2. Notebook 系统与 UI 层

2.1 .mtm 文件模型与 Serializer（notebook/serializer.ts）

.mtm 是 JSON：{ formatVersion: 1, metadata: AgentMetadata, context: PersistedAgentMessage[], notes?: NotebookNote[] }。VS Code 通过 NotebookSerializer 把它与 Notebook 文档互相转换。

核心算法是 messages ↔ generic cells 双向映射（messagesToGenericCells / genericCellsToMessages），并被 HeadlessAdapter 复用，因此协议是"与 UI 无关"的：

• User 消息 → Code cell（kind 2）
• Markup cell（kind 1）→ 用户注释，按 notes.beforeUserIndex 独立持久化，不进入 Agent 历史
• 紧随 user 的 assistant/tool 消息组不单独建 cell，而是存入该 user cell 的 mutsumi_interaction metadata，渲染为该 cell 的输出区（这是最反直觉的点）
• Assistant/tool 消息必须附着于前置 user；磁盘中不支持孤儿 assistant/tool 或 system 消息
• mutsumi_interaction 只存在于 user cell，永不写在 Markup cell 上
• 连续 user 是合法 pending turns；只在 provider 边界临时合并，磁盘 Cell 边界保持不变
• cell value 中保存的幽灵块 markdown 在反序列化时剥离（stripGhostBlockFromCell），结构化版本在 metadata 中