@ dolusoft/ command- protocol

JSON类型 命令控制台和纯正的 函数高于命令输入计划、选项行和信封。 没有依附关系 没有框架 没有DOM.

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个操作的呼叫者字符,以及 dataJSON的结果 给那个从不 最多抽签 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(三); '' 财务报告和审定财务报表 "" 给一个空的标志。 没有线的延续.

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';一个节点是:

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 返回 :

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 在用户标签之间带一个请求; 消费者的运输移动它, 仅协议 描述和检查:

{
  "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,从来没有两者:

{
  "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· ; fixtures/remote/ 存放处有他们的例子.

许可证

麻省理工学院,看 利比里亚。 。 。 .