# @gitkraken/shared-tools 中文文档

规范地址：https://npmcn.com/package/%40gitkraken/shared-tools/

版本：0\.3\.0
npm 元数据更新时间：2026-10-07T15:27:41.565Z
中文译文更新时间：2026-11-16T11:22:49.943Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40gitkraken/shared-tools
原文对照：https://npmcn.com/package/%40gitkraken/shared-tools/?lang=original

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

- 包体积（解压后）：51 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 22
- 运行依赖：0 个
- 首次发布：2026-04-23T22:39:42.613Z
- 最新版本发布：2026-10-07T15:27:41.384Z
- 近 30 天下载量：7457（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

@ gitkraken 核心工具的端口接口, 共享类型, 以及取消功能的机器 .

## 安装

```sh
npm install @gitkraken/shared-tools
```

也可以使用：`pnpm add @gitkraken/shared-tools`、`yarn add @gitkraken/shared-tools`、`bun add @gitkraken/shared-tools`

## README

# @ gitkraken/ 共享工具

端口接口、共享类型和用于 `core-tools` 单相机 域包( 如 `@gitkraken/compose-tools`)依赖于这个软件包;消费者用自己的git和AI供应商来实施其端口.

## 港口

### `GitPort`

Raw git 命令执行 。 启动非零退出密码.

```typescript
interface GitPort {
    exec(args: string[], options?: GitExecOptions): Promise<string>;
}

interface GitExecOptions {
    env?: Record<string, string>;
    stdin?: string;
    signal?: AbortSignal;
}
```

所有更高层次的git操作(diffing, content building, ref management, rebase coordersion等)都是域包中的功能,用于编译调用 `exec()`消费者从未在这一界面上执行更高层次的操作——见 `ComposeGitPort` 内 `@gitkraken/compose-tools` 用于该域特有的可选更高层次操作表面.

`signal` 从每个接受一个域的工作流程中转发 `AbortSignal`适配器应该将它连接到其 git-进程执行中,所以取消会终止进程.

### `AiModelPort`

无国籍文本生成 。 呼叫者通过每个呼叫的全部消息历史——会话线程是呼叫者的责任,而不是模型的责任.

```typescript
interface AiModelPort {
    generate(params: AiGenerateParams): Promise<AiGenerateResult>;
}

interface AiGenerateParams {
    system?: string;
    messages: AiMessage[];
    maxTokens?: number;
    temperature?: number;
    signal?: AbortSignal;
}

interface AiGenerateResult {
    text: string;
    usage?: AiTokenUsage;
}
```

`signal` 从每个AI工作流程中转发。 适配器应该把它接入 LLM 请求中 取消飞行中通话.

### `StoragePort`

Async key/value store for a library's own state, 已被主机范围化 . 无TTL; `get` 返回时 `null` 对于一个缺失的密钥. `createMemoryStorage()` 是不可延长的 `Map`\- 支持实施测试.

```typescript
interface StoragePort {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
    delete(key: string): Promise<void>;
}
```

### `TelemetryPort`

火灾和遗忘的遥测水槽;执行不得抛出. `noopTelemetry` 是主机注入一无所有时的默认值。 呼叫者通过可以持有 URL 或错误文本的属性 `redactUrlCredentials`。 。 。 .

```typescript
interface TelemetryPort {
    event(name: string, attributes?: TelemetryAttributes): void;
    exception(error: unknown, attributes?: TelemetryAttributes): void;
}
```

### `FileSystemPort`

文件系统访问超过绝对的,主机提供的路径. 缺席是 `null`· ; `remove` 缺少并丢入非空目录时为无操作, 除非 `recursive` 设置; `mode` 是非 POSIX 主机忽略的 POSIX 权限 .

```typescript
interface FileSystemPort {
    readFile(path: string): Promise<string | null>;
    writeFile(path: string, content: string, options?: { mode?: number }): Promise<void>;
    remove(path: string, options?: { recursive?: boolean }): Promise<void>;
    readDir(path: string): Promise<string[] | null>;
}
```

## 实施港口

消费者将自己的git和AI供应商包装成适配器. 适配器可以分层遥测,缓存,错误处理,取消,优先排队,或者其他任何行为——都不可见于域包.

### 示例 `GitPort` 适配器

```typescript
import type { GitPort } from '@gitkraken/shared-tools';

const git: GitPort = {
    exec: async (args, options) => {
        const result = await myGitProvider.run(args, {
            cwd: '/path/to/repo',
            env: options?.env,
            stdin: options?.stdin,
            signal: options?.signal,
        });
        return result.stdout;
    },
};
```

### 示例 `AiModelPort` 适配器

```typescript
import type { AiModelPort } from '@gitkraken/shared-tools';

const ai: AiModelPort = {
    generate: async (params) => {
        const response = await myAiProvider.chat(params.messages, {
            system: params.system,
            maxTokens: params.maxTokens,
            temperature: params.temperature,
            signal: params.signal,
        });
        return {
            text: response.text,
            usage: { inputTokens: response.inputTokens, outputTokens: response.outputTokens },
        };
    },
};
```

## 撤消列表

域包使用这些原始来记录一次操作的每次git突变,并随后回放倒数. 机器是共享的,因为它的外形是通俗的——任何能移动回放或改变活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活.

### `capturePreOperationState(git, options?)`

抓取工作流程触摸到任何东西之前的操作前状态 :

-   目前HEAD SHA和分支名称.
-   当前工作目录的解密藏出( 通过 `git stash create`当工作日是脏的时侯, **没有** 添加到隐藏列表中 .

撤消使用此快照恢复头部和工作目录 。 抓取帮助器在建立存储器时注意不突变真实的git索引——它使用临时索引通过 `GIT_INDEX_FILE` 所以消费者的状态 从来没有被扰动.

### `UndoStore`

阅读和写作 `UndoManifest` 对象输入 repo 对象数据库 `refs/undo/<id>`。特性在分支操作中幸存,在撤销运行时自动被去除。 提供 `save(manifest)`, (中文(简体) ), `load(id)`, (中文(简体) ), `list()`, (中文(简体) ), `delete(id)`。 。 。 .

### `generateUndoId()`

显示一个稳定的UUID,用于新的取消列表 .

### `undoOperation(input)` 财务报告和审定财务报表 `validateUndo(input)`

核心撤消执行和干运行验证符 。 域包(像作曲)用自己的输入类型来包装这些- `undoCompose` 以编剧工具代表 `undoOperation` 翻译后.

## 出口

数值 :

-   `createMemoryStorage`
-   `noopTelemetry`
-   `redactUrlCredentials`
-   `capturePreOperationState`
-   `generateUndoId`
-   `UndoStore`
-   `undoOperation`
-   `validateUndo`

类型 :

-   `GitPort`, (中文(简体) ), `GitExecOptions`
-   `AiModelPort`, (中文(简体) ), `AiGenerateParams`, (中文(简体) ), `AiGenerateResult`, (中文(简体) ), `AiMessage`, (中文(简体) ), `AiTokenUsage`
-   `StoragePort`, (中文(简体) ), `TelemetryPort`, (中文(简体) ), `TelemetryAttributes`, (中文(简体) ), `FileSystemPort`
-   `AiCreditUsage`, (中文(简体) ), `GetAiCreditUsage`
-   `PreOperationState`, (中文(简体) ), `UndoManifest`, (中文(简体) ), `UndoId`
-   `RefKind`, (中文(简体) ), `RefIdentity`, (中文(简体) ), `RefSnapshot`, (中文(简体) ), `RefMovement`
-   `UndoBlocker`, (中文(简体) ), `UndoWarning`, (中文(简体) ), `UndoValidation`
-   `UndoInput`, (中文(简体) ), `UndoForceOptions`, (中文(简体) ), `UndoResult`, (中文(简体) ), `ValidateUndoInput`

也导出 : `refKindToFullRefname(kind, name)` 用于解析标记为全名的身份.

## 运行时环境

这个软件包使用节点.js内置(`node:crypto`, (中文(简体) ), `node:fs`, (中文(简体) ), `node:os`, (中文(简体) ), `node:path`在倒置机械。 在任何环境中,只输入类型都是安全的;运行时间使用 `UndoStore`, (中文(简体) ), `capturePreOperationState`, (中文(简体) ), `generateUndoId`, (中文(简体) ), `undoOperation`, (中文(简体) ), `validateUndo` 需要节点运行时间.

## 捐款

此套件遵循了 monrepo 的标准工具 – 见 root [捐款额](https://npmcn.com/package/CONTRIBUTING.md)。本地命令:

```bash
pnpm --filter @gitkraken/shared-tools build
pnpm --filter @gitkraken/shared-tools typecheck
pnpm --filter @gitkraken/shared-tools test
```

### 修改端口的设计限制

港口是故意最小和稳定的。 添加方法到 `GitPort` 或者说 `AiModelPort` 这对于每一个消费者来说都是一个突破性的变化——每一个执行都必须更新。 在提出新方法之前:

1.  确认操作不能表示为基于 `exec()` 或者说 `generate()`。 。 。 .
2.  确认操作需要多个域包(不仅仅是一个).
3.  确认任何消费者都无法合理地在适配器中以不同方式实施该软件.

当堆叠的变更需要合同在使用该合同的包件之前到位时,新港口可能先于消费者落地.

在实践中,新的方法应该是罕见的。 默认的答案是“这是否应该进入港口?” **没有** ——将其放入一个域包中作为调用功能 `exec()` 编号 : `generate()` 内部或特定域的端口界面(参见 `ComposeGitPort` 以作曲工具.

## 常见问题

### @gitkraken/shared-tools 是什么？

@ gitkraken 核心工具的端口接口, 共享类型, 以及取消功能的机器 \.

### 如何安装 @gitkraken/shared-tools？

在项目目录运行 npm install @gitkraken/shared-tools，或使用 pnpm add / yarn add / bun add。

### @gitkraken/shared-tools 支持 TypeScript 吗？

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

### @gitkraken/shared-tools 支持 ESM 还是 CommonJS？

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

### @gitkraken/shared-tools 需要什么版本的 Node\.js？

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

### @gitkraken/shared-tools 可以商用吗？

@gitkraken/shared-tools 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @gitkraken/shared-tools 的下载量有多少？

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

### @gitkraken/shared-tools 还在维护吗？

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

