内容
align="center">
<img src="./assets/ai-canon-logo.svg" alt="ai-canon convergence logo" width="160">
</p>
<h1 align="center">ai-canon</h1>
<p align="center"><strong>将您团队的 AI 代理自定义内容保存在一个规范仓库中，然后同步到每个仓库、代理和操作系统。</strong></p>
定义您的 *规范*（技能、规则、MCP 服务器、帮助脚本）一次，在一个 Git 仓库中。每个消费者仓库通过清单声明它想要的子集。开发者运行一个命令，获取他们实际使用的代理的原生配置：
| 代理 | 技能 | MCP | 规则 |
| --- | --- | --- | --- |
| Claude Code | `.claude/skills/` | `.mcp.json` | 不适用 |
| Codex CLI | `.agents/skills/` | `.codex/config.toml` | 不适用 |
| Cursor | `.cursor/skills/` | `.cursor/mcp.json` | `.cursor/rules/<ns>-rules.mdc` |
| OpenCode | `.opencode/skills/` | `opencode.json` | 不适用 |
（对于规则，请参考 [AGENTS.md](https://agents.md)：每个主要代理现在都读取它。ai-canon 填补了仍然特定于工具的空白。）
## 何时使用此工具（以及何时不使用）
像 [rulesync](https://github.com/dyoshikawa/rulesync) 和 [Ruler](https://github.com/intellectronica/ruler) 这样的工具解决了 **一个仓库 → 许多代理** 的问题，并支持比 ai-canon 更多工具。如果您的规范在一个单独的仓库中运行良好，请使用它们。[Microsoft APM](https://github.com/microsoft/apm) 也涵盖了多仓库分发，作为一个具有清单、锁定文件和组织治理的完整包生态系统；如果您想要来自多个源的包跨多个代理，请使用它。
ai-canon 是这个想法的缩小版，**一个规范仓库 → 许多仓库 → 许多代理**，具有一些较大的工具跳过的一些安全行为：
- 一个由您的平台/AI 启用人员拥有的中心、版本化的规范仓库
- 每个仓库的清单：后端仓库获取后端技能，前端仓库获取前端技能，每个人都获取通用集
- 一个 CI 友好的漂移检查（`ai-canon doctor --check`），以便仓库在规范更改时收到通知
- 所有权安全：生成的文件带有标记，如果手动编写，永远不会被静默覆盖；过时的技能仅在其命名空间内清理
- 机密卫生：MCP 配置中的 `${VAR}` 占位符从开发人员的环境中解析；缺少值的服务器被并报告，从未写入未解析的占位符
## 快速入门
### 1. 编写规范（每个团队一次）
```sh
mkdir our-ai-canon && cd our-ai-canon && git init
npx ai-canon init canon
git add . && git commit -m "我们的 AI 规范" && git push
```
这会搭建：
```text
canon.json 名称、命名空间、默认值
canon/
skills/common/*.md 技能（SKILL.md 格式 + 前置信息）
mcp/common.json MCP 服务器目录（允许 ${VAR} 占位符）
rules/common.md 规则内容（适用于不支持 AGENTS.md 的代理）
scripts/ 安装到 .ai/scripts/ 的帮助脚本
manifests/
<repo-name>.json 每个消费者仓库的一个清单
```
脚手架包括 `manifests/example.json`。为每个消费者仓库复制一份并编辑所选内容：
```sh
cp manifests/example.json manifests/your-app.json
# 编辑 "repo" 为 "your-app"，然后选择它需要的技能/规则/MCP/脚本。
git add manifests/your-app.json && git commit -m "添加 your-app 清单" && git push
```
文件名必须与消费者仓库的 `repo` 值（通常是其目录名称）匹配。
### 2. 连接每个消费者仓库
```sh
cd your-app
npx ai-canon init --canon git@github.com:your-org/our-ai-canon.git
git add .ai.yaml .gitignore && git commit -m "采用 ai-canon"
```
### 3. 每个开发者，任何机器
```sh
npx ai-canon sync
```
在 TTY 上交互式（选择代理、技能、MCP）；否则完全可脚本化：
```sh
npx ai-canon sync --agent claude,cursor --no-interactive
npx ai-canon sync --agent codex --skill acme-test --mcp context7
```
成功的首次同步会明确指出它创建的每个本地文件：
```text
ai-canon [acme]: your-app -> claude, codex
Changes (5)
created .claude/skills/acme-test/SKILL.md
created .agents/skills/acme-test/SKILL.md
created .mcp.json
created .codex/config.toml
created .ai.lock.json
```
规范被克隆/获取到仓库本地的、被 git 忽略的 `.ai/.canon` 中，每次运行都这样，因此更新所有人只需 `git push` 到规范仓库；开发者在下一次同步时获取它。
### 4. 在 CI 中保持仓库诚实
```sh
npx ai-canon doctor --check # 如果生成的文件与规范移，则退出 1
```
## 概念
###on.json`（规范目录）
```{
"name": "acme",
"namespace": "acme",
"generatedNotice": "生成的文件。不要直接编辑。运行：ai-canon sync"
}
```
`namespace` 将每个规范技能名称限定为 `<namespace>-*`。过时清理还需要 ai-canon 的结构化所有权编写的技能保持标记允许有清理在规范故意更改时保持正确。
### 技能
标准 [SKILL.md](https://agentskills.io) 文件，带有一些额外的前置信息：
```markdown
---
name: acme-open-pr
description: 打开一个遵循 Ac定的 PR。使用户说“打开一个 PR”时使用。
agents: [claude, code # 可选，默认值：所有
default: false # 可选，默认技能（默认值：true）
requires-env: [GITHUB_TOKEN] # 可则跳过报告
---
说明...
目录
```json
{
"mcpServers "context7 "command": "nargs": ["-y", "@upstash/context7-mcp"] },
"jira": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {IRA_API_TOKEN": "${_API_TOKEN}" },
["claude","],
"default": false
}
}
}
```
占位符从进程环境或 git 忽略的 `.ai.local/env` 中解析。开发人员可以在 `.ai.local/mcp.json` 中添加个人服务器；它们会覆盖规范。
### 清单（每个消费者仓库一个）
```json
{
"version": 1,
"repo": "skills": ["common/*.md", "common/acme-jira-*.md", "backend/*.md"],
"rules": ["common.md", "backend.md"],
"mcp": [""],
"scripts": ["open-pr/*"],
"defaultAgents": ["claude", "codex"]
}
```
### 消费者 `.ai.yaml`
```yaml
canon: git@github.com:your-org/our-ai-canon.git # 或相对路径
repo: backend # 清单名称；默认为目录名称
Ref: v1.2.0 # 可选固定（标签、分支或提交；默认：远程默认分支）
```
## 安全规则
- **将规范仓库视为受信任的代码。** 它分发代理指令、MCP 命令和可执行帮助脚本。像应用程序代码一样审查规范更改，并保护谁可以推送到它。
- 生成的文件是本地开发人员状态：保持它们被 git 忽略（`init` 设置了这一点）。它们可能包含已解析的机密。同步拒绝 Git 已跟踪的带有机密的生成使用 `git rm --cached <path>` 在继续从索引中删除。
- 每个生成的文件都带有结构化的 `[ai-canon 标记。具有托管目标的文件（包括技能、脚本和根代理配置）仅在该标记或旧版 0.1 标记证明所有权时被覆盖。否则，同步在更改任何内容之前都会拒绝。故意使用 `--force` 覆盖。
- 仅当所有权得到证明时，才会删除过时的技能（旧版 0.1 文件还需要当前命名空间前缀）。仅在 `.ai/scripts/` 下才会清理过时的已拥有脚本。
- 清单路径仅限于其规范目录，生成目标仅限于消费者仓库。拒绝绝对路径、遍历、反斜杠和转义符号链接。
- 具有未解析的 `${VAR}` 占位符 服务器被跳过并报告，从未写入。
- 带有机密的根 MCP 文件在 POSIX 上为 `0600` 模式。Git URL 在错误和锁定文件中被编辑，但凭证应来自 Git 凭证管理器，而不是嵌入在 URL 中。
- 同步在写入之前验证并计划整个操作。守护冲突不会进行任何更改；后续文件系统故障会回滚整个计划，单个文件替换是原子的。
## 本地规范开发
```sh
AI_CANON_SOURCE=../our-ai-canon npx ai-canon sync --no-interactive # 使用本地检出
AI_CANON_REF=origin/my-branch npx ai-canon sync # 测试规范分支
```
`.ai.lock.json` 记录了生成当前文件的规范提交/内容（仅审计）。
## 恢复和回滚
- 预览漂移而不更改文件：`npx ai-canon doctor --check`。
- 检查配置的源、清单、待处理更改、删除和冲突：`npx ai-canon doctor`。
- 通过在 `.ai.yaml` 中将 `canonRef` 设置为已知的标签或提交，然后运行 `npx ai-canon sync --no-interactive` 回滚。
- 通过删除 `canonRef` 并再次同步，返回到远程默认分支。
- 如果手动编写的内容故意替换了生成的根配置，同步会在修改任何内容之前停止。将个人 MCP 条目移动到 `.ai.local/mcp.json`，或审查替换并在一次使用 `--force`。
- 如果 `.ai/.canon` 受损，请删除仅被 git 忽略的缓存目录并再次同步。ai-canon 还会在配置的规范 URL 更改时自动替换它。
`doctor --check` 报告写入、更新、删除、冲突和锁定文件漂移，并在下一次同步将更改本地状态时退出 1。
## 开发
```sh
pnpm install
pnpm check # 类型检查
pnpm test # e2e CLI 测试
pnpm build # 打包 dist/cli.mjs
```
## 发布
维护者配置仓库的 `NPM_TOKEN` 机密，递增 `package.json`，更新 `CHANGELOG.md`，并推送匹配的 `v<version>` 标签。发布工作流重新运行检查，使用 npm 证据发布，并创建 GitHub 发布说明。 不匹配的标签在发布前会失败。
## 许可证
MIT
