26 环境与 harness
✅ 已验证
本机
Fedora 44 · Krita 6.0.2.1（RPM）· PyQt6 · Xvfb · Python 3.14（numpy / scipy / scikit-learn / Pillow / matplotlib）· 46 GB 内存 · RTX 5070 Ti 16 GB（本书没用到 GPU）。
sudo dnf install krita python3-numpy python3-pillow python3-scipy python3-scikit-learn xorg-x11-server-Xvfb
装 RPM 不要装 Flatpak：Flatpak 的沙箱 Python 没有 numpy，路径还会被搬到 ~/.var/app/org.kde.krita/。
必须 Krita 6.0+。Node.paintLine / paintPath 是 6.0 新增的，是整套东西的地基。5.x 要走 tablet event 注入，每一条都要单独调试（坐标标定不可知、笔触只能落在第一层、saveAs 段错误、吞吐只有 200–600 笔/分）。本书代码不兼容 5.x。
harness：一个独立的 HOME
code/setup_fedora.sh <harness目录> <输出目录> 生成 krita-bot/：
krita-bot/
run_job.sh 启动脚本
.config/kritarc 最小配置: 关 autosave
.local/share/krita/pykrita/autopaint/ 一个 Krita 扩展: 启动 3s 后 exec $KRITA_JOB, 跑完退出
*.py code/ 的副本
用独立 HOME 的两个理由：批量作业的配置不污染你自己的 Krita 偏好；rm *autosave*.kra 删不到你真正的恢复文件。
run_job.sh 做的事：
export HOME=<harness> XDG_RUNTIME_DIR=/tmp/xdg-kritabot LANG=C.UTF-8 PYTHONIOENCODING=utf-8
export KRITA_JOB="$(realpath "$1")" # 所有路径在 cd 之前转绝对
cd "$HOME"; rm -f *autosave*.kra # 残留的 autosave 会弹恢复对话框, 卡死之后每一次
xvfb-run -a -s "-screen 0 1600x1200x24" krita --nosplash # 或 --gui 在真实桌面上看
改完 code/ 必须重跑 ./paint setup——harness 跑的是副本。setup_fedora.sh 先 rm -f 再 cp：只 cp 不删的话，改过名的旧模块会原地留下，漏改的 import 继续跑通而不报错。
四个环境级的坑
| 坑 | 症状 | 修 |
|---|---|---|
QT_QPA_PLATFORM=offscreen | Krita 6 启动即段错误 | 必须 Xvfb 或真实 display |
只设 LANG 不设 PYTHONIOENCODING | print("中文") 在作业跑到一半时抛 UnicodeEncodeError | 两个都设；读作业文件也要 encoding='utf-8' |
| 崩溃留下的 autosave | 之后每次运行无错误、无 traceback、持续失败 | 启动前 rm -f *autosave*.kra，EnableAutosave=false |
没有 view 时调 paint* | 段错误，C++ 层，无 Python traceback | Session.__init__ 已 addView；自己建文档必须也建 |
作业的骨架
import os, sys
sys.path.insert(0, os.path.expanduser("~")) # harness 就是 HOME, code/ 的副本在这
from canvas import *
s = Session(W, H, "作品名", journal=True) # document + view + 输出目录
... # 建树、落笔
s.stage("标签") # 存一张 stages/NN-标签.png
s.final() # final.png + final.kra + layers.json
Session 的输出根是 $ART_OUT，./paint 会设好。
自检
./paint check 跑 code/job_selfcheck.py，31 项，每项真跑一遍看像素：版本 ≥ 6 / ground / preset / stroke / path / ellipse / selection 限制与取消 / select_mask 羽化 / erase / filter box / blending / stage 与 final 落盘 / 目录布局 / build 建树 / 嵌套顺序 / GroupLayer 类型 / find 寻址 / by_role / by_label / 重名拒绝 / clipping / 局部 box 读写 / manifest / .kra 往返（层数、clip、blend/opacity/label）。
改了 canvas.py 之后必须全过。