CLI-Anything 之 Inkscape Agent 原生 CLI面向 SVG/XML 直接操作的有状态矢量图形命令行工具【免费下载链接】CLI-AnythingCLI-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 自动化链路重且难以验证。本模块采取的是“直接操纵 SVGXML”的路线SVG 本身是纯 XML 文本天然具备 svg_utils.py 中体现的“人类可读、与 GUI 对象一一映射、CSS 样式可直接解析、transform 是标准 SVG 属性、图层即g元素、渐变位于defs”等优势。项目分析文档 INKSCAPE.md 将这一策略总结为三层引擎xml.etree.ElementTree——标准库直接解析与生成 SVG主引擎Pillow——把基础形状矩形、圆、文本等栅格化为 PNGInkscape CLIinkscape --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控制台入口与依赖click8.0.0、prompt-toolkit3.0.0、defusedxml0.7.1并要求python_requires3.10同时注册 entry pointcli-anything-inkscapecli_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, indent2, defaultstr)打印关闭时用_print_dict/_print_list递归排版见 inkscape_cli.py 的output()。这意味着任何命令的结果都能被 LLM/Agent 稳定解析而不必猜测表格格式。五、交互式 REPL带补全与历史的有状态会话对于人工调试或半交互式编辑可直接进入 REPLpython3 -m cli.inkscape_cli repl # 或携带已有项目进入 python3 -m cli.inkscape_cli repl --project doc.jsonREPL 复用同一套Session状态机依赖 prompt-toolkit 提供 tab 补全与历史可在会话内连续执行上述全部子命令并借助undo/redo回退主入口的 REPL 骨架可在 inkscape_cli.py 中查看文档另提及 REPL 皮肤逻辑位于 utils/repl_skin.py。六、命令组全解README 的 Command Groups 依功能将命令划分为十个组下面逐一结合源码要点展开。6.1 文档管理documentdocument 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.pyPROFILES预置了 20 种常见画布见 document.py 的 PROFILES覆盖设计/社交/印刷场景例如Profile尺寸单位典型用途default/hd1080p1920×1080 / 1280×720px网页与高清视频4k3840×2160px超高清a4_portrait/a4_landscape210×297 / 297×210mm打印letter_portrait8.5×11in北美打印instagram_story1080×1920px竖版故事youtube_thumbnail1280×720px视频封面business_card3.5×2in名片icon_16~icon_51216~512px图标矩阵VALID_UNITS (px, mm, cm, in, pt, pc)document.pycreate_document()对非法单位、非正尺寸做参数校验并默认生成一个名为 “Layer 1”、visible/locked/opacity齐备的初始图层document.py。GUI 的“文件→新建/打开/保存”即对应document new/open/save映射表见 INKSCAPE.md。6.2 形状管理shapeshape 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 文本管理texttext 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.15Text 排版辅助函数layout_text_lines、text_anchor_x被导出模块直接复用见 core/export.py即“文本盒折行”在 PNG/SVG 两个渲染路径中行为一致。6.4 样式管理stylestyle 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 变换操作transformtransform 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 图层管理layerlayer add 添加图层 layer remove 删除图层 layer set 设置图层属性name、visible、locked、opacity layer move-object 把对象移动到其他图层 layer list 列出全部图层 layer reorder 调整图层顺序 layer get 查看图层详情在 SVG 中图层就是g元素并以inkscape:groupmodelayer标记INKSCAPE.md 的 SVG Generation 步骤 3。JSON 项目模型中的每个 layer 记录id/name/visible/locked/opacity/objects导出 SVG 时按层从底到顶绘制visiblefalse的层及其对象会被跳过见 export.py 的 render_to_png。6.7 路径布尔运算pathpath 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 渐变管理gradientgradient add-linear 添加线性渐变 gradient add-radial 添加径向渐变 gradient apply 把渐变应用到对象 gradient list 列出全部渐变线性渐变用两个颜色端点建模如--color1 #ff0000 --color2 #0000ff渐变定义写入 SVG 的defsapply则通过 fill 引用绑定到对象。项目模型中的gradients数组字段结构含x1/y1/x2/y2与 stop 列表可参考 INKSCAPE.md 中的示例 JSON。6.9 导出exportexport png 用 Pillow 栅格化为 PNG export svg 导出为 SVG 矢量文件 export pdf 导出为 PDF需要 Inkscape export presets 列出导出预设core/export.py 内置了EXPORT_PRESETS见 export.pypng_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.mdSVG 精确、基础 PNG 走 Pillow、PDF/EPS 走 Inkscape。6.10 会话管理sessionsession status 查看会话状态 session undo 撤销上一步 session redo 重做被撤销的操作 session history 查看撤销历史核心实现在 core/session.pySession.MAX_UNDO 50session.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 文件解析统一使用defusedxmlsvg_utils.py规避了 XXE 等 XML 安全风险这对解析外部传入 SVG 的 Agent 管线尤为重要。从项目状态到 SVG 的生成顺序INKSCAPE.md 的 Rendering Pipeline依次为建根元素与 viewBox → 写入渐变defs→ 为每个图层生成带inkscape:groupmodelayer的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 个纯内存单元测试不使用真实文件、不需要 Inkscapetest_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 --tbshort # 短回溯模式注仓库当前包布局下测试位于 tests/ 的test_core.py与test_full_e2e.py。十、给 AI Agent 的接入约定无论用于 LLM 工具调用还是脚本化流水线skills/SKILL.md 给出的建议均成立一律使用--json取机器可读输出检查返回码——0 表示成功非零即出错解析 stderr获取失败时的错误信息文件操作用绝对路径避免工作目录歧义导出后验证产物存在再进入下一步标题与变长文案优先用文本盒自动折行box-width/line-height保证多次编辑后布局稳定。结合本文所讲的状态模型还可以总结出更高级的 Agent 用法先document new建项目再以“一命令一对象”的方式增量编辑需要回退时不必重建文档直接session undo消费 50 级历史最后用export svg拿精确矢量结果、用export png拿位图预览整个过程中.inkscape-cli.json既是状态源也是审计日志任何一步都能通过document json全量导出核对。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考