# canonkit 中文文档

规范地址：https://npmcn.com/package/canonkit/

版本：2\.4\.0
npm 元数据更新时间：2026-11-03T05:18:21.578Z
中文译文更新时间：2026-11-03T07:21:12.782Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/canonkit
原文对照：https://npmcn.com/package/canonkit/?lang=original
项目主页：https://github.com/erikalira/canonkit#readme
源码仓库：https://github.com/erikalira/canonkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：538 kB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-05-08T03:15:38.092Z
- 最新版本发布：2026-11-03T05:18:21.247Z
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

一个版本代理团队，为Claude Code， Codex和OpenCode。安装10个核心代理和5个可选域专家，每个拥有一个域并对自己的风险进行分类。

## 安装

```sh
npm install canonkit
```

也可以使用：`pnpm add canonkit`、`yarn add canonkit`、`bun add canonkit`

## README

# canonkit

一个版本化的AI子代理团队 **克劳德代码**， **食典委** 和 **OpenCode**. 每个代理拥有一个领域：产品、架构、安全、质量、用户体验、 性能、操作或文档。在提出任何建议之前，它会对风险进行评估 关于变化。小的，可逆的工作留给你的主代理。更改为auth， 秘密、移民或公共合同归拥有它们的代理机构所有。在克劳德。 代码中，钩子强制执行最重要的规则，因此它们即使在模型失效时也能保持不变 忘记他们。Codex和OpenCode得到了最重要的两个：没有git钩子 绕过并没有秘密写入文件。

每个特工都有一个Markdown文件 [`agents/`](https://github.com/erikalira/canonkit/tree/main/agents)的格式 克劳德代码是这样写的。对于Claude Code，安装是一个纯拷贝。法典和开放代码 获取同一主体的生成副本。不管怎样，每个特工都有一个信息源， 也不需要手工调和。

> **canonkit 1。X不是canonkit 0.x。** 版本到 `0.2.0` 我们是不同的 工具。它生成了spec - kit风格的治理模板(`.specify/`,一个 结构，尺度轮廓)通过 `canonkit init`． 该工具已归档并 这里不存在它的任何命令。如果你用过，别针 `canonkit@0.2.0`.

## 是给谁的？

-   你使用Claude Code， Codex或OpenCode与子代理，你想要每一个 叫 **只有当它的领地处于危险之中时**，而不是每一个变化。
-   你想要一些保证，即使模型忘记了它们：确认 之前 `git commit` 和 `git push`，保密，并要求审查前 高风险变更算完成。
-   您希望了解委托成本（令牌、时间、每次分派的报告大小） 不用从你的机器上发送任何东西。

如果您希望每个任务一个代理，或者一个繁重的规范优先进程，那么它就不合适了。 Canonkit可以配合使用 [openspec](https://github.com/erikalira/canonkit/blob/main/docs/tools.md)，但它不能取代它。

## 快速入门

要求Node 18+。在Linux、macOS和Windows上：

```bash
npx canonkit install --wire-hooks
```

在终端中，一个菜单询问安装哪个运行时。克劳德法典和法典 预先确定;OpenCode是可选择加入的。 `--wire-hooks` 每个门钩的电线 您选择的运行时间： `~/.claude/settings.json`， `$CODEX_HOME/hooks.json` (然后运行 `/hooks` 在Codex一次信任它)，以及OpenCode 2插件。它保存了一个过时的 `.bak` 对于每个配置文件，它只更改，不更改其他任何内容。如果你离开 国旗, `install` 只打印Claude Code的JSON供您粘贴。 [每个选项写了什么](https://github.com/erikalira/canonkit/blob/main/docs/install.md#core-at-user-level).

Codex代理默认为 `gpt-6.1-sol`． 遵循你的法典会议模式 而不是固定一个版本，设置 `CANONKIT_CODEX_MODEL=inherit` 当安装。 看到 [模型配置](https://npmcn.com/package/canonkit/docs/install.md#follow-the-session-model) 对于PowerShell 例如，覆盖和更新现有代理。

**检查它是否有效：**

```bash
npx canonkit doctor
```

`doctor` 只读取。每次检查打印一行(`OK`， `WARN` 或者 `FAIL`), 如果任何操作失败，则以1退出：

```text
OK   agents: 10 core agents in ~/.claude/agents
OK   reference: managed blocks in ~/AGENTS.md and ~/.claude/CLAUDE.md
OK   hook file: ~/.claude/hooks/canonkit-hook.js, same as this package's
OK   hook syntax: node --check passes
OK   hook wiring: registered with its matcher under PreToolUse, PostToolUse, SubagentStop, UserPromptSubmit, Stop
OK   log: ~/.claude/canonkit-activity is writable
OK   forwarder: no meu-time-hook.js left, and no settings in sight run it
OK   config: file none (defaults), root ~/my-project

No check failed.
```

然后在任何项目中打开一个新的Claude Code会话：

1.  `/agents` 应列出十大核心代理商(`scott`， `archie`， `bob`,……)。
2.  让它做点什么。你应该找个 `canonkit gate: git commit/push requires explicit user authorization` 提示。下降;你刚看到一扇门 火。没有提示吗?看到 [如果没有门着火](https://npmcn.com/package/canonkit/#readme-if-no-gate-ever-fires).

**可选：仪表盘。** 它在本地运行，并显示分派、令牌和 盖茨:

```bash
node ~/.claude/canonkit-dashboard/serve.js          # Linux, macOS, Git Bash
node $HOME\.claude\canonkit-dashboard\serve.js      # Windows PowerShell
```

然后打开 `http://localhost:4317`. [它记录了什么](https://github.com/erikalira/canonkit/blob/main/docs/telemetry.md).

## 它如何决定：低还是高

每个代理使用一个共享的风险量表：

-   **低**：本地可逆。没有公开合同，认证，敏感数据或 运行时共享。
-   **媒介**：新的规则、流程、集成、许可或配置；一个 共享重构;一个貌似合理的回归。
-   **高**：认证，秘密，迁移，公共合同，新服务，支付，等等 生产部署，或任何难以回滚的部署。

下面两个例子都来自 [路由eval](https://github.com/erikalira/canonkit/blob/main/docs/evals.md#routing-eval) 例:

**“改正错别字 `recieve` 在README.md。”** 这是LOW。主代理修复它 内联且不分派任何人。派遣需要一个冷启动，外加一份报告 之后的每一回合都要重读一遍，为了一个词的修正。

**添加刷新令牌 `src/auth/session.js`”。** 这是高的，因为它 触动身份验证。事情是这样的：

1.  主要代理商计划引进 **加尔省** （保安），业主的授权。
2.  编辑 `src/auth/session.js` 启动高危门，然后你确认 编辑。
3.  这部作品没有按作者的要求完成。当转弯结束时，停闸 检查独立审稿人(Quinn, Gard, Archie， Perry或a 项目审阅者)被分派，或通过消息恢复， **最后一次之后 封闭的编辑**． 如果没有，它会阻塞一次转弯 然后要了一个。

有一种情况介于两者之间：在 _评论_ 在 `src/auth/messages.js`． 门仍然会触发，因为文件在 `auth/`。这个 但风险仍然很低，预期的行为是确认，解释为什么， 和 **不** 把加尔拉进来。一扇门告诉你要重新审视风险；事实并非如此 使改变高。

## 这个团队

**核心**：安装在用户级别，可用于每个项目。

| 代理 | 拥有 | 阻塞权威 |
| --- | --- | --- |
| **斯科特** | 产品：问题、范围、验收标准、成功指标 | 否决 |
| **阿奇** | 体系结构：模式、模块/服务边界、公共契约、新服务 | 否决 |
| **鲍勃** | 实现：编码、调试、重构、集成 | 无 |
| **奎因** | 质量：测试策略、覆盖率、边缘用例、回归风险 | 否决 |
| **加尔省** | 安全：授权、权限、秘密、暴露、依赖、Docker/Compose | 否决 |
| **Pixie** | UX：流程、UI状态、可访问性、微观拷贝 | 否决 |
| **佩里** | 感知速度：预算、测量、生产构建证据 | 块;放松预算的唯一权威 |
| **管** | 操作：CI/CD、部署、回滚、可观察性、作业、运行迁移 | 块 |
| **斯宾塞** | 文档：adr、规格、API文档、运行手册、发行说明 | 否决 |
| **处女座** | 团队自己的配置：代理，技能，这些管理块 | 无 |

**专家**：默认不安装。项目只有在添加时才会得到一个 这样就不会有特工被召来补全名单了

| 代理 | 安装时，项目有… |
| --- | --- |
| **玛雅** | 玩法或游戏化：核心循环、进程、平衡 |
| **新星** | 一种危在旦夕的视觉形象：调色板、构图、视觉特效语言 |
| **回声** | 带有意义的声音：作为反馈，自适应音乐的SFX |
| **丹娜** | 真实用户和数据：遥测、漏斗、A/B测试 |
| **虹膜** | ML或计算机视觉：提取，数据集，模型评估 |

```bash
cd my-project
npx canonkit add maya nova      # writes Claude Code, Codex and OpenCode copies + the project's AGENTS.md
```

**否决权是微弱的。** 代理只能在自己的域内使用否决权 中等或高的变化，并且只针对它可以命名的风险。你可以否决a 否决。当你这样做时，代理记录下未付风险并继续帮助你。谁拥有 在边界，每个代理遵循的约定，以及集成 审查正在进行中 [文档/ team.md](https://github.com/erikalira/canonkit/blob/main/docs/team.md).

## 堆栈包，每个项目

**可选技能** 向现有团队添加语言和框架指导。 选择项目使用的包；每个都是与核心分开安装的。

| 堆栈 | 指导 | 安装到您的项目中 |
| --- | --- | --- |
| [打印稿](https://npmcn.com/package/canonkit/stack-packs/typescript/SKILL.md) | 类型安全、异步边界和模块/构建诊断 | `npx canonkit add typescript` |
| [c++](https://npmcn.com/package/canonkit/stack-packs/cpp/SKILL.md) | 资源所有权、生存期、并发性和编译器/链接器诊断 | `npx canonkit add cpp` |
| [c# /。网](https://npmcn.com/package/canonkit/stack-packs/csharp/SKILL.md) | 空性、异步/资源生存期和解决方案/项目构建 | `npx canonkit add csharp` |
| [Java](https://npmcn.com/package/canonkit/stack-packs/java/SKILL.md) | 资源、并发性和Maven/Gradle诊断 | `npx canonkit add java` |
| [Python](https://npmcn.com/package/canonkit/stack-packs/python/SKILL.md) | 运行时数据、可变状态、资源、异步和环境 | `npx canonkit add python` |
| [反应](https://npmcn.com/package/canonkit/stack-packs/react/SKILL.md) | 钩子、状态/效果、水合作用和配置框架边界 | `npx canonkit add react` |
| [生锈](https://npmcn.com/package/canonkit/stack-packs/rust/SKILL.md) | 所有权、生命周期、异步/不安全不变量和Cargo诊断 | `npx canonkit add rust` |
| [去](https://npmcn.com/package/canonkit/stack-packs/go/SKILL.md) | 错误、程序/通道和模块/工作区构建 | `npx canonkit add go` |
| [芬兰湾的科特林](https://npmcn.com/package/canonkit/stack-packs/kotlin/SKILL.md) | 空性，协程/流和JVM/Android/多平台构建 | `npx canonkit add kotlin` |
| [斯威夫特](https://npmcn.com/package/canonkit/stack-packs/swift/SKILL.md) | ARC、actors/concurrency和SwiftPM/Xcode诊断 | `npx canonkit add swift` |

从项目中运行这些命令。你可以一次添加几个包，检查 什么是安装和删除包时，您停止使用它：

```bash
cd my-project
npx canonkit add typescript react
npx canonkit list
npx canonkit remove react
```

React和TypeScript是独立的。添加一个包安装它的指令； 它不安装编译器、运行时或项目依赖项。

拷贝到项目的 `.agents/skills/canonkit-<stack>/` 和 `.claude/skills/canonkit-<stack>/`． 保存本地编辑和不相关的文件； 重复 `add` 更新完整的副本。细节，恢复和移除 [文档/ install.md](https://github.com/erikalira/canonkit/blob/main/docs/install.md#stack-packs-per-project).

## 当门着火时

这张表是Claude Code。Codex和OpenCode一旦连接起来，就只执行git 旁路块和秘密块，用同样的理由文本 （[哪个登机口在哪里](https://github.com/erikalira/canonkit/blob/main/docs/hooks.md#codex-and-opencode)）。 git、secret、高风险和性能提示符以 `canonkit gate`． 停止门开始于 `Definition-of-done gate`． 上下文大小的提醒是纯文本。

| 门 | 火灾时 | 该怎么做 |
| --- | --- | --- |
| **Git commit / push** | 任何 `git commit` 或者 `git push`，包括后面 `git -C dir` 或者 `git -c key=value` | 只有在你要求的时候才确认。 |
| **Git hook / signing bypass （block）** | `--no-verify`， `git commit -n`， `--no-gpg-sign`， `-c core.hooksPath=...` 或者 `-c commit.gpgsign=false` | 它被否认了。修复钩子报告的内容。如果你真的想跳过它，你可以自己运行这个命令(`!` 《克劳德法典》)。细节 [文档/ hooks.md](https://github.com/erikalira/canonkit/blob/main/docs/hooks.md#what-the-git-gates-read). |
| **秘密(块)** | 私钥或云密钥将被写入文件 | 它被否认了。将值移动到env变量或秘密存储区。 |
| **秘密(问)** | 有些东西看起来像是硬编码的凭证 | 只有当它不是一个真正的秘密，如测试夹具时，才确认。 |
| **高风险的表面** | 编辑或shell写入认证、秘密、迁移或契约路径 | 提示询问谁导入或调用该文件，它涉及哪个公共契约（或“none”）以及回滚：确认之前的答案。再看看风险。如果它确实是高的，计划业主的审查（Gard, Archie）。如果是低的，确认并说明原因。 |
| **绩效预算** | 编辑预算文件(灯塔，大小限制， `budget.json`,……) | 提示符以任何一种方式触发，因为钩子看到的是路径而不是方向。确认拧紧。放松是佩里的决定，但要有节制。 |
| **完成的定义** (停止) | 编辑了封闭的文件，并且在最后一次编辑后没有派遣审稿人 | 发送（或简历）Quinn, Gard, Archie， Perry或项目审查人员，或者明确地说明为什么不需要审查。每回合发射一次。 |
| **上下文大小** | 会话传递约100k、150k或200k令牌 | 提醒，而不是阻碍。如果主题改变了，从切换开始一个新的会话。 |

**假警报。** 高风险门匹配路径，所以它有时会触发 文件夹命名 `sessions/` 或者 `contracts/` 这与真实无关。每一个 项目可以调整这个 `.claude/canonkit.json`：

```json
{
  "version": 1,
  "highRisk": { "include": ["src/billing/**"], "exclude": ["src/domain/contracts/**"] },
  "perfBudgets": ["perf/thresholds.yml"]
}
```

`exclude` 只能沉默暧昧的话。它从不让秘密支票沉默， 凭据路径(`.env`， `*.pem`，……)或强烈措词(`auth`， `jwt`， `migrations` 在代码中)。编辑 `canonkit.json` 它本身就是一扇门。不要编辑 钩子使门停止发射：下一个安装覆盖它。完整的规则 在 [文档/ hooks.md](https://github.com/erikalira/canonkit/blob/main/docs/hooks.md).

### 如果没有门着火

运行 `npx canonkit doctor`． 钩子打不开 目的，所以一个坏的或未注册的钩子永远不会阻止你的会话。这也 意思是钩子断了不会发出警告。

## 运行时

| 运行时 | 代理 | 规则 | 挂钩和门 |
| --- | --- | --- | --- |
| 克劳德代码 | `~/.claude/agents` | `~/AGENTS.md` +块内 `~/.claude/CLAUDE.md` | 是 |
| 食典委 | `$CODEX_HOME/agents/*.toml` （`~/.codex`） | `~/AGENTS.md` +块内 `$CODEX_HOME/AGENTS.md` | 两个拒绝门（git旁路，秘密），一次连线；其余的靠判断 |
| OpenCode 2（可选择加入） | `~/.config/opencode/agents` | 块在 `~/.config/opencode/AGENTS.md` | 两个拒绝大门，加上一个提示 `git commit`/`git push` 打好了，接好了；其余的靠判断 |

每个目标是如何生成的，以及为什么OpenCode是可选的： [文档/ install.md](https://github.com/erikalira/canonkit/blob/main/docs/install.md#codex). 哪个门在每个运行时做什么： [文档/ hooks.md](https://github.com/erikalira/canonkit/blob/main/docs/hooks.md#codex-and-opencode).

## 命令

| 命令 | 它是做什么的 |
| --- | --- |
| `install` | 核心代理、钩子、仪表板、全局块、技能(`--claude` / `--codex` / `--opencode` 跳过菜单) |
| `install --wire-hooks` | 相同的，并连接每个安装的运行时的钩子（Claude Code, Codex, OpenCode） |
| `doctor` | 检查安装情况；1号出口开 `FAIL` |
| `reference` | 只有全局块和技能 |
| `uninstall [--claude] [--codex] [--opencode]` | 删除跟踪的全局工件；没有旗子，都是有记录的背带 |
| `add <name>...` / `remove <name>...` | 当前项目中的专家或堆栈打包技能 |
| `list` | 花名册和什么是安装在哪里 |
| `tool add|remove|list` | 集成 [图形化或开放说明](https://github.com/erikalira/canonkit/blob/main/docs/tools.md) 在当前项目中 |

`--dry-run` 工作于每一个写的命令：它报告什么会改变和 写什么。

## 常见问题解答

**每回合的成本是多少？** 克劳德代码列出了所有已安装的代理程序 每个回合的描述。这个列表加上两个全局块总共是 3 k令牌。代理的整个主体（约1-2k个令牌）仅在代理处于 派遣。 [测量](https://github.com/erikalira/canonkit/blob/main/docs/evals.md#always-loaded-cost).

**它会对每一笔小额找零都派出特工吗？** 这是不应该的。低工作时间 按规则内联。在每次发布之前，改变指令，路由 Eval用上面的拼写错误修复之类的情况检查这一点。如果你看到它发生， 请 [打开一个问题](https://github.com/erikalira/canonkit/issues).

**我可以编辑已安装的代理吗？** 不到位：下一个 `install` 覆盖 `~/.claude/agents` 还有托管块。要更改一个，请创建一个 使用不同名称的项目代理，或者更改此处的源代码并重新安装 （[文档/ maintaining.md](https://github.com/erikalira/canonkit/blob/main/docs/maintaining.md)）. 托管块之外的文本 标记 `~/AGENTS.md` 和 `~/.claude/CLAUDE.md` 是你的，被保存。

**有东西离开我的机器吗？** 钩子使遥测保持在本地 `~/.claude/canonkit-activity/`;新记录省略任务描述和命令 片段，但仍然包括路径和标识符以及计数和计时。 旧的记录可以保留这些文本直到轮换。两个 [项目附带问题](https://github.com/erikalira/canonkit/blob/main/docs/out-of-scope-issues.md) 还有可选的 [学习循环贡献](https://github.com/erikalira/canonkit/blob/main/docs/learning-loop.md#contributing-a-general-improvement) 提供经消毒的草稿；出版需要您的审阅和明确授权。原始的日志 而个人的回忆不属于一份贡献。 [字段列表](https://github.com/erikalira/canonkit/blob/main/docs/telemetry.md#stable-fields).

**一扇门在变化中被点燃，我确定是低的。** 确认并说明原因。如果是一样的 路径总是无缘无故触发门，加到 `highRisk.exclude` (见 [当门着火时](https://npmcn.com/package/canonkit/#readme-when-a-gate-fires)）。

**如何卸载？** 运行 `npx canonkit uninstall --dry-run` 预览一下 `npx canonkit uninstall` （或选择带标志的挽具）。它使用安装 清单，备份编辑过的藏物，完整保存观察到的藏物 并保持外部内容的管理 块。预清单安装和模糊的布线需要手动清理；看到 [文档/ install.md](https://github.com/erikalira/canonkit/blob/main/docs/install.md#uninstalling).

**我升级 `meu-time`.** `install` 迁移日志文件夹和树叶 旧钩子名的转发器。看到 [文档/ install.md](https://github.com/erikalira/canonkit/blob/main/docs/install.md#upgrading-from-meu-time).

## 文档

| 医生 | 为 |
| --- | --- |
| [文档/ install.md](https://github.com/erikalira/canonkit/blob/main/docs/install.md) | 每个安装写什么，Codex/OpenCode细节，专家，参考块和技能，升级，卸载 |
| [文档/ hooks.md](https://github.com/erikalira/canonkit/blob/main/docs/hooks.md) | 钩子接线，运行时间门，故障模式， `canonkit.json` 规则和全球方言 |
| [文档/ telemetry.md](https://github.com/erikalira/canonkit/blob/main/docs/telemetry.md) | 调度指标，日志字段，上下文贡献者，仪表板 |
| [文档/ team.md](https://github.com/erikalira/canonkit/blob/main/docs/team.md) | 完整的花名册，领域边界，代理惯例，集成审查 |
| [文档/ tools.md](https://github.com/erikalira/canonkit/blob/main/docs/tools.md) | 图形化和openspec集成，以及它们的安全注意事项 |
| [文档/ maintaining.md](https://github.com/erikalira/canonkit/blob/main/docs/maintaining.md) | 编辑代理、文件格式、 `validate.sh`、测试 |
| [文档/ evals.md](https://github.com/erikalira/canonkit/blob/main/docs/evals.md) | 路线和质量评估，方法和结果 |
| [文档/ learning-loop.md](https://github.com/erikalira/canonkit/blob/main/docs/learning-loop.md) | 调查错误并提出评估后的教学变更建议 |
| [文档/ out-of-scope-issues.md](https://github.com/erikalira/canonkit/blob/main/docs/out-of-scope-issues.md) | 保存偶然的项目发现并批批批准问题草案 |
| [文档/ adr /](https://github.com/erikalira/canonkit/tree/main/docs/adr) | 体系结构决策 |

## 许可证

[麻省理工学院](https://github.com/erikalira/canonkit/blob/main/LICENSE)

## 常见问题

### canonkit 是什么？

一个版本代理团队，为Claude Code， Codex和OpenCode。安装10个核心代理和5个可选域专家，每个拥有一个域并对自己的风险进行分类。

### 如何安装 canonkit？

在项目目录运行 npm install canonkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 canonkit，可以用 npx canonkit 直接运行。

### canonkit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/canonkit 是否存在。

### canonkit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### canonkit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### canonkit 可以商用吗？

canonkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### canonkit 还在维护吗？

最新版本 2\.4\.0 发布于 2026/11/03（今天）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/05/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。