# @hasna/connectors 中文文档

规范地址：https://npmcn.com/package/%40hasna/connectors/

版本：1\.8\.0
npm 元数据更新时间：2026-10-16T22:31:34.116Z
中文译文更新时间：2026-11-17T11:37:32.856Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40hasna/connectors
原文对照：https://npmcn.com/package/%40hasna/connectors/?lang=original
项目主页：https://github.com/hasna/apps/tree/main/apps/connectors#readme
源码仓库：https://github.com/hasna/apps

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

- 包体积（解压后）：85.2 MB，20518 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：14 个
- 首次发布：2026-02-14T08:44:11.617Z
- 最新版本发布：2026-10-16T22:31:33.938Z
- 近 30 天下载量：47411（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：149（近 12 个月 149 个）

## 中文简介

开源连接器库 - 用单一命令安装 API 连接器

## 安装

```sh
npm install @hasna/connectors
```

也可以使用：`pnpm add @hasna/connectors`、`yarn add @hasna/connectors`、`bun add @hasna/connectors`

## README

# @ hasna/ 连接器

开源连接器平台,用于启用,认证,并从一个包运行API连接器.

[![npm](https://img.shields.io/npm/v/@hasna/connectors)](https://www.npmjs.com/package/@hasna/connectors) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/%40hasna/connectors/LICENSE)

## 安装

```bash
bun install -g @hasna/connectors
```

## 这是什么

`@hasna/connectors` 单产品运行时间 :

-   连接器停留在这个 repo 和软件包内
-   工程启用他们想要的连接符 `.connectors/manifest.json`
-   证书在连接器数据之家(由包件溶解器解决); `~/.hasna/connectors/` 直到 XDG 数据之家被采用)
-   CLI, MCP, REST, 以及本地的API/ OAuth 服务器都使用相同的连接器注册

## 本地或远程

连接器默认在本地运行, 无任何配置: CLI, MCP 服务器和 SDK 在进程中运行连接器引擎,并保持连接 当地商店.

使用服务器(一个您自己运行, 或任何会说话的服务) [`/v1` API 密码](https://npmcn.com/package/%40hasna/connectors/docs/api-v1.md)),指向客户端:

```bash
# One shell or CI job: environment variables
export CONNECTORS_API_URL=https://connectors.example.com
export CONNECTORS_API_KEY=...            # from your server administrator

# Or save it: the key is read from stdin or a hidden prompt, never from arguments
connectors login --api-url https://connectors.example.com
connectors config show                   # mode, server URL, whether a key is set
connectors logout                        # delete the stored key
connectors config unset api-url          # back to local mode
```

设置按此顺序解决: `--api-url` 编号 : `--api-key-stdin` 旗帜,然后 `CONNECTORS_API_URL` 编号 : `CONNECTORS_API_KEY`,则 `<connectors home>/config.json` (模式) `0600`时 `connectors login`),然后是本地模式。 保存的密钥是 只被发送到它保存的服务器上,没有密钥的服务器 URL 是 错误而非静态返回到本地模式, plain `http://` 实值 拒绝任何回扣,除非 `CONNECTORS_ALLOW_INSECURE_HTTP=1`。 。 。 .

服务连接器在两种模式中工作方式相同:

```bash
connectors service list
connectors service describe openai       # auth methods, operations and their effects
printf '{"adminKey":"%s"}' "$OPENAI_ADMIN_KEY" | \
  connectors connections add openai --auth admin_key --label prod-admin --secrets-stdin
connectors connections add openai --auth admin_key --label ci --secret-env adminKey=OPENAI_ADMIN_KEY
connectors connections list
connectors connections check openai:prod-admin
connectors call openai <operation> --connection prod-admin --input '<json object>'
connectors runs list --limit 20
```

发送的服务连接器是 `anthropic`, (中文(简体) ), `brandsight`, (中文(简体) ), `cloudflare`, (中文(简体) ), `cursor`, (中文(简体) ), `godaddy`, (中文(简体) ), `openai`, (中文(简体) ), `opencode`, (中文(简体) ), `stable` 财务报告和审定财务报表 `youtrust` (你们相信, 签名:签名请求、文件、收件人、审计线索和 网点; 见 [文件/提供者/你的信任](https://npmcn.com/package/%40hasna/connectors/docs/providers/youtrust.md)A级 您信任连接用平地选择环境 :

```bash
connectors connections add youtrust --auth api_key --label prod \
  --field environment=production --secret-env apiKey=YOUTRUST_API_KEY   # default: sandbox
connectors call youtrust signature_requests.list --connection prod --input '{"limit":10}'
```

保密连接字段从不被接受为参数( Name`--field` 拒绝 它们); 使用 `--secret-env key=ENV_NAME`, (中文(简体) ), `--secrets-stdin` 或者隐藏的提示. 非读取的操作( E)`write`, (中文(简体) ), `billable`, (中文(简体) ), `destructive`, (中文(简体) ), `credential`需求 `--confirm`A级 `credential` 结果,例如新铸造的 键,会显示一次且从未存储.

## 国 际

```bash
connectors --help
```

典型流量 :

```bash
connectors install github stripe
connectors auth github
printf '%s\n' "$STRIPE_API_KEY" | connectors auth stripe --key-stdin
connectors run github --help
connectors run stripe products list --limit 5
```

密钥命令 :

-   `connectors install` 写入工程启用到 `.connectors/manifest.json`
-   `connectors list` 财务报告和审定财务报表 `connectors search` 浏览共享目录
-   `connectors docs` 从内部登记册读取连接器文件
-   `connectors auth` 将证书存储在连接器数据之家(由包件解析器解决)
-   `connectors auth <name> --key-stdin` 从 Stdin 读取 API 密钥或无记名符号 `--key-env <VAR>` 从命名的环境变量读取. `connectors setup` 财务报告和审定财务报表 `connectors llm set` 一样 两旗 不要通过密钥作为命令行值: 它降落在 shell 历史和进程列表中 .
-   `connectors run` 执行单产品运行时的连接器命令
-   `connectors status` 财务报告和审定财务报表 `connectors doctor` 验证设置和认证状态

### 压缩输出默认值

CLI 输出默认是紧凑的, 所以代理终端不会充满巨大的 目录,README部分,证书状态表,或API记录.

-   `connectors list` 显示一个紧凑的页面。 使用 `--cursor <n>` 或者说 `--offset <n>` 下一页, `--limit <n>` 更改页面大小, `--verbose` 扩大范围 行,或 `--all --verbose` 为完整的人类目录. `--json` 现在返回 a 精密的20行信封, 有真实的 `total`, (中文(简体) ), `limit`, (中文(简体) ), `cursor`, (中文(简体) ), `next_cursor`,以及 `has_more`; 使用 `--json --verbose` 用于全域 限制页面,或 `--json --full` 编号 : `--json --all` 留下的遗产 阵列。 超过100分的受约束JSON限值在完全输出指导下被拒绝.
-   `connectors docs <name>` 显示一个摘要。 使用 `--verbose` 用于全解析 节, `--essential` 仅限认证/env vars, `--raw` 原始标记,或 `--json` 用于结构化文件.
-   `connectors status`, (中文(简体) ), `connectors doctor`, (中文(简体) ), `connectors jobs list`, (中文(简体) ), `connectors workflows list`, (中文(简体) ), `connectors whoami`,并使用干线安装输出 页面或默认缩短人行。 使用 `--verbose`, (中文(简体) ), `show`编号 :`inspect`,或 `--json` 当需要全部细节时.
-   `connectors run` 保留 JSON 风格的命令输出, 但切换非常大 人类的出击。 使用 `connectors run --verbose <connector> ...` 给全垒打.

## MCP 服务器

```bash
connectors-mcp
```

MCP工具也使用紧凑默认. `list_connectors`, (中文(简体) ), `list_jobs`, (中文(简体) ), `list_workflows`,以及 `list_agents` 返回页中的对象 `count`, (中文(简体) ), `total`, (中文(简体) ), `limit`, (中文(简体) ), `cursor`, (中文(简体) ), `nextCursor`,以及 `hasMore`; 通过 `cursor` 继续, `limit` 更改页面大小,以及 `verbose: true` 完全记录. `list_connectors` 页收取绕行可选概率输出剥取, 因此无法删除延续元数据. `connector_docs` 和作业发现 返回摘要,除非 `verbose: true` 或请求特定的细节路径.

服务连接工具通过与CLI(本地,或 服务器从 `CONNECTORS_API_URL` 编号 : `connectors login`: `connectors_service_list`, (中文(简体) ), `connectors_service_describe`, (中文(简体) ), `connections_list`, (中文(简体) ), `connections_check`, (中文(简体) ), `connectors_call` (通过) `confirm: true` 对于任何非读取)和 `runs_list`中,没有工具接受一个秘密值;与 CLI 或 API,因此生密钥从不通过代理工具参数. 何时 `connectors_call` 运行 a `credential` 操作(一个薄荷键), 其结果中的秘密值(`key`, (中文(简体) ), `token`, (中文(简体) ), `secret`, (中文(简体) ), `api_key`, (中文(简体) ), `access_token`, (中文(简体) ), `refresh_token`, (中文(简体) ), `client_secret`, (中文(简体) ), `value`,在任何深度)来 恢复为 `[redacted: pass reveal_secret=true to return it]` 除非电话 套装 `reveal_secret: true`。 。 `connectors call` 仍然打印 值,一次,有一个警告.

## HTTP 模式

```bash
connectors-mcp --http            # http://127.0.0.1:8808/mcp
MCP_HTTP=1 connectors-mcp
```

卫生: `GET http://127.0.0.1:8808/health`. MCP 也安装在 `connectors-serve` 时间 `/mcp`。 。 。 .

## 运行自己的服务器

`connectors-serve` 服务于 [`/v1` API 密码](https://npmcn.com/package/%40hasna/connectors/docs/api-v1.md) 国家行动倡议、混合国家方案 服务器和SDK在远程模式中使用.

```bash
connectors-serve                         # http://127.0.0.1:9876, SQLite in the connectors home
PORT=8080 connectors-serve
connectors-serve --host 0.0.0.0          # shared server: needs CONNECTORS_DATABASE_URL (containers, behind TLS)
```

只有回回转上的 SQLite 服务器处于本地模式( 服务器令牌, 私人) `base_url`s,当地 `/api/*` (原始内容存档于2018-10-21). routes. PostgreSQL, 或任何非循环 地址, 是公共模式: 仅租户 API 密钥, 公开 `https` `base_url`编号 只有他们的宿主,在每一个供应者的要求之前,已判决他们, 而 OAuth 仅使用 `CONNECTORS_PUBLIC_URL`。一个 SQLite 服务器拒绝 除非 `CONNECTORS_ALLOW_SQLITE_ON_PUBLIC_BIND=1`。 。 。 . 限制服务器的网络进取(拒绝元数据地址, 链接本地、 回回和私有区域: DNS 检查无法停止名称 在检查和请求之间更改答案.

| 设置 | 目的 |
| --- | --- |
| `PORT` 编号 : `CONNECTORS_PORT` | 要监听的端口( 默认) `9876`) (中文(简体) ). |
| `CONNECTORS_HOST` | 要绑定的接口( 默认) `127.0.0.1`· ; `--host` (原始内容存档于2017-03-25). overse. |
| `CONNECTORS_DATABASE_URL` | PostgreSQL DSN (英语). 取消设置: SQLite at `<connectors home>/connectors.db`常规 `DATABASE_URL` 被忽略。 TLS 跟随DSN的 `sslmode`· ; `CONNECTORS_DATABASE_CA_FILE` 针接CA捆. |
| `CONNECTORS_DATABASE_STATEMENT_TIMEOUT_MS` | 邮递SQL `statement_timeout` 集合连接( 默认) `15000`) (中文(简体) ). |
| `CONNECTORS_ENCRYPTION_KEY` | Base64, 32字节. 加密存储的证书(AES-256-GCM). 本地模式生成 `<connectors home>/encryption.key` (模式) `0600`相反。 它的指纹按密钥版本记录;一个服务器以不同的密钥开始,用于被记录版本,拒绝启动. |
| `CONNECTORS_ADMIN_KEY` | 启用管理路径( 至少24个字符) 。 未设置:他们返回404. |
| `CONNECTORS_API_KEY_SIGNING_SECRET` | 存储的API- key hashes 可选 HMAC 密钥 . |
| `CONNECTORS_ORIGIN_AUTH` 编号 : `CONNECTORS_ORIGIN_AUTH_HEADER` | 可选共享秘密( 至少 24 个字符) 前置网关必须发送的 `/v1`。 。 。 . |
| `CONNECTORS_PUBLIC_URL` | 公用基址, 用于 OAuth 重定向 URI 和相对 `redirect_after` 路径。 公共模式下 OAuth 要求 . |
| `CONNECTORS_OAUTH_REDIRECT_ORIGINS` | 逗号分隔的准确来源( 例如) `https://app.example.com`)绝对 OAuth `redirect_after` 也许可以使用. |
| `CONNECTORS_ALLOW_SQLITE_ON_PUBLIC_BIND` | `1` 让 SQLite 服务器绑定一个非浏览地址;然后在公共模式下运行. |
| `CONNECTORS_BASE_PATH` | 接受在倒置前缀下的请求, 例如 `/connectors`。 。 。 . |

迁移经过版本和验收。 在开始前应用,或让 服务器启动时应用它们 :

```bash
connectors-serve migrate
connectors-serve --migrate
```

租户和 API 密钥由服务器自己的 CLI 管理( 环境相同 ) 服务器,来自环境的秘密, 绝不来自参数 :

```bash
connectors-serve admin create-tenant acme
connectors-serve admin create-key <tenantId> --label ci     # the key is printed once
connectors-serve admin list-tenants
connectors-serve admin revoke-key <keyId>
```

或者通过管理员 API `Authorization: Bearer <CONNECTORS_ADMIN_KEY>`数字 : `POST /v1/admin/tenants`, (中文(简体) ), `POST /v1/admin/tenants/{id}/keys`, (中文(简体) ), `GET /v1/admin/tenants/{id}/keys` 财务报告和审定财务报表 `DELETE /v1/admin/keys/{id}`。给出每个 使用他们的密钥; 它们运行 `connectors login --api-url <your server>`。 。 。 .

在 Docker 中, 在 Bun 图像上安装软件包并运行 `connectors-serve`,与 PostgreSQL 和加密密钥作为环境变量传递 :

```dockerfile
FROM oven/bun:1
RUN bun install -g @hasna/connectors
ENV PORT=9876 CONNECTORS_HOST=0.0.0.0
EXPOSE 9876
CMD ["connectors-serve", "--migrate"]
```

```bash
docker run -p 9876:9876 \
  -e CONNECTORS_DATABASE_URL -e CONNECTORS_ENCRYPTION_KEY -e CONNECTORS_ADMIN_KEY \
  my-connectors-server
```

容器必须在非回放接口上收听(`CONNECTORS_HOST=0.0.0.0`(中文(简体) ) 让已公布的端口到达它。 把 TLS 放在服务器前( 反向) 由于客户拒绝普通 `http://` 除了其他任何东西 循环回放. 包裹是自己的 `Dockerfile` 从 预建 `bin/serve.js` 捆绑( e)`bun run build` (第一编).

## 本地 REST API (英语:`/api`(中文(简体) )

本地的 REST API 提供一次性产品运行时间 `http://127.0.0.1:9876` (只有默认情况下).

### 认证

每个 `/api/*` 路径和 `/mcp` 挂载需要一个无记名符号 : `Authorization: Bearer <token>` (或 `X-Connectors-Token: <token>`) (中文(简体) ). `GET /api/export` 返回每个已配置的供应商证书, 因此服务器 永远不回答,或者其他的 `/api/` - 匿名的 - 匿名的. `/health` 和 OAuth 浏览器路由(`/oauth/:name/start`, (中文(简体) ), `/oauth/:name/callback`(中文(简体) ) 是公开的.

符号按此顺序解决, 并且从未打印 :

1.  `HASNA_CONNECTORS_SERVE_TOKEN` 在环境中.
2.  只有所有者的文件 `<connectors home>/serve-token` (模式) `0600`默认值 `~/.hasna/connectors/serve-token`),第一个启动时生成.

这个 `connectors` CLI , (英语), `connectors-mcp` 编辑 `./sdk` 客户端读取相同的两个 源,所以没有配置的框认证符上的相同用户进程 当远程或其他用户进程获得时 `401 CONNECTORS_SERVE_UNAUTHORIZED`。 。 。 . 没有匿名模式。 要故意在另一个界面上听,请打电话 `startServer(port, { hostname })`。 。 。 .

### SDK (英语:`@hasna/connectors/sdk`(中文(简体) )

此包件内的 SDK 类型脚本船作为 `./sdk` 导出子路径 (每个应用程序一个软件包——没有单独的 `-sdk` 软件包; 前者 `@hasna/connectors-sdk` 被这个子路径所取代). 是HTTP客户端 仅限(`ConnectorsApiClient`, (中文(简体) ), `createHttpBackend`, (中文(简体) ), `BackendError` 编辑 ),它运行在节点和 Bun:已建成 `dist/sdk/index.js` 进口 节点仅建出, 绝不是本地引擎或 `bun:sqlite`。 。 。 .

本地模式,并按 CLI 的方式解决后端,需要 Bun 和 住在这里 `@hasna/connectors/local` (单位:千美元)`resolveBackend`, (中文(简体) ), `createLocalBackend`, (中文(简体) ), `describeMode`; 包主条目再出口. 每个条目是其 自己的捆绑,所以检查 `instanceof BackendError` 与条目的类 你打电话来`./sdk` 页:1 `ConnectorsApiClient`, (中文(简体) ), `./local` 页:1 `resolveBackend`),或比较 `err.code`。 。 。 .

```ts
import { ConnectorsApiClient, BackendError } from "@hasna/connectors/sdk";

// Any server that speaks the /v1 API (Node or Bun)
const client = new ConnectorsApiClient({
  baseUrl: "https://connectors.example.com",
  apiKey: process.env.CONNECTORS_API_KEY!,
});
const connections = await client.listConnections({ connector: "openai" });
```

```ts
// Bun only: resolve like the CLI (flags/env, then the saved config, then local mode)
import { resolveBackend, BackendError } from "@hasna/connectors/local";

const backend = await resolveBackend();
try {
  const { result, run_id } = await backend.run({
    connector: "openai",
    operation: "<operation>", // a name from (await backend.getConnector("openai")).operations
    connection: "prod-admin",
    input: {},
  });
} catch (err) {
  if (err instanceof BackendError && err.code === "CONFIRMATION_REQUIRED") {
    // not a read operation: pass confirm: true once the action is approved
  }
}
```

`LocalConnectorsClient` (及其别名) `ConnectorsClient`)),他们说话 当地 `/api` 路线,以及 `HostedConnectorsClient` 仍然为 兼容性,但被折旧为偏好 `ConnectorsApiClient` 财务报告和审定财务报表 `resolveBackend` (从) `@hasna/connectors/local`) (中文(简体) ).

## 项目布局

项目本地启用为轻量级:

```text
.connectors/
├── manifest.json
└── index.ts
```

软件包不再将完整的连接器源树复制到每个工程中.

## 数据目录

接通器数据之家由包内解析器(XDG/macOS家用布局)解决. 遗产 `~/.hasna/connectors/` 默认保存有效数据之家,直到存储实际迁移到 XDG 数据之家(`~/.local/share/hasna/connectors` 在 Linux 上,与 `connectors.db` 或操作员设置数据类型覆盖 `HASNA_DATA_HOME`。精确的应用程序覆盖 `HASNA_CONNECTORS_DIR` 无条件获胜。 现有的活店在升级时永远不会变得隐形.

## 撰稿人笔记

一还原/一产品模式的促进者指导生活在 [文档/一还原一产品. md](https://npmcn.com/package/%40hasna/connectors/docs/one-repo-one-product.md)。 。 。 .

## 许可证

Apache-2.0 - 见 [自由主义](https://npmcn.com/package/%40hasna/connectors/LICENSE)

## 常见问题

### @hasna/connectors 是什么？

开源连接器库 - 用单一命令安装 API 连接器

### 如何安装 @hasna/connectors？

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

### @hasna/connectors 支持 TypeScript 吗？

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

### @hasna/connectors 支持 ESM 还是 CommonJS？

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

### @hasna/connectors 可以商用吗？

@hasna/connectors 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @hasna/connectors 的下载量有多少？

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

### @hasna/connectors 还在维护吗？

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

