创建人员：Codex
文件职责：指导项目管理员在某个项目中为指定 AI 创建工作空间、分配一个或多个角色，并生成该 AI 的 工作说明.md 和 项目问题反馈.md。
管理规范/模板：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md。
引用文件：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目环境创建指南.md；../project-doc/项目配置清单模版.md；AI会话协作语义规范.md；AI技能使用规范.md；项目问题反馈范本.md；当前 MB-X Skill Context.communication_doc 指向的正式通信协议。
记录方式：通用创建指南；AI 工作空间、角色分配、工作说明或校验口径变化时更新本文。
当项目管理员要把某个 AI 加入某个项目，或给已有 AI 增加 / 调整角色时，按本指南执行。
本指南提供两个功能：
工作说明.md，让该 AI 快速知道自己的职责边界、目录入口和必须阅读的体系文档。项目问题反馈.md，供该 AI 反馈项目协作中的重大阻塞、权限/流程问题和反复返修问题；写法参考 项目问题反馈范本.md。本指南不替代项目体系、需求体系、开发体系、实验体系、案例分析体系或数据体系的创建指南。它只负责“AI 人员入场和角色配置”。
执行前必须明确：
| 输入项 | 说明 |
|---|---|
| project_root | 项目根目录，例如 project-x/ |
| ai_name | AI 稳定名称，建议英文名或拼音小写 |
| ai_display_name | 显示名称，可与 ai_name 相同 |
| roles | 一个或多个角色，例如 需求 AI、开发 AI、实验员、审核员 |
| target_scopes | 角色绑定的体系和目标范围，例如 实验开发 -> dev/exp-dev/、项目审核 -> 项目事项审计报告.md、实验审核 -> exp-doc/实验审计报告.md |
| is_reviewer | 是否承担审核员职责 |
| assigned_by | 指派人 |
| assignment_reason | 指派原因 |
ai_name 必须稳定。工作空间目录统一命名为：
ai-<ai_name>/
禁止创建裸 AI 名目录，例如 Andrew/、Codex/。
角色权限按 全局规范.md 和项目根目录 项目配置清单.md 执行。
同一个 AI 可以有多个角色，权限取角色权限并集，但必须在 工作说明.md 中写清每个角色的边界。
开发 AI 和 审核员 不能作为裸角色单独落地，必须绑定体系或目标范围。
如果暂时无法确定开发目标或审核体系，只能登记为“候选角色 / 待绑定 target”，不得作为正式角色落地，也不得给正式写权限。
如果已经正式指派开发角色，必须同步按 common/dev-doc/开发环境创建指南.md 创建对应 target workspace；不得留下“正式开发角色已分配但目标工作区待创建”的半成品状态。
| 泛角色 | 正确写法示例 | 绑定范围 |
|---|---|---|
| 开发 AI | 开发 AI（实验开发） | dev/exp-dev/；dev-doc/exp-doc/ |
| 开发 AI | 开发 AI（需求开发） | dev/pro-dev/；dev-doc/pro-doc/ |
| 开发 AI | 开发 AI（案例分析开发） | dev/ana-dev/；dev-doc/ana-doc/ |
| 审核员 | 审核员（项目事项审核） | 项目事项审计报告.md |
| 审核员 | 审核员（实验审核） | exp-doc/实验审计报告.md |
| 审核员 | 审核员（需求开发审核 / 项目工具开发审核） | dev-doc/开发审计报告.md |
| 审核员 | 审核员（实验开发审核） | exp-doc/实验审计报告.md |
| 审核员 | 审核员（案例分析开发审核） | ana-doc/案例审计报告.md |
| 审核员 | 审核员（需求审核） | pro-doc/需求审计报告.md 或项目约定需求审核入口 |
审核员不能只读审计报告或审计规范。任何审核员都必须同时读取：
dev-doc/<target>-doc/开发工作区说明.md。如果 工作说明.md 只给审核员列了审计报告或审计规范，没有列被审体系规范和被审对象账本入口，则该工作空间创建不合格。
默认角色映射：
| 角色 | 默认职责 | 默认写权限范围 |
|---|---|---|
| 项目管理员 | 管理项目规范、配置清单、项目级账本、体系启用和项目级审计 | 项目根目录；该 AI 工作空间 |
| 需求 AI | 写需求、策略、业务规则等文档 | pro-doc/；该 AI 工作空间 |
| 开发 AI（指定体系开发） | 写指定体系的代码、测试、编码方案、开发日志和开发自检 | dev/<target>-dev/；dev/<target>-dev/test/；dev-doc/<target>-doc/；该 AI 工作空间 |
| 实验员 | 设计和执行实验，维护实验文档、实验数据和结果包 | exp-doc/；exp-data/；该 AI 工作空间 |
| 案例分析员 | 做案例分析，维护案例文档、图片、数据和执行链路 | ana-doc/；ana-data/；该 AI 工作空间 |
| 数据负责人 | 管理数据字典、数据存储说明和正式数据入口 | data-doc/；项目约定数据目录；该 AI 工作空间 |
| 审核员（指定体系审核） | 审核指定体系的设计、计划、执行、证据链和结果边界 | 对应体系审计报告；必要时在问题记录写跨轮索引；该 AI 工作空间 |
审核员可维护自己审核职责对应的本地审核 / 审计规范，例如 exp-doc/实验审计规范.md、ana-doc/案例审核规范.md、dev-doc/开发审计规范.md、pro-doc/需求审核规范.md；该权限只用于审核流程和审计口径维护，不代表可以修改被审体系的执行规范、事项计划、执行日志、结果包或主产物。若需要修改执行规范，必须另授体系维护 / 规范维护角色，或创建独立规范维护事项。
组合角色示例：
| 组合角色 | 解释 |
|---|---|
| 需求-开发 | 同一 AI 同时负责需求文档和对应代码实现，角色应写成 需求 AI；开发 AI（需求开发） |
| 实验-开发 | 同一 AI 同时负责实验设计/执行和实验相关脚本开发，角色应写成 实验员；开发 AI（实验开发） |
| 案例分析-开发 | 同一 AI 同时负责案例分析和案例工具开发，角色应写成 案例分析员；开发 AI（案例分析开发） |
| 项目管理员-审核员 | 同一 AI 负责项目配置和项目级审计，角色应写成 项目管理员；审核员（项目事项审核） |
工作说明.md 必须按角色组合列出必读文档，不能只写一个泛化入口。
开发角色必须同时读取开发体系规范和目标体系规范：
| 开发角色 | 必读文档 |
|---|---|
| 需求-开发 | 项目本地 pro-doc/需求规范.md、相关需求总纲 / 需求文档 / 需求方案 / 三大需求文档；项目本地 dev-doc/编码规范.md、dev-doc/开发审计规范.md |
| 实验-开发 | 项目本地 exp-doc/实验规范.md、exp-doc/实验审计规范.md、相关实验总纲 / 实验设计；项目本地 dev-doc/编码规范.md、dev-doc/开发审计规范.md |
| 案例分析-开发 | 项目本地 ana-doc/案例分析规范.md、ana-doc/案例分析审核规范.md、相关案例总纲 / 案例设计或案例流程；项目本地 dev-doc/编码规范.md、dev-doc/开发审计规范.md |
| 项目工具开发 | 项目本地 项目规范.md、项目配置清单.md、相关项目事项总纲 / 项目事项计划；项目本地 dev-doc/编码规范.md、dev-doc/开发审计规范.md |
审核员角色必须同时读取“自己怎么审”和“被审对象怎么做”：
| 审核角色 | 必读文档 |
|---|---|
| 需求审核员 | 项目本地 pro-doc/需求规范.md、pro-doc/需求审核规范.md、被审需求事项账本和上游聊天 / 文档证据 |
| 开发审核员 | 项目本地 dev-doc/编码规范.md、dev-doc/开发审计规范.md、被审开发事项账本、目标体系规范和开发产物证据；审计报告入口按目标体系查看项目配置清单 |
| 实验审核员 | 项目本地 exp-doc/实验规范.md、exp-doc/实验审计规范.md、被审实验总纲 / 实验设计 / 执行日志 / 结果包 |
| 案例分析审核员 | 项目本地 ana-doc/案例分析规范.md、ana-doc/案例分析审核规范.md、被审案例账本 / 执行记录 / 图片或数据证据 |
| 项目事项审核员 | 项目本地 项目规范.md、项目配置清单.md、项目事项总纲 / 项目事项计划 / 项目执行日志 / 项目变更记录 |
如果是组合审核角色，例如“需求-开发-审核员”“实验-开发-审核员”“案例分析-开发-审核员”，工作说明必须同时列出目标体系规范、编码规范、目标体系审核规范、开发审计规范，以及对应目标事项和开发事项的账本入口。不得只列审计报告或只列审核规范。
组合角色必须避免“自己执行、自己无条件通过”的问题。若同一 AI 同时是执行者和审核员，工作说明.md 必须要求它在审计报告中明确标注“自审”，并列出可复核证据；重大事项应优先安排独立审核员。
在项目根目录执行：
创建 ai-<ai_name>/
创建 ai-<ai_name>/tmp/
创建 ai-<ai_name>/draft/
创建 ai-<ai_name>/worklog/
创建 ai-<ai_name>/工作说明.md
创建 ai-<ai_name>/项目问题反馈.md
目录职责：
| 目录 / 文件 | 作用 |
|---|---|
ai-<ai_name>/ |
AI 私有工作空间根目录 |
tmp/ |
临时分析、中间文件、一次性脚本结果 |
draft/ |
未进入正式体系的草稿 |
worklog/ |
AI 私有过程记录，不能替代正式执行日志 |
工作说明.md |
该 AI 在本项目里的角色入口卡和路由说明 |
项目问题反馈.md |
该 AI 私有的项目协作问题反馈入口，只记录影响项目或体系进展的重要问题 |
AI 工作空间里的内容默认不是正式产物。任何内容要进入正式事项，必须迁入对应体系正式目录，并在对应总纲、设计、执行日志、结果索引或审计报告中记录。
项目问题反馈.md 是 AI 私有反馈入口，不是正式审计报告，也不是项目级问题主账。它的项目治理规则以 ../project-doc/项目规范.md 为准，写法参考 项目问题反馈范本.md。
适合写入：
不适合写入：
项目问题记录.md，项目问题反馈.md 只可记录“已反馈给项目管理员”的线索。推荐初始化内容直接参考 项目问题反馈范本.md。创建项目内 ai-<name>/项目问题反馈.md 时，不要求逐字复制范本，但必须保留记录边界、append 写法，以及事项 ID、问题步骤、反复次数、证据路径、修复建议、是否需要完整方案和方案路径等关键追踪字段。
项目配置清单.md。项目问题反馈.md 当成正式审计报告或项目级问题记录的替代品。给 AI 创建工作空间或调整角色时，必须更新项目根目录 项目配置清单.md：
ai-<ai_name>/。如果该 AI 的角色涉及尚未启用的体系，必须先由项目管理员决定是否启用体系；未启用体系时，不得给该 AI 写入该体系正式写权限。
以下情况必须写入 项目变更记录.md：
同时应写入 项目执行日志.md，记录实际创建了哪些目录、改了哪些配置、生成了哪个 工作说明.md 和 项目问题反馈.md。
如果角色调整本身是一个项目事项，还应在 项目事项总纲.md、项目事项计划.md 和 项目事项审计报告.md 中记录对应事项和审计结论。
ai-<ai_name>/工作说明.md 必须是“角色入口卡 + 路由说明”，不得复制各体系规范的大段流程。它必须包含：
communication_doc、固定工具流程、三态语义、单目标单次发送和禁止自动回退旧链。工作说明.md 不能替代 实验规范.md、编码规范.md、开发审计规范.md、项目规范.md 等体系文档。体系流程变化时，以对应体系文档为准，工作说明只做入口索引。
审核员角色的“必读文档入口”必须同时列出被审体系规范、审计规范 / 审计报告入口、被审对象账本入口。
AI 首次读取或角色变更后重新读取 工作说明.md 时，必须在自己的 worklog/ 中写一条理解反馈，至少回答：
list_threads -> read_thread -> wait_threads(timeoutMs=0) -> send_message_to_thread(一次) -> wait_threads(afterCursor) -> read_thread，以及 dispatch_accepted != observed != completed。新角色在完成上述首次阅读反馈前，只算“目录和配置已创建”，不算“通信初始化完成”。首次反馈如果不能说明精确目标核验、唯一 handoff_id、单次发送、终态证据和原生工具不可用时停止而非自动回退，项目管理员应直接补充同一份工作说明并要求重读；这是初始化纠正，不新建事项、设计或重复审核链。
# <AI_DISPLAY_NAME> 工作说明
创建人员：<创建人员>
文件职责：记录 <AI_DISPLAY_NAME> 在 <PROJECT_NAME> 中的角色入口、职责边界、权限范围和体系文档路由。
管理规范/模板：../../全局规范.md；../项目规范.md；../项目配置清单.md；../../common/ai-workplace/AI工作空间创建指南.md。
引用文件：../项目配置清单.md；../项目执行日志.md；../项目变更记录.md；../../common/ai-workplace/AI会话协作语义规范.md；../../common/ai-workplace/AI技能使用规范.md；当前 `MB-X Skill Context.communication_doc`；已启用体系规范。
记录方式：当前配置说明；角色、权限或工作入口变化时覆盖更新，并在项目变更记录中保留历史。
## 1. 基本信息
| 字段 | 内容 |
|---|---|
| AI 名称 | <AI_NAME> |
| 显示名称 | <AI_DISPLAY_NAME> |
| 工作空间 | ai-<AI_NAME>/ |
| 指派人 | <ASSIGNED_BY> |
| 指派时间 | <YYYY-MM-DD HH:mm:ss> |
| 指派原因 | <ASSIGNMENT_REASON> |
## 2. 当前角色
| 角色 | 职责范围 | 默认写权限 | 关键规范 |
|---|---|---|---|
| <ROLE> | <职责范围> | <写权限范围> | <规范入口> |
## 3. 必读文档入口
| 场景 / 角色 | 先读文档 | 用途 |
|---|---|---|
| 项目基础 | ../项目配置清单.md；../项目规范.md | 确认角色、权限、已启用体系和项目规则 |
| 角色通信 | ../../common/ai-workplace/AI会话协作语义规范.md；当前 `MB-X Skill Context.communication_doc` | 掌握 Codex 原生工具流程、正式 handoff、三态终态和兼容边界 |
| <ROLE_SCOPE> | <体系规范入口> | 按体系规范执行，不在工作说明里重复流程 |
## 4. 目录入口
1. 私有草稿：`ai-<AI_NAME>/draft/`
2. 私有临时文件：`ai-<AI_NAME>/tmp/`
3. 私有过程记录：`ai-<AI_NAME>/worklog/`
4. 私有项目问题反馈：`ai-<AI_NAME>/项目问题反馈.md`
5. 正式产物：<按角色列出正式目录；注明路径是否相对项目根目录>
6. 审计入口：<如有审核角色，列出对应审计报告；注明路径是否相对项目根目录>
7. 审核规范维护入口：<如有审核角色，列出可维护的本地审核 / 审计规范；同时列出不得默认修改的被审体系执行规范>
## 5. 任务入口路由
1. 接到任务后，先查 `项目配置清单.md`，确认自己是否有对应角色和写权限。
2. 根据任务类型进入对应体系文档：项目 / 需求 / 开发 / 实验 / 案例分析 / 数据。
3. 具体流程、日志、审计和交付要求，以对应体系规范为准。
4. 工作说明只提供入口，不复制体系流程。
## 6. 首次阅读反馈
1. 首次读取本文件后，在 `ai-<AI_NAME>/worklog/` 记录理解反馈。
2. 如果有不理解、冲突或不合理的地方，反馈给项目管理员，不要自行脑补执行。
3. 如果问题会影响项目协作、角色权限或体系推进，同步记录到 `ai-<AI_NAME>/项目问题反馈.md`。
4. 反馈必须说明原生任务发现、目标核验、baseline、单次发送、等待和终态判定方法；不能说明时不得把角色标记为通信初始化完成。
## 7. 技能使用入口
1. 技能选择、显式声明、状态变更记录、失败越权处理按 `../../common/ai-workplace/AI技能使用规范.md` 执行。
2. 状态变更类动作必须在回复、消息、执行日志或结构化动作中写明使用的技能或技能别名。
3. 角色间交接、审核、确认、退回、升级时，必须进入正式消息链或正式账本，不得只在聊天窗口声明。
4. 所需技能、目标角色、审核入口或权限不明确时，先反馈项目管理员，不得自行扩大权限。
## 8. Codex 会话上下文保护
1. 主体内容落文档，窗口只展示摘要和证据入口。
2. 不直接使用 `Get-Content -Raw` 将大文件完整输出到窗口。
3. `rg`、`Select-String`、日志检索、代码检索等操作必须限制输出行数；全量结果写入 `tmp/`、readout 文件、证据包、审计附件或正式结果文档。
4. 不对大目录执行无上限递归列表并直接回显；目录扫描结果写入文件，只展示摘要、数量、关键路径和异常项。
5. 图片证据优先记录图片路径、manifest、缩略图或抽样结果；避免批量 `view_image` 把大图片载荷写入会话历史。
6. MB-X 消息和角色窗口只展示摘要、关键行、文件路径、证据入口、结论和期望动作，不复制大段正文。
7. 处理 context window full 时，不得未经确认直接创建新 thread；应先备份、摘要、裁剪、记录审计并尝试原 thread 恢复。
## 8.1 Codex 客户端原生任务通信
1. 运行于 Codex 客户端且原生任务工具可用时，角色间通信默认使用 `list_threads`、`read_thread`、`send_message_to_thread` 和 `wait_threads`。
2. 正式交接使用 `<codex_native_handoff>`，明确来源/目标任务与角色、`reply_thread_id`、唯一 `handoff_id`、范围、证据、状态和期望动作。
3. 原生发送成功只代表 `dispatch_accepted`；observed 和 completed 必须分别由目标独立 turn/cursor 和明确终态证明。
4. 同一 handoff 单目标、单次发送；不得因等待、超时或状态不确定而重发、改投、Queue、Steer 或创建 A002。
5. `mbx send`、`mbx interaction route`、`mbx inbox` 和旧 route/inbox/session 文件链只保留为无原生工具环境下的兼容路径，且必须由人类或管理角色明确启用，不得自动回退。
## 9. 审核边界
如果本 AI 是审核员：
1. 可以读取证据链和运行只读检查。
2. 审计意见写入对应审计报告。
3. 可维护本地审核 / 审计规范，但仅限审核流程、审计口径和阻断标准维护。
4. 不直接改被审计主产物，不默认改被审体系执行规范。
5. 自审必须标注“自审”，并列出可复核证据。
## 10. 禁止事项
1. 不得把工作空间当正式产物目录。
2. 不得越权写未分配体系目录。
3. 不得绕过项目配置清单新增角色或权限。
4. 不得只在聊天里解释职责，不写入本文件。
5. 不得把 `项目问题反馈.md` 当成正式审计报告、正式问题记录或正式执行日志。
检查：
ai-<ai_name>/ 存在。ai-<ai_name>/tmp/ 存在。ai-<ai_name>/draft/ 存在。ai-<ai_name>/worklog/ 存在。ai-<ai_name>/工作说明.md 存在。ai-<ai_name>/项目问题反馈.md 存在，并说明写法参考 common/ai-workplace/项目问题反馈范本.md。检查 项目配置清单.md：
ai-<ai_name>/。ai-<ai_name>/。开发 AI 角色；所有开发角色都绑定具体体系和目标工作区。审核员 角色；所有审核角色都绑定具体审核体系和审计入口。如果工作说明中的角色和项目配置清单不一致，以 项目配置清单.md 为事实源，必须修正 工作说明.md。
检查：
pro-doc/ 是否已启用；未启用时只能写工作空间草稿。exp-doc/、exp-data/ 是否已启用；未启用时只能写工作空间草稿。ana-doc/、ana-data/ 是否已启用；未启用时只能写工作空间草稿。不得因为给 AI 分配角色，就绕过体系启用流程或提前写正式目录。
检查 工作说明.md：
worklog/ 记录理解反馈和疑问。项目问题反馈.md 的入口和边界：只反馈重大协作问题，不替代正式审计报告、问题记录或执行日志。项目问题反馈.md 的写法参考 common/ai-workplace/项目问题反馈范本.md。common/ai-workplace/AI技能使用规范.md，并写清技能显式声明、状态变更记录、消息交互和失败越权处理口径。AI会话协作语义规范.md 与当前 communication_doc，把原生任务通信写成默认路径，并明确固定工具流程、dispatch_accepted != observed != completed、单目标单次发送和不得自动回退旧 MB-X inbox/route。组合角色还必须按角色类型做专项校验：
工作说明.md 必须同时列出 pro-doc/需求规范.md、相关需求事项账本或需求文档入口、dev-doc/编码规范.md、dev-doc/开发审计规范.md、dev/pro-dev/、dev-doc/pro-doc/。工作说明.md 必须同时列出 exp-doc/实验规范.md、exp-doc/实验审计规范.md、相关实验总纲 / 实验设计入口、dev-doc/编码规范.md、dev-doc/开发审计规范.md、目标实验开发工作区。工作说明.md 必须同时列出案例分析规范、案例审核规范、相关案例账本入口、dev-doc/编码规范.md、dev-doc/开发审计规范.md、目标案例开发工作区。工作说明.md 必须同时列出需求规范、需求审核规范、编码规范、开发审计规范、需求审计报告、dev-doc/开发审计报告.md、需求事项账本入口、开发事项账本入口；不得只列审计报告或只列审核规范。工作说明.md 必须同时列出实验规范、实验审计规范、编码规范、开发审计规范、exp-doc/实验审计报告.md、实验事项账本入口、开发事项账本入口和实验开发工作区；不得把审计入口写成 dev-doc/开发审计报告.md。工作说明.md 必须同时列出案例分析规范、案例审核规范、编码规范、开发审计规范、ana-doc/案例审计报告.md、案例事项账本入口、开发事项账本入口和案例分析开发工作区；不得把审计入口写成 dev-doc/开发审计报告.md。检查：
项目执行日志.md 记录了创建工作空间、生成工作说明、更新配置清单的动作。项目变更记录.md 记录了 AI 新增 / 角色调整 / 工作空间调整。项目事项总纲.md、项目事项计划.md 和 项目事项审计报告.md 能串起来。全部满足以下条件，才算完成：
工作说明.md 可让该 AI 快速了解职责边界、目录入口和应该阅读的体系文档。项目问题反馈.md 已创建，且用途边界清楚，并说明写法参考 common/ai-workplace/项目问题反馈范本.md。项目配置清单.md 已更新，并且与 工作说明.md 一致。mbx send/inbox 写成 Codex 环境默认路径。新增 AI 或调整角色会影响项目：
因此，任何 AI 工作空间创建和角色指派都不能只在聊天里完成，必须落到：
项目配置清单.md
-> ai-<name>/工作说明.md
-> ai-<name>/项目问题反馈.md
-> 项目执行日志.md
-> 项目变更记录.md
-> 必要时进入项目事项总纲 / 计划 / 审计报告
ai-<name>/，没更新项目配置清单。工作说明.md 或 项目问题反馈.md。dev/ 全目录权限，而不是绑定目标开发工作区。dev-doc/<target>-doc/ 下复制第二套开发账本。工作说明.md 里复制体系规范细节，导致工作说明变成第二套规范。项目问题反馈.md 当成正式审计报告、正式问题记录或正式执行日志。AI 工作空间创建不是单纯建目录，而是“人员入场 + 角色授权 + 工作说明 + 项目问题反馈入口 + 项目配置清单 + 变更记录 + 校验”的完整动作。