zhangweildlh 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 节。
- 分析（Analyze）：对即将开展的子任务/子步骤/子流程做性质与场景归类——它属于"收敛型"（要打磨出唯一交付）还是"铺开型"（可并行调研/搜索/生成），并归其所属协同场景（编码 / 讨论 / GitHub / 项目开发）。
- 判定（Decide）：基于上一步的分析结论，显式确定其适用范式（范式A 串行 / 范式B 并行 / 二者分段混合；具体范式择用方法见
references/collab-workflow.md第 1.4 节）。 - 执行（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 大模型在小米服务端完成推理，对外表现为"接收一段自然语言任务描述 + 一个工作目录，返回一个执行结果与产物"。其能力覆盖：
- 编写代码/文件：按规格生成完整、可运行、带注释的文件（代码或文本/配置/文档）；
- 修改代码/文件：读取指定文件、定位缺陷、就地修复（保持签名/接口不变）；
- 代码审核：对目标文件做 code review，列出缺陷/风险并按严重度排序（默认只读、不改写，除非明确要求）；
- 项目分析：对目录做结构、依赖、可维护性、风险分析（只读，不改动）；
- 方案/技术讨论：承载可行性、技术路线、架构、实现方法的开放性讨论与比选；
- 内容生成：为 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 — 调用前必读）
以下结论来自实测，违反会直接导致任务失败：
- 禁止并行批量调用：对
mimo.code同时发起多个调用会全部返回"Group not found"（代理形态）或类似错误；必须串行顺序调用。（注意：串行指"对 mimo 的调用"不能并发；范式B 中的"并行"是主Agent 与 mimo 承担不同子任务的并行，仍各自单次串行调用 mimo。） - 连接超时/失联 → 强制重试 2 次 + 连续 3 次降级门禁：常见错误——
"Group not found"（代理冷启动/瞬时竞态）、MCP -32000 Connection closed（代理重连中）、原生 MCP 的瞬时断连、TCP/HTTP 连接超时。按「强制连接韧性约束」（见下方专节，★ 最高优先级）处理：任何连接超时/失联先原样重试 2 次，仍失败且连续累计 3 次才允许主 Agent 单独工作。 continue_session是否保活因环境而异：见上方"通用调用方法"。多轮记忆的最稳妥兜底是由主Agent 在每轮把历史上下文拼进prompt回灌给 mimo。- Token 真相：
mimo.code返回中自带用量报告（输入/输出/推理/费用），费用恒为$0——真正的推理算力由 MiMo 在小米服务端完成，使用的是小米侧额度（MIMO_API_KEY之类），不消耗主Agent 的 LLM 额度。主Agent 仅承担"请求参数 + 返回结果"进入自身上下文的（输入）token；长返回会膨胀主Agent 上下文，长会话需管控（回灌时压缩历史）。 - 写操作需显式约束：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 服务不可用，可经重试恢复，切勿一见失败就改写参数或放弃协同。
强制法则（三步，不允许任何例外）：
- 重试（Retry）：一旦发生连接超时/失联，主Agent 必须原样重试 2 次（首次失败后再尝试 2 次，单次逻辑调用最多 3 次连接尝试）。重试保留原始参数，不立即改动 prompt/参数——多数重连波动、偶发失联在第 2 次重试内恢复。
- 计数（Count）：仅在连接层错误上累加"失败次数"；只要出现一次成功连接，计数器立即归零。非连接类错误（参数错误、内容审核分歧、死锁等）不计入本计数器。
- 升级门禁（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）：
- 所有使用方法（参数组合）；2. 边界能力（超长/空/目录异常/超时/多语/大项目）；
- 编程能力（编写/修改/审核/分析）；4. 协调编程 + GitHub 协同闭环；
- 多轮讨论 + 项目开发协同（范式A）；6. 并行交叉审核（范式B）；
- 强制闭环与防死锁（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"精简提示词及用法。