From 73023c72c6916df30e24bab2a15260c1d55baf00 Mon Sep 17 00:00:00 2001 From: 1 <wentingyear@gmail.com> Date: Mon, 08 Jun 2026 02:51:44 +0800 Subject: [PATCH] Merge branch 'master' of https://gitee.com/wudicaidou/mb-ms-doc --- common/ai-workplace/AI工作空间创建指南.md | 20 ++++- common/ai-workplace/目录导读.md | 12 +- common/ai-workplace/AI会话协作语义规范.md | 4 common/ai-workplace/AI技能使用规范.md | 156 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 182 insertions(+), 10 deletions(-) diff --git "a/common/ai-workplace/AI\344\274\232\350\257\235\345\215\217\344\275\234\350\257\255\344\271\211\350\247\204\350\214\203.md" "b/common/ai-workplace/AI\344\274\232\350\257\235\345\215\217\344\275\234\350\257\255\344\271\211\350\247\204\350\214\203.md" index b33d36d..432e652 100644 --- "a/common/ai-workplace/AI\344\274\232\350\257\235\345\215\217\344\275\234\350\257\255\344\271\211\350\247\204\350\214\203.md" +++ "b/common/ai-workplace/AI\344\274\232\350\257\235\345\215\217\344\275\234\350\257\255\344\271\211\350\247\204\350\214\203.md" @@ -3,7 +3,7 @@ 创建人员：Codex 文件职责：定义 AI 角色会话在阅读项目文档时，如何把“提交审核、退回、交给产品、上报管理员”等自然语言协作字眼转换为正式角色交互动作。 管理规范/模板：../../全局规范.md；AI工作空间创建指南.md。 -引用文件：AI工作空间创建指南.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md。 +引用文件：AI工作空间创建指南.md；AI技能使用规范.md；../project-doc/项目规范.md；../project-doc/项目配置清单模版.md。 记录方式：AI 会话协作语义规范；协作语义、消息意图或角色交互规则变化时更新。 ## 1. 定位 @@ -84,6 +84,8 @@ 如果当前项目运行在 MB-X 环境中，应优先使用 `mbx-interaction-router` 或等价交互路由 skill 统一完成“文档字眼 -> 交互意图 -> 目标角色 -> MB-X 消息”的映射。人工会话可先规划路由，再确认发送；runtime / daemon 场景由角色返回等价发送 action。 +技能选择、显式声明、状态变更记录、失败越权处理和性能口径按 `AI技能使用规范.md` 执行。角色不得在未声明技能的情况下发送正式消息、ack 消息、提交审核或升级管理端。 + ## 6. 消息内容最低要求 任何正式交互消息至少包含： diff --git "a/common/ai-workplace/AI\345\267\245\344\275\234\347\251\272\351\227\264\345\210\233\345\273\272\346\214\207\345\215\227.md" "b/common/ai-workplace/AI\345\267\245\344\275\234\347\251\272\351\227\264\345\210\233\345\273\272\346\214\207\345\215\227.md" index b48e836..f3d419e 100644 --- "a/common/ai-workplace/AI\345\267\245\344\275\234\347\251\272\351\227\264\345\210\233\345\273\272\346\214\207\345\215\227.md" +++ "b/common/ai-workplace/AI\345\267\245\344\275\234\347\251\272\351\227\264\345\210\233\345\273\272\346\214\207\345\215\227.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；项目问题反馈范本.md。 +引用文件：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目环境创建指南.md；../project-doc/项目配置清单模版.md；AI技能使用规范.md；项目问题反馈范本.md。 记录方式：通用创建指南；AI 工作空间、角色分配、工作说明或校验口径变化时更新本文。 ## 1. 使用场景 @@ -221,7 +221,11 @@ 7. 正式产物目录、草稿目录、临时目录和审计入口。 8. 任务入口路由：接到任务后应该先查哪个配置、再读哪个体系规范。 9. 审核边界：如果该 AI 是审核员，要写清审核体系、审计报告入口和不能直接改被审计产物。 +<<<<<<< HEAD 10. 审核规范维护边界：如果该 AI 是审核员，要写清可维护的本地审核 / 审计规范入口，以及不得默认修改的被审体系执行规范入口。 +======= +10. 技能使用入口：写清允许使用的技能、显式声明方式、状态变更记录和失败处理口径。 +>>>>>>> 512faa36f7634c3e25068761afaf3f20d2e8170f 11. 禁止事项和越权边界。 `工作说明.md` 不能替代 `实验规范.md`、`编码规范.md`、`开发审计规范.md`、`项目规范.md` 等体系文档。体系流程变化时，以对应体系文档为准，工作说明只做入口索引。 @@ -242,7 +246,7 @@ 创建人员：<创建人员> 文件职责：记录 <AI_DISPLAY_NAME> 在 <PROJECT_NAME> 中的角色入口、职责边界、权限范围和体系文档路由。 管理规范/模板：../../全局规范.md；../项目规范.md；../项目配置清单.md；../../common/ai-workplace/AI工作空间创建指南.md。 -引用文件：../项目配置清单.md；../项目执行日志.md；../项目变更记录.md；已启用体系规范。 +引用文件：../项目配置清单.md；../项目执行日志.md；../项目变更记录.md；../../common/ai-workplace/AI技能使用规范.md；已启用体系规范。 记录方式：当前配置说明；角色、权限或工作入口变化时覆盖更新，并在项目变更记录中保留历史。 ## 1. 基本信息 @@ -292,7 +296,14 @@ 2. 如果有不理解、冲突或不合理的地方，反馈给项目管理员，不要自行脑补执行。 3. 如果问题会影响项目协作、角色权限或体系推进，同步记录到 `ai-<AI_NAME>/项目问题反馈.md`。 -## 7. 审核边界 +## 7. 技能使用入口 + +1. 技能选择、显式声明、状态变更记录、失败越权处理按 `../../common/ai-workplace/AI技能使用规范.md` 执行。 +2. 状态变更类动作必须在回复、消息、执行日志或结构化动作中写明使用的技能或技能别名。 +3. 角色间交接、审核、确认、退回、升级时，必须进入正式消息链或正式账本，不得只在聊天窗口声明。 +4. 所需技能、目标角色、审核入口或权限不明确时，先反馈项目管理员，不得自行扩大权限。 + +## 8. 审核边界 如果本 AI 是审核员： @@ -301,7 +312,7 @@ 3. 不直接改被审计主产物。 4. 自审必须标注“自审”，并列出可复核证据。 -## 8. 禁止事项 +## 9. 禁止事项 1. 不得把工作空间当正式产物目录。 2. 不得越权写未分配体系目录。 @@ -371,6 +382,7 @@ 12. 是否要求 AI 首次阅读后在 `worklog/` 记录理解反馈和疑问。 13. 是否写清 `项目问题反馈.md` 的入口和边界：只反馈重大协作问题，不替代正式审计报告、问题记录或执行日志。 14. 是否说明 `项目问题反馈.md` 的写法参考 `common/ai-workplace/项目问题反馈范本.md`。 +15. 是否引用 `common/ai-workplace/AI技能使用规范.md`，并写清技能显式声明、状态变更记录、消息交互和失败越权处理口径。 组合角色还必须按角色类型做专项校验： diff --git "a/common/ai-workplace/AI\346\212\200\350\203\275\344\275\277\347\224\250\350\247\204\350\214\203.md" "b/common/ai-workplace/AI\346\212\200\350\203\275\344\275\277\347\224\250\350\247\204\350\214\203.md" new file mode 100644 index 0000000..e5864bc --- /dev/null +++ "b/common/ai-workplace/AI\346\212\200\350\203\275\344\275\277\347\224\250\350\247\204\350\214\203.md" @@ -0,0 +1,156 @@ +# AI 技能使用规范 + +创建人员：Codex +文件职责：定义 AI 角色会话和管理会话在项目协作中如何选择、声明、执行和记录技能。 +管理规范/模板：../../全局规范.md；AI工作空间创建指南.md；AI会话协作语义规范.md。 +引用文件：AI工作空间创建指南.md；AI会话协作语义规范.md；../project-doc/项目规范.md。 +记录方式：AI 技能使用规范；技能入口、显式声明、状态变更、校验或失败处理口径变化时更新。 + +## 1. 定位 + +本文件是 `common/ai-workplace/` 下的通用技能使用规范，适用于管理会话、项目角色会话和被分配多个角色的 AI 会话。 + +项目可以使用 MB-X 或其他 Agent 协作框架。只要项目提供技能、工具、命令或等价能力，AI 会话都必须按本文档执行：先确认上下文，再声明技能，再执行动作，最后校验和记录。 + +## 2. 基本原则 + +1. 技能是受约束的能力入口，不是任意扩大权限的理由。 +2. 角色只能使用当前上下文允许的技能。 +3. 状态变更类动作必须显式声明使用的技能或技能别名。 +4. 文档驱动优先，技能调用必须读取当前项目、体系、角色和事项要求。 +5. 技能执行结果必须可追踪，不能只停留在聊天窗口。 +6. 技能失败、权限不足或目标不确定时，必须记录阻塞并反馈给上游角色或管理会话。 + +## 3. 使用前必须确认的上下文 + +执行技能前至少确认： + +1. 当前项目或工作区。 +2. 当前 AI 会话身份。 +3. 当前角色或角色实例。 +4. 当前事项、任务、问题或消息 ID。 +5. 当前项目配置清单和角色绑定关系。 +6. 当前体系规范、角色工作说明和必读文档。 +7. 当前动作是否会改变项目、文档、消息、会话、数据或配置状态。 +8. 当前动作完成后需要写入哪个正式账本、日志、审计记录或消息链。 + +如果同一个 AI 会话绑定多个角色，必须先确认本轮以哪个角色身份执行。不得用一个角色的权限处理另一个角色的事项。 + +## 4. 技能选择矩阵 + +| 场景 | 技能类型 | 输出要求 | +|---|---|---| +| 读取项目约束、角色边界、必读文档 | 治理技能 | 说明已读取的上下文和适用约束 | +| 创建或维护工作区、项目、体系、角色、会话 | 管理技能 | 更新配置清单、执行日志、变更记录和必要审计 | +| 创建或维护 AI 工作空间、工作说明、角色绑定 | AI workspace 技能 | 更新 AI 私有空间、项目配置清单和角色入口 | +| 正式文档创建、修改、移动、删除、改名 | 文件治理技能 | 更新目录导读、引用、执行记录和审计证据 | +| 角色间交接、审核、确认、退回、升级 | 交互路由技能 | 形成正式消息，包含任务、来源、目标、证据、期望动作 | +| 读取并处理本角色 inbox 或待办消息 | 消息处理技能 | 展示消息正文，处理后回复或 ack | +| 后台自动处理角色消息 | 运行时技能 | 返回结构化动作和处理结论 | +| 框架、技能、工具或运行环境更新 | 更新技能 | 记录更新范围、验证结果、失败恢复方案 | +| 需求、开发、实验、案例等体系内专业工作 | 体系专业技能 | 按当前体系文档执行，并写入体系要求的正式记录 | + +当一个动作同时涉及多个技能时，先使用治理技能确认边界，再使用实际负责状态变更的主技能。执行记录中应写明主技能，必要时说明辅助技能。 + +## 5. 显式声明规则 + +只读理解类动作可以在回复中说明“使用治理技能读取上下文”。 + +以下动作必须显式声明技能： + +1. 修改项目、体系、角色、AI 工作空间、会话或工具配置。 +2. 创建、修改、移动、删除、重命名正式文档。 +3. 发送角色消息、确认消息、触发运行时或改变消息状态。 +4. 提交审核、退回修改、请求确认、升级管理端或跨角色交接。 +5. 更新框架、同步技能、修复错误日志或清理运行态。 +6. 写入结论、审计意见、验收记录或发布记录。 + +显式声明可以写在： + +- 人工可见会话回复中。 +- 正式消息正文中。 +- 项目执行日志、变更记录、问题记录或审计报告中。 +- 运行时返回的结构化动作中。 + +示例： + +```text +使用 skill_alias=route，向 dev.reviewer 发送 review_request： +任务：TASK-001 +证据入口：dev-doc/... +期望动作：按开发审核规范审核本次实现。 +``` + +## 6. 状态变更四步法 + +所有状态变更类技能按四步执行： + +1. **确认上下文**：读取当前项目、角色、事项、配置清单和必读文档。 +2. **声明技能**：说明本次使用的技能或技能别名。 +3. **执行动作**：调用工具、发送消息或修改文件。 +4. **校验记录**：按文档要求验证结果，并写入正式记录。 + +不允许先执行、后补理由。若上下文不完整，应先补上下文或发起补充信息请求。 + +## 7. 角色间交互技能要求 + +当文档中出现“提交审核”“交给产品确认”“退回开发员”“上报管理端”“请协作”等语义时，角色应使用交互路由类技能，而不是只在聊天窗口里说明。 + +正式交互消息至少包含： + +1. 任务 ID 或事项 ID。 +2. 来源角色。 +3. 目标角色。 +4. 消息类型或交互意图。 +5. 摘要。 +6. 背景。 +7. 证据入口。 +8. 期望动作。 +9. 校验或审核要求。 +10. 风险、阻塞或不确定项。 +11. 希望对方如何反馈。 + +目标角色不明确时，应先规划路由或请求管理员确认，不得自行创造角色或泛化为“某个审核员”。 + +## 8. 性能与上下文读取口径 + +技能使用要避免无意义的全量扫描。 + +1. 已知目标、任务和正文时，交互路由直接走发送路径。 +2. 接收消息后先可见确认“已收到”，再完整处理。 +3. 消息中主动写清证据入口，减少接收方搜索。 +4. 只读摘要足够时先读摘要；涉及审计、结论或争议时再读原文。 +5. 不同消息类型使用最小必要处理流程，避免每条消息都执行全量治理检查。 +6. 响应慢时先区分通信投递慢、会话 busy、模型处理慢、文档读取慢或工具命令慢。 + +速度优化不得削弱文档要求。若文档要求完整校验，必须执行完整校验并记录耗时。 + +## 9. 失败、越权和降级 + +遇到以下情况必须暂停状态变更： + +1. 当前会话无法确认项目或角色身份。 +2. 当前角色没有目标动作权限。 +3. 所需技能不在当前上下文中。 +4. 目标角色、审核入口或证据入口不明确。 +5. 工具调用失败、通信失败或运行时状态不可信。 + +处理方式： + +1. 写清失败命令、错误摘要和影响范围。 +2. 向上游角色、项目管理员或管理会话发送补充信息请求或升级消息。 +3. 按项目规范写入问题记录、执行日志、错误日志或审计报告。 +4. 得到新上下文或授权后再继续。 + +不得通过读取其他角色 inbox、修改未授权目录、跳过审核、绕过配置清单或使用非正式通信渠道来降级处理。 + +## 10. 校验口径 + +一次技能使用合格，至少满足： + +1. 使用前确认了当前项目、角色和事项。 +2. 所用技能与动作类型匹配。 +3. 状态变更类动作显式声明了技能。 +4. 输出进入正式消息链、正式文档或正式账本。 +5. 结果按当前文档要求完成校验。 +6. 失败、越权或不确定项有记录和恢复路径。 diff --git "a/common/ai-workplace/\347\233\256\345\275\225\345\257\274\350\257\273.md" "b/common/ai-workplace/\347\233\256\345\275\225\345\257\274\350\257\273.md" index e57849e..a502b74 100644 --- "a/common/ai-workplace/\347\233\256\345\275\225\345\257\274\350\257\273.md" +++ "b/common/ai-workplace/\347\233\256\345\275\225\345\257\274\350\257\273.md" @@ -3,7 +3,7 @@ 创建人员：Codex 文件职责：说明 `common/ai-workplace/` 下 AI 工作空间和角色指派相关通用文档的入口。 管理规范/模板：../../全局规范.md。 -引用文件：AI工作空间创建指南.md；AI会话协作语义规范.md；项目问题反馈范本.md。 +引用文件：AI工作空间创建指南.md；AI会话协作语义规范.md；AI技能使用规范.md；项目问题反馈范本.md。 记录方式：目录导读；新增或删除本目录文件时更新。 ## 文件清单 @@ -12,6 +12,7 @@ |---|---| | AI工作空间创建指南.md | 指导项目管理员创建 AI 工作空间、分配角色、生成工作说明和项目问题反馈入口并做校验 | | AI会话协作语义规范.md | 定义 AI 角色会话如何把“提交审核、退回、交给产品、上报管理员”等文档字眼转换为正式角色交互动作 | +| AI技能使用规范.md | 定义 AI 会话如何选择、声明、执行和记录技能，尤其是状态变更、消息交互、失败和越权处理 | | 项目问题反馈范本.md | 提供 `ai-<name>/项目问题反馈.md` 的参考写法，用于重大协作问题和反复返修问题反馈 | ## 使用顺序 @@ -19,7 +20,8 @@ 1. 项目管理员先确认项目根目录和 `项目配置清单.md`。 2. 按 `AI工作空间创建指南.md` 创建 `ai-<name>/`。 3. 读取 `AI会话协作语义规范.md`，把角色间交接、审核、确认、返修、升级等自然语言动作写入工作说明。 -4. 生成 `ai-<name>/工作说明.md`。 -5. 参考 `项目问题反馈范本.md` 创建 `ai-<name>/项目问题反馈.md`。 -6. 同步更新 `项目配置清单.md`、`项目执行日志.md`、`项目变更记录.md`。 -7. 按指南中的校验方案检查。 +4. 读取 `AI技能使用规范.md`，把角色允许使用的技能、显式声明方式、状态变更记录和失败处理口径写入工作说明。 +5. 生成 `ai-<name>/工作说明.md`。 +6. 参考 `项目问题反馈范本.md` 创建 `ai-<name>/项目问题反馈.md`。 +7. 同步更新 `项目配置清单.md`、`项目执行日志.md`、`项目变更记录.md`。 +8. 按指南中的校验方案检查。 -- Gitblit v1.9.3