klipper-manager

技能：klipper-manager

Klipper Manager — 全面的 AI 驱动打印机配置与诊断

通过 Moonraker API 管理任何 Klipper 打印机：读取和编辑 printer.cfg、运行诊断、执行校准序列、监控实时状态，并在充分了解配置的基础上修复问题。

---

激活条件

当用户要求：

• 连接或管理 Klipper 打印机
• 读取、更改或修复任何 printer.cfg 设置
• 诊断 Klipper 错误或警告
• 运行校准（床面网格、探针、PID、共振、压力提前、轴扭曲、螺丝等）
• 监控温度、位置或打印状态
• 发送 GCode 命令
• 重启固件或 Klipper

始终先读取 state/printer_context.json——如果该文件存在，向用户问候并概述已知打印机信息。如果文件不存在，或用户提供了新 IP，则运行阶段 1。

---

阶段 1：发现打印机

步骤 1 — 连接到 Moonraker

如果尚不知道打印机 IP，请向用户询问。然后验证连接：

curl -s "http://<IP>:7125/printer/info"

预期响应包含：state、hostname、software_version、config_file。

如果 state 不是 "ready"，请报告该状态，并让用户先解决问题再继续。

步骤 2 — 获取 printer.cfg

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

同时获取通过 [include ...] 引用的所有文件：

curl -s "http://<IP>:7125/server/files/config/<included_file>"

自动获取的常见包含文件：mainsail.cfg、macros/*.cfg、KAMP/*.cfg。

步骤 3 — 解析并清点配置

解析获取到的配置中的所有部分。提取并保存到 state/printer_context.json：

{
  "version": 1,
  "updated": "ISO-8601",
  "moonraker_url": "http://<IP>:7125",
  "klipper_version": "v0.13.x",
  "hostname": "mainsailos",
  "config_file": "/home/pi/printer_data/config/printer.cfg",

  "kinematics": "cartesian | corexy | corexz | delta | ...",
  "build_volume": {"x": 235, "y": 235, "z": 250},

  "steppers": {
    "stepper_x": {"position_max": 246, "position_min": 0, "rotation_distance": 40, "microsteps": 16},
    "stepper_y": {"position_max": 235, "position_min": 0},
    "stepper_z": {"position_max": 250, "position_min": -2}
  },

  "probe": {
    "type": "bltouch | probe | smart_effector | probe_eddy_current | none",
    "x_offset": -62,
    "y_offset": -12,
    "z_offset": 3.439
  },

  "bed_mesh": {
    "mesh_min": [60, 30],
    "mesh_max": [170, 220],
    "probe_count": [5, 5]
  },

  "axis_twist_compensation": {
    "calibrate_start_x": 20,
    "calibrate_end_x": 183,
    "calibrate_y": 117.5
  },

  "safe_z_home": {
    "home_xy_position": [108.5, 117.5]
  },

  "extruder": {
    "nozzle_diameter": 0.4,
    "rotation_distance": 7.687,
    "pressure_advance": null
  },

  "tmc_drivers": {
    "stepper_x": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_y": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_z": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0},
    "extruder": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0}
  },

  "input_shaper": {
    "x": {"type": "3hump_ei", "freq": 66.2},
    "y": {"type": "ei", "freq": 45.0}
  },

  "printer_limits": {
    "max_velocity": 300,
    "max_accel": 7000,
    "max_z_velocity": 15,
    "max_z_accel": 100
  },

  "installed_sections": [],
  "save_config_block": {},

  "known_issues": [],
  "last_diagnostic": null
}

步骤 4 — 运行自动诊断

解析完成后，始终运行完整诊断（参见阶段 3），并报告发现的任何问题。

步骤 5 — 显示摘要

向用户显示一张表格：

Printer    : mainsailos (Klipper v0.13.x)
Kinematics : Cartesian  |  Build: 246 × 235 × 250 mm
Probe      : BLTouch    |  x_offset: -62  y_offset: -12  z_offset: 3.439
Sections   : [printer] [extruder] [heater_bed] [bltouch] [bed_mesh] [axis_twist_compensation]
             [input_shaper] [firmware_retraction] [safe_z_home] [screws_tilt_adjust] ...
Issues     : (list any found by diagnostic, or "None detected")

---

阶段 2：配置管理

读取设置

要读取任何设置，请查阅已解析的 printer_context.json，或重新获取文件：

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

编辑设置

每次更改配置都必须遵循以下工作流：

1. 获取当前文件（绝不编辑过时的副本）
2. 进行针对性更改
3. 验证更改（参见阶段 3 的验证规则）
4. 保存到临时文件 C:/Users/<user>/Documents/printer_fix.cfg
5. 通过 Moonraker 上传：

   curl -s -X POST "http://<IP>:7125/server/files/upload" \
     -F "root=config" \
     -F "file=@C:/Users/<user>/Documents/printer_fix.cfg;filename=printer.cfg"
   

6. 重启固件以应用更改：

   curl -s -X POST "http://<IP>:7125/printer/firmware_restart"
   

7. 等待 5 秒，确认 state: ready：

   curl -s "http://<IP>:7125/printer/info"
   

8. 更新 state/printer_context.json
9. 清理临时文件

重要：绝不要手动编辑 SAVE_CONFIG 块。 只能使用 Klipper 的 SAVE_CONFIG 命令修改该块。上传修改后的配置时，除非明确要移除过时的校准数据，否则必须原样保留整个 #*# <--- SAVE_CONFIG ---> 块。

多个配置文件

如果打印机使用 [include] 部分，请列出所有配置文件：

curl -s "http://<IP>:7125/server/files/list?root=config"

获取并编辑正确的文件——如果目标部分位于包含文件中，请勿修改 printer.cfg。

---

阶段 3：诊断与验证

自动诊断检查清单

每次加载配置或进行任何更改后，都要运行此检查。检查所有规则：

1. 探针偏移边界

对于使用探针坐标的每个校准部分，考虑探针偏移后，喷嘴必须处于 [position_min, position_max] 范围内。

部分	坐标参数	喷嘴位置公式
[axis_twist_compensation]	calibrate_start_x、calibrate_end_x、calibrate_y	nozzle_x = coord_x - probe.x_offset；nozzle_y = coord_y - probe.y_offset
[bed_mesh]	mesh_min、mesh_max	nozzle_x = mesh_x - probe.x_offset；nozzle_y = mesh_y - probe.y_offset
[screws_tilt_adjust]	screw1..N (x,y)	nozzle_x = screw_x - probe.x_offset；nozzle_y = screw_y - probe.y_offset
[safe_z_home]	home_xy_position	这些是喷嘴坐标本身（无需减去偏移）
[delta_calibrate]	radius	考虑偏移后，探针必须落在距中心不超过半径的位置

对每个轴进行验证：

nozzle_x >= stepper_x.position_min  AND  nozzle_x <= stepper_x.position_max
nozzle_y >= stepper_y.position_min  AND  nozzle_y <= stepper_y.position_max

修复公式：

max_coord_x = stepper_x.position_max + probe.x_offset   (when x_offset is negative)
min_coord_x = stepper_x.position_min - probe.x_offset   (when x_offset is positive)

2. 热床网格边界

mesh_min 和 mesh_max 必须位于探针可达范围内：

mesh_min.x >= stepper_x.position_min - probe.x_offset
mesh_max.x <= stepper_x.position_max + probe.x_offset  (when x_offset < 0)
mesh_min.y >= stepper_y.position_min - probe.y_offset
mesh_max.y <= stepper_y.position_max + probe.y_offset  (when y_offset < 0)

3. 安全 Z 轴归位位置

home_xy_position 必须位于喷嘴可达范围内：

home_xy.x >= stepper_x.position_min AND home_xy.x <= stepper_x.position_max
home_xy.y >= stepper_y.position_min AND home_xy.y <= stepper_y.position_max

还要验证在归位位置时，探针位于热床上方（而不是悬在边缘外）。

4. SAVE_CONFIG / 校准一致性

更改配置后，检查 #*# SAVE_CONFIG 中保存的校准数据是否仍然有效：

• 如果 axis_twist_compensation 的边界发生变化 → 旧的 z_compensations / compensation_start_x / compensation_end_x 可能已过时 → 提醒用户重新运行 AXIS_TWIST_COMPENSATION_CALIBRATE
• 如果手动更改了 bltouch.z_offset 或 probe.z_offset → 提醒用户应重新运行 PROBE_CALIBRATE
• 如果 bed_mesh 的边界发生变化 → 现有网格配置文件可能超出边界 → 提醒用户重新运行 BED_MESH_CALIBRATE

5. TMC 驱动器警告

• 挤出机上设置了 stealthchop_threshold: 999999，且启用了压力提前 → 发出警告（扭矩会降低，但通常可以接受）
• 配置了 hold_current → 发出警告（可能导致振动，Klipper 文档建议省略此项）
• run_current > 电机额定电流 × 0.85 → 发出警告（有过热风险）
• 高精度要求下使用 interpolate: True → 提示位置偏差（16 个微步时约为 0.006mm）

6. 输入整形

• shaper_type: 3hump_ei 或 2hump_ei → 共振特征较复杂 → 建议检查皮带张力
• 没有 [input_shaper] 段 → 建议运行 SHAPER_CALIBRATE
• 整形器频率 < 20Hz → 可能是校准不正确或工具头非常重

7. 压力提前

• [extruder] 中未设置 pressure_advance（为 0 或未设置）→ 建议进行校准
• pressure_advance > 1.0 → 数值异常高，请检查 rotation_distance 和挤出机类型

8. 旋转距离合理性检查

挤出机：

• 直驱：rotation_distance 应为 4–10（BMG 类型通常为 7–8）
• Bowden：rotation_distance 应为 20–40

运动轴：

• GT2 皮带，20 齿皮带轮：rotation_distance = 40
• GT2 皮带，16 齿皮带轮：rotation_distance = 32
• T8 丝杆（螺距 2mm，4 线）：rotation_distance = 8
• T8 丝杆（螺距 2mm，1 线）：rotation_distance = 2

9. PID 调校

• control: watermark → 这是旧方法，建议进行 PID 校准
• 未设置 pid_Kp、pid_Ki、pid_Kd → 加热器没有 PID，运行可能不稳定

10. 缺少建议的配置段

将以下情况标记为警告（而非错误）：

• 没有 [exclude_object] → 无法取消单个对象的打印
• 没有 [firmware_retraction] → 无法在运行时调整回抽
• 没有 [gcode_arcs] → 无法使用圆弧支持
• 没有 [respond] → 宏反馈可能不会显示
• 没有 [pause_resume] → 暂停 / 取消打印可能无法使用

---

阶段 4：实时状态监控

查询打印机对象

Klipper 通过 Moonraker 的对象 API 提供实时状态：

# Query everything
curl -s "http://<IP>:7125/printer/objects/query?toolhead&extruder&heater_bed&bed_mesh&probe&print_stats"

# Query specific fields
curl -s "http://<IP>:7125/printer/objects/query?toolhead=position,max_velocity,max_accel&extruder=temperature,target,pressure_advance"

关键对象和字段：

对象	关键字段
toolhead	position、homed_axes、max_velocity、max_accel、stalls
extruder	temperature、target、pressure_advance、can_extrude
heater_bed	temperature、target、power
probe 或 bltouch	last_query、last_probe_position
bed_mesh	profile_name、mesh_min、mesh_max、probed_matrix
print_stats	state、filename、total_duration、filament_used
idle_timeout	state、printing_time
motion_report	live_position、live_velocity
firmware_retraction	retract_length、retract_speed
input_shaper	（从 configfile 查询）
tmc2209 stepper_x	run_current、hold_current、drv_status、temperature
configfile	save_config_pending、settings.<section>.<key>
webhooks	state、state_message
system_stats	sysload、cputime、memavail

发送 GCode

curl -s -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "QUERY_ENDSTOPS"}'

查询限位开关

curl -s "http://<IP>:7125/printer/query_endstops/status"

---

阶段 5：校准流程

探测器 Z 偏移校准（PROBE_CALIBRATE）

1. 确认打印机已归位：发送 G28
2. 开始校准：PROBE_CALIBRATE
3. 引导用户在喷嘴处进行纸张测试
4. 确认：TESTZ Z=-0.1（逐步调整）
5. 完成校准：ACCEPT
6. 保存：SAVE_CONFIG（会自动触发固件重启）

热床网格校准

1. 归位所有轴：G28
2. 可选：先将热床加热到打印温度
3. 运行：BED_MESH_CALIBRATE
4. 保存配置文件：BED_MESH_PROFILE SAVE=default
5. 保存到配置：SAVE_CONFIG

轴扭曲补偿

运行前，务必验证 calibrate_end_x：

max_safe_end_x = stepper_x.position_max + probe.x_offset

如果 calibrate_end_x > max_safe_end_x → 先修正（参见第 2 阶段编辑工作流）

然后：

1. 归位：G28
2. 运行：AXIS_TWIST_COMPENSATION_CALIBRATE
3. 按提示在每个探测点进行纸张测试
4. 保存：SAVE_CONFIG

PID 调校

热端：

PID_CALIBRATE HEATER=extruder TARGET=200
SAVE_CONFIG

热床：

PID_CALIBRATE HEATER=heater_bed TARGET=60
SAVE_CONFIG

压力提前

方法 1 — 调校塔（手动）：

SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500
TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005

打印调校塔模型。测量最佳层高。计算： PA = START + FACTOR × best_layer_height_mm

方法 2 — 找到数值后直接设置：

SET_PRESSURE_ADVANCE ADVANCE=0.04

然后将其添加到配置中的 [extruder]，并运行 SAVE_CONFIG。

共振 / 输入整形校准

1. 确认已配置 [adxl345] 或其他加速度计
2. 归位：G28
3. 测试加速度计：ACCELEROMETER_QUERY
4. 测量噪声基线：MEASURE_AXES_NOISE
5. 校准 X：SHAPER_CALIBRATE AXIS=X
6. 校准 Y：SHAPER_CALIBRATE AXIS=Y
7. 查看结果并应用推荐的整形器
8. SAVE_CONFIG

螺丝倾斜调整

1. 归位：G28
2. 运行：SCREWS_TILT_CALCULATE
3. 查看输出 — 每颗螺丝都会显示旋转方向（CW/CCW）和幅度（HH:MM）
4. 重复运行，直到所有螺丝的偏差都小于 0:05

TMC 驱动器诊断

转储驱动器状态：

DUMP_TMC STEPPER=stepper_x
DUMP_TMC STEPPER=stepper_y
DUMP_TMC STEPPER=stepper_z
DUMP_TMC STEPPER=extruder

在运行时调整电流（仅用于测试 — 要持久保存，请添加到配置中）：

SET_TMC_CURRENT STEPPER=stepper_x CURRENT=0.8 HOLDCURRENT=0.5

---

第 6 阶段：故障排除

完整的错误 → 原因 → 修复数据库请参阅 references/troubleshooting.md。

针对用户粘贴的任何错误消息的工作流：

1. 提取错误模式（错误类型，以及存在时的坐标/数值）
2. 与故障排除参考文档中的已知模式匹配
3. 从 printer_context.json 提取相关配置段
4. 使用验证公式计算具体的修复值
5. 提供诊断结果以及需要修改的准确行
6. 提供自动应用修复的选项（第 2 阶段编辑工作流）

常见错误模式（速查）：

错误	原因	修复
Move out of range: X Y Z [step]	喷嘴将超出轴限位；通常是校准坐标未考虑探测器偏移	将 calibrate_end_x / mesh_max 减小 abs(probe.x_offset)
Must home axis first	移动命令执行前轴尚未归位	运行 G28
Endstop stepper_x still triggered	限位开关卡住或接线故障	检查 QUERY_ENDSTOPS，检查限位开关引脚极性
Unable to read tmc uart ... IFCNT	TMC UART 通信故障	检查电机电源和 UART 接线；断电重启
TMC reports error: ... OvertempError	TMC 驱动器过热	降低 run_current，改善散热
TMC reports error: ShortToGND	电机线短路	检查电机接线
TMC reports error: Undervoltage	电源电压骤降	检查电源和接线
Heater extruder not heating at expected rate	需要进行 PID 调校，或加热器/传感器存在问题	运行 PID_CALIBRATE HEATER=extruder TARGET=200
Probe triggered prior to movement	BLTouch 状态错误或 z_offset 过高	运行 BLTOUCH_DEBUG COMMAND=reset，然后重新归位
Timeout on connect	Moonraker 未运行或 IP 错误	验证打印机 IP，并确认 Moonraker 正在运行
Lost communication with MCU	USB 连接断开或固件崩溃	运行 FIRMWARE_RESTART；检查 USB 线

---

第 7 阶段：配置段参考

完整的参数参考请参阅 references/config_sections.md。

关键配置段及其最常调整的参数：

[printer]

kinematics: cartesian          # cartesian|corexy|corexz|delta|deltesian|polar
max_velocity: 300              # mm/s — runtime tunable via SET_VELOCITY_LIMIT
max_accel: 7000                # mm/s² — runtime tunable
max_z_velocity: 15             # mm/s (cartesian only)
max_z_accel: 100               # mm/s² (cartesian only)
minimum_cruise_ratio: 0.5      # 0.0–1.0, reduces top speed of short moves
square_corner_velocity: 5.0    # mm/s, higher = less deceleration at corners

[stepper_x/y/z]

rotation_distance: 40          # mm per full motor rotation
microsteps: 16                 # 8|16|32|64|128
position_min: 0                # soft limit minimum
position_max: 246              # soft limit maximum — CRITICAL for range checks
position_endstop: 0            # endstop position (must match position_min or position_max)
homing_speed: 80               # mm/s

[extruder]

rotation_distance: 7.687       # mm per motor rotation (direct drive ~7-8, bowden ~20-40)
nozzle_diameter: 0.400
pressure_advance: 0.04         # 0 = disabled; typical range 0.02–0.12 for direct
pressure_advance_smooth_time: 0.04
max_extrude_cross_section: 5   # max mm² cross section (4 × nozzle_diameter² is safe default)

[bltouch] / [probe]

x_offset: -62                  # probe X position relative to nozzle (negative = left of nozzle)
y_offset: -12                  # probe Y position relative to nozzle (negative = in front)
# z_offset: stored in SAVE_CONFIG block
samples: 3                     # number of probe samples
samples_result: median         # average|median
sample_retract_dist: 5.0
samples_tolerance: 0.01        # max deviation between samples (mm)
samples_tolerance_retries: 3

[bed_mesh]

mesh_min: 60, 30               # PROBE coordinates (not nozzle!)
mesh_max: 170, 220             # PROBE coordinates
probe_count: 5, 5              # grid points per axis
algorithm: bicubic             # lagrange (≤3×3) | bicubic (≥4×4 recommended)
fade_start: 1                  # mm height to start fading mesh correction
fade_end: 10                   # mm height where mesh correction reaches zero (0=disabled)

[axis_twist_compensation]

calibrate_start_x: 20         # PROBE X coordinate — nozzle = start_x - x_offset
calibrate_end_x: 183          # PROBE X coordinate — nozzle = end_x - x_offset
calibrate_y: 117.5            # PROBE Y coordinate — nozzle = calibrate_y - y_offset
# Rule: nozzle must be within [position_min, position_max]
# Formula: calibrate_end_x <= position_max + x_offset  (when x_offset < 0)

[safe_z_home]

home_xy_position: 108.5, 117.5  # NOZZLE position for Z homing (not probe!)
speed: 120
z_hop: 10
z_hop_speed: 5

[tmc2209 stepper_x]

run_current: 0.750             # Amps RMS — start at 70% rated current
hold_current: 0.500            # Optional — Klipper docs recommend omitting
stealthchop_threshold: 999999  # 999999=always stealthChop; 0=always spreadCycle
interpolate: True              # micro-step interpolation (small positional error)
driver_SGTHRS: 255             # stallGuard threshold for sensorless homing (if used)

[input_shaper]

shaper_type_x: 3hump_ei        # mzv|ei|2hump_ei|3hump_ei|zv|zvd
shaper_freq_x: 66.2            # Hz — from SHAPER_CALIBRATE
shaper_type_y: ei
shaper_freq_y: 45.0

[firmware_retraction]

retract_length: 0.5            # mm — direct drive: 0.4–1.0; bowden: 4–7
retract_speed: 60              # mm/s
unretract_extra_length: 0
unretract_speed: 60

---

Moonraker API 快速参考

基础 URL：http://<IP>:7125

方法	端点	用途
GET	/printer/info	Klipper 状态、版本、主机名
GET	/server/files/config/printer.cfg	读取 printer.cfg
GET	/server/files/list?root=config	列出所有配置文件
POST	/server/files/upload (multipart)	上传/覆盖配置文件
POST	/printer/firmware_restart	固件重启（应用配置更改）
POST	/printer/gcode/script	发送 GCode 命令（JSON 请求体：{"script":"..."}）
GET	/printer/objects/list	列出所有可查询的打印机对象
GET	/printer/objects/query?<obj>=<fields>	查询打印机实时状态
GET	/printer/query_endstops/status	限位开关状态
POST	/printer/gcode/script {"script":"SAVE_CONFIG"}	保存校准数据
GET	/server/info	Moonraker 版本、已注册组件
POST	/machine/reboot	重启主机（Pi）
POST	/machine/shutdown	关闭主机

文件上传（curl）

curl -X POST "http://<IP>:7125/server/files/upload" \
  -F "root=config" \
  -F "file=@/path/to/printer.cfg;filename=printer.cfg"

发送 GCode（curl）

curl -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "G28"}'

对象查询（curl）

curl "http://<IP>:7125/printer/objects/query?extruder&heater_bed&toolhead"

---

平台说明

AI 会使用 curl（Windows 和 Linux 上均可用）以及直接文本分析，在行内完成所有配置获取、解析和编辑。scripts/ 中的脚本作为参考实现提供，可在 Linux/macOS 上运行（需要 python3）。在 Windows 上，AI 会直接执行等效逻辑——不要依赖 shell 脚本。

直接在 Klipper 主机上运行时（通过 SSH），这些脚本无需修改即可运行。

---

文件结构

klipper-manager/
├── SKILL.md                         # This file
├── references/
│   ├── config_sections.md           # Full parameter reference for all config sections
│   ├── gcodes.md                    # All supported G-codes and extended commands
│   ├── troubleshooting.md           # Error patterns → causes → fixes
│   └── moonraker_api.md             # Full Moonraker API reference
├── scripts/
│   ├── fetch_config.sh              # Fetch printer.cfg from Moonraker
│   ├── upload_config.sh             # Upload modified config
│   ├── send_gcode.sh                # Send a GCode command
│   ├── query_status.sh              # Query printer status objects
│   └── diagnose.sh                  # Full diagnostic run
└── state/
    └── printer_context.json         # Persisted printer state (auto-created)

基础目录：file:///C:/Users/santi/.config/opencode/skills/klipper-manager