# https://github.com/sukoji/loadout 项目说明书
生成时间：2026-07-03 18:22:47 UTC
## 目录
- [项目概述与核心价值](#page-overview)
- [三层覆盖生态与目录体系](#page-tiers)
- [CLI 模块架构与数据流](#page-architecture)
- [插件市场与斜杠命令注册](#page-marketplace)
- [扫描、领域匹配与推荐打分](#page-scan-recommend)
- [应用写入与多代理配置](#page-apply-targets)
- [目录 JSON、领域文档与校验流程](#page-catalog)
- [Doctor 审计、命令行工作流与贡献指南](#page-ops-contrib)
## 项目概述与核心价值
### 相关页面
相关主题：[三层覆盖生态与目录体系](#page-tiers), [扫描、领域匹配与推荐打分](#page-scan-recommend)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sukoji/loadout/blob/main/README.md)
- [CLAUDE.md](https://github.com/sukoji/loadout/blob/main/CLAUDE.md)
- [CHANGELOG.md](https://github.com/sukoji/loadout/blob/main/CHANGELOG.md)
- [package.json](https://github.com/sukoji/loadout/blob/main/package.json)
- [src/index.js](https://github.com/sukoji/loadout/blob/main/src/index.js)
- [src/catalog.js](https://github.com/sukoji/loadout/blob/main/src/catalog.js)
- [src/discover.js](https://github.com/sukoji/loadout/blob/main/src/discover.js)
# 项目概述与核心价值
## 项目定位与基本介绍
Loadout 是一个面向 Claude 开发者的插件加载与发现工具，作为 npm 包 `claude-loadout` 发布 资料来源：[package.json:1-20]()。它聚焦于解决 Claude 工作流中"插件分散、来源不一、信任难以甄别"这一长期痛点，让工程师能够在单一入口中完成插件的选取、安装与激活。项目的核心理念可以浓缩为一句话：**让 Claude 的能力加载像游戏装备栏（Loadout）一样可被精心编排**。
从工程视角看，Loadout 既不是 Claude 自身的替代品，也不是单一插件仓库，而是**插件元数据与发现流程的协调层**。它向上对接 Claude 的插件运行时，向下对接三个差异显著的来源——官方市场、社区贡献与本地精选集。
## 核心价值主张
Loadout 的价值可拆解为三条互相支撑的设计原则：
1. **统一入口（Unified Entry）**：开发者不再需要在 Anthropic 官方市场、GitHub 仓库、个人收藏之间来回切换。Loadout 提供一致的 CLI 与配置约定。
2. **分层信任（Layered Trust）**：不同来源的插件被赋予不同的可信等级，并在 UI/CLI 输出中显著标注，避免把"未经验证"的项目混入生产栈。
3. **栈感知匹配（Stack-aware Matching）**：插件列表会根据用户当前声明的技术栈进行过滤与推荐，而非简单地把全部条目一并倾倒。
这三个原则共同构成了 Loadout 在 Claude 工具生态中的差异化定位 资料来源：[README.md:10-40]()。
## 三层覆盖架构
| 层级 | 来源 | 规模 | 可信标识 | 触发方式 |
|------|------|------|----------|----------|
| Tier 1 | 项目维护者精选（Curated） | 35 项 | verified | 默认加载 |
| Tier 2 | Anthropic 官方市场 | ~240 项 | official | 按技术栈匹配时显示 |
| Tier 3 | 社区技能（Community） | 4 项 | unverified | 必须显式 `--discover` |
合计 **279 个目录条目** 是 v0.3.0 的当前容量 资料来源：[CHANGELOG.md:1-25]()。这一三层结构在代码层面分别由不同的模块承载：精选集直接以静态数据进入打包流程，官方市场通过抓取/索引模块按需拉取，社区技能则交由专门的发现管线处理 资料来源：[src/catalog.js:1-80]()。
```
用户 CLI 入口
│
▼
┌──────────────────────┐
│ loadout load / sync │
└──────────┬───────────┘
▼
┌───────────────┐
│ catalog.js │ ← 合并三层数据源
└───────┬───────┘
▼
┌───────────────┐
│ Claude 插件 │
│ 运行时 │
└───────────────┘
```
## 发现机制与安全边界
社区层（例如被称为 "caveman token-saver" 的省 token 提示技巧）通过 `--discover` 命令显式启用，并在输出中明确标记为 `unverified`，**绝不会被自动应用** 资料来源：[CHANGELOG.md:5-15]()。这一约束由 `discover.js` 在调用链最外层完成：它既负责从外部源抓取条目，也负责给结果打上不可自动激活的标记，从而把"发现"与"应用"这两个动作在权限层面解耦 资料来源：[src/discover.js:1-60]()。
这一设计回应了社区中反复出现的关切：**Claude 插件生态扩张迅速，开发者渴望广度，又对自动加载未审核内容心存警惕**。Loadout 通过"按需发现 + 显式启用"的双门设计，在两者之间取得了务实平衡 资料来源：[CLAUDE.md:1-30]()。
## 适用人群与典型场景
- **个人开发者**：希望快速为本地 Claude 配置一组可信工具，而无需自行维护清单。
- **小团队**：需要在多人之间复现一致的插件集合，借助 Loadout 的同步能力降低环境差异。
- **技术写作者与研究者**：通过 `--discover` 探索社区新插件，但保留人工把关的最终决定权。
综上，Loadout 以"轻量协调层 + 三层信任模型"的组合，定位为一个**值得长期放置在开发者工具链边缘**的辅助组件，而非喧宾夺主的运行时替代品 资料来源：[src/index.js:1-50]()。
---
## 三层覆盖生态与目录体系
### 相关页面
相关主题：[项目概述与核心价值](#page-overview), [目录 JSON、领域文档与校验流程](#page-catalog), [插件市场与斜杠命令注册](#page-marketplace)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/loadout/catalog/community.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/community.json)
- [plugins/loadout/catalog/ecosystem.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/ecosystem.json)
- [scripts/ingest-official.mjs](https://github.com/sukoji/loadout/blob/main/scripts/ingest-official.mjs)
- [cli/lib/recommend.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/recommend.mjs)
# 三层覆盖生态与目录体系
Loadout 的目录体系围绕"广度优先、人工把关、按需落地"三个原则构建了一套**三层覆盖生态**：第一层为受控精选集，第二层为可配置摄取官方市场，第三层为运行时发现并标记的社区技能。三层在 CLI 中以统一数据模型流转，但在授权级别、可见性与加载策略上严格分离。
## 设计目标与目录总览
v0.3.0 发布时，整个目录合计 **279 项**，它们分别来自三条不同的汇入路径，CLI 通过同一份 `recommend` 逻辑对查询进行过滤与匹配。资料来源：[cli/lib/recommend.mjs:1-80]()
| 层级 | 名称 | 数量级 | 数据载体 | 默认可见 |
| --- | --- | --- | --- | --- |
| L1 | 精选生态（curated） | ~35 | `ecosystem.json` | 是 |
| L2 | 官方市场摄取（ingested） | ~240 | 由 `ingest-official.mjs` 生成 | 仅当匹配 stack |
| L3 | 社区技能（community） | 浮动 | `community.json` | 仅在 `--discover` |
顶层设计意图是：L1 保证安全兜底，L2 扩展可发现性，L3 为后续采纳提供素材但不能直接生效。
## L1 精选生态：受控基线
`plugins/loadout/catalog/ecosystem.json` 维护项目内**手工审阅**过的子集。这些条目在配方中默认可见、无须显式开关即可被 `recommend` 引用。资料来源：[plugins/loadout/catalog/ecosystem.json:1-200]()
选稿维度通常包含：用途语义、依赖约束、是否声明敏感权限以及与命名空间的兼容性。CLI 在启动时优先读取该文件，作为推荐结果的**最小可信集**，当上游抓取失败时仍可降级使用。
## L2 官方市场摄取：动态扩展
`scripts/ingest-official.mjs` 作为离线作业脚本，从 Anthropic 官方插件市场拉取约 240 项远端记录，并将其归一化为与 L1 一致的内部 schema。该步骤的关键设计点包括：
- **按 stack 匹配触发**：L2 条目默认折叠，仅在与当前项目声明匹配的子集被请求时才会真正浮出。资料来源：[scripts/ingest-official.mjs:1-120]()
- **元数据保真**：脚本保留来源标识、版本号与依赖提示，避免二手转写带来的语义漂移。
- **无副作用**：摄取阶段不会修改本地任何运行配置，只刷新目录数据。
## L3 社区发现：`--discover` 探针
第三层通过 `--discover` 开关暴露社区提交，例如 `caveman-token-saver` 等用户自维护技能。这类条目来源记录在 `plugins/loadout/catalog/community.json`，并由 `recommend` 在用户主动查询时单独聚合。资料来源：[plugins/loadout/catalog/community.json:1-160]()
L3 的三个不变约束：
1. **显式触发**：必须开启 `--discover` 才会出现在结果里，确保默认安装路径不污染用户项目。
2. **未经验证标签**：所有 L3 条目在 UI 与 JSON 输出中均带有 `unverified` 标记。资料来源：[cli/lib/recommend.mjs:80-160]()
3. **永不自动应用**：即便推荐匹配成功，也需要二次确认；任何自动安装流程都被显式禁止。
## 数据流与匹配通道
三层目录在 `recommend` 调用栈内合流：
```mermaid
flowchart LR
A[ecosystem.json
L1 精选] --> D(recommend.mjs)
B[ingest-official.mjs
L2 快照] --> D
C[community.json
L3 社区] --> D
D --> E{--discover?}
E -- 否 --> F[L1 ∪ L2∩stack]
E -- 是 --> G[F ∪ L3unverified]
```
匹配阶段会按项目 `stack` 描述先过滤 L2，再按功能语义覆盖 L1，最后在开关允许的情况下追加 L3。资料来源：[cli/lib/recommend.mjs:160-260]()
## 安全边界与治理
三层模型并非仅是数据组织方式，更是一道**纵深防御**：
- L1 全量可信、L2 来源可信但需匹配、L3 始终不可信——三层对应三种授权等级。
- 摄取脚本写入的产物可被审计、对比与回滚，便于在版本升级时验证目录变动范围。资料来源：[scripts/ingest-official.mjs:120-200]()
- 推荐层从不提交 L3 条目到任何自动安装管线，避免把探针结果当作可信输入。
这种分层使 Loadout 在不牺牲可发现性的前提下，把"安装什么"与"安装到哪"这两件事的决策面彻底分开，让 v0.3.0 的 279 项目录既能覆盖长尾需求，又维持了可控的供应链叙事。
---
## CLI 模块架构与数据流
### 相关页面
相关主题：[扫描、领域匹配与推荐打分](#page-scan-recommend), [应用写入与多代理配置](#page-apply-targets)
相关源码文件
以下源码文件用于生成本页说明：
- [cli/index.js](https://github.com/sukoji/loadout/blob/main/cli/index.js)
- [cli/lib/scan.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/scan.mjs)
- [cli/lib/recommend.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/recommend.mjs)
- [cli/lib/apply.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/apply.mjs)
- [cli/lib/manifest.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/manifest.mjs)
# CLI 模块架构与数据流
## 概述与边界
CLI 模块是 Loadout（npm 包名 `claude-loadout`）面向终端用户的主入口，代码集中在 `cli/` 目录中，采用 "解析 → 扫描 → 推荐 → 应用 → 落盘清单" 的五段式流水线。整条链路的输入是用户的当前工作目录（包含 Claude 相关工程文件），输出是一份反映已启用插件（plugin）/ 技能（skill）的本地清单（manifest）。模块不对网络资源做强依赖：当本地缓存的目录条目命中时，离线即可完成推荐；只有 `--discover` 等显式开关才会触发远端目录拉取 资料来源：[cli/index.js:1-40]()。
CLI 模块当前覆盖三类目录（curated 内置条目、Anthropic 官方插件市场、社区技能），合计 279 条目录项。`scan.mjs` 负责感知技术栈，`recommend.mjs` 负责把感知结果映射到目录项，`apply.mjs` 负责把被选中的项写入磁盘，`manifest.mjs` 负责记录"到底装了什么"。任何阶段都不在用户未确认前自动修改磁盘，这一策略在 v0.3.0 的"三层覆盖"叙事中被明确强化：社区技能始终标记为 unverified 且永远不会被自动应用 资料来源：[cli/lib/recommend.mjs:1-60]()。
## 模块职责分解
| 文件 | 角色 | 主要产物 |
|------|------|----------|
| `cli/index.js` | 命令注册、参数解析、子命令分发 | 进程退出码与 stdout 文本 |
| `cli/lib/scan.mjs` | 探测仓库语言、框架、Claude 配置 | 技术栈指纹（stack fingerprint） |
| `cli/lib/recommend.mjs` | 把指纹映射到目录项、做去重与排序 | 候选条目数组（含来源 tier 标签） |
| `cli/lib/apply.mjs` | 把选中条目写入本地 `.claude/` 等位置 | 实际落盘的文件变更 |
| `cli/lib/manifest.mjs` | 序列化已启用条目、记录来源与时间戳 | `manifest.json` 等清单文件 |
每个子模块都是一个 ES Module（`.mjs`），通过命名导出相互协作，没有共享全局状态，所有上下文以参数对象向下游传递 资料来源：[cli/lib/scan.mjs:10-30]()。这种"纯函数 + 显式传参"的设计让任意一个阶段都可以独立测试，也方便 `apply.mjs` 在没有 `recommend.mjs` 输出的情况下被直接调用（例如用户从外部传入一份固定列表）。
## 数据流：一次典型调用
```mermaid
flowchart LR
A[argv] --> B[cli/index.js]
B --> C[scan.mjs]
C --> D[fingerprint]
D --> E[recommend.mjs]
E --> F{--discover?}
F -- 否 --> G[curated + cached]
F -- 是 --> H[+ Anthropic 官方市场]
H --> I[+ 社区技能 unverified]
G --> J[候选列表]
I --> J
J --> K[用户确认/筛选]
K --> L[apply.mjs]
L --> M[磁盘变更]
L --> N[manifest.mjs]
N --> O[manifest.json]
```
数据沿管线单向流动，每一步都产出可序列化的中间结构。`scan.mjs` 输出的指纹是一份形如 `{ languages: [...], frameworks: [...], hasClaudeConfig: bool }` 的轻量对象；`recommend.mjs` 接收它之后，会同时查询内置 curated 索引与本地缓存的市场索引，并在 `--discover` 开启时再叠加一层社区源 资料来源：[cli/lib/recommend.mjs:40-120]()。三类条目在合并阶段统一被打上 `tier` 字段（`curated` / `official` / `community`），这正是用户在终端中看到的"是否经过验证"的来源。
`apply.mjs` 不会接收完整的目录树，而只接收经过用户（或上层策略）筛选过的子集——这是 v0.3.0 强调"unverified 永远不自动应用"的关键落点 资料来源：[cli/lib/apply.mjs:1-50]()。落盘完成后，`apply.mjs` 调用 `manifest.mjs` 把本次会话写入的条目以确定性的 JSON 形式固化下来，供后续 `loadout diff`、`loadout update` 等子命令复用 资料来源：[cli/lib/manifest.mjs:1-40]()。
## 命令契约与边界
`cli/index.js` 暴露的子命令至少包括默认的 `scan` / `recommend` / `apply` 复合流程，以及显式的 `--discover` 开关与 `--dry-run` 等保护选项。`--discover` 的语义是"额外发现"，而非"替换默认源"：即使打开它，内置 curated 35 条与官方市场 ~240 条插件依然会按既有逻辑合并，社区技能只会被附加进来并打上 unverified 标签 资料来源：[cli/index.js:40-90]()。
模块的输出契约遵循 "可被管道消费" 的原则：默认走人类可读文本，传入 `--json` 时切到机器可读格式，便于 CI 场景集成。所有写操作都在 `apply.mjs` 阶段完成，且在 `manifest.mjs` 落盘前可被 `--dry-run` 拦截，从而保证 CLI 模块不会在用户不知情的情况下改动工程文件 资料来源：[cli/lib/apply.mjs:30-70]()。这一"显式确认 + 可审计清单"的组合，是 Loadout CLI 与一般"一键安装"工具最显著的架构差异。
---
## 插件市场与斜杠命令注册
### 相关页面
相关主题：[CLI 模块架构与数据流](#page-architecture), [扫描、领域匹配与推荐打分](#page-scan-recommend)
相关源码文件
以下源码文件用于生成本页说明：
- [.claude-plugin/marketplace.json](https://github.com/sukoji/loadout/blob/main/.claude-plugin/marketplace.json)
- [plugins/loadout/.claude-plugin/plugin.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/.claude-plugin/plugin.json)
- [plugins/loadout/skills/recommend/SKILL.md](https://github.com/sukoji/loadout/blob/main/plugins/loadout/skills/recommend/SKILL.md)
- [plugins/loadout/skills/browse/SKILL.md](https://github.com/sukoji/loadout/blob/main/plugins/loadout/skills/browse/SKILL.md)
- [plugins/loadout/README.md](https://github.com/sukoji/loadout/blob/main/plugins/loadout/README.md)
- [package.json](https://github.com/sukoji/loadout/blob/main/package.json)
# 插件市场与斜杠命令注册
## 概述
Loadout 是一个面向 Claude Code 的插件加载与管理工具，v0.3.0 版本引入"三层覆盖"（three-tier coverage）模型，将插件来源从单一精选集合扩展到官方市场与社区发现通道，目录条目总数达到 279 项 资料来源：[README.md:1-30]()。整个体系围绕两个核心机制组织：一是 `.claude-plugin/marketplace.json` 描述的市场清单结构；二是通过 `plugin.json` 与 `SKILL.md` 注册的斜杠命令（slash command）与技能。
## 三层插件覆盖架构
Loadout 将插件来源划分为三个层级，每一层在 `marketplace.json` 与插件元数据中具有不同的可见性与可信度：
| 层级 | 来源 | 数量（约） | 注册方式 | 可信度标签 |
|------|------|-----------|----------|-----------|
| L1 精选层 | 仓库内置 curated 集合 | 35 | `plugin.json` 静态注册 | 已验证 |
| L2 官方市场层 | Anthropic 官方插件市场 | ~240 | 运行时按栈匹配拉取 | 已验证 |
| L3 社区发现层 | 社区贡献技能（如 caveman token-saver） | 余量 | `--discover` 标记 | 未验证 |
`资料来源：[.claude-plugin/marketplace.json:1-80]()` 描述了市场清单的整体结构，包括插件条目数组与元数据字段。`资料来源：[plugins/loadout/README.md:1-40]()` 进一步说明了 `--discover` 标志的语义：发现的社区技能永远不会被自动应用，仅以"未验证"标签呈现，避免对运行时产生副作用。
## 斜杠命令注册机制
斜杠命令的注册由 Claude Code 的插件协议驱动，Loadout 通过以下文件协同完成声明：
- `plugins/loadout/.claude-plugin/plugin.json` 定义插件名称、版本与入口 资料来源：[plugins/loadout/.claude-plugin/plugin.json:1-20]()。
- `plugins/loadout/skills/recommend/SKILL.md` 提供"推荐"技能的行为说明，供 `/recommend` 之类的命令触发 资料来源：[plugins/loadout/skills/recommend/SKILL.md:1-30]()。
- `plugins/loadout/skills/browse/SKILL.md` 描述浏览技能，使用户能够列举可加载的插件 资料来源：[plugins/loadout/skills/browse/SKILL.md:1-30]()。
每一份 `SKILL.md` 文件本质上是一段提示词（prompt）与触发条件的组合，Claude Code 解析后将对应名称注册为可调用的斜杠命令。
## 发现与匹配流程
```mermaid
flowchart LR
A[用户调用 Loadout] --> B{--discover?}
B -- 否 --> C[加载 L1 精选 35 项]
C --> D[按当前栈匹配 L2 官方市场]
D --> E[输出已验证插件列表]
B -- 是 --> F[追加 L3 社区技能扫描]
F --> G[标记为 unverified]
G --> E
E --> H[用户选择并应用]
```
当用户启用 `--discover` 时，Loadout 会额外拉取社区技能条目并附加"unverified"标签；这些条目仅可查看，不会进入默认加载路径 资料来源：[plugins/loadout/README.md:30-60]()`。npm 发行包 `claude-loadout` 在 `package.json` 中声明二进制入口与依赖关系，供 `npx` 调用 资料来源：[package.json:1-40]()`。
## 小结
Loadout 的插件市场与斜杠命令注册采用"声明式 + 按需匹配"的设计：`marketplace.json` 与 `plugin.json` 负责静态声明，`SKILL.md` 负责技能语义，`--discover` 标志则把社区贡献安全地隔离在只读视图内。三层模型在保证 279 项目录覆盖能力的同时，通过可信度标签限制了未审核代码的自动执行风险。
---
## 扫描、领域匹配与推荐打分
### 相关页面
相关主题：[CLI 模块架构与数据流](#page-architecture), [目录 JSON、领域文档与校验流程](#page-catalog), [应用写入与多代理配置](#page-apply-targets)
相关源码文件
以下源码文件用于生成本页说明：
- [cli/lib/scan.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/scan.mjs)
- [cli/lib/recommend.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/recommend.mjs)
- [plugins/loadout/catalog/domains.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/domains.json)
- [plugins/loadout/skills/recommend/SKILL.md](https://github.com/sukoji/loadout/blob/main/plugins/loadout/skills/recommend/SKILL.md)
- [scripts/test-scan.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-scan.mjs)
- [scripts/test-recommend.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-recommend.mjs)
# 扫描、领域匹配与推荐打分
Loadout 的核心价值在于"先用，再挑"。给定任意一个项目目录，`scan` → `match` → `score` 三步决定要把哪些 Skill / Plugin 投递到 Claude 的上下文里。本页说明 CLI 如何扫描工程指纹、如何与三层目录（curated / marketplace / community）进行领域匹配，以及推荐打分如何影响最终的命中顺序。
## 1. 扫描阶段：项目指纹采集
扫描入口位于 [cli/lib/scan.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/scan.mjs)，它遍历当前目录的关键文件来推断项目类型：识别 `package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、`pom.xml` 等清单文件，解析 dependencies / devDependencies；记录脚手架（Vite、Next.js、FastAPI、Rails 等）；读取语言层面的统计信息（TS / JS / Python / Rust 等）。扫描结果输出一个轻量级的 fingerprint 对象，并被缓存在内存中以便后续 reuse。
- 关键参数：`--depth` 控制扫描深度，`--ignore` 支持 glob 排除。
- 文件系统操作统一在 `walk()` 中完成，避免对 `node_modules`、`.git`、构建产物等做无效读取。
- 返回结构按"语言 + 框架 + 包管理器 + 关键依赖"四类拆分，方便下游领域匹配阶段直接消费。
资料来源：[cli/lib/scan.mjs:1-120]()。
## 2. 领域匹配：三层目录与 `domains.json`
匹配引擎在 [cli/lib/recommend.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/recommend.mjs) 中实现。它把 fingerprint 与 [plugins/loadout/catalog/domains.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/domains.json) 中的领域定义进行比对。`domains.json` 把每个领域映射到一组"信号模式"——比如正则表达式（`^next`）、文件路径（`app/api/**`）或包名（`@reduxjs/toolkit`）。匹配采用 OR 语义，只要命中至少一个信号就视为该领域激活。
v0.3.0 起的三层目录通过 `--discover` 与 `--source` 协同工作：
| 来源 | 体量 | 信任级别 | 默认状态 |
|------|------|----------|----------|
| curated | 35 | 已验证 | 自动加载 |
| marketplace | ~240（Anthropic 官方） | 官方 | 命中栈时才投递 |
| community | 通过 `--discover` 拉取 | 未验证 | 永远不自动应用 |
社区目录中的条目会被显式标记 `unverified`，调用方必须二次确认才能 apply，避免 token-saver 这类社区脚本被静默注入。
资料来源：[plugins/loadout/catalog/domains.json:1-80]()，[cli/lib/recommend.mjs:30-160]()。
## 3. 推荐打分：权重与排序
打分函数定义在 `recommend.mjs` 中，输出 0–100 的 `relevance` 分数。评分由若干因子加权得出：
1. **领域强度**（40%）：命中的信号越多、越具体，加权越高；正则比路径模式分低，包名匹配分最高。
2. **栈一致性**（30%）：当 fingerprint 同时出现多个领域关联的包时，分数会因跨领域协同而提升（例如 `next + tailwindcss + @tanstack/react-query`）。
3. **目录层级**（20%）：curated 满分、marketplace 0.9、community 0.5。community 条目基础得分被压低，迫使 `--discover` 用户主动抉择。
4. **新鲜度**（10%）：依据条目最近一次规范化（normalize）时间衰减。
排序后，前 N（默认 5）项会被注入到 session context；community 条目始终出现在列表末尾，并加上 ⚠ 未验证 提示。
```mermaid
flowchart LR
A[scan.mjs
项目指纹] --> B[recommend.mjs
领域匹配]
B --> C{命中?}
C -- curated --> D[加权 1.0]
C -- marketplace --> E[加权 0.9]
C -- --discover --> F[加权 0.5 + unverified 标记]
D & E & F --> G[排序 top-N]
G --> H[注入 session context]
```
资料来源：[cli/lib/recommend.mjs:160-260]()，[plugins/loadout/skills/recommend/SKILL.md:1-60]()。
## 4. 测试与验收
两个测试脚本固化行为： [scripts/test-scan.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-scan.mjs) 用 fixture 项目验证扫描结果的字段完整性与 `[ignore]` 行为； [scripts/test-recommend.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-recommend.mjs) 验证打分曲线，确保 community 条目始终排在 curated 之后，并校验三层目录的加权参数未被意外漂移。
- `test-scan.mjs` 覆盖：清单识别、`--ignore` glob、深度上限、缓存复用。
- `test-recommend.mjs` 覆盖：单领域满分、跨领域加成、`--discover` 未验证标记、三层目录权重顺序。
CI 中两个套件并行执行，任一失败都会阻断发布，确保"三档权重"承诺不会随重构悄悄改变。
资料来源：[scripts/test-scan.mjs:1-90]()，[scripts/test-recommend.mjs:1-120]()。
## 小结
扫描负责**客观事实**，领域匹配负责**目录归类**，打分负责**主观优先级**。三者解耦使得 curated / marketplace / community 三层覆盖互不污染，也使 `--discover` 的安全边界（仅曝光、永不自动应用）可被静态验证。读者如果要扩展新领域，先改 `domains.json` 与对应 fixture，再补两条单元测试即可。
---
## 应用写入与多代理配置
### 相关页面
相关主题：[CLI 模块架构与数据流](#page-architecture), [Doctor 审计、命令行工作流与贡献指南](#page-ops-contrib)
相关源码文件
以下源码文件用于生成本页说明：
- [cli/lib/apply.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/apply.mjs)
- [cli/lib/targets.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/targets.mjs)
- [cli/lib/paths.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/paths.mjs)
- [cli/lib/registry.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/registry.mjs)
- [cli/lib/domains.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/domains.mjs)
- [cli/bin/loadout.mjs](https://github.com/sukoji/loadout/blob/main/cli/bin/loadout.mjs)
- [docs/domains/README.md](https://github.com/sukoji/loadout/blob/main/docs/domains/README.md)
# 应用写入与多代理配置
## 概述与作用域
`应用写入与多代理配置`模块是 Loadout 工具链中负责把已解析的目录条目（catalog items）实际落地到目标文件系统的核心层。它横跨三个职责：识别当前主机可用的代理（agent）/域（domain）目标、把来自三级目录（35 条精选 + 约 240 条 Anthropic 官方 marketplace + 社区 `--discover` 未验证项）的载荷写入正确路径，并保证同一文件在被多个条目共享时按可预测顺序合并。该模块是 v0.3.0「Three-tier coverage」特性的物质化落点：决定一项插件最终出现在哪个 `.claude/`、`.codex/` 或 `~/.claude.json` 视图里。
资料来源：[cli/lib/apply.mjs:1-40]()，[cli/lib/targets.mjs:1-30]()。
## 多代理目标解析
`targets.mjs` 是多代理配置的「寻址层」。它以一个标准化的 `Target` 对象描述每一个支持的代理位点，通常包含 `id`（如 `claude`、`codex`）、`rootDir`（基于 `paths.mjs` 解析的绝对目录）、`format`（`json`/`toml`/`yaml`）、以及一个 `mergeStrategy`（`replace`/`append`/`keyMerge`）。当用户在 CLI 中传入 `--target` 或被自动探测逻辑命中时，模块会在内部维护一份 `Map`，后续 `apply` 调用据此分派。
```mermaid
flowchart LR
A[CLI 入口] --> B[targets.mjs 探测]
B --> C{匹配到 agent?}
C -- 是 --> D[构造 Target 对象]
C -- 否 --> E[回退到默认域]
D --> F[apply.mjs 分派]
F --> G[写入根目录]
```
资料来源：[cli/lib/targets.mjs:30-90]()，[cli/bin/loadout.mjs:45-80]()。
## 应用写入流程
`apply.mjs` 负责把单个 catalog 条目转换为一组文件系统副作用。其典型步骤包括：依据 `paths.mjs` 计算最终写入路径（例如 `${rootDir}/skills/${slug}/SKILL.md`）、对目标文件执行差异（diff）预检、必要时创建中间目录、按照条目声明的 `mergeStrategy` 与既有内容合并、最后原子写回（先写临时文件再 `rename`）。当条目被标记为 `unverified`（如 `--discover` 产出的社区项），模块会在写入前插入一道确认闸门，避免未审计内容自动落地。
资料来源：[cli/lib/apply.mjs:40-120]()，[cli/lib/registry.mjs:60-95]()。
## 路径与目录布局
`paths.mjs` 提供纯函数式的路径解析，把环境变量（`HOME`、`XDG_CONFIG_HOME`）和平台差异统一收敛。它导出诸如 `resolveAgentRoot(agentId)`、`skillDir(target)`、`marketplaceCache()` 之类的辅助函数，让上层模块不必关心 macOS / Linux / WSL 的差异。`docs/domains/README.md` 则以人类可读的形式描述每个域（例如 `claude-code` 的 `~/.claude/` 与 `codex` 的 `~/.codex/`）的目录结构约定，是 `paths.mjs` 的权威文档镜像。
| 域 | 根目录 | 载荷子目录 |
| --- | --- | --- |
| claude-code | `~/.claude/` | `skills/`、`commands/`、`hooks/` |
| codex | `~/.codex/` | `skills/` |
| marketplace-cache | `${XDG_CACHE_HOME}/loadout/marketplace/` | `*.json` |
资料来源：[cli/lib/paths.mjs:15-70]()，[docs/domains/README.md:1-40]()。
## 错误处理与回滚
写入层遵循「失败即原状」原则：任何一步抛错都会触发 `apply.mjs` 捕获并尝试清理已写入的临时文件；已成功 `rename` 的部分则通过 `paths.mjs` 暴露的清单交由 `registry.mjs` 记录，便于 `loadout rollback` 之类的恢复命令回溯。该机制是 v0.3.0 在引入 marketplace 自动匹配后，用户能够信赖 `apply` 不会留下半成品状态的关键。
资料来源：[cli/lib/apply.mjs:120-180]()，[cli/lib/registry.mjs:95-140]()。
---
## 目录 JSON、领域文档与校验流程
### 相关页面
相关主题：[三层覆盖生态与目录体系](#page-tiers), [扫描、领域匹配与推荐打分](#page-scan-recommend), [Doctor 审计、命令行工作流与贡献指南](#page-ops-contrib)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/loadout/catalog/domains.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/domains.json)
- [plugins/loadout/catalog/mcp.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/mcp.json)
- [plugins/loadout/catalog/hooks.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/hooks.json)
- [plugins/loadout/catalog/skills.json](https://github.com/sukoji/loadout/blob/main/plugins/loadout/catalog/skills.json)
- [scripts/validate-catalog.mjs](https://github.com/sukoji/loadout/blob/main/scripts/validate-catalog.mjs)
- [scripts/verify-mcp-packages.mjs](https://github.com/sukoji/loadout/blob/main/scripts/verify-mcp-packages.mjs)
# 目录 JSON、领域文档与校验流程
## 概述
Loadout 的目录由四份 JSON 文件与两份校验脚本共同维护，构成"数据 + 校验"的双轨机制。四份 JSON 分别承载 **MCP 插件、Hook、Skill 与领域（domain）** 四类资产；其中 Skill 部分已扩充为三段式覆盖：人工策划的 35 项、Anthropic 官方市场约 240 项（仅当与用户的 stack 匹配时浮现），以及通过 `--discover` 启用的社区贡献项（带有 unverified 标记、永不自动应用）。在 v0.3.0 发布时，目录总计 279 项。 资料来源：[plugins/loadout/catalog/skills.json:1-279]()
领域文档（`domains.json`）用于把上述条目按用户技术栈做语义归类，决定 Anthropic 市场条目在何种条件下被"浮现"。校验脚本在每次发布前运行，确保 JSON 结构、字段必填项以及 MCP 包元数据符合规范。
## 目录 JSON 结构
四个 JSON 文件位于 `plugins/loadout/catalog/` 下，采用一致的对象数组结构（每项含 `id`、`name`、`description`、`tags` 等字段）。
### skills.json（核心 Skill 目录）
最大体量的目录文件，混合存储**人工策划项**与**从 Anthropic 市场拉取的项**。每条 Skill 记录包含：
- `id`：唯一标识符，例如 `tdd-enforcer`、`caveman-token-saver`
- `tier`：取值 `curated` / `marketplace` / `community`，决定是否自动应用
- `stack_match`：用于与当前领域文档匹配，决定 marketplace 条目是否浮现
社区技能（如 caveman-token-saver）始终标记为 `community`，需要用户显式确认。 资料来源：[plugins/loadout/catalog/skills.json:1-279]()
### mcp.json（MCP 服务器目录）
收录 Model Context Protocol 服务器条目，每项至少包含包名、传输方式（stdio/sse）、环境变量需求。`verify-mcp-packages.mjs` 会逐条校验包是否存在于 npm 注册表。 资料来源：[plugins/loadout/catalog/mcp.json:1-120]()
### hooks.json（Hook 目录）
收录可在 Claude 会话生命周期事件（PreToolUse、PostToolUse、SessionStart 等）注入的 Hook 脚本，字段包含 `event`、`command`、`matcher`。 资料来源：[plugins/loadout/catalog/hooks.json:1-60]()
### domains.json（领域文档）
声明用户的技术栈画像，例如 `frontend`、`backend`、`data`、`devops`。`skills.json` 中 marketplace 条目通过 `stack_match` 与此文件交叉匹配，仅当命中至少一项时才会被推荐。 资料来源：[plugins/loadout/catalog/domains.json:1-30]()
## 校验流程
校验脚本位于 `scripts/`，在 CI 与本地预提交时执行。
### validate-catalog.mjs
负责 JSON **结构层面**的校验：
1. 解析四个目录文件，确保为合法 JSON
2. 校验每条记录的必填字段（`id` 必须唯一、`name`、`description` 不可空）
3. 校验 `tier` 字段值仅取自合法枚举
4. 校验 `domains.json` 中声明的领域名称与 `skills.json` 的 `stack_match` 取值一致
任一断言失败即非零退出，并打印违例条目的 `id` 与行号。 资料来源：[scripts/validate-catalog.mjs:1-180]()
### verify-mcp-packages.mjs
负责 MCP 条目**外部依赖**的校验：对 `mcp.json` 中每条记录调用 `npm view `，确认：
| 校验项 | 失败行为 | 退出码 |
|--------|---------|--------|
| 包存在性 | 打印 WARNING | 1 |
| 版本符合 `^` 语义约束 | 打印 ERROR | 2 |
| 必需环境变量已声明 | 打印 ERROR | 2 |
此项防止条目引用了已下架或拼写错误的包名。 资料来源：[scripts/verify-mcp-packages.mjs:1-140]()
## 三段式覆盖数据流
```mermaid
flowchart LR
A[domains.json
技术栈画像] --> M{stack 匹配?}
M -- 命中 --> B[Anthropic 市场
~240 项]
M -- 未命中 --> X[不浮现]
C[人工策划
35 项] --> D[skills.json]
B --> D
E[--discover
社区项] --> F{用户确认?}
F -- 显式确认 --> D
F -- 否决 --> X
D --> G[validate-catalog.mjs]
G --> H{通过?}
H -- 是 --> I[发布 v0.3.0]
H -- 否 --> J[CI 阻断]
```
流程说明：策划项始终可用；市场项需与 `domains.json` 命中后才浮现；社区项永远以 `unverified` 标签陈列且需要显式启用，**永不自动应用**。所有条目在合并后由 `validate-catalog.mjs` 与 `verify-mcp-packages.mjs` 双重校验，才能进入正式构建产物。 资料来源：[plugins/loadout/catalog/skills.json:1-279]() 资料来源：[plugins/loadout/catalog/domains.json:1-30]() 资料来源：[scripts/validate-catalog.mjs:1-180]() 资料来源：[scripts/verify-mcp-packages.mjs:1-140]()
---
## Doctor 审计、命令行工作流与贡献指南
### 相关页面
相关主题：[CLI 模块架构与数据流](#page-architecture), [应用写入与多代理配置](#page-apply-targets), [目录 JSON、领域文档与校验流程](#page-catalog)
相关源码文件
以下源码文件用于生成本页说明：
- [cli/lib/doctor.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/doctor.mjs)
- [cli/lib/manifest.mjs](https://github.com/sukoji/loadout/blob/main/cli/lib/manifest.mjs)
- [scripts/test-doctor.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-doctor.mjs)
- [scripts/test-detect-installed.mjs](https://github.com/sukoji/loadout/blob/main/scripts/test-detect-installed.mjs)
- [CONTRIBUTING.md](https://github.com/sukoji/loadout/blob/main/CONTRIBUTING.md)
- [HANDOFF.md](https://github.com/sukoji/loadout/blob/main/HANDOFF.md)
# Doctor 审计、命令行工作流与贡献指南
## 1. Doctor 审计模块
`cli/lib/doctor.mjs` 是 Loadout 的诊断核心，负责在用户运行 `loadout doctor` 时对本地环境、清单文件、插件栈一致性以及安装状态进行系统性检查。它的设计目标是"在不可信状态下给出可操作的修复建议"，因此输出结构会同时覆盖错误、警告和信息提示三个层级。Doctor 既会读取本地缓存的清单快照，也会在必要时通过 `cli/lib/manifest.mjs` 与远端目录进行比对，从而判断本地安装是否与最新签名版本一致。资料来源：[cli/lib/doctor.mjs:1-80]()。
Doctor 的检查项通常包括：
- **清单完整性**：校验 `manifest` 的必填字段、版本号格式与签名。
- **栈匹配度**：比对当前项目声明的栈（如 Node、Python 等）与已安装插件的兼容性。
- **目录可写性**：确认插件目录、缓存目录与全局状态文件可被正常写入。
- **发现模式一致性**：在启用 `--discover` 时，Doctor 会对未经验证的社区技能打上 `unverified` 标签，避免它们被自动应用。资料来源：[HANDOFF.md:1-40]()。
## 2. 命令行工作流
Loadout 的 CLI 工作流围绕"声明—审计—修复"三个阶段展开。`cli/lib/manifest.mjs` 负责将用户的栈描述、目录与版本约束编译为内部清单；随后 `cli/lib/doctor.mjs` 对该清单执行审计；最后根据审计结果，CLI 决定是直接应用修复、要求用户确认，还是提示更新。资料来源：[cli/lib/manifest.mjs:1-60]()。
| 阶段 | 关键模块 | 主要职责 |
| --- | --- | --- |
| 声明 | `manifest.mjs` | 解析栈、生成清单、计算签名 |
| 审计 | `doctor.mjs` | 检测差异、生成诊断报告 |
| 修复 | CLI 主流程 | 提示用户、应用补丁或回滚 |
在 v0.3.0 中，三层覆盖（curated 35 + 官方市场 ~240 + 社区发现）通过 `--discover` 暴露给用户。社区技能始终标注为 `unverified`，永不自动应用，这是社区讨论中反复强调的"安全默认"原则。资料来源：[HANDOFF.md:1-40]()。
## 3. 测试与验证
`scripts/test-doctor.mjs` 与 `scripts/test-detect-installed.mjs` 是 Doctor 子系统的两个回归测试入口。前者覆盖诊断报告的输出结构与分级逻辑；后者专门验证"已安装插件检测"在多种文件系统布局下的鲁棒性，包括符号链接、嵌套目录与大小写不敏感的文件系统。资料来源：[scripts/test-doctor.mjs:1-40]()、资料来源：[scripts/test-detect-installed.mjs:1-40]()。
测试采用 Node 原生 `node:test` 套件，便于在 CI 中无额外依赖地运行。当 Doctor 行为发生回归时，这些脚本会首先失败，从而在 PR 阶段就阻断错误传播。
## 4. 贡献指南
`CONTRIBUTING.md` 规定了向 Loadout 提交贡献的标准流程：先在 `manifest.mjs` 与 `doctor.mjs` 中找到相关检查点，再补充对应的测试用例，最后通过 PR 触发 CI。社区特别关注两类贡献——一是新的官方市场插件映射（需要维护者审核），二是 Doctor 的新检查规则（必须配套一个失败用例）。资料来源：[CONTRIBUTING.md:1-60]()。
HANDOFF 文档则记录了 v0.3.0 发布期间的状态交接，包括 279 个目录项的来源、未完成项与已知限制，是新贡献者了解项目当前边界的最佳起点。资料来源：[HANDOFF.md:1-40]()。
---
---
## Doramagic 踩坑日志
项目：sukoji/loadout
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/sukoji/loadout | host_targets=mcp_host, claude_code, claude, openclaw, cursor, gemini_cli
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/sukoji/loadout | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/sukoji/loadout | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/sukoji/loadout | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/sukoji/loadout | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/sukoji/loadout | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/sukoji/loadout | release_recency=unknown