CLI-Anything 之 Inkscape Agent 原生 CLI：面向 SVG/XML 直接操作的有状态矢量图形命令行工具

CLI-Anything 之 Inkscape Agent 原生 CLI：面向 SVG/XML 直接操作的有状态矢量图形命令行工具

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

导读

本文将系统讲解开源仓库 CLI-Anything 中为矢量图形编辑器 Inkscape 打造的 Agent 原生命令行界面（关联文档）。与依赖 GUI 自动化或二进制格式解析的思路不同，该 CLI 利用 Inkscape 原生格式 SVG 即 XML 的特性，用 JSON 项目文件做状态追踪、按需生成合法 SVG，从而无需安装 Inkscape 即可完成绝大多数矢量图形编辑。读完本文，你将掌握该 CLI 的安装方式、完整命令组（文档/形状/文本/样式/变换/图层/路径/渐变/导出/会话）、JSON 输出模式与 REPL 用法，并能理解其“JSON 状态模型 + SVG 生成管线 + 可回退会话”的底层设计，直接用于 Agent 自动化出图、脚本化批量制图等场景。

一、设计动机：为什么不走二进制格式

Inkscape 的矢量图形处理能力强大，但其 GUI 基于 GTK，传统思路是借助命令行执行inkscape --actions或进行 UI 自动化，链路重且难以验证。本模块采取的是“直接操纵 SVG（XML）”的路线：SVG 本身是纯 XML 文本，天然具备 svg_utils.py 中体现的“人类可读、与 GUI 对象一一映射、CSS 样式可直接解析、transform 是标准 SVG 属性、图层即<g>元素、渐变位于<defs>”等优势。项目分析文档 INKSCAPE.md 将这一策略总结为三层引擎：

1. xml.etree.ElementTree——标准库直接解析与生成 SVG（主引擎）；
2. Pillow——把基础形状（矩形、圆、文本等）栅格化为 PNG；
3. Inkscape CLI（inkscape --actions）——仅在需要 PDF 导出、复杂路径布尔运算、text-to-path 等高级操作时作为可选后端。

由于 SVG 可以“从项目状态生成、在任何浏览器或 SVG 查看器中打开”，该 CLI 的渲染缺口评估为低：SVG 导出精确，基础 PNG 走 Pillow，复杂特性（滤镜、蒙版、裁剪路径）才回退到 Inkscape（详见 INKSCAPE.md 的渲染管线一节）。

二、安装与运行环境

从 关联文档 看，常规安装只需少量 Python 依赖：

# 在 agent-harness 目录内 pip install click pillow

需要特别说明的是：

• SVG 编辑不需要安装 Inkscape。click提供命令解析、pillow提供基础 PNG 栅格化，而 SVG 解析用的是 Python 标准库 +defusedxml。
• Inkscape 仅用于 PDF 导出与高级渲染（README 的 Installation 一节）。
• 若按 PyPI 包方式安装，setup.py 声明了cli-anything-inkscape控制台入口与依赖click>=8.0.0、prompt-toolkit>=3.0.0、defusedxml>=0.7.1，并要求python_requires=">=3.10"，同时注册 entry point：cli-anything-inkscape=cli_anything.inkscape.inkscape_cli:main（见 setup.py）。包内附带 Skills 文档用于 Agent 能力发现（见 skills/SKILL.md）。

pip install cli-anything-inkscape cli-anything-inkscape --help

在当前仓库内也可以直接以 Python 模块方式运行（包级__main__.py入口位于 inkscape/main.py）。本文示例沿用 README 的 Quick Start 中记载的python3 -m cli.inkscape_cli命令风格，实际调用入口名取决于你的安装形态（源码模块入口或cli-anything-inkscape控制台命令等价）。

三、Quick Start：一条龙完成“建文档→画形状→上样式→加文字→变换→渐变→导出”

文档 Quick Start 给出的完整工作流覆盖了绝大多数基础制图需求：

# 1) 创建新文档 python3 -m cli.inkscape_cli document new --name "MyDrawing" -o drawing.json # 2) 添加形状（每个命令都通过 --project 指向当前项目） python3 -m cli.inkscape_cli --project drawing.json shape add-rect --x 100 --y 100 --width 200 --height 150 python3 -m cli.inkscape_cli --project drawing.json shape add-circle --cx 400 --cy 300 --r 80 python3 -m cli.inkscape_cli --project drawing.json shape add-star --cx 700 --cy 300 --points 5 --outer-r 100 # 3) 设置样式（索引 0 是矩形的对象下标） python3 -m cli.inkscape_cli --project drawing.json style set-fill 0 "#ff0000" python3 -m cli.inkscape_cli --project drawing.json style set-stroke 1 "#000000" --width 3 # 4) 添加文字 python3 -m cli.inkscape_cli --project drawing.json text add --text "Hello World" --x 100 --y 50 --font-size 36 # 5) 变换对象（对象 0 向下平移 25，对象 1 旋转 45°） python3 -m cli.inkscape_cli --project drawing.json transform translate 0 50 --ty 25 python3 -m cli.inkscape_cli --project drawing.json transform rotate 1 45 # 6) 渐变：线性渐变后应用到对象 0 python3 -m cli.inkscape_cli --project drawing.json gradient add-linear --color1 "#ff0000" --color2 "#0000ff" python3 -m cli.inkscape_cli --project drawing.json gradient apply 0 0 # 7) 导出 python3 -m cli.inkscape_cli --project drawing.json export svg output.svg --overwrite python3 -m cli.inkscape_cli --project drawing.json export png output.png --overwrite

几个值得注意的约定（来自 README 及对应源码）：

• 对象引用一律用索引（下标），而非 ID。--project用于在多条命令之间延续同一个项目状态。
• 导出带--overwrite才允许覆盖已存在的输出文件；否则会抛出FileExistsError（见 export.py）。
• 若在--project指向一个尚不存在的路径，CLI 不会报错，而是自动为它 seed 一个全新内存文档（见 inkscape_cli.py 的_load_or_seed_project与 skills/SKILL.md），这对 Agent 边画边存档很友好。

四、JSON 输出模式：给 Agent 与脚本的机器可读接口

所有命令都支持全局--json标志，将结果以结构化 JSON 输出，取代默认的人类可读表格/键值对（README 的 JSON Output Mode 一节）：

python3 -m cli.inkscape_cli --json document new -o doc.json python3 -m cli.inkscape_cli --json --project doc.json shape list

实现上，inkscape_cli.py维护全局_json_output状态：开启时统一走json.dumps(data, indent=2, default=str)打印；关闭时用_print_dict/_print_list递归排版（见 inkscape_cli.py 的output()）。这意味着任何命令的结果都能被 LLM/Agent 稳定解析，而不必猜测表格格式。

五、交互式 REPL：带补全与历史的有状态会话

对于人工调试或半交互式编辑，可直接进入 REPL：

python3 -m cli.inkscape_cli repl # 或携带已有项目进入 python3 -m cli.inkscape_cli repl --project doc.json

REPL 复用同一套Session状态机（依赖 prompt-toolkit 提供 tab 补全与历史），可在会话内连续执行上述全部子命令，并借助undo/redo回退；主入口的 REPL 骨架可在 inkscape_cli.py 中查看（文档另提及 REPL 皮肤逻辑位于 utils/repl_skin.py）。

六、命令组全解

README 的 Command Groups 依功能将命令划分为十个组，下面逐一结合源码要点展开。

6.1 文档管理（document）

document new 创建新文档 document open 打开既有项目文件 document save 保存当前项目 document info 查看文档信息 document profiles 列出可用的文档画布预设 document canvas-size 设置画布尺寸 document units 设置文档单位（px, mm, cm, in, pt, pc） document json 打印原始项目 JSON

底层支撑在 core/document.py：PROFILES预置了 20 种常见画布（见 document.py 的 PROFILES），覆盖设计/社交/印刷场景，例如：

Profile	尺寸	单位	典型用途
default/hd1080p	1920×1080 / 1280×720	px	网页与高清视频
4k	3840×2160	px	超高清
a4_portrait/a4_landscape	210×297 / 297×210	mm	打印
letter_portrait	8.5×11	in	北美打印
instagram_story	1080×1920	px	竖版故事
youtube_thumbnail	1280×720	px	视频封面
business_card	3.5×2	in	名片
icon_16~icon_512	16~512	px	图标矩阵

VALID_UNITS = ("px", "mm", "cm", "in", "pt", "pc")（document.py）；create_document()对非法单位、非正尺寸做参数校验，并默认生成一个名为 “Layer 1”、visible/locked/opacity齐备的初始图层（document.py）。GUI 的“文件→新建/打开/保存”即对应document new/open/save（映射表见 INKSCAPE.md）。

6.2 形状管理（shape）

shape add-rect 添加矩形 shape add-circle 添加圆 shape add-ellipse 添加椭圆 shape add-line 添加线段 shape add-polygon 添加多边形 shape add-path 添加 SVG path shape add-star 添加星形 shape remove 按索引删除 shape duplicate 复制对象 shape list 列出全部形状 shape get 查看形状详情

各add-*使用直观的几何参数：矩形为--x/--y/--width/--height（支持自定义样式与圆角），圆为--cx/--cy/--r，星形为--points/--outer-r/--inner-r。底层在 core/shapes.py，它在 JSON 状态模型中登记对象并生成 SVG 元素；校验规则严格，例如拒绝负宽高、零半径、点数过少的星形与空 path/polygon（测试证据见 tests/TEST.md 的 TestShapes 一节），并保证所有对象 ID 唯一、默认归入当前图层。

6.3 文本管理（text）

text add 添加文本元素（支持 --box-width/--box-height/--line-height 排版） text set 修改文本属性（text、font-family、font-size、fill、box-width 等） text list 列出全部文本对象

自动换行文本盒是 skills/SKILL.md 特别强调的能力：text add --box-width 1180 --box-height 260 --line-height 1.05会把长文案按box-width折行，并在导出 SVG 时生成多个<tspan>行；box-height则让超长文案“安全失败”，避免文字溢出画布。适合标题卡、标签、竖版安全区等长文案场景：

cli-anything-inkscape --project title.json text add \ --text "Real capture + Veo cold open + Gemini score + thumbnail plate" \ --x 180 --y 470 --font-size 118 \ --box-width 1180 --box-height 260 --line-height 1.05 cli-anything-inkscape --project title.json text set 0 box-width 980 cli-anything-inkscape --project title.json text set 0 line-height 1.15

Text 排版辅助函数（layout_text_lines、text_anchor_x）被导出模块直接复用（见 core/export.py），即“文本盒折行”在 PNG/SVG 两个渲染路径中行为一致。

6.4 样式管理（style）

style set-fill 设置填充色 style set-stroke 设置描边色/描边宽度 style set-opacity 设置整体不透明度（0.0–1.0） style set 设置任意 CSS 样式属性 style get 读取对象样式 style list-properties 列出可用样式属性

样式本质上是 CSS 字符串。工具层 svg_utils.py 提供parse_style/serialize_style把"fill:#ff0000;stroke:#000;stroke-width:2"与 dict 互转、按需update_element_style，并用validate_color校验 hex /rgb()/ 命名色 /none（见 svg_utils.py 与 svg_utils.py 的 validate_color）。校验层还会拒绝负描边宽、越界透明度等（测试证据见 TEST.md 的 TestStyles）。

6.5 变换操作（transform）

transform translate 平移 transform rotate 旋转（可指定旋转中心） transform scale 缩放（支持非等比） transform skew-x 水平斜切 transform skew-y 垂直斜切 transform get 读取当前变换 transform clear 清空全部变换

所有变换最终以 SVGtransform属性字符串（如translate(10,20) rotate(45)）作用于对象。按 TEST.md TestTransforms 的描述，core/transforms.py 具备“链式变换累积”与“解析/序列化 transform 字符串”能力，并拒绝零缩放等非法输入。

6.6 图层管理（layer）

layer add 添加图层 layer remove 删除图层 layer set 设置图层属性（name、visible、locked、opacity） layer move-object 把对象移动到其他图层 layer list 列出全部图层 layer reorder 调整图层顺序 layer get 查看图层详情

在 SVG 中图层就是<g>元素，并以inkscape:groupmode="layer"标记（INKSCAPE.md 的 SVG Generation 步骤 3）。JSON 项目模型中的每个 layer 记录id/name/visible/locked/opacity/objects，导出 SVG 时按层从底到顶绘制，visible=false的层及其对象会被跳过（见 export.py 的 render_to_png）。

6.7 路径布尔运算（path）

path union 两个形状取并集 path intersection 取交集 path difference 取差集（A-B） path exclusion 取异或（XOR） path convert 把形状转换为路径 path list-operations 列出支持的运算

core/paths.py 维护PATH_OPERATIONS注册表，把 union / intersection / difference / exclusion 乃至 division、cut_path 映射到 Inkscape 的原生 verb/action（如path-union、SelectionDiff等，见 paths.py），同时声明了可转换类型的白名单。需要如实说明的实现边界是：这些操作先在 JSON 模型中记录“路径操作元数据”，真正复杂的 SVG path 计算仍需 Inkscape（或路径计算库）在渲染阶段完成——这也是 INKSCAPE.md 明确标注的渲染缺口之一。

6.8 渐变管理（gradient）

gradient add-linear 添加线性渐变 gradient add-radial 添加径向渐变 gradient apply 把渐变应用到对象 gradient list 列出全部渐变

线性渐变用两个颜色端点建模，如--color1 "#ff0000" --color2 "#0000ff"；渐变定义写入 SVG 的<defs>，apply则通过 fill 引用绑定到对象。项目模型中的gradients数组字段结构（含x1/y1/x2/y2与 stop 列表）可参考 INKSCAPE.md 中的示例 JSON。

6.9 导出（export）

export png 用 Pillow 栅格化为 PNG export svg 导出为 SVG 矢量文件 export pdf 导出为 PDF（需要 Inkscape） export presets 列出导出预设

core/export.py 内置了EXPORT_PRESETS（见 export.py）：png_web(96 DPI)、png_print(300 DPI)、png_hires(600 DPI)、svg、pdf、eps。其中有一个值得 Agent 注意的优雅降级设计：若 Pillow 不可用，render_to_png不会直接失败，而是先生成 SVG，再输出一条inkscape ... --export-filename=... --export-dpi=...命令供调用方执行（export.py），保证“渲染路径永远可达”。导出保真度小结（INKSCAPE.md）：SVG 精确、基础 PNG 走 Pillow、PDF/EPS 走 Inkscape。

6.10 会话管理（session）

session status 查看会话状态 session undo 撤销上一步 session redo 重做被撤销的操作 session history 查看撤销历史

核心实现在 core/session.py：Session.MAX_UNDO = 50（session.py），即最多保留 50 级撤销历史。机制上，每次变更前snapshot()用copy.deepcopy把整个项目状态连同操作描述、时间戳压入撤销栈并清空重做栈；undo()再把当前状态压入重做栈并弹回历史快照（session.py）。此外，save_session()采用fcntl文件锁做原子化 JSON 落盘（写前LOCK_EX、完成后LOCK_UN，非 POSIX 平台自动跳过锁，见 session.py 的_locked_save_json），这为多进程/多 Agent 并发操作同一项目文件提供了基本防护。

七、状态模型：.inkscape-cli.json项目文件

CLI 的双文件策略是理解一切的钥匙（README 的 Key Design 一节）：

• JSON 项目文件.inkscape-cli.json追踪所有对象、图层、渐变与元数据，支撑状态管理与撤销/重做；
• SVG 文件在导出时由项目状态生成，输出的是可在 Inkscape、浏览器或任何 SVG 查看器中打开的合法文档；
• 命名空间会写入inkscape:、sodipodi:前缀，与 Inkscape 的图层体系等特性保持兼容。

所以全程无需解析任何二进制格式，一切都是可读的 XML 与 JSON。项目格式的完整示例（document/objects/layers/gradients/metadata五段结构，含单对象的style、transform、layer归属字段）见 INKSCAPE.md 的 Project Format 一节。GUI 操作与 CLI 命令之间存在清晰的映射表（矩形/圆形/星形/路径/文本/图层/渐变/样式/变换/布尔运算/撤销重做，逐条列出），便于把 GUI 工作流翻译成 Agent 可执行的命令序列，参见 INKSCAPE.md 的 Command Map。

八、SVG 生成原理与命名空间细节

工具层 utils/svg_utils.py 完整声明了 SVG 生态所需的全部命名空间常量：SVG_NS、INKSCAPE_NS、SODIPODI_NS、XLINK_NS及 RDF/CC/DC 等（svg_utils.py），并在模块加载时用ET.register_namespace统一注册，避免序列化时产生ns0/ns1这类脏前缀（svg_utils.py）。create_svg_element()生成根<svg>时写入width/height/viewBox/version，自动附带<defs>与带inkscape:document-units、pagecolor的sodipodi:namedview元数据（svg_utils.py）。SVG 文件解析统一使用defusedxml（svg_utils.py），规避了 XXE 等 XML 安全风险，这对解析外部传入 SVG 的 Agent 管线尤为重要。

从项目状态到 SVG 的生成顺序（INKSCAPE.md 的 Rendering Pipeline）依次为：建根元素与 viewBox → 写入渐变<defs>→ 为每个图层生成带inkscape:groupmode="layer"的<g>→ 把形状/文本/path 放入所属图层组 → 应用样式、变换与渐变引用。对应实现位于 core/document.py 的project_to_svg/save_svg。

九、架构速览与测试体系

按 README 的 Architecture，模块按职责拆分为扁平目录，主入口在 inkscape_cli.py，核心逻辑全部落在core/下的十个模块，与本文 6.1–6.10 的每个命令组一一对应：

core/document.py 文档创建/打开/保存/信息 + SVG 生成 core/shapes.py 形状操作（rect、circle、path、star…） core/text.py 文本元素管理 core/styles.py CSS 样式管理（fill/stroke/opacity） core/transforms.py 变换（translate/rotate/scale…） core/layers.py 图层/分组管理 core/paths.py path 布尔运算 core/gradients.py 渐变管理 core/export.py 导出（Pillow PNG / SVG / PDF） core/session.py 带撤销/重做的有状态会话 utils/svg_utils.py SVG XML 辅助、命名空间常量

测试证据（tests/TEST.md）显示共197 个测试：test_core.py的 11 个测试类覆盖 150 个纯内存单元测试（不使用真实文件、不需要 Inkscape），test_full_e2e.py的 5 个测试类覆盖 47 个端到端用例。E2E 关注点包括：SVG XML 合法性（格式良好、命名空间正确）、文档 JSON 往返、SVG 导出后回读、PNG 像素验证、多步工作流与 CLI 子进程调用。运行方式：

# 在 agent-harness 目录内 python3 -m pytest cli/tests/ -v # 全部测试 python3 -m pytest cli/tests/test_core.py -v # 仅单元测试 python3 -m pytest cli/tests/test_full_e2e.py -v # 仅端到端 python3 -m pytest cli/tests/ -v --tb=short # 短回溯模式

（注：仓库当前包布局下测试位于 tests/ 的test_core.py与test_full_e2e.py。）

十、给 AI Agent 的接入约定

无论用于 LLM 工具调用还是脚本化流水线，skills/SKILL.md 给出的建议均成立：

1. 一律使用--json取机器可读输出；
2. 检查返回码——0 表示成功，非零即出错；
3. 解析 stderr获取失败时的错误信息；
4. 文件操作用绝对路径，避免工作目录歧义；
5. 导出后验证产物存在，再进入下一步；
6. 标题与变长文案优先用文本盒自动折行（box-width/line-height），保证多次编辑后布局稳定。

结合本文所讲的状态模型，还可以总结出更高级的 Agent 用法：先document new建项目，再以“一命令一对象”的方式增量编辑；需要回退时不必重建文档，直接session undo消费 50 级历史；最后用export svg拿精确矢量结果、用export png拿位图预览；整个过程中.inkscape-cli.json既是状态源也是审计日志，任何一步都能通过document json全量导出核对。

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything