# Mimo Code Collab

> 当需要与 mimo.code（小米 MiMo 代码智能体）协同开展任何工程任务时加载本技能——包括但不限于：代码编写、修改、BUG 修复、代码审核、项目分析与重构、技术方案/架构讨论与文档编写、非代码文件（配置/文档/规格）讨论与编写、GitHub 变更的内容生成与审阅。覆盖 mimo.code 的能力边界、环境无关的通用调用方法（同时适配「Dynamic-mcp 工具中转连接」与「MCP 服务方式直接连接」两种接入形态）、以及「主Agent × mimo.code 通用分工闭环 + 双范式（串行交替审核 / 并行交叉审核）+ 强制前置分析约束（子任务启动前先判定场景与范式）+ 防死锁」的协同工作流。即使完全未接触过 mimo.code，读完本技能也可正确调用并组织协同。

- Skill: `zhangweildlh/mimo-code-collab` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add zhangweildlh/mimo-code-collab`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangweildlh/mimo-code-collab/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zhangweildlh (https://skillmd.com/u/zhangweildlh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhangweildlh/mimo-code-collab

---


# Mimo Code Collab（mimo.code 使用与协同手册）

## Overview
本技能把 `mimo.code` 定位为一名"远程协作者"：它在小米 MiMo 服务端具备独立推理能力，能在指定目录内生成、修改、分析代码与文本，也能承载技术讨论。主Agent 则充当"本地主编 / 架构师 / 执行者"，负责决策、记忆、以及对 GitHub 等外部系统的真实操作。二者通过**通用分工闭环**协同，像两名工程师一样反复讨论、相互审核、分工修订，最终形成唯一交付。

本技能的协同核心是**「三要素贯穿 + 双范式驱动」**：
- **三要素（讨论 / 审核 / 分工）贯穿任一任务**：无论编写代码、修复 BUG、讨论方案还是处理 GitHub，双方都持续进行"讨论（互相提出观点/方案）→ 审核（互相给出详细审核报告）→ 分工（主Agent 掌握决策与外部操作权，mimo 掌握内容/代码产出权，能力边界与权限约束之外的工作由主Agent 完成）"。
- **双范式**：串行交替审核范式（范式A）与并行交叉审核范式（范式B），按子任务性质动态择用（详见"通用协同范式"）。
- **强制闭环 + 防死锁**：每份协同都有显式出口条件、最大轮次、停滞检测与仲裁升级，绝不无限循环。

> **本技能的环境无关性**：不绑定任何具体连接器命名、分组名或本机路径。无论目标 Agent 是通过 `Dynamic-mcp` 工具中转连接 `mimo.code`，还是以 MCP 服务方式直接连接 `mimo.code`，本技能均适用（见"通用调用方法"）。

## When To Use（触发场景）
在以下任一情况下加载本技能：
- 需要 `mimo.code` 编写、修改、重构、调试或审查代码；
- 需要 `mimo.code` 分析既有项目（只读评估结构、缺陷、可维护性）；
- 需要与 `mimo.code` 讨论技术方案、架构、实现方法、可行性；
- 需要 `mimo.code` 参与 GitHub 工作流（生成代码变更、提交信息、PR 描述、Review 意见）——**注意：GitHub 的真实 git/gh 操作由主Agent 执行，mimo 只产出内容**；
- 任何"主Agent 出题/审查 + mimo 实现/修订"的分工场景；
- 首次接触 `mimo.code`、不确定其能力/边界/参数时，先读本技能再动手。

## 激活与触发（Activation）
本技能**由主Agent 在识别到 mimo.code 协同场景时自动加载使用**，也支持用户显式调用：
- **自动加载（场景/任务匹配触发）**：当主Agent 判断当前任务属于"When To Use"所列任一场景（编码/修改/审核/讨论方案/GitHub 内容生成等涉及 mimo.code 协同），会基于本 SKILL.md 的 `description` 场景化描述主动加载本技能，**不依赖某个固定激活词**——靠语义匹配而非词表。
- **显式调用**：用户也可直接以 `/mimo-code-collab` 触发本技能。
- **覆盖增强建议**：若希望自动加载覆盖更全，可在主Agent 的常驻记忆/系统提示中加入"涉及 mimo.code 的协同任务，先加载 mimo-code-collab 技能"；本技能 `description` 已尽量穷举适用场景，但无法（也不应）预列所有口语化激活词——语义匹配比词表更鲁棒。
- **可直接复用的首条注入提示词**：若你希望在"对话会话第一条"就提醒主Agent 先判断是否激活本 Skill，见 `references/session-activation-prompt.md`（含精简提示词与用法）。

## 强制前置分析约束（子任务启动闸门，★ 最高优先级元规则）
> **这是使用本技能时不可跳过的前置闸门（gate）。它优先级高于任何具体协同模板、高于双范式定义本身。** 凡涉及"主Agent × mimo.code 协同"的任务，在**每一个任务 / 子任务 / 子步骤 / 子流程**正式开展之前，主Agent **必须**先完成以下三步，未判定不得开工：

> 下文「通用协同范式」小节将定义"范式A/B""四类协同"等术语；本闸门先用之，完整决策方法与三步走细节见 `references/collab-workflow.md` 第 1.4 / 1.5 节。

1. **分析（Analyze）**：对即将开展的子任务/子步骤/子流程做性质与场景归类——它属于"收敛型"（要打磨出唯一交付）还是"铺开型"（可并行调研/搜索/生成），并归其所属协同场景（编码 / 讨论 / GitHub / 项目开发）。
2. **判定（Decide）**：基于上一步的分析结论，显式确定其**适用范式**（范式A 串行 / 范式B 并行 / 二者分段混合；具体范式择用方法见 `references/collab-workflow.md` 第 1.4 节）。
3. **执行（Execute）**：严格按判定出的"适用场景 + 适用范式"正式开展工作/操作，全程遵守对应协同模板与闭环元规则（详见 `references/collab-workflow.md` 第 2 节）。

**强制要点（不允许例外）**：
- 不允许"先动手再补范式"——**判定必须在开工动作之前完成**，并在协同时显式记录判定结论（场景 + 范式）；
- 复合任务里**每个子任务/子步骤/子流程都要重新走一遍这个闸门**，不能用"整个任务选了一个范式"来替代某一步的判定；但**范式A/B 内部的逐轮迭代（v1→v2→v3…）属于同一子任务的收敛过程，不重复走闸门**——闸门只在"进入新子任务"或"切换子任务性质"时各走一次；
- 此判定是主Agent 的责任，mimo 不参与判定，只承接判定后的产出工作；
- 决策流程的具体问题与设计见 `references/collab-workflow.md` 第 1.4 / 1.5 节。

## 核心能力（Capabilities）与边界
`mimo.code` 基于 MiMo 大模型在**小米服务端**完成推理，对外表现为"接收一段自然语言任务描述 + 一个工作目录，返回一个执行结果与产物"。其能力覆盖：
1. **编写代码/文件**：按规格生成完整、可运行、带注释的文件（代码或文本/配置/文档）；
2. **修改代码/文件**：读取指定文件、定位缺陷、就地修复（保持签名/接口不变）；
3. **代码审核**：对目标文件做 code review，列出缺陷/风险并按严重度排序（默认只读、不改写，除非明确要求）；
4. **项目分析**：对目录做结构、依赖、可维护性、风险分析（只读，不改动）；
5. **方案/技术讨论**：承载可行性、技术路线、架构、实现方法的开放性讨论与比选；
6. **内容生成**：为 GitHub 等场景生成提交信息、PR 描述、Review 意见、规格文档。

**能力边界（务必先读，避免误用）**：
- `mimo.code` 是**代码/文本智能体**，作用域限定在 `working_dir` 内的文件读写与技术讨论；**实测它确实会在 `working_dir` 内生成/修改文件**（如落盘 `*.md` 方案、`*.py` 脚本、Review 报告等），并非"只读"——这既是它的生产力来源，也是需显式约束写范围的原因（只读/讨论任务必须在 `prompt` 写明"不要写任何文件 / 只分析"）。若遇响应超时但任务疑似已完成，可先去 `working_dir` 查看是否已有落盘产物作为兜底。
- 它**不直接操作 GitHub / git / 外部系统**。所有 git commit、push、开 PR、merge 等真实动作由**主Agent 用 gh/git 执行**；mimo 只负责"写什么内容"（代码 diff 建议、提交信息、PR 描述文本）；**主Agent 执行 git 时须遵循路径核验防误报规范**（先 `ls .git` 复核、用 `git -C "D:/绝对/Windows/路径"` 或先 `cd /d/绝对/路径` 再执行，禁止 `git -C /d/...`）。
- 所有写操作默认作用于 `working_dir` 指定的目录；讨论/分析类任务须显式声明"只分析、不写文件"，避免误写；
- **能力边界 / 权限约束之外的工作由主Agent 完成**：例如真实 git/gh 动作、需要主Agent 本地环境才能运行的验证（编译/测试/依赖安装）、需要访问主Agent 私有凭据或内部系统的操作，一律由主Agent 执行，mimo 只提供可供主Agent 复核的内容。

## 通用调用方法（Invocation，环境无关）
`mimo.code` 在不同 Agent 上的接入形态可能不同，本技能统一抽象为以下两种，**首次使用前先做接入探测**：

- **形态 A — `mimo.code` 经 `Dynamic-mcp` 类可执行中继（典型实现如 `dmcp.exe`）中转连接到 Agent**：宿主平台先把本脚本（`mimo_mcp.py` + `mimo.exe`）登记为中继的一个 server group（分组名如 `mimo-mcp`，**具体名随平台而定**），再通过动态工具通道（如 `call_dynamic_tool`）调用，参数为 `{group: <你的 mimo 分组名>, name: "mimo.code", args: {...}}`。探测：`list_groups` 确认分组已连接，`get_dynamic_tools` 取 `mimo.code` 精确 schema。
  - **中继侧超时/保活须同步上调（★ 关键部署要点）**：`dmcp.exe` 这类中继自身往往带握手超时与保活机制；当 `MIMO_CODE_TIMEOUT` 上调（本脚本默认已 900s）后，**中继的超时/保活配置也要一并调大**。否则 mimo 真实耗时接近中继上限时，会在响应回传前被中继强杀（表现为 `-32001` / 工具调用超时 / 串台）——但 mimo 后台往往**已落地文件**，主Agent 可直接从 `working_dir` 读取结果兜底，不必重跑。
  - **宿主配置变更后需重载信任**：修改宿主的 MCP 配置（如 `mcp.json`）会触发宿主对 server 的哈希信任校验，未重载则 server 可能被标为 `untrusted` / `demoted` 而不加载；变更后须按宿主要求**重启或写审批表激活**，否则双范式与稳定性专项测试都跑不起来。
- **形态 B — `mimo.code` 以 MCP 服务方式直接连接 Agent**：`mimo.code` 作为原生 MCP 工具直接暴露（工具名可能为 `mimo__code` 或 `<前缀>__code`）。探测：查阅当前 Agent 的 MCP 工具列表，确认 `mimo.code` 的确切工具名。

> 分组名（如 `mimo-mcp`）与工具前缀因环境而异，**不要写死**；始终以探测到的实际命名为准。两种形态的参数语义完全一致，区别仅在"如何寻址到 mimo.code"。

`args` 参数全表（通用，与接入形态无关）：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string | 是 | 任务自然语言描述。编写/修改须含"只写某文件/只修改某文件"等边界约束；讨论须含"只分析、不写任何文件" |
| `working_dir` | string | 否 | 任务根目录（绝对路径）。**默认真实仓库工作副本**，仅受硬约束（mimo 部署强制沙箱 / 安全策略禁止直写 / 高风险探索测试）才回退隔离沙箱 `<SANDBOX>`；不传则按代理默认目录 |
| `format` | string | 否 | `"text"` 或 `"json"`。编程/讨论任务用 `"text"` |
| `continue_session` | bool | 否 | 跨调用延续上下文开关。**是否生效因环境而异**：首次使用应先做 2 轮探测（第 1 轮提方案，第 2 轮带 `continue_session=true` 追问"延续上文"；若 mimo 能接上则说明该环境支持会话保持，否则不保活）。**无论环境如何，主Agent 在 prompt 中回灌历史都是最稳妥的兜底** |
| `skip_permissions` | bool | 否 | 设为 `true` 跳过文件操作权限确认，使非交互执行不挂起。**建议始终设为 `true`** |

完整参数语义、`mimo.health` 健康检查、`mimo.chat` 与 `mimo.code` 的分工、Token 消耗真相，见 `references/invocation.md`。

## 关键边界与限制（CRITICAL — 调用前必读）
以下结论来自实测，违反会直接导致任务失败：
1. **禁止并行批量调用**：对 `mimo.code` 同时发起多个调用会全部返回 `"Group not found"`（代理形态）或类似错误；必须**串行顺序**调用。（注意：串行指"对 mimo 的调用"不能并发；范式B 中的"并行"是主Agent 与 mimo 承担**不同子任务**的并行，仍各自单次串行调用 mimo。）
2. **连接超时/失联 → 强制重试 2 次 + 连续 3 次降级门禁**：常见错误——`"Group not found"`（代理冷启动/瞬时竞态）、`MCP -32000 Connection closed`（代理重连中）、原生 MCP 的瞬时断连、TCP/HTTP 连接超时。按「强制连接韧性约束」（见下方专节，★ 最高优先级）处理：**任何连接超时/失联先原样重试 2 次**，仍失败且连续累计 3 次才允许主 Agent 单独工作。
3. **`continue_session` 是否保活因环境而异**：见上方"通用调用方法"。多轮记忆的**最稳妥兜底**是由**主Agent 在每轮把历史上下文拼进 `prompt` 回灌**给 mimo。
4. **Token 真相**：`mimo.code` 返回中自带用量报告（输入/输出/推理/费用），**费用恒为 `$0`**——真正的推理算力由 MiMo 在小米服务端完成，使用的是小米侧额度（`MIMO_API_KEY` 之类），**不消耗主Agent 的 LLM 额度**。主Agent 仅承担"请求参数 + 返回结果"进入自身上下文的（输入）token；长返回会膨胀主Agent 上下文，长会话需管控（回灌时压缩历史）。
5. **写操作需显式约束**：mimo 默认会改动 `working_dir` 内文件；只读/讨论任务必须显式写"不要写任何文件 / 只分析"，否则可能误写。

## 强制连接韧性约束（Connection Resilience，★ 最高优先级元规则）

> **强制范围**：本约束覆盖**任何时候、任何任务、任何工作过程**，与协同范式（范式A/B）、接入形态（形态 A `Dynamic-mcp` 中转 / 形态 B MCP 直连）无关。无论主Agent 正在分析、讨论、编码、Review 还是跑 GitHub 流程，只要涉及 `mimo.code` / `Dynamic-mcp` 的连接，本约束立即生效；其优先级仅低于「强制前置分析约束」闸门，高于其余所有协同规则。

**现象背景（真实环境实测）**：`MiMo code` 与 `Dynamic-mcp` 在真实环境中存在「**代理重连波动**」与「**MCP 工具偶发失联**」——表现为 `Group not found`（代理冷启动/瞬时竞态）、`MCP -32000 Connection closed`（代理重连中）、原生 MCP 瞬时断连、以及 TCP/HTTP 连接超时。上述均为**连接层瞬时错误**，不代表 mimo 服务不可用，**可经重试恢复**，切勿一见失败就改写参数或放弃协同。

**强制法则（三步，不允许任何例外）**：
1. **重试（Retry）**：一旦发生连接超时/失联，主Agent **必须原样重试 2 次**（首次失败后再尝试 2 次，单次逻辑调用最多 3 次连接尝试）。重试**保留原始参数，不立即改动 prompt/参数**——多数重连波动、偶发失联在第 2 次重试内恢复。
2. **计数（Count）**：仅在**连接层错误**上累加"失败次数"；**只要出现一次成功连接，计数器立即归零**。非连接类错误（参数错误、内容审核分歧、死锁等）**不计入**本计数器。
3. **升级门禁（Escalate）**：仅当**连续 3 次连接超时/失联**（即"首次失败 + 2 次重试"仍全部失败，或工作过程中跨调用累计出现 3 次连接失败事件）出现时，才**允许主 Agent 单独工作**——即放弃本轮对 `mimo.code` 的连接依赖，由主Agent 独立承接本子任务的"内容/代码产出权 + 决策权 + 外部操作权"。

**单独工作的边界（降级而非甩锅）**：
- 主 Agent 单独工作时，仍遵守本技能角色分工：主Agent 永远掌握"决策权"与"对外部系统的真实操作权"；只是"mimo 的内容/代码产出"暂由主Agent 自承——**不可因降级而省略审核/验收（主Agent 自审自验）**，防止无复核直接落盘。
- **连接恢复后，下一子任务必须重新尝试协同**：降级是临时避险，不是永久退出协同；一旦重试成功或 `mimo.health` 健康检查通过，立即在后续子任务恢复"主Agent × mimo.code"分工闭环。
- 触发单独工作时，主Agent 应在协同时**显式记录降级原因与连续失败次数**，便于后续复盘。

**与其他约束的关系**：
- 本约束与「串行调用」互不冲突：重试同样**必须串行**，不得对 mimo 并发重试。
- 本约束与「防死锁」互补：连接层连续失败走本门禁（降级单独工作）；内容层无进展走死锁仲裁（拍板/交用户）。

## 通用协同范式：主Agent × mimo.code 分工闭环
本技能的核心价值。目标：让主Agent 与 mimo.code 在**任意工程任务**上分工协作。统一抽象为**「三要素 + 双范式」**，适用于四类协同（模板与防死锁详见 `references/collab-workflow.md`）。

### 三要素（贯穿任一任务）
- **讨论**：任何一方都可提出观点、方案、疑问、替代路线，不限于某一方的单方面提案。
- **审核**：任何一方收到对方（或交叉收到）的产出物后，都必须给出**详细的审核报告**（覆盖可行性 / 风险 / 不足 / 与约束契合度），并在串行范式下同时产出"新版本产出物"。
- **分工**：主Agent 永远掌握"决策权"与"对外部系统（git/gh 等）的真实操作权"；mimo 是"内容/代码产出方"。**能力边界与权限约束之外的所有工作由主Agent 完成**（真实 git/gh 动作、需本地环境运行的验证、涉及私有凭据的操作等）。

### 双范式
> **范式选择的粒度是「子任务」，不是「整个任务/项目」**。一个项目/任务往往由多个性质不同的子任务组成：有的需逐轮打磨收敛（用范式A），有的可并行铺开调研（用范式B）。因此**不应对整个任务固定选一个范式**，而应在**每个子任务启动时按性质重新判定**。"默认范式"只是该类协同最常见的选择，并非锁定；复合任务（如 GitHub 协同）内部不同阶段可分别选 A/B（搜索阶段范式B、Review 修订阶段范式A）。动态择范决策规则见 `references/collab-workflow.md` 第 1.4 节。

**范式A — 串行交替审核（Serial Alternating Review）**
适用于需要逐轮打磨、收敛到唯一方案的场景：代码编写/修改/BUG 修复、方案/架构讨论、文件/文档编写等。
核心规则：**每一轮接收方都必须产出「详细审核报告 + 新版本产出物」**。
```
① 主Agent 完成 v1 产出物（含初始条件/上下文） → 灌注 mimo.code
② mimo.code 审核 v1 → 给出[审核报告 + v2 产出物] → 回灌主Agent
③ 主Agent 审核 v2 → 给出[审核报告 + v3 产出物] → 灌注 mimo.code
④ mimo.code 审核 v3 → 给出[审核报告 + v4 产出物] → 回灌主Agent
⑤ …… 类推，直到双方对当前版本无新增异议 → 落盘唯一交付
```
> 任一轮也可在"审核报告"中直接裁决（主Agent 拍板）提前闭环；见"闭环元规则"。

**范式B — 并行交叉审核（Parallel Cross Review）**
适用于可分解、双方能同时推进的探索/搜索/生成场景：如 GitHub 仓库搜索、联网搜索、问题思考、方案提报等。
核心规则：**双方并行开展各自子任务，再将产出物交叉灌注给对方互审**。
```
① 主Agent 与 mimo.code 并行开展不同子任务
   （如：主Agent 跑 `gh`/本地工具搜索，mimo 跑联网搜索/方案草拟；
    注意：涉及真实外部操作的部分由主Agent 执行，mimo 只产出可被复核的内容）
② 双方各自产出中间产物
③ 交叉灌注：主Agent 的产物交给 mimo 审，mimo 的产物交给主Agent 审
④ 各自给出审核报告，指出遗漏/风险/互补点
⑤ 主Agent 汇总双方审核结论，合成最终方案/报告 → 闭环
```

### 四类协同工作流（模板见 references/collab-workflow.md）
> 下表"默认范式"为该类协同最常见选择；**实际执行时每个子任务应按性质动态切换（见上方"范式选择粒度"说明）**。

| 协同类型 | 主Agent 角色 | mimo.code 角色 | 默认范式（可按子任务动态切换） |
|---|---|---|---|
| **编码协同** | 出题（规格）、审查、验收 | 实现、修订 | 范式A |
| **讨论协同** | 提方向、比选、拍板 | 提方案/反方案、分析 | 范式A |
| **GitHub 协同** | 执行 git/gh 真实动作 | 生成变更内容、提交信息、PR 描述、Review 意见 | 范式B（搜索/生成并行）+ 范式A（Review 修订） |
| **项目开发协同** | 编排以上三类，串成开发流水 | 按阶段承接对应子任务 | 范式A + 范式B 混合 |

**闭环元规则（每条协同都必须遵守，缺一不可）**：
- **角色分工明确**：主Agent 永远掌握"决策权"与"对外部系统的真实操作权"；mimo 是"内容/代码产出方"。能力边界外由主Agent 完成。
- **出口条件（Done Criteria）显式化**：协同启动即明确"什么算完成"（如"文件通过主Agent 全部自测" / "双方对四要素无新增异议" / "PR 已开、diff 经 mimo 审阅无 P0、主Agent 已合入"）。
- **最大轮次硬上限**：编码闭环（范式A）≤ 5 轮、讨论闭环（范式A）≤ 8 轮。范式B 单次并行 + 一轮交叉审核即算一个批次，可多批次推进但总批次 ≤ 5。触及上限即终止循环（见防死锁）。
- **强制闭环 + 防死锁**：每轮主Agent 必须判定"是否收敛"。若连续 2 轮无实质进展（mimo 输出高度相似 / 主Agent 重复同一意见 / 分歧未缩小），触发**死锁仲裁**：主Agent 总结分歧点并给出裁决，或交用户决策，或降级为单轮执行；**绝不无限循环**。

## 测试方法（维度）
为全面验证 mimo.code，按以下维度设计用例（用例矩阵见 `references/test-matrix.md`）：
1. **所有使用方法**（参数组合）；2. **边界能力**（超长/空/目录异常/超时/多语/大项目）；
3. **编程能力**（编写/修改/审核/分析）；4. **协调编程 + GitHub 协同闭环**；
5. **多轮讨论 + 项目开发协同**（范式A）；6. **并行交叉审核**（范式B）；
7. **强制闭环与防死锁**（T-LOCK）；8. **强制前置分析约束验证**（T-GATE，验证子任务启动闸门是否被遵守）。

## Resources
本技能依赖以下参考文档（按需加载，无需全读）：
- `references/invocation.md` — 通用调用方法、两种接入形态（Dynamic-mcp 中转 / MCP 服务直连）探测、参数全表、健康检查、chat vs code 分工、Token 真相；
- `references/collab-workflow.md` — **协同核心**：三要素与双范式定义、四类协同模板（含范式A/B）、会话回灌格式、强制闭环与防死锁机制、实测示例；
- `references/test-matrix.md` — 全维度测试用例矩阵（含范式B 与防死锁维度）；
- `references/cases-and-pitfalls.md` — 实测案例（编码协同范式A、讨论协同范式A、GitHub 协同、并行交叉范式B）与关键陷阱速查；
- `references/session-activation-prompt.md` — 供用户首条注入的"提醒主Agent 在主任务前判断是否激活本 Skill"精简提示词及用法。