企业官网建设流程全解析

CLI-Anything Krita Harness 实战：用命令行与 Agent 驱动 Krita 数字绘画全流程

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

本文是 Krita CLI 技能（skill）的完整技术指南，讲解如何在无 GUI 环境下通过cli-anything-krita完成工程创建、图层管理、滤镜应用、画布调整与多格式导出，并解锁面向 AI Agent 的 JSON 机器可读输出模式。读完本文，你既能手工敲出一条条可复现的绘画流水线命令，也能理解其"工程 JSON → .kra 打包 → 真实 Krita 引擎渲染"的底层实现原理，从而放心地把 Krita 绘画接入脚本与 Agent 工作流。

概览：让 Krita 成为可编程软件

Krita 是 KDE 出品的专业开源数字绘画软件，支持栅格与矢量图形、动画，以及 90 余种混合模式与完整 ICC 色彩管理。在开源仓库 CLI-Anything 中，Krita 的 agent-harness（krita/agent-harness）为它包了一层纯命令行的"操作皮肤"，把所有关键操作收敛为project / layer / filter / canvas / export / session / status等命令组。

一个重要设计前提是：这个 CLI 是通向 Krita 的接口，而不是替代品。所有像素级渲染都由 Krita 自己的引擎完成——CLI 只负责把意图翻译成结构化的工程状态与合法的.kra文件（渲染管线说明见 KRITA.md 的 "Rendering Approach" 一节）。

前置条件与安装

技能文档（SKILL.md）声明了两个前置条件：

• Krita已安装到系统（Windows / macOS / Linux 均可）；
• Python 3.10+（harness 运行环境）。

安装命令如下（在仓库根目录执行）：

cd krita/agent-harness && pip install -e .

安装 Krita 的常见途径：Windows 从官网下载安装包；macOS 用brew install --cask krita；Linux 可用sudo apt install krita或flatpak install flathub org.kde.krita。

CLI 运行时会自动探测 Krita 可执行文件。查看 krita_backend.py 的find_krita()可知其查找顺序：优先读取KRITA_PATH环境变量（显式指定路径）→ 其次查找系统PATH中的krita/krita.exe→ 再次是 Windows 常见安装目录（通配符匹配）→ 最后是 macOS 应用包路径。全部找不到时会抛出带安装指引的RuntimeError，status命令会如实报告krita_installed: false。

命令体系总览

入口可执行文件为cli-anything-krita，全局携带三个影响所有子命令的选项（实现在 krita_cli.py）：

命令组与子命令一览：

若不带任何子命令直接运行cli-anything-krita，会进入交互式 REPL（repl子命令，隐藏项），可配合--project project.json直接加载工程。

工程管理：以 JSON 为中枢的项目生命周期

Krita CLI 不像 GUI 那样直接操作.kra，而是先维护一份工程 JSON（project state），记录画布、图层与滤镜等文档状态。核心数据结构由 project.py 的create_project()生成，字段包括name / version / created / modified / canvas / layers / metadata。

新建工程

cli-anything-krita project new -n "My Art" -w 2048 -h 2048 -o project.json

project_new 支持的参数：

校验规则也在这里生效：画布宽高与分辨率必须为正整数，颜色空间与位深必须命中白名单，否则抛出ValueError。新建工程会自动带一个名为Background、不透明度 255、混合模式 normal 的默认 paintlayer。不带-o时工程仅驻留内存，可通过后续project save落盘。

打开、保存与查看信息

cli-anything-krita project open project.json cli-anything-krita --project project.json project save cli-anything-krita --project project.json project info

project open读取工程 JSON 并做基本完整性检查（缺少version或canvas字段会报非法文件）；project save在未传-o时写入当前已绑定路径；project info输出画布尺寸、颜色空间、位深、图层数与每层摘要。save_project()通过locked_save_json原子落盘（见 io.py），避免并发写坏文件。

值得注意的自动化细节：当使用--project执行单次命令（one-shot）时，命令结束会自动把变更保存回工程文件（见 krita_cli.py 的_auto_save），因此每步修改后不必手动save；若想先演练后落盘，加--dry-run即可。

图层管理：从草图到着色的堆栈编排

图层命令覆盖增、删、查、改四类操作：

cli-anything-krita -p project.json layer add "Sketch" -t paintlayer cli-anything-krita -p project.json layer add "Colors" --opacity 200 cli-anything-krita -p project.json layer add "Group" -t grouplayer cli-anything-krita -p project.json layer remove "Sketch" cli-anything-krita -p project.json layer list cli-anything-krita -p project.json layer set "Colors" opacity 180 cli-anything-krita -p project.json layer set "Colors" visible false cli-anything-krita -p project.json layer set "Colors" blending_mode multiply

layer add

支持的 7 种图层类型与 CLI 的--type取值一致：

paintlayer、grouplayer、vectorlayer、filterlayer、filllayer、clonelayer、filelayer

其他参数：--opacity默认255（取值范围 0–255，越界会抛ValueError）；--blending默认normal（如 multiply、overlay 等 Krita 混合模式名）；--hidden以隐藏状态创建图层。图层名在同一堆栈内必须唯一（project.py）。

layer list与layer set

layer list打印形如[索引] 名称 (类型) opacity=值 visible/hidden的列表，方便核对堆栈顺序。layer set使用三参数形式layer set <图层名> <属性> <值>，值会自动做类型推断：true/yes→True，false/no→False，纯数字 →int，否则保留字符串。可修改属性包括opacity、visible、blending_mode、locked、name、type，其中opacity与type在赋值时会再次校验（project.py）。

滤镜应用：声明式的效果描述

cli-anything-krita -p project.json filter apply blur -l "Background" cli-anything-krita -p project.json filter apply sharpen cli-anything-krita -p project.json filter apply levels -c '{"shadows": 10, "highlights": 240}' cli-anything-krita filter list

filter apply的参数：filter_name为必选滤镜名；-l, --layer指定目标图层，缺省时作用于当前堆栈最上层（实现上取layers[-1]，见 krita_cli.py）；-c, --config以 JSON 字符串传入滤镜专属参数，如上面的 levels 示例传入{"shadows": 10, "highlights": 240}。滤镜会被追加到目标图层的filters列表，随工程状态持久化，由渲染引擎在导出时统一求值。

技能文档列出的可用滤镜集合为：blur, sharpen, desaturate, levels, curves, brightness-contrast, hue-saturation, color-balance, unsharp-mask, posterize, threshold。

若执行filter list，实际返回的完整清单还包含更多变体（定义于 project.py 的VALID_FILTERS）：

blur、gaussian-blur、motion-blur、lens-blur、sharpen、unsharp-mask、brightness-contrast、levels、curves、hue-saturation、color-balance、desaturate、invert、posterize、threshold、auto-contrast、normalize、emboss、edge-detection、oil-paint、pixelize、noise-reduction、halftone

传入清单之外的滤镜名会立即抛ValueError（project.py），起到纠错与可发现性作用。

画布操作：调整画布与分辨率

cli-anything-krita -p project.json canvas resize -w 4096 -h 4096 cli-anything-krita -p project.json canvas resize --resolution 600 cli-anything-krita -p project.json canvas info

canvas resize的-w/-h/--resolution三个参数均为可选，只更新显式给出的维度，其余保持不变（见set_canvas()实现 project.py），因此上面第二条命令仅把 DPI 改为 600。负值或零会被拒绝。canvas info则输出当前画布的宽、高、颜色空间、位深与分辨率。

导出与渲染：把工程交给真正的 Krita 引擎

cli-anything-krita -p project.json export render output.png -p png --overwrite cli-anything-krita -p project.json export render output.jpg -p jpeg cli-anything-krita -p project.json export render output.psd -p psd cli-anything-krita -p project.json export animation ./frames/ -p png cli-anything-krita export presets cli-anything-krita export formats

导出预设

技能文档列出的预设：png, png-web, jpeg, jpeg-web, jpeg-low, tiff, tiff-lzw, psd, pdf, svg, webp, gif, bmp。

各预设的底层编码参数定义在 export.py 的EXPORT_PRESETS中，值得展开的细节：

这些选项最终会通过--export-option key=value逐个传给 Krita 进程（见 krita_backend.py）。export presets/export formats可随时查询可用项。

渲染管线：Project JSON → .kra → Krita --export

export render走的是一条值得单独理解的双段管线（其流程与 KRITA.md 描述的 "Rendering Approach" 一致）：

1. 打包 .kra：build_kra_from_project()（export.py）在临时目录把工程状态拼装成合法 Krita 归档——mimetype（application/x-kra，必须为首项且不压缩）、maindoc.xml（含图层堆栈、尺寸、颜色空间）、documentinfo.xml（Dublin Core 元数据）以及每个 paintlayer 对应的空白 RGBA PNG 图层文件；
2. 调用真实引擎：export_file()定位系统 Krita 可执行文件，执行krita --export --export-filename <输出> --export-option key=value <临时.kra>完成真正渲染（krita_backend.py）。这样 Krita 的混合模式、滤镜与色彩管理均由官方引擎求值，保证输出保真。

安全语义上，目标文件已存在且未加--overwrite时会抛FileExistsError拒绝覆盖（export.py）；导出成功返回output_path / file_size / format / method等可验证信息。export animation则改用--export-sequence导出帧序列，支持--basename前缀（默认frame，产出frame_0001.png这类命名）与帧范围控制。

会话管理：命令级 undo / redo

cli-anything-krita session undo cli-anything-krita session redo cli-anything-krita session history

会话层由 session.py 的Session类实现：每次变更操作（建工程、加/删图层、改属性、加滤镜、改画布）都会在内存中snapshot一份深拷贝的工程状态，并附带时间戳与操作说明标签。执行 undo/redo 时通过移动历史指针回放或丢弃状态；若撤销后产生新操作，指针之后的所有 redo 分支会被截断（标准线性历史语义）。session history会带>>>标记当前指针位置。undo/redo 触发的状态变化同样会自动保存回--project文件，让多步流水线的回滚在命令行上也可安全执行。

status则给出一次性的全局快照：工程是否加载、路径、历史深度、能否 undo/redo、当前画布与图层数，以及 Krita 版本号与是否探测到（krita_cli.py）。

Agent 使用：JSON 机器可读模式

技能文档明确说明：所有命令都支持--json输出机器可读结果，这是面向 LLM / Agent 集成设计的核心接口：

cli-anything-krita --json -p project.json project info cli-anything-krita --json -p project.json layer list cli-anything-krita --json status

该模式由_output()与统一错误装饰器handle_error保障（krita_cli.py）：正常结果整体json.dumps缩进输出；各类失败（FileNotFoundError、FileExistsError、RuntimeError及其他异常）也会被捕获并序列化为{"error": ..., "type": <异常类型>}，方便 Agent 用结构化的方式判断成功与失败，而不是解析人读文本。层列表、滤镜清单、导出预设与格式在 JSON 模式下均返回数组/对象结构。

对 Agent 而言，推荐的工作姿势是：project new落盘工程 JSON → 每次操作都带-p（触发自动保存）→ 状态查询加--json→ 最终export render --overwrite产出成品。技能文档还提供一个完整示例（Illustration 工程），逐条命令如下：

# 1. Create project cli-anything-krita --json project new -n "Illustration" -w 3000 -h 4000 -o art.json # 2. Set up layer stack cli-anything-krita --json -p art.json layer add "Background" -t paintlayer cli-anything-krita --json -p art.json layer add "Sketch" -t paintlayer --opacity 180 cli-anything-krita --json -p art.json layer add "Inking" -t paintlayer cli-anything-krita --json -p art.json layer add "Colors" -t paintlayer cli-anything-krita --json -p art.json layer add "Effects" -t paintlayer --opacity 128 # 3. Apply effects cli-anything-krita --json -p art.json filter apply blur -l "Background" # 4. Export cli-anything-krita --json -p art.json export render final.png -p png --overwrite

这条流水线演示了典型漫画插画结构：Background / Sketch / Inking / Colors / Effects 五层，通过不透明度（180、128）区分草稿与特效层，局部对 Background 做模糊，最后以 PNG 导出。如需保存中间检查点，可把最终-p art.json路径换成多个版本文件，从而实现"分支式"绘画实验。

进阶：REPL 交互与会话可扩展性

除了一次性命令，无参数运行会进入交互式 REPL（依赖prompt-toolkit，缺失时会提示安装命令），在提示符中可以直接输入project new ...、layer add ...等命令并实时看到执行结果，支持help与quit/exit（命令速查表见 krita_cli.py）。它本质是把命令行参数重新分发给 Click 子命令，因此 REPL 与 one-shot 行为一致。

如果需要更细粒度的控制，Session.save()/load()支持把完整快照历史持久化到磁盘（session.py），可以按需扩展为断点续传式的长会话。此外仓库自带的测试（tests/test_core.py、tests/test_full_e2e.py）可作为命令行为与端到端导出链路的可运行参考。

总结

cli-anything-krita把 Krita 的绘画工作流压缩为一套确定性命令：project负责工程生命周期、layer编排图层、filter声明效果、canvas调整画布、export借助真实 Krita 引擎完成高质量渲染、session提供可回滚的历史。配合全局--json、--project（自动保存）与--dry-run，它既能支撑脚本化的批量图像处理，也能成为 AI Agent 操作 Krita 的稳定工具面。想要深入底层，建议继续阅读 krita_cli.py（命令注册）、project.py（状态与校验）、export.py（.kra 构建与导出）以及 krita_backend.py（Krita 进程调用）四个文件，即可完全掌握其设计全貌。

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