# @fourier-labs/harbour-contracts 中文文档

规范地址：https://npmcn.com/package/%40fourier-labs/harbour-contracts/

版本：0\.106\.3
npm 元数据更新时间：2026-11-12T16:44:57.568Z
中文译文更新时间：2026-11-15T10:22:26.357Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40fourier-labs/harbour-contracts
原文对照：https://npmcn.com/package/%40fourier-labs/harbour-contracts/?lang=original
项目主页：https://github.com/Fourier-Labs-AI/harbour-contracts#readme
源码仓库：https://github.com/Fourier-Labs-AI/harbour-contracts

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

- 包体积（解压后）：1.7 MB，323 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-03T21:13:27.552Z
- 最新版本发布：2026-11-12T16:44:57.343Z
- 近 30 天下载量：9073（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：85（近 12 个月 85 个）

## 中文简介

每个跨越Isomorph元件之间边界的数据形状的单一真理源.

## 安装

```sh
npm install @fourier-labs/harbour-contracts
```

也可以使用：`pnpm add @fourier-labs/harbour-contracts`、`yarn add @fourier-labs/harbour-contracts`、`bun add @fourier-labs/harbour-contracts`

## README

# 港口合同

每个跨越Isomorph边界的数据形状的单一真理源 组件. **司马先:** 手写 JSON Schema 在 `schema/` 是来源; 跳 软件包( r)`gen-go/`)和类型脚本包(`gen-ts/` → `@fourier-labs/harbour-contracts`已经 **生成** 和执着。 没有处理器, 后置堆栈, 或 MCP 操作程序是针对一个形状构建的 这里首先存在.

## 版式

| 路径 | 什麽 |
| --- | --- |
| `schema/*.json` | JSON Schema (草案-07). 你唯一手写的档案. |
| `gen-go/` | 已生成 去包装 `contracts` (进口) `github.com/Fourier-Labs-AI/harbour-contracts/gen-go`) (中文(简体) ). |
| `gen-ts/` | 生成 TS 源; 发布于 `@fourier-labs/harbour-contracts`。 。 。 . |
| `contract-release.json` | 生成出放出/版本外加聚合和每个文件的schema,AI-fixture,Go-source和TypeScript-source摘要,用于严格的消费针. |
| `tools/gen/gen.mjs` | 单一代码驱动程序(节点). 验证每个计划,然后发出Go + TS. |
| `docs/adr/` | 会议记录(例如:. `0001-t1-ratified.md`) (中文(简体) ). |

## 计划

| 文件 | 形状 | 长期 |
| --- | --- | --- |
| `deploy-request.schema.json` | MCP 磁共振 `deploy(app, {commit, branch})` 有效载荷; 新预览部署默认为 `branch_select` 除非 `sequential` 明确 | 第7节 |
| `error-envelope.schema.json` | 每个 FAILED 转换时发射的失败信封 | 第2.1节 |
| `error-category.enum.json` | 闭合故障类别 enum + 每个类别 `retryable` 登记 | 第2.2节 |
| `artifact-contract.schema.json` | 建立产出合同(供应商-可移动性接合),包括以摘要为主、定义明确的应用程序明确参考 | 第3节 |
| `well-defined-app-manifest.schema.json` | 用于静态、全存储和浏览器第一应用程序的版本运行时线:工作量、时间表、队列、服务绑定、语言运行时、浏览器能力和路由认证 | 定义良好的应用程序 P0 |
| `version-state.schema.json` | 状态机器 T1a — 状态,法律过渡,版本Id格式 | 第1节 |
| `env-bindings.schema.json` | `EnvBindings` 编号 : `Target` 编号 : `Binding` (BYOC完成) (英语) | 第4.2.2节 |
| `kvs-routing-entry.schema.json` | CloudFront KVS 路由值 (% 1)`{static, api}`(中文(简体) ) | 第8条 |
| `ai-composite-policy-digest.schema.json` | 订购复合政策摘要标识并生成GO/TS助手 | AI 治理 § 5.1 |
| `ai-classification-stamp.schema.json` | 不可更改的确切版本分类证据 | AI治理 §5.2 |
| `ai-deployment-gate-decision.schema.json` | 仅附加明确的部署门决定 | AI治理 §5.2 |
| `ai-governance-decision.schema.json` | AI治理决定,包括审查的OpenAI兼容客户端配置边界的无值描述符 | AI 治理 §5 |
| `ai-gateway-key-lifecycle-event.schema.json` | 无价值版本的关键生命周期证据 | AI 治理 §7 |
| `ai-runtime-binding.schema.json` | 平台中性工作量标识/保密约束 | AI治理第5.8节 |
| `binding-classification-subject.schema.json` | 版本分配前的完整无值绑定名称分类 | AI 治理 § 5.7 / SEC-UP-01 |
| `sanitized-binding-evidence.schema.json` | 准确的版本 sanitized 运行时间约束分配收据 | AI治理 第5.7节/SEC-UP-02 |
| `ai-pricing-revision`, (中文(简体) ), `ai-metering-policy`, (中文(简体) ), `ai-budget-ledger-event`, (中文(简体) ), `ai-trace-event-v2` | 附加计量 v2 记录,包括媒体维度和 P5 痕量归属; v1 记录仍可读取 | AI 治理 §9 |
| `app-integrations-declaration.schema.json` | 承诺 `.isomorph/integrations.json` (单位:千美元)`isomorph.app-integrations/2.0`: 已关闭的八十一操作集(黑读/后/更新/删除/DM/ Lookup,Gmail list/thread/read/send/attachment-ADR 0018; Basecamp 项目/待办列表/待办列表/待办/消息/评论/人名单,待办、消息、评论和营火帖-ADR 0022;Sharepoint list/ite/drive/file list,文件搜索和读取,项目创建和更新,文件上传-ADR 0024;电话短消息列表-ADR 0028;电话号码读取-ADR 0029;Google日历、驱动器、Docs和工作表及展望、OneDRrive、Excel和Teams读取和写作签名人-ADR 0032;仓库视图读取和表格附载取\`访问 ' 读取 | 附录 `— ADR 0028; service request) with fixed or declared identity modes (`gmail.message.send ' 于0.102.0 — ADR 0045宣布;4个Gmail自0.106.0 — ADR 0049读取;拥有共享操作/身份/环境enums |
| `integration-execute-request`, (中文(简体) ), `integration-execute-result`, (中文(简体) ), `integration-connect-result`, (中文(简体) ), `integration-error-details` | App SDK集成电线合同 `/_harbour/integrations/*`: 操作输入范围(仓库读取过滤器、组、总量和仓库中的种类,并说何时) `truncated` – ADR 0017; Slack 和 Gmail 读取页面, 邮递线程, 邮件携带 HTML 和附件 – ADR 0018; 读取的开发仓库可能携带应用程序 `sampleRows` 结果是 `sample` ——ADR 0021; Basecamp 列表页面 `pageToken`,ids是数字字符串,写答 `{id, appUrl}` — ADR 0022; SharePoint 列表页图 `$skiptoken`身份证是图式身份证, `fields` 是一个有界限的记录, 写答 `{id, webUrl}` - ADR 0024;仓库附件需要 `rows`,并使用一个电话短信列表 `since`编号 :`from` ——ADR 0028;一个电话号码读取不需输入 ——ADR 0029;日历事件取用RFC 3339 `start`编号 :`end`,工作表和Excel带 `values`,一个带边框的单元格矩阵, Docs take `replacements`,且该事件读取,文档读取,值和工作表结果有各自的形状——ADR 0032,操作结果形状,同意状态和关闭状态 `details.code` 设置理由 | 发展工具包§4,§8 |
| `saas-connection.schema.json`, (中文(简体) ), `data-grant-v2.schema.json` | 租户SaaS的连接记录(每个租户和供应商安装一个频道图;信息技术可选 `oauthClient`, (中文(简体) ), `userModeApproval`, (中文(简体) ), `directMessages`, (中文(简体) ), `externalRecipients` ——ADR 0018; Basecamp 连接被固定 `account` 和项目编号 `channels` ——ADR 0022;一个SharePoint连接的被钉住的微软365租户在 `account` 和站点编号 `channels` ——ADR 0024;最多20个 `approvers` - 除了租户管理者之外,他们可以批准访问请求——ADR 0026 `channels` - ADR 0028,一个应用程序用别名读取——ADR 0029;8个Google Workspace和Microsoft 365的供应商,只有用户同意,一个Teams连接的固定租户和 `<teamId>/<channelId>` 频道映射 — ADR 0032; 可选 `startedBy` 当一个构建者的第一个请求创建连接时 —— ADR 0034; 一个 Gmail 连接的 `installation` 是公司邮箱IT连接, `botName` 其地址——ADR 0045和添加剂 `harbour.data-grant/2.0` 具有结构化资源和提供租赁/清理的赠款记录(生成状况机器;遗产) `data-grant` 未触及) | 第5节 |
| `kit-bundle-manifest.schema.json`, (中文(简体) ), `kit-lock.schema.json` | 已发布套装捆绑身份( SDK tarball 文摘加可选) `sdk.version` 链接 `sdk.url` 下载位置)和承诺 `.isomorph/kit.lock.json` 密码 建造 SDK 复仇门比较 | 发展工具箱§3 |
| `deploy-response.schema.json` | 接受机构 `POST /v1/tenants/{tenant}/apps/{app}/deployments`,仅在权威的 QUEUED 版本存在并接受其 SQS 消息后返回 | —— 说 |
| `deployment-source.schema.json` | 证书无源 `DeployRequest` 机构 : `provider` 实值 `github` 或者说 `gitlab`, (中文(简体) ), `repositoryUrl` 并且部署控制平面对照租户的源链接(ADR 0023)检查宿主; 证书通过 Matterize Source 内部解决 | —— 说 |
| `deployment-environment.schema.json` | 预览 API 所接受的公共环境(`preview` 只能通过促销来实现生产) | —— 说 |
| `api-error-response.schema.json` | 部署/状态Lambda的安全JSON错误机构 4xx/5xxx答复;不同于内部 `ErrorEnvelope` | —— 说 |
| `deployment-status-request.schema.json` | 经验证的路径参数 `GET /v1/tenants/{tenant}/apps/{app}/deployments/{versionId}` | —— 说 |
| `deployment-status-response.schema.json` | 200 OK body for GET status: 准确的不可改变版本,带有 `progress` 线索, `deployTarget` 财务报告和审定财务报表 `diagnosticRef` | —— 说 |
| `deployment-status-failure.schema.json` | 前端安全故障投影嵌入了失败状态响应; 带摘要 `diagnosticRef` 找到经编辑的诊断 | —— 说 |
| `promotion-request.schema.json` | 机构 `POST /v1/tenants/{tenant}/apps/{app}/promotions`;寄存器身份来自存储的记录,而非调用者 | ADR 0003 数据 |
| `promotion-response.schema.json` | 202 接受体在生产版本及其耐用性约束存在后返回 | ADR 0003 数据 |
| `transform-report.schema.json` | 结构化输出 一种剂必须从一次变换尝试返回; 交给该剂作为输出计划并被控制平面重新验证 | —— 说 |
| `transform-parked-result.schema.json` | 在需要建构器输入时, 在一个持久的检查站后进行连续审查的结果; 没有成功的报告 | —— 说 |
| `builder-input-proposal.schema.json` | 在没有构建者自主输入的情况下,连续预览无法继续进行时发布的无价值建议 | —— 说 |
| `deployment-continuation.schema.json` | 允许从已停放的输入请求中部署一个儿童的不可改变的参考文献;从未使用证书值 | —— 说 |
| `security-scan-input-v2.schema.json` | 向安全保证机器提供投入`harbour.security-scan-input/2.0`,替换v1):一个包在源输入处验证,扫描在租户的执行账户中 | ADR 0014 (英语) |
| `security-verdict.schema.json` | 安全保证决定; `BLOCKED` 表面为不可重试 `gate.security-scan` 类别 | ADR 0014 (英语) |
| `data-source.schema.json` | 行政登记的外部数据来源; `credentialRef` 是一个隐秘的 URI , 证书从未越过此边界; 可选 `development`编号 :`preview` 副本 `environments`,生产是顶级终点;连接器包括 `trino` (ADR 0021)和 (中文(简体) ) `clickhouse` (ADR 0030) (中文(简体) ) | 数据存取 MVP |
| `data-dependency.schema.json` | 与租户数据源清单相比,一个已申报或发现的应用程序的外部数据依赖性 | 数据存取 MVP |
| `secret-reference.schema.json` | 命名一个应用程序所依赖的秘密槽; 只有引用及其生命周期交叉, 绝不是值 | 秘密经理MVP |
| `ai-callsite-inventory.schema.json` | 一个精确的部署版本(仅检测)的不可移动,已消毒的AI呼叫站点发现 | AI 治理 |
| `ai-runtime-contract.schema.json` | 由AI治理计划决定产生的不可移动运行时间合同;范围化配置外加保密管理者参考 | AI 治理 |
| `ai-policy-snapshot.schema.json` | AI Gateway所摄取的、内容不易改变的AI政策快照 | AI 治理 |
| `ai-gateway-key-lookup.schema.json` | 一个版本范围Isomorph 密钥的无值网关认证元数据 | AI 治理 |
| `ai-trace-event.schema.json` | 无值 AI Gateway 追踪元数据( v1); 原始提示和回复从不入队列 | AI 治理 |
| `ai-transform-event.schema.json` | 载有计划拦截计划的AI拦截任务输入 | AI 治理 |
| `ai-transform-result.schema.json` | 确定性拦截结果:仅说明和摘要证据 | AI 治理 |
| `ai-verification-evidence.schema.json` | 通过部署核查提交一个规范版本的无价值的有根据证据 | AI 治理 |

运行时资源简介是由转换、文物和 定义明确的应用程序显示。 支持的配置文件是 `standard`, (中文(简体) ), `memory-1g`,以及 `memory-2g`;消费者必须拒绝未经确认的原始CPU或内存覆盖.

两种计划携带逻辑 超越结构类型,生成到帮助者:

-   **`error-category.enum.json`** → `IsRetryable(category)` (前进) / `isRetryable(category)` (TS), 处理具体类别和家庭前缀`storage.unsupported-engine.<engine>`) (中文(简体) ). 未知类别已关闭( 不可重试) .
-   **`version-state.schema.json`** → `CanTransition(environment, from, to)` 编号 : `IsTerminal(state)` (开始)和 `canTransition` 编号 : `isTerminal` (TS),由 `x-transitions` 边缘列表——如此控制平面 任何消费者都同意一个来源的合法性.
-   **`binding-classification-subject.schema.json`** 财务报告和审定财务报表 **`sanitized-binding-evidence.schema.json`** · 犬形长度前缀SHA-256 预想/潜水员加上确切姓名, 在 Go 和 TypeScript 中请求映射和分配接收验证器.
-   **`integration-execute-request.schema.json`** → `IntegrationExecuteInputRules` + 键 `validateIntegrationExecuteInput(operation, input)` (TS)/ (中文(简体) ) `ValidateIntegrationExecuteInput` (走开), 从每个操作的 `then`\- 块(`propertyNames.enum`, (中文(简体) ), `required`每个外地 `maximum`编号 :`default`) (中文(简体) ). 治理者执行路径, 应用 SDK 和工具包的本地检查 拒绝同样判决的请求(`limit must be an integer between 1 and 15`; 计 数 SDK出售TypeScript文件,因为它没有依赖性.

## 工作流程

```sh
make gen       # regenerate gen-go/ + gen-ts/ from schema/ (Node only — no Go needed)
make verify    # regenerate, then fail if git shows a diff  ← the staleness gate (CI runs this)
make build     # compile-check the generated Go + TS (needs go + local tsc)
make test      # generator determinism + contract-logic tests (Node; Go when installed)
```

代码是 **只节点** 这样 `make gen` 可在任何地方复制 `tsc` 为: 仅用于 _编译检查_ 产出(`make build`),而不是生成.

### 更改形状

1.  编辑方案 `schema/`。类别 enum 和 状态机器是 **关闭** - 延长 他们 **只有通过 PR 到此 repo** (PR是通知消费者的地方).
2.  `make gen` 承诺 `gen-go/` + 键 `gen-ts/` 除了改变计划.
3.  CI (中文(简体) )`make verify`失败 .
4.  不编辑 `VERSION`, (中文(简体) ), `package.json`其版本或 `CHANGELOG.md`: 发布版本来自 页:1 `vX.Y.Z` 合并后按下标签( t)[ADR 0050 (英语)](https://npmcn.com/package/%40fourier-labs/harbour-contracts/docs/adr/0050-release-version-from-the-tag.md)) (中文(简体) ).
5.  形状变化是 `(contracts)` 变化:通过 `/review` + 键 `/code-review ultra` → `/ship`。 。 。 .

消费者应该将出版的三部分版本和出版的三部分放在上面 `schemasDigest`编号 :`aiFixturesDigest` 内 `contract-release.json`他们的线人应该 (一) 对照所生成的型号或计划,验证罐头装置; 在合同没有签出时,它不能默默不作. Npm文物中包含 `schema/`, (中文(简体) ), `fixtures/ai/`, (中文(简体) ), `gen-ts/` 和释放 显示,所以每个由显示器命名的字节都可从 同样的释放。 通过标记的 Go 模块源源仍然可用 .

`generatedGo` 财务报告和审定财务报表 `generatedTypeScript` 封存每个 `.go`编号 :`.ts` 文档中 软件包目录. `gen-go/contract_release.go` 财务报告和审定财务报表 `gen-ts/contract-release.ts` 是唯一的排除: 那些生成的文件 嵌入集合消化器本身,所以将它们包括进去将产生一个 自我参考,没有有限的摘要。 列出的排除和 (a) 测试拒绝任何不同的排斥设置和独立 重新计算每个包含的文件和集合 .

平台中性的工作量和秘密参考资料是标识,而不是一般的 URLs (英语). 他们用 `scheme://authority/path` 经审查的添加剂计划 登记(`aws-sm`, (中文(简体) ), `iam-role`, (中文(简体) ), `k8s-sa`, (中文(简体) ), `secretref`, (中文(简体) ), `spiffe`, (中文(简体) ), `vault`, (中文(简体) ), `vault-v2`) (中文(简体) ). 一个新的平台在合同发布中扩展了登记处. 用户信息、 端口、 % 编码、 查询字符串、 碎片和空路径 区段故意无法代表,防止引用字段 成为证明或任意价值的运输.

V2 度量计方案是与现有 v1 政策/跟踪挂钩的预测 身份证明 在迁移期间,消费者可双读v1和v2,并可双写 都一样 旧记录从不重写;更正仅为附加调整 或取代记录。 删除 v1 写作需要单独记录 消费者削减证据.

## 消费

-   **开始:** `go get github.com/Fourier-Labs-AI/harbour-contracts/gen-go@v0.50.0`
    
    二事使此相通,而后一相相出,非所显也.
    
    **发布标记必须是3个部分的分集.** 运行和npm 需要 `MAJOR.MINOR.PATCH`,而此寄存器记录 `MAJOR.MINOR.PATCH.MICRO`因此,可公布的发布要求多边空间研究组织: 成为零, 并按确定性绘制地图:仓库 `0.9.0.0` − 包装 `0.9.0` → 发布标签 `v0.9.0`。可选的四部分记账标签 `v0.9.0.0` 可能 在同一承诺中指明,但不公布。 CI验证这张地图, 更改日志标题和标签格式.
    
    **Repo是私人的,Go从全球缓存取来.** 设定此值一次 机器 :
    
    ```sh
    go env -w GOPRIVATE=github.com/Fourier-Labs-AI/*
    git config --global credential."https://github.com/Fourier-Labs-AI".helper '!gh auth git-credential'
    git config --global credential."https://github.com/Fourier-Labs-AI".useHttpPath true
    ```
    
    证书的配置必须是 **全局和URL范围d**,该组合是 非附带事项 :
    
    -   无法覆盖文件夹( I)`includeIf gitdir:…`) (中文(简体) ). 运行 `git ls-remote` 内部 `~/go/pkg/mod/cache/vcs/…`所以每个指南的助手从不 适用。 完全失败 `/tmp` 并且从伊索莫特的复出 让它看起来像一个糟糕的标签 而不是一个认证问题.
    -   使用 URL 前缀进行范围界定使其远离您其他的 GitHub 账户:仅 `github.com/Fourier-Labs-AI/*` 使用此证书.
    -   一个SSH `insteadOf` 重写是通常的建议,而且 **这里不对** 除非你们 SSH 密钥属于一个有 Fourier org 访问权限的账户. 检查 `ssh -T git@github.com` 在到达它之前.
    
    没有以上, `go get` 失败 `Repository not found` ——读作: 缺少标签, 而不是缺少访问权限 .
    
-   **{\\FN华文楷体\\FS16\\1CHE0E0E0}TS:** `npm i @fourier-labs/harbour-contracts` ——由CI从标签上发表. 手写AI政策解决器(`resolver/index.ts`(b) 与该船同装的船舶 `@fourier-labs/harbour-contracts/resolver` 子路径导出( n)`package.json` `exports`) (中文(简体) ).
    

## 页:1

`gen.mjs` 从节点生产两种语言。 走开 **构建字段对齐** 实值 (gofmt为通过 `make fmt`) ;这从未 影响编译,而 staleness gate 比较了原始生成器输出,所以保持绿色.

## 常见问题

### @fourier-labs/harbour-contracts 是什么？

每个跨越Isomorph元件之间边界的数据形状的单一真理源\.

### 如何安装 @fourier-labs/harbour-contracts？

在项目目录运行 npm install @fourier-labs/harbour-contracts，或使用 pnpm add / yarn add / bun add。

### @fourier-labs/harbour-contracts 支持 TypeScript 吗？

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

### @fourier-labs/harbour-contracts 支持 ESM 还是 CommonJS？

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

### @fourier-labs/harbour-contracts 可以商用吗？

@fourier-labs/harbour-contracts 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @fourier-labs/harbour-contracts 的下载量有多少？

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

### @fourier-labs/harbour-contracts 还在维护吗？

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