# AI 会话协作语义规范

创建人员：Codex
文件职责：定义 AI 角色会话在阅读项目文档时，如何把“提交审核、退回、交给产品、上报管理员”等自然语言协作字眼转换为正式角色交互动作。
管理规范/模板：../../全局规范.md；AI工作空间创建指南.md。
引用文件：AI工作空间创建指南.md；AI技能使用规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md；当前 `MB-X Skill Context.communication_doc` 指向的正式通信协议。
记录方式：AI 会话协作语义规范；协作语义、消息意图或角色交互规则变化时更新。

## 1. 定位

本文件定义 `common/` 文档中常见协作语义的统一解释方式。

当项目在 MB-X 管理环境中运行时，AI 角色会话看到“提交审核”“交给审核员”“让产品确认”“退回开发员”“需要项目管理员介入”等字眼，不应只在聊天窗口里口头说明，而应把它们视为正式角色交互动作。

正式角色交互动作必须满足：

1. 能确认当前项目。
2. 能确认当前角色。
3. 能找到目标角色。
4. 能形成可追踪消息。
5. 能进入 Codex 原生任务通信链或对应正式账本。
6. 能让接收方知道要读哪些证据、执行什么动作、如何反馈。

## 2. 通用处理规则

AI 角色会话处理协作语义时，按以下顺序执行：

1. 确认当前项目、当前角色和当前事项。
2. 读取项目配置清单、当前 AI 工作说明、相关体系规范和通信规范。
3. 判断文档字眼对应的交互意图。
4. 根据项目配置和文档确定目标角色，不得只凭角色名字猜测。
5. 形成包含任务 ID、来源、目标、证据入口、期望动作和风险的消息。
6. 在官方 Codex 客户端中按本文件第 5 节使用原生任务通信发送；非客户端环境只在被明确启用兼容模式时使用旧链。
7. 记录或汇报 `handoff_id`、精确目标任务、`dispatch_accepted / observed / completed` 状态和后续处理要求。

如果无法确认目标角色、审核入口、证据入口或当前角色权限，应暂停发送，并向项目管理员或管理会话反馈不确定项。

## 3. 常见协作语义

| 文档字眼 / 人类说法 | 交互意图 | 目标角色选择 | 输出动作 |
|---|---|---|---|
| 提交审核、送审、给审核员审核、等待审核 | `review_request` | 当前事项所属体系或目标工作区对应的审核角色 | 发送审核请求，附证据入口和待审核点 |
| 审核不通过、退回、要求返修、需要补证据 | `review_feedback` | 被审事项来源角色、负责人或执行者 | 发送审核反馈，说明阻断问题和修复要求 |
| 审核通过、复审通过 | `review_result` | 被审事项来源角色、项目管理员或后续负责人 | 发送审核结论，说明依据和可进入的下一状态 |
| 让产品确认、请需求确认、确认是否符合需求 | `confirmation_request` | 产品角色、需求角色或项目配置中指定确认人 | 发送确认请求，列出确认事项和证据 |
| 产品确认通过、需求确认完成 | `confirmation_result` | 请求确认的来源角色或后续执行角色 | 发送确认结论，说明确认范围 |
| 交给开发、交给实验员、交给分析员、转交执行 | `handoff` | 当前体系或目标范围对应执行角色 | 发送交接消息，说明输入、输出和验收要求 |
| 请补充、需要更多信息、缺少上下文 | `info_request` | 能补充信息的来源角色、产品角色、管理员或上游角色 | 发送补充信息请求，说明缺口和用途 |
| 已补充、信息已更新 | `info_response` | 发起补充请求的角色 | 发送信息回复，给出更新入口 |
| 需要项目管理员介入、上报管理端、流程不清、权限不够 | `escalation` | 项目管理员、管理会话或项目级角色 | 发送升级消息，说明阻塞、影响和建议动作 |
| 已完成、可收口、请归档、进入下一阶段 | `completion_notice` | 项目管理员、下一环节角色或来源角色 | 发送完成通知，说明完成依据和剩余事项 |
| 稍后自查、后续复核、拆分下一步 | `self_message` | 当前角色自身 | 发送自发消息，必须写清终止条件，避免重复循环 |
| 请协作、请配合、联合处理 | `collaboration_request` | 项目配置和当前文档指定的协作角色 | 发送协作请求，说明各自边界和期望输出 |

## 4. 目标角色选择规则

目标角色必须从当前项目上下文中确定，优先级如下：

1. `项目配置清单.md` 中明确指定的角色、AI、审核入口和工作空间。
2. 当前项目 `mbx.project.yaml` 或等价机器配置中已经登记的 role / AI / session 绑定。
3. 当前体系本地规范、工作区说明、事项计划、设计文档中明确指定的负责人或审核人。
4. `common/` 体系规范中规定的默认职责边界。
5. 仍无法确认时，向项目管理员或管理会话发送不确定项，不得自行创造目标角色。

审核目标不得只用“审核员”三个字泛化。必须尽量明确是项目事项审核、需求审核、开发审核、实验审核、案例分析审核、数据审核或其他项目特化审核。

## 5. Codex 客户端中的执行要求

在官方 Codex 客户端且原生任务工具可用时，正式角色交互默认使用 Codex 原生任务通信。当前 `MB-X Skill Context.communication_doc` 指向的正式通信协议是完整合同，本节给出所有新角色首次阅读时必须掌握的最小操作路径：

1. 用 `list_threads` 发现候选任务。
2. 用 `read_thread` 核对唯一目标的 task、role、cwd、status 和发送前 latest turn。
3. 用 `wait_threads(timeoutMs=0)` 取得发送前 baseline cursor，并检查目标最近 turn 中是否已存在同一 `handoff_id`。
4. 只向核验后的一个精确 `target_thread_id` 调用一次 `send_message_to_thread`。
5. 用 `wait_threads(afterCursor=<last_cursor>)` 等待增量，再用 `read_thread` 核验发送后的同一目标 turn 和正式回执。

固定状态语义：

- `send_message_to_thread` 成功只表示 `dispatch_accepted`。
- `observed` 必须由发送后的目标 turn 证明同一 `handoff_id` 和精确 source / target / reply 身份。
- `completed` 必须由该 turn 的 completed、无 error、明确终态以及需要时的 reply receipt 共同证明。
- timeout、历史 final、无关并发 turn、stale wake 或状态不确定都不得触发第二次发送。

正式交接使用 `<codex_native_handoff>...</codex_native_handoff>`。一个 `handoff_id` 只绑定一个精确目标并只发送一次；禁止自动 resend、reroute、Queue、Steer、创建 A002 或切换 legacy fallback。

`mbx-human-workflow` 和 `mbx-role-runtime` 可以帮助角色识别意图、边界和应答动作，但在 Codex 客户端内不得把它们解释为旧 `mbx send/inbox/route/session` 的默认入口。`mbx-interaction-router`、`mbx-inbox-watch`、旧 MB-X CLI、session 管理与 Remote TUI 仅是人类或管理角色明确选择后的兼容路径；原生工具不可用时应停止并报告 blocker，不得自动回退。

技能选择、显式声明、状态变更记录、失败越权处理和性能口径按 `AI技能使用规范.md` 执行。技能声明不替代目标核验、单次发送和终态证据。

## 6. 消息内容最低要求

任何正式原生交接至少显式包含：

1. `project_id`、`message_type`、唯一 `handoff_id`。
2. 精确 `source_ai_id / source_thread_id / source_role_instance_id`。
3. 精确 `target_ai_id / target_thread_id / target_role_instance_id`。
4. 精确 `reply_thread_id` 和当前 `status`。
5. `scope:`：授权范围和排除项。
6. `evidence:`：文档、测试、cursor、review ID 等证据入口。
7. `expected_action:`：一个有界动作和终态回复要求。

可以附加摘要、背景、风险和验收说明，但 `summary` 不能替代 `scope:` 或 `evidence:`。

审核、确认、返修、升级管理端等关键交互不得只发送一句“请审核”或“已完成”。

## 7. 禁止事项

1. 不得把“提交审核”理解为只在当前聊天窗口声明已送审。
2. 不得在无法确认目标角色时随意选择一个看起来像审核员的角色。
3. 不得让执行角色无条件批准自己的工作。
4. 不得绕过项目配置清单和当前体系文档直接写消息。
5. 不得把正式交接只写入 AI 私有工作空间而不进入正式消息链或正式账本。
6. 不得因为文档中只写“审核员”就忽略具体审核体系和审计入口。
7. 不得把旧 `mbx send/inbox/route/session` 写成 Codex 客户端默认通信路径。
8. 不得因 timeout、失败或不确定而重发、改投、Queue、Steer、创建 A002 或自动回退兼容链。

## 8. 校验口径

一次协作语义处理合格，至少满足：

1. 交互意图识别正确。
2. 目标角色来自项目配置或当前文档。
3. 消息进入精确 Codex 原生目标任务或对应正式账本。
4. `handoff_id`、source / target / reply 身份、范围、证据和期望动作完整。
5. 能区分 `dispatch_accepted`、`observed` 与 `completed`，且终态由发送后证据支持。
6. timeout 或不确定没有产生第二次发送或自动 legacy fallback。
7. 失败或不确定项已反馈给项目管理员或管理会话。
8. 不存在执行者直接无条件批准自己工作的情况。