全量分发的问题：配置噪音
团队仓库跑起来之后很快会撞上这个问题：仓库里积累了几十个 Skills，但它们不是为所有人准备的——
- 部署运维类 Skills，对前端工程师是纯噪音
- 前端组件规范 Rule，后端同事永远不会用
- 测试工程师需要的接口测试 Skills，开发视角根本不关心
全量分发的后果不只是「列表难看」。配置噪音会稀释 AI 的注意力：上下文里塞满了与当前任务无关的 Skills 和 Rules，AI 的行为反而变差。给 AI 的配置和给系统的权限一样，都需要最小化原则。
teamai-cli 的角色机制解决这个问题：通过 manifest/roles.yaml 定义角色，不同角色获得不同的配置子集。
roles.yaml：角色的定义方式
在仓库的 manifest 目录里用 roles.yaml 声明角色。每个角色绑定一组 Skills/Rules/Docs 的子集——从全量资产里圈出「这个岗位需要的部分」。
官方文档给的示例角色命名：hai（AI 工程师）、pm（产品经理）、devops（运维）。实际按你的团队结构调整，常见的角色划分思路：
| 角色维度 | 示例 | 分发内容倾向 |
|---|---|---|
| 按职能 | 前端 / 后端 / 移动端 | 各技术栈的 Skills 与规范 |
| 按工种 | 开发 / 测试 / 运维 / 产品 | 工种专属工作流配置 |
| 按资历 | 新人 / 资深 | 新人多了「项目导览」「避坑指南」类 |
| 按项目 | 项目A / 项目B | 项目专属约定与文档 |
角色的设置与叠加
成员侧用 teamai roles set 绑定自己的角色：
# 设置主角色为 AI 工程师
teamai roles set hai
# 在主角色之上附加产品经理角色（一人多角色场景）
teamai roles set hai --add pm两个设计细节值得注意：
主角色 + 附加角色的叠加结构。一人兼多岗是常态——既写代码又兼运维的工程师，set 主角色 hai 再 —add devops，两个角色的配置子集合并生效。这比「每个组合建一个角色」灵活得多：三个基础角色可以组合出任意岗位形态。
角色切换即时生效。pull 或下次会话启动（SessionStart Hook）后，本机 AI 工具目录里的配置就变成了当前角色对应的子集。转岗、借调这类场景，改一行命令完成配置迁移。
设计角色矩阵的实操建议
给团队设计 roles.yaml 时，按这个顺序推演：
第一步，盘点资产打标签。 把仓库里每个 Skill/Rule 标上适用对象——这个动作在做Skills 治理时顺手完成，打标签的过程本身就会暴露「这个 Skill 到底谁在用」的存量问题。
第二步，从「不需要什么」反推角色。 先看运维不需要什么（前端框架类）、前端不需要什么（部署类）——减法比加法好做，角色边界自然浮现。
第三步，公共层独立。 所有角色都需要的（代码规范基线、通用文档查询 Skills）放进公共层，所有角色自动获得——角色文件里只写差异部分，避免重复声明。
第四步，留一个 full 角色。 管理员或需要全量配置的角色（比如做配置巡检的人）用 full，日常不建议成员默认全量。
一个三角色配置示例的结构
公共层（所有角色）：
代码规范基线、Git 工作流、架构文档、通用查询 Skills
hai（AI 工程师）：
+ 各语言开发 Skills、API 设计规范、测试策略
pm（产品经理）：
+ 需求文档 Skills、原型审查清单、项目背景 Docs
devops（运维）：
+ 部署 Skills、监控巡检流程、基础设施文档分发的最小化不是抠门，是让每个人打开 AI 工具时，看到的都是为自己岗位定制的、干净的配置环境。
角色配置命令速查表
角色机制涉及的全部命令，按「定义 → 绑定 → 验证」三个环节排列：
| 命令 | 环节 | 作用 |
|---|---|---|
编辑 manifest/roles.yaml | 定义 | 管理员声明角色与各角色的配置子集 |
teamai roles set <角色> | 绑定 | 成员设置主角色 |
teamai roles set <主角色> --add <附加角色> | 绑定 | 一人多角色的叠加组合 |
teamai pull | 生效 | 拉取当前角色对应的配置子集 |
teamai status | 验证 | 确认本地与远端一致 |
teamai list | 验证 | 查看当前角色下实际装了哪些技能 |
teamai skill exclude add <技能名> | 微调 | 角色粒度之下的个人级排除 |
注意最后两行的层级关系：roles.yaml 决定「这个岗位看到什么」，skill exclude 决定「我个人不要什么」。两层各司其职——如果某个技能整个岗位都不需要，正确做法是改角色定义，而不是让每个成员各自 exclude 一遍。
角色机制 FAQ
Q：roles.yaml 由谁来改？ 它是仓库里的文件，变更走和 Skills、Rules 一样的 push → MR/PR 审核 → 合并流程。角色定义影响全团队的分发结果，比单个 Skill 的变更更值得认真 review。
Q：新成员应该先 init 还是先 roles set？
先 init 接入仓库，再 teamai roles set 绑定角色。顺序反了也没关系——绑定后 pull 一次（或等 SessionStart Hook 自动同步）即可收敛到正确子集。两步加起来三十秒，岗位级环境初始化完成。
Q：转岗或借调时配置怎么迁移？
一条 teamai roles set <新角色>（原岗位能力还要保留就 --add 附加角色），pull 或下次会话启动后本机配置自动切换到新子集。旧角色的配置随之退场，不需要手动清理。
Q：公共层的某个 Skill 想对特定角色隐藏怎么办？ 这属于角色定义问题：回 roles.yaml 调整该角色的子集范围，而不是让成员个人 exclude——角色定义管「岗位该有什么」，个人 exclude 只处理「我个人用不上」的长尾情况。
Q：角色建多了怎么管理？ 从组合的角度控制数量：基础角色少而正交（比如按工种分三四个），复杂岗位靠主角色 + 附加角色组合覆盖。「每个组合建一个角色」会让 roles.yaml 膨胀到没人维护——那是另一种形式的配置腐化。
与团队权限体系的衔接
注意区分两层权限：仓库层权限（谁能 push、谁能合并——Git 平台管理）和配置层权限（谁同步哪些内容——roles.yaml 管理）。两层正交：一个只读成员也可以是任何角色。新人入职的标准动作于是变成两条命令：teamai init 接仓库 + teamai roles set <角色> 定身份——三十秒完成岗位级环境初始化。
角色机制配好了，teamai-cli 还有两个更深的能力在等你：摩擦信号的经验沉淀（团队成员踩的坑自动变成知识库）和知识召回（沉淀的知识被 AI 主动用起来）——这两件事合起来，才是这个工具区别于普通配置分发工具的地方。