内容
<div align="center">
<img src="./doc/renkei.png" alt="Renkei" height="128" />
# Renkei
*AI 工作流的包管理器*
[](https://github.com/MeryllEssig/renkei/actions)
[](LICENSE)
[功能](#features) | [安装](#installation) | [快速入门](#quick-start) | [用法](#usage) | [支持的后端](#supported-backends)
</div>
AI 工具配置 — 技能、钩子、代理、MCP 服务器 — 分散在不同的工具中，没有版本控制，无法共享。 **Renkei** (`rk`) 将它们打包成一种单一的便携式格式，并同时部署到您的 AI 工具中。
```bash
rk install git@github.com:team/our-workflows # 从 Git 安装
rk install ./local-package # 从本地路径安装
rk list # 查看已安装的包
rk doctor # 运行健康检查
```
## 功能
- **多后端部署** — 一个包可以安装到 Claude Code、Cursor、Codex、Gemini CLI 和共享的 `.agents/` 标准，所有这些都是一次完成的
- **便携式格式** — 一个 `renkei.json` 清单文件和约定目录（`skills/`、`agents/`、`hooks/`），任何团队成员都可以安装
- **锁定文件和完整性** — `rk.lock` 记录确切的 Git SHA 和 SHA-256 哈希值，以实现可复制的安装
- **作用域安装** — 默认情况下为项目级，全局安装使用 `-g`
- **冲突检测** — 在 TTY 中进行交互式解析，在 CI 中进行硬错误，使用 `--force` 覆盖
- **原子回滚** — 如果任何后端失败，则回滚所有更改
- **工作区** — 支持多包仓库的 Monorepo
- **健康诊断** — `rk doctor` 检查已部署的文件、完整性哈希值、环境变量和后端可用性
## 安装
### 快速安装
```bash
curl -fsSL https://raw.githubusercontent.com/MeryllEssig/renkei/main/install.sh | sh
```
自动检测您的操作系统和架构。默认安装到 `~/.local/bin`（可使用 `RK_INSTALL_DIR` 覆盖）。
### 从源码安装
```bash
git clone git@github.com:MeryllEssig/renkei.git
cd renkei
cargo install --path .
```
## 快速入门
### 创建一个包
```
my-workflow/
├── renkei.json
├── skills/
│ └── code-review/
│ └── SKILL.md
├── agents/
│ └── researcher.md
└── hooks/
└── pre-commit.json
```
```json
{
"name": "@team/my-workflow",
"version": "1.0.0",
"description": "我们团队的共享 AI 工作流",
"author": "团队",
"license": "MIT",
"backends": ["claude", "cursor"]
}
```
### 安装它
```bash
rk install ./my-workflow
```
技能、代理和钩子被部署到项目中的 `.claude/` 和 `.cursor/`。创建一个 `rk.lock` 来跟踪已安装的内容。
### 分发它
```bash
rk package --bump minor # 创建一个版本化的 .tar.gz 存档
```
通过 Git 共享或直接分发存档。
## 用法
| 命令 | 描述 |
|:---|:---|
| `rk install <source>` | 从 Git URL 或本地路径安装 |
| `rk install` | 从 `rk.lock` 恢复 |
| `rk install -g <source>` | 全局安装（`~/`） |
| `rk install --tag v1.0` | 固定到 Git 标签 |
| `rk install <source> -m <member>` | 仅安装指定的工作区成员（可重复，CSV 感知） |
| `rk install <source> --yes` | 跳过预安装确认提示（在 CI / 非 TTY 中需要） |
| `rk install <source> --allow-build` | 跳过捆绑的本地 MCP 服务器的构建确认（在 CI / 非 TTY 中需要） |
| `rk install --link <source>` | 将源代码符号链接而不是复制（实时开发模式）；对于本地 MCP，还符号链接 `~/.renkei/mcp/<name>/` |
| `rk uninstall @scope/name` | 删除一个包 |
| `rk list` | 显示已安装的包 |
| `rk doctor` | 运行健康诊断 |
| `rk package` | 创建可分发的存档 |
| `rk package --bump <level>` | 升级版本并打包 |
| `rk config` | 交互式后端配置 |
| `rk config set defaults.backends claude,cursor` | 设置后端 |
| `rk migrate ./path` | 将目录转换为 Renkei 包 |
> [!TIP]
> 运行 `rk install` 且不带参数，以从现有的 `rk.lock` 恢复所有包 — 适用于新员工或 CI。
## 支持的后端
| 后端 | 技能 | 代理 | 钩子 | MCP |
|:---|:---:|:---:|:---:|:---:|
| Claude Code | `.claude/skills/` | `.claude/agents/` | `settings.json` | `~/.claude.json` |
| Cursor | `.cursor/rules/` | `.cursor/agents/` | `hooks.json` | `mcp.json` |
| Codex | `.agents/skills/` | `.toml` 文件 | `hooks.json` | `config.toml` |
| Gemini CLI | `.gemini/skills/` | `.md` 文件 | `settings.json` | `settings.json` |
| 代理（共享） | `.agents/skills/` | — | — | — |
Renkei 自动检测哪些后端可用，并将部署到所有后端。使用 `--backend` 或 `rk config` 覆盖。
## 清单参考
`renkei.json` 清单支持以下字段：
```json
{
"name": "@scope/name",
"version": "1.0.0",
"description": "...",
"author": "...",
"license": "MIT",
"backends": ["claude", "cursor", "codex", "gemini"],
"scope": "any",
"keywords": [],
"mcp": {
"my-server": {
"command": "node",
"entrypoint": "dist/index.js",
"build": [["bun", "install"], ["bun", "run", "build"]]
}
},
"requiredEnv": { },
"workspace": ["packages/a", "packages/b"],
"messages": {
"preinstall": "在安装前配置 GitLab MCP 服务器。",
"postinstall": "运行 `rk doctor` 以验证安装。"
}
}
```
| 字段 | 必需 | 描述 |
|:---|:---:|:---|
| `name` | 是 | 作用域包名（`@scope/name`） |
| `version` | 是 | Semver 版本 |
| `description` | 是 | 简要描述 |
| `author` | 是 | 作者姓名 |
| `license` | 是 | 许可证标识符 |
| `backends` | 是 | 目标后端 |
| `scope` | 否 | `"any"`（默认）、`"global"` 或 `"project"` |
| `mcp` | 否 | MCP 服务器配置。外部服务器使用原生的 `command`/`args`/`env` 块。**本地 MCP** 添加 `entrypoint`（`mcp/<name>/` 内的相对路径）和 `build`（argv 步骤数组）。Renkei 将源代码从 `mcp/<name>/` 复制到 `~/.renkei/mcp/<name>/`（始终是全局的，与包作用域无关），运行构建，并将绝对入口点注册到后端。参见 [`doc/prd/mcp.md`](./doc/prd/mcp.md)。 |
| `requiredEnv` | 否 | 要求的环境变量 |
| `workspace` | 否 | Monorepo 成员路径 |
| `messages` | 否 | `preinstall` / `postinstall` 安装时通知（每个 ≤ 2000 字符） |
## 构件格式
构件使用中立的 Markdown 格式，带有可选的 YAML 前置信息。Renkei 在部署期间将它们转换为每个后端的原生格式。
```markdown
---
description: 审查代码以符合最佳实践
---
审查代码更改并提供反馈，内容包括：
- 代码质量和可读性
- 潜在的错误或边缘情况
- 性能考虑
```
> [!NOTE]
> 钩子使用具有抽象事件的 JSON 格式（`pre-commit`、`post-save` 等），Renkei 将其映射到每个后端的钩子系统。
## 开发
```bash
git config core.hooksPath .githooks # 启用预提交检查（fmt、clippy、test）
cargo test # 运行所有测试
cargo test -- --nocapture # 带输出
cargo clippy # Lint
cargo fmt # 格式化
```
