killvxk 远程角色管理（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 个选项：
- "覆盖已有" — 替换 lock 条目和文件
- "跳过此角色" — 不安装
- "重命名为 {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 — 移除角色
- 在
roles-lock.json中查找角色代号 - 展示信息并确认删除
- 删除缓存文件
- 从 lock 的
roles[]移除条目 - 若该 repo 下无剩余角色 → 删除整个目录 + 从
repos[]移除 - 写入 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、字段说明、初始化结构