@ docspack/ cmdspec
cmdspec:一个命令行接口的机器可读描述.
OpenAPI说HTTP API取取回. 连CLI都没说过 状态 : 打开CLI 是一个没有值类型的0.1草案 使用量 富贵但没有自己的文件计划。 cmdspec是一种格式 两者兼而有之,无论说什么,都不加损失地转换成它 说:命令是否安全运行,其退出状态意味着什么,它打印什么,以及哪些 选项适用于哪个操作.
- 规格:
SPEC.md(CC BY 4. 0) (中文(简体) ) - 计划:
schema/v0.1.jsonJSON Schema 2020-12 (英语) - 实例: 文档包装、 t、 ku和 ffmpeg
examples/ - 为什么它存在,是什么被测量:
docs/design/cmdspec.md
cmdspec: "0.1"
info: { name: greet, version: 1.0.0 }
arguments:
- { name: who, required: true }
options:
- { name: --shout, aliases: [-s], summary: Print in capitals }
effects: []
examples:
- run: greet world --shout
国家行动倡议
npx @docspack/cmdspec validate cmdspec.yaml
npx @docspack/cmdspec convert mise.usage.kdl --to cmdspec --program-version 2026.10.0
npx @docspack/cmdspec convert cmdspec.yaml --to opencli -o opencli.json
npx @docspack/cmdspec digest cmdspec.yaml remote add
npx @docspack/cmdspec map cmdspec.yaml
validate 报告每个问题,而不是第一个问题,并列出每个问题所在的命令和选项.
CLI本身由CMdspec文档定义—— cmdspec.yaml:它的解析器,它的
--help 财务报告和审定财务报表 cmdspec --cmdspec 都来自那个档案.
文摘——代理人的读取
一个命令,一切需要运行它, 在帮助页面的形状:
docspack ask <question>... [options]
Answer from the local index — the command to give an agent
<question>... words are joined with spaces
-p, --package <s> only packages whose name contains this text
--limit <n> maximum chunks to return (integer; at least 1; default 3)
--max-tokens <n> token ceiling for the result set (integer; at least 1; default 3000)
--all search the whole store, not just this project
also accepts: --store <path>, --cwd <dir>, --json, -q, --quiet, -h, --help
effects: read; idempotent
stdout: text/markdown, the answer; application/json, the chunks and their scores with --json
exit: 0 success; 1 the command failed; 2 the command was used wrongly; 3 nothing matched, and a docs package is installed but not indexed; 4 nothing matched, and everything installed is already indexed
$ docspack ask "how do I verify a webhook signature"
$ docspack ask "webhook signature" --package stripe --limit 5 # Look in one package only, and return more
这不是一个注解:每个注解都是一个词,因为帮助页是模型的格式 并且设计文件测量到 字比标记要贵3.2% 老师 它在帮助页面中添加的是帮助页面所遗漏的内容——类型,默认,效果, 产出和退出状况。 四个例子中最大的文摘是544个符号.
转换
| 从...到.. | 损失 |
|---|---|
| 使用量 ~ cmdspec | 无: 未映射属性和节点被保存 x-usage 写回 |
| OpenCLI — cmdspec | 无:未映射的字段被保存为 x-opencli-* |
| cmdspec – OpenCLI 光谱 | 无: OpenCLI 无法在其中表达的 metadata |
| (cmdspec-使用量) | 用法不能说——列出,从不悄悄地下降 |
测试真实文件而不是承诺:Mise自己的使用规格(290个命令)存活下来 用法 – cmdspec – 用法 – cmdspec 不变并转换为有效文档,和 dotnet的 已发布 OpenCLI 文档 (813 KB) 来源于 OpenCLI → cmdspec → OpenCLI 作为同名 JSON .
作为图书馆
import {
commandDigest,
fromOpenCli,
mergeOverlay,
parseArgsConfig,
resolveDocument,
toOpenCli,
} from "@docspack/cmdspec";
import { validate, validateOverlay } from "@docspack/cmdspec/validate";
import { readFile } from "@docspack/cmdspec/read";
import { fromUsage, toUsage } from "@docspack/cmdspec/usage";
import { fromCitty, fromCommander, fromYargs } from "@docspack/cmdspec/emit";
| 条目 | 包含 | 依赖性 |
|---|---|---|
@docspack/cmdspec | 类型, resolveDocument,摘要和地图, OpenCLI 转换, parseArgsConfig规则, mergeOverlay | 无 |
@docspack/cmdspec/validate | validate 计划,然后是规则; validateOverlay | ajv |
@docspack/cmdspec/read | readFile, (中文(简体) ), readText - JSON或YAML,经验证 | yaml |
@docspack/cmdspec/usage | fromUsage, (中文(简体) ), toUsage | @bgotink/kdl |
@docspack/cmdspec/emit | fromCommander, (中文(简体) ), fromCitty, (中文(简体) ), fromYargs | 无 |
@docspack/cmdspec/builder | mountCommandBuilders — 命令构建器, 在浏览器中 | 无 |
parseArgsConfig(command) 给 node:util是因为 parseArgs 命令文档中的选项,
因此一个节点CLI可以从它所记录的同一份文件中解析它的命令行.
读者选择的命令行
commandLine(builderTarget(command), values) 写入一组值生成的命令行..
附加文档的值 syntax 说,引用 POSIX 外壳,放 --
并列出仍然缺少的必要投入.
@docspack/sheaf-react是因为 CliBuilder 把它变成一种形式 @docspack/cmdspec/builder 运行在
浏览器作为读者类型 .
从指挥官,城堡或烤肉计划
一个已经用其中一个框架构建的程序有它的命令行在内存中. 发射者 阅读并写入文档,所以描述它从它实际描述的内容开始:
import { fromCommander } from "@docspack/cmdspec/emit";
import { program } from "./cli.js"; // the commander program, not yet parsed
const document = fromCommander(program);
fromCitty(command) 解决每一个懒惰的子命令,所以是aync. fromYargs(build) 拿着
函数用于构建程序,因为 yargs 只在运行时构建命令的选项,
在程序本身上;每个命令称为一次,版本来自
fromYargs(build, { version })。没有导入框架:每个排放方读取其少数字段
需要,条目没有依赖关系.
一个框架不知道的是,该文件没有说:效果、退出状况、产出和
实例。 故你们应当以他们为表率,以免后世失去他们;
docspack build 警告每个仍然失踪的人.
保持一个框架所不能知道
重叠是程序旁边的文件—— schema/overlay-v0.1.json
将它产生的每份文件合并:
cmdspecOverlay: "0.1"
exits:
"0": { meaning: success }
commands:
serve:
effects: [network]
options:
--port: { value: { minimum: 1024 } }
db drop:
effects: [destructive]
import { mergeOverlay } from "@docspack/cmdspec";
const result = mergeOverlay(fromCommander(program), overlay);
if (!result.merged) throw new Error(result.problems.map((p) => `${p.at}: ${p.message}`).join("\n"));
命令按其程序下方的路径键取,用拼写选项和用名参数键取.
每个条目必须给程序命名 所以重新命名 db drop 做一个覆盖
而不是一个静静地停止应用的补丁。 内容覆盖文档
退出; 如果程序表示一个值, 覆盖必须商定或列出
override。 。 。 . validateOverlay 对照其计划检查一个复数 mergeOverlay 报告
每一个问题,不是第一个。 为什么会这样
docs/design/cmdspec-adapters.md。 。 。 .
查找程序文档
一个软件包将其文档命名于 package.json —— 说 "cmdspec": "./dist/cmdspec.json",作为这个
执行 —— 当运行时, 一个程序会打印它 --cmdspec两者都载于SPEC第13节.
许可证
代码,计划以及例子都是MIT. 规格文本, SPEC.md,为
CC BY 4.0 (英语)固定装置由麻省理工学院颁发许可证
来自 mise 和 OpenCLI 的文档;见 tests/fixtures/README.md。 。 。 .