# @cleocode/git-shim 中文文档

规范地址：https://npmcn.com/package/%40cleocode/git-shim/

版本：2026\.11\.1
npm 元数据更新时间：2026-11-12T05:56:24.046Z
中文译文更新时间：2026-11-12T06:00:41.652Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cleocode/git-shim
原文对照：https://npmcn.com/package/%40cleocode/git-shim/?lang=original
项目主页：https://github.com/kryptobaseddev/cleo#readme
源码仓库：https://github.com/kryptobaseddev/cleo

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

- 包体积（解压后）：236 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.16\.0
- 运行依赖：2 个
- 首次发布：2026-04-23T05:09:27.519Z
- 最新版本发布：2026-11-12T05:56:23.653Z
- 近 30 天下载量：12278（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：268（近 12 个月 268 个）

## 中文简介

保护CLEO代理分支(T1118)

## 安装

```sh
npm install @cleocode/git-shim
```

也可以使用：`pnpm add @cleocode/git-shim`、`yarn add @cleocode/git-shim`、`bun add @cleocode/git-shim`

## README

# @ cleocode/ git-shim (英语)

> 部分 [平等机会委员会](https://github.com/kryptobaseddev/cleo#readme)。从 root README 开始;运行 `cleo <command> --help` 对于任何命令.

策略-不可知论 `git` PATH 覆盖了栅栏代理( 工人 \\\\ \\ 领导 \\ ) 副代理人) 被引用. 提供两层强制执行:

1.  **T1118 拒绝列表** ——分行流动业务 (单位:千美元)`checkout`, (中文(简体) ), `switch`, (中文(简体) ), `branch -D`, (中文(简体) ), `worktree add`, (中文(简体) ), `reset --hard`, (中文(简体) ), `rebase`, (中文(简体) ), `push --force`(见a/c.5/49/70,附件).
2.  **T1591 边界围栏** - 相关规则与 工作树与违约模式(ADR-055)+工作树与综合 (ADR-062): (英语)
    -   **(a) 国家** `git add` 活动工作树内的必经舞台路径.
    -   **(b) 国家** `git commit -m "<msg>"` 必须嵌入 CLEO 任务ID (单位:千美元)`T<NUM>`) (中文(简体) ).
    -   **(c))** `git merge` 需要由 `completeAgentWorktreeViaMerge` (通过 `CLEO_ORCHESTRATE_MERGE=1`) (中文(简体) ).
    -   **(d)** `git cherry-pick <ref>` 千万不要拿一个 `task/T<NUM>` 来源 (樱桃从工作树树枝上摘取是腐烂的融合) 路径被ADR-062所取代.

每个区块和每个绕行都被记录在 `<XDG_DATA_HOME ?? ~/.local/share>/cleo/audit/git-shim.jsonl`。 。 。 .

## 安装

闪电船作为 `git` 此软件包的本条目。 指挥家 实现a `git` 内相链接 `<projectRoot>/.cleo/bin/` (或任何 shim 目录)通过 `installShimSymlink(...)` 并预留 产出物剂目录 `PATH`。 。 。 .

## 激活门

Shim仅在代理角色受到限制时执行:

```bash
CLEO_AGENT_ROLE=worker  # or lead, subagent
```

兽人(无 `CLEO_AGENT_ROLE` 或者说 `CLEO_AGENT_ROLE=orchestrator`绕过shim完全 —— 这保持 管弦乐编码路径快而无拘束.

## 环境合同

| 变量 | 设定 | 目的 |
| --- | --- | --- |
| `CLEO_AGENT_ROLE` | 管弦乐手(发作) | 为被限制的角色激活栅栏. |
| `CLEO_WORKTREE_ROOT` | 管弦乐手(发作) | 明确的工作树路径;自动从cwd中检测到其他路径. |
| `CLEO_TASK_ID` | 管弦乐手(发作) | 活动任务 ID; 自动出自工作树路径. |
| `CLEO_ORCHESTRATE_MERGE` | `completeAgentWorktreeViaMerge` (T1587) (中文(简体) ) | 单一用途赠款——允许 `git merge`. 见下文. |
| `CLEO_ALLOW_BRANCH_OPS` | 运算符(手工) | 遗产拒绝列表的单发绕道. 经审计. |
| `CLEO_ALLOW_GIT` | 运算符(紧急) | 任何T1591边界块的通用绕道. 经审计. |
| `CLEO_AUDIT_LOG_PATH` | 测试 | 覆盖审计日志位置. |
| `CLEO_REAL_GIT_PATH` | 测试 | 跳过 PATH 步; 使用此二进制作为真正的 git . |
| `CLEO_SHIM_MARKER` | 安装器( 可选) | 识别 shim dir 的路径碎片 。 默认 : `.cleo/bin/git-shim`。 。 。 . |

## `CLEO_ORCHESTRATE_MERGE=1` 合同(T1587/ADR-062集成)

`packages/core/src/spawn/branch-lock.ts::completeAgentWorktreeViaMerge` 这是 **仅限** 被制裁的入境点 `git merge` cLEO任务 树枝。 它必须设置 `CLEO_ORCHESTRATE_MERGE=1` 在洞穴中传入 产卵 `git merge --no-ff` 进程。 shim的边界(c)拒绝任何 其他项目 `git merge` 援引有限的作用.

具体(见 `branch-lock.ts:830`:

```ts
execFileSync('git', ['merge', '--no-ff', branch, '-m', subject], {
  cwd: gitRoot,
  encoding: 'utf-8',
  stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...process.env, CLEO_ORCHESTRATE_MERGE: '1' },
});
```

如果您发现了需要引用的代码路径 `git merge` 从 有限作用上下文 **其他** `completeAgentWorktreeViaMerge`, (中文(简体) ), 提交后续任务——不要默默设置 `CLEO_ORCHESTRATE_MERGE=1` 别的地方 狭义的内地是边界 可审计.

`--abort`, (中文(简体) ), `--continue`,以及 `--quit` 引用旗帜是例外的—— 它们不进行合并.

## 旁通工作流程

对于正当的紧急情况(如操作员热修,事件分解):

```bash
# One-off bypass; audit entry written to git-shim.jsonl.
CLEO_ALLOW_GIT=1 git <subcommand> ...
```

绕行器有完整的上下文记录(子命令、参数、cwd、角色、, 任务 d, 工作树 path 。 审查者可通过下列方式列出绕行:

```bash
jq 'select(.outcome | startswith("bypassed"))' \
  ~/.local/share/cleo/audit/git-shim.jsonl
```

## 审计记录计划a

```ts
interface AuditRecord {
  ts: string;                          // ISO 8601
  outcome: 'blocked' | 'bypassed-allow-git' | 'bypassed-orchestrate-merge';
  boundary: 'a' | 'b' | 'c' | 'd' | 'denylist';
  code: string;                        // E_GIT_OP_BLOCKED | E_GIT_BOUNDARY_*
  subcommand: string;
  args: string[];
  cwd: string;
  worktree_path: string | null;
  task_id: string | null;
  role: string | null;
  context: Record<string, string>;
}
```

计划为项目不可知性:下面的审计日志 `~/.local/share/cleo/audit/` 由每个CLEO管理 在主机上的项目.

## 深入防御管道

Git- 二进制栅栏( 此套件) 是多检查点的一层 管道:

| 层 | 软件包 | 接头 |
| --- | --- | --- |
| Git 二进制 | `@cleocode/git-shim` (这个) | 代理人的直接援引 |
| 提交 msg 钩子 | `@cleocode/core` (T1588) (法语) | 编辑流程输入( 无内置) `-m`(中文(简体) ) |
| 漂流监视器 | `@cleocode/core` (T1594) (中文(简体) ) | 在工作树外修改的文件 |
| 预推调节 | `@cleocode/core` (T1595) (中文(简体) ) | 推动前分行状态漂移 |
| 同步插件 | CI(T1598) (中文(简体) ) | 审查时间政策错配 |

T1588(hook)和T1591(shim,边界b)均强制执行 承诺主题 T -ID规则。 这是蓄意深入辩护:a 禁用本地钩子的开发者仍然会通过 shim .

## 参考资料

-   ADR-055 — 工作树与违约代理隔离
-   ADR-062——工作树一体化 `git merge --no-ff` (不是樱桃点心)
-   T1118 — 原始分支锁定引擎( 密度列表)
-   T1587次列车 - `completeAgentWorktreeViaMerge` (套数) `CLEO_ORCHESTRATE_MERGE=1`(中文(简体) )
-   T1591——这一围栏(边界a/b/c/d)

## 常见问题

### @cleocode/git-shim 是什么？

保护CLEO代理分支\(T1118\)

### 如何安装 @cleocode/git-shim？

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

### @cleocode/git-shim 支持 TypeScript 吗？

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

### @cleocode/git-shim 支持 ESM 还是 CommonJS？

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

### @cleocode/git-shim 需要什么版本的 Node\.js？

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

### @cleocode/git-shim 可以商用吗？

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

### @cleocode/git-shim 的下载量有多少？

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

### @cleocode/git-shim 还在维护吗？

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