`matrix_registry.json` 是什么：矩阵这层抽象干什么用

CLI-Anything 仓库根目录下有三张注册表 JSON。registry.json 是主表，我们采集时（2026-08-10，对应仓库快照 39634a6）clis 数组是 79 条；public_registry.json 是 22 条；第三张叫 matrix_registry.json，只有 5 条。前两张讲的是「有哪些 CLI」，第三张讲的是完全不同的一件事。

先说一个会直接把脚本卡住的差别：matrix_registry.json 的顶层键是 meta 和 matrices，不是 clis。你如果写了个小脚本处理前两张表，习惯性地 d['clis'] 一把梭，读到这张表会直接 KeyError。它的 meta 有四个字段：repo、description、updated（值是 2026-06-11）、以及一个 registry.json 的 meta 里没有的 schema_doc（registry.json 的 meta 只有 repo、description、updated 三个字段）。description 原文是 “Curated CLI Matrix registry for CLI-Hub multi-CLI workflows (capability-based, v2 schema)“（matrix_registry.json:3-6）——关键词是 multi-CLI 和 capability-based，这两个词基本把这层抽象的定位说完了。

五条矩阵的原始数据

我们采集时（2026-08-10 快照），matrices 数组长度是 5，每条 15 个字段，5 条全都齐（Python 解析后逐条比对字段集）。下面这张表和本节后面的字段清单，数的都是这一份快照：

matrix_id	name	display_name	category	version	引用 CLI 数	capabilities	recipes	known_gaps
S1	video-creation	Video Creation & Editing	video	3	14	19	7	4
S2	knowledge-research	Knowledge / Office / Research	knowledge	1	13	12	6	4
S3	3d-cad	3D & CAD	3d	1	6	12	6	4
S4	game-development	Game Development	game	1	9	10	6	3
S5	image-design	Image & Graphic Design	image	1	7	9	7	3

15 个字段是：name、display_name、version、schema_version、description、category、matrix、matrix_id、homepage、skill_md、clis、capabilities、recipes、known_gaps、suggest_to_user_template。其中 matrix 字段 5 条全是 "cli-matrix"，schema_version 5 条全是 "2"。

这里有个容易看串的地方：这张表上有两个版本号，含义完全不同。schema_version 说的是这张表本身用的 schema 版本（全为 2），version 说的是这条矩阵内容的版本——S1 是 3，其余四条都是 1。你写工具做兼容判断时，认的应该是 schema_version。

从内容看，一条 matrix 由四块组成：clis 是它要调动的那批命令行工具，capabilities 是它声称能干的事，recipes 是把这些能力串起来的固定配方，known_gaps 是它明说干不了的事。这四块合起来构成的东西，和 registry.json 那种「一条记录 = 一个软件」的登记方式，完全不是一个层级——前者登记的是场景。五条矩阵对应五个场景：做视频、做研究、做三维与 CAD、做游戏、做图。

最反直觉的一处：注册表里专门留了字段登记「做不到」

绝大多数注册表、目录、插件市场干的都是同一件事：把「我有什么」列出来。known_gaps 反过来——它是这张表里结构化程度和其它字段完全对等的一个数组字段，5 条矩阵每条都有，条数是 4、4、4、3、3，每一条 gap 含三个子字段：capability（缺的是哪个能力）、reason（为什么缺）、workaround（暂时怎么绕）。

举三条卡在具体位置上的：

• S1 video-creation 记了一个 publish.upload 缺口，reason 原文是 “No first-party or public CLI for YouTube/TikTok/Bilibili/Instagram yet.”。也就是说这条矩阵能帮你把片子剪出来，但发布这一步它自己写明了没有对应的 CLI。
• S4 game-development 的 game.engine 缺口原文写 “Only Godot has a harness; no Unity/Unreal path.”。做游戏这条线上，引擎这一环只覆盖了 Godot。
• S5 image-design 把 Figma 称为 “the headline cross-scenario gap (S5 and S7)”。

为什么这件事值得单独拎出来讲？因为它正好戳中读这个仓库最容易犯的错：注册表里有条目，不等于这件事你装上就能干。registry.json 那 79 条也一样，79 条不是 79 个开箱可用的能力——单是我们采集时的目录比对就有 11 条 registry 里有条目而根目录没有同名目录（那 11 条正好都是 source_url 非 null、指向独立仓库的条目）。matrix 这层的价值恰恰在于它把边界写进了数据结构：一条矩阵告诉你它能串起哪几步，同时告诉你哪一步串不上、以及项目自己建议怎么绕。你在评估要不要按某条矩阵组工作流时，known_gaps 应该是第一个读的字段，而不是最后一个。

还有一层现实约束不能略过：README 明确提醒过，包装真实桌面软件的 CLI 需要用户自行安装上游应用（README.md:236）。S1 这 14 个里有相当一部分是桌面软件的壳，README 提醒的正是这一类；至于具体哪几条落在这个限定里、各自要装什么，本文没有逐条核对到宿主依赖，不做清单。另外，这类 harness 运行时会在本机执行外部程序与脚本。这两件事都和「注册表里有没有这一条」无关。

矩阵引的 CLI，横跨两张注册表

把 5 条矩阵的 clis 全摊平去重，一共 37 个不同的 CLI 名。它们并不都来自 registry.json：

S1 那 14 个里，openscreen、obs-studio、audacity、kdenlive、shotcut、videocaptioner、gimp、krita、inkscape 这 9 个能在 registry.json 的 79 条里查到，而 generate-veo-video、jimeng、minimax-cli、elevenlabs、suno 这 5 个查不到——它们在 public_registry.json 的 22 条里。S2 到 S5 引用的名字则全部落在 registry.json 的 79 条内。

这个分布是有意思的：public_registry.json 登记的是第三方与官方 CLI（meta.description 里写的是跨 npm、bundled、brew 等安装方式管理的那批），而矩阵这层不管你来自哪张表，只按能力挑人。S1 那五个来自 public 表的名字，在 public_registry.json 里的 category 分别是 ai 三条、audio 一条、music 一条，仓库内 harness 那批则以本地桌面软件为主。想验证这一点不用读代码，把三张 JSON 的 name 集合取出来做差集就行，下一节给命令。

顺带一提，两张注册表各自的字段差异是另一篇的话题，本篇只关心矩阵这层怎么跨表引用。

三处对不上的地方

写这类结构解读绕不开一件事：文档指的路径和仓库里实际有的东西，未必对得上。这张表上有三处。

第一处，schema_doc 和 homepage 指向的目录不存在。 meta.schema_doc 写的是 docs/cli-matrix/matrix_registry.schema.md（matrix_registry.json:6），5 条矩阵的 homepage 则统一指向 docs/cli-matrix/cli-matrix-plan.md。而我们采集时 ls docs/cli-matrix 返回 “No such file or directory”，find docs -type f 数出来的 32 个文件里也没有任何 cli-matrix 路径。JSON 里写了两个路径、仓库里这两个路径都不存在，这是两个可以各自核对的事实，我们只陈述到这里。这对你的直接影响是：想搞清 v2 schema 每个字段的确切语义，schema 文档这条路走不通，只能回去读 JSON 本身。

第二处，S7 被提到了，但矩阵只有 S1 到 S5。 上面引过的 S5 那条 Figma 缺口，原文把它称作 “the headline cross-scenario gap (S5 and S7)“，而 matrices 数组长度是 5，matrix_id 是 S1 到 S5。表里提到了一个表里没有的编号，同样是两个并列的事实。

第三处不算矛盾，但值得记一笔：skill_md 是这张表上唯一被验证全部存在的路径。 5 条矩阵的 skill_md 形如 cli-hub-matrix/<name>/SKILL.md，我们采集时逐条 test -f，5 条全部命中。也就是说矩阵这层真正落地的产物是那 5 份 SKILL.md——给 agent 读的那一份，而不是给人读的 plan 文档。

你可以自己跑一遍的核对动作

上面的数都能自己复现。clone 仓库后在根目录执行：

python -c "
import io, json
d = json.load(io.open('matrix_registry.json', encoding='utf-8'))
print(list(d.keys()))
print(len(d['matrices']))
for m in d['matrices']:
    print(m['matrix_id'], m['name'], m['version'], m['schema_version'],
          len(m['clis']), len(m['capabilities']), len(m['recipes']), len(m['known_gaps']))
"

想验证「矩阵横跨两张注册表」这一点，把三张表的名字集合取出来做差集：

python -c "
import io, json
load = lambda f, k: set(c['name'] for c in json.load(io.open(f, encoding='utf-8'))[k])
r = load('registry.json', 'clis')
p = load('public_registry.json', 'clis')
m = json.load(io.open('matrix_registry.json', encoding='utf-8'))['matrices']
names = set(c for x in m for c in x['clis'])
print(len(names), sorted(names - r))
"

想确认那两条文档路径：

ls docs/cli-matrix
ls cli-hub-matrix/*/SKILL.md

以上为按仓库中的文件与字段语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

怎么用这层抽象

从读者处境倒推，这张表有两种读法。

如果你是想按场景组一条多工具流水线的人：先看 matrix_id 找到对应场景，再读 known_gaps 确认你要的那一步在不在缺口清单里，最后才去看 recipes 里的配方。顺序反过来的话，你会在把前几步接通之后才发现最后一步项目自己写了没有对应 CLI。

如果你是想给这个仓库贡献东西的人：五条矩阵覆盖的是视频、知识研究、三维 CAD、游戏、图像五个场景，known_gaps 里那十几条 capability 是项目自己列出来的空位。至于这些空位是不是欢迎外部补，CONTRIBUTING.md 里我们只核对过 registry 条目的字段要求，矩阵这块没有核实过，不下结论。

最后回到最开始那个 5 和 79 的对比。79 条是「这个仓库碰过哪些软件」，5 条是「这些软件被组织成了哪几种干活方式」。后者的数量少得多，但它是唯一一处把「多个 CLI 怎么配合」写成结构化数据的地方——包括写下哪里配合不起来。

---

本文依据 CLI-Anything 官方仓库（github.com/HKUDS/CLI-Anything）的 README、registry.json、 docs/ 与各 agent-harness/ 下的源码整理，核对日 2026-08-10，对应仓库快照 39634a6。 本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何一个 harness， 也没有在本机驱动过任何一款宿主软件，因此不涉及实际操控效果的任何描述。 这类 harness 会在本机执行外部程序与脚本，是否使用请结合自身环境评估。 注册表与 harness 内容随上游更新而变动，请以仓库最新内容为准。 安全相关做法请结合自身环境评估，本文不构成安全方案建议。