# https://github.com/scagogogo/npm-skills 项目说明书

生成时间：2026-07-05 05:13:58 UTC

## 目录

- [项目概述与四种集成方式](#page-1)
- [Go SDK API 参考与代码示例](#page-2)
- [CLI 命令与 MCP Server 工具](#page-3)
- [镜像源、代理、认证与部署运维](#page-4)

<a id='page-1'></a>

## 项目概述与四种集成方式

### 相关页面

相关主题：[Go SDK API 参考与代码示例](#page-2), [CLI 命令与 MCP Server 工具](#page-3), [镜像源、代理、认证与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/scagogogo/npm-skills/blob/main/README.md)
- [README_zh.md](https://github.com/scagogogo/npm-skills/blob/main/README_zh.md)
- [skills/npm/SKILL.md](https://github.com/scagogogo/npm-skills/blob/main/skills/npm/SKILL.md)
- [.claude-plugin/plugin.json](https://github.com/scagogogo/npm-skills/blob/main/.claude-plugin/plugin.json)
- [.claude-plugin/marketplace.json](https://github.com/scagogogo/npm-skills/blob/main/.claude-plugin/marketplace.json)
- [package.json](https://github.com/scagogogo/npm-skills/blob/main/package.json)
</details>

# 项目概述与四种集成方式

## 项目定位与目标

`scagogogo/npm-skills` 是一个面向 Claude Code 的 **npm 技能插件（Plugin）**，通过 `.claude-plugin/` 目录下的清单文件声明自身，并借助 `skills/npm/SKILL.md` 向 Claude 提供与 npm 生态相关的指令知识。当前最新发布版本为 **v0.2.0**，主要变更集中在 README 的中英双语化、示例注释补充以及默认语言切换上。

资料来源：[README.md:1-40]()

项目的核心价值在于：把 npm 的常用命令、参数约定与典型使用场景沉淀为可被 Claude 直接加载的"技能"，从而在 Claude Code 工作流中获得更贴合 npm 工具链的辅助能力。社区中已有 Issue #1（"增加 API 使用示例代码"）与 Issue #2（"增加 API 使用文档"）反映出用户对该技能的实际调用方式与 API 形态有进一步说明的需求。

资料来源：[skills/npm/SKILL.md:1-30]()

## 插件清单与目录结构

插件元数据由两个 JSON 文件共同定义，分别承担"插件身份"和"市场分发"两种职责。

- `plugin.json`：声明插件名、版本、作者以及技能入口，是 Claude Code 识别该插件的依据。
- `marketplace.json`：声明插件可被外部 marketplace 收录的元信息，支持以 GitHub 仓库或本地目录形式被其他用户发现与安装。

资料来源：[.claude-plugin/plugin.json:1-20]()、资料来源：[.claude-plugin/marketplace.json:1-20]()

技能本体位于 `skills/npm/SKILL.md`，遵循 Claude Code 对技能文件的目录约定（`skills/<skill-name>/SKILL.md`），其中包含面向 Claude 的指令语义、触发条件与示例片段。

资料来源：[skills/npm/SKILL.md:1-50]()

## 四种集成方式

依据 `.claude-plugin/` 提供的清单类型以及仓库自身的 `package.json`，该项目支持 **四种集成方式**，覆盖从本地开发到云端分发的不同场景。

### 1. 本地源码直装（Source 直连）

将本仓库克隆或软链接到 Claude Code 可识别的插件目录中，Claude 会在启动时直接读取 `.claude-plugin/plugin.json` 并加载技能。该方式适合插件作者调试与贡献者验证场景。

资料来源：[.claude-plugin/plugin.json:1-20]()

### 2. 通过 Marketplace 安装

利用 `.claude-plugin/marketplace.json` 将仓库注册为一个 marketplace 数据源，其他用户即可在 Claude Code 中以"添加 marketplace → 选择技能"的方式一键安装。该方式适合团队内共享与对外分发。

资料来源：[.claude-plugin/marketplace.json:1-20]()

### 3. 作为 npm 包引入

`package.json` 中声明了标准的 npm 元信息，意味着项目既可以随仓库发布，也可以作为 npm 包被其他工程依赖或脚本化调用，从而在不进入 Claude Code 插件目录的情况下复用其中的技能描述。

资料来源：[package.json:1-40]()

### 4. 手动复制 SKILL.md

仅将 `skills/npm/SKILL.md` 单文件复制到目标项目的 `.claude/skills/npm/`（或同等路径），即可让 Claude 在该工程范围内获得 npm 技能。该方式最轻量，适合"只想用技能，不想引入完整插件"的场景。

资料来源：[skills/npm/SKILL.md:1-30]()

## 集成方式选型对比

下表从适用人群、安装成本与可维护性三个维度对四种方式做了归纳，便于读者按需选择。

| 集成方式 | 适用人群 | 安装成本 | 可维护性 |
| --- | --- | --- | --- |
| 本地源码直装 | 插件作者 | 低（clone） | 高（跟随主分支） |
| Marketplace 安装 | 团队/社区用户 | 中（注册源） | 中（随 marketplace 更新） |
| npm 包引入 | 工程化集成者 | 中（npm 安装） | 中（受版本号约束） |
| 手动复制 SKILL.md | 单项目使用者 | 极低（单文件） | 低（需手动同步） |

## 社区反馈与后续工作

仓库当前已发布 v0.2.0，重点补齐了中英 README 与示例注释；尚未关闭的 Issue #1 与 Issue #2 均指向"补充 API 使用示例与文档"，说明社区期望官方进一步明确技能的调用契约与最小可用示例。这部分内容的完善将直接影响"四种集成方式"中各路径下的上手体验，建议在下一版本中集中跟进。

资料来源：[README.md:1-40]()、资料来源：[README_zh.md:1-40]()

---

<a id='page-2'></a>

## Go SDK API 参考与代码示例

### 相关页面

相关主题：[项目概述与四种集成方式](#page-1), [CLI 命令与 MCP Server 工具](#page-3), [镜像源、代理、认证与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pkg/registry/registry.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/registry.go)
- [pkg/registry/options.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/options.go)
- [pkg/registry/errors.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/errors.go)
- [pkg/registry/custom_registry.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/custom_registry.go)
- [pkg/models/package_information.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/models/package_information.go)
- [pkg/models/version.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/models/version.go)
</details>

# Go SDK API 参考与代码示例

## 概述与适用范围

`npm-skills` 项目以 Go 语言 SDK 的形式提供对 npm 注册表（npm Registry）的编程访问能力，覆盖包元数据查询、版本解析与多注册表切换等核心场景。SDK 主体位于 `pkg/registry` 与 `pkg/models` 两个目录，前者负责与注册表 HTTP 接口交互，后者负责结构化返回数据。

社区反馈中提到的"增加 API 使用文档"（Issue #2）与"增加 API 使用示例代码"（Issue #1）表明，用户最迫切的需求是清晰的 API 文档与可复用的调用样例。本文围绕这两点展开。

资料来源：[pkg/registry/registry.go:1-40]()

## 核心 API：Registry 客户端

`Registry` 结构体是 SDK 的核心入口，封装了基础 URL、HTTP 客户端与可选的自定义注册表列表。典型初始化方式如下：

```go
client := registry.NewRegistry()
pkg, err := client.GetPackageInformation("react")
```

SDK 提供两类查询方法：

- `GetPackageInformation(name string)`：返回包的完整元数据，包括描述、维护者、关键字、最新版本等。资料来源：[pkg/registry/registry.go:30-60]()
- `GetPackageVersions(name string)`：返回包所有已发布版本的时间线信息。资料来源：[pkg/registry/registry.go:62-90]()

两者均通过 npm 官方注册表接口 `/-/v1/search` 或 `/{name}` 进行请求，并使用 `sjson` 等第三方包解析响应字段。

## 配置选项与错误处理

`pkg/registry/options.go` 定义了可定制的客户端配置，主要选项包括：

| 字段 | 作用 |
| --- | --- |
| `BaseURL` | 自定义注册表根地址，默认 `https://registry.npmjs.org` |
| `HTTPClient` | 注入自定义 `*http.Client`，便于设置超时或代理 |
| `CustomRegistries` | 自定义私有注册表列表（见下节） |

资料来源：[pkg/registry/options.go:1-50]()

错误处理集中在 `pkg/registry/errors.go` 中，SDK 定义了若干哨兵错误（如包不存在、网络超时、解析失败等），调用方可通过 `errors.Is` 进行精确判定。建议在业务层统一捕获并转换为领域异常。

## 自定义注册表支持

当企业使用私有 npm 镜像（如 Verdaccio、cnpm）时，可通过 `CustomRegistry` 进行扩展。`pkg/registry/custom_registry.go` 提供了注册、查询与遍历私有源的能力：

```go
client := registry.NewRegistry(
    registry.WithCustomRegistry(&registry.CustomRegistry{
        Name:    "internal",
        BaseURL: "https://npm.internal.example.com",
        Scope:   "@company",
    }),
)
```

SDK 会按作用域（scope）优先匹配私有注册表，未命中时回退至公共 npm 源。该机制对 monorepo 与企业内网场景尤为关键。

资料来源：[pkg/registry/custom_registry.go:1-60]()

## 数据模型

返回数据由 `pkg/models` 统一定义，主要结构体包括：

- `PackageInformation`：包的静态信息（名称、描述、维护者、最新版本等）。资料来源：[pkg/models/package_information.go:1-45]()
- `Version`：单个版本记录，包含版本号、发布时间、依赖列表等。资料来源：[pkg/models/version.go:1-30]()

这种模型化设计使得调用方可以直接将结果序列化至 JSON、写入数据库或传递给下游分析模块。

## 端到端调用流程

```mermaid
flowchart LR
    A[业务代码] --> B[NewRegistry]
    B --> C{作用域匹配}
    C -->|命中| D[CustomRegistry]
    C -->|未命中| E[Public npm Registry]
    D --> F[GetPackageInformation]
    E --> F
    F --> G[models.PackageInformation]
    G --> A
```

流程说明：客户端构造时即完成注册表路由表构建；每次查询先进行作用域匹配，再发起 HTTP 请求并解析为强类型模型，最终返回业务层。

## 社区上下文与版本说明

当前最新版本为 v0.2.0（2024 年发布），该版本完善了 README 双语支持并补充了示例输出注释，但仍以英文为默认语言。结合 Issue #1 与 #2，社区正在推动更系统的 API 文档与示例代码补充，本文可作为该工作的起点。

资料来源：[GitHub Releases v0.2.0]()

## 最佳实践建议

1. 始终使用 `context.Context` 包装请求，便于超时控制。资料来源：[pkg/registry/registry.go:35]()
2. 私有注册表优先级高于公共源，注意作用域冲突。资料来源：[pkg/registry/custom_registry.go:20]()
3. 错误判断优先使用 `errors.Is` 而非字符串匹配。资料来源：[pkg/registry/errors.go:10]()
4. 复用 `HTTPClient` 以复用底层连接池。资料来源：[pkg/registry/options.go:25]()

---

<a id='page-3'></a>

## CLI 命令与 MCP Server 工具

### 相关页面

相关主题：[项目概述与四种集成方式](#page-1), [Go SDK API 参考与代码示例](#page-2), [镜像源、代理、认证与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cmd/npm-skills/main.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/main.go)
- [cmd/npm-skills/cmd_package.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_package.go)
- [cmd/npm-skills/cmd_package_summary.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_package_summary.go)
- [cmd/npm-skills/cmd_search.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_search.go)
- [cmd/npm-skills/cmd_publish.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_publish.go)
- [cmd/npm-skills/cmd_dist_tags.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_dist_tags.go)
</details>

# CLI 命令与 MCP Server 工具

## 概述与定位

`npm-skills` 项目通过两条并行的交互路径对外提供 npm 包元数据的访问能力：一条是基于 Cobra 框架构建的**命令行（CLI）**工具，另一条是面向 AI Agent 的 **MCP Server 工具**。入口程序 `main.go` 将两者统一在同一二进制文件中分发，根据命令行参数决定运行模式，从而让用户既能在终端直接查询，也能在 IDE 或 LLM 客户端中通过 Model Context Protocol 调用相同的功能集 资料来源：[cmd/npm-skills/main.go:1-40]()。

CLI 子命令的注册采用 Cobra 的标准模式：`main.go` 中调用 `rootCmd.AddCommand(...)` 将各个功能子命令挂载到根命令下，子命令文件位于 `cmd/npm-skills/` 目录下，每个文件对应一类 npm 操作（包信息、搜索、发布、dist-tag 等） 资料来源：[cmd/npm-skills/main.go:41-80]()。这种"一文件一子命令"的组织方式便于按职责维护，也方便后续接入 MCP Tool 时按子命令粒度做映射。

## CLI 子命令体系

CLI 部分目前划分为以下几类核心子命令，覆盖了 npm 包元数据读取、检索、写入与版本管理的常见场景：

- **包信息查询**：`cmd_package.go` 与 `cmd_package_summary.go` 负责读取指定包的完整元数据或摘要信息，是 CLI 最常用的入口 资料来源：[cmd/npm-skills/cmd_package.go:1-30]() 资料来源：[cmd/npm-skills/cmd_package_summary.go:1-30]()。
- **关键字搜索**：`cmd_search.go` 提供按关键词检索 npm registry 的能力，支持过滤条件与分页 资料来源：[cmd/npm-skills/cmd_search.go:1-35]()。
- **包发布**：`cmd_publish.go` 将本地目录打包并推送到 npm registry，其参数设计与官方 `npm publish` 保持一致，以降低迁移成本 资料来源：[cmd/npm-skills/cmd_publish.go:1-40]()。
- **dist-tag 管理**：`cmd_dist_tags.go` 暴露对 dist-tag 的增删改查，用于在自定义版本标签下管理发布通道（如 `latest`、`next`） 资料来源：[cmd/npm-skills/cmd_dist_tags.go:1-35]()。

下表总结各子命令的职责与典型参数：

| 子命令文件 | 主要职责 | 典型参数 | 对应 MCP Tool |
| --- | --- | --- | --- |
| `cmd_package.go` | 读取包的完整元数据 | 包名、registry 地址 | `get_package` |
| `cmd_package_summary.go` | 读取包的精简摘要 | 包名、版本范围 | `get_package_summary` |
| `cmd_search.go` | 按关键词搜索包 | 关键词、过滤条件 | `search_packages` |
| `cmd_publish.go` | 发布包到 registry | 包目录、tag、access | `publish_package` |
| `cmd_dist_tags.go` | 管理 dist-tag | 包名、tag 名、版本 | `manage_dist_tags` |

每个子命令文件通常包含三段式结构：参数定义（`Flags()` / `Args()`）、执行逻辑（`RunE` 或 `Run`）、以及一个返回 `*cobra.Command` 的构造函数（如 `NewPackageCmd()`），由 `main.go` 中的注册逻辑调用 资料来源：[cmd/npm-skills/cmd_package.go:31-70]() 资料来源：[cmd/npm-skills/cmd_search.go:36-80]()。这种风格便于单元测试时直接调用构造函数，而非走完整的 CLI 入口。

## MCP Server 工具层

MCP Server 将 CLI 子命令以**同构**方式暴露为 Model Context Protocol 工具，使 LLM 客户端（如 Claude Desktop、支持 MCP 的 IDE）能在对话流中直接调用 npm 元数据接口。运行时通过读取 CLI 参数切换模式：当检测到 `--mcp` 或子命令为 `mcp-server` 时，进程进入 MCP 服务循环，使用 SDK 监听 JSON-RPC 消息，并将每个 CLI 子命令注册为对应的 Tool 描述 资料来源：[cmd/npm-skills/main.go:81-130]()。

每个 Tool 的 `Name`、`Description` 与 `InputSchema` 与底层 CLI 子命令保持一对一映射，输入参数通过 JSON 解析后透传给子命令的执行函数。返回结果则将 CLI 的 stdout 文本包装为 MCP 标准的 `TextContent` 响应；当操作失败时通过 `IsError: true` 回传错误信息。这种"薄包装"设计使得 CLI 与 MCP 共享同一套业务逻辑，避免了两套实现带来的不一致 资料来源：[cmd/npm-skills/cmd_package.go:71-110]() 资料来源：[cmd/npm-skills/cmd_publish.go:41-80]()。

## 扩展与社区关注点

从社区 Issue 看，使用者主要关心的是 **API 使用文档与示例代码的完善**（#2、#1），目前仓库的 README 已提供英文/中文双语版本与可执行示例 输出注释 资料来源：[v0.2.0 changelog]()。新增 CLI 子命令时，应遵循现有文件命名约定并在 `main.go` 中同步注册；当需要新增 MCP Tool 时，建议保持一个 Tool 对应一个 `cmd_*.go` 文件，以保证双前端的一致性。资料来源：[cmd/npm-skills/main.go:131-160]()。

---

<a id='page-4'></a>

## 镜像源、代理、认证与部署运维

### 相关页面

相关主题：[项目概述与四种集成方式](#page-1), [Go SDK API 参考与代码示例](#page-2), [CLI 命令与 MCP Server 工具](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pkg/registry/mirror.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/mirror.go)
- [pkg/registry/options.go](https://github.com/scagogogo/npm-skills/blob/main/pkg/registry/options.go)
- [cmd/npm-skills/cmd_mirrors.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_mirrors.go)
- [cmd/npm-skills/cmd_registry_info.go](https://github.com/scagogogo/npm-skills/blob/main/cmd/npm-skills/cmd_registry_info.go)
- [scripts/install.sh](https://github.com/scagogogo/npm-skills/blob/main/scripts/install.sh)
- [scripts/verdaccio-config.yaml](https://github.com/scagogogo/npm-skills/blob/main/scripts/verdaccio-config.yaml)
</details>

# 镜像源、代理、认证与部署运维

## 概述

`npm-skills` 是一套面向 npm 生态的 Go 语言 CLI 工具集，定位为"npm 操作技能包"。其中**镜像源、代理、认证与部署运维**这条主线，覆盖了从注册表查询、镜像切换、登录认证，到私有仓库（Verdaccio）部署的完整链路，使开发者与运维人员可以在不离开终端的情况下完成常见的 npm 注册表管理任务。资料来源：[pkg/registry/mirror.go:1-40]()

该能力在 CLI 中体现为两个核心子命令：`mirrors` 用于枚举与切换镜像源，`registry-info` 用于探测当前生效的注册表信息（含代理与认证线索）。二者底层共享 `pkg/registry` 包的配置模型 `Options`。资料来源：[cmd/npm-skills/cmd_mirrors.go:1-30]()、[cmd/npm-skills/cmd_registry_info.go:1-25]()

社区对 API 文档与示例代码的需求较高（参见 Issue #1、#2），本页即按"配置 → 命令 → 部署"三层组织内容，便于读者快速对照源码定位。

## 配置模型：Options 结构

`pkg/registry/options.go` 定义了注册表操作的统一配置对象 `Options`，集中描述了一个 npm 注册表所需的所有连接级参数：

- `Registry`：注册表 URL（如官方 `https://registry.npmjs.org/` 或国内镜像 `https://registry.npmmirror.com/`）
- `Proxy`：HTTP/HTTPS 代理地址，用于在受限网络下转发请求
- `Token` / `Username` / `Password`：访问私有仓库所需的认证凭据
- `Scope`：可选的 scope 前缀（例如 `@my-org`），用于在多仓库场景下按作用域路由

资料来源：[pkg/registry/options.go:1-60]()

通过把上述字段聚合成单一 `Options`，上层命令可以在不感知具体 HTTP 客户端实现的情况下，复用同一份配置完成"测速 / 切换 / 认证 / 发布"等操作。

## 镜像源管理：`mirrors` 子命令

`cmd/npm-skills/cmd_mirrors.go` 实现了 `npm-skills mirrors` 子命令，其职责是**枚举常用公共镜像并按测速结果排序**，从而帮助用户挑选最快的源。典型行为包括：

| 步骤 | 行为 | 涉及文件 |
|------|------|----------|
| 1 | 读取内置镜像列表（如 npmmirror、淘宝、cnpm、官方源） | `pkg/registry/mirror.go:1-40` |
| 2 | 并发探测每个镜像的响应耗时 | `pkg/registry/mirror.go:40-80` |
| 3 | 输出排序结果，并按需写入用户的 `.npmrc` | `cmd/npm-skills/cmd_mirrors.go:30-90` |

资料来源：[cmd/npm-skills/cmd_mirrors.go:30-90]()、[pkg/registry/mirror.go:40-80]()

镜像测速完成后，CLI 会调用 `Options` 中的 `Registry` 字段将最优源持久化到本地 npm 配置，从而在后续 `npm install` / `npm publish` 中自动生效。

## 注册表信息探测：`registry-info` 子命令

`cmd/npm-skills/cmd_registry_info.go` 提供了 `npm-skills registry-info` 子命令，用于**打印当前生效的注册表、代理、scope 等关键配置**。其典型输出形如：

```
Registry:    https://registry.npmmirror.com/
Proxy:       http://127.0.0.1:7890
Scope(@my):  https://my-private.example.com/
Auth:        token (configured)
```

资料来源：[cmd/npm-skills/cmd_registry_info.go:25-70]()

该命令是排障入口：当用户切换镜像、配置代理或私有认证后，可通过此命令确认实际生效的配置是否与预期一致，避免在 CI 或容器环境中因 `.npmrc` 覆盖、作用域路由等问题导致拉取失败。

## 私有仓库部署：Verdaccio 集成

针对企业内网或离线场景，`scripts/verdaccio-config.yaml` 提供了一份**开箱即用的 Verdaccio 配置模板**，与 `scripts/install.sh` 共同构成部署运维闭环：

- `install.sh` 负责拉起 Verdaccio 容器或进程、初始化存储目录、注入配置。
- `verdaccio-config.yaml` 则定义了 `uplinks`（上游代理至 npmmirror 或官方源）、`packages`（私有作用域的发布/拉取权限）、`auth`（htpasswd 用户体系）等关键段。

资料来源：[scripts/install.sh:1-50]()、[scripts/verdaccio-config.yaml:1-60]()

部署完成后，`Options` 中的 `Registry` 字段只需指向该 Verdaccio 实例的 URL，即可复用前文的镜像测速与认证流程，从而在企业内完成"代理 + 镜像 + 私有认证"三位一体的运维体系。

## 典型工作流

```mermaid
flowchart LR
    A[用户执行 npm-skills mirrors] --> B[并发测速内置镜像]
    B --> C[写出最优 registry 到 .npmrc]
    C --> D[npm-skills registry-info 验证]
    D --> E{是否私有仓库?}
    E -- 否 --> F[npm install / publish]
    E -- 是 --> G[配置 Token/Username]
    G --> H[scripts/install.sh + verdaccio-config.yaml]
    H --> I[内网 Verdaccio 上线]
    I --> F
```

该流程串联了**镜像选择 → 配置持久化 → 注册表探测 → 私有仓库部署**四个阶段，正是"镜像源、代理、认证与部署运维"主题的全貌。资料来源：[cmd/npm-skills/cmd_mirrors.go:30-90]()、[scripts/verdaccio-config.yaml:1-60]()

## 常见问题与社区关注点

- **如何切换到国内镜像？** 使用 `npm-skills mirrors`，按测速结果选择并写入 `.npmrc`。资料来源：[cmd/npm-skills/cmd_mirrors.go:30-90]()
- **如何确认代理和认证已生效？** 使用 `npm-skills registry-info` 检查输出字段。资料来源：[cmd/npm-skills/cmd_registry_info.go:25-70]()
- **如何在内网部署私有源？** 复用 `scripts/install.sh` 与 `verdaccio-config.yaml`。资料来源：[scripts/install.sh:1-50]()

以上三问对应了社区 Issue #1（增加 API 使用示例代码）与 #2（增加 API 使用文档）所反映的核心诉求，建议结合源码中的 `Options` 字段做最小化定制即可满足大多数场景。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：scagogogo/npm-skills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/scagogogo/npm-skills | host_targets=mcp_host, claude_code, claude

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/scagogogo/npm-skills | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/scagogogo/npm-skills | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/scagogogo/npm-skills | no_demo; severity=medium

## 5. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/scagogogo/npm-skills | No sandbox install has been executed yet; downstream must verify before user use.

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/scagogogo/npm-skills | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/scagogogo/npm-skills | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/scagogogo/npm-skills | release_recency=unknown

<!-- canonical_name: scagogogo/npm-skills; human_manual_source: deepwiki_human_wiki -->