Skip to content

CLI ​

预览版本

当前 jsmind CLI 仍是预览版本,之后还会更新。请随时查阅本文档,以了解当前可用的命令和用法。

CLI 是 jsMind V2 导图数据的命令行工具。你可以创建导图、查看树结构和 id、修改结构和节点属性、校验文件,以及导出图片。

安装 ​

请先用 npm i jsmind@2 安装 2.x 版本,然后运行 npx jsmind。如果使用本仓库的克隆,请先构建,再运行 npx jsmind 或 node dist/cli.js。这两种方式任选其一,不是先后步骤。安装说明见 快速上手。

需要临时查看参数时,可以运行 jsmind --help。要确认预览版当前有哪些命令,请以本文档为准。

用法 ​

jsmind <command> [options]

全局选项 ​

这些选项对所有命令和子命令都合法。

选项含义
--json以机器可读格式输出
--dry-run只显示将要发生的改动,不写入文件
--output <path>写入到输入文件以外的路径
--backup覆盖前保留一份 .bak 备份
--strict把未知选项当作用法错误
--version打印版本号后退出
-h, --help显示内置帮助

--dry-run、--output 和 --backup 适用于会改写文件的 mind 和 node 子命令。create 支持 --dry-run 和 --backup,但输出路径就是位置参数里的文件,因此不使用 --output。

其余选项归属具体的子命令,见下面各节。某个命令不接受的选项会被报告出来,而不是默默忽略——见 未知选项。

--version 打印 package.json 里的 version 字符串,单独一行,不带其他文字,也不需要子命令。版本号只有一处定义,所以不会和发布版本脱节。

未知选项 ​

每个子命令都只接受固定的选项集合:上面这些全局选项,加上它自己的。集合之外的选项——拼错的 flag,或者属于另一个子命令的 flag——会打到 stderr,命令照常执行。

$ jsmind mind find map.json --node-id root --sdie
jsmind: warning: unknown option for "mind find": --sdie (--strict makes this an error)
{
  "id": "root",
  ...
}

警告不会写进 stdout,所以 --json 的输出仍然可以直接解析。代价是另一面:只看 stdout 和退出码的调用方看不到这条警告。这是「只警告不报错」的固有成本,不是以后要修的 bug。不能接受这一点时,加上 --strict,同样的调用就变成用法错误,退出码 2:

$ jsmind mind find map.json --node-id root --sdie --strict
Unknown option for "mind find": --sdie
$ echo $?
2

脚本和 agent 流程里建议打开 --strict:选项被默默忽略,比命令失败更糟。

不做拼写建议。判断 --sdie「像是」--side 只能靠猜意图,猜错的代价是把调用方引去改一个它根本没打过的 flag。

退出码 ​

退出码含义
0成功
1数据无效
2用法错误
3IO 或运行时错误

create ​

jsmind create <file> --title <title> [options]

创建一张只包含根节点的新导图。

选项含义
--title <title>根节点文字;同时用作 meta.name(必填)
--name <name>当 meta.name 需要和标题不同时,用它覆盖
--author <author>写入 meta 的作者
--force若文件已存在则覆盖
--backup覆盖前保留一份 .bak 备份
--dry-run打印文档内容,不写入文件

没有 --force 时,create 不会覆盖已有文件。其他命令都假定文件已经存在;新文件由这条命令创建。

validate ​

jsmind validate <file> [--json]

按格式规范检查一份 v2 导图文件,并报告发现的全部问题。它不会修改文件。

退出码含义
0有效
1数据无效
3无法读取文件

context ​

jsmind context <file> [options]

这是查看步骤:打印整棵树,方便你(或 agent)找到后续命令所需的 id。

选项含义
--focus <text>按节点文字模糊匹配,并连同祖先一起显示
--depth <n>从根节点往下显示的层数(默认 2)
--max-text <n>将标签截断到 n 个字符(默认 40)
--full-text不截断
--ids-only只打印 id
--json以机器可读格式输出

id 会打印在左对齐的一列中,便于复制到下一条命令。多行标签会被展平,截断处以省略号结束。行尾可能带有 {…} 块。side 只出现在根节点及其直接子节点上;节点折叠时会出现 folded;若节点样式与主题不同,也会显示相应覆盖项。

文件如果声明了文档级样式,树的上方会多一行摘要,这样在任何节点被读到之前就能发现主题:

style: theme=default defaultTone=primary overrides=defaultTone,tones,node

--json 返回一个带 nodes 数组的对象;文件带样式时,会额外给出同一个摘要作为 style 块(theme、defaultTone、overrides)。文件没有文档级样式时两者都不出现,文本那一行在 --ids-only 下会被省略。

当 --focus 没有匹配到任何节点时,会改为列出最接近的候选项。

export ​

jsmind export <file> <out.png> [options]

将思维导图渲染为图片。输出尺寸以导图自身大小为准:视口内的空白会保留,超出视口的部分也不会被裁切。

export 需要 Chromium 浏览器。如果它不在常见安装位置,请设置 CHROME_PATH;浏览器启动比默认的 60 秒还慢,就设置 JSMIND_BROWSER_START_MS。

选项含义
--width <px>布局时使用的视口宽度(默认 1200)
--height <px>视口高度(默认 800)
--scale <n>输出像素比(默认 2)
--type <format>image/png、image/jpeg 或 image/webp(默认 image/png)
--transparent透明背景(PNG 和 WebP;需显式打开,默认保持当前的不透明背景)。用于 JPEG 时会忽略该选项并给出警告。
--json以机器可读格式输出

按默认的宽度、高度和缩放,常见导出尺寸是 2400×1600 像素。

mind ​

jsmind mind <subcommand> <file> [options]

用于修改结构和关系边,以及文档自身的样式。定位一律使用 id。请使用当前这次 context 输出中的 id,不要沿用示例里的 id。

子命令选项含义
find--node-id <id>显示一个节点
list-edges--node-id <id>列出与该节点相连的边
add-child--parent-id <id> --text <text> [--side left|right] [--position <n>] [--folded true|false]添加一个子节点
move--node-id <id> --parent-id <id> [--position <n>]将节点移到新的父节点下
remove-node--node-id <id>删除该节点、它的整棵子树,以及触及其中任一节点的所有边
add-edge--source-id <id> --target-id <id> [--type link] [--label <text>]添加一条关系边
remove-edge--edge-id <id>删除一条关系边
set-style--default-tone <tone>文档级样式(mind.style):没有自己 tone 的节点所用的语气

--side 只在父节点是根节点时合法。侧向是根的直接子节点的位置,它下面整棵子树都继承这个侧向,所以在更深的地方写 side 只会改文件、不改画面 —— 这种情况是用例错误(退出码 2),报错会点名该节点所属的一级分支,不会静默通过。只有根节点是 center,所以 --side 只接受 left 或 right。

--position 是父节点 children 数组的下标。越过末尾会追加,省略同样是追加。根节点的子节点跨两侧计数:下标对应的是这一个数组,不是某一侧的列表。

--folded true 表示新建节点时就折叠。

所有会改写数据的子命令都会在完成后校验结果,失败则回滚。这些写入可以使用 --dry-run、--output 和 --backup。

mind set-style ​

jsmind mind set-style <file> [style fields]

文档级样式(mind.style):写一次,所有没有单独覆盖的节点都继承。它写的是 mind.style 而不是某个节点的样式 —— 给单个节点覆盖主题是 node set-style —— 所以「整张图换个配色」仍然是一次写入,语义色也就留给真正需要突出的节点。

字段可选值
--default-tone <tone>default | primary | success | warning | danger | info | accent

defaultTone 是没有自己 tone 的节点所用的语气。优先级为 node.style.tone > mind.style.defaultTone > "default",连线颜色走同一个回落。这个字段存的是语气名字而不是调色板,所以 tones 覆盖仍然作用在它上面。

--dry-run、--output、--backup 与其他改写命令一致。

node ​

jsmind node <subcommand> <file> --node-id <id> [options]

用于修改节点属性。结构上的改动请使用 jsmind mind。

子命令选项含义
set-text--node-id <id> --text <text>修改标签
set-folded--node-id <id> --folded true|false折叠或展开
set-side--node-id <id> --side left|right设置节点所在侧
set-style--node-id <id> [style fields]为单个节点覆盖主题样式

set-side 只对根的直接子节点合法,理由和 add-child --side 一样:只有这些节点的侧向会改变排版。根节点永远是 center,所以 --side 只接受 left 或 right;打在更深的节点上是用例错误,报错会点名它所属的一级分支,而不是一次画面看不见的写入。

set-style 的字段可以在一次写入中组合使用。点号表示层级,因此 --incoming.color 对应 style.incoming.color。

字段可接受的值
--tone <value>default | primary | success | warning | danger | info | accent
--background <color>CSS 颜色字符串
--color <color>CSS 颜色字符串
--border-color <color>CSS 颜色字符串
--border-width <number>正数
--border-style <value>solid | dashed | dotted
--font-size <number>正数
--font-weight <value>normal | bold
--incoming.color <color>CSS 颜色字符串
--incoming.width <number>正数
--incoming.pattern <value>solid | dashed | dotted
--incoming.curve <value>straight | bezier

若要恢复为主题中的值:

选项含义
--clear <fields>逗号分隔的字段名,拼写与对应参数相同
--reset清除该节点上的全部样式覆盖

样式块只记录与主题不同的项,因此去掉某个键就会恢复主题中的值。没有 unset 这样的哨兵值——键不存在就表示没有覆盖。--reset 不能与具体字段或 --clear 同时使用。

颜色只检查是否为字符串,主题接受任意 CSS 颜色。语气、线型和字重会在这里校验,这样错误值会指向你输入的参数,而不是某个 JSON 路径。

节点的 id、父节点和子节点只能通过 jsmind mind 修改。每条 node 子命令都会在完成后校验结果,失败则回滚。这些写入可以使用 --dry-run、--output 和 --backup。

另见 ​

  • 快速上手 — 安装并创建第一张图
  • Skill — 供 agent 用本 CLI 画图或改图时遵循的禁令与清单

本文档由 AI 协助生成 / This documentation was prepared with AI assistance