# @agent-relay/github-primitive 中文文档

规范地址：https://npmcn.com/package/%40agent-relay/github-primitive/

版本：7\.1\.1
npm 元数据更新时间：2026-05-25T06:53:18.220Z
中文译文更新时间：2026-11-05T21:43:29.698Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40agent-relay/github-primitive
原文对照：https://npmcn.com/package/%40agent-relay/github-primitive/?lang=original
项目主页：https://github.com/AgentWorkforce/relay#readme
源码仓库：https://github.com/AgentWorkforce/relay

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

- 包体积（解压后）：328 kB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-22T20:28:04.482Z
- 最新版本发布：2026-05-25T06:53:17.922Z
- 近 30 天下载量：16796（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

代理中继的 GitHub 工作流程原始

## 安装

```sh
npm install @agent-relay/github-primitive
```

也可以使用：`pnpm add @agent-relay/github-primitive`、`yarn add @agent-relay/github-primitive`、`bun add @agent-relay/github-primitive`

## README

# @ agent-relay/github-原始内容

GitHub 工作流程原始为代理中继器. 它暴露一个打字客户端和一个 工作流程整合步骤,可在本地运行 `gh` CLI 或一团云 GitHub 代理服务器 .

## 运行时间选择

原始模式支持三种运行模式:

-   `auto`:宁戈或中继云证书出现时更喜欢云, 以其他方式使用当地 `gh` 如有CLI的话.
-   `local`: 使用 `gh api` 从当前机器.
-   `cloud`:先使用南戈,再配置后使用中继-云代理.

```ts
import { GitHubClient } from '@agent-relay/github-primitive';

const github = await GitHubClient.create({
  runtime: 'auto',
});

const repo = await github.getRepo('AgentWorkforce', 'relay');
console.log(repo.defaultBranch);
```

## 行动

客户端和工作流程步骤支持:

-   仓库 : `listRepos`, (中文(简体) ), `getRepo`
-   问题: `listIssues`, (中文(简体) ), `createIssue`, (中文(简体) ), `updateIssue`, (中文(简体) ), `closeIssue`
-   拉动请求 : `listPRs`, (中文(简体) ), `getPR`, (中文(简体) ), `createPR`, (中文(简体) ), `updatePR`, (中文(简体) ), `mergePR`
-   文件 : `listFiles`, (中文(简体) ), `readFile`, (中文(简体) ), `createFile`, (中文(简体) ), `updateFile`, (中文(简体) ), `deleteFile`
-   分支和承诺: `listBranches`, (中文(简体) ), `createBranch`, (中文(简体) ), `listCommits`, (中文(简体) ), `createCommit`
-   身份 : `getUser`, (中文(简体) ), `listOrganizations`

## 工作流程步骤

```ts
import { createGitHubStep } from '@agent-relay/github-primitive/workflow-step';

createGitHubStep({
  name: 'read-readme',
  action: 'readFile',
  repo: 'AgentWorkforce/relay',
  params: {
    path: 'README.md',
  },
  output: {
    mode: 'data',
    format: 'text',
  },
});
```

见 `examples/github-step.ts` 用于工作流程运行实例和 `examples/github-client.ts` 为独立的客户端示例.

## 端到端的公关工作流程

`examples/end-to-end-pr-workflow.ts` 环绕整个公关寿命周期 单个运行时间 :

1.  `getRepo` ——检查+登录所选运行时间.
2.  `createBranch` 从基地分支.
3.  `createFile` ——在新分行上写出标记文件.
4.  `createPR` ——核心集成步骤云工作流程迁移到.
5.  `getPR` ——来回核实.
6.  `updatePR` ——编辑PR正文而无需更改代码.
7.  `listPRs` ——确认可索引性.
8.  (评论) `mergePR` 默认关闭,所以示例永远不会合并 任何真实的.

运行在抓取回:

```
GITHUB_REPO=AgentWorkforce/scratch npx tsx \
  packages/github-primitive/examples/end-to-end-pr-workflow.ts
```

运行时间选择是自动的 :

| 路径 | 触发当 |
| --- | --- |
| 当地 `gh` | `gh auth status` 成功且没有设置云卡 |
| 南戈语Name | `NANGO_SECRET_KEY` + 键 `NANGO_GITHUB_CONNECTION_ID` + 键 `NANGO_GITHUB_PROVIDER_CONFIG_KEY` 当前 |
| 中继云 | `RELAY_CLOUD_API_URL` + 键 `RELAY_CLOUD_API_TOKEN` + 键 `WORKSPACE_ID` 现值( 南戈缺席时返回) |

## 多租户路线

在云中,每个工作空间都有自己的 GitHub App 安装—— 一个南戈 每个租户的连接. `createGitHubStep` 接受每步 `config` 字段,所以单个工作流程可以通过 不同的连接。 一个工作流程,许多租户.

`examples/multi-tenant-pr-workflow.ts` 演示: 它打开 PR 内 `AgentWorkforce/cloud` (通过Agent Workforce app)和在一个 MSD自有回波(通过MSD的应用),来自相同的工作流程定义,由 更改 `config:` 字段.

### 云收养:解相助者

原始人留下的租户 - 不小心 `GitHubRuntimeConfig` 并按其所传. 租户的望相住在云中,在小地方 帮助者 :

```ts
// cloud/packages/web/lib/github/connection-resolver.ts
import type { GitHubRuntimeConfig } from '@agent-relay/github-primitive';

export async function githubConfigForRepo(opts: {
  repo: string; // "owner/repo"
  workspaceId?: string; // optional — cloud-owned repos default
}): Promise<GitHubRuntimeConfig> {
  const connection = await resolveWorkspaceIntegration(opts.workspaceId, 'github', opts.repo);

  return {
    runtime: 'auto',
    nango: {
      connectionId: connection.connectionId,
      providerConfigKey: connection.providerConfigKey, // 'github-agentworkforce' | 'github-msd' | 'github-nightcto' | ...
      secretKey: process.env.NANGO_SECRET_KEY,
    },
    relayCloud: {
      apiUrl: process.env.CLOUD_API_URL,
      accessToken: process.env.CLOUD_API_TOKEN,
      workspaceId: opts.workspaceId,
    },
  };
}
```

云中的工作流作者再写:

```ts
createGitHubStep({
  name: 'open-pr',
  action: 'createPR',
  repo: 'AgentWorkforce/cloud',
  params: { title, head, base, body },
  config: await githubConfigForRepo({
    repo: 'AgentWorkforce/cloud',
    workspaceId: process.env.RELAY_WORKSPACE_ID,
  }),
});
```

一个解决器,一个呼叫站台形状。 添加一个新的 GitHub App 安装是一个 `workspace_integrations` 行 + (可选) a `NANGO_*` 秘密 - 没有 创建 PR 的工作流程中的代码更改.

## 常见问题

### @agent-relay/github-primitive 是什么？

代理中继的 GitHub 工作流程原始

### 如何安装 @agent-relay/github-primitive？

在项目目录运行 npm install @agent-relay/github-primitive，或使用 pnpm add / yarn add / bun add。

### @agent-relay/github-primitive 支持 TypeScript 吗？

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

### @agent-relay/github-primitive 支持 ESM 还是 CommonJS？

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

### @agent-relay/github-primitive 可以商用吗？

@agent-relay/github-primitive 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-relay/github-primitive 的下载量有多少？

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

### @agent-relay/github-primitive 还在维护吗？

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