# @dolusoft/command-protocol 中文文档

规范地址：https://npmcn.com/package/%40dolusoft/command-protocol/

版本：1\.9\.0
npm 元数据更新时间：2026-11-11T13:14:23.620Z
中文译文更新时间：2026-11-12T15:23:14.187Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：172 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18
- 运行依赖：0 个
- 首次发布：2026-10-26T17:49:29.435Z
- 最新版本发布：2026-11-11T13:14:23.199Z
- 近 30 天下载量：3427（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

命令控制台的JSON:条目,输出块,命令光谱,响应,效果,上下文框架,以及行指示器. 无依取相.

## 安装

```sh
npm install @dolusoft/command-protocol
```

也可以使用：`pnpm add @dolusoft/command-protocol`、`yarn add @dolusoft/command-protocol`、`bun add @dolusoft/command-protocol`

## README

# @ dolusoft/ command- protocol

JSON类型 [命令控制台](https://github.com/dolusoft/command-console)和纯正的 函数高于命令输入计划、选项行和信封。 没有依附关系 没有框架 没有DOM.

```sh
pnpm add @dolusoft/command-protocol
```

大部分消费者都用它 `@dolusoft/command-console` (再出口其类型)或 `@dolusoft/command-console-core`。当服务器或测试建立控制台输出时直接使用,或者像控制台那样分割一行.

## 类型

这里的每一个类型都是普通的JSON:只有有限的数字,没有 `undefined` (缺少一个没有值的可选字段),以及 一个数值存在 `JSON.parse(JSON.stringify(x))` 不变. `JsonValue`, (中文(简体) ), `JsonPrimitive` 财务报告和审定财务报表 `isJsonValue` 说明和说明 检查它。 函数( 一个命令 ) `run` 财务报告和审定财务报表 `complete`住在核心,从来没有在这里.

-   **条目** 向后滚动 : `ConsoleEntry` 是一个 `InputEntry` (单位:千美元)`id`, (中文(简体) ), `prompt` 当线路结束时, `text` 或者说 `null` 当它被修改的时候, `redacted`, (中文(简体) ), `status: 'submitted' | 'cancelled'`选项 `actor`数字 : `'user'`, (中文(简体) ), `'assistant'` 或者说 `'external-agent'`,历史的标签,绝不允许)或 `OutputEntry` (单位:千美元)`id`, (中文(简体) ), `tone: 'default' | 'error' | 'notice'`, (中文(简体) ), `blocks`选项 `inputId` 选择 `quiet: true` 用于产出的活区不应读出.
    
-   **块** 输出条目(`OutputBlock`),从HTML:
    
    | 块 | 字段 |
    | --- | --- |
    | `text` | `text` |
    | `json` | `value: JsonValue` |
    | `table` | `columns: { key, label }[]`, (中文(简体) ), `rows: Record<string, JsonPrimitive>[]` |
    | `list` | `items: string[]` |
    | `message` | `code: MessageCode`, (中文(简体) ), `params?` (由图书馆制作) |
    | `custom` | `kind`, (中文(简体) ), `data?: JsonValue` (消费者驾驶) |
    
-   **信件** (单位:千美元)`MessageCode`, (中文(简体) ), `MessageParams`:库中写出没有文字,只有代码. `command-not-found` (单位:千美元)`{ name }`, (中文(简体) ), `command-failed` (没有偏差:错误的文本从未显示), `unterminated-quote` (单位:千美元)`{ index }`, (中文(简体) ), `interrupted`, (中文(简体) ), `invalid-args` (单位:千美元)`{ path, reason }`: 一个命令选项的第一个错误, `reason` a 一个 `InputErrorCode`和 `operation-failed` (单位:千美元)`{ code }`页:1 `ErrorCode`,用于结束而不运行其 页:1 对于敏感线条 `name`, (中文(简体) ), `index` 财务报告和审定财务报表 `path` 为: `null`。 。 。 .
    
-   **图标**数字 : `CommandSpec` 是一个命令的 JSON 部分(`name`, (中文(简体) ), `aliases`, (中文(简体) ), `summary`, (中文(简体) ), `usage`, (中文(简体) ), `hidden`, (中文(简体) ), `sensitive: boolean | { fromArg }`, (中文(简体) ), `input` (其输入方案,下), `danger: 'read' | 'change' | 'irreversible'`) (中文(简体) ). `CommandResponse` 是命令可以归还的`output`, (中文(简体) ), `tone`, (中文(简体) ), `quiet`, (中文(简体) ), `effects`, (中文(简体) ), `summary`,结果很短 最多200个操作的呼叫者字符,以及 `data`JSON的结果 给那个从不 最多抽签 `dataMaxBytes` (32768)字节为UTF-8 JSON.
    
-   **结果** (单位:千美元)`CommandOutcome`: `{ status: 'ok', summary?, data? }` 或者说 `{ status: 'error', code: ErrorCode, message?, line? }`,如何结束其呼叫者的行动; `line` 只来 与 `not-allowed`线条 `change` 命令用户可以输入. `ErrorCode` 实值 `invalid-args`, (中文(简体) ), `unknown-command`, (中文(简体) ), `not-allowed`, (中文(简体) ), `target-not-found`, (中文(简体) ), `id-conflict`, (中文(简体) ), `unsupported-version`, (中文(简体) ), `too-large`, (中文(简体) ), `busy`, (中文(简体) ), `timeout`, (中文(简体) ), `failed`, (中文(简体) ), `connection-lost` 或者说 `cancelled`。 。 。 .
    
-   **效果** (单位:千美元)`ConsoleEffect`: `clear`, (中文(简体) ), `close`, (中文(简体) ), `push-context` (单位:千美元)`frame`, (中文(简体) ), `pop-context` (单位:千美元)`count?`,默认 1), `reset-context`, (中文(简体) ), `clear-recall`。它们在响应输出前按顺序应用.
    
-   **背景框架** (单位:千美元)`ContextFrame`: `{ id, prompt, data? }`。顶框的 `prompt` 是下一行的提示.
    

## 行语法

白空(包含tabs) 分隔符. `'…'` 从字面上来说. `"…"` 和其中的团体 `\"` 财务报告和审定财务报表 `\\` 这是 只有逃脱。 外部引用 `\` 是个普通的角色,所以 `C:\data` 留下来 `C:\data`。相邻部分加入一个符号 (单位:千美元)`a"b c"d` 实值 `ab cd`(三); `''` 财务报告和审定财务报表 `""` 给一个空的标志。 没有线的延续.

```ts
import { quoteArgument, tokenize } from '@dolusoft/command-protocol'

tokenize(`set title "Hello \\"world\\""`).tokens.map(t => t.value)
// ['set', 'title', 'Hello "world"']

const result = tokenize(`set title 'Hello`)
// result.ok === false, result.error: { code: 'unterminated-quote', index: 10 }
// result.tokens still holds the tolerant tokens; the last one has open: true

const args = ['set', 'path', 'C:\\Program Files']
const line = args.map(quoteArgument).join(' ')
// "set path 'C:\\Program Files'", which tokenizes back to the same three values
```

每个 `Token` 拥有 `value` (引文已删除), `start` 财务报告和审定财务报表 `end` (单位:千美元), `end` 独家, 包括原文及其引文), `quoted` 财务报告和审定财务报表 `open`。未关闭的引文给出 `ok: false` 指数 开头的引号,符号仍然还原: `open` 然后跑到终点 这个 控制台拒绝这样一条线;完成工作在宽容的标志上起作用。 什么都没有掉下来.

`quoteArgument(value)` 返回最短的:光值, `'value'`,或 `"value"` 与逃脱; 它总是 符号返回到 `value`。 。 。 .

## 输入方案

一个命令 `input` 是JSON Schema的一个小子集. 根为: `type: 'object'`;一个节点是:

| `type` | 关键词 `description` 财务报告和审定财务报表 `default` |
| --- | --- |
| `string` | `enum`, (中文(简体) ), `minLength`, (中文(简体) ), `maxLength`, (中文(简体) ), `pattern` |
| `number`, (中文(简体) ), `integer` | `enum`, (中文(简体) ), `minimum`, (中文(简体) ), `maximum` |
| `boolean` | 无 |
| `array` | `items` (必须), `maxItems`; 无 `default` |
| `object` | `properties`, (中文(简体) ), `required` |

`checkInputSchema(schema)` 丢出一个 `TypeError` 命名其它任何路径: 另一个关键字, 一个关键字 类型它不适用,不匹配的属性名称 `^[A-Za-z][A-Za-z0-9_-]*$`页:1 `pattern` 没错 未与该编译 `u` 旗帜, a `required` 名称不是一个财产, a `default` 节点拒绝,或对象和 数组的嵌入比输入限制允许的更深。 没有什么是被忽视的.

`validateInput(schema, value)` 返回时 `{ ok: true, value }` 带有新值( 缺少一个可选字段) 对象取其 `default`,不存在的可选数组是 `[]`)或(或) `{ ok: false, errors }` 错误为 `{ path, code }`数字 : `path` 实值 `ip`, (中文(简体) ), `filter.ip`, (中文(简体) ), `tags[2]` 或者说 `''` 对于根, 和价值从来没有在里面。 代码 为: `type` (单位:千美元) `integer` 想要一个完整的数字, `required`, (中文(简体) ), `additional` (一个字段不在 `properties`, (中文(简体) ), `limit` 财务报告和审定财务报表 失败的关键字名称。 长度计算代码点; a `pattern` 未锁定.

每个值都持有到 `inputLimits` 不管它的策略允许什么: 最多1000个代码点的字符串 (单位:千美元)`maxTextLength`),最多50个项的数组(`maxArrayLength`),最多3个深处的对象和数组,根对象 为 1(`maxDepth`) (中文(简体) ). 在他们之外,代码是 `limit`。 。 。 .

### 选项行

写有计划的命令 `name --field value …`。 。 。 . `parseOptions(args, schema)` 后取符号值 名称并返回 `validateInput` 返回 :

```ts
import {
  formatCommandLine,
  type InputSchema,
  parseOptions,
  tokenize
} from '@dolusoft/command-protocol'

const schema: InputSchema = {
  type: 'object',
  properties: {
    ip: { type: 'string' },
    limit: { type: 'integer', default: 100 },
    verbose: { type: 'boolean' },
    tags: { type: 'array', items: { type: 'string' } }
  },
  required: ['ip']
}

const args = tokenize('search --ip 10.0.0.5 --verbose --tags a --tags b')
  .tokens.slice(1)
  .map(t => t.value)
parseOptions(args, schema)
// { ok: true, value: { ip: '10.0.0.5', limit: 100, verbose: true, tags: ['a', 'b'] } }

formatCommandLine('search', { ip: '10.0.0.5', tags: [] }, schema)
// 'search --ip 10.0.0.5 --limit 100'
```

一个值会转换为它的字段类型: JSON 所写入的数字,一个对象(或者一个属于对象的数组项目,或者 如 JSON 文本, 字符串, 如它开始时的字符串 `--`。一个布尔地是 `true` 并带有 `true` 或者说 `false`。一个数组字段重复它的名称;一个缺失的字段是 `[]`。未知名称,或不是 名称,是 `additional`;没有其值的名称,或不是数组的字段的第二个值,是 `type`。 。 。 .

`formatCommandLine(command, value, schema)` 写出条子行:按顺序写已验证值的字段 联 合 国 `properties`,每个符号通过 `quoteArgument`, (中文(简体) ), `true` 像赤裸裸一样 `--name` 财务报告和审定财务报表 `false` 作为 `--name false`。 。 名称后读取符号 `parseOptions` 以同样价值计算。 计划拒绝的价值. `formatCommandArgv(command, value, schema)` 给予未引用的等同数组(`['search', '--ip', '10.0.0.5', '--limit', '100']`(三); `tokenize(formatCommandLine(...))` 还给他们.

## 信封

一个 `Envelope` 在用户标签之间带一个请求; 消费者的运输移动它, 仅协议 描述和检查:

```json
{
  "v": 1,
  "id": "3f0c6c1e-6d1b-4a8e-9b7e-2a4c1f2d9e10",
  "kind": "request",
  "actor": "user",
  "from": { "tab": "t-5b21" },
  "target": { "tab": "t-5b21", "view": "v-91c0" },
  "command": "dataview.search",
  "args": { "ip": "10.0.0.5", "from": "2026-11-04T18:40:00Z" }
}
```

`parseEnvelope(raw)` 读一下从运输中传来的东西 永远不会改变 它回来了 `{ ok: true, envelope }` 带有一个只保存已知字段的新信封,或 `{ ok: false, code }`数字 : `unsupported-version` 为平地 对象 `v` 是1以外的数字, `too-large` 当它的UTF-8 JSON结束时 `envelopeMaxBytes` (16384, 以生值计量, `invalid` 对于缺失或打错的字段,另一个 `kind`,或 `args` 这不是JSON 在输入限制范围内的对象。 A 类 `null` `target.view`,键入的传输可能回回写,不是视图,而是 离开. `envelopeBytes(envelope)` 是其JSON的UTF-8长度,供发送者在发送之前测量.

## 远程信封

桌面 CLI 发送 `cli-request`页:1 `help-request` 或一个 `cancel` 通过枢机到它必须的标签 (ADR 0014);中枢写出印章. A 类 `cli-request` 将命令带入 `argv` (如壳分出)或同为一 `line`,从来没有两者:

```json
{
  "v": 1,
  "kind": "cli-request",
  "id": "r-1",
  "argv": ["tasks.stop", "--id", "8812"],
  "origin": { "kind": "cli", "grantId": "g-1", "bindingId": "b-1" },
  "stampedAt": 1793957400000,
  "expiresAt": 1793957430000
}
```

`parseCliMessage(raw)` 检查为 `parseEnvelope` 检查信封( a) `argv` 最多为 `remoteArgvMaxItems` 及项目和项目 `remoteLineMax` 代码; 对于 a `cli-request` 它拒绝, `refusedCliRequest(raw)` 只读 `id` 编辑 `origin` ids,所以标签可以回答. 标签的答案是 `received`, (中文(简体) ), `awaiting-approval`, (中文(简体) ), `chunk`, (中文(简体) ), `finished`, (中文(简体) ), `help-result`, (中文(简体) ), `cancelled-before-start` 财务报告和审定财务报表 `cancel-requested` (单位:千美元)`CliReply`, (中文(简体) ), `isCliReply`) (中文(简体) ). 每一个错误 携带其 `class` (单位:千美元)`errorClassOf(code)`)),CLI变为其出站代码; `suggest` 财务报告和审定财务报表 `next` 参数为 CLI的指纹,永远不要运行。 结果 `data` 作为JSON文本在最多时 `remoteChunksMax` (3) 最多块 `envelopeMaxBytes` 每一个: `chunkData(id, text)` 切开, `joinChunks(finished, chunks)` 加入或给予 `undefined` 当一个部分缺失时. `CommandSpec.confirm` 命名将预览转换成修改的布尔字段 cLI 变化不需要这样的领域 `--dry-run` 请求预览. `CommandSpec.effect` 说什么 `change` 命令更改( e)`screen` 或者说 `server`),和变化的 `finished` 说它是如何被放走的`approval`数字 : `card` 或者说 `none`) (中文(简体) ).

CLI的标签不是信封: `capabilitiesParts(payload)` 切换一个 JSON `CapabilitiesPayload` (单位:千美元)`envelopes`, (中文(简体) ), `features`, (中文(简体) ), `minCli`, (中文(简体) ), `revision`, (中文(简体) ), `sensitive`, (中文(简体) ), `commands`)为一至三 用于枢纽的最多16个KB部分,以及 `readCapabilitiesParts(parts)` 读回来. `remoteFeatures` 财务报告和审定财务报表 `remoteEnvelopes` 这是这个版本所说的。 规范领域表格载于 [`docs/remote-contract.md`](https://github.com/dolusoft/command-console/blob/main/docs/remote-contract.md)· ; `fixtures/remote/` 存放处有他们的例子.

## 许可证

麻省理工学院,看 [利比里亚](https://npmcn.com/package/%40dolusoft/command-protocol/LICENSE.md)。 。 。 .

## 常见问题

### @dolusoft/command-protocol 是什么？

命令控制台的JSON:条目,输出块,命令光谱,响应,效果,上下文框架,以及行指示器\. 无依取相\.

### 如何安装 @dolusoft/command-protocol？

在项目目录运行 npm install @dolusoft/command-protocol，或使用 pnpm add / yarn add / bun add。

### @dolusoft/command-protocol 支持 TypeScript 吗？

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

### @dolusoft/command-protocol 支持 ESM 还是 CommonJS？

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

### @dolusoft/command-protocol 需要什么版本的 Node\.js？

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

### @dolusoft/command-protocol 可以商用吗？

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

### @dolusoft/command-protocol 的下载量有多少？

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

### @dolusoft/command-protocol 还在维护吗？

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