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