@gitkraken/shared-tools

中文文档
0.3.0发布于 2026/10/07SEE LICENSE IN LICENSETypeScriptES Module零依赖近 30 天下载 7457

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

中文使用文档
文档目录18 节
  1. 港口
  2. GitPort
  3. AiModelPort
  4. StoragePort
  5. TelemetryPort
  6. FileSystemPort
  7. 实施港口
  8. 示例 GitPort 适配器
  9. 示例 AiModelPort 适配器
  10. 撤消列表
  11. capturePreOperationState(git, options?)
  12. UndoStore
  13. generateUndoId()
  14. undoOperation(input) 财务报告和审定财务报表 validateUndo(input)
  15. 出口
  16. 运行时环境
  17. 捐款
  18. 修改端口的设计限制

@ gitkraken/ 共享工具

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

港口

GitPort

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

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

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

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- 支持实施测试.

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

TelemetryPort

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

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

FileSystemPort

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

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 适配器

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 适配器

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 捐款额。本地命令:

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 共发布 6 个版本,首次发布于 2026/04/24;过去 12 个月发布了 6 个版本。

版本发布日期距今
0.3.0latest2026/10/071 个月前
0.2.1-beta.2next2026/07/034 个月前
0.2.1-beta.12026/07/034 个月前
0.2.02026/05/146 个月前
0.1.12026/05/126 个月前
0.1.02026/04/246 个月前

关于 @gitkraken/shared-tools 的常见问题

@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 和提交记录判断。