edit | blame | history | raw

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. 写入结论、审计意见、验收记录或发布记录。

显式声明可以写在：

  • 人工可见会话回复中。
  • 正式消息正文中。
  • 项目执行日志、变更记录、问题记录或审计报告中。
  • 运行时返回的结构化动作中。

示例：

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