| 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 — 触发后的准备
第一步：识别讨论文件位置（按优先级）
- 用户提供的 spec 目录下，新建/读取
discussion-<topic>.md（不污染原 spec 文档）
- 当前项目的
dev-pipeline/discussions/discussion-<topic>.md（不存在则 mkdir -p）
- 绝对 fallback：
/tmp/multi-llm-align/discussion-<topic>.md（保留旧目录名，兼容历史讨论文件）
topic 取自 spec 主题名（如 claude-sidecar-contract、thread-event-schema），不要太泛。
单文件追加：所有轮次都写在同一份文件里（不每轮新建），让后续接手的 agent 一次读完所有上下文。
第二步：识别自己的子 agent 名
每次发言都要标注子 agent 名，方便后续接手时区分谁说的。
识别策略（按优先级）：
- 优先使用当前子 agent / reviewer / 实现方名称。
- 找不到就一句话问用户："我用什么名字署名？"
- 对方子 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 继续推进
