/x-multi-llm-align

name: x-multi-llm-align
description: |
  跨子 agent 协议/数据结构/流程对齐 skill。当一个项目的契约（API/事件协议/数据结构/接口/流程）需要由两个子 agent 各自代表实现方立场来回审稿时使用。用户作为人类中间人，在两个子 agent 之间传递文档与反馈。
  典型场景：项目 A 的子 agent 写了一份 contract 文档，项目 B 的子 agent 要从实现方角度审稿、提反馈、敲细节，多轮迭代到双方都站得住脚。
  触发关键词："和另一个子 agent 对齐协议"、"跨团队 contract review"、"让另一个子 agent 给意见"、"多子 agent 讨论"、"另一个工程师设计的协议你看看"、"我把反馈传过去了，对方改了"、"x-multi-llm-align"、"multi-agent 流程"，或用户描述的场景里同时出现"另一个子 agent/工程师/项目"+"协议/契约/数据结构/接口"+"对齐/review/审稿"等组合。
  适用领域：协议对齐、数据结构对齐、流程对齐。不适用：单方面 review、代码 PR 评审（用 x-cr）、写作 peer review。

x-multi-llm-align — 跨子 agent 协议对齐器

这个 skill 解决什么

把"两个子 agent 各自代表自己实现方立场来回审稿协议"的高质量对齐流程固化下来。

为什么这种流程比单方面写文档更有价值：

• 不同子 agent **分别代表不同实现方的立场**，会从自己实现侧的"我得真去实现"角度提问，挖出对方写文档时漏掉的实现陷阱
• 用户作为**人类中间人传递反馈**，不需要两个子 agent 之间直接通信，也保留人类对关键产品决策的拍板权
• 多轮迭代后产出的契约**双方都站得住脚**，开发时返工率低
• **保留推理过程**，后续接手的 agent 能直接读懂整套对齐逻辑，不用从头推一遍

适用与不适用

**适用**：

• 协议对齐（JSON/JSONL/HTTP API/RPC 契约）
• 数据结构对齐（事件 schema、消息格式、状态机定义）
• 流程对齐（接入流程、生命周期约定、错误处理流程）

**不适用**（这些场景将来可能有姊妹 skill）：

• 代码 PR 正确性评审 → 用 `x-cr`
• 写作 peer review（论文/博客/PRD）
• 单方面文档 review（不涉及第二个子 agent）

---

工作流

阶段 0 — 触发后的准备

**第一步：识别讨论文件位置**（按优先级）

1. 用户提供的 spec 目录下，新建/读取 `discussion-<topic>.md`（不污染原 spec 文档） 2. 当前项目的 `dev-pipeline/discussions/discussion-<topic>.md`（不存在则 `mkdir -p`） 3. 绝对 fallback：`/tmp/multi-llm-align/discussion-<topic>.md`（保留旧目录名，兼容历史讨论文件）

**topic** 取自 spec 主题名（如 `claude-sidecar-contract`、`thread-event-schema`），不要太泛。

**单文件追加**：所有轮次都写在同一份文件里（不每轮新建），让后续接手的 agent 一次读完所有上下文。

**第二步：识别自己的子 agent 名**

每次发言都要标注子 agent 名，方便后续接手时区分谁说的。

识别策略（按优先级）： 1. 优先使用当前子 agent / reviewer / 实现方名称。 2. 找不到就一句话问用户："我用什么名字署名？" 3. 对方子 agent 的名字：用户提供，或从 spec 文档作者标记里读，找不到就标 `[<对方未知>]`

发言标签格式：`[agent-a]` / `[agent-b]` / `[实现方-A]` / `[<对方未知>]`

**第三步：如果讨论文件已存在**

直接读完整个文件，搞清当前在第几轮、上一轮决议是什么，然后接力进入下一轮。**不要重新发起第 1 轮**。

---

阶段 1 — 单轮 review 流程

每轮必做这 5 步：

1.1 读全文（第一轮）或读 diff（后续轮）

**第一轮**：完整读所有相关 spec 文档，不抽样、不靠目录推测内容。漏读的部分会变成"我没发现的对齐问题"，下一轮才暴露，浪费一次往返。

**第二轮起**：只读对方改了什么（用 git 或对照之前版本），同时**全文档扫一遍**确认命名空间没漂移（特别要检查状态机表、映射表、错误处理段落、跨文档引用——这些位置最容易漏改）。

1.2 建立编号反馈清单

按问题性质给前缀编号：

| 前缀 | 含义 | 例子 | |---|---|---| | `E` | Error / 不一致 / 矛盾（必改） | `E1 — 04 和 05 文档对 content 类型定义不一致` | | `Q` | Question / 不明确点（待敲板） | `Q1 — 进程是 thread 级还是 run 级？` | | `N` | New / 我建议新增的事项 | `N1 — 缺 generic_chat 路径定义` | | `D` | Decision / 待用户拍板的产品决策 | `D1 — deny 后是否强制 fail？` |

每个问题用统一格式：

### E1 — <一句话问题描述>
**现状**：<对方文档怎么写的，引用具体行/段落>
**问题**：<为什么这是问题，不改会发生什么后果>
**推荐**：<具体怎么改，给最终态文字而不是泛泛建议>
**理由**：<为什么这么改最好——给硬背书：实测/SDK 源码/类比同类系统>
**影响面**：<协议字段 / 状态机 / 实现细节 / 产品决策>

**关键**：所有问题集中列完，按优先级排（P0/P1/P2/P3）。**一次给完，不要拖泥带水分多次**。一次给完才方便对方批量处理。

1.3 写到讨论文件（追加，不重写）

## 第 N 轮 — 反馈 [<我的子 agent 名>]
> 时间：YYYY-MM-DD HH:MM
> 状态：反馈待回应
> 我读了：<spec 文件列表，相对路径>

### 上下文回顾
<上一轮的核心决议，让新进来的 agent 不用从头读>

### 本轮反馈
<E1 / E2 / Q1 / N1 ... 编号清单，按优先级排序>

### 拍板格式
回 `全 Y` 同意全部 / `改 #1 #3` 指出要改的编号 / `撤回 #2` 撤掉某条 / 自由文字。

1.4 等用户传话

不要假设对方反应。用户回来的常见信号：

• "改好了 / 改完了" → 进 1.5（再 review）
• "对方拒绝 #X，理由 Y" → 重新评估你的论点，必要时撤回
• "对方又改了某地方" → 进入下一轮 review
• 单字回复（`Y` / `OK` / `提交`） → 收口当前轮

1.5 评估对方反应（核心：不硬扛）

对方拒绝你时**不要硬扛**。重读对方理由，如果站得住脚就**直接撤回自己的方案**（不辩护）。这是这个 skill 最关键的纪律——也是用户协作偏好里写明的："用户指出我误导时直接承认错误，不要辩护"。

撤回时在讨论文件追加：

## 第 N 轮 — 撤回回应 [<我的子 agent 名>]
> 状态：撤回部分提案

### 撤回 #X
<对方的论点摘要>
我之前的推荐 <X> 站不住脚，撤回。改用 <对方方案>。理由：<我承认的具体论点>。

但反过来——**SDK 源码 / 实测数据 / 第三方实现支持你时**，可以坚持，但要给硬证据，不要凭空辩护。

---

阶段 2 — 多轮迭代

按阶段 1 重复，直到收口。两条关键技巧：

2.1 借子 agent 做实测背书

如果协议涉及第三方库 / SDK / API，spec 里的字段/行为假设可能跟实情不符——**派子 agent 跑 smoke 实测**，结果作为下一轮反馈的硬背书。

实测脚本类型：

• 调真实 API/SDK，逐条打印输出对象的类型 + 字段
• 测边界场景（错误路径、并发、resume、超时）
• 整理成"SDK 真实行为 vs spec 假设"对照表

实测背书比凭空推理强很多——**对方很难拒绝实测数据**。如果实测会消耗 API 配额或费用，先告知用户。

2.2 通俗模式

当用户说"看不懂"、"消化不了"、"用术语过密"——**立即换大白话重写一遍**，每条带：

• **现状是什么**（spec 现在怎么写的）
• **我建议改成什么**（最终态）
• **为什么这么改**（理由 + 背书）
• **不改会怎样**（具体后果，最好给场景化的例子）

**不要用简短术语涵盖大量语义**。这是用户协作偏好里写明的硬要求。

---

阶段 3 — 收口

3.1 收口判断

**硬条件**（任一即收口）：

• 剩余坑都是 nice-to-have（无阻塞性反对）
• 用户主动说"敲死 / 可以开工 / 收"
• 对方完全采纳所有反馈，无新问题冒出

**软条件**（建议提示用户）：

• 同一个问题来回 3 轮以上还在拉锯 → 让用户决定
• 双方各自从立场坚持不让步 → 让用户决定（人类拍板）

3.2 收口时在讨论文件追加

## 收口 [<我的子 agent 名>]
> 时间：YYYY-MM-DD HH:MM
> 状态：双方协议敲定 / 用户决定收口

### 最终决议
<本次对齐的核心决议清单，每条一句话，按编号引用之前的反馈>

### 已留待办
<没在本次解决但记录在案的事项，比如 v0.X 之后再做的细节>

### 后续动作
<开发流程下一步：进 x-req / x-spec / x-dev>

---

讨论文件初始模板

第一次创建讨论文件时写入：

# 多子 agent 对齐讨论：<topic>

> 议题：<协议名 / spec 主题>
> 主 spec 路径：<spec 目录或核心文件>
> 参与子 agent：[<我的子 agent 名>] [<对方子 agent 名>]
> 启动时间：YYYY-MM-DD

## 议题概要

<2-3 句话说清楚要对齐什么>

## 决议追踪

（收口时填，记录最终决议清单）

---
（往下追加每轮反馈和回应）

---

关键约束

不污染对方文档

讨论永远在 `discussion-<topic>.md` 里，**绝不直接改对方的 spec**。对方的 spec 改与不改是对方的决定。

一次给完反馈

一轮反馈把所有问题集中列完，不要分多次。让对方一次性批量处理，节省往返次数。

拍板格式简洁

最后给用户的"回什么"必须一目了然——单字（`Y` / `1` / `B`）/ 编号（`改 #1 #3`）/ 自由文字。**不要让用户填表或回答开放式问题**。

撤回不辩护

对方论点站得住脚就立即撤回。**这是质量纪律**，硬扛会污染讨论质量。

保留推理过程

讨论文件里**不只写结论**，更要写"为什么这么定"。后续 agent 接手时能直接读懂逻辑链，不需要重新推。

---

触发后的第一句话

skill 触发时，用一句话告诉用户即将做什么：

> "我用 x-multi-llm-align 流程开干。先识别讨论文件位置 → 通读 spec → 建立编号反馈清单 → 写到讨论文件，等你转给对方。"

然后立即开始阶段 0。**不要先问一堆开放式问题**——讨论文件位置、topic 名、子 agent 名都按上面的优先级自动选，遇到必须问的再问。

---

兼容性

• 不依赖外部工具或 MCP server
• 不调用额外模型 API（用户作为人类中间人）
• 跟其他 x-* skills 配合：本 skill 收口后通常进 `x-spec` 或 `x-req` 继续推进