内容
<p align="center">
<img src="assets/rolecraft_logo.png" alt="RoleCraft" width="200" height="200">
</p>
<h1 align="center">RoleCraft</h1>
<p align="center">
<b>安装 AI 代理技能作为角色和行为 — 来自任何来源。</b><br>
零依赖 CLI。技能 + MCP 服务器。无应用商店。无需注册。
</p>
<p align="center">
<a href="https://awesome.re"><img src="https://awesome.re/badge.svg" alt="Awesome"></a>
<a href="https://skills.sh/sametcelikbicak/rolecraft"><img src="https://skills.sh/b/sametcelikbicak/rolecraft" alt="skills.sh"></a>
<a href="https://www.npmjs.com/package/rolecraft"><img src="https://img.shields.io/npm/v/rolecraft" alt="npm"></a>
<a href="https://www.npmjs.com/package/rolecraft"><img src="https://img.shields.io/npm/dm/rolecraft" alt="npm downloads"></a>
<a href="https://github.com/sametcelikbicak/rolecraft/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/sametcelikbicak/rolecraft/test.yml?label=tests" alt="Tests"></a>
<a href="https://github.com/sametcelikbicak/rolecraft/actions/workflows/codeql.yml"><img src="https://img.shields.io/github/actions/workflow/status/sametcelikbicak/rolecraft/codeql.yml?label=CodeQL" alt="CodeQL"></a>
<a href="https://github.com/sametcelikbicak/rolecraft/blob/main/.github/dependabot.yml"><img src="https://img.shields.io/badge/dependabot-enabled-025e8c?logo=Dependabot" alt="Dependabot"></a>
<a href="https://github.com/sametcelikbicak/rolecraft"><img src="https://img.shields.io/github/stars/sametcelikbicak/rolecraft?style=social" alt="Stars"></a>
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/📜-Changelog-blue" alt="Changelog"></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/🤝-Contributing-green" alt="Contributing"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
<a href="https://sametcelikbicak.github.io/rolecraft/"><img src="https://img.shields.io/badge/📖-Docs%20site-blue" alt="Docs"></a>
<a href="package.json"><img src="https://img.shields.io/node/v/rolecraft" alt="Node"></a>
<a href="docs/security.md"><img src="https://img.shields.io/badge/🔒-security%20scoring-brightgreen" alt="Security scoring"></a>
<a href="CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/📖-Code%20of%20Conduct-orange" alt="Code of Conduct"></a>
<a href="SUPPORT.md"><img src="https://img.shields.io/badge/💬-Support-blue" alt="Support"></a>
</p>
<p align="center">
<a href="https://www.producthunt.com/products/rolecraft?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-rolecraft" target="_blank" rel="noopener noreferrer"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1184576&theme=light&t=1782890843931" alt="Product Hunt" width="200"></a>
</p>
<p align="center">
支持 <b>82+ AI 代理</b>: opencode · claude-code · cursor · windsurf · devin · codex · copilot · aider · cline · gemini-cli · cody · continue · warp · codeium · fabric · goose · tabnine · supermaven · pr-pilot · loom · roo · trae · hermes · kiro · augment · kilo · openhands · junie · factory · command-code · cortex · mistral-vibe · qwen-code · openclaw · codebuddy · mux · pi · autohand-code · rovo · firebender · bob · aider-desk · 等等
</p>
<p align="center">
<a href="#quick-start">快速开始</a> ·
<a href="#who-is-this-for">适用人群</a> ·
<a href="#features">功能</a> ·
<a href="#commands-overview">命令概述</a> ·
<a href="#faq">常见问题</a> ·
<a href="docs/security.md">安全</a> ·
<a href="CONTRIBUTING.md">贡献</a>
</p>
<p align="center">
<img src="assets/rolecraft-demo.gif" alt="RoleCraft demo" width="720">
</p>
---
<p align="center">
<b>⚡ 零依赖</b> · <b>📦 4 KB</b> · <b>🤖 82+ 代理</b> · <b>🔌 技能 + MCP</b> · <b>🔒 无遥测</b> · <b>🌐 离线优先</b> · <b>🔧 任意来源</b>
</p>
<p align="center">
<a href="benchmark/RESULTS.md"><img src="benchmark/comparison.svg" alt="Benchmark: 434x faster than Vercel" width="600"></a>
<br>
<a href="benchmark/RESULTS.md"><b>完整基准测试结果 →</b></a>
<a href="docs/comparison.md"><b>完整功能比较 →</b></a>
<a href="docs/migration-from-skills.md"><b>从 Vercel 迁移 →</b></a>
</p>
---
## 适用人群
| 如果您... | RoleCraft 帮助您... |
|-----------|----------------------|
| 使用 AI 编码代理（Claude, Cursor, Copilot 等） | 安装可重用的技能，以便您的代理在每个会话中不再重新学习您的项目 |
| 维护团队约定 | 在整个团队中共享一个技能仓库 — 无需复制/粘贴 |
| 运行 CI/CD 管道 | 基于锁定文件的 `rolecraft ci` 以确定性方式重新安装技能 |
| 构建代理技能 | 从一个来源为 82+ 代理构建、测试和分发技能 |
| 关注安全 | 内置 0–100 安全评分，阻止提示注入、命令注入和凭证收集 |
---
## 入门指南：零到生产力只需一条命令
新项目？新团队成员？一条命令即可安装技能 + MCP 服务器 + 约定到**每个 AI 代理**：
```bash
# 全局安装
npm install -g rolecraft
# 一条命令：检测所有代理 + 安装技能 + MCP 服务器
rolecraft setup sametcelikbicak/task-decomposer
```
就是这样。该技能现在在您使用的所有代理中都已启用 — opencode、cursor、claude-code、copilot、aider 等等。 [→ 完整入门指南](docs/guides/onboarding.md)
## 快速开始
```bash
# 尝试使用而无需安装
npx rolecraft --help
# 或全局安装（支持 npm、pnpm、yarn、bun）
npm install -g rolecraft
# 创建一个技能
rolecraft init my-skill
# 安装它
rolecraft install ./my-skill # 本地文件夹
rolecraft install user/repo # GitHub 仓库
rolecraft install https://gitlab.com/org/project # GitLab 仓库
rolecraft install git@github.com:user/repo.git # SSH URL
rolecraft install npm:some-package # npm 包
rolecraft install npm:@scope/package@1.0.0 # npm 带有版本号
rolecraft install ./my-skill --cursor # 仅限特定代理
# 安装带有 MCP 服务器的技能（在 SKILL.md 中声明）
rolecraft install ./my-postgres-rules --cursor
# 或独立管理 MCP 服务器
rolecraft mcp install npm:@modelcontextprotocol/github --cursor
# 或安装 RoleCraft 技能（教 AI 代理使用 RoleCraft）
npx skills add sametcelikbicak/rolecraft
# 管理
rolecraft list
rolecraft search code-review
rolecraft check
rolecraft remove my-skill
```
**要求：** Node.js >= 20 · 无其他依赖 · 支持 82+ 代理 · [完整安装指南 →](docs/install.md)
> **为什么是零依赖？** 每个依赖都是一个风险 — 供应链攻击、破坏性更改、膨胀的 `node_modules`。RoleCraft 仅使用 Node.js 内置模块（`fs`、`path`、`crypto`、`https`）。整个 CLI 约 4 KB。无需 `npm install` 惊喜。
---
## 功能
- **零依赖** — ~4 KB，无膨胀
- **任意来源** — 本地文件夹、GitHub/GitLab/Bitbucket 仓库、SSH git URL、npm 包
- **MCP + 技能一体化** — 一条命令安装技能及其 MCP 服务器。其他 CLI 工具不具备此功能。
- **82+ 代理** — opencode、claude-code、cursor、copilot、aider、devin、gemini-cli 等等
- **与 skills.sh 兼容** — 可通过 `npx skills add sametcelikbicak/rolecraft` 安装
- **无需注册** — 无需注册、无应用商店、无供应商锁定
- **安全评分** — 安装时静态分析：检测提示注入、命令注入、混淆代码、凭证收集和敏感文件访问。评分 0–100。除非 `--yes`，否则阻止危险技能
- **非交互模式** — `--yes` / `-y` 标志用于自动化/CI 管道
- **更新检查** — `rolecraft check` 查看哪些技能有更新
- **Shell 补全** — bash、zsh、fish 自动补全
- **TUI 搜索** — 交互式箭头键技能浏览器，支持预览
- **内容哈希验证** — 检测篡改或过时的技能
- **CI 准备** — 基于锁定文件的管道重新安装
- **干燥运行模式** — 安装前预览
- **系统健康检查** — `rolecraft doctor` 诊断 Node.js、代理目录、锁定文件和技能完整性
- **AGENTS.md XML 生成** — `rolecraft agents-xml` 生成适用于 AGENTS.md 的 Claude Code 兼容 `<skills_system>` XML
---
## 技能 + MCP 一体化
RoleCraft 是**唯一**一个将代理技能和 MCP 服务器一起安装的 CLI。
当 SKILL.md 在其 frontmatter 中声明 MCP 服务器时：
```yaml
---
name: postgres-rules
mcp_servers:
- name: postgres
source: npm:@modelcontextprotocol/postgres
---
```
`rolecraft install ./postgres-rules --cursor` 安装技能和 MCP 服务器 — 一条命令，无需单独的工具。
您也可以独立管理 MCP 服务器：
```bash
rolecraft mcp install npm:@modelcontextprotocol/github --cursor
rolecraft mcp list
rolecraft mcp remove postgres
```
[→ 完整 MCP 文档](docs/mcp.md)
---
## 命令概述
| 命令 | 描述 | 详情 |
| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------ |
| `rolecraft init [<name>]` | 搭建一个新的 `SKILL.md` | [文档](docs/commands/init.md) |
| `rolecraft install <source>` | 安装技能并进行安全扫描（本地路径、GitHub/GitLab/SSH URL、npm） | [文档](docs/commands/install.md) |
| `rolecraft bundle <sources>` | 从内联源或文件安装多个技能 | [文档](docs/commands/bundle.md) |
| `rolecraft bundle create` | 创建一个新的 bundle 文件 | [文档](docs/commands/bundle.md) |
| `rolecraft search <query>` | 在 GitHub 上搜索技能（支持 TUI 和 `--interactive`） | [文档](docs/commands/search.md) |
| `rolecraft check` | 检查已安装的技能是否有可用的更新 | [文档](docs/commands/check.md) |
| `rolecraft use <source>` | 在安装前预览技能的文件 | [文档](docs/commands/use.md) |
| `rolecraft completions bash\|zsh\|fish` | 生成 Shell 补全脚本 | [文档](docs/commands/completions.md) |
| `rolecraft setup [<source>]` | 检测代理，可选安装技能到所有 | [文档](docs/commands/setup.md) |
| `rolecraft list` | 显示所有已安装的技能 | [文档](docs/commands/list.md) |
| `rolecraft doctor` | 运行系统健康检查 | [文档](docs/commands/doctor.md) |
| `rolecraft agents-xml [--write]` | 生成 AGENTS.md 的技能 XML | [文档](docs/commands/agents-xml.md) |
| `rolecraft mcp install/remove/list` | 安装、删除和列出 AI 代理的 MCP 服务器 | [文档](docs/commands/mcp.md) |
| `rolecraft profile save/apply/list` | 保存、应用和共享多代理配置配置文件 | [文档](docs/commands/profile.md) |
| `rolecraft verify` | 通过内容哈希检查已安装的技能完整性 | [文档](docs/commands/verify.md) |
| `rolecraft watch [<slug>]` | 监视技能变化并自动同步 | [文档](docs/commands/watch.md) |
| `rolecraft ci` | 从锁定文件重新安装所有技能（CI 模式） | [文档](docs/commands/ci.md) |
| `rolecraft upgrade` | 升级 RoleCraft 到最新版本 | [文档](docs/commands/upgrade.md) |
| `rolecraft remove <slug>` | 卸载技能 | [文档](docs/commands/remove.md) |
| `rolecraft update <slug>` | 重新安装技能到最新版本 | [文档](docs/commands/update.md) |
| `rolecraft --version` | 显示版本 | |
---
## 为什么选择 RoleCraft
[→ 完整功能比较](docs/comparison.md)
| 功能 | RoleCraft | skills (Vercel) | @agentskill.sh/cli |
| ------------------------------------ | ---------------- | --------------- | ------------------- |
| 零依赖 | ✅ **0** | ✅ (1 依赖) | ❌ (2) |
| 本地路径安装 | ✅ **一等公民** | ✅ | ❌ 仅限应用商店 |
| GitHub 仓库安装 | ✅ | ✅ | ❌ |
| GitLab / SSH git URL | ✅ | ✅ | ❌ |
| npm 包源 | ✅ | ✅ | ❌ |
| **MCP 服务器管理** | ✅ | ❌ | ❌ |
| 代理目标 | **82** | 72 | 15+ |
| skills.sh 列表 | ✅ | ✅ | ⚠️ (仅限注册) |
| 捆绑安装 + 创建 | ✅ | ❌ | ✅ (仅限技能集) |
| 交互式 TUI 搜索 + 安装 | ✅ | ✅ | ❌ |
| 安全评分 (0–100) | ✅ | ✅ (Snyk) | ✅ (服务器 + 本地) |
| 非交互标志 (`--yes`/`-y`) | ✅ | ✅ | ❌ |
| 技能更新检查 (`check`) | ✅ | ❌ | ❌ |
| Shell 补全 (bash/zsh/fish) | ✅ | ❌ | ❌ |
| 干燥运行预览 (`--dry-run`) | ✅ | ❌ | ❌ |
| 交互式范围提示 | ✅ | ✅ | ❌ |
| 内容哈希验证 (`verify`) | ✅ | ✅ | ❌ |
| CI 模式重新安装 (`ci`) | ✅ | ✅ | ❌ |
| 系统健康检查 (`doctor`) | ✅ | ❌ | ❌ |
| 监视模式 (auto-sync) | ✅ | ❌ | ❌ |
| AGENTS.md XML 生成 | ✅ | ❌ | ❌ |
| 自升级命令 | ✅ | ❌ | ❌ |
| 文件大小 | ~4 KB | ~465 KB | ~84 KB |
[查看完整表格 →](docs/comparison.md)
---
## 安全
每次安装都会自动扫描静态分析以检测：
| 严重性 | 它捕获什么 |
|----------|----------------|
| 🔴 关键 | 提示注入、混淆代码（base64 块、`eval()`）、命令注入（下载并执行） |
| 🟡 高 | 凭证收集模式、敏感文件访问 (`~/.ssh`、`.env`) |
| 🟢 中/低 | 缺失的元数据、不寻常的源模式 |
评分范围 **约4 KB | ~465 KB | ~84 KB |
[→ 完整安全文档](docs/security.md)
---
## 代理如何发现技能
RoleCraft 知道每个 AI 代理在哪里查找技能。使用 `--claude`、 `--cursor`、 `--devin` 等标志来针对特定代理，或使用 `--all` 来支持所有代理。
[→ 完整代理路径表](docs/agents.md)
```bash
# 一次安装多个代理
rolecraft install ./my-skill --cursor --devin --copilot --gemini --cody
```
---
## 架构
1. 从源读取 `SKILL.md` 并解析元数据（slug、名称、所有者）
2. 对所有技能文件运行**安全扫描** — 检查提示注入、命令注入、混淆代码、凭证收集和敏感文件访问。 评分 0–100。 除非 `--yes`，否则阻止危险技能
3. 将所有文件复制（或使用 `--symlink` 进行符号链接）到目标目录
4. 计算 SHA256 内容哈希并将其存储在锁定文件中
5. 更新 `~/.agents/.skill-lock.json` 以便代理可以发现技能
6. 与 `@agentskill.sh/cli`、`add-skill` 或手动安装的技能兼容
7. 可作为技能本身通过 `npx skills add sametcelikbicak/rolecraft` 安装
[→ 完整架构和项目结构](docs/architecture.md)
---
## 常见问题
**问：我需要注册或登录吗？**
答：不需要。无需账户，无需 API 密钥，无需市场。只需将 rolecraft 指向任何文件夹或仓库，它就会生效。
**问：我可以使用多个 AI 代理与 rolecraft 吗？**
答：可以。支持 82+ 个代理。使用 `--cursor`、`--claude`、`--devin` 标志或 `--all` 以适用于所有代理。
**问：rolecraft 会发送遥测数据吗？**
答：不会。零数据离开您的机器。安全扫描在本地运行。无任何数据发送。
**问：这与 `npx skills`（Vercel）有何不同？**
答：rolecraft 具有零依赖项、MCP 服务器管理、82 个代理（而非 72）、`doctor`、`watch`、`bundle`、`agents-xml` 和 shell 补全。[完整比较 →](docs/comparison.md)
**问：我可以在 CI/CD 中使用它吗？**
答：可以。`rolecraft ci --yes` 重新安装 lockfile 中的所有技能，非交互式。适用于管道。
**问：我的技能被标记为 DANGER。我该怎么办？**
答：查看安全报告，修复标记的模式，或使用 `--yes` 强制安装（不建议用于不受信任的技能）。
## 开发
克隆仓库并在本地测试，无需发布到 npm：
```bash
git clone https://github.com/sametcelikbicak/rolecraft.git
cd rolecraft
# 全局链接
npm link
# 现在 `rolecraft` 从您的本地分支运行
rolecraft --help
# 对于文档站点（VitePress）
npm install
npm run docs:dev # 在 http://localhost:5173/rolecraft/ 上进行本地预览
npm run docs:build # 生产构建到 docs/.vitepress/dist/
# 完成后取消链接
npm unlink -g rolecraft
```
所有命令与安装版本相同。无需发布到 npm。
## 支持
- **[文档站点](https://sametcelikbicak.github.io/rolecraft/)** — 完整的命令参考和指南
- **[GitHub 问题](https://github.com/sametcelikbicak/rolecraft/issues)** — 错误报告、功能请求
- **[SUPPORT.md](SUPPORT.md)** — 如何获取帮助
- **[SECURITY.md](SECURITY.md)** — 责任披露
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开始贡献的指南。在打开问题之前，请查看我们的 [模板](.github/ISSUE_TEMPLATE/) 以获取错误报告和功能请求。
### 贡献者
感谢所有为 RoleCraft 做出贡献的人员：
| 头像 | 姓名 | 角色 |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| <img src="https://github.com/sametcelikbicak.png" width="40" height="40" alt="sametcelikbicak"> | [Samet ÇELİKBIÇAK](https://github.com/sametcelikbicak) | 所有者 & 维护者 |
| <img src="https://github.com/fengjikui.png" width="40" height="40" alt="fengjikui"> | [冯基魁](https://github.com/fengjikui) | [贡献者](https://github.com/sametcelikbicak/rolecraft/pull/62) |
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器