---
name: krita-drawing
description: 使用本机 Krita 执行项目 Python 绘制程序，生成可编辑 .kra、检查保存重开结果并原位修改选定节点；也可用底层笔刷和图层工具执行明确操作。用于组件制作与源文件编辑；已有资产的页面排版使用 page-composition，ICON 模型生图使用 icon-assets。
---

# 在 Krita 中制作与修改项目组件

项目程序定义具体画法，通用工具负责计划校验、Krita 执行和证据记录。工具参数见[项目工具说明](../../docs/project-tools.md)；编写或修改程序时读[绘制程序约定](../../docs/drawing-programs.md)。参考分析与规则提取使用相邻的 [reference-style Skill](../reference-style/SKILL.md)，按当前项目的参考和需求确定画法。

任务只是把已有组件排成页面、移动实例或修改文案时，使用 [page-composition Skill](../page-composition/SKILL.md)。先查询可复用资产，不因需要一张完整页面而重绘基础 UI；只有外观或所需状态确实变化时，才进入本制作流程。

## 基础 UI 与 ICON 的制作边界

本 Skill 制作基础 UI 及其 ICON 容器、占位和留白；ICON 图像通过独立的宿主生图或图像编辑流程制作，共享适用风格依据，并在目标尺寸的静态 UI 组合中检查。不要为 ICON 图像强制编写 Krita 程序，也不要将整张 UI 生图作为可编辑组件的交付。生成位图不等同于可分层修改的 `.kra`。ICON 的生成、登记和组合工作流见[icon-assets Skill](../icon-assets/SKILL.md)。

SmartUI 不提供 ICON 生图后端，也不导入位图为 Krita 图层；项目可登记独立图像并创建固定坐标的静态组合预览。占位可作为组件规格中的布局约束，必要时绘制明确的占位标记；不因尚未生成 ICON 而伪造组件成功运行。已有明确资产引用缺失时应报错，不能静默换成占位。组合接口限制见[项目工具说明](../../docs/project-tools.md#独立图像资产与静态组合预览)。

## 项目制作

`project_root` 是业务工程根目录的绝对路径。创建时可通过 `paths` 局部指定工程内相对目录，默认文档为 `docs/ui`、参考为 `docs/ui/references`、程序为 `art/ui/programs`、源文件为 `art/ui/sources`。工程外参考登记时会复制入参考目录。状态中的工程内文件引用保存为工程相对 POSIX 路径。保留 `.smartui` 状态和制作记录，缓存、锁及临时文件按生成的忽略规则处理。需要导入数据目录时，按[数据导入与目录迁移](../../docs/project-tools.md#数据导入与目录迁移)先预检，再显式执行。

已有项目先读 `project_context`，需要修改程序时先 `project_get_program`。新项目先创建并登记参考。工具调用中的文件路径参数使用绝对路径，`paths` 目录配置及持久化引用使用工程内相对路径。每次写入用最新 revision；冲突后重新读取并核对差异，不自动覆盖。

用 `project_update_style` 保存共用规则与项目参数，`project_save_program` 保存完整 Python 源码，`project_define_component` 用必需的 `spec.program_id` 引用它。其余参数和规格字段由项目程序决定。按实际编辑需求组织图层、绘制步骤与笔刷。

制作换色和状态变体时，用共用参数定义颜色用途和状态差异，用组件规格选择主题、状态和尺寸。共用几何留在同一画法里，按当前需求逐项检查应制作的状态。程序应明确报出缺少的主题、状态或颜色用途引用。需要了解参数如何传给绘制程序时，可查看[颜色用途与状态示例](../../examples/drawing-programs/semantic_palette.py)，该示例使用合成数据演示接口。

保存只检查语法。用 `project_plan_component` 执行并检查返回计划，再用 `krita_status` 确认连接、`krita_list_brushes` 核对精确预设。缺少预设直接说明，不静默换成近似笔刷。程序是可信本机代码，独立进程和 60 秒超时不构成安全沙箱；程序应计算计划，不直接修改项目或 Krita 现场。

调用 `project_draw_component` 完成绘制、保存、导出、重开检查与记录。图层、分组和蒙版由程序计划决定。查看实际 PNG。需要验证参考复现时，用 `project_compare_component` 选择可比区域及显示倍率，查看对照拼图后再记录可观察的偏差与建议。

检查多份产物时，调用 `project_create_visual_check`，每项指定成功运行的 `component_id`、`run_id` 和 `label`。可用原图像素 `region` 裁切，按目标显示尺寸计算等比 `scale`，原尺寸用 1。提供 `#RRGGBB` 纯色背景，可同时查看独立灰度图。用图上序号与标签核对实际样片，需要恢复旧检查图时用 `project_get_visual_check`。检查图辅助比较组件，最终的页面视觉层次还要在目标场景中复查。

`.smartui/project.json` 是唯一结构化数据源，受管 Markdown 由工具生成。不要手改文档、文档摘要、程序文件或运行记录绕过校验。缺失或摘要不符时报告具体文件并保留差异。

## 原文件局部更新

先读取完整组件规格和程序，按用户反馈调整必要内容，生成计划。`project_draw_component(..., layers=[节点key])` 可选择绘画图层、分组或透明度蒙版；工具比较上次实际计划，拒绝选定范围外变化。局部更新不限制特定参数名或高光角色。

选择分组只更新分组自身属性，不隐式更新子树；需要修改子节点时逐一列出它们的 key。局部更新必须有已登记的 `plan.json` 及其摘要，供工具校验和比较。

针对已有反馈，先读对照和反馈详情，结合其中的节点 key 与规则 ID 确定修改范围。绘制成功后，用新运行和同一参考区域生成新对照。查看拼图后用 `project_update_feedback` 记录复查结论。技术 `verified` 只表示保存重开检查通过，关闭偏差需要新的对照证据。

完整重画也要求现有画布、图层结构和记录匹配；新尺寸或新结构暂用新组件 ID。规则、共用参数或源码变化后，依赖组件需要重新检查，旧记录仍保留实际执行版本。不能修改版本号冒充已重画，也不要把单个组件反馈擅自升级为全项目规则。

## 底层操作、失败与交付

底层参数按需读[接口约定](../../docs/bridge-contract.md)。已有文档先确认是否打开，已打开直接检查，未打开才 document.open。优先用 UUID 定位，名称唯一时才用 name:名称。路径/椭圆填色如实记录为几何填色，当前接口不保留完整自由手绘的逐点压力、倾角和时间。

批量操作不是事务，失败项可能部分生效；超时不自动重发。先检查请求 ID、结果文件和文档。运行失败保留旧成功历史，但旧记录不能证明当前磁盘文件有效；资产生成后状态提交冲突时，说明产物已保存而项目记录未更新。

展示实际预览和可编辑 .kra 路径，交代实际风格版本、程序版本、技术检查和仍需视觉修正的内容。工具不会代填用户确认，模型评价也不能冒充用户确认。