# @cyberuni/agent-harness 中文文档

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

版本：0\.7\.1
npm 元数据更新时间：2026-11-04T15:16:24.920Z
中文译文更新时间：2026-11-11T07:14:22.681Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cyberuni/agent-harness
原文对照：https://npmcn.com/package/%40cyberuni/agent-harness/?lang=original
源码仓库：https://github.com/cyberuni/agent-harness

弃用说明：Renamed to cyber-agentkit

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

- 包体积（解压后）：1.1 MB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：clibuilder ^12\.0\.0
- 首次发布：2026-09-26T22:39:34.872Z
- 最新版本发布：2026-10-17T19:08:33.435Z
- 近 30 天下载量：2906（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

与 AI 代理 协作的工具包 : 检测哪个正在运行,查询其管理下的政策位置,插件存储,启用插件,以及技能命名,并解决分层的参考文件.

## 安装

```sh
npm install @cyberuni/agent-harness
```

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

## README

# @ cyberuni/ 代理服务器

[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cyberuni/agent-harness/blob/main/LICENSE)

与人工智能特工合作的工具包 检测哪个正在运行 克劳德代码,克塞尔, Codex, GitHub 副驾驶 CLI, OpenCode, Kilo 代码,双子座 CLI, Quen 代码, VS 代码中的 GitHub 副驾驶, Cline, Crush, OpenHands, 或 Auggie CLI —— 询问它持有什么(它管理的政策位置, 插件存储、 启用插件、 如何命名插件技能以及如何运行无头设备),以及 解决代理按要求读取的参考文件.

它依赖于没有其它的代理工具,所以其中任何一种工具都可以建立在它上.

**状态:释放前.** 每一个事实,这个库 编码基于 [`.research/harness-detection`](https://github.com/cyberuni/agent-harness/tree/main/.research/harness-detection)。 。 。 .

## 探测绳子

```ts
import { detectHarness } from '@cyberuni/agent-harness'

const result = detectHarness()
// {
//   harness: 'claude-code',
//   candidates: ['claude-code'],
//   evidence: [
//     { harness: 'claude-code', signal: 'CLAUDECODE', research: 'E-CC-D1', description: '…' },
//     { harness: 'claude-code', signal: 'CLAUDE_CODE_CHILD_SESSION', research: 'E-CC-D3', description: '…' },
//   ],
// }
```

检测会读取环境变量,每个控制器都设定在其产生的过程上:

| 节奏 | 从 |
| --- | --- |
| 克劳德代码 | `CLAUDECODE=1` 与 `CLAUDE_CODE_CHILD_SESSION=1` 或者说 `CLAUDE_CODE_SESSION_ID` |
| 光标 | `CURSOR_AGENT=1`,或 `CURSOR_VERSION` 与 `CURSOR_PROJECT_DIR` 钩子 |
| 代码 | `CODEX_THREAD_ID` |
| GitHub 副驾驶 CLI | `COPILOT_CLI=1`, (中文(简体) ), `COPILOT_AGENT_SESSION_ID`,或 `COPILOT_PLUGIN_ROOT` 钩子 |
| 打开代码 | `OPENCODE=1` 与 `OPENCODE_PID` |
| Kilo 代码 | `KILO=1` 与 `KILO_PID` |
| 双子座CLI | `GEMINI_CLI=1` |
| Quen 代码 | `QWEN_CODE=1` |
| VS 代码中的 GitHub 副驾驶 | `COPILOT_AGENT=1` |
| 线 | `CLINE_ACTIVE=true`,仅由 VS 代码扩展设置 |
| 碾碎 | `CRUSH=1` |
| 打开手 | `AI_AGENT=openhands`,或 `OPENHANDS_EVENT_TYPE` 与 `OPENHANDS_PROJECT_DIR` 钩子 |
| 奥吉CLI | `AUGMENT_HOOK_EVENT` 与 `AUGMENT_PROJECT_DIR`只有钩子 |

报告 `unknown` 而不是猜测 :

-   当没有带匹配,包括 `CLAUDECODE=1` a. 本身,IDE扩展也设置;
-   当一个以上的绳子匹配, 就像一个绳子运行在另一个的外壳。 比赛 列于 `candidates`· ;
-   页:1 `AGENT` 财务报告和审定财务报表 `AI_AGENT`,几个供应商设定的(只有确切价值) `AI_AGENT=openhands` (计数)和 `OPENCODE=1` 单是Kilo代码,即OpenCode分叉,也可以设置;
-   在吊带没有设置任何自身背景的背景:Codex、双子座CLI和Quen码钩,Quen 代码, Crush, OpenHands, 和 Auggie MCP 服务器, Auggie shell 命令, OpenHands CLI 1.1.6. 0 shell 命令( 其 SDK 先前日期) `AI_AGENT=openhands`)和线CLI;
-   没有经过证实的信号的绳索,如:鹅、抗重力、罗沃德夫、基罗、安普、工厂 机器人 德文桌面 和曲速 研究记录了为什么每一个.

过 `{ env }` 检查除 `process.env`。 。 。 .

## 管理政策

```ts
import { managedPolicyLocations } from '@cyberuni/agent-harness'

managedPolicyLocations('claude-code', { platform: 'linux' })
// [
//   { kind: 'server', location: 'claude.ai admin console or a self-hosted Claude apps gateway', … },
//   { kind: 'file', location: '/etc/claude-code/managed-settings.json', … },
//   { kind: 'directory', location: '/etc/claude-code/managed-settings.d', … },
//   { kind: 'file', location: '/etc/claude-code/managed-mcp.json', … },
// ]
```

`kind` 实值 `file` 或者说 `directory` 因为一个召唤者能从磁盘上读取什么, `macos-managed-preferences` 或者说 `windows-registry` 用于交付MDM,以及 `server` 供应商持有的保单 组织。 A 类 `server` 条目意味着本地文件不是整个政策.

## 插件存储

```ts
import { pluginStorage } from '@cyberuni/agent-harness'

pluginStorage('codex')
// {
//   harness: 'codex',
//   configDir: '/home/me/.codex',
//   locations: [
//     { kind: 'plugin-cache', path: '/home/me/.codex/plugins/cache', … },
//     { kind: 'enabled-record', path: '/home/me/.codex/config.toml', … },
//   ],
// }
```

路径是计算而不是检查的,所以在安装第一个插件之前,一个位置可能不存在. 光标没有 `enabled-record`: 没有启用其插件的文件记录 .

## 已启用的插件

```ts
import { enabledPlugins } from '@cyberuni/agent-harness'

const result = await enabledPlugins('claude-code')
// {
//   harness: 'claude-code',
//   supported: true,
//   plugins: [{ id: 'my-plugin@my-marketplace', enabled: true, scope: 'project', source: '/repo/.claude/settings.json' }],
//   sources: [{ scope: 'managed', path: '/etc/claude-code/managed-settings.json', found: false }, …],
//   unread: ['server-managed settings (claude.ai admin console or a self-hosted Claude apps gateway)', …],
//   research: ['E-CC-P3', …],
// }
```

| 节奏 | 文件已读取, 最高优先 |
| --- | --- |
| 克劳德代码 | 管理 `managed-settings.json`, (中文(简体) ), `.claude/settings.local.json`, (中文(简体) ), `.claude/settings.json`, (中文(简体) ), `<config dir>/settings.json` |
| 代码 | `<config dir>/config.toml` |
| GitHub 副驾驶 CLI | 管理 `managed-settings.json`, (中文(简体) ), `.github/copilot/settings.local.json`, (中文(简体) ), `.github/copilot/settings.json`, (中文(简体) ), `<config dir>/settings.json` |
| Cursor, OpenCode, Kilo 代码, 双子座 CLI, Quen 代码, VS 代码中的副驾驶, Cline, Crush, OpenHands, Auggie CLI | 无: `supported` 实值 `false` |

仅报告有明确条目的插件。 没有条目的插件会回到默认状态 此软件包不知道 。 何时 `unread` 不为空, MDM 或服务器管理的政策仍然可以 推翻答案.

## 已安装插件

```ts
import { enabledPlugins, installedPlugins } from '@cyberuni/agent-harness'

const installed = await installedPlugins('claude-code')
// {
//   harness: 'claude-code',
//   supported: true,
//   plugins: [{ id: 'my-plugin@my-marketplace', path: '/home/me/.claude/plugins/cache/my-marketplace/my-plugin/1.0.0', version: '1.0.0', scope: 'user', research: ['E-CC-P2'] }],
//   unresolved: [],
//   sources: [{ path: '/home/me/.claude/plugins/installed_plugins.json', found: true }],
//   unread: [],
//   research: ['E-CC-P2'],
// }

// The folder of each enabled plugin:
const enabled = new Set((await enabledPlugins('claude-code')).plugins.filter((p) => p.enabled).map((p) => p.id))
const folders = installed.plugins.filter((p) => enabled.has(p.id)).map((p) => p.path)
```

| 节奏 | 从 | 文件夹 |
| --- | --- | --- |
| 克劳德代码 | `<config dir>/plugins/installed_plugins.json` | `installPath`; 每个范围安装一个插件条目 |
| 代码 | `<config dir>/plugins/cache/<marketplace>/<plugin>/` | `local` 如果存在, 其他最高版本, 如 Codex 所选 |
| GitHub 副驾驶 CLI | `<config dir>/config.json` `installedPlugins` | `cache_path`; 直接安装的 `id` 它的空名是无 |
| Cursor, OpenCode, Kilo 代码, 双子座 CLI, Quen 代码, VS 代码中的副驾驶, Cline, Crush, OpenHands, Auggie CLI | 无: `supported` 实值 `false` | —— 说 |

`unresolved` 列出缓存混合 semver 和非 semver 版本文件夹的 Codex 插件, 其中 文件夹 Codex 选择取决于其类型。 从本地添加的市场中加载 CLI 插件 路径到位,没有安装记录,所以它们出现在 `unread` 换句话说.

## 技能命名和插件依赖性

```ts
import { skillInvocation, supportsPluginDependencies } from '@cyberuni/agent-harness'

skillInvocation('claude-code', { plugin: 'my-plugin', skill: 'review' })?.text // '/my-plugin:review'
skillInvocation('copilot-cli', { plugin: 'my-plugin', skill: 'review' })?.text // '/review'
skillInvocation('codex', { plugin: 'my-plugin', skill: 'review' })?.text // '$review'
skillInvocation('gemini-cli', { plugin: 'my-plugin', skill: 'review' }) // undefined: the model loads skills itself

supportsPluginDependencies('claude-code') // true; false for the others
```

## 技能目录

```ts
import { skillsDirectories } from '@cyberuni/agent-harness'

skillsDirectories('claude-code') // { project: ['.claude/skills'], user: ['.claude/skills'], research: ['E-CC-L1'] }
skillsDirectories('codex')?.project.includes('.agents/skills') // true
skillsDirectories('qwen-code') // undefined: not confirmed
```

项目目录与项目根相对,用户目录与主目录相对. 仅 默认读取的目录被列出;管理员,捆绑,插件技能被忽略.

## 无头运行

如何运行一个没有用户的提示:命令、模型和权限 标记、输出格式以及其中显示符号用途和成本的地方、记录片位置、, 和记录的退出代码。 库只描述运行; 启动进程最多 你吗.

```ts
import { headlessCommand, headlessInvocation } from '@cyberuni/agent-harness'

headlessCommand('claude-code', {
  prompt: 'Fix the failing test',
  model: 'sonnet',
  permission: 'unattended',
  outputFormat: 'stream-json',
})
// { executable: 'claude', args: ['-p', '--model', 'sonnet', '--permission-mode', 'bypassPermissions',
//   '--output-format', 'stream-json', '--verbose', 'Fix the failing test'] }

const codex = headlessInvocation('codex')
// codex.outputFormats[1]: { name: 'jsonl', args: ['--json'],
//   usage: { event: 'turn.completed', tokens: 'usage', accumulate: 'sum' } } (no dollar cost)

headlessInvocation('vscode-copilot').supported // false: no headless mode
headlessInvocation('opencode').supported // 'unknown': a one-shot mode exists, but its flags are not verified
```

Claude Code, Codex, 副驾驶 CLI, Cursor, 双子座 CLI, 和 Quen Code 都涵盖在内. `permission: 'unattended'` 让运行中编辑文件和运行命令而不询问,所以只用在一个 弃取取出. 退出代码是一个弱信号: Claude 代码只记录零和非零,以及 以转弯停止的运行或预算上限由 `result` 留言的 `subtype`。 。 。 .

## 参考文件

参考文件是名为Markdown的文档,代理人按要求读取,例如核对表或一组 计算技能。 任何人都可以在不编辑传送它的插件的情况下覆盖一个插件: a 项目在 `.agents/references/<name>.md`,在 `~/.agents/references/<name>.md`。 。 。 .

```ts
import { loadReference } from '@cyberuni/agent-harness'

const resolved = await loadReference('agent-readiness-weights', {
    root: process.cwd(),
    // The plugin calling the resolver: its own `references/` is the first plugin layer.
    plugin: { name: 'my-plugin', root: pluginRoot },
})
if (resolved.status === 'found') console.log(resolved.content)
```

`status` 实值 `found`, (中文(简体) ), `missing`,或 `ambiguous` (两个插件持有此名称; 请求其中之一) `resolved.plugins`,例如 `my-plugin/agent-readiness-weights`) (中文(简体) ). `trace` 说出每一层所持有的东西.

层被读取最高优先 :

| 级别 | 文件夹 |
| --- | --- |
| 管理 | 管理员 `references/` 文件夹和 a `references/` 除了每个检测到的被管理的政策文件 |
| 项目 | `.agents/references/` 根和上方的每个文件夹,直到寄存器根 |
| 用户 | `~/.agents/references/` |
| 插件 | 调用插件 `references/`,每个插件,带启用,然后每个软件包 `package.json` 声明 |

每个文件夹中, `<name>.md` 先回答,然后说 `<name>/README.md`, (中文(简体) ), `<name>/index.md`,以及 `<name>/SKILL.md`. 遗产 `governances/` 文件夹仍在读取, 下方 `references/` 旁边 他们.

文档的前题 `merge` 说它如何与下面的地层结合:

-   `first-wins` (默认值):它取代了下面的一切.
-   `combine`:放在下层上方,每层保持整齐.
-   `merge-sections`:其各节取而代之的是下面标题相同的各节,并配以标题路径, 而它没有重新定义的部分被保留下来。 在标题下, `<!-- merge: combine -->` 附录 改为该节 `<!-- merge: remove -->` 删除它.

前题读作YAML. `merge`, (中文(简体) ), `description`,以及 `tags` 是解析器读取的密钥; `resolved.metadata` 持有每把钥匙,更高层的胜利。 不属于YAML 的前题 地图被忽略 警告.

| 函数 | 对 |
| --- | --- |
| `loadReference(name, options)` | 将根定出一个名称, 每一级改为 |
| `referenceLayers(options)` | 构建命令的图层,以解析多个名称 |
| `resolveReference(name, layers)` | 决定一个解析后的名称( N)`parseReferenceName`)对分层 |
| `listReferences(layers)`, (中文(简体) ), `referenceNames(layers)` | 层所持的每个名称, 以及每个副本的状态 |
| `listReferences(layers, { pattern })` | 按确切名称模式列出的每一个引用,都有层次、插件和模糊状态 |
| `searchReferences(query, layers)` | 按名称、描述、标题或正文匹配查询的名称 |
| `whereReference(name, layers, options)` | 工程和用户文件可以写入一个覆盖到 |
| `managedReferencesDir()`, (中文(简体) ), `projectReferencesDir()`, (中文(简体) ), `projectReferenceLayers()` | 单个文件夹和层 |
| `declaredDependencies()`, (中文(简体) ), `packageDir()` | 一份清单申报了包件,每个包装在哪里 |

### 引用命令

货包船a `reference` 命令为 `show`, (中文(简体) ), `list`, (中文(简体) ), `search`, (中文(简体) ), `where`, (中文(简体) ), `create`,以及 `delete` 子命令 :

```sh
npx -y @cyberuni/agent-harness reference show <name>... --root <repository root>
npx -y @cyberuni/agent-harness reference list
npx -y @cyberuni/agent-harness reference list 'project-tracker.capabilities.*'
npx -y @cyberuni/agent-harness reference create <name> --scope project
npx -y @cyberuni/agent-harness reference delete <name> --scope project --dry-run
```

`delete` 只删除复制到 `.agents/references/` (单位:千美元)`--scope project`)或(或) `~/.agents/references/` (单位:千美元)`--scope user`,以及复制后答复姓名的报告: 插件的复制件, 一旦一个工程的覆盖器消失 。 它拒绝一个插件已发送或管理的副本.

输出为 [东](https://github.com/toon-format/toon) 默认情况下, 代理分析; 通过 `--format json` 或者说 `--format text` (单位:千美元)`show`, (中文(简体) ), `create`,以及 `delete` 默认为 `text`) (中文(简体) ). 格式 跟着 [`clibuilder`](https://www.npmjs.com/package/clibuilder) 12,其他任何价值均为a 使用错误(退出代码2). 建材制造器制造的CLI 12 可以在自己的插件名称下托管同一命令 `./commands` 子路径. `--format` 是主机的全球选项,所以主机 `cli({ format })` 设置每个子命令的默认值; 页:1 `text` 默认 `show`, (中文(简体) ), `create`,以及 `delete` 属于 `agent-harness` CLI: 爱丽丝

```ts
import { createReferenceCommand } from '@cyberuni/agent-harness/commands'

app.command(createReferenceCommand({ plugin: { name: 'my-plugin', root: pluginRoot } }))
```

### 这个 `reference` 技能

软件包也是一个代理插件, `cyber-agent-harness`,该船a `reference` 技术。 类型 `/reference` (单位:千美元)`/cyber-agent-harness:reference` 在 Claude 代码中),以加载、创建、更新、删除、查找或 检查一个参考物, 或者用电线来装入一个。 技能只写或删除文件 你同意吗? 它从捆绑中运行命令 `scripts/reference.mjs`,则不需要 `node_modules`。 。 。 .

```text
/plugin marketplace add cyberuni/cyberplace
/plugin install cyber-agent-harness@cyberplace
```

需要一个参考名称的技巧 单行,作为技巧 [`README.md`](https://github.com/cyberuni/agent-harness/blob/main/packages/agent-harness/skills/reference/README.md) 显示 :

```text
Load `skill-design` with the `reference` skill in the `cyber-agent-harness` plugin.
```

## 为什么会这样

`universal-plugin`, (中文(简体) ), `buddy-agent-harness`, (中文(简体) ), `repobuddy`,以及 `cyberlegion/cyber-mux` 每一个需要知道 他们正在使用的是什么毒剂, 并且每个人都在重新分别进行检测. 这个软件包是存在的,因此它们共享一个执行.

## 许可证

[麻省理工学院](https://github.com/cyberuni/agent-harness/blob/main/LICENSE)

## 常见问题

### @cyberuni/agent-harness 是什么？

与 AI 代理 协作的工具包 : 检测哪个正在运行,查询其管理下的政策位置,插件存储,启用插件,以及技能命名,并解决分层的参考文件\.注意：该包已被作者标记为弃用——Renamed to cyber-agentkit

### 如何安装 @cyberuni/agent-harness？

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

### @cyberuni/agent-harness 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cyberuni\_\_agent-harness 是否存在。

### @cyberuni/agent-harness 支持 ESM 还是 CommonJS？

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

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

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

### @cyberuni/agent-harness 可以商用吗？

@cyberuni/agent-harness 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cyberuni/agent-harness 的下载量有多少？

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

### @cyberuni/agent-harness 还在维护吗？

最新版本 0\.7\.1 发布于 2026/10/18（24 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/27。作者已将其标记为弃用，新项目建议寻找替代方案。