# @compforge/harness-common 中文文档

规范地址：https://npmcn.com/package/%40compforge/harness-common/

版本：0\.5\.15
npm 元数据更新时间：2026-11-06T07:45:00.435Z
中文译文更新时间：2026-11-10T13:44:12.877Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：64.2 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-09-16T13:44:11.599Z
- 最新版本发布：2026-11-06T07:45:00.252Z
- 近 30 天下载量：3091（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

执行中性客户生命周期和牵引装置数据源合同

## 安装

```sh
npm install @compforge/harness-common
```

也可以使用：`pnpm add @compforge/harness-common`、`yarn add @compforge/harness-common`、`bun add @compforge/harness-common`

## README

# 类型脚本常见的调用

执行中性服务地形、客户生命周期、环境背景和数据源合同,由用户和工具箱客户共享. 这里没有数据库驱动程序,Kubernetes适配器,博士概念或商业配置.

```typescript
import { ClientManager, type DataSource } from "@compforge/harness-common";

const clients = new ClientManager();
try {
  const client = await clients.get(source); // source implements DataSource<Client>
  // Borrow the initialized client; the root execution owns cleanup.
} finally {
  await clients.dispose();
}
```

一个客户端提供客户端Key识别完整的配置和访问政策. 平等密钥共享客户端 初始化,而不是查询结果. 使用客户端Key来进行散列配置,而不披露证书. ServiceDataSource将共享服务(或消费者扩展)与源进行关联,而无需更改其密钥. 数据源扩展客户端 提供数据访问语义; 执行无障碍混凝土环境 客户端直接提供. 两者都使用同一位经理. Context约束环境(或消费者) 扩展名),只获取客户端视图和单调截止日期Ms (Perfect.now ()). 它不需要固定装置,也不拥有处置或注销设备;将剩余的地雷投入作业. 提供者只接收客户端管理器视图和根中止符号 。 通过这些获取依赖性 因此,同时期消费者在依赖之前分享和处置. 依赖性图表必须是循环图. 失败的初始化只允许在成功清理后重试; 清理失败后会毒害该密钥, 当根管理器被处理后会再次被报告 .

使用 `clients.create({ createClient })` 一个新的客户端。 打电话者一工作就处理掉 完成; 通过 `get` 其他客户可继续使用,直到处理完毕。 词根也 处置创建的客户端作为一能的安全网. 使用 `get` - 借款人 不得处置这些共享实例。 API在名称之前都无法构建任何东西.

`FileDataSource` 宣布为非空的一组独特 `paths` 这可以一起获得. `FileClient.read` 一次获得整个组并返回一个 `FileReadResult` 每个已声明路径, 顺序: `{ path, status: "ok", bytes }` 或者说 `{ path, status: "error", error }`。空文件成功; 缺少和过大的文件会保持独立的错误,而不丢弃成功的兄弟姐妹.

呼叫者指定 `maxBytes` 每个文件, `maxTotalBytes` 所有保留字节(包括进行中) 文档 , `timeoutMs` 用于包括队列在内的整个操作,以及可选的取消. 取消、预算总额用完、集团截止日期和运输/议定书失效 整个行动。 每个读取的观测到新字节; 共取组不是一个原子 文件系统快照。 分析、配置优先和持久性属于消费者. 平台实施情况 `@compforge/harness-toolbox/file`。 。 。 .

0.5.4版本取代单一版本 `path` ;单文件消费者声明 `paths: [path]` 并消耗每个文件唯一的结果。 没有隐含的遗产适配器.

服务确定一个组件在环境中的运行时间。 属于仓库的组件 在一个福吉。 产品是一个单独的商业特性;消费者拥有其众多协会 包含组件。 仓库发现和目录所有权仍然是消费者的责任. 服务明确声明为零或更多工作负荷。 向企业提供服务 能力,不重复这些身份。 例如:

```typescript
import {
  repositoryId, conceptToMarkdown, knowledgeToMarkdown, stepToMarkdown, workflowToMarkdown,
  type Service,
} from "@compforge/harness-common";

const service: Service = {
  name: "chat",
  knowledge: {
    markdown() { return knowledgeToMarkdown(this); },
    concepts: [{ id: "conversation", name: "Conversation", description: "Contains Messages; each Message may have multiple execution Attempts.",
      markdown() { return conceptToMarkdown(this); } }],
    workflows: [{ markdown() { return workflowToMarkdown(this); }, id: "reply", title: "Reply", summary: "Accept and answer a message.", steps: [
      { id: "execute", title: "Execute", description: "Execute an attempt and persist its response.",
        markdown() { return stepToMarkdown(this); } },
    ] }],
  },
  upstream: ["gateway"],
  component: {
    name: "api",
    repository: { forge: { name: "github" }, path: "example/app", id() { return repositoryId(this); } },
  },
  environment: { name: "test" },
  workloads: [{
    name: "web", platform: "kubernetes",
    location: { kind: "resource", resource_kind: "Deployment", name: "api-server" },
  }],
};
```

仓库扩展身份 : `id()` 返回时 `forge.name/path`,不包括 `forkedFrom`。 。 。 . 使用 `repositoryId(this)` 执行方法时,包括恢复仓库时 从JSON; 方法不序列化.

服务和产品接受简短介绍的可选说明,结构化 `knowledge` 用于概念、工作流程、文章和词典。 服务知识涵盖其自身 责任,而产品知识则涵盖端到端的流动。 消费者维持这个下线 元数据; 它不会改变身份, 执行工作流程或证明运行时状态 .

服务 `upstream` 列出在消费者的 目录. 排除意味着这种关系未申报; `[]` 宣布没有上游呼叫者. 此描述架构;运行时的痕迹确定哪些呼叫实际发生.

环境带有身份和可选的本地/SSH主机声明,而不是连接. 主机环境 描述直接运行在该主机上的目标。 具体的无障碍环境,例如工具箱 Kubernetes Environment, 额外执行客户端服务. 仅主机声明不添加 SSH 支持客户端。 服务与环境Context保留了混凝土环境的接通类型.

Workload描述了逻辑运行时载体及其资源,Kubernetes Service或标签位置. Workload Instance记录了一个被观察到的有环境和UID特性的Pod化身. 这些合同没有进行发现或I/O;呼叫者在其选定的环境中解决申报问题. 集装箱选择会影响访问路线,而不是Pod身份. 见 [共享模式](https://npmcn.com/docs/workload.md)。 。 。 .

Python的相应包是 sdks/python/common (harness-common). 语言保持平庸的API 和独立版本的软件包;它们不需要执行锁定步骤中的每个模型.

开发:包子安装,做花花,做测试. 公布的文物为节点相容的无害环境管理和申报.

## 结构化知识

产品和服务接受可选 `knowledge` 声明. `Knowledge` 组 `Concept`, (中文(简体) ), `Workflow` (带有父范围) `Step` 记录), `Article` (与 `Section` )和打入 `Dictionary<Entry>` 藏书. 所有8个内容界面扩展 `Markdown`,其 `markdown(): string` 方法返回 I/O 无表达式. 声明仍然是普通对象;方法可以委托给下面的共享转换器. `KnowledgeSource` 说明出处,不包含这一提供合同.

JSON保留了内容字段,但不是方法. 消费者自己的来源验证, 方法恢复、分发和版本选择。 解析 JSON 或断言一个类型 不创建可调用的知识对象; 在每个内容对象上恢复方法 通过这些界面曝光.

身份证在所有人内部是独一无二的,在父母内部是每个儿童收集的. 步骤 `parentId` 表示包含; 即使父程序也跟着数组 出现在孩子之后. `validateKnowledge` 拒绝重复/空身份证, 父母身份不明 以及参考文献曝光前的父周期。 词典条目 ID 是独一无二的, 而 名称和域名如出错代码可能重复. `source.version` 描述 发布的定义独立于包含发行版本.

`knowledge.ts` 并提供确定性、I/O无标记预测: `knowledgeToMarkdown`, (中文(简体) ), `conceptToMarkdown`, (中文(简体) ), `workflowToMarkdown`, (中文(简体) ), `stepToMarkdown`, (中文(简体) ), `articleToMarkdown`, (中文(简体) ), `sectionToMarkdown`, (中文(简体) ), `dictionaryToMarkdown` 财务报告和审定财务报表 `entryToMarkdown`。 。 。 . 词典条目保留其输入的域; 执行 `Entry.markdown()` 改为 包括这些领域。 共享 `entryToMarkdown` 使用名称、描述和别名. 生成标题并命令步骤使用紧凑相距; 作者段落和代码 块保留其内容。 终端演示文稿、 精确的查询、 搜索、 源装入 而矢量指数属于消费者.

## 升级到0.4

移动已删除的产品/服务 `concepts` 财务报告和审定财务报表 `workflows` 字符串字段为 `knowledge.concepts` 财务报告和审定财务报表 `knowledge.workflows`对域对象使用概念记录 和业务流程的工作流程/步骤记录。 知识仍然是可选的.

## 升级到0.5

执行 `markdown()` 概念、工作流程、步骤、, 第一节 词典与条目. 例如:

```typescript
import { conceptToMarkdown, type Concept } from "@compforge/harness-common";

const concept: Concept = {
  id: "carrier",
  name: "Carrier",
  description: "Infrastructure capacity.",
  markdown() { return conceptToMarkdown(this); },
};

console.log(concept.markdown());
```

现有 `...ToMarkdown` 职能作为共享执行保留。 每个 父母给孩子打电话 `markdown()` 知识群体的概念、工作流程、, 文章和词典; 文章制作部分; 词典制作条目; 工作流程 数字和缩进 `parentId`父母保留子女产出 从孩子的地里重建它。 帮手从不叫接收器自己的方法, 这样 `markdown() { return knowledgeToMarkdown(this); }` 不再发生.

默认标题跟随构成树: 知识类别使用一级; 概念, 工作流程,文章和词典使用二级;分节和条目使用三级. 步骤返回粗体标题和正文,由Workflow提供编号。 独立输出 使用相同的格式。 自定义方法拥有其标题选择; 父母不重写 子输出中的标题或代码块 .

移动 `KnowledgeMarkdownOptions.renderEntry` 或者说 `dictionaryToMarkdown` 渲染器召回 每个条目 `markdown()` 方法。 这些回调参数用0.5去除;a 自定义条目在单独显示或通过其词典和知识显示时,目前是一致的.

## 资源库存

`Resource` 宣布运行中的服务处持有的收藏; `ServiceResource` 记录管理/使用 关系不重复身份. `ResourceSnapshot` 保留已键入实例, 单位为 测量、独立已知总数和完整/部分/无覆盖。 发现和 作案仍为消费者所有。 见 [共享合同](https://npmcn.com/docs/resource.md)。 。 。 .

## 拉请求

`PullRequest` 根据其目标确定PR/MR `Repository` 和仓库本地编号. 国家、分支、源寄存器、修订和提供者时间戳是可选事实. 见 [共享合同](https://npmcn.com/docs/pull-request.md) 身份和未知状态的语义. 交通和投票仍然是消费者/工具箱的责任.

## 便携式价值

`Value`, (中文(简体) ), `ValueCodec`, (中文(简体) ), `Summary`,JSON正常化是生产者拥有的数据合同. 使用 `serializeValue` 保存不可改变的 JSON 和读取提示 `deserializeValue` 带有一个明确的匹配代码以恢复运行时的行为。 通相与解相相为净相. 医生及其插件直接从下列来源进口这些合同: `@compforge/harness-common`· ; 观察身份、证据和渲染仍由消费者掌握.

## 组件工具和投放点

可选择声明组件 `tools` 和一个逻辑 `depot`。 。 。 . `Tool` 描述一个动态 工具和可选的已声明版本/约束. `Depot.bins` 组 `Bin` 声明 存储器相对路径和 `dependencies`, (中文(简体) ), `output` 或者说 `cache` 类型。 元数据不变 组件身份,证明物理存在或授权删除. 发现,准备, 使用保护和开垦属于消费者。 见 [共享合同](https://npmcn.com/docs/component-depot.md)。 。 。 .

## 终点

`Endpoint` 描述网络访问地址:可选小写 `scheme`, (中文(简体) ), `host`,明确 `port`选择 `secure`它独立于后面的服务、数据来源或资源 那个地址 IPv6主机被解压. 证书、路径、查询参数、执行 适配器和超时器不属于本合同.

可选 `id` 财务报告和审定财务报表 `description` 查明并描述消费者的依赖性. 可选 `workload` 携带完整的消费者 `Workload` 地址所属声明 包括平台、位置、命名空间和容器。 消费者决心 实例直接来自此声明,而不在服务目录中查找名称。 声明 没有发现实例或允许访问。 协议探测可以单独消耗地址域.

`secure: true` 需要加密传输; 协议决定是否直接使用 TLS或特定协议的谈判. 不透露不要求加密 HTTPS/WSS/TLS 结束点需要 `secure: true`本宣言不主张连通性、信任政策 批准或授权。 工具箱拥有URL投影,验证和网络探测.

## 常见问题

### @compforge/harness-common 是什么？

执行中性客户生命周期和牵引装置数据源合同

### 如何安装 @compforge/harness-common？

在项目目录运行 npm install @compforge/harness-common，或使用 pnpm add / yarn add / bun add。

### @compforge/harness-common 支持 TypeScript 吗？

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

### @compforge/harness-common 支持 ESM 还是 CommonJS？

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

### @compforge/harness-common 需要什么版本的 Node\.js？

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

### @compforge/harness-common 可以商用吗？

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

### @compforge/harness-common 的下载量有多少？

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

### @compforge/harness-common 还在维护吗？

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