# @cosmicdrift/kumiko-guards 中文文档

规范地址：https://npmcn.com/package/%40cosmicdrift/kumiko-guards/

版本：0\.419\.0
npm 元数据更新时间：2026-11-10T16:29:11.695Z
中文译文更新时间：2026-11-10T20:10:24.751Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cosmicdrift/kumiko-guards
原文对照：https://npmcn.com/package/%40cosmicdrift/kumiko-guards/?lang=original
项目主页：https://kumiko.rocks/
源码仓库：https://github.com/CosmicDriftGameStudio/kumiko-framework

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

- 包体积（解压后）：909 kB，107 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@cosmicdrift/kumiko-framework 0\.419\.0
- 首次发布：2026-09-16T06:40:03.556Z
- 最新版本发布：2026-11-10T16:29:11.337Z
- 近 30 天下载量：20793（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：153（近 12 个月 153 个）

## 中文简介

以AST为基础的Kumiko repos的保安:直通fs/fatch,租户升级,admin-API,逃生舱口和相关检查,运行于一个共享的ts-morph项目.

## 安装

```sh
npm install @cosmicdrift/kumiko-guards
```

也可以使用：`pnpm add @cosmicdrift/kumiko-guards`、`yarn add @cosmicdrift/kumiko-guards`、`bun add @cosmicdrift/kumiko-guards`

## README

# @cosmicdrift/kumiko-护卫

AST 守卫和回放检查 单个需要多个回放的Kumiko 档案:直接实体写作、租户升级、未申报出逃舱口, `openToAll` 无缘无故地 缺少了拒绝进入的测试和回购检查. 单文件检查( 直接 fs/ fetch, 日期 API, 测试标题, 原始 HTML, ...) 生物预设 `@cosmicdrift/kumiko-framework/biome-rules` 作为内建和 GritQL 插件 。 每一项调查结果都必须明确雷波自己的安全基线; 没有卫兵跳出旗子.

```
bun node_modules/@cosmicdrift/kumiko-guards/src/run-guards.ts [--explain|--write-security-baseline]
```

基线为: `.kumiko-security-baseline.json` 在消费者中 复发相根. `--explain` 打印已解析的 repo 和 per guard 扫描范围 没有任何警卫; `--write-security-baseline` 冻结当前 将结果输入基线文件.

## 依赖性检查

3个子命令检查 repo 的依赖性 `cwd` 请坐 他们叫 npm 注册或 `bun audit`,所以它们不是默认运行的一部分 非该部分 `checks`; 每个需要 `--report` (仅打印,出入口0;用于 `outdated` 它增加了中转和干支和被贬值的直接依赖 仍为一出. `outdated` 列出登记册未回答的每个软件包 在没有直接依赖者得到答案时失败.

```
bunx kumiko-guards licenses   # licence allow/gray/deny classification of installed packages
bunx kumiko-guards security   # bun audit: critical/high block, moderate warns
bunx kumiko-guards outdated   # installed direct dependencies the registry marks deprecated
```

已安装软件包`licenses`, (中文(简体) ), `outdated`读取自 `node_modules` 会 议 日 程 和 议 程 repo root, 它的工作空间成员和每个祖先目录, 分辨率 Bun自己用,所以一个高起的家长工作空间和 `.wt/` 工作树工作。 若为 没有找到命令失败( 没有扫描) . `security` 审计 重传根 `bun.lock`,或最近的祖先的 (宣布) 当回波有 无, 如果没有锁文件则失败 .

例外情况需要说明理由、审查人和终止日期。 货船 缺省数(`dependency-license-exceptions.json`, (中文(简体) ), `dependency-security-exceptions.json`); repo 中的同名文件 根(和,用于 `licenses`在一个祖先 `node_modules` 已扫描) 合并在顶上。 安全例外在14天内失效.

## Raw-SQL 标记

`guard-raw-sql` 块 `.unsafe()` 编号 : `asRawClient()` 外部 `db/queries/*`, (中文(简体) ), `db/query.ts` 和测试代码。 A 类 `// kumiko-lint-ignore raw-sql <reason>` 在调用线上或上面的线上标记,只压制其 (文件,理由)对被冻结在 `.kumiko-raw-sql-baseline.json` 在回购 树根。 一个没有基线条目的新或重新填入的标记没有检查结果,所以 每一个例外都作为基准 diff在审查。 没有基线文件 守卫只发出警告,所以消费者不会崩溃。 优先键入 `db/query` 帮助者; 故意冻结例外:

```
bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql
```

重写原因为新条目:再运行指令并审查diff. 一个已删除的标记会留下一个不失败的 stale 条目; 相同的命令 放下枪.

## `kumiko-pre-push`

一个POSIX-sh 预推钩,通过复制包的接线 `hooks/pre-push` 嘘 `.husky/pre-push`。shim执行最近的可执行文件 `node_modules/.bin/kumiko-pre-push` 从树根向上 没有自己的 `node_modules` 通过父设备安装解决,最多 包括 `$HOME`,跳过由另一个用户拥有或可写入的祖先 组/其他)和未关闭 `bun install` 当不存在时提示。 内部 它运行一个范围化的工作空间 `bun check` 页:1 仅驱动重播; 在独立的克隆中, 它运行重播自己的 `package.json` `test` 剧本. 从a `.wt/<name>` 母树下的工作树 它运行一个跟踪的工作空间 `scripts/check-wt.sh` 如果存在,否则 工作树自己的 `package.json` 脚本 `typecheck`, (中文(简体) ), `lint`, (中文(简体) ), `test`,以及 `test:dom` 直接在工作树上——父母的 `bun check` 否则将检查主检出,然后 `kumiko-guards guards`, (中文(简体) ), `ui` (仅无空) `uiRoots` 内 `kumiko.json`, (中文(简体) ), 与 `kumiko check`, (中文(简体) ), `checks`, (中文(简体) ), `comment-lang` 财务报告和审定财务报表 `public-exports-changelog`。 。 。 . 货包的退货 `packages/guards/src/cli.ts` 这些 没有绕行开关 。 A 类 `check-wt.sh` 包接此钩子( 通过 `exec` 或作为一个孩子的过程)被承认,所以钩子不再叫它 并跳过飞行前的步骤(`pre-push-extra.sh`升职后卫, 外跑已经做了 识别需要记录的拥有者 PID (单位:千美元)`KUMIKO_CHECK_WT_OWNER`) 是一个进程或祖先运行 `scripts/check-wt.sh`随机 `KUMIKO_CHECK_WT_NONCE` 符合 0600文件 `kumiko-prepush-<pid>` 在一个普通目录中。 设置变量 手( 手 )`KUMIKO_CHECK_WT_OWNER=$$ git push`因此,不跳过任何文件 完成的运行被下一个推力所覆盖.

扩展点: 有轨可执行文件 `scripts/pre-push-extra.sh` 运行 在主检查前,每个分支(工作树、父母范围,以及 独立) `KUMIKO_PUSH_REPO_ROOT` 财务报告和审定财务报表 `KUMIKO_PUSH_PARENT_DIR` 可用内线( 从未导出, 因此没有其它东西继承 ) 。 一个 未跟踪或无法执行 `scripts/pre-push-extra.sh` 从不运行——这个 无法关闭,所以一个流出或未经审查的文件 无法劫持推进。 一个非零 退出从 `pre-push-extra.sh` 在主检查运行前中止推动.

## 常见问题

### @cosmicdrift/kumiko-guards 是什么？

以AST为基础的Kumiko repos的保安:直通fs/fatch,租户升级,admin-API,逃生舱口和相关检查,运行于一个共享的ts-morph项目\.

### 如何安装 @cosmicdrift/kumiko-guards？

在项目目录运行 npm install @cosmicdrift/kumiko-guards，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 kumiko-guards、kumiko-pre-push，可以用 npx kumiko-guards 直接运行。

### @cosmicdrift/kumiko-guards 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cosmicdrift/kumiko-guards 支持 ESM 还是 CommonJS？

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

### @cosmicdrift/kumiko-guards 可以商用吗？

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

### @cosmicdrift/kumiko-guards 的下载量有多少？

根据 npm 官方下载统计，@cosmicdrift/kumiko-guards 在 2026/10/11 – 2026/11/09 这 30 天内被下载 20,793 次，日均约 693 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cosmicdrift/kumiko-guards 还在维护吗？

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