Equipment Manager

装备管理器（Equipment Manager）

管理从第三方仓库安装的 skill 与 agent，全程用对话式流程推进：一次一问、给选项、你拍板、才动手。方法论一份，各仓库专属情报按仓库归档在 references/；装备状态（已装清单/评估结论）存独立台账 ~/.config/equipment-manager/state.json——档案只存稳定情报、状态不跟 git，加新仓库只需加一个档案文件，方法论不动。

使用时机

• 某仓库 git pull 后有新增/变更的 skill 或 agent，需评估是否安装
• 从某仓库安装新 skill/agent
• 精简/删除某仓库已装的装备
• 盘点本地已装的 skill/agent 及其来源

支持的仓库

数据分层（三层，别混）

• 仓库档案 references/*.md：稳定情报（基本信息/目录结构/安装机制/坑位），变更低频、进 git 语义干净
• 装备状态 ~/.config/equipment-manager/state.json：易变状态（已装清单/评估结论），不进 git，装删零噪音、可被 dotfiles 同步
• 用户画像：属独立 skill persona（skills/persona/profile.md 人工层 + profile.d/<hostname>.md 自学习层 + miner-state 纠正状态）——本技能只消费画像，不维护

查重以实际目录为准（ls ~/.claude/skills/ + 软链来源识别），台账仅辅助回忆历史决策。

接入新仓库

当用户说「我新 clone 了 XX 仓库」「想接入 XX 仓库」、或提出一个新的 skill/agent 来源时：

1. 确认来源：git -C <仓库路径> remote -v
2. 摸清结构：目录结构、命名约定、安装机制（复制 vs 符号链接）
3. 建档案：在 references/ 下新建档案文件（按作者或仓库名命名，仿照现有三个档案的格式：基本信息/目录结构/安装机制/坑位），只存稳定情报
4. 登记：在上表加一行
5. 更新 description：把新仓库加入 frontmatter description 的「已接入」列表（保持触发精准）

通用内核不动——仓库差异全走档案，加仓库 = 建档案 + 表格一行 + description 补一个名字。

对话式流程

装备管理是一场对话，不是一份报告。核心节奏：一次一问 → 给 2-3 个选项 → 你选 → 确认 → 下一步。每个岔路口停下来等你拍板，不一口气甩结论。

硬闸门

在对话对齐并获得你明确批准之前，不安装、不删除、不改动任何文件。对话本身是安全的——只有你说"装/删"之后才动手。

阶段一：对齐场景（开场必问）

别一上来就盘点或查仓库。先问一句你要干嘛，给选项：

• A 盘点：本地装了什么、各来自哪个仓库
• B 评估：某仓库 git pull/clone 后新增了啥，值不值得装
• C 安装：从某仓库装某个 skill/agent
• D 精简：清理用不上的旧装备

选完再走对应分支；B/C/D 先确认是哪个仓库、意图是什么，再深入。

阶段二：澄清（一次一问）

一次只问一个，问到 95% 确定理解需求为止；优先给多选，开放回答也行。涉及删除，先复述你理解的清单让你确认，再继续。

评估场景（B）必须先对齐使用习惯：推荐的第一标准是「你用不用得上」，不是「本地有没有同类」。动工前先读用户画像（画像维护归 persona skill）：

• 读画像：cat skills/persona/profile.md（人工层）+ skills/persona/profile.d/*.md（自学习层汇总；顶层通配符天然不匹配 profile.d/prefs/ 子目录，个人习惯备忘不参与评估）。画像 = 🧠记忆 + 🔍扫描/miner 实测 + 🗣口述交叉验证，单一口述不落地
• 画像 updated 超 90 天或缺失 → 先跑 persona skill 更新画像（扫描 + miner 举证 + 你确认），再评估
• 画像可用 → 亮出画像要点（工作流/技术栈/明确不用的领域），问一句「这份画像还准吗？有变化就回写」，以你当场确认为准
• 判定依据必须标注证据来源：每个「用得上/用不上/建议/不建议」判定，理由一律标依据——🧠画像实证 / 🔍实测 / 🗣用户表态 / ⚠️推断。画像「明确不用领域」为空时，「用不上」多是推断，必须标 ⚠️推断，不得冒充实证；⚠️推断驱动的「建议安装」不直接进建议表，先走第二意见或降级待权衡

阶段三：摸底与查重（读地图，不裸跑 ls）

1. 跑脚本：scripts/scan-installed.sh → 全量事实清单（NAME/SOURCE/FORM/ENABLED/DESCRIPTION，插件走官方 CLI、LSP 天然过滤、gstack 折叠）；--check 自动断言覆盖度与合规
2. 读语义：~/.config/equipment-manager/state.json 的 inventory → 每个已装装备的 purpose/tags；缺 purpose 的新装备现场补写（按模板细心琢磨）
3. 识别增量：git -C <repo> log --diff-filter=A --name-only --since="90 days"，对照事实清单 + inventory 区分新增与早已装，只评估新增
4. 查重：按 tags 聚簇（tags 交集 = 进决策树门票）+ purpose 精判，决策树第 0 步任务粒度判定重复

输出必须用大白话：什么是什么、哪来的。术语要翻译（in-progress=未完工、软链=跟着仓库更新自动传播、ticket=拆出的任务条），不许甩黑话。

阶段三点五：重复判定（冲突结局决策树）

总门槛（先于一切判定）：本地没有同类 ≠ 值得装。「用不用得上」按阶段二对齐的使用习惯判，与本地是否有同类无关。无同类但用户工作流用不上 → 直接进「不建议安装」，理由写「用户工作流用不上」，不进决策树。只有「用户实际会用」的装备才进决策树判重复。

对每项可能与本地已装重复的装备，走决策树。入口先问一句：「新装备可能与本地已装的 X 抢同一任务，需要我对比吗？」——需要才走决策树，不需要直接按正常流程。

0. 任务粒度判定：与本地已装的是否解决「同一个具体任务」？

• 任务不同 → 不算重复，走正常评估（不进查重）
• 任务相同 → 真重复，看触发词

1. 触发词是否重叠？

• 触发词不重叠 → 并存例外：无触发词互相干扰风险（上下文膨胀成本仍在，由你取舍），标注「可并存」，进待权衡项。跳过缺口仲裁与审核。
• 触发词重叠 → 进入缺口仲裁

2. 缺口仲裁（默认不装）：

• 本地旧装备已废弃/停更/不可用 → 第一类缺口，直接进入替换评估（覆盖检查放松：死工具的独有能力无保留价值）
• 旧装备够用 → 不装，理由写「本地 X 已覆盖，无缺口」
• 旧装备有明显缺口（一句话能说清、旧装备明确缺少、你实际会用的能力）且新装备恰好补上 → 进入替换评估
• 缺口说不清、只是角度不同 → 不装，宁可漏判不堆表

3. 第二意见审核（强制）：凡结论会落进「建议安装」表——含首次评估无重复的新装备、以及替换评估——一律过第二意见：子代理（Agent 工具）或 /codex，视角 = 缺口/价值判断是否成立 + 依据是实证还是推断 + 未覆盖能力是否可接受

• 替换评估的覆盖检查：新装备是否覆盖旧装备独有能力（= 旧具备、新不具备、你实际依赖的能力）？未覆盖 → 以审核结论为准，提示你确认接受损失后拍板，不默认替换
• 审核结论记录后按两阶段流定去向：确认「值得」→ 提升为建议安装并标「建议替换本地 X」（首次评估标「经审核」）；否决 → 降为不装（见下方表联动）
• 审核后仍无法判定 → 默认不装（不回问答二选一，SKILL.md 写死默认不装）

4. 多重冲突：新装备与多个本地项碰撞时，逐对走完决策树；结局不一致（对 A 替换、对 B 并存）→ 升级第二意见 / 你拍板。

阶段四：给方案（先出三张带理由的表，再提问）

摸底完成后，先把全貌一次给全——三张表格，每张都带理由列，让用户先看完整盘、再逐个拍板。不要边摸底边穿插提问。

三张表给出后，再进入逐项提问：每个决策点给 2-3 个选项带利弊，先说我的推荐，你选：

• 安装方式（须你拍板）：软链（仓库更新自动传播，省磁盘，但仓库路径变动会断链）vs 复制（独立稳定，但更新需手动重装）；默认推荐复制（用户偏好：不用软链、避免断链事故），听你的
• 删不删：给三档清单（保留/待定/删）+ 理由，等你确认

阶段五：批准与执行

你说"装/删"之后才动手：

1. 覆盖/删除前先备份：mkdir -p ~/.claude/backups/<日期> + cp，不用 mv xxx.bak
2. 按你选的安装方式执行（软链 ln -s / 复制 cp -r，官方脚本有软链选项优先用官方参数，具体见对应仓库档案）
3. 验证：文件存在且非空；软链 readlink 确认目标存在、目标目录有 SKILL.md
4. 同步台账：装/删后更新 ~/.config/equipment-manager/state.json（installed、notes 与 inventory）。评估结论必须记录审核状态：过第二意见的记「经审核」（附一句结论），未过审的推断项记「⚠️推断未审核」。inventory 增量维护：
   • 装/删后重跑 scan-installed.sh，对比 inventory 与事实层差异
   • 模型只对新增装备写 purpose/tags（按模板细心琢磨），已存在不动
   • 删除装备整条移除；词表扩充时存量 tags 由模型重映射
5. 接入一键安装（自动收尾，不额外征询）：装/删完成后同步 my-skills 的三机部署入口，保证其他机器 bash install.sh 即自动带上/移除该装备：
   • 仓库已接入 my-skills install.sh → 自动更新 my-skills/install.sh（EQUIP 元数据行 + 对应安装段；装=加、删=同步移除）与 my-skills/THIRD-PARTY.md（表格行 + 调用方式），然后 bash -n 校验语法 + bash install.sh --list 复核统计
   • 仓库未接入 my-skills → 走「接入新仓库」流程先建档案再接入；用户没让接入新仓库时，只提示该装备未进一键安装，不擅自塞入

接入新仓库（同样对话式）

用户说"接入新仓库"时，走阶段一 B/C 分支，确认仓库路径后依次确认：来源（git remote -v）→ 结构（目录/命名/安装机制）→ 建档案（references/ 下按作者或仓库名新建，仿现有三个档案）→ 登记表格 → 更新 frontmatter description。每一步都先确认再做下一步，不一口气全做。

常用操作速查

常见误区

• 把台账当真相 → 查重以实际目录为准（ls + readlink），台账只记历史决策
• 把「本地没同类」当「值得装」 → 推荐看使用习惯：无同类但用不上 = 不装；用得上且无同类 = 才考虑建议安装
• 在本技能维护画像 → 画像属独立 persona skill，equipment-manager 只消费不维护；要更新先跑 persona
• 画像只靠口述 → 画像必须经 persona 的扫描 + miner 举证交叉验证，单一口述不落地
• 按名字判重复 → 按任务粒度判：与本地已装解决同一具体任务才算重复
• 一口气甩结论 → 必须对话式：阶段四才给全量三张表，之前一次一问
• 默认安装方式 → 软链/复制由用户拍板，不默认；默认推荐复制（用户偏好，见记忆 install-preference-no-symlink）
• 装完不接入 install.sh → 三机部署入口漏了该装备，其他机器装不上；阶段五步骤 5 自动收尾同步
• 删前不备份 → 覆盖/删除前一律先 mkdir -p ~/.claude/backups/<日期> + cp
• 把推断当实证 → 判定理由必须标依据来源（🧠/🔍/🗣/⚠️）；⚠️推断的「建议安装」不过第二意见不得进建议表，⚠️推断的「用不上」不得冒充画像实证
• 台账进 git → state.json 不进 git，装删零噪音、可被 dotfiles 同步
• 裸跑 ls 当盘点 → 用 scripts/scan-installed.sh 拿全量事实（官方 CLI 覆盖插件、LSP 天然过滤、gstack 折叠），state.json 的 inventory 给语义；不再裸跑 ls ~/.claude/skills/
• 把 command-based 插件当 skill → code-review/commit-commands/feature-dev/pr-review-toolkit 等插件 skill 在 commands/ 下无 SKILL.md，脚本不列出属正常；按需用 /命令 直接调用
• expect DESCRIPTION 永远可读 → 个别 SKILL.md 用多行 description（>/|），脚本只取到符号，读该装备语义以 inventory.purpose 为准