docs: add AI skill usage governance

cai

2026-06-07 512faa36f7634c3e25068761afaf3f20d2e8170f

docs: add AI skill usage governance

 common/ai-workplace/AI会话协作语义规范.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. 消息内容最低要求

任何正式交互消息至少包含：

 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；项目问题反馈范本.md。  
引用文件：../../全局规范.md；../project-doc/项目规范.md；../project-doc/项目环境创建指南.md；../project-doc/项目配置清单模版.md；AI技能使用规范.md；项目问题反馈范本.md。  
记录方式：通用创建指南；AI 工作空间、角色分配、工作说明或校验口径变化时更新本文。

## 1. 使用场景
@@ -219,7 +219,8 @@
7. 正式产物目录、草稿目录、临时目录和审计入口。
8. 任务入口路由：接到任务后应该先查哪个配置、再读哪个体系规范。
9. 审核边界：如果该 AI 是审核员，要写清审核体系、审计报告入口和不能直接改被审计产物。
10. 禁止事项和越权边界。
10. 技能使用入口：写清允许使用的技能、显式声明方式、状态变更记录和失败处理口径。
11. 禁止事项和越权边界。

`工作说明.md` 不能替代 `实验规范.md`、`编码规范.md`、`开发审计规范.md`、`项目规范.md` 等体系文档。体系流程变化时，以对应体系文档为准，工作说明只做入口索引。
审核员角色的“必读文档入口”必须同时列出被审体系规范、审计规范 / 审计报告入口、被审对象账本入口。
@@ -239,7 +240,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. 基本信息
@@ -288,7 +289,14 @@
2. 如果有不理解、冲突或不合理的地方，反馈给项目管理员，不要自行脑补执行。
3. 如果问题会影响项目协作、角色权限或体系推进，同步记录到 `ai-<AI_NAME>/项目问题反馈.md`。

## 7. 审核边界
## 7. 技能使用入口

1. 技能选择、显式声明、状态变更记录、失败越权处理按 `../../common/ai-workplace/AI技能使用规范.md` 执行。
2. 状态变更类动作必须在回复、消息、执行日志或结构化动作中写明使用的技能或技能别名。
3. 角色间交接、审核、确认、退回、升级时，必须进入正式消息链或正式账本，不得只在聊天窗口声明。
4. 所需技能、目标角色、审核入口或权限不明确时，先反馈项目管理员，不得自行扩大权限。

## 8. 审核边界

如果本 AI 是审核员：

@@ -297,7 +305,7 @@
3. 不直接改被审计主产物。
4. 自审必须标注“自审”，并列出可复核证据。

## 8. 禁止事项
## 9. 禁止事项

1. 不得把工作空间当正式产物目录。
2. 不得越权写未分配体系目录。
@@ -367,6 +375,7 @@
12. 是否要求 AI 首次阅读后在 `worklog/` 记录理解反馈和疑问。
13. 是否写清 `项目问题反馈.md` 的入口和边界：只反馈重大协作问题，不替代正式审计报告、问题记录或执行日志。
14. 是否说明 `项目问题反馈.md` 的写法参考 `common/ai-workplace/项目问题反馈范本.md`。
15. 是否引用 `common/ai-workplace/AI技能使用规范.md`，并写清技能显式声明、状态变更记录、消息交互和失败越权处理口径。

组合角色还必须按角色类型做专项校验：


 common/ai-workplace/AI技能使用规范.md

New file
@@ -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. 失败、越权或不确定项有记录和恢复路径。

 common/ai-workplace/目录导读.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. 按指南中的校验方案检查。