common/ai-workplace/AI会话协作语义规范.md
@@ -3,7 +3,7 @@ 创建人员：Codex 文件职责：定义 AI 角色会话在阅读项目文档时，如何把“提交审核、退回、交给产品、上报管理员”等自然语言协作字眼转换为正式角色交互动作。 管理规范/模板：../../全局规范.md；AI工作空间创建指南.md。 引用文件：AI工作空间创建指南.md；AI技能使用规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md。 引用文件：AI工作空间创建指南.md；AI技能使用规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md；当前 `MB-X Skill Context.communication_doc` 指向的正式通信协议。 记录方式：AI 会话协作语义规范；协作语义、消息意图或角色交互规则变化时更新。 ## 1. 定位 @@ -18,7 +18,7 @@ 2. 能确认当前角色。 3. 能找到目标角色。 4. 能形成可追踪消息。 5. 能写入项目消息链、inbox 或对应正式账本。 5. 能进入 Codex 原生任务通信链或对应正式账本。 6. 能让接收方知道要读哪些证据、执行什么动作、如何反馈。 ## 2. 通用处理规则 @@ -30,8 +30,8 @@ 3. 判断文档字眼对应的交互意图。 4. 根据项目配置和文档确定目标角色，不得只凭角色名字猜测。 5. 形成包含任务 ID、来源、目标、证据入口、期望动作和风险的消息。 6. 使用当前框架提供的正式通信机制发送消息。 7. 记录或汇报消息 ID、目标角色、目标 inbox 和后续处理要求。 6. 在官方 Codex 客户端中按本文件第 5 节使用原生任务通信发送；非客户端环境只在被明确启用兼容模式时使用旧链。 7. 记录或汇报 `handoff_id`、精确目标任务、`dispatch_accepted / observed / completed` 状态和后续处理要求。 如果无法确认目标角色、审核入口、证据入口或当前角色权限，应暂停发送，并向项目管理员或管理会话反馈不确定项。 @@ -64,43 +64,42 @@ 审核目标不得只用“审核员”三个字泛化。必须尽量明确是项目事项审核、需求审核、开发审核、实验审核、案例分析审核、数据审核或其他项目特化审核。 ## 5. MB-X 环境下的执行要求 ## 5. Codex 客户端中的执行要求 在 MB-X 管理环境中，正式角色交互应使用 MB-X 通信机制。 在官方 Codex 客户端且原生任务工具可用时，正式角色交互默认使用 Codex 原生任务通信。当前 `MB-X Skill Context.communication_doc` 指向的正式通信协议是完整合同，本节给出所有新角色首次阅读时必须掌握的最小操作路径： 当前可见人工会话优先使用 `mbx-human-workflow`： 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 和正式回执。 1. 人类说“提交审核”“交给产品确认”等自然语言请求。 2. AI 读取当前上下文、项目配置和本文件。 3. AI 选择交互意图和目标角色。 4. AI 调用 MB-X 发送消息。 5. AI 向人类报告 message id、目标角色和 inbox。 固定状态语义： Runtime / daemon 触发的角色消息优先使用 `mbx-role-runtime`： - `send_message_to_thread` 成功只表示 `dispatch_accepted`。 - `observed` 必须由发送后的目标 turn 证明同一 `handoff_id` 和精确 source / target / reply 身份。 - `completed` 必须由该 turn 的 completed、无 error、明确终态以及需要时的 reply receipt 共同证明。 - timeout、历史 final、无关并发 turn、stale wake 或状态不确定都不得触发第二次发送。 1. 角色在处理消息或文档时识别协作语义。 2. 角色返回正式 action，由 runtime 执行发送、ack、blocker 或 note。 3. 发送动作必须包含交互意图、目标角色和完整消息内容。 正式交接使用 `<codex_native_handoff>...</codex_native_handoff>`。一个 `handoff_id` 只绑定一个精确目标并只发送一次；禁止自动 resend、reroute、Queue、Steer、创建 A002 或切换 legacy fallback。 如果当前项目运行在 MB-X 环境中，应优先使用 `mbx-interaction-router` 或等价交互路由 skill 统一完成“文档字眼 -> 交互意图 -> 目标角色 -> MB-X 消息”的映射。人工会话可先规划路由，再确认发送；runtime / daemon 场景由角色返回等价发送 action。 `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` 执行。角色不得在未声明技能的情况下发送正式消息、ack 消息、提交审核或升级管理端。 技能选择、显式声明、状态变更记录、失败越权处理和性能口径按 `AI技能使用规范.md` 执行。技能声明不替代目标核验、单次发送和终态证据。 ## 6. 消息内容最低要求 任何正式交互消息至少包含： 任何正式原生交接至少显式包含： 1. 任务 ID 或事项 ID。 2. 来源角色。 3. 目标角色。 4. 交互意图。 5. 摘要。 6. 背景。 7. 证据入口。 8. 期望动作。 9. 校验或审核要求。 10. 阻塞、风险或不确定项。 11. 希望对方如何反馈。 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:`。 审核、确认、返修、升级管理端等关键交互不得只发送一句“请审核”或“已完成”。 @@ -112,6 +111,8 @@ 4. 不得绕过项目配置清单和当前体系文档直接写消息。 5. 不得把正式交接只写入 AI 私有工作空间而不进入正式消息链或正式账本。 6. 不得因为文档中只写“审核员”就忽略具体审核体系和审计入口。 7. 不得把旧 `mbx send/inbox/route/session` 写成 Codex 客户端默认通信路径。 8. 不得因 timeout、失败或不确定而重发、改投、Queue、Steer、创建 A002 或自动回退兼容链。 ## 8. 校验口径 @@ -119,7 +120,9 @@ 1. 交互意图识别正确。 2. 目标角色来自项目配置或当前文档。 3. 消息进入正式通信链或正式账本。 4. 接收方能从消息中找到证据入口和期望动作。 5. 失败或不确定项已反馈给项目管理员或管理会话。 6. 不存在执行者直接无条件批准自己工作的情况。 3. 消息进入精确 Codex 原生目标任务或对应正式账本。 4. `handoff_id`、source / target / reply 身份、范围、证据和期望动作完整。 5. 能区分 `dispatch_accepted`、`observed` 与 `completed`，且终态由发送后证据支持。 6. timeout 或不确定没有产生第二次发送或自动 legacy fallback。 7. 失败或不确定项已反馈给项目管理员或管理会话。 8. 不存在执行者直接无条件批准自己工作的情况。 common/ai-workplace/AI工作空间创建指南.md
@@ -3,7 +3,7 @@ 创建人员：Codex 文件职责：指导项目管理员在某个项目中为指定 AI 创建工作空间、分配一个或多个角色，并生成该 AI 的 `工作说明.md` 和 `项目问题反馈.md`。 管理规范/模板：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md。 引用文件：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目环境创建指南.md；../project-doc/项目配置清单模版.md；AI技能使用规范.md；项目问题反馈范本.md。 引用文件：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目环境创建指南.md；../project-doc/项目配置清单模版.md；AI会话协作语义规范.md；AI技能使用规范.md；项目问题反馈范本.md；当前 `MB-X Skill Context.communication_doc` 指向的正式通信协议。 记录方式：通用创建指南；AI 工作空间、角色分配、工作说明或校验口径变化时更新本文。 ## 1. 使用场景 @@ -224,7 +224,8 @@ 10. 审核规范维护边界：如果该 AI 是审核员，要写清可维护的本地审核 / 审计规范入口，以及不得默认修改的被审体系执行规范入口。 11. 技能使用入口：写清允许使用的技能、显式声明方式、状态变更记录和失败处理口径。 12. Codex 会话上下文保护：写清主体内容落文档、窗口只展示摘要和证据入口、大输出不得直接回显、上下文耗尽不得擅自新建 thread。 13. 禁止事项和越权边界。 13. Codex 原生通信入口：写清 `communication_doc`、固定工具流程、三态语义、单目标单次发送和禁止自动回退旧链。 14. 禁止事项和越权边界。 `工作说明.md` 不能替代 `实验规范.md`、`编码规范.md`、`开发审计规范.md`、`项目规范.md` 等体系文档。体系流程变化时，以对应体系文档为准，工作说明只做入口索引。 审核员角色的“必读文档入口”必须同时列出被审体系规范、审计规范 / 审计报告入口、被审对象账本入口。 @@ -235,6 +236,9 @@ 2. 是否能找到必须阅读的体系文档。 3. 是否有不理解、冲突或不合理的地方。 4. 如果有问题，应该反馈给项目管理员并记录到项目执行日志或对应审计报告。 5. 是否能说清 `list_threads -> read_thread -> wait_threads(timeoutMs=0) -> send_message_to_thread(一次) -> wait_threads(afterCursor) -> read_thread`，以及 `dispatch_accepted != observed != completed`。 新角色在完成上述首次阅读反馈前，只算“目录和配置已创建”，不算“通信初始化完成”。首次反馈如果不能说明精确目标核验、唯一 `handoff_id`、单次发送、终态证据和原生工具不可用时停止而非自动回退，项目管理员应直接补充同一份工作说明并要求重读；这是初始化纠正，不新建事项、设计或重复审核链。 ### 5.4 工作说明.md 推荐模板 @@ -244,7 +248,7 @@ 创建人员：<创建人员> 文件职责：记录 <AI_DISPLAY_NAME> 在 <PROJECT_NAME> 中的角色入口、职责边界、权限范围和体系文档路由。 管理规范/模板：../../全局规范.md；../项目规范.md；../项目配置清单.md；../../common/ai-workplace/AI工作空间创建指南.md。 引用文件：../项目配置清单.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. 基本信息 @@ -269,6 +273,7 @@ | 场景 / 角色 | 先读文档 | 用途 | |---|---|---| | 项目基础 | ../项目配置清单.md；../项目规范.md | 确认角色、权限、已启用体系和项目规则 | | 角色通信 | ../../common/ai-workplace/AI会话协作语义规范.md；当前 `MB-X Skill Context.communication_doc` | 掌握 Codex 原生工具流程、正式 handoff、三态终态和兼容边界 | | <ROLE_SCOPE> | <体系规范入口> | 按体系规范执行，不在工作说明里重复流程 | ## 4. 目录入口 @@ -293,6 +298,7 @@ 1. 首次读取本文件后，在 `ai-<AI_NAME>/worklog/` 记录理解反馈。 2. 如果有不理解、冲突或不合理的地方，反馈给项目管理员，不要自行脑补执行。 3. 如果问题会影响项目协作、角色权限或体系推进，同步记录到 `ai-<AI_NAME>/项目问题反馈.md`。 4. 反馈必须说明原生任务发现、目标核验、baseline、单次发送、等待和终态判定方法；不能说明时不得把角色标记为通信初始化完成。 ## 7. 技能使用入口 @@ -400,7 +406,8 @@ 13. 是否写清 `项目问题反馈.md` 的入口和边界：只反馈重大协作问题，不替代正式审计报告、问题记录或执行日志。 14. 是否说明 `项目问题反馈.md` 的写法参考 `common/ai-workplace/项目问题反馈范本.md`。 15. 是否引用 `common/ai-workplace/AI技能使用规范.md`，并写清技能显式声明、状态变更记录、消息交互和失败越权处理口径。 16. 如果角色运行于 Codex 客户端，是否把原生任务通信写成默认路径，并明确 `dispatch_accepted != observed != completed`、单目标单次发送和不得自动回退旧 MB-X inbox/route。 16. 如果角色运行于 Codex 客户端，是否引用 `AI会话协作语义规范.md` 与当前 `communication_doc`，把原生任务通信写成默认路径，并明确固定工具流程、`dispatch_accepted != observed != completed`、单目标单次发送和不得自动回退旧 MB-X inbox/route。 17. 首次阅读反馈是否实际说明上述通信方法；只有“已阅读”或“配置匹配”而没有通信理解，不算通信初始化完成。 组合角色还必须按角色类型做专项校验：
@@ -19,9 +19,9 @@ 1. 项目管理员先确认项目根目录和 `项目配置清单.md`。 2. 按 `AI工作空间创建指南.md` 创建 `ai-<name>/`。 3. 读取 `AI会话协作语义规范.md`，把角色间交接、审核、确认、返修、升级等自然语言动作写入工作说明。 3. 读取 `AI会话协作语义规范.md` 和当前 `MB-X Skill Context.communication_doc`，把角色间交接、审核、确认、返修、升级等自然语言动作及 Codex 原生任务通信的固定流程、三态终态、单目标单次发送和禁止自动回退写入工作说明。 4. 读取 `AI技能使用规范.md`，把角色允许使用的技能、显式声明方式、状态变更记录和失败处理口径写入工作说明。 5. 生成 `ai-<name>/工作说明.md`。 6. 参考 `项目问题反馈范本.md` 创建 `ai-<name>/项目问题反馈.md`。 7. 同步更新 `项目配置清单.md`、`项目执行日志.md`、`项目变更记录.md`。 8. 按指南中的校验方案检查。 8. 按指南中的校验方案检查；新角色首次反馈必须能说明原生任务发现、核验、发送、等待和终态判定，才能标记为通信初始化完成。 common/ana-doc/案例分析规范.md
@@ -216,6 +216,14 @@ 6. 审计报告通过。 7. 如有非审计问题，问题记录已关闭或明确暂缓；如有审计问题，审计报告已有复审结论或明确暂缓原因。 ## 10. 一句话 ## 10. 长期行业研究的稳定成果入口 1. 同一行业需要持续按任务、批次或运行轮次更新的研究，正式人读成果必须合并维护在 `ana-data/cases/<行业>案例/核心文档/`，默认入口为 `ana-data/cases/<行业>案例/当前成果索引.md`。 2. `task_id`、`case_id`、`batch_id` 和 `run_id` 只承担任务、证据和审核血缘；不得据此为长期行业成果反复创建新的用户可见 `outputs/` 目录。 3. 候选稿和可重建中间文件只进入 `ana-data/tmp/<行业>案例/<task_id>/<run_id>/`；通过必要的合并执行/输出审核后，才合并或晋升到稳定核心文档。 4. `<case_id>/outputs/` 只适用于真正一次性的专题、单公司或独立案例，不是长期行业研究的默认落点。项目本地规范如已定义稳定核心入口，以本条和本地稳定入口合同为准。 5. 旧 `outputs/` 只有在内容已合并、证据血缘已保留且路径映射可追溯后才能归档；不得把未审核候选直接改名成正式成果，也不得保留两个并列的“当前成果”入口。 ## 11. 一句话 案例分析体系的核心是：让 AI 像分析员一样把一件事按规则跑完整，并把每一步为什么这么做、证据在哪里、结果怎么来的都留下来。 common/ana-doc/案例存储体系创建指南.md
@@ -133,3 +133,20 @@ 3. 操作流水没有触发证据。 4. 证据路径指向临时目录但当作正式证据。 5. 结果包没有回写入口。 ## 7. 长期行业成果目录 对需要持续增量更新的行业研究，项目本地存储体系应固定以下用户入口： ```text ana-data/cases/<行业>案例/ 当前成果索引.md 核心文档/ manifest/ 审计包/ ana-data/tmp/<行业>案例/<task_id>/<run_id>/ ana-data/result/<行业>案例/当前成果索引.md ``` `核心文档/` 保存稳定、可读、持续合并更新的行业成果；`tmp/` 保存候选；`审计包/` 保存历史和恢复材料；`result/当前成果索引.md` 只作轻量跳转。长期行业成果不得默认按任务建立多个 `<case_id>/outputs/`。一次性专题或单公司独立案例仍可使用案例级输出目录，但必须在本地规范中明确分类。 common/ana-doc/案例审核规范.md
@@ -141,3 +141,10 @@ 如确需修改案例分析执行规范，应创建规范维护事项，或额外授予案例体系维护 / 规范维护角色，并记录原因、影响范围和复审入口。 审核员应抓真问题，不把边角料升级成阻断。 ## 9. 长期行业成果路径审核 1. 长期行业研究的正式人读成果应从 `ana-data/cases/<行业>案例/当前成果索引.md` 进入，并合并维护在 `核心文档/`；审核员不得反向要求其为每个任务或批次另建 `<case_id>/outputs/`。 2. 候选应位于 `ana-data/tmp/<行业>案例/<task_id>/<run_id>/`。审核通过前不得进入核心文档；审核通过后不得继续把任务目录当作第二个当前成果入口。 3. `<case_id>/outputs/` 仅用于一次性专题、单公司或独立案例。判断路径是否合规时，先判断事项是“长期行业累计成果”还是“一次性独立案例”。 4. 旧任务输出的收口应一次检查内容合并、证据血缘和路径映射，不按文件拆分多轮审核。 common/ops-doc/目录导读.md
New file @@ -0,0 +1,39 @@ # 运维体系目录导读 创建人员：Codex 文件职责：说明 `common/ops-doc` 下运维体系公共规范、模板和创建指南的用途。 管理规范/模板：../../全局规范.md；../../体系创建流程.md；运维规范.md。 引用文件：运维环境创建指南.md；运维审核规范.md；运维事项总纲模版.md；运维事项计划模版.md；运维执行日志模版.md；运维变更记录模版.md；运维审计报告模版.md；运维问题记录模版.md；运维操作手册模版.md。 记录方式：目录导读；文件清单或职责变化时同步更新。 ## 1. 体系定位 运维体系负责把项目已经批准的运行目标落实为可观察、可回滚、可复盘的运行操作。它覆盖服务、任务、配置、数据库、部署、备份恢复、监控告警和事故处置，但不替代项目决策、开发实现或业务判断。 基本原则是：实用优先、快速落地、小步快跑、避免过度设计。只保留能降低真实运行风险的检查、留证和审核。 ## 2. 文件清单 | 文件 | 类型 | 职责 | |---|---|---| | `运维规范.md` | 全局规范 | 定义事项分级、执行边界、变更、回滚、证据和通信规则 | | `运维环境创建指南.md` | 创建指南 | 指导项目启用运维体系并创建本地入口 | | `运维审核规范.md` | 审核规范 | 定义需要独立审核的情形和实质性检查口径 | | `运维事项总纲模版.md` | 模板 | 登记运维事项、事故和当前状态 | | `运维事项计划模版.md` | 模板 | 记录必要的短计划、窗口、前置检查和回滚条件 | | `运维执行日志模版.md` | 模板 | 记录实际命令、结果、证据和终态 | | `运维变更记录模版.md` | 模板 | 记录运行配置和运行态事实源变化 | | `运维审计报告模版.md` | 模板 | 记录独立审核或事后复核结论 | | `运维问题记录模版.md` | 模板 | 跟踪非审计来源问题和事故后续项 | | `运维操作手册模版.md` | 模板 | 固化可重复的日常操作、检查和恢复步骤 | ## 3. 使用顺序 1. 项目管理员按需启用 `operations`，但不因此自动创建角色。 2. 项目先建立本地 `ops-doc/`、`ops-data/evidence/`、`ops-data/tmp/` 和十个正式入口。 3. 日常只读检查直接按操作手册执行；可回滚变更使用短计划；高风险动作取得项目级明确授权并做一次必要独立审核。 4. 创建运维角色时，其工作说明必须读取本地运维规范、审核规范、操作手册和项目配置，并使用 Codex 原生任务通信。 ## 4. 边界 运维体系不保存密码、令牌、私钥或完整连接串；只记录秘密的安全引用、版本或脱敏指纹。代码修复回到开发体系，项目范围和风险接受由项目管理员决定，跨项目或全局控制面事项才升级到管理体系。 common/ops-doc/运维事项总纲模版.md
New file @@ -0,0 +1,30 @@ # 运维事项总纲 创建人员：<创建人员> 文件职责：记录运维事项、事故、负责人、状态和当前结论。 管理规范/模板：common/ops-doc/运维规范.md。 引用文件：运维事项计划.md；运维执行日志.md；运维审计报告.md；运维问题记录.md。 记录方式：append-only；新增事项或状态变化时追加。 ## 当前总览 | 事项 ID | 类型 | 目标 | 负责人 | 风险级别 | 状态 | 当前结论 | |---|---|---|---|---|---|---| | <OPS-ITEM-ID> | 日常/变更/事故 | <目标> | <负责人> | 日常/受控/高风险 | 未开始 | <结论> | ## 事项模板 ### <时间> <OPS-ITEM-ID>：<标题> - 来源与授权：<用户/项目事项/告警/事故及可追溯入口> - 目标：<要达到的运行状态> - 范围：<服务、环境、主机、数据库、任务或目录> - 排除项：<明确不做什么> - 风险级别：日常 / 受控 / 高风险 - 负责人：<运维员或项目管理员> - 审核员：<需要时填写，否则 N/A> - 状态：未开始 / 执行中 / 待审核 / 完成 / HOLD / FAIL / 取消 - 计划入口：<OPS-PLAN-ID / N/A> - 执行入口：<OPS-LOG-ID> - 审计入口：<OPS-AUDIT-ID / N/A> - 当前结论：<实际状态> common/ops-doc/运维事项计划模版.md
New file @@ -0,0 +1,26 @@ # 运维事项计划 创建人员：<创建人员> 文件职责：记录需要计划的运维事项之执行窗口、前置检查、动作、验证和恢复条件。 管理规范/模板：common/ops-doc/运维规范.md；common/ops-doc/运维审核规范.md。 引用文件：运维事项总纲.md；运维执行日志.md；运维操作手册.md。 记录方式：append-only；每个计划或修订追加。 ## 计划模板 ### <时间> <OPS-PLAN-ID>：<标题> - 关联事项：<OPS-ITEM-ID> - 授权主体与窗口：<角色/人员；开始和到期> - 执行主体：<精确角色/会话/主机> - 目标与范围：<精确目标> - 排除项：<禁止动作> - 写前状态：<版本、哈希、运行态、备份或快照> - 动作步骤：<最小顺序步骤> - 消费点与重试：<何时产生副作用；能否重试；去重键> - 成功验证：<独立验证方式> - 停止条件：<漂移、权限、额度、状态不确定等> - 回滚/恢复：<触发条件、步骤和验证> - 证据路径：<ops-data/evidence/...> - 审核要求：无需 / 普通验收 / 独立计划与执行审核 - 状态：待执行 / 已授权 / 执行中 / 完成 / HOLD / FAIL common/ops-doc/运维变更记录模版.md
New file @@ -0,0 +1,20 @@ # 运维变更记录 创建人员：<创建人员> 文件职责：记录服务、任务、配置、数据库、部署和运行态事实源的正式变化。 管理规范/模板：common/ops-doc/运维规范.md。 引用文件：运维事项总纲.md；运维事项计划.md；运维执行日志.md。 记录方式：append-only；每次正式变化或回滚追加。 ## 变更模板 ### <时间> <OPS-CHANGE-ID>：<变更标题> - 关联事项：<OPS-ITEM-ID> - 目标：<精确对象> - 变更前：<版本/状态/bytes/hash> - 变更后：<版本/状态/bytes/hash> - 原因与授权：<来源> - 执行与验证：<OPS-LOG-ID 及验证结果> - 回滚状态：未触发 / 已回滚 / 不适用 - 影响：<实际影响与残余风险> common/ops-doc/运维审核规范.md
New file @@ -0,0 +1,30 @@ # 运维审核规范 创建人员：Codex 文件职责：定义运维事项的必要审核边界、检查项和结论标准。 管理规范/模板：../../全局规范.md；../project-doc/项目规范.md；运维规范.md。 引用文件：运维事项计划模版.md；运维执行日志模版.md；运维审计报告模版.md。 记录方式：全局审核规范；实质风险或审核边界变化时更新。 ## 1. 审核原则 1. 审核以一个运维事项或一次事故为单位，一轮返回完整实质问题集合。 2. 日常只读操作和低风险、可回滚、已有手册的动作不强制独立审核。 3. 高风险操作、正式生产变更、权限/凭据、数据库结构或批量数据变更、不可逆动作必须独立审核。 4. 审核只检查正确性、授权边界、重复执行风险、恢复能力和证据，不增加同义计划、逐命令授权或“审核审核是否存在”的元审核。 ## 2. 计划审核 检查目标和范围、执行主体、窗口、前置状态、具体动作、消费点、幂等/去重、验证、停止条件、回滚或恢复以及秘密保护。缺少会造成真实副作用不确定的内容才阻断。 ## 3. 执行审核 检查实际输入是否匹配计划、命令和副作用计数是否完整、是否越界、成功状态是否独立验证、失败子集是否保留、回滚是否真实完成、证据是否可复算。不得把 exit code 0 等同于业务完成。 ## 4. 结论 使用 `PASS`、`HOLD`、`FAIL`：`PASS` 表示范围内目标和证据闭环；`HOLD` 表示外部前置条件或状态不确定且未产生错误结论；`FAIL` 表示已确认违反合同或结果不正确。历史 HOLD/FAIL 保留，后继修复使用新条目，不改写历史。 ## 5. 审核员边界 审核员可以只读复现检查并写审计报告，不得修改被审配置、脚本、运行目标或执行日志。审核员同时拥有运维角色时，必须在每个动作中声明当前身份，不得自审自己的高风险执行。 common/ops-doc/运维审计报告模版.md
New file @@ -0,0 +1,24 @@ # 运维审计报告 创建人员：<创建人员> 文件职责：记录运维计划审核、执行审核、事故复盘和复审结论。 管理规范/模板：common/ops-doc/运维审核规范.md。 引用文件：运维事项总纲.md；运维事项计划.md；运维执行日志.md；运维变更记录.md。 记录方式：append-only；每次独立审核追加。 ## 审计模板 ### <时间> <OPS-AUDIT-ID>：<审计标题> - 审计对象：<事项/计划/执行/事故> - 审核员：<独立角色> - 范围：<已检查对象> - 前置与授权：PASS / HOLD / FAIL - 目标和范围一致性：PASS / HOLD / FAIL - 重复执行与消费点：PASS / HOLD / FAIL - 变更、验证和回滚：PASS / HOLD / FAIL - 秘密和访问控制：PASS / HOLD / FAIL - 证据可追踪性：PASS / HOLD / FAIL - 实质问题：<完整集合；无则写无> - 结论：PASS / HOLD / FAIL - 允许下一步：<精确下一步或 NONE> common/ops-doc/运维执行日志模版.md
New file @@ -0,0 +1,23 @@ # 运维执行日志 创建人员：<创建人员> 文件职责：记录运维动作的实际输入、命令、副作用、验证、回滚和终态。 管理规范/模板：common/ops-doc/运维规范.md。 引用文件：运维事项总纲.md；运维事项计划.md；运维变更记录.md；运维审计报告.md。 记录方式：append-only；每次执行或恢复追加。 ## 日志模板 ### <时间> <OPS-LOG-ID>：<动作> - 关联事项/计划：<OPS-ITEM-ID> / <OPS-PLAN-ID 或 N/A> - 执行主体与环境：<角色、任务、主机、环境> - 写前检查：<结果和证据> - 实际命令/动作：<脱敏后的精确命令或操作> - 副作用计数：<创建/修改/删除/外部写入/触发次数> - 关键输出：<路径、bytes、SHA-256、退出状态> - 成功验证：<方法与结果> - 异常与实际子集：<无或具体事实> - 回滚/恢复：未触发 / 已完成 / 失败 / 不适用 - 终态：PASS / HOLD / FAIL - 后续动作：<无或明确下一步> common/ops-doc/运维操作手册模版.md
New file @@ -0,0 +1,25 @@ # 运维操作手册 创建人员：<创建人员> 文件职责：固化项目可重复执行的日常检查、变更、恢复和事故响应步骤。 管理规范/模板：common/ops-doc/运维规范.md。 引用文件：运维事项计划.md；运维执行日志.md；运维变更记录.md。 记录方式：受控维护文档；新增或修改步骤时记录版本和验证结果。 ## 手册条目模板 ### <RUNBOOK-ID>：<操作名称> - 适用环境：<开发/测试/生产及精确目标> - 允许执行角色：<角色> - 风险级别：日常 / 受控 / 高风险 - 前置条件：<权限、版本、窗口、备份、依赖> - 输入：<参数；不得包含秘密明文> - 步骤：<最小可执行步骤> - 预期结果：<状态和输出> - 验证：<独立验证命令或方法> - 停止条件：<出现什么立即停止> - 回滚/恢复：<步骤或不适用原因> - 幂等与重试：<重复执行规则和去重键> - 证据：<应记录到哪里> - 最近验证：<时间、环境、结果、验证人> common/ops-doc/运维环境创建指南.md
New file @@ -0,0 +1,48 @@ # 运维环境创建指南 创建人员：Codex 文件职责：指导项目管理员启用运维体系并建立项目本地文档、证据目录和角色依据。 管理规范/模板：../../体系创建流程.md；运维规范.md；运维审核规范.md。 引用文件：本目录全部运维模板。 记录方式：创建指南；目录或启用流程变化时更新。 ## 1. 启用前确认 确认项目确有持续运行、部署、配置、数据库、任务、监控、备份恢复或事故处置需求。只有偶发只读查询时，可继续由项目管理员按项目规范处理，不必为了形式启用运维体系。 ## 2. 最小目录 ```text <project_root>/ ops-doc/ 目录导读.md 运维规范.md 运维审核规范.md 运维事项总纲.md 运维事项计划.md 运维执行日志.md 运维变更记录.md 运维审计报告.md 运维问题记录.md 运维操作手册.md ops-data/ evidence/ tmp/ ``` ## 3. 启用步骤 1. 在工作区 `system_templates` 中确认 `operations -> common/ops-doc` 已注册。 2. 在项目 `mbx.project.yaml` 的 `systems` 中增加 `operations`，状态为 `enabled`，登记上述目录和文档入口。 3. 从 common 模板创建本地十个文档，并把本地 `运维规范.md`、`运维审核规范.md`、`运维操作手册.md` 校准为项目事实。 4. 同步 `项目配置清单.md`，在项目执行日志和变更记录追加启用事实。 5. 运行 UTF-8、目录、配置和 `mbx validate --project <id>` 检查。 6. 只有出现实际岗位需求时才创建 `operations.operator`、`operations.reviewer` 或更具体的角色；体系启用不自动创建会话。 ## 4. 角色创建要求 运维角色必须绑定明确的项目、工作目录、写入范围和 Codex 任务。运维员默认只写 `ops-doc/`、`ops-data/` 及事项明确授权的目标；审核员默认只写 `运维审计报告.md` 和必要问题索引。真实生产、数据库、凭据、外部写入等权限按具体事项另行授予，不从角色名称自动继承。 ## 5. 验收 目录、十个文档、机器配置和人类清单一致；本地规范明确项目边界；验证无新增阻断；未创建无需求的角色、会话、服务或运行态。 common/ops-doc/运维规范.md
New file @@ -0,0 +1,64 @@ # 运维规范 创建人员：Codex 文件职责：定义 MB-X 项目运维事项的分级、执行、变更、回滚、证据和通信底线。 管理规范/模板：../../全局规范.md；../project-doc/项目规范.md。 引用文件：目录导读.md；运维环境创建指南.md；运维审核规范.md；运维操作手册模版.md。 记录方式：全局运维规范；运维边界或底线变化时更新。 统一依赖：项目本地运维规范可以补充项目特有服务、环境和窗口，但不得削弱本规范。 ## 1. 权责边界 1. 项目管理员决定项目内运维目标、授权范围、时间窗口和可接受风险；运维角色负责技术执行，不因执行高风险动作而获得项目决策权。 2. 运维审核员独立检查必要的计划、执行证据和回滚能力，不替运维员执行，也不把边角料问题升级为阻断。 3. 代码、测试和构建逻辑修改归开发体系；业务结论和研究判断归对应专业体系；全局控制面和跨项目规则才归管理体系。 4. 已批准事项内的日常步骤不逐命令申请管理授权。授权应尽量采用事项、阶段或时间窗口合同，写清主体、目标、范围、排除项和终止条件。 ## 2. 事项分级 ### 2.1 日常操作 只读检查、状态查询、日志读取、容量查看、已批准监控和不产生外部影响的健康检查，可按操作手册直接执行，记录必要结果即可，不强制计划或独立审核。 ### 2.2 受控变更 可回滚的服务重载、配置调整、任务启停、已验证部署、备份恢复演练等，使用一份短计划，至少说明前置状态、动作、验证、回滚和停止条件。普通低风险事项由项目管理员或请求者验收；只有项目规范或计划明确要求时才独立审核。 ### 2.3 高风险操作 生产写入、不可逆删除、数据库结构或批量数据变更、凭据轮换、外部消息、权限和访问控制、跨项目资源、重大部署与真实恢复，必须有项目级明确授权、写前预检、回滚或恢复方案、独立审核和正式终态。 ## 3. 标准执行闭环 1. 确认事项 ID、请求来源、授权主体、目标、范围、排除项、窗口和成功/停止条件。 2. 写前读取实际环境、版本、目标和依赖；不确定时停止，不用猜测补齐。 3. 能 dry-run 或只读验证时先做一次；禁止为“证明权限”制造额外副作用。 4. 按最小批次执行；每一步完成后立即验证，不把多个独立风险捆成一次大变更。 5. 失败时先保护现场和实际子集；按冻结条件回滚或停止，不静默重试可能重复消费的动作。 6. 写入执行日志、变更记录和必要证据，回传实际终态。 ## 4. 变更、重试与幂等 1. 每个有副作用动作必须有唯一事项或尝试标识；明确消费点和可否重试。 2. `CreateNew`、覆盖、删除、迁移、回滚必须在计划中明确；默认不覆盖、不删除、不改写历史证据。 3. 网络超时、客户端不确定、目标状态未知或可能重复执行时，按“可能已发生”保守处理并停止。 4. 已知无副作用的命令拼写、路径或查询错误可在同一事项内纠正；修正后必须记录实际命令。 5. 自动化应可重复运行；无法做到幂等时必须设置去重键、锁或人工确认点。 ## 5. 证据与秘密 1. `ops-doc/` 保存事项、计划、日志、变更、审计和操作手册；`ops-data/evidence/` 保存命令输出、清单和回执；临时文件只放 `ops-data/tmp/` 并在终态清理。 2. 关键证据至少包含时间、执行主体、目标、命令或动作、退出状态、实际结果和验证方法；涉及文件时记录路径、字节数和 SHA-256。 3. 密码、令牌、私钥、Cookie 和完整连接串不得写入文档、日志、命令输出或任务消息。只记录秘密管理器引用、脱敏标识或版本。 4. 运维日志和审计记录 append-only；更正历史时追加更正条目，不改写原始失败或 HOLD。 ## 6. 通信与角色启动 1. 正式 Codex 任务默认使用 Codex App 原生任务通信：精确目标、单次发送，并区分 `dispatch_accepted`、`observed`、`completed`。 2. 原生工具不可用时停止并报告，不自动回退旧 MB-X inbox、router、session 或 Remote TUI。 3. 新运维角色工作说明必须读取项目配置、项目规范、本地运维规范、运维审核规范和操作手册；角色未完成首次理解反馈前不得承担高风险操作。 ## 7. 完成标准 运维事项只有在目标状态已验证、实际副作用已计数、失败/回滚状态明确、必要证据已落盘、临时文件已处理、请求者或审核员得到终态时才完成。计划通过、消息已发送或命令退出 0 都不能单独代表完成。 common/ops-doc/运维问题记录模版.md
New file @@ -0,0 +1,20 @@ # 运维问题记录 创建人员：<创建人员> 文件职责：跟踪非审计来源运维问题、事故后续项和跨轮问题索引。 管理规范/模板：common/ops-doc/运维规范.md；common/ops-doc/运维审核规范.md。 引用文件：运维事项总纲.md；运维执行日志.md；运维审计报告.md。 记录方式：append-only；新问题、修复和复验追加。 ## 问题模板 ### <时间> <OPS-ISSUE-ID>：<问题标题> - 来源：监控 / 执行失败 / 人工反馈 / 审计索引 / 其他 - 关联事项：<OPS-ITEM-ID> - 影响与优先级：<影响；P0/P1/P2/P3> - 事实与证据：<路径、时间、输出或审计 ID> - 是否阻断：是 / 否 - 负责人：<角色/人员> - 状态：OPEN / FIXING / FIXED_PENDING_REVIEW / CLOSED / PAUSED - 修复与复验：<实际动作和结论> common/project-doc/项目规范.md
@@ -426,6 +426,7 @@ | 实验体系 | `实验总纲.md` 中的一个实验目标或实验事项 | | 案例分析体系 | `案例总纲.md` 中的一个案例目标或案例事项 | | 数据体系 | 数据体系总纲或数据事项账本中的一个数据目标或数据事项 | | 运维体系 | `运维事项总纲.md` 中的一个运维事项或一次事故处置 | ### 7.2 项目级审计边界
@@ -221,10 +221,11 @@ 3. `exp-doc/`：实验体系规范和实验文档模板，包括实验总纲、实验设计、执行日志、实验存储体系创建指南、实验审核规范、审计报告、问题记录。项目内应创建本地 `实验规范.md` 和 `实验审计规范.md`，分别引用 common 全局规范。 4. `data-doc/`：数据存储、数据样本、数据库表、图片资产相关规范。 5. `ana-doc/`：案例分析体系规范和模板，包括案例分析规范、案例审核规范、案例总纲、案例分析设计、案例执行日志、案例存储体系创建指南、案例审计报告、案例问题记录。 6. `project-doc/`：项目规范和项目创建模板，包括项目规范、项目配置清单、项目事项总纲、项目事项计划、项目执行日志、项目事项审计报告、项目问题记录、项目变更记录。 7. `全局规范.md`：所有 AI 都必须遵守的全局规则。 8. `体系创建流程.md`：创建新体系时使用的通用流程和完成标准。 9. `manage-doc/`：管理体系规范和模板，用于约束 MB-X 管理根目录、管理会话、管理管理员、管理观察员和管理级事项。 6. `ops-doc/`：运维体系规范和模板，包括运维规范、环境创建指南、运维事项账本、执行日志、变更记录、操作手册、审核规范、审计报告和问题记录。 7. `project-doc/`：项目规范和项目创建模板，包括项目规范、项目配置清单、项目事项总纲、项目事项计划、项目执行日志、项目事项审计报告、项目问题记录、项目变更记录。 8. `全局规范.md`：所有 AI 都必须遵守的全局规则。 9. `体系创建流程.md`：创建新体系时使用的通用流程和完成标准。 10. `manage-doc/`：管理体系规范和模板，用于约束 MB-X 管理根目录、管理会话、管理管理员、管理观察员和管理级事项。 公共规范应尽量通用，不绑定某一个具体项目。
@@ -59,13 +59,13 @@ ## 3. 体系插件原则 `common/` 下的需求体系、开发体系、实验体系、数据体系、案例分析体系，都是体系插件。项目体系和开发体系是项目创建时默认自带的基础体系；其他体系由项目管理员按需启用。 `common/` 下的需求体系、开发体系、实验体系、数据体系、案例分析体系、运维体系，都是体系插件。项目体系和开发体系是项目创建时默认自带的基础体系；其他体系由项目管理员按需启用。 默认口径： 1. `common/` 是全局能力库。 2. 项目创建时默认启用项目体系和开发体系。 3. 项目管理员决定是否额外启用需求、实验、案例分析、数据等体系。 3. 项目管理员决定是否额外启用需求、实验、案例分析、数据、运维等体系。 4. 未启用的非默认体系，不对项目产生执行义务。 5. 启用某个体系后，项目必须创建对应目录、入口文档和本地规范。开发体系是例外：一个项目只有一套开发体系账本和本地开发规范，项目创建时默认创建 `dev/`、`dev-doc/` 根目录；创建具体目标开发工作区时，只创建 `dev/<target>-dev/` 和 `dev-doc/<target>-doc/` 目标代码文档区，不再复制第二套开发规范或开发账本。 6. 启用后，项目必须同时遵守 `common` 全局体系规范和项目本地体系规范。开发体系在未创建具体目标开发工作区前，先遵守 `common/dev-doc` 全局开发规范。
