rolecraft

<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 · <b>MCP + 技能一键安装</b> · 86+ 代理 · 无需注册 </p> <p align="center"> <a href="https://awesome.re"><img src="https://awesome.re/badge.svg" alt="Awesome"></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/rolecraft-sh/rolecraft/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/rolecraft-sh/rolecraft/test.yml?label=tests" alt="Tests"></a> <a href="https://github.com/rolecraft-sh/rolecraft/actions/workflows/codeql.yml"><img src="https://img.shields.io/github/actions/workflow/status/rolecraft-sh/rolecraft/codeql.yml?label=CodeQL" alt="CodeQL"></a> <a href="https://github.com/rolecraft-sh/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/marketplace/actions/rolecraft-action"><img src="https://img.shields.io/badge/GitHub%20Action-rolecraft--action-blue?logo=github" alt="GitHub Action"></a> <a href="https://github.com/rolecraft-sh/rolecraft"><img src="https://img.shields.io/github/stars/rolecraft-sh/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://rolecraft-sh.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"> 支持 <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="#features">功能</a> · <a href="#commands-overview">命令概览</a> · <a href="#comparison">比较</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>🤖 86+ 代理</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="基准测试：比 Vercel 快 434 倍" 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> --- ## 快速开始 ```bash # 无需安装即可试用 npx rolecraft --help # 或全局安装（支持 npm、pnpm、yarn、bun） npm install -g rolecraft # 检测所有代理并为每个代理安装技能 rolecraft setup user/repo # 安装技能（本地、GitHub、GitLab、SSH、npm） rolecraft install ./my-skill --cursor # 安装带有 MCP 服务器的技能（在 SKILL.md 中声明） rolecraft install ./postgres-rules --cursor # 独立管理 MCP 服务器 rolecraft mcp install npm:@modelcontextprotocol/github --cursor # 管理已安装的技能 rolecraft list rolecraft search code-review rolecraft check rolecraft remove my-skill # 在 SKILL.md 和 .mdc 格式之间转换 rolecraft convert ./my-skill rolecraft convert --help ``` **要求：** Node.js >= 20 · 4 KB · 零依赖 · 86+ 代理 · [开始使用 →](docs/guides/getting-started.md) · [完整安装指南 →](docs/install.md) > **为什么是零依赖？** 每个依赖都是供应链风险。rolecraft 只使用 Node.js 内置模块（`fs`、`path`、`crypto`、`https`）—— 没有 `node_modules` 的惊喜。 --- ## 技能 + MCP 一键安装 rolecraft 是 **唯一** 一个将代理技能和 MCP 服务器一起安装的 CLI。 单个 SKILL.md 可以声明技能及其所需的 MCP 服务器： ```yaml --- name: postgres-rules mcp_servers: - name: postgres source: npm:@modelcontextprotocol/postgres --- ``` ```bash # 一键安装技能和 MCP 服务器 rolecraft install ./postgres-rules --cursor ``` 没有其他 CLI 可以同时安装两者。 npx skills 没有 MCP 支持。 ags 仅有一个用于搜索的 MCP 服务器。 [→ 完整 MCP 文档](docs/mcp.md) --- ## 功能 - **零依赖** — ~4 KB，仅 Node.js 内置模块 - **MCP + 技能一键安装** — 同时安装技能及其 MCP 服务器。独特。 - **任意来源** — 本地文件夹、GitHub/GitLab/SSH URL、npm 包 - **86+ 代理** — opencode、claude-code、cursor、copilot、aider、devin、gemini-cli 等等 - **无需注册** — 无需注册、无需 API 密钥、无需应用商店、无需供应商锁定 - **安全评分** — 静态分析：检测提示注入、命令注入、混淆代码、凭证收集。分数 0–100。阻止危险技能 - **CI-ready** — 基于 lockfile 的重新安装 (`rolecraft ci`)、`--yes` 标志、`--dry-run` - **Shell 补全** — bash、zsh、fish 自动补全 - **TUI 搜索** — 交互式箭头键技能浏览器，支持预览 - **系统健康检查** — `rolecraft doctor` 诊断代理目录、lockfile 和技能完整性 - **AGENTS.md XML 生成** — `rolecraft agents-xml` 生成 Claude Code 兼容的 XML - **配置文件** — 保存、应用和共享多代理配置 --- ## CI/CD 集成 使用 [rolecraft GitHub Action](https://github.com/marketplace/actions/rolecraft-action) 在您的 CI 流水线中验证和安装技能： ```yaml # .github/workflows/skills.yml - uses: rolecraft-sh/rolecraft-action@v1 with: command: ci --yes ``` 查看 [CI 指南](docs/guides/ci.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` | 从 lockfile 重新安装所有技能（CI 模式） | [文档](docs/commands/ci.md) | | `rolecraft convert <source>` | 在 SKILL.md 和 .mdc 格式之间转换 | [文档](docs/commands/convert.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 --help` | 显示完整命令参考 | [CLI 参考](docs/reference.md) | --- ## 比较 | 功能 | rolecraft | skills (Vercel) | @agentskill.sh/cli | | --- | --- | --- | --- | | 零依赖 | ✅ **0** | ✅ (1 依赖) | ❌ (2) | | 本地路径安装 | ✅ **一流** | ✅ | ❌ 市场应用商店仅限 | | GitHub 仓库安装 | ✅ | ✅ | ❌ | | GitLab / SSH git URL | ✅ | ✅ | ❌ | | npm 包源 | ✅ | ✅ | ❌ | | **MCP 服务器管理** | ✅ | ❌ | ❌ | | 代理目标 | **82** | 72 | 15+ | | skills.sh 列表 | ✅ | ✅ | ⚠️ (仅限注册) | | 捆绑安装 + 创建 | ✅ | ❌ | ✅ (仅限 skillset) | | 交互式 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()`）、命令注入（command download-and-execute）、凭证收集模式 | | 🟡 高 | 凭证收集模式、敏感文件访问（`~/.ssh`、`*.env`） | | 🟢 中/低 | 缺失元数据、不寻常的源模式 | 分数范围 **0–100**： - **90+** → 安全，安装继续 - **70–89** → 审查，提示确认 - **<70** → 危险，阻止除非 `--yes` ```bash rolecraft install ./my-skill # 自动扫描 rolecraft install ./my-skill --yes # 强制安装，即使危险 ``` [→ 完整安全文档](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`（本地、GitHub、GitLab、SSH、npm） 2. 对所有文件运行 **静态安全扫描**（提示注入、命令注入、混淆、凭证收集）—— 分数 0–100 3. 将文件复制/符号链接到目标代理的技能目录 4. 在 `~/.agents/.skill-lock.json` 中记录 SHA256 内容哈希 5. 与 `npx skills`、`@agentskill.sh/cli` 或手动安装的技能兼容 [→ 完整架构](docs/architecture.md) --- ## 常见问题 **问：我需要注册或登录吗？** 答：不需要。无需帐户，无需 API 密钥，无需市场应用商店。只需指向 rolecraft 任何文件夹或仓库即可。 **问：我可以在多个 AI 代理上使用 rolecraft 吗？** 答：是的。支持 86+ 代理。使用 `--cursor`、`--claude`、`--devin` 标志或 `--all` 所有代理。 **问：rolecraft 会发送遥测数据吗？** 答：否。机器上没有数据离开。安全扫描在本地运行。没有电话回家。 **问：它与 `npx skills`（Vercel）有什么不同？** 答：rolecraft 具有零依赖、MCP 服务器管理、86 个代理（vs 72）、`doctor`、`watch`、`bundle`、`agents-xml` 和 Shell 补全。[完整比较 →](docs/comparison.md) **问：我可以在 CI/CD 中使用它吗？** 答：是的。`rolecraft ci --yes` 重新安装 lockfile 中的所有技能，非交互式。适用于管道。 **问：我的技能被阻止为 DANGER。我该怎么办？** 答：查看安全报告，修复标记的模式，或使用 `--yes` 强制安装（不推荐用于不受信任的技能）。 ## 开发 ```bash git clone https://github.com/rolecraft-sh/rolecraft.git cd rolecraft npm link # rolecraft CLI 从本地检查运行 npm install # 用于文档站点（VitePress） npm run docs:dev # 本地文档预览 npm test # 730+ 测试，0 个失败预期 ``` [→ 贡献指南](CONTRIBUTING.md) ## 支持 - **[文档站点](https://rolecraft-sh.github.io/rolecraft/)** — 完整命令参考和指南 - **[GitHub 问题](https://github.com/rolecraft-sh/rolecraft/issues)** — 错误报告、功能请求 - **[SUPPORT.md](SUPPORT.md)** — 获取帮助的方式 - **[SECURITY.md](SECURITY.md)** — 负责披露 ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开始贡献的指南。在打开问题之前，请查看我们的 [模板](.github/ISSUE_TEMPLATE/) 以获取错误报告和功能请求。 ### 贡献者 感谢所有为 RoleCraft 做出贡献的人： <table> <tr> <td align="center"><a href="https://github.com/sametcelikbicak"><img src="https://github.com/sametcelikbicak.png" width="60" height="60" alt="sametcelikbicak"><br><b>Samet ÇELİKBIÇAK</b></a><br>_{所有者 &amp; 维护者}</td> <td align="center"><a href="https://github.com/fengjikui"><img src="https://github.com/fengjikui.png" width="60" height="60" alt="fengjikui"><br><b>冯基魁</b></a><br>_{<a href="https://github.com/sametcelikbicak/rolecraft/pull/62">贡献者</a>}</td> <td align="center"><a href="https://github.com/Yurii201811"><img src="https://github.com/Yurii201811.png" width="60" height="60" alt="Yurii201811"><br><b>Yurii201811</b></a><br>_{<a href="https://github.com/sametcelikbicak/rolecraft/pull/104">贡献者</a>}</td> <td align="center"><a href="https://github.com/gaoharimran29-glitch"><img src="https://github.com/gaoharimran29-glitch.png" width="60" height="60" alt="gaoharimran29-glitch"><br><b>Gaohar Imran</b></a><br>_{<a href="https://github.com/sametcelikbicak/rolecraft/pull/116">贡献者</a>}</td> <td align="center"><a href="https://github.com/ajaynomics"><img src="https://github.com/ajaynomics.png" width="60" height="60" alt="ajaynomics"><br><b>Ajay Krishnan</b></a><br>_{<a href="https://github.com/sametcelikbicak/rolecraft/pull/121">贡献者</a>}</td> <td align="center"><a href="https://github.com/BenjaminAyivoh1"><img src="https://github.com/BenjaminAyivoh1.png" width="60" height="60" alt="BenjaminAyivoh1"><br><b>Benjamin Ayivoh</b></a><br>_{<a href="https://github.com/sametcelikbicak/rolecraft/pull/122">贡献者</a>}</td> </tr> </table> --- ⭐ **如果 rolecraft 让您的 AI 代理工作流程更轻松，请考虑 [给仓库加星](https://github.com/rolecraft-sh/rolecraft)。** 这有助于他人发现该项目，并表明社区认为它有用。 --- ## 许可 MIT