内容
# quay
**适用于 AI 编程代理的 Git 原生技能注册表.** 在开发者、团队成员和组织之间共享 `SKILL.md` 文件（Claude Code、Codex、Cursor 等）- 使用任何 git 仓库作为中心。不需要 SaaS，不需要 `git` 之外的令牌，不需要锁定。
```text
$ quay search csv
csv-parse 解析 CSV 并进行类型推断。
$ quay add csv-parse
已安装 csv-parse → .agents/skills/csv-parse/
$ quay push my-skill --bump=patch
已打开 PR: https://github.com/acme/skills/pull/142
```
**完整文档：** <https://evgeniiperov.github.io/quay/intro.html>
## 安装
### Homebrew（macOS，Linux）
```sh
brew install evgeniiPerov/tap/quay
```
### Windows（PowerShell）
始终拉取最新版本:
```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/evgeniiPerov/quay/releases/latest/download/quay-installer.ps1 | iex"
```
### 手动下载
从 <https://github.com/evgeniiPerov/quay/releases/latest> 获取匹配的 tarball 或 zip 文件，并将 `quay` 二进制文件提取到您的 `PATH` 目录中。
### macOS Gatekeeper 注意
v0.1 中的二进制文件未签名。如果 macOS 在首次启动时阻止二进制文件：
```sh
xattr -d com.apple.quarantine /usr/local/bin/quay
```
… 或在 Finder 中右键单击二进制文件并选择 **打开**。
## 为什么？
代理正在吞噬开发工作流，但使它们有用的 **技能** （提示、验证器、脚手架、重试策略）被从项目复制到项目，漂移到私人 gist 中死亡。
Quay 将技能视为包：
- **一次性编写。** 将 `SKILL.md` 文件放入 `.agents/skills/<name>/` 目录中 - 在任何项目中编写、使用 AI 生成或使用任何编辑器。
- **推送到中心。** 中心 = 一个常规的 git 仓库，由您的团队拥有。推送会打开一个 PR。
- **在任何地方拉取。** `quay add <skill>` 安装到 `.agents/skills/` 目录中；镜像传播到 `.claude/skills/`、`.codex/skills/`、`.cursor/skills/` 目录，通过 `quay link` 实现。
- **留在 git 中。** 没有锁定文件，没有锁定。技能由 git 历史记录跟踪。权限 = 仓库权限。审计 = `git log`。
适用于：一个 Next.js 团队共享 `react-perf-review` 技能，一个组织在服务中标准化 `pr-description` 技能，一个承包商通过私人 GitHub 仓库向客户发布技能。
需要 `git` 在 `PATH` 中。`gh` / `glab` / `az` 是可选的 - 用于在 `quay push` 时自动打开 PR；如果没有它，推送会打印一个比较 URL 或在直接模式下运行，如果远程配置为它。
支持的中心提供商：**GitHub.com**，**GitHub Enterprise**，**GitLab** （云 + 自托管，嵌套子组），**Bitbucket Cloud**，**Azure DevOps Services**。从 URL 自动检测；使用 `quay remote add --provider <kind>` 覆盖。
## 状态
| 计划 | 范围 | 状态 |
|---|---|---|
| 1–5 | 基础，读取 CLI，搜索，创建/验证/推送，配置文件，镜像 | ✅ |
| 7a | 提供商抽象（GitHub / GHE / GitLab / Bitbucket / Azure DevOps）+ 实时 `remote test` | ✅ |
| 7b | 打包发布（cargo-dist，GitHub Releases，Homebrew tap，PowerShell 安装程序） | ✅ |
| 8 | 扫描优先流程，格式宽容推送，混合格式技能 | ✅ |
| 9 | 每个远程的 `push_mode` （`pr` 默认，`direct` 通过纯 git 选择，无提供商 CLI） | ✅ |
| 10 | 文件系统优先模型：删除锁定文件 + 同步 + 创建；多镜像扫描器；`scan` 镜像 + 偏移列 | ✅ **v0.2.0** |
## 快速开始
### 编写 + 共享技能（您）
### 设置配置文件
创建配置文件有三种方法：
#### 交互式向导
```sh
quay profile add -i
```
通过名称、电子邮件、远程（带有提供商自动检测）、推送模式、默认标志和激活来遍历。 在一个会话中添加任意多个远程。
#### 从 TOML 文件或 stdin
```sh
quay profile add ci --from-toml ci-profile.toml
# 或从 stdin：
cat profile.toml | quay profile add ci --from-toml -
```
#### 显式标志（可脚本化）
```sh
quay profile add work \
--email you@example.com \
--remote main=git@github.com:org/skills.git --provider github --push-mode pr --default \
--remote azure=git@ssh.dev.azure.com:v3/org/proj/repo --provider azuredevops --push-mode direct \
--activate
```
这三种模式是互斥的；如果组合使用，clap 将报错。
```sh
# 1. 配置文件 + 中心（一次）
quay profile add work --email you@example.com \
--remote main=https://github.com/your-org/skills.git
quay remote test main
# 2. 在任何项目中（Next.js，Rust 等）
cd ~/code/your-app
quay init
$EDITOR .agents/skills/http-retries/SKILL.md # 人类或 AI 代理编写技能
quay validate http-retries
quay push http-retries --bump=patch # 打开 PR
```
已经在 `.agents/skills/` 中有技能？直接推送：
```sh
quay scan # 发现现有技能，任何格式；显示镜像 + 偏移
quay push <name> # 推送原样，前面可选
```
### 拉取队友的技能（同事）
```sh
cd ~/code/their-app
quay init
quay remote add team https://github.com/your-org/skills.git --default
quay search retries
quay add http-retries
```
### 保持同步
```sh
quay outdated # 显示偏移（无锁定文件 - 比较实时注册表与本地文件）
quay update # 拉取已安装技能的最新版本
# 无 `quay sync` - 技能通过 git 历史记录跟踪；正常提交更改。
```
### 批量选择
`push`、`add`、`update`、`remove` 命令在终端中调用会打开一个复选框多选选择器：
```sh
quay push -i # 复选框列表的本地技能
quay add -i # 复选框列表的远程注册表行
quay update -i # 复选框列表的过时技能
quay remove -i # 复选框列表的本地技能删除
```
### 批量添加 - 冲突处理
当部分选定的技能已经在本地存在时，`quay add -i` 会一次性询问如何处理冲突：
```
3 of 5 already exist locally:
- foo (modified)
- bar (clean)
- baz (clean)
? What should we do with the existing ones?
◉ Update all (overwrite from remote)
◯ Skip all (only install new ones)
◯ Prompt per skill
```
选择 **Prompt per skill** 会显示每个冲突的迷你提示，并为每个技能选择 **Update** / **Skip**。
`quay add foo` （单技能）仍然会在冲突时报错；传递 `--force` 以覆盖。
### 交互式默认值
在终端中，`add`、`push`、`update`、`remove` 命令调用会打开一个多选选择器：
| 命令 | `name foo` | `-i` | 裸 TTY | 裸非 TTY |
|---|---|---|---|---|
| `add` | 安装 foo | 选择器 | 选择器 | 错误 |
| `push` | 推送 foo | 选择器 | 选择器 | 错误 |
| `remove` | 删除 foo | 选择器 | 选择器 | 错误 |
| `update` | 更新 foo | 选择器 | 选择器 | 更新所有 |
`update` 是唯一一个裸非 TTY 有效的命令 - 它会更新所有已安装的技能。 使用 `update --all` 强制此行为，即使在 TTY 上。
管道 / 重定向 / CI 运行器始终计为非 TTY，因此以前在没有参数的情况下运行的脚本保持不变。
参见 [`apps/cli/README.md`](apps/cli/README.md) 以获取完整的命令列表和 `--json` 输出示例。
## 从 AI 代理（MCP）使用 quay
quay 配备了一个 MCP 服务器：`quay mcp` 通过 stdio 讲模型上下文协议。它公开了技能注册表操作 - `search`、`add`、`info`、`list`、`outdated`、`scan`、`validate`、`link`、`update`、`remove`、`push`、`remote` - 作为结构化工具，AI 代理可以直接调用，返回 JSON 而不是人类可读文本。
一步到位，每个客户端注册：`quay mcp install <client>` 打印 `claude`、`codex` 或 `cursor` 的配置片段。对于 Claude Code：
```sh
claude mcp add -s user quay -- quay mcp
```
跨客户端设计 - 任何支持 stdio 的 MCP 客户端都可以驱动它。
## 概念
- **中心。** 具有 `skills/<name>/SKILL.md` 文件和 `registry.json` 索引的 git 仓库。上述任何提供商都有效。
- **配置文件。** 一个命名为 `(identity + remotes)` 的捆绑包。一个配置文件对应一个组织；使用 `quay profile use <name>` 或通过 `--profile=<name>` / `QUAY_PROFILE` 覆盖每个命令。
- **技能。** 带有 YAML 前面的 Markdown 文件（`name`、`description`、`version`、`tags` 等）。安装后位于 `.agents/skills/<name>/SKILL.md`。通过 `quay link` 处理工具特定镜像（`.claude/skills/`、`.codex/skills/`、`.cursor/skills/`）。
- **镜像根目录。** quay 扫描所有四个根目录 - `.agents/skills/`、`.claude/skills/`、`.codex/skills/`、`.cursor/skills/` - 并通过文件夹名称进行重复数据消除。在多个根目录中出现的技能，当内容不同时，会显示一个偏移徽章。
- **扫描。** `quay scan` 遍历所有四个镜像根目录，并将每个技能标记为 `Local`、`Installed`、`InstalledModified` 或 `PushedLocal`。显示 `MIRRORS` 和偏移列。
## 仓库布局
```
apps/cli/ Rust 工作区
├── crates/quay-core/ 域逻辑（配置、注册表、获取器、管理器、
│ 扫描器、提供者 {github,gitlab,bitbucket,azure}）
├── crates/quay-cli/ clap 子命令
├── crates/quay-mcp/ MCP 服务器（`quay mcp`）- 注册表操作作为代理工具
└── crates/quay/ 二进制文件
.github/workflows/ release.yml - cargo-dist 矩阵 + Homebrew 发布
.agents/ 共享代理规则 + 技能（工具中立）
.claude/ Claude Code 特定配置
```
## 更新日志
发布说明位于 [`CHANGELOG.md`](CHANGELOG.md) 中，在文档的 [Releases](https://evgeniiperov.github.io/quay/releases.html) 下渲染。每个版本的二进制文件都位于 [releases page](https://github.com/evgeniiPerov/quay/releases)。
最新版本：**v0.13.4** - 注册表路径遍历修复（如果您从不控制的中心安装，请更新），两个仅限 Windows 的修复，并且 CI 现在在 Linux 和 Windows 上运行套件。
## 贡献
欢迎 PR。在打开之前运行：
```sh
cd apps/cli
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
```
代码库通过子代理驱动开发计划实施；参见 [`.agents/rules/`](.agents/rules/) 以获取代码样式和测试约定代理遵循。
## 许可证
[MIT](LICENSE).
