# https://github.com/sator-imaging/suggest-skills 项目说明书
生成时间：2026-05-13 13:58:02 UTC
## 目录
- [项目介绍](#project-introduction)
- [核心特性](#key-features)
- [系统架构](#system-architecture)
- [项目结构](#project-structure)
- [MCP 工具](#mcp-tools)
- [传输模式](#transport-modes)
- [Generate 命令](#generate-command)
- [Server 命令](#server-command)
- [配置指南](#configuration-guide)
- [部署指南](#deployment-guide)
## 项目介绍
### 相关页面
相关主题：[核心特性](#key-features), [系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
# 项目介绍
`suggest-skills` 是一个用于管理和发现 AI Agent 技能（Skills）的工具项目。该项目通过 MCP（Model Context Protocol）协议提供技能建议功能，支持从 GitHub 仓库自动扫描、本地安装以及远程技能清单管理。
## 项目概述
`suggest-skills` 的核心功能是帮助 AI Agent 智能地发现和推荐可用的技能扩展包。用户可以通过配置技能清单（manifest）URL，系统会自动扫描本地已安装的技能，并与远程清单进行对比，最终呈现可用的技能建议列表。
资料来源：[README.md]()
### 主要特性
| 特性 | 描述 |
|------|------|
| MCP 协议支持 | 提供符合 MCP 标准的工具接口 |
| 多模式运行 | 支持 stdio 模式和 HTTP 服务器模式 |
| GitHub 集成 | 可从 GitHub 仓库自动发现和下载技能 |
| 清单生成 | 支持从 GitHub 目录递归扫描生成技能清单 |
| 多格式配置 | 支持 JSON、逗号分隔、换行分隔的环境变量配置 |
资料来源：[README.md]()
## 技术栈
项目采用现代 TypeScript 技术栈构建，主要依赖包括：
```json
{
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0",
"zod": "^3.23.8"
},
"devDependencies": {
"bun": "latest"
}
}
```
| 技术组件 | 用途 |
|----------|------|
| Bun | JavaScript 运行时和打包工具 |
| TypeScript | 类型安全的开发语言 |
| @modelcontextprotocol/sdk | MCP 协议 SDK 实现 |
| Zod | 运行时配置验证 |
资料来源：[package.json]()
## 架构设计
### 整体架构
```mermaid
graph TD
A[Config 配置] --> B[MCP 工具注册]
B --> C[stdio 传输模式]
B --> D[HTTP 传输模式]
E[CLI generate 命令] --> F[GitHub 目录扫描]
F --> G[生成 manifest markdown]
H[GitHub URL 规范化] --> I[文件夹下载]
I --> F
```
项目架构分为两个主要入口：
1. **MCP 服务器模式**：通过 `Config` 配置驱动的 MCP 工具服务
2. **CLI 生成模式**：命令行工具用于扫描 GitHub 仓库生成技能清单
资料来源：[README.md]()
### 模块职责
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| 配置模块 | `src/config.ts` | 环境变量验证与解析 |
| MCP 工具 | `src/index.ts` | 工具注册与请求处理 |
| 下载功能 | `src/download.ts` | GitHub 仓库文件下载 |
| 生成功能 | `src/generate.ts` | 技能清单生成逻辑 |
| CLI 命令 | `src/cmd_generate.ts` | 命令行参数解析与输出 |
资料来源：[src/download.ts](), [src/generate.ts](), [src/cmd_generate.ts]()
## MCP 工具接口
### suggest_skills
主动建议可用技能的主工具。
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |
返回说明：生成一条指令负载，指导 Agent 如何获取可用技能列表、对比本地与远程能力、以及呈现建议。
资料来源：[README.md]()
### fetch_manifest
获取指定清单文件内容。
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| manifestUrl | string | 是 | 技能清单的 GitHub URL |
返回内容：清单文件的完整文本内容。
资料来源：[README.md]()
### download_skill
下载指定 GitHub 文件夹中的所有文件。
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| url | string | 是 | GitHub 文件夹 URL |
返回内容：文件夹中每个文件的路径、UTF-8 文本内容。符号链接会被解析并递归下载。
资料来源：[README.md](), [src/download.ts]()
## 下载流程实现
### GitHub API 调用
项目使用 GitHub Contents API 和 Git Trees API 来获取仓库内容：
```mermaid
sequenceDiagram
参与者 A as 用户请求
参与者 G as GitHub API
参与者 L as 本地处理
A->>G: 请求目录内容
G-->>L: 返回 tree 结构
L->>L: 解析路径并过滤
L->>G: 获取文件下载 URL
G-->>A: 返回文件内容
```
资料来源：[src/download.ts]()
### 路径解析逻辑
下载模块的核心路径处理逻辑位于 `buildContentsApiUrl` 和 `buildTreeApiUrl` 函数中：
```typescript
function buildContentsApiUrl(location: GithubDirectoryLocation): string {
const pathSuffix = location.path
.split("/")
.filter(Boolean)
.map((part) => encodeURIComponent(part))
.join("/");
// 构建 API 路径并添加 ref 参数
}
```
关键处理步骤：
1. 过滤空路径段
2. 对每个路径段进行 URL 编码
3. 拼接为标准 GitHub API 路径
4. 设置 `ref` 参数指定分支/提交
资料来源：[src/download.ts]()
## 清单生成功能
### generate 命令工作流
```mermaid
graph LR
A[GitHub URL] --> B[目录扫描]
B --> C[识别 SKILL.md]
B --> D[识别 DESIGN.md]
B --> E[收集资产文件]
C --> F[生成 skills.md]
D --> G[生成 designs.md]
E --> F
E --> G
```
生成模式下，系统会：
1. 递归扫描 GitHub 目录结构
2. 识别包含 `SKILL.md` 的技能目录
3. 识别包含 `DESIGN.md` 的设计目录
4. 收集目录中的其他资产文件
5. 生成格式化的 Markdown 清单文件
资料来源：[src/generate.ts](), [README.md]()
### 生成选项
| 选项 | 简写 | 描述 |
|------|------|------|
| --recursive, -r | 递归扫描子目录 | |
| --output, -o | 指定输出目录 | 默认输出到 `.agents/skills` |
资料来源：[README.md]()
### 输出文件类型
| 文件类型 | 内容 | 触发条件 |
|----------|------|----------|
| `..skills.md` | 技能条目列表 | 目录中包含 `SKILL.md` |
| `..designs.md` | 设计条目列表 | 目录中包含 `DESIGN.md` |
| `..agents.md` | Agent 条目列表 | 平面化顶级 markdown 文件 |
资料来源：[README.md]()
## 配置管理
### 环境变量配置
| 变量名 | 必需 | 描述 |
|--------|------|------|
| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL 列表 |
清单 URL 支持三种格式：
| 格式 | 示例 |
|------|------|
| JSON 数组 | `["https://example.com/manifest.md"]` |
| 逗号分隔 | `https://a.com/1.md,https://b.com/2.md` |
| 换行分隔 | `https://a.com/1.md\nhttps://b.com/2.md` |
资料来源：[README.md]()
### 启动模式
#### stdio 模式
标准输入输出模式，适合本地集成：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
#### HTTP 服务器模式
提供 HTTP API 端点，适合远程访问：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| 端点 | 路径 | 描述 |
|------|------|------|
| MCP 服务 | `/mcp` | 主要的 MCP 协议端点 |
| 健康检查 | `/health` | 服务健康状态检查 |
资料来源：[README.md]()
## 代码规范
项目遵循以下编码标准：
| 规范 | 说明 |
|------|------|
| 模块化设计 | 小而专注的模块，按运行时关注点拆分文件 |
| 配置验证 | 通过 `ConfigError` 进行显式配置验证 |
| 类型安全 | 使用 Zod 进行运行时类型验证 |
| 结构化输出 | MCP 工具使用类型化 Schema 和结构化返回 |
| 传输层抽象 | 最小化传输层封装，围绕共享服务器创建 |
资料来源：[README.md]()
## 使用示例
### 快速开始
1. **配置环境变量**：
```bash
export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md"]'
```
2. **运行 MCP 服务器**：
```bash
npx suggest-skills server --port 3100
```
3. **生成技能清单**：
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
### 递归扫描示例
生成包含子目录的完整清单：
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
这会生成以下文件：
- `...skills.md`
- `...designs.md`
资料来源：[README.md]()
## 相关资源
| 资源 | 链接 |
|------|------|
| 官方技能库 | [official/skills](./official/skills) |
| 社区技能库 | [community/skills](./community/skills) |
| MCP 协议文档 | [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) |
---
## 核心特性
### 相关页面
相关主题：[项目介绍](#project-introduction), [MCP 工具](#mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [官方 Skills 清单](https://github.com/anthropics/skills)
- [OpenAI Skills 清单](https://github.com/openai/skills)
# 核心特性
`suggest-skills` 是一个基于 MCP（Model Context Protocol）的技能推荐与管理系统，旨在帮助 AI 代理（Agent）发现、安装和管理来自各类 GitHub 仓库的技能扩展包。本项目采用现代化的技术栈构建，支持灵活的配置方式和多种运行模式。
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 配置层
A[环境变量配置] --> B[Config 验证模块]
B --> C[ConfigError 异常处理]
end
subgraph 核心功能层
D[MCP 工具注册] --> E[suggest_skills]
D --> F[fetch_manifest]
D --> G[download_skill]
end
subgraph 传输层
H[stdio 传输]
I[HTTP 传输]
end
subgraph GitHub 交互层
J[目录扫描] --> K[SKILL.md 发现]
J --> L[DESIGN.md 发现]
J --> M[manifest 生成]
end
B --> D
E --> J
F --> M
G --> J
D --> H
D --> I
```
### 技术栈
| 技术组件 | 用途说明 |
|---------|---------|
| Bun | JavaScript 运行时与打包工具 |
| TypeScript | 类型安全与开发体验 |
| @modelcontextprotocol/sdk | MCP 协议实现 |
| Zod | 配置验证与类型推断 |
资料来源：[README.md:技术栈]()
## MCP 工具集
项目提供三个核心 MCP 工具，供 AI 代理调用以实现技能管理功能。
### 工具功能总览
| 工具名称 | 功能描述 | 输入参数 |
|---------|---------|---------|
| `suggest_skills` | 生成技能推荐指令负载 | `manifestUrl`（可选） |
| `fetch_manifest` | 获取技能清单文本内容 | `manifestUrl` |
| `download_skill` | 下载指定 GitHub 文件夹的所有文件 | GitHub 文件夹 URL |
### suggest_skills 工具
该工具是系统的核心入口点，负责生成指令负载，指导 AI 代理完成以下任务：
- 从配置的 manifest 文件获取可用技能列表
- 扫描本地已安装的技能
- 对比远程与本地能力差异
- 在用户请求前不执行任何安装操作
```mermaid
graph LR
A[调用 suggest_skills] --> B{是否指定 manifestUrl?}
B -->|是| C[使用指定 URL]
B -->|否| D[使用环境变量配置的默认 URL]
C --> E[生成指令负载]
D --> E
E --> F[返回技能发现/推荐指导]
```
### fetch_manifest 工具
用于获取远程技能清单的原始文本内容，支持自定义技能仓库的 manifest 文件获取。
### download_skill 工具
该工具实现 GitHub 目录的递归下载功能，支持以下特性：
- 接收标准 GitHub 树形 URL 格式：`https://github.com///tree/[/`
- 返回文件夹内所有文件及其相对路径
- 自动处理文件 symlink（当 GitHub 提供 `download_url` 时）
- 解析仓库相对目录 symlink 并递归下载
资料来源：[README.md:MCP Tools]()
## 技能清单生成
### 生成工作流程
```mermaid
graph TD
A[CLI: npx suggest-skills generate] --> B[接收 GitHub URL]
B --> C{是否指定 --recursive?}
C -->|是| D[递归扫描目录树]
C -->|否| E[扫描当前层级]
D --> F[发现 SKILL.md 文件]
E --> F
F --> G[发现 DESIGN.md 文件]
G --> H[汇总同目录资产文件]
H --> I[生成清单文件]
I --> J[.skills.md]
I --> K[.designs.md]
I --> L[.agents.md]
```
### 生成规则
| 规则类型 | 说明 |
|---------|------|
| 目录发现 | 使用递归树形列表 API 进行 GitHub 目录扫描 |
| 文件识别 | `SKILL.md` 和 `DESIGN.md` 在技能目录中识别 |
| 资产打包 | 同目录及嵌套子目录中的其他文件视为资产 |
| Symlink 处理 | 发现时不作特殊处理，可能出现在资产列表中 |
| 空输出跳过 | 空生成结果不写入文件，不显示覆盖提示 |
### 输出文件类型
| 文件后缀 | 内容来源 | 文件格式 |
|---------|---------|---------|
| `.[.].skills.md` | 包含 `SKILL.md` 的目录 | Markdown 表格 |
| `.[.].designs.md` | 包含 `DESIGN.md` 的目录 | Markdown 表格 |
| `.[.].agents.md` | 平面顶级 Markdown 文件 | Name + Description 列 |
资料来源：[README.md:Generate a Manifest]()
资料来源：[src/generate.ts:SKILL.md/DESIGN.md 发现逻辑]()
## 配置管理
### 环境变量配置
| 环境变量 | 必填 | 用途 |
|---------|-----|------|
| `GITHUB_PAT` | 否 | 访问 GitHub API 的个人访问令牌 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | **是** | 技能清单 URL 列表 |
`SUGGEST_SKILLS_MANIFEST_URLS` 支持三种格式：
- JSON 数组：`["url1", "url2"]`
- 逗号分隔字符串：`url1,url2`
- 换行分隔字符串：`url1\nurl2`
> **注意**：GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。
资料来源：[README.md:Environment Variables]()
### 配置验证
系统通过 `ConfigError` 异常类实现显式配置验证，确保：
- 至少配置一个 manifest URL
- URL 格式正确
- 环境变量解析成功
```mermaid
stateDiagram-v2
[*] --> 加载环境变量
加载环境变量 --> 验证配置
验证配置 --> 配置有效: 通过
验证配置 --> ConfigError: 失败
配置有效 --> MCP 工具注册
ConfigError --> [*]
```
## 运行模式
### stdio 模式
适用于本地集成和管道通信场景：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP 模式
适用于分布式部署和远程服务场景：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| 端点 | 路径 | 用途 |
|-----|------|------|
| MCP 端点 | `http://localhost:3100/mcp` | MCP 协议通信 |
| 健康检查 | `http://localhost:3100/health` | 服务状态监控 |
资料来源：[README.md:Run in stdio Mode]()
资料来源：[README.md:Run in HTTP Mode]()
## GitHub API 交互
### API 端点构建
项目封装了多个 GitHub API URL 构建函数：
| 函数 | 功能 |
|-----|------|
| `buildContentsApiUrl` | 构建 Contents API URL |
| `buildTreeApiUrl` | 构建 Tree API URL（支持递归） |
| `buildGithubRawUrl` | 构建 Raw 文件访问 URL |
### 目录扫描数据结构
```typescript
interface ContentEntry {
path: string; // 文件相对路径
download_url: string | null; // 下载 URL（文件）或 null（目录）
type: "file" | "dir"; // 条目类型
}
```
### 路径解析规则
1. 解析 GitHub 目录位置信息（owner、repo、ref、path）
2. 将相对路径与基础路径拼接
3. 去除前导斜杠确保路径一致性
4. 递归处理树形结构
```mermaid
graph LR
A[GitHub Tree API 响应] --> B[遍历 entries]
B --> C{entry.type === 'tree'?}
C -->|是| D[创建 dir 条目]
C -->|否| E[entry.type === 'blob'?]
E -->|是| F[构建 download_url]
F --> G[创建 file 条目]
E -->|否| H[跳过]
D --> I[返回 ContentEntry 数组]
G --> I
```
资料来源：[src/download.ts:ContentEntry 类型定义]()
资料来源：[src/download.ts:buildContentsApiUrl 函数]()
## CLI 选项
| 选项 | 全写形式 | 说明 |
|-----|---------|------|
| `-o ` | `--output ` | 技能安装输出目录 |
| `generate [-r\|--recursive]` | 生成模式 | 从 GitHub 技能目录生成清单 |
| `server --port ` | 服务模式 | 启动 HTTP 服务器 |
默认安装目录：`.agents/skills`
## 代码组织规范
项目遵循以下实现模式：
| 规范类别 | 说明 |
|---------|------|
| 模块划分 | 小而专注的模块，按运行时关注点拆分 |
| 配置验证 | 通过 ConfigError 实现显式验证 |
| 类型安全 | 使用 Zod 进行工具 schema 验证和结构化输出 |
| 传输封装 | 最小化传输层包装，围绕共享服务器创建 |
| 测试策略 | 聚焦可观察行为而非实现细节 |
资料来源：[README.md:Coding Standards]()
## 与官方技能仓库集成
项目内置支持从主流技能仓库生成清单和下载技能：
### Anthropic 官方技能
包含 40+ 个预构建技能，覆盖文档协作、Word 文档处理、PDF 操作、Figma 设计集成、Web 应用测试等领域。
### OpenAI 精选技能
包含 Notion 集成、Linear 项目管理、PDF 处理、Jupyter 笔记本、Figma 协作、Playwright 自动化测试、Vercel/Netlify 部署等企业级工具。
### 社区技能
汇集来自 ComposioHQ 等社区的精选技能，包括主题工厂、Twitter 算法优化、YouTube 下载器等实用工具。
资料来源：[官方 Skills 清单]()
资料来源：[OpenAI Skills 清单]()
资料来源：[社区 Skills 清单]()
---
## 系统架构
### 相关页面
相关主题：[项目结构](#project-structure), [传输模式](#transport-modes)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)
- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)
- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
# 系统架构
## 概述
`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理工具，旨在帮助 AI Agent 智能地发现、推荐和安装来自各种来源的技能扩展包。 资料来源：[README.md]()
该项目的核心价值在于：**将分散在不同 GitHub 仓库中的技能清单（Manifest）聚合起来，为 Agent 提供统一的技能发现和安装接口**，而无需预先安装任何内容。
## 技术栈
| 技术 | 用途 |
|------|------|
| Bun | JavaScript/TypeScript 运行时与打包工具 |
| TypeScript | 类型安全的开发语言 |
| @modelcontextprotocol/sdk | MCP 协议实现与工具注册框架 |
| Zod | 运行时配置验证 |
资料来源：[README.md]()
---
## 整体架构
`suggest-skills` 采用**分层模块化设计**，核心架构遵循以下数据流：
```mermaid
graph TD
A[配置文件
Config] --> B[MCP 工具注册
Tool Registration]
B --> C{传输层选择}
C --> D[stdio 模式
标准输入输出]
C --> E[HTTP 模式
HTTP 服务器]
F[CLI 命令] --> G[GitHub 目录扫描
目录树 API]
G --> H[Manifest 生成器]
H --> I[Markdown 清单文件]
J[MCP 客户端] --> K[suggest_skills 工具]
J --> L[fetch_manifest 工具]
J --> M[download_skill 工具]
```
资料来源：[README.md](), [src/index.ts](), [src/stdio.ts](), [src/http.ts]()
---
## 核心模块解析
### 1. 配置层 (Config)
配置层负责加载和验证所有运行时参数，支持两种配置方式：
| 配置方式 | 说明 |
|----------|------|
| 环境变量 | `SUGGEST_SKILLS_MANIFEST_URLS`、`GITHUB_PAT` |
| CLI 参数 | `-o`、`--output`、`--port` 等 |
**关键配置项：**
| 变量名 | 必需 | 说明 |
|--------|------|------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | Manifest URL 列表，支持 JSON 数组、逗号分隔、换行分隔 |
| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |
| 输出目录 | 否 | 默认为 `.agents/skills` |
支持的 URL 格式：
- 普通 GitHub URL
- GitHub `blob` URL（自动转换为 `raw.githubusercontent.com`）
资料来源：[README.md](), [src/config.ts]()
### 2. MCP 工具层 (Core)
MCP 工具层是系统的核心业务逻辑，提供三个主要工具：
| 工具名 | 功能 | 输入参数 |
|--------|------|----------|
| `suggest_skills` | 智能推荐技能 | 可选 `manifestUrl` 覆盖默认配置 |
| `fetch_manifest` | 获取 Manifest 内容 | `manifestUrl` |
| `download_skill` | 下载技能目录 | GitHub 文件夹 URL |
**`suggest_skills` 工具的工作流程：**
```mermaid
graph LR
A[获取配置的 Manifest URLs] --> B[抓取远程技能列表]
B --> C[扫描本地已安装技能]
C --> D[对比远程与本地能力]
D --> E[生成推荐指令]
E --> F[展示建议
不自动安装]
```
资料来源：[README.md](), [src/core.ts]()
### 3. 传输层 (Transport)
传输层负责 MCP 服务器与客户端之间的通信，支持两种模式：
#### 3.1 stdio 模式
适用于本地 CLI 调用和终端交互场景。通过标准输入输出进行 JSON-RPC 通信。
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' \
npx suggest-skills
```
资料来源：[src/stdio.ts](), [README.md]()
#### 3.2 HTTP 模式
适用于远程部署和服务化场景，提供 HTTP 端点：
| 端点 | 路径 | 说明 |
|------|------|------|
| MCP 协议端点 | `/mcp` | MCP 工具调用入口 |
| 健康检查 | `/health` | 服务状态检查 |
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' \
npx suggest-skills server --port 3100
```
资料来源：[src/http.ts](), [README.md]()
### 4. CLI 生成模块 (Generate)
CLI 生成模块提供命令行工具，用于从 GitHub 仓库自动生成技能清单文件：
```bash
# 生成单个目录的清单
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
# 递归生成（含子目录）
npx suggest-skills generate --recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
**生成的文件类型：**
| 文件后缀 | 内容 | 发现规则 |
|----------|------|----------|
| `.skills.md` | 技能目录清单 | 包含 `SKILL.md` 的目录 |
| `.designs.md` | 设计清单 | 包含 `DESIGN.md` 的目录 |
| `.agents.md` | Agent 清单 | 平铺的顶层 Markdown 文件 |
**生成模式规则：**
```mermaid
graph TD
A[GitHub 仓库 URL] --> B{是否包含路径?}
B -->|是| C[扫描指定目录树]
B -->|否| D[假设仓库根目录为技能目录]
C --> E[递归遍历树结构]
D --> E
E --> F[发现 SKILL.md 或 DESIGN.md]
F --> G[收集同目录资源文件]
G --> H[生成 Markdown 表格]
```
资料来源：[src/generate.ts](), [src/cmd_generate.ts](), [README.md]()
### 5. 下载模块 (Download)
下载模块负责从 GitHub 仓库获取技能目录及其所有文件：
```typescript
// 核心数据结构
interface ContentEntry {
path: string; // 相对路径
download_url: string | null; // 文件下载链接
type: "file" | "dir"; // 条目类型
}
```
**GitHub API 调用策略：**
| 步骤 | API | 用途 |
|------|-----|------|
| 1 | `/repos/{owner}/{repo}/git/trees/{sha}?recursive=1` | 获取目录树 |
| 2 | `/repos/{owner}/{repo}/contents/{path}` | 获取文件内容 |
资料来源：[src/download.ts]()
---
## 数据模型
### Manifest URL 配置结构
```mermaid
classDiagram
class Config {
+string[] manifestUrls
+string? githubPat
+string outputDir
}
class Manifest {
+string url
+Skill[] skills
}
class Skill {
+string name
+string description
+string url
+Asset[] bundledAssets
}
class Asset {
+string path
+string downloadUrl
}
Config --> Manifest : 引用
Manifest --> Skill : 包含
Skill --> Asset : 引用
```
### 生成的 Markdown 表格结构
| 列 | 来源 | 说明 |
|----|------|------|
| Name | 目录名 | 链接到 GitHub 目录 |
| Description | `SKILL.md`/`DESIGN.md` 首行或摘要 | 技能用途描述 |
| Bundled Assets | 同目录其他文件 | 附带的资源文件 |
资料来源：[src/cmd_generate.ts](), [src/generate.ts]()
---
## 入口点
### 主入口 (index.ts)
```mermaid
graph TD
A[index.ts
主入口] --> B{命令行参数解析}
B -->|generate| C[cmd_generate.ts
生成清单]
B -->|server| D[http.ts
HTTP 服务器]
B -->|stdio| E[stdio.ts
stdio 传输]
B -->|默认| F[stdio.ts
stdio 传输]
```
资料来源：[src/index.ts]()
---
## 关键设计决策
### 1. 惰性安装原则
`suggest_skills` 工具**仅返回推荐指令**，不会自动安装任何内容。用户确认后，需单独触发安装流程。
> "Present suggestions without installing anything until requested" 资料来源：[README.md]()
### 2. 空输出跳过机制
在生成清单时，如果某个类型没有任何条目，则不生成对应文件，也不显示覆盖确认提示。
### 3. 符号链接处理
生成模式中，符号链接会被发现并包含在资源列表中，但不会进行递归遍历。
### 4. URL 自动转换
GitHub `blob` 格式的 URL 会自动转换为 `raw.githubusercontent.com` 格式，便于直接获取原始内容。
---
## 模块依赖关系
```mermaid
graph TD
subgraph "传输层"
stdio[stdio.ts
stdio 传输]
http[http.ts
HTTP 服务器]
end
subgraph "业务逻辑层"
core[core.ts
MCP 工具实现]
download[download.ts
文件下载]
generate[generate.ts
清单生成]
cmd[cmd_generate.ts
CLI 命令]
end
subgraph "基础设施层"
config[config.ts
配置管理]
index[index.ts
入口调度]
end
config --> core
config --> download
config --> generate
config --> cmd
core --> download
core --> stdio
core --> http
generate --> download
cmd --> generate
stdio --> index
http --> index
```
---
## 扩展性与可维护性
该架构具备良好的扩展性：
| 扩展方向 | 实现方式 |
|----------|----------|
| 新增 MCP 工具 | 在 `core.ts` 中注册 `Tool` 实例 |
| 新增传输协议 | 实现 `Server` 接口并添加到 `index.ts` |
| 新增 Manifest 来源 | 扩展 `config.ts` 中的 URL 解析逻辑 |
| 新增文件格式支持 | 在 `generate.ts` 中添加 `DESIGN.md` 等文件类型识别 |
---
## 项目结构
### 相关页面
相关主题：[系统架构](#system-architecture), [Generate 命令](#generate-command)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/constants.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/constants.ts)
- [src/utils.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/utils.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
# 项目结构
## 概述
suggest-skills 是一个基于 Model Context Protocol (MCP) 的技能推荐与管理系统。该项目允许 AI Agent 发现、扫描并推荐可用的技能（Skills），同时支持从 GitHub 下载技能资源。项目的核心架构围绕 MCP 协议展开，通过标准化的工具接口实现远程与本地技能的能力对比与展示。
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 技术栈
| 类别 | 技术/框架 |
|------|----------|
| 运行时 | Bun |
| 开发语言 | TypeScript |
| 协议层 | @modelcontextprotocol/sdk |
| 数据验证 | Zod |
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 整体架构
项目采用分层架构设计，核心流程为：配置层 → MCP 工具注册 → 传输层（stdio 或 HTTP）。同时提供独立的 CLI 工具用于生成技能清单。
```mermaid
graph TD
A[配置文件] --> B[MCP 工具注册]
B --> C[stdio 传输模式]
B --> D[HTTP 传输模式]
E[CLI generate] --> F[GitHub 目录扫描]
F --> G[生成 Manifest Markdown]
H[下载技能] --> I[download_skill 工具]
J[推荐技能] --> K[suggest_skills 工具]
```
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 目录结构
### 源码目录 (`src/`)
| 文件 | 功能说明 |
|------|----------|
| `index.ts` | MCP 服务入口，工具注册与传输层初始化 |
| `config.ts` | 配置管理与验证逻辑 |
| `constants.ts` | 常量定义 |
| `utils.ts` | 通用工具函数 |
| `download.ts` | GitHub 目录下载功能 |
| `generate.ts` | Manifest 生成器核心逻辑 |
| `cmd_generate.ts` | CLI generate 命令实现 |
### 技能清单目录
| 目录 | 用途 |
|------|------|
| `official/` | 官方维护的技能清单 |
| `community/` | 社区贡献的技能清单 |
| `official/skills/` | 官方技能定义 |
| `community/skills/` | 社区技能定义 |
每个技能目录下应包含 `SKILL.md` 或 `DESIGN.md` 文件，用于描述技能的用途与触发条件。
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 核心模块
### 配置模块 (`src/config.ts`)
配置模块负责验证环境变量与命令行参数，确保 MCP 服务正常运行。
**关键环境变量：**
| 变量名 | 必需 | 说明 |
|--------|------|------|
| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |
**配置格式：**
```json
{
"manifestUrls": ["https://some/skill-manifest.md"]
}
```
GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
### GitHub 下载模块 (`src/download.ts`)
该模块封装了 GitHub API 调用，实现目录内容的递归下载。
**核心 API 交互：**
```mermaid
graph LR
A[buildContentsApiUrl] --> B[GET /repos/{owner}/{repo}/contents/{path}]
C[buildTreeApiUrl] --> D[GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1]
```
**主要函数：**
| 函数 | 功能 |
|------|------|
| `buildContentsApiUrl()` | 构建 GitHub Contents API URL |
| `buildTreeApiUrl()` | 构建 GitHub Trees API URL（支持递归） |
| `fetchDirectoryContents()` | 获取目录内容并解析为结构化条目 |
资料来源：[src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
### Manifest 生成模块 (`src/generate.ts`)
负责扫描技能目录并生成规范化的 Markdown 清单文件。
**处理流程：**
1. 遍历目录树，识别包含 `SKILL.md` 或 `DESIGN.md` 的目录
2. 收集同目录下的其他资源文件作为 bundled assets
3. 按目录层级组织输出
```mermaid
graph TD
A[遍历目录树] --> B{文件类型判断}
B -->|SKILL.md| C[标记为技能目录]
B -->|DESIGN.md| D[标记为设计目录]
B -->|其他资源| E[加入 bundled assets]
C --> F[按层级排序输出]
D --> F
```
资料来源：[src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
### CLI 生成命令 (`src/cmd_generate.ts`)
实现命令行工具的 generate 子命令，支持递归扫描和自定义输出目录。
**CLI 选项：**
| 选项 | 说明 |
|------|------|
| `-o `, `--output ` | 指定输出目录，默认为 `.agents/skills` |
| `generate [-r\|--recursive] ` | 从 GitHub URL 生成清单 |
| `server --port ` | 启动 HTTP 服务器 |
**生成的输出文件类型：**
| 文件后缀 | 内容来源 |
|----------|----------|
| `.skills.md` | 包含 `SKILL.md` 的技能目录 |
| `.designs.md` | 包含 `DESIGN.md` 的设计目录 |
| `.agents.md` | 平面化顶级 Markdown 文件 |
资料来源：[src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
## MCP 工具接口
### suggest_skills
推荐可用技能的 MCP 工具，根据用户需求返回相应的技能建议。
**输入参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `manifestUrl` | string | 否 | 覆盖默认配置的清单 URL |
**返回内容：**
生成指令负载，指导 Agent 如何获取、扫描、对比远程与本地技能，并展示推荐结果。
### fetch_manifest
获取指定清单文件内容的工具。
**输入参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `manifestUrl` | string | 是 | 清单文件的 URL |
### download_skill
下载 GitHub 文件夹中的所有文件。
**输入参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `url` | string | 是 | GitHub 文件夹 URL，格式：`https://github.com///tree/[/` |
**返回内容：**
文件夹内每个文件的相对路径、UTF-8 文本内容及类型信息。
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 传输模式
### stdio 模式
适用于本地进程间通信的标准化输入输出模式。
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP 模式
适用于网络化的 MCP 客户端连接。
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
**端点：**
| 端点 | 路径 | 说明 |
|------|------|------|
| MCP 服务 | `/mcp` | MCP 协议端点 |
| 健康检查 | `/health` | 服务健康状态 |
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 编码规范与设计原则
项目遵循以下实现模式：
| 原则 | 说明 |
|------|------|
| 模块化 | 小而专注的模块，按职责拆分文件 |
| 配置验证 | 通过 `ConfigError` 进行显式验证 |
| 类型安全 | 使用 Zod 验证工具模式和数据模型 |
| 结构化输出 | MCP 工具使用类型化 Schema |
| 传输抽象 | 最小化传输层封装，围绕共享服务构建 |
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 扩展方式
### 贡献新技能
1. 在 `community/skills/` 下创建技能目录
2. 添加 `SKILL.md` 文件描述技能用途与触发条件
3. 可选：添加相关资源文件作为 bundled assets
### 添加新的清单源
1. 在 `SUGGEST_SKILLS_MANIFEST_URLS` 中添加新的 URL
2. 遵循现有的 Markdown 清单格式
### 扩展 MCP 工具
新工具应：
- 在 `src/` 下创建独立的模块文件
- 使用 Zod 定义输入输出 Schema
- 在 `index.ts` 中注册到 MCP 服务
---
## MCP 工具
### 相关页面
相关主题：[传输模式](#transport-modes), [配置指南](#configuration-guide)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/core.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/core.ts)
- [src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# MCP 工具
## 概述
MCP 工具是 `suggest-skills` 项目实现的核心功能模块，基于 Model Context Protocol (MCP) 标准提供技能建议、清单获取和技能下载能力。该模块作为 MCP 服务器运行，支持 `stdio` 和 HTTP 两种传输模式，使 AI 代理能够动态发现和推荐可用技能。
MCP 工具的主要职责包括：
- 从配置的清单 URL 获取远程技能目录
- 扫描本地已安装的技能
- 对比远程与本地能力差异
- 向用户展示技能建议列表
- 下载指定 GitHub 文件夹中的所有文件
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 架构概览
```
Config -> MCP 工具注册 -> stdio 或 HTTP 传输
```
项目采用分层架构：
- **配置层**：环境变量和命令行参数解析
- **工具层**：三个核心 MCP 工具实现
- **传输层**：stdio 和 HTTP 两种通信协议支持
- **GitHub 交互层**：仓库扫描和文件下载
技术栈：Bun、TypeScript、@modelcontextprotocol/sdk、Zod
资料来源：[README.md:89-94](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 核心工具列表
| 工具名称 | 功能描述 | 输入参数 |
|---------|---------|---------|
| `suggest_skills` | 生成技能建议指令负载，指导代理如何获取和推荐技能 | `manifestUrl`（可选） |
| `fetch_manifest` | 获取指定清单 URL 的文本内容 | `manifestUrl`（必填） |
| `download_skill` | 下载 GitHub 文件夹中的所有文件 | `url`（必填） |
资料来源：[README.md:53-73](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## suggest_skills 工具
### 功能说明
`suggest_skills` 是默认的技能推荐工具，返回一个生成的指令负载。该负载指示代理如何：
1. 从配置的清单中获取可用技能
2. 扫描本地已安装的技能
3. 对比远程与本地的能力差异
4. 展示建议而不自动安装
### 参数定义
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| `manifestUrl` | string | 否 | 用于覆盖默认配置的清单 URL |
### 返回值
返回包含以下步骤的指令负载：
- 获取清单中的技能列表
- 本地技能扫描
- 差异对比分析
- 用户建议展示（仅在请求时安装）
资料来源：[src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)
## fetch_manifest 工具
### 功能说明
`fetch_manifest` 工具接受一个清单 URL 参数，返回该清单的完整文本内容。用于获取远程技能目录的详细描述。
### 参数定义
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| `manifestUrl` | string | 是 | 技能清单的 GitHub URL |
### 典型使用场景
- 获取第三方技能仓库的清单
- 动态更新本地缓存的技能列表
- 跨仓库技能发现
## download_skill 工具
### 功能说明
`download_skill` 工具用于下载 GitHub 文件夹中的所有文件，返回每个文件的相对路径、UTF-8 文本内容和符号链接信息。
### 参数定义
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| `url` | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |
### 返回数据结构
| 字段 | 类型 | 说明 |
|-----|------|------|
| `path` | string | 相对于请求文件夹的文件路径 |
| `download_url` | string \| null | 文件的直接下载 URL（目录为 null） |
| `type` | "file" \| "dir" | 条目类型 |
### GitHub URL 解析
工具内部通过以下步骤解析 GitHub 目录位置：
```typescript
interface GithubDirectoryLocation {
owner: string; // 仓库所有者
repo: string; // 仓库名称
ref: string; // 分支/标签/提交 SHA
path: string; // 目录路径
}
```
资料来源：[src/download.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
## 工作流程图
```mermaid
graph TD
A[启动 MCP 服务器] --> B{传输模式}
B -->|stdio| C[标准输入输出]
B -->|HTTP| D[HTTP 端点 /mcp]
C --> E[注册 MCP 工具]
D --> E
E --> F[suggest_skills]
E --> G[fetch_manifest]
E --> G --> H[获取清单文本]
E --> I[download_skill]
I --> J[解析 GitHub URL]
J --> K[调用 GitHub Contents API]
K --> L[递归获取目录树]
L --> M[构建下载条目列表]
M --> N[返回文件内容]
```
## 配置方式
### 环境变量
| 变量名 | 必填 | 说明 |
|-------|-----|------|
| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于已认证请求 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 URL 的清单地址 |
`SUGGEST_SKILLS_MANIFEST_URLS` 支持以下格式：
- JSON 数组：`["https://example.com/manifest.md"]`
- 逗号分隔字符串：`"url1,url2,url3"`
- 换行分隔字符串：`"url1\nurl2\nurl3"`
### CLI 选项
| 选项 | 说明 |
|-----|------|
| `-o ` / `--output ` | 安装技能的目标目录 |
| `generate [-r\|--recursive] ` | 从 GitHub 技能目录生成清单 |
| `server --port ` | 运行 HTTP 服务器 |
| `[...args]` | 以 stdio 模式运行（默认） |
默认输出目录：`.agents/skills`
资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## HTTP 模式
HTTP 服务器提供以下端点：
| 端点 | 方法 | 说明 |
|-----|------|------|
| `/mcp` | POST | MCP 工具调用端点 |
| `/health` | GET | 健康检查端点 |
默认端口：3100
### 启动命令
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' \
npx suggest-skills server --port 3100
```
## GitHub API 集成
### API 端点
| 功能 | API 端点 |
|-----|---------|
| 获取目录内容 | `/repos/{owner}/{repo}/contents/{path}` |
| 获取目录树 | `/repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1` |
### URL 转换
GitHub `blob` URL 自动转换为 `raw.githubusercontent.com` URL：
```typescript
function normalizeGithubRawUrl(url: string): string | null {
// 将 github.com/blob/ 转换为 raw.githubusercontent.com/
}
```
资料来源：[src/download.ts:40-70](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
## 类型定义
### ContentEntry
```typescript
interface ContentEntry {
path: string;
download_url: string | null;
type: "file" | "dir";
}
```
### CliRuntimeMode
```typescript
type CliRuntimeMode =
| { kind: "generate"; url: string; recursive: boolean; config: Config }
| { kind: "download"; url: string; recursive: boolean; config: Config }
| { kind: "server"; port: number }
| { kind: "stdio"; args: string[] };
```
### Config
```typescript
interface Config {
manifestUrls: string[];
outputDirectory: string;
githubPat?: string;
}
```
## 清单文件格式
清单文件为 Markdown 格式，支持以下结构：
```markdown
| 技能名称 | 描述 | 文件列表 |
|---------|------|---------|
| [skill-name](链接) | 功能说明 | `file1.md`, `assets/` |
```
生成模式自动扫描包含 `SKILL.md` 或 `DESIGN.md` 的目录。
资料来源：[src/generate.ts:1-80](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
## 最佳实践
### 1. 清单 URL 配置
建议使用多个清单源以覆盖更广泛的技能库：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='[
"https://raw.githubusercontent.com/anthropics/skills/main/README.md",
"https://raw.githubusercontent.com/openai/skills/main/README.md",
"https://raw.githubusercontent.com/sator-imaging/suggest-skills/main/README.md"
]'
```
### 2. 递归下载
对于包含子目录的技能文件夹，使用 `--recursive` 选项确保完整下载：
```bash
npx suggest-skills download --recursive \
https://github.com/owner/repo/tree/main/skills/my-skill
```
### 3. GitHub 认证
当访问私有仓库或需要更高 API 限额时，配置 `GITHUB_PAT`：
```bash
GITHUB_PAT=ghp_xxx npx suggest-skills fetch_manifest
```
## 相关文档
- [官方技能目录](../official/)
- [社区技能](../community/)
- [生成清单命令](./generate.md)
- [下载技能命令](./download.md)
---
## 传输模式
### 相关页面
相关主题：[系统架构](#system-architecture), [部署指南](#deployment-guide)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)
- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/cli.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cli.ts)
# 传输模式
## 概述
`suggest-skills` 项目实现了 MCP (Model Context Protocol) 服务器，支持两种传输模式用于与 AI 代理进行通信。这两种模式分别为 **stdio 模式** 和 **HTTP 模式**，它们共享相同的核心功能和 MCP 工具集，仅在通信机制上有所不同。
传输模式的选择直接影响工具调用方与应用服务器的交互方式：
- **stdio 模式**：适用于本地进程通信，通过标准输入/输出流传递 JSON-RPC 消息
- **HTTP 模式**：适用于网络远程调用，通过 HTTP REST API 提供 MCP 端点
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 架构设计
### 传输层抽象
项目采用传输层抽象设计，将核心业务逻辑与通信机制分离。配置层负责解析 CLI 参数并确定运行时模式，随后将控制权委托给对应的传输处理器。
```mermaid
graph TD
A[CLI 入口] --> B[配置解析]
B --> C{运行时模式}
C -->|stdio| D[stdio.ts]
C -->|server| E[http.ts]
D --> F[MCP 工具注册]
E --> F
F --> G[核心业务逻辑]
G --> H[suggest_skills]
G --> I[fetch_manifest]
G --> J[download_skill]
```
资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
### 运行时模式类型
`CliRuntimeMode` 联合类型定义了所有支持的运行时变体：
| 模式 | 标识 | 用途 | 传输协议 |
|------|------|------|----------|
| `stdio` | 默认模式 | 本地进程通信 | stdin/stdout JSON-RPC |
| `generate` | 生成模式 | 生成技能清单 | 仅 CLI |
| `download` | 下载模式 | 下载技能资源 | 仅 CLI |
| `server` | 服务模式 | HTTP 服务器 | HTTP/Streamable |
资料来源：[src/config.ts:1-50](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## stdio 模式
### 工作原理
stdio 模式是 MCP 协议的传统实现方式，服务器通过标准输入接收 JSON-RPC 请求，并通过标准输出返回响应消息。此模式无需网络配置，非常适合与本地 AI 代理进程集成。
### 启动方式
stdio 模式作为默认模式运行，当用户未指定任何子命令时自动激活：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
环境变量 `SUGGEST_SKILLS_MANIFEST_URLS` 为必需配置，必须包含至少一个技能清单 URL。
### 特性
- **零网络依赖**：无需开放端口，完全在本地运行
- **进程隔离**：每个会话创建独立进程
- **低延迟**：直接内存通信，无网络开销
- **标准化协议**：完全兼容 MCP JSON-RPC 规范
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## HTTP 模式
### 工作原理
HTTP 模式启动一个基于 Streamable HTTP 的 MCP 服务器，支持远程调用和持久化连接。此模式适用于需要跨网络访问 MCP 工具的场景。
### 端点配置
| 端点 | 路径 | 功能 |
|------|------|------|
| MCP 主端点 | `/mcp` | 处理所有 MCP 协议请求 |
| 健康检查 | `/health` | 服务状态验证 |
### 启动方式
使用 `server` 子命令启动 HTTP 服务器：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
### 端口配置
通过 `--port` 参数指定监听端口，默认情况下服务器绑定至 `0.0.0.0` 接受所有网络接口连接。
### 特性
- **远程访问**：支持跨网络调用 MCP 工具
- **持久连接**：支持流式响应和连接复用
- **健康监控**：内置健康检查端点便于运维监控
- **REST 兼容**：基于标准 HTTP 协议，易于集成
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 配置管理
### 环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `GITHUB_PAT` | 否 | GitHub API 认证令牌，用于提高 API 限制 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 技能清单 URL，支持 JSON 数组、逗号分隔或换行分隔格式 |
### 清单 URL 格式
清单 URL 支持多种格式：
```json
["https://some/skill-manifest.md"]
```
```text
https://some/skill-manifest.md,https://other/skill-manifest.md
```
GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## CLI 命令结构
### 命令速查表
| 命令 | 模式 | 说明 |
|------|------|------|
| `suggest-skills` | stdio | 默认启动 stdio 模式 |
| `suggest-skills server` | http | 启动 HTTP 服务器 |
| `suggest-skills generate ` | generate | 生成技能清单文档 |
| `suggest-skills download ` | download | 下载技能资源 |
### 全局选项
- `-o, --output `：设置技能安装输出目录，默认为 `.agents/skills`
### 生成模式选项
- `-r, --recursive`：启用递归扫描子目录
- `--url`：指定 GitHub 仓库路径
### 服务器模式选项
- `--port `：指定 HTTP 服务器监听端口
资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## MCP 工具集
无论采用哪种传输模式，以下 MCP 工具均可用：
### suggest_skills
返回生成的指令负载，指导代理如何：
- 获取已配置清单中的可用技能
- 扫描本地已安装技能
- 比较远程与本地能力
- 在用户请求前呈现建议而不安装任何内容
**参数**：`manifestUrl` (可选) - 覆盖默认配置的清单 URL
### fetch_manifest
获取指定清单 URL 的文本内容。
**参数**：`manifestUrl` - 清单 URL
### download_skill
下载 GitHub 文件夹中的所有文件。
**参数**：`url` - GitHub 文件夹 URL，格式为 `https://github.com///tree/[/`
返回每个文件包含：
- 相对于请求文件夹的路径
- UTF-8 文本内容
- 文件 symlink 的目标内容
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 模式选择指南
```mermaid
graph TD
A[开始] --> B{调用场景?}
B -->|本地 AI 代理| C[stdio 模式]
B -->|远程服务| D[HTTP 模式]
B -->|生成清单| E[generate 模式]
B -->|批量下载| F[download 模式]
C --> G[低延迟隔离环境]
D --> H[跨网络访问]
E --> I[生成 markdown 文档]
F --> J[获取技能文件]
```
### 选择建议
| 场景 | 推荐模式 | 原因 |
|------|----------|------|
| Claude Code 本地集成 | stdio | 无网络开销，即插即用 |
| 微服务架构 | HTTP | 支持远程调用和水平扩展 |
| 持续集成流水线 | stdio | 进程生命周期清晰 |
| Web 前端集成 | HTTP | 标准 REST 调用方式 |
| 技能库迁移 | generate/download | 专用 CLI 功能 |
## 技术栈
项目使用的核心技术：
| 技术 | 用途 |
|------|------|
| TypeScript | 主开发语言 |
| Bun | 运行时和打包工具 |
| @modelcontextprotocol/sdk | MCP 协议实现 |
| Zod | 配置验证和类型安全 |
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## 最佳实践
### 环境配置
```bash
# 生产环境建议
export GITHUB_PAT="your_personal_access_token"
export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/skills/README.md"]'
```
### 安全考量
- HTTP 模式部署时应配置 TLS 终止
- GitHub PAT 应存储在安全密钥管理系统中
- 避免在日志中输出敏感配置信息
### 性能优化
- stdio 模式适合高频低延迟场景
- HTTP 模式支持连接池和请求批处理
- 大型仓库建议使用递归模式以获取完整技能树
---
## Generate 命令
### 相关页面
相关主题：[项目结构](#project-structure), [配置指南](#configuration-guide)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
# Generate 命令
## 概述
Generate 命令是 suggest-skills 工具的核心功能之一，用于从 GitHub 仓库中扫描技能目录并生成标准化的 Markdown 清单文件。该命令通过递归扫描 GitHub 目录结构，自动发现包含 `SKILL.md`、`DESIGN.md` 的技能目录，并将其转换为可读的 Markdown 表格格式。
Generate 命令的主要职责包括：
- 扫描指定的 GitHub 仓库或目录路径
- 递归发现技能定义文件
- 收集每个技能的元数据（名称、描述、关联资产）
- 生成格式化的 Markdown 清单文件
- 支持可选的递归扫描模式
## 命令行接口
### 基本语法
```bash
npx suggest-skills generate
```
### 递归扫描模式
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `` | string | 是 | GitHub 仓库或目录的 URL |
| `-r, --recursive` | flag | 否 | 启用递归扫描模式，扫描所有子目录 |
## 工作流程
```mermaid
graph TD
A[用户执行 generate 命令] --> B[解析 GitHub URL]
B --> C{是否为递归模式?}
C -->|是| D[使用 Tree API 递归获取目录结构]
C -->|否| E[使用 Contents API 获取单层目录]
D --> F[扫描 SKILL.md 和 DESIGN.md 文件]
E --> F
F --> G[收集技能条目和资产信息]
G --> H[格式化 Markdown 表格]
H --> I[生成输出文件]
I --> J[写入 ...skills.md]
I --> K[写入 ...designs.md]
I --> L[写入 ...agents.md]
```
## 输出文件
执行 generate 命令后，会在当前工作目录生成以下文件：
| 文件类型 | 命名格式 | 内容描述 |
|----------|----------|----------|
| 技能清单 | `.[.].skills.md` | 包含 `SKILL.md` 的目录条目 |
| 设计清单 | `.[.].designs.md` | 包含 `DESIGN.md` 的目录条目 |
| 代理清单 | `.[.].agents.md` | 顶层 markdown 文件（仅含 Name 和 Description 列） |
### 生成的 Markdown 格式
```markdown
| Name | Description |
| -----|-------------|
| [skill-name](url) | skill description |
```
当启用资产包含选项时，格式扩展为：
```markdown
| Name | Description | Bundled Assets |
| -----|-------------|----------------|
| [skill-name](url) | description | LICENSE.txt, scripts (5 files) |
```
## 源码架构
### 核心模块职责
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| CLI 配置 | `src/config.ts` | 定义命令行参数解析和运行时模式 |
| 生成逻辑 | `src/cmd_generate.ts` | 处理 Markdown 表格格式化和条目输出 |
| 下载服务 | `src/download.ts` | 与 GitHub API 交互获取目录结构 |
### 运行时模式定义
```typescript
interface CliRuntimeMode {
kind: "generate" | "download" | "server" | "stdio";
url: string;
recursive: boolean;
config: {
outputDirectory: string;
sourceUrls: string[];
};
}
```
资料来源：[src/config.ts:32-38]()
### 表格格式化流程
```mermaid
graph LR
A[Entry 数据] --> B[formatRow 函数]
B --> C{includeAssets?}
C -->|是| D[格式化资产列]
C -->|否| E[仅输出名称和描述]
D --> F[escapeTableCell 转义特殊字符]
E --> F
F --> G[拼接 Markdown 行]
G --> H[生成完整表格]
```
## 表格单元格格式化
Generate 命令使用 `escapeTableCell` 函数处理单元格内容，防止 Markdown 表格解析错误。
### 转义规则
| 原字符 | 转义后 | 说明 |
|--------|--------|------|
| `|` | `\|` | 管道符会破坏表格结构 |
| 换行符 | 空格 | 单元格内容需保持单行 |
```typescript
function escapeTableCell(value: string): string {
return value.replaceAll("|", "\\|").replaceAll("\n", " ");
}
```
资料来源：[src/cmd_generate.ts:75-77]()
## 资产打包格式
当技能目录包含额外文件时，Generate 命令会将这些文件列为"关联资产"。
### 资产显示格式
| 资产数量 | 显示格式 | 示例 |
|----------|----------|------|
| 无资产 | `None` | `None` |
| 单文件 | 文件名 | `LICENSE.txt` |
| 多文件 | 文件名 + 计数 | `scripts` (5 files) |
| 文件夹 | 文件夹名 + 计数 | `assets` (4 files) |
### 内联资产数量限制
```typescript
const BUNDLED_ASSETS_INLINE_MAX_ITEMS = 3;
```
当资产数量超过 3 个时，Generate 命令会切换为计数显示模式，避免表格过宽。
## GitHub URL 处理
### URL 规范化
Generate 命令支持多种 GitHub URL 格式：
| 输入格式 | 处理方式 |
|----------|----------|
| `github.com/owner/repo/tree/main/path` | 自动转换为 API 端点 |
| `raw.githubusercontent.com/...` | 直接使用 |
| `github.com/owner/repo` | 扫描仓库根目录 |
### API 端点构建
```typescript
function buildContentsApiUrl(location: GithubDirectoryLocation): string {
const pathSuffix = location.path
.split("/")
.filter(Boolean)
.map((part) => encodeURIComponent(part))
.join("/");
const pathname = `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents/${pathSuffix}`;
const url = new URL(pathname, GITHUB_API_BASE_URL);
url.searchParams.set("ref", location.ref);
return url.toString();
}
```
资料来源：[src/download.ts:85-98]()
## 空输出处理
Generate 命令实现了智能的空输出检测机制，避免生成无意义的清单文件。
### 空文档判定
```typescript
function isEmptyGeneratedDocument(document: GeneratedDocument): boolean {
return document.markdown === "| Name | Description |\n| -----|-------------|\n"
|| document.markdown === "| Name | Description | Bundled Assets |\n| -----|-------------|----------------|\n";
}
```
资料来源：[src/cmd_generate.ts:64-68]()
当检测到空输出时：
- 不写入任何文件
- 不显示覆盖确认提示
- 静默跳过该类型清单
## 配置集成
Generate 命令可以通过环境变量进行配置：
### 环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `GITHUB_PAT` | 否 | GitHub 个人访问令牌，用于认证请求 |
| `SUGGEST_SKILLS_MANIFEST_URLS` | 是 | 至少包含一个 manifest URL |
### Manifest URL 格式
```bash
# JSON 数组格式
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]'
# 逗号分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='url1,url2,url3'
# 换行分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='url1
url2'
```
## 最佳实践
### 推荐使用场景
1. **初始化新仓库**：首次设置技能目录时生成清单
2. **同步更新**：每次技能更新后重新生成以保持文档最新
3. **多仓库管理**：使用递归模式扫描组织下的所有技能
### 性能注意事项
| 模式 | 适用场景 | API 调用次数 |
|------|----------|-------------|
| 非递归 | 单层目录结构 | 1-2 次 |
| 递归 | 多层嵌套技能 | N+1 次（根据深度） |
### GitHub API 限制
- 未认证请求：每小时 60 次
- 认证请求（使用 GITHUB_PAT）：每小时 5000 次
对于大型仓库或频繁使用场景，建议配置 `GITHUB_PAT` 环境变量。
## 完整使用示例
### 示例 1：扫描官方技能库
```bash
npx suggest-skills generate \
https://github.com/anthropics/skills/tree/main/skills
```
输出文件：
- `anthropics.skills.skills.md`
- `anthropics.skills.designs.md`
- `anthropics.skills.agents.md`
### 示例 2：递归扫描社区技能
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' \
npx suggest-skills generate \
--recursive \
https://github.com/ComposioHQ/awesome-claude-skills/tree/master
```
### 示例 3：集成到 CI/CD
```yaml
# .github/workflows/generate-skills.yml
name: Generate Skills Manifest
on:
schedule:
- cron: '0 0 * * *' # 每日执行
push:
branches:
- main
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate skills manifest
env:
GITHUB_PAT: ${{ secrets.GITHUB_PAT }}
SUGGEST_SKILLS_MANIFEST_URLS: '["https://raw.githubusercontent.com/anthropics/skills/main/skills-index.json"]'
run: npx suggest-skills generate --recursive https://github.com/anthropics/skills/tree/main/skills
```
## 相关命令
| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `download` | 下载技能到本地 | 本地开发或离线使用 |
| `server` | 启动 HTTP 服务 | 远程代理集成 |
| `stdio` | 标准输入输出模式 | 与 MCP 客户端集成 |
---
## Server 命令
### 相关页面
相关主题：[传输模式](#transport-modes), [部署指南](#deployment-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# Server 命令
## 概述
`server` 命令是 `suggest-skills` CLI 工具的核心运行模式之一，用于启动一个基于 HTTP 协议的 MCP（Model Context Protocol）流式服务器。该服务器提供了技能（Skills）发现、清单获取和技能下载等核心功能，使 AI 代理能够在运行时动态获取和推荐可用的技能扩展。
Server 命令的主要职责包括：
- 注册 MCP 工具接口
- 提供 RESTful HTTP 端点
- 处理技能清单的获取与解析
- 支持技能目录的下载功能
资料来源：[README.md:1-20]()
## 架构设计
### 技术栈
Server 命令基于以下技术构建：
| 组件 | 技术 | 用途 |
|------|------|------|
| 运行时 | Bun | 高性能 JavaScript 运行时 |
| 语言 | TypeScript | 类型安全开发 |
| 协议框架 | @modelcontextprotocol/sdk | MCP 标准协议实现 |
| 数据验证 | Zod | 运行时 Schema 验证 |
资料来源：[README.md:89-96]()
### 项目架构
```
Config -> MCP tool registration -> stdio or HTTP transport
CLI generate -> GitHub directory scan -> manifest markdown file
\-> GitHub URL normalization / folder download
```
整体架构遵循配置驱动、工具注册、传输层分离的设计模式。HTTP 传输作为独立的传输层实现，与 stdio 模式共享核心业务逻辑。
资料来源：[README.md:98-104]()
## 命令行接口
### 基本用法
```bash
npx suggest-skills server --port <端口号>
```
### 端口配置
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--port ` | 指定 HTTP 服务器监听端口 | 3100 |
配置示例：
```bash
# 启动服务器并指定端口
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
资料来源：[src/config.ts:30-33]()
## HTTP 端点
### 端点列表
| 端点 | 方法 | 功能 |
|------|------|------|
| `/mcp` | POST | MCP 协议主端点，处理工具调用 |
| `/health` | GET | 健康检查端点 |
### 服务地址
- **MCP 端点**: `http://localhost:<端口>/mcp`
- **健康检查**: `http://localhost:<端口>/health`
默认配置下：
- MCP 端点: `http://localhost:3100/mcp`
- 健康检查: `http://localhost:3100/health`
资料来源：[README.md:76-77]()
## MCP 工具
Server 命令注册了以下 MCP 工具供 AI 代理调用：
### suggest_skills
获取技能建议的工具，用于告知 AI 代理如何：
- 从配置的清单中获取可用技能
- 扫描本地已安装的技能
- 比较远程与本地能力
- 在用户请求前仅展示建议而不实际安装
**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| manifestUrl | string | 否 | 覆盖默认配置的清单 URL |
资料来源：[README.md:80-92]()
### fetch_manifest
获取指定清单 URL 的文本内容。
**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| manifestUrl | string | 是 | 清单文件的完整 URL |
资料来源：[README.md:94-97]()
### download_skill
下载 GitHub 文件夹中的所有文件。
**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| url | string | 是 | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |
**返回内容**:
- 文件相对路径
- UTF-8 编码的文本内容
- GitHub 提供的 symlink 目标内容
- 仓库相对目录 symlink 自动解析并递归下载
资料来源：[README.md:99-112]()
## 数据流程
### 技能下载流程
```mermaid
graph TD
A[download_skill 工具调用] --> B[解析 GitHub URL]
B --> C[构建 Contents API 请求]
C --> D[获取仓库 Tree SHA]
D --> E[递归获取文件树]
E --> F[处理 symlink 解析]
F --> G[构建下载 URL]
G --> H[返回文件内容列表]
I[buildGithubRawUrl] --> G
J[buildTreeApiUrl] --> D
```
### 清单生成流程
```mermaid
graph TD
A[generate 命令] --> B[扫描 GitHub 目录]
B --> C[递归发现 SKILL.md]
C --> D[收集同目录资产文件]
D --> E[构建 Markdown 表格]
E --> F[输出清单文件]
G[normalizeGithubRawUrl] --> A
```
资料来源：[src/download.ts:1-50](), [src/generate.ts:1-80]()
## 环境配置
### 必需环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| SUGGEST_SKILLS_MANIFEST_URLS | 是 | 技能清单 URL 列表 |
**支持的格式**:
- JSON 数组: `["url1", "url2"]`
- 逗号分隔字符串: `"url1,url2"`
- 换行分隔字符串: `"url1\nurl2"`
### 可选环境变量
| 变量名 | 说明 |
|--------|------|
| GITHUB_PAT | GitHub 个人访问令牌，用于对 api.github.com 的认证请求 |
### URL 自动转换
GitHub `blob` URLs 会自动转换为 `raw.githubusercontent.com` URLs。
资料来源：[README.md:120-138]()
## 代码实现
### 命令注册
Server 命令通过 `cac` CLI 框架注册：
```typescript
cli
.command("server [...args]", "Run the streamable HTTP server")
.option("--port ", "Port number")
.action(actions.onServer);
```
资料来源：[src/config.ts:30-33]()
### 运行时模式
Server 命令解析后生成以下运行时配置：
```typescript
{
kind: "server",
port: number,
config: {
manifestUrls: string[],
githubToken?: string
}
}
```
## 传输模式对比
| 特性 | stdio 模式 | HTTP 模式 |
|------|------------|-----------|
| 启动方式 | `npx suggest-skills` | `npx suggest-skills server --port 3100` |
| 通信协议 | 标准输入输出 | HTTP |
| 适用场景 | 本地 CLI 集成 | 远程服务部署 |
| 端点支持 | 无 | `/mcp`, `/health` |
| 并发支持 | 单会话 | 多会话 |
资料来源：[README.md:142-157]()
## 最佳实践
### 生产环境部署
1. **配置清单 URL**: 确保 `SUGGEST_SKILLS_MANIFEST_URLS` 包含所有必需的技能清单
2. **使用 GitHub Token**: 通过 `GITHUB_PAT` 提升 API 请求频率限制
3. **健康检查**: 定期调用 `/health` 端点验证服务状态
### 调试建议
- 使用 `--port` 参数指定非默认端口避免冲突
- 查看服务器日志确认 MCP 工具注册状态
- 使用 `curl http://localhost:/health` 快速验证服务
## 相关命令
| 命令 | 说明 |
|------|------|
| `suggest-skills generate` | 从 GitHub 目录生成技能清单 |
| `suggest-skills download` | 下载技能到本地目录 |
| `suggest-skills` | 以 stdio 模式运行（默认） |
资料来源：[src/config.ts:20-35]()
---
## 配置指南
### 相关页面
相关主题：[MCP 工具](#mcp-tools), [传输模式](#transport-modes)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# 配置指南
## 概述
`suggest-skills` 是一个基于 Model Context Protocol (MCP) 的技能建议工具，用于从 GitHub 仓库中发现、管理和推荐 AI 助手技能。该项目支持三种运行时模式：stdio 模式、HTTP 服务模式和生成模式，通过环境变量和命令行参数进行灵活配置。 资料来源：[README.md:1-50]()
## 核心配置架构
```mermaid
graph TD
A[环境变量配置] --> B[CLI 参数解析]
B --> C{运行时模式}
C -->|stdio| D[MCP stdio 传输]
C -->|server| E[MCP HTTP 服务]
C -->|generate| F[Manifest 生成器]
A1[`SUGGEST_SKILLS_MANIFEST_URLS`] --> A
A2[`GITHUB_PAT`] --> A
B1[`-o, --output`] --> B
B2[`-r, --recursive`] --> B
B3[`--port`] --> B
```
## 环境变量配置
### 必需配置
| 环境变量 | 说明 | 格式要求 | 示例 |
|---------|------|---------|------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 地址 | JSON 数组、逗号分隔或换行分隔 | 参见下方详细说明 |
`SUGGEST_SKILLS_MANIFEST_URLS` 是必需的配置文件，必须包含至少一个有效的清单 URL。支持的格式如下：
```bash
# JSON 数组格式
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]'
# 逗号分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'
# 换行分隔格式
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md
https://example.com/manifest2.md'
```
GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL。 资料来源：[README.md:70-90]()
### 可选配置
| 环境变量 | 说明 | 用途 |
|---------|------|------|
| `GITHUB_PAT` | GitHub 个人访问令牌 | 用于对 `api.github.com` 的认证请求，提高 API 限制 |
## 命令行接口配置
### 全局选项
| 选项 | 完整格式 | 说明 | 默认值 |
|-----|---------|------|-------|
| 输出目录 | `-o `, `--output ` | 安装技能的输出目录 | `.agents/skills` |
输出目录指定安装的技能文件存放位置，相对路径相对于当前工作目录。 资料来源：[src/config.ts:1-50]()
### 子命令配置
#### generate 命令
```bash
npx suggest-skills generate [--recursive, -r]
```
| 参数/选项 | 说明 |
|---------|------|
| `` | GitHub 仓库或技能目录 URL |
| `--recursive`, `-r` | 递归扫描子目录 |
生成模式会扫描指定 GitHub 路径下的所有技能目录，并生成以下文件：
- `.[.].skills.md` - 包含 `SKILL.md` 的技能目录清单
- `.[.].designs.md` - 包含 `DESIGN.md` 的设计目录清单
- `.[.].agents.md` - 平面顶级 Markdown 文件中的代理清单
空生成的输出会被跳过，不会覆盖现有文件。 资料来源：[README.md:40-65]()
#### download 命令
```bash
npx suggest-skills download [--recursive, -r]
```
下载技能、代理和设计文件到当前目录。使用 GitHub Contents API 递归获取文件内容。 资料来源：[src/download.ts:1-40]()
#### server 命令
```bash
npx suggest-skills server [--port ]
```
| 选项 | 说明 | 默认值 |
|-----|------|-------|
| `--port ` | HTTP 服务监听端口 | `3100` |
HTTP 服务提供两个端点：
- `http://localhost:/mcp` - MCP 协议端点
- `http://localhost:/health` - 健康检查端点
```mermaid
graph LR
A[客户端] -->|HTTP 请求| B[MCP 端点 /mcp]
A -->|健康检查| C[Health 端点 /health]
B --> D[技能清单处理]
C --> E[服务状态返回]
```
#### stdio 模式（默认）
当不指定任何子命令时，工具以 stdio 模式运行，作为 MCP 服务器通过标准输入输出通信：
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]' npx suggest-skills
```
## 配置验证机制
### ConfigError 异常处理
项目通过 `ConfigError` 类进行显式配置验证，任何配置错误都会抛出该异常并终止程序执行。这确保了配置问题在启动阶段就能被发现。 资料来源：[src/config.ts:1-20]()
### 运行时模式解析
配置解析流程如下：
```mermaid
graph TD
A[解析 process.argv] --> B[解析环境变量]
B --> C{命令类型判断}
C -->|generate| D[设置 generate 运行时模式]
C -->|download| E[设置 download 运行时模式]
C -->|server| F[设置 server 运行时模式]
C -->|无命令| G[设置 stdio 运行时模式]
D --> H[构建配置对象]
E --> H
F --> H
G --> H
```
每个运行时模式包含以下配置属性：
| 属性 | 说明 |
|-----|------|
| `kind` | 模式类型：`generate`、`download`、`server`、`stdio` |
| `url` | GitHub URL（generate/download 模式） |
| `recursive` | 是否递归扫描 |
| `config` | 通用配置对象 |
## MCP 工具配置
### suggest_skills 工具
核心建议工具，接受可选的 `manifestUrl` 参数覆盖默认配置。返回生成的指令载荷，指导代理如何：
- 从配置的清单获取可用技能
- 扫描本地安装的技能
- 比较远程和本地能力
- 在请求安装前呈现建议
### fetch_manifest 工具
接受清单 URL 并返回其文本内容。
### download_skill 工具
接受 GitHub 文件夹 URL 格式：
```
https://github.com///tree/[/
```
返回文件夹中的每个文件，包含相对路径、UTF-8 文本内容和符号链接信息。 资料来源：[README.md:100-130]()
## 清单文件格式
### 技能清单结构
清单文件采用 Markdown 表格格式，每行包含技能名称（链接）、描述和捆绑资源：
```markdown
| Name | Description | Bundled Assets |
|------|-------------|----------------|
| [skill-name](url) | Description text | `file1.txt`, `dir/` (3 files) |
```
### Manifest 加载流程
```mermaid
sequenceDiagram
participant CLI as CLI 工具
participant Config as 配置模块
participant Manifest as 清单 URL
participant MCP as MCP 服务器
CLI->>Config: 解析环境变量
Config->>Manifest: 获取清单内容
Manifest-->>Config: 返回 Markdown
Config->>MCP: 注册工具和资源
MCP->>CLI: 服务就绪
```
## 常见配置场景
### 场景一：本地开发环境
```bash
# 设置清单源
export SUGGEST_SKILLS_MANIFEST_URLS='["https://raw.githubusercontent.com/anthropics/skills/main/official/skills.skills.md"]'
# 以 stdio 模式运行
npx suggest-skills
```
### 场景二：HTTP 服务部署
```bash
# 设置清单源（多源）
export SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest1.md","https://example.com/manifest2.md"]'
# 自定义端口
npx suggest-skills server --port 8080
```
### 场景三：从 GitHub 生成清单
```bash
# 递归扫描官方技能
npx suggest-skills generate https://github.com/anthropics/skills/tree/main/skills --recursive
# 单层扫描
npx suggest-skills generate https://github.com/anthropics/skills/tree/main/official/skills
```
## 技术栈配置依赖
项目使用以下技术栈构建，所有配置都围绕这些核心依赖展开：
| 技术 | 用途 | 配置关联 |
|-----|------|---------|
| Bun | 运行时和打包 | `package.json` 定义脚本入口 |
| TypeScript | 类型安全 | 编译配置 |
| @modelcontextprotocol/sdk | MCP 协议实现 | 工具和资源注册 |
| Zod | 配置验证 | 环境变量和参数 schema |
## 配置最佳实践
1. **环境变量优先**：优先通过环境变量配置清单 URL，避免硬编码
2. **使用认证令牌**：生产环境建议配置 `GITHUB_PAT` 以提高 API 限制
3. **指定输出目录**：使用 `-o` 选项明确指定技能安装位置
4. **递归扫描谨慎使用**：大仓库递归扫描会增加 API 调用次数
5. **健康检查监控**：部署 HTTP 服务时定期检查 `/health` 端点
---
## 部署指南
### 相关页面
相关主题：[传输模式](#transport-modes), [Server 命令](#server-command)
]
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# 部署指南
本页面详细说明 `suggest-skills` 项目的部署方式、配置方法及运行模式。该项目是一个基于 MCP（Model Context Protocol）的技能推荐服务器，支持通过命令行工具生成技能清单以及作为 MCP 服务器运行。
## 系统要求
| 组件 | 要求 | 说明 |
|------|------|------|
| Node.js | v18+ | 运行 MCP 服务器的基础环境 |
| 包管理器 | npm / yarn / pnpm | 安装项目依赖 |
| 可选认证 | GitHub Personal Access Token | 提高 GitHub API 请求速率限制 |
资料来源：[README.md:1-10]()
## 安装方式
### 通过 npm 全局安装
```bash
npm install -g suggest-skills
```
### 通过 npx 直接运行
```bash
npx suggest-skills
```
### 从源码构建
```bash
git clone https://github.com/sator-imaging/suggest-skills.git
cd suggest-skills
npm install
npm run build
```
## 环境变量配置
### 必需配置
| 环境变量 | 说明 | 格式要求 |
|----------|------|----------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | 技能清单 URL 列表 | JSON 数组、逗号分隔字符串或换行分隔字符串 |
```bash
# JSON 数组格式
export SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md"]'
# 逗号分隔格式
export SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest1.md,https://example.com/manifest2.md'
```
### 可选配置
| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `GITHUB_PAT` | GitHub 个人访问令牌 | 无 |
`GITHUB_PAT` 用于对 `api.github.com` 的认证请求，可有效提高 API 速率限制。
```bash
export GITHUB_PAT="ghp_xxxxxxxxxxxx"
```
资料来源：[README.md:1-20]()
## 运行模式
### stdio 模式
stdio 模式适用于与本地 MCP 客户端直接集成，通过标准输入输出进行通信。
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
此模式适合集成到支持 MCP 协议的开发工具中。
### HTTP 服务器模式
HTTP 模式提供网络 HTTP 接口，适合远程访问和分布式架构部署。
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
#### 服务端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/mcp` | GET/POST | MCP 协议主端点，处理技能推荐请求 |
| `/health` | GET | 健康检查端点，验证服务状态 |
```text
http://localhost:3100/mcp # MCP 协议端点
http://localhost:3100/health # 健康检查端点
```
资料来源：[README.md:20-35]()
## 命令行接口
### generate 命令
生成技能清单文档，从 GitHub 仓库扫描技能目录。
```bash
npx suggest-skills generate
```
#### 参数说明
| 参数 | 说明 | 示例 |
|------|------|------|
| `` | GitHub 仓库或目录 URL | `https://github.com/OWNER/REPO/tree/main/skills` |
| `-r, --recursive` | 递归扫描子目录 | 扫描嵌套的技能目录 |
#### 基本用法
```bash
# 从 skills 目录生成清单
npx suggest-skills generate https://github.com/OWNER/REPO/tree/main/skills
# 递归生成所有嵌套技能
npx suggest-skills generate --recursive https://github.com/OWNER/REPO/tree/main/skills
```
#### 输出文件
generate 命令会在当前工作目录生成以下文件：
| 文件类型 | 命名规则 | 内容 |
|----------|----------|------|
| 技能清单 | `.[.].skills.md` | 包含 SKILL.md 的目录条目 |
| 设计清单 | `.[.].designs.md` | 包含 DESIGN.md 的目录条目 |
| 智能体清单 | `.[.].agents.md` | 顶级 markdown 智能体定义 |
#### 扫描规则
```mermaid
graph TD
A[GitHub URL] --> B{--recursive 参数}
B -->|否| C[扫描直接子目录]
B -->|是| D[递归扫描所有子目录]
C --> E[发现 SKILL.md 或 DESIGN.md]
D --> E
E --> F[收集同目录资源文件]
F --> G[生成清单文件]
```
- GitHub `blob` URL 会自动转换为 `raw.githubusercontent.com` URL
- 符号链接会被下载但不递归遍历
- 空生成的输出会被跳过，不写入文件
资料来源：[README.md:35-60]()
### server 命令
启动 HTTP 服务器运行 MCP 端点。
```bash
npx suggest-skills server --port
```
#### 参数说明
| 参数 | 说明 | 默认值 |
|------|------|------|
| `--port, -p` | HTTP 服务器监听端口 | 3100 |
### CLI 选项汇总
| 选项 | 说明 | 适用于 |
|------|------|--------|
| `-o ` | 技能安装输出目录 | install |
| `--recursive` | 递归扫描子目录 | generate |
| `--port ` | HTTP 服务器端口 | server |
资料来源：[README.md:15-25]()
## MCP 工具接口
### suggest_skills
推荐可用技能的工具。
| 参数 | 类型 | 说明 |
|------|------|------|
| `manifestUrl` | string (可选) | 覆盖默认配置的清单 URL |
**返回内容**：生成的指令负载，指导智能体如何获取技能、扫描本地安装、对比远程与本地能力。
### fetch_manifest
获取清单文件内容。
| 参数 | 类型 | 说明 |
|------|------|------|
| `manifestUrl` | string | 清单文件 URL |
**返回内容**：清单文件的原始文本内容。
### download_skill
下载技能目录中的所有文件。
| 参数 | 类型 | 说明 |
|------|------|------|
| `url` | string | GitHub 文件夹 URL，格式为 `https://github.com///tree/[/` |
**返回内容**：文件夹中每个文件的路径、UTF-8 文本内容及符号链接信息。
```mermaid
graph LR
A[MCP 客户端] -->|suggest_skills| B[返回推荐指令]
A -->|fetch_manifest| C[获取清单]
A -->|download_skill| D[下载技能文件]
B --> E[用户选择技能]
E --> D
D --> F[本地文件]
```
## Docker 部署（推荐架构）
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
ENV SUGGEST_SKILLS_MANIFEST_URLS="https://raw.githubusercontent.com/anthropics/skills/main/skills/skills.md"
EXPOSE 3100
CMD ["npx", "suggest-skills", "server", "--port", "3100"]
```
### Docker Compose 编排
```yaml
version: '3.8'
services:
suggest-skills:
image: suggest-skills:latest
ports:
- "3100:3100"
environment:
- SUGGEST_SKILLS_MANIFEST_URLS=https://example.com/manifest.md
- GITHUB_PAT=${GITHUB_PAT}
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "--spider", "-q", "http://localhost:3100/health"]
interval: 30s
timeout: 10s
retries: 3
```
## 项目架构
```mermaid
graph TD
subgraph 配置层
A[环境变量] --> B[Config 模块]
B --> C[配置验证]
end
subgraph 核心层
D[MCP 服务器] --> E[工具注册]
F[CLI 工具] --> G[GitHub 目录扫描]
G --> H[清单生成器]
end
subgraph 传输层
I[stdio 传输]
J[HTTP 传输]
end
B --> D
B --> F
E --> I
E --> J
H --> K[Markdown 输出]
```
### 核心模块
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| MCP 工具注册 | `src/mcp/` | 注册 suggest_skills、fetch_manifest、download_skill 工具 |
| 配置管理 | `src/config.ts` | 验证环境变量，处理配置错误 |
| GitHub API | `src/download.ts` | 目录内容获取、树形结构扫描 |
| 清单生成 | `src/generate.ts` | 解析 SKILL.md、DESIGN.md 生成清单文档 |
## 故障排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| `SUGGEST_SKILLS_MANIFEST_URLS` 未设置 | 环境变量缺失 | 设置至少一个清单 URL |
| GitHub API 速率限制 | 未使用认证令牌 | 配置 `GITHUB_PAT` 环境变量 |
| 清单生成无输出 | 目录中无 SKILL.md 或 DESIGN.md | 确认目标目录包含技能定义文件 |
| HTTP 端口占用 | 端口已被占用 | 使用 `--port` 指定其他端口 |
### 健康检查
部署后验证服务状态：
```bash
curl http://localhost:3100/health
```
正常响应返回 HTTP 200 状态码。
### 日志级别
通过环境变量启用调试日志：
```bash
DEBUG=suggest-skills:* npx suggest-skills server --port 3100
```
## 最佳实践
1. **始终设置 GitHub PAT**：生产环境建议配置认证令牌以避免 API 限制
2. **使用版本化的清单 URL**：避免清单更新导致行为不一致
3. **配置健康检查**：容器编排中设置健康检查探针
4. **分离配置与部署**：使用环境变量管理配置，便于不同环境切换
5. **限制网络暴露**：stdio 模式优先用于敏感环境
资料来源：[README.md:1-80]()
---
---
## Doramagic 踩坑日志
项目：sator-imaging/suggest-skills
摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.
## 3. 运行坑 · 来源证据：v1.0.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。
## 4. 运行坑 · 来源证据：v1.1.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。
## 5. 运行坑 · 来源证据：v1.2.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。
## 6. 运行坑 · 来源证据：v1.3.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 维护坑 · 来源证据：v1.0.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 维护坑 · 来源证据：v1.0.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 来源证据：v2.0.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing
## 11. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium
## 12. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown
]