# Team Roles

> This skill should be used when the user asks to "安装远程角色", "team-roles add", "team-roles list", "添加远程角色", "管理远程角色", "从 GitHub 安装角色", "team-roles update", "team-roles remove", "team-roles search", "install remote roles", "add remote roles", "远程角色管理", "list remote roles", "update remote roles", "remove remote roles". 从 GitHub 仓库、单文件 URL 或 npx 包安装扩展角色到项目级缓存 .team-roles/。

- Skill: `killvxk/team-roles` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add killvxk/team-roles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/killvxk/team-roles/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: killvxk (https://skillmd.com/u/killvxk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/killvxk/team-roles

---


# 远程角色管理（team-roles）

管理项目级远程角色缓存，支持从 GitHub 仓库、单文件 URL、npx 包三种来源安装角色文件，与 `/team-init`、`/team-load`、`/team-save` 无缝集成。

## 路径约定

- `{work_dir}`：用户当前工作目录（项目根目录）
- `.team-roles/`：`{work_dir}/.team-roles/`，远程角色缓存根目录
- `roles-lock.json`：`{work_dir}/.team-roles/roles-lock.json`，锁文件（唯一数据源）

缓存目录结构：
```
.team-roles/
├── roles-lock.json           # 锁文件
├── {repo-name}/              # GitHub repo 源
├── _singles/                 # 单文件 URL 源
└── _npx/{package-name}/      # npx 包源
```

---

## 子命令路由

| 参数 | 路由 |
|------|------|
| `add <url>` 或 `add npx:<pkg>` | → `add` |
| `list` | → `list` |
| `search <keyword>` | → `search` |
| `update [repo-name]` | → `update` |
| `remove <role-code>` | → `remove` |
| 无参数 | → 打印使用说明 |

---

## `add` — 安装远程角色

### 源类型自动检测

```
参数以 "npx:" 开头       → sourceType = "npx"
参数匹配 github.com      → sourceType = "github-repo"
其他（含 .md 结尾）       → sourceType = "file-url"
```

### .gitignore 自动追加

首次创建 `.team-roles/` 目录时，检查并追加 `.team-roles/` 到 `.gitignore`。

### 安装流程

按 `sourceType` 分支执行，详细步骤参考 **`references/add-flows.md`**：

- **A1. GitHub Repo**：`git clone --depth 1` → 检测 manifest（`team-roles.json`）→ 扫描角色文件 → 5-Block 验证 → 用户选择 → 冲突检测 → 复制到 `.team-roles/{repo-name}/` → 更新 lock → 清理临时目录
- **A2. 单文件 URL**：`WebFetch` 下载 → 5-Block 验证 → 展示摘要确认 → 写入 `_singles/` → 更新 lock
- **A3. npx 包**：三级回退安装（`npx skills add` → git clone → 报错）→ 扫描 `.md` 文件 → 剥离 YAML frontmatter → 标记 unverified → 用户选择 → 写入 `_npx/` → 更新 lock

### 冲突检测

角色代号与已安装角色重复时，提示 3 个选项：
1. "覆盖已有" — 替换 lock 条目和文件
2. "跳过此角色" — 不安装
3. "重命名为 {repo}-{code}" — 保留两者

### `--roles=a,b` 参数

跳过交互，直接安装指定代号的角色。

---

## 5-Block 验证算法

| 标签对 | 权重 |
|--------|------|
| `<role>` + `</role>` | **必须** |
| `<rules>` + `</rules>` | **必须** |
| `<deliverables>` + `</deliverables>` | 可选 |
| `<collaboration>` + `</collaboration>` | 可选 |
| `<metrics>` + `</metrics>` | 可选 |

- 两个必须标签对均存在 → `verified: true`
- 任一必须标签对缺失 → `verified: false`（unverified）
- verified 但缺少可选标签 → 仍为 verified，输出 warning

---

## `list` — 列出已安装角色

从 `roles-lock.json` 读取，格式化表格输出：

```
| 代号           | 来源             | 类型        | 状态         | 安装时间   |
|----------------|-----------------|------------|-------------|------------|
| ai-engineer    | user/my-roles   | github-repo | ✓ verified  | 2026-03-18 |
| vite-skill     | antfu/skills    | npx         | ⚠ unverified | 2026-03-18 |

共 {N} 个角色，来自 {M} 个源
```

空状态提示：`暂无已安装的远程角色。使用 team-roles add <url> 安装。`

---

## `search` — 搜索已安装角色

对 `code`、`displayName`、`department`、`source` 四个字段做不区分大小写的关键词匹配。输出格式同 `list`。

---

## `update` — 更新角色

按源类型分别处理，详细步骤参考 **`references/update-flows.md`**：

- **GitHub repo**：clone → 比对 commitHash → 逐角色覆盖 + 重新 5-Block 验证 → 更新 lock
- **单文件 URL**：WebFetch 重新下载 → 内容比对 → 覆盖 + 重新验证 → 更新 lock
- **npx 包**：覆盖安装 → 重新扫描 → 覆盖缓存 → 更新 lock

每次 update 都重新运行 5-Block 验证（角色可能从 unverified 变为 verified，或反之）。

---

## `remove` — 移除角色

1. 在 `roles-lock.json` 中查找角色代号
2. 展示信息并确认删除
3. 删除缓存文件
4. 从 lock 的 `roles[]` 移除条目
5. 若该 repo 下无剩余角色 → 删除整个目录 + 从 `repos[]` 移除
6. 写入 lock

---

## 错误处理

| 场景 | 处理 |
|------|------|
| `git clone` 失败 | 报错退出，清理临时目录 |
| WebFetch 失败 | 报错退出 |
| lock 损坏 | 提示手动检查或删除后重试 |
| lock 不存在（读） | 视为空 lock |
| lock 不存在（写） | 初始化新结构 |
| npx + git 都失败 | 提示用户提供 GitHub URL |

---

## 使用说明

```
team-roles — 远程角色管理

用法：
  team-roles add <github-url>          从 GitHub 仓库安装角色
  team-roles add <file-url.md>         从单文件 URL 安装角色
  team-roles add npx:<package>         从 npx 包安装角色
  team-roles add <url> --roles=a,b     指定安装部分角色（非交互）
  team-roles list                      列出所有已安装的远程角色
  team-roles search <keyword>          搜索已安装角色
  team-roles update [repo-name]        更新指定 repo 或全部角色
  team-roles remove <role-code>        移除指定角色
```

---

## 参考资料

详细流程和 schema 定义：
- **`references/add-flows.md`** — 三种源类型的完整安装步骤（A1/A2/A3）
- **`references/update-flows.md`** — 三种源类型的完整更新步骤（U1/U2/U3）
- **`references/lock-schema.md`** — `roles-lock.json` 完整 schema、字段说明、初始化结构