edit | blame | history | raw

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. 不存在执行者直接无条件批准自己工作的情况。