项目定位与基本介绍

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。

三层覆盖架构

合计 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。

设计目标与目录总览

v0.3.0 发布时，整个目录合计 279 项，它们分别来自三条不同的汇入路径，CLI 通过同一份 recommend 逻辑对查询进行过滤与匹配。资料来源：cli/lib/recommend.mjs:1-80

顶层设计意图是：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 调用栈内合流：

flowchart LR
    A[ecosystem.json<br/>L1 精选] --> D(recommend.mjs)
    B[ingest-official.mjs<br/>L2 快照] --> D
    C[community.json<br/>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 模块是 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。

模块职责分解

每个子模块都是一个 ES Module（.mjs），通过命名导出相互协作，没有共享全局状态，所有上下文以参数对象向下游传递 资料来源：cli/lib/scan.mjs:10-30。这种"纯函数 + 显式传参"的设计让任意一个阶段都可以独立测试，也方便 apply.mjs 在没有 recommend.mjs 输出的情况下被直接调用（例如用户从外部传入一份固定列表）。

数据流：一次典型调用

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 与一般"一键安装"工具最显著的架构差异。

概述

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 与插件元数据中具有不同的可见性与可信度：

资料来源：.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 解析后将对应名称注册为可调用的斜杠命令。

发现与匹配流程

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 项目录覆盖能力的同时，通过可信度标签限制了未审核代码的自动执行风险。

1. 扫描阶段：项目指纹采集

扫描入口位于 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 中实现。它把 fingerprint 与 plugins/loadout/catalog/domains.json 中的领域定义进行比对。domains.json 把每个领域映射到一组"信号模式"——比如正则表达式（^next）、文件路径（app/api/**）或包名（@reduxjs/toolkit）。匹配采用 OR 语义，只要命中至少一个信号就视为该领域激活。

v0.3.0 起的三层目录通过 --discover 与 --source 协同工作：

社区目录中的条目会被显式标记 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 条目始终出现在列表末尾，并加上 ⚠ 未验证 提示。

flowchart LR
    A[scan.mjs<br/>项目指纹] --> B[recommend.mjs<br/>领域匹配]
    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 用 fixture 项目验证扫描结果的字段完整性与 [ignore] 行为； 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，再补两条单元测试即可。

概述与作用域

应用写入与多代理配置模块是 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<agentId, Target>，后续 apply 调用据此分派。

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 的权威文档镜像。

资料来源：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。

概述

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 <package>，确认：

此项防止条目引用了已下架或拼写错误的包名。 资料来源：scripts/verify-mcp-packages.mjs:1-140

三段式覆盖数据流

flowchart LR
    A[domains.json<br/>技术栈画像] --> M{stack 匹配?}
    M -- 命中 --> B[Anthropic 市场<br/>~240 项]
    M -- 未命中 --> X[不浮现]
    C[人工策划<br/>35 项] --> D[skills.json]
    B --> D
    E[--discover<br/>社区项] --> 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

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。

在 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。

Pitfall Log / 踩坑日志

项目：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