pp-bambu

Bambu Lab — Printing Press CLI

前提条件：安装 CLI

此技能依赖 bambu-pp-cli 二进制文件。**调用此技能中的任何命令之前，必须先确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install bambu --cli-only
   

2. 验证：bambu-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）。此方式会将程序安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/devices/bambu/cmd/bambu-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功之前，请勿继续执行技能命令。

供需要编写 Agent 或代码来监控 Bambu 打印，并向 Discord、Webhook 或其他自动化工具发布更新的用户使用。可通过常规本地访问获取实时 MQTT 状态、当前作业的精确 3MF 重量和预览、与服务商无关的开始/完成事件，以及本地历史记录；此 CLI 有意不支持 Developer Mode、LAN Only Mode、Bambu Cloud、打印机控制和打印农场管理。

何时使用此 CLI

当 Agent 或自动化需要获取有关 Bambu 打印的结构化本地信息时，请使用此 CLI，包括进度、预计完成时间、AMS/HMS 状态、精确的打印板元数据、模型预览，以及开始/完成事件负载。对于打印机控制、LAN Only Mode、Developer Mode、摄像头墙或打印农场管理，请使用 Bambuddy 或其他面向控制的项目。

不适用场景

请勿将此 CLI 用于：

• 打印机控制、打印任务分发、移动、加热、固件、摄像头控制或 AMS 写入。
• Developer Mode、LAN Only Mode、Bambu Cloud、远程中继或打印农场管理工作流。
• 切片、网格修复、浏览 MakerWorld 或管理耗材库存。
• 在标志、日志、工件、聊天消息或 MCP 调用中暴露本地访问码。

独特功能

其他适用于此 API 的工具均不具备这些功能。

利用历史记录改进实时决策

• job eta — 根据同一作业以往运行的误差模式，修正打印机的完成时间估计。

  当自动化或用户需要依据此打印机的历史表现来确定完成时间时使用此功能。

  bambu-pp-cli job eta --agent
  

• history failure-correlations — 对与作业失败关联度最高的打印机、耗材、打印板、固件、速度和温度情境进行排序。

  当需要对重复故障进行有证据支持的排查，而非只检查单个作业时使用此功能。

  bambu-pp-cli history failure-correlations --since 30d --agent
  

• job timeline — 按顺序重建一次打印的各个阶段、暂停、层数、温度恢复情况和错误。

  使用此功能可以说明一次打印在哪个阶段减速、暂停、恢复或失败。

  bambu-pp-cli job timeline --latest --agent
  

• job repeats — 比较同一打印板多次运行的耗时、暂停、材料、错误和结果。

  使用此功能判断重复打印是否稳定且可复现。

  bambu-pp-cli job repeats "Colored Accents" --agent
  

考虑材料情况进行操作

• ams runway — 估算当前活动的 AMS 托盘是否足以打印完当前打印板剩余部分；当托盘估算值或多材料映射不明确时，会明确标示结果未知。

  在让长时间打印无人看管运行，或决定哪个料卷需要处理之前使用此功能。

  bambu-pp-cli ams runway --agent
  

提升集成韧性

• printer field-diff — 比较所选时间范围内首次和最新持久化的脱敏 MQTT 架构，找出新增、移除或类型变更的字段。

  使用此功能检查本地持久化观测结果之间的结构性报告变化。

  bambu-pp-cli printer field-diff --since 7d --agent
  

命令参考

观察记录 — 从 LAN 状态和事件命令收集并在本地持久化、经过脱敏的打印机观察记录。

• bambu-pp-cli observations — 列出在本地持久化的打印机观察记录。

查找合适的命令

知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

bambu-pp-cli which "<capability in your own words>"

which 会将自然语言能力查询匹配到此 CLI 精选功能索引中最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有足够可靠的匹配项，此时请回退到 --help 或使用范围更窄的查询。

手写扩展

这些命令由规范作者声明，需要单独手写接线；生成器不会为它们生成 Cobra 注册代码。此处列出这些命令以便查找，并且有意将它们放在 ## Command Reference 之外，避免 verify-skill 的未知命令检查将其视为生成器管理的路径。

• bambu-pp-cli discover — 使用 SSDP 和序列号筛选，在专用 LAN 上发现 Bambu 打印机。
• bambu-pp-cli profile — 管理安全处理密钥的多打印机配置档案和环境优先级。
• bambu-pp-cli printer status — 获取最新的标准化 MQTT pushall 状态快照。
• bambu-pp-cli printer raw — 返回完整的脱敏 MQTT 报告，包括未知固件字段。
• bambu-pp-cli events watch — 以 NDJSON 格式输出与提供方无关的打印生命周期开始和终止事件负载。
• bambu-pp-cli events monitor — 监控一次打印，并自动保留其事件日志和预览资源。
• bambu-pp-cli printer watch — 流式输出标准化打印机快照和可在重启后安全恢复的生命周期转换。
• bambu-pp-cli printer temperatures — 显示热床、腔室、喷嘴和 AMS 的当前温度及目标温度。
• bambu-pp-cli printer fans — 显示可用的部件、辅助、腔室、热断路器和风道风扇状态。
• bambu-pp-cli printer capabilities — 显示与型号相关的灯光、速度、网络、舱门、存储、固件、喷嘴和工具功能。
• bambu-pp-cli ams status — 显示 AMS 单元、料盘、材料、颜色、RFID、湿度、温度和剩余量估算。
• bambu-pp-cli ams active — 根据 Bambu 料盘语义解析当前使用的 AMS 料盘或外置线轴。
• bambu-pp-cli ams services — 显示只读的 AMS 烘干和耗材备份服务状态。
• bambu-pp-cli printer health — 显示标准化 HMS 消息和打印错误及其历史记录。
• bambu-pp-cli job current — 显示当前作业 ID、构建板、进度、预计完成时间、层数、阶段、速度、文件和计时信息。
• bambu-pp-cli job objects — 显示当前作业中可打印和已跳过对象的标识。
• bambu-pp-cli job metadata — 通过 FTPS 读取与当前作业精确匹配的、有大小限制的 3MF 构建板、对象和材料元数据。
• bambu-pp-cli job thumbnail — 将经过验证的当前构建板预览图写入明确指定的输出路径。
• bambu-pp-cli printer services — 显示队列、上传、升级、摄像头和延时摄影的运行状态标志。
• bambu-pp-cli files list — 通过经过证书验证的隐式 FTPS 列出打印机文件。
• bambu-pp-cli files download — 将有大小限制的打印机文件下载到明确指定的安全本地路径。
• bambu-pp-cli history — 查询本地持久化的作业、结果、时长、状态转换和观测记录。
• bambu-pp-cli maintenance — 跟踪按使用量推算的维护到期状态、预测和完成记录。
• bambu-pp-cli analytics — 基于本地观测存储运行打印机和作业分析。
• bambu-pp-cli job eta — 预测经过校准的完成时间和历史误差范围。
• bambu-pp-cli ams runway — 估算当前构建板已装载耗材的余量或缺口。
• bambu-pp-cli job repeats — 比较同一可打印作业的持久化执行记录。
• bambu-pp-cli printer field-diff — 检测固件报告字段的新增、移除、类型变更和过时情况。
• bambu-pp-cli history failure-correlations — 关联失败作业与打印机、耗材、构建板、固件、速度和温度相关的上下文。
• bambu-pp-cli job timeline — 重建一次打印的阶段、暂停、层数、热恢复和错误记录。

操作指南

适合自动化的打印事件

bambu-pp-cli events monitor --agent

在开始打印前运行此命令。该命令会等待一次打印，流式输出其开始负载，其中包含可用的嵌入式 3MF 项目/配置文件标题、对象名称、重量和预览；在终止负载到达后退出，并将相同的 NDJSON 以及任何预览存储在带时间戳的私有数据目录中。匹配的终止负载会沿用已补充的身份信息，不会重复附带文件。job.name 优先采用嵌入式 3MF 项目标题，其次采用唯一可打印对象去掉扩展名后的名称；job.source_name 保留打印机标签，而 job.project_name、job.profile_name 和 job.objects 则保持为明确字段。打印机端的 3MF 不会传输本地 Bambu Studio 窗口文件名，因此无法通过 LAN MQTT/FTPS 恢复该名称。只有在其他程序要求指定位置时才使用 --output-dir。从显示屏启动的打印可能只提供打印机上存储的 G-code，因此不包含 3MF 元数据。

events watch 是更底层的基本命令，适用于自行管理生命周期和资源存储的长时间运行使用者。

对于需要在多个任务间持续监视的守护进程或机器人，务必为这个默认无限期运行的监视器设置明确的运行时限：

bambu-pp-cli events watch --agent --asset-dir <dir> --timeout 24h

当前打印的精简摘要

bambu-pp-cli printer status --agent --select state,job.name,job.percent,job.estimated_finish_at,job.current_layer,job.total_layers,ams_active

仅保留通知或 Agent 所需的字段。

检查耗材余量

bambu-pp-cli ams runway --agent

估算已装载的材料是否足以完成当前打印板。

说明最新的打印

bambu-pp-cli job timeline --latest --agent

重建各个阶段、暂停、层进度、温度恢复情况和错误。

查找反复出现的故障背景

bambu-pp-cli history failure-correlations --since 30d --agent

按打印机、耗材、打印板、固件、速度和温度背景对失败的任务分组。

身份验证设置

从打印机网络设置中获取 BAMBU_SERIAL 和 BAMBU_ACCESS_CODE 并进行设置。BAMBU_HOST 为可选项，因为设备发现会跟随 DHCP 变更；只有在多播 SSDP 无法跨越本地网络时才设置它。CLI 仅使用常规本地访问，会验证打印机 CA，并将对等证书 CN 与配置的序列号进行匹配。

运行 bambu-pp-cli doctor 验证设置。

Agent 模式

为任何命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 可保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于内容冗长的 API，此功能对于缩减上下文至关重要：

  bambu-pp-cli observations --agent --select id,name,status
  

• 可预览 — --dry-run 会显示请求，但不会发送

• 支持离线 — 同步/搜索命令可在本地 SQLite 存储可用时使用它

• 非交互式 — 不会提示输入，所有输入都通过标志提供

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在一个来源信息对象中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时来源还是本地来源。仅当 stdout 连接到终端，且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要输出到 stderr；管道/Agent 使用者和指定格式的运行会在 stdout 上获得纯 JSON。

路径与状态

Agent 应将 CLI 的路径解析器视为运行时契约的一部分：

• 使用 --home <dir> 指定单次调用的目录，或设置 BAMBU_HOME=<dir>，将四类路径都重定位到同一个根目录下。

• 仅当某类路径需要单独设置时，才使用对应类型的环境变量：BAMBU_CONFIG_DIR、BAMBU_DATA_DIR、BAMBU_STATE_DIR、BAMBU_CACHE_DIR。

• 解析顺序为对应类型的环境变量、--home、BAMBU_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），最后是平台默认值。

• config 包含 config.toml 和配置档案等设置。data 包含 credentials.toml、data.db、Cookie 和认证辅助文件。state 包含持久化查询、任务和 teach.log。cache 包含可重新生成的 HTTP/缓存文件。

• 存储的密钥位于 data 目录下的 credentials.toml 中。为保持兼容性，也会读取现有旧版 config.toml 中的密钥，并在首次写入认证信息时将其移出 config.toml。

• 运行 bambu-pp-cli doctor --fail-on warn，以显示路径和凭据位置警告。对于需要获取解析后目录的 Agent，agent-context 会提供 schema v4 的 paths 块。

• 对于 MCP，请通过 MCP 主机配置传递重定位设置。MCP 二进制文件不会继承 CLI 标志：

  {
    "mcpServers": {
      "bambu": {
        "command": "bambu-pp-mcp",
        "env": {
          "BAMBU_HOME": "/srv/bambu"
        }
      }
    }
  }
  

路径优先级：继承的对应类型环境变量会覆盖该类型的显式 --home。使用 BAMBU_HOME 或对应类型的环境变量进行持久化安装重定位，仅在单次调用时使用 --home。取消设置环境变量并不能撤销重定位；清除 BAMBU_HOME 前，请手动移动文件，否则 doctor 将无法找到留在原根目录下的凭据。

自动学习

此 CLI 内置了一个自动捕获的学习循环。CLI 会自行记录：每次调用都会在本地记入日志；先使用错误标志再更正重试时，会自动推导出一个 flag_alias 候选项；对于没有操作手册的查询类别，执行 teach 时会根据本次会话的日志自动合成一个 playbook_candidate。你只需进行判断：先运行 recall，处理呈现的候选项，用 teach 记录最终答案，并在发现需要更正时运行 playbook amend。你无需手动记录失败。

第 1 步：任何探索前先运行 recall

针对新的用户问题，在运行列表/搜索/深入查询命令前，先运行：

bambu-pp-cli recall "<user's question>" --agent

响应信封：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "bambu-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空存储时的提前退出：如果存储中尚无学习内容、操作手册或候选项（recall 无结果，且 learnings list 和 learnings candidates 都为空），本次会话的其余时间可跳过 recall，避免每次查询都增加负担；在记录新内容后，再恢复先运行 recall 的做法。

第 2 步：决策树

按以下顺序查看 candidates、playbook、notes、results[0] 和警告：

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `bambu-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

操作手册和 Notes 与逐资源路径相互独立。一次 recall 响应可以同时包含操作手册和 Results[] 命中项——两者都要使用：操作手册告诉你要执行哪种流程；资源命中项则可以省去特定步骤。默认跳过 mismatches；仅在调查冷启动时的意外情况时传入 --debug-mismatches。

候选项判断细节：learnings confirm <id> 会在生成候选项之前打印其完整内容——请检查打印的内容是否与已验证的行为一致。learnings reject <id> 会将推导签名标记为无效，避免同一候选项再次出现。信封只包含当前值得处理的少数候选项；bambu-pp-cli learnings candidates 会列出所有未处理的候选项。

平稳降级：如果 learnings confirm 是未知命令，说明你使用的是较旧的二进制文件——忽略候选项相关指引，并遵循协议的其余部分。

第 3 步：始终读取 warnings

• low_confidence：存在 confidence<2 的行。将其视为提示，而不是跳过发现的命中项。
• resource_not_in_store：本地存储中没有学习内容所指向的资源。匹配验证器无法对实体分类——直接获取资源并重新评估。
• cross_alias_match（每个结果）：该行是以不同别名学习的，并通过 entity_lookups 匹配了实时查询的规范实体（例如，学习“USA”后满足对“United States”的回忆请求）。信任 resource_id。
• similar_shape_different_entity:<canonical>（顶层）：存在结构匹配的行，但其规范实体与实时查询中的不同。按冷启动处理；警告会附带冲突的规范实体作为提示，但该行不会加入 Results。
• ambiguous_alias（顶层）：单个查询实体解析到了多个规范实体（例如，“Cards” → Arizona Cardinals + St. Louis Cardinals）。在选定资源之前，先根据上下文说明这种歧义。
• candidates_present（顶层）：该封装包含 candidates 部分。先按照第 2 步中的候选项分支处理，再做其他操作。
• lookup_refresh_available（顶层）：查询中的某个实体尚无查找行，但同步数据可能提供该行。运行 bambu-pp-cli sync 以刷新实体查找项。
• 顶层 no_learnings_for_query_family：表中没有超过 Jaccard 下限的行。纯粹的冷启动。

第 4 步：完成回复后执行 teach &——始终如此

学习操作无条件执行。在解决存储无法回答的查询后，在后台学习最终的资源映射——不设调用次数门槛，也不判断学习是否“值得”。学习操作是整个循环的锚点：如果某个类别尚无操作手册，它会触发操作手册合成；同一指代对象的不同表述会归入同一类别，因此近乎重复的学习不会导致存储碎片化。在整理好面向用户的回复后、发出回复前，使用 shell & 执行该操作，使调用立即返回：

bambu-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功时不输出任何内容。错误仅会写入已解析状态目录下的 teach.log。学习最具体的资源——如果用户提出了宽泛的问题，而你通过查看父记录找到了具体答案，就学习叶节点 ID，而不是父节点。CLI 会在回忆时使用预置的 entity_lookups 进行跨别名解析，因此以某个别名（例如，“Niners”）进行的学习会自动满足未来使用其他别名（例如，“49ers”、“San Francisco”）的查询。

PII 规则：学习结构化问题时必须剔除标识符——切勿在学习的查询或备注中包含姓名、电子邮件地址、电话号码、账户 ID 或其他个人标识符。CLI 会扫描学习查询中明显的电子邮件地址或电话号码格式并发出警告，但不会阻止；请在学习前剔除这些信息，而不要依赖警告。

步骤 5：playbook - 可选标记、自动合成

你不必判断某个会话是否“值得”编写 playbook：如果某个类别还没有 playbook，使用该类别进行 teach 会根据会话日志自动合成一个 playbook_candidate，并由下一次会话通过确认/拒绝来判断。只有当你已经掌握值得原样记录的操作流程时，才附加明确的 playbook 标记——例如 CLI 未显示的变通方法（被静默丢弃的标记、未记录的参数、分页技巧、负载问题）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和 playbook：

# Common case: record both the resource learning AND the playbook in one call.
bambu-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
bambu-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook 文件是包含 steps、entity_slots、expected_tool_calls 的 JSON 文件。Notes 文件是原样记录问题细节的 Markdown 文件。不使用文件的调用方（仅使用 MCP 的 Agent）可直接内联传入相同内容：在集成式 teach 形式中使用 --playbook-json 和 --playbook-notes，在 teach-playbook 中使用 --playbook-json 和 --notes。在集成式 teach 形式中，playbook 标记是可选的——如果只想 teach 资源，可完全省略这些标记。在独立的 teach-playbook 形式中，必须至少设置 playbook 标记和 notes 标记中的一个；两者都为空时会被拒绝。Playbook 以结构化查询类别（去除实体）为键，因此从一种实体形态的查询中学到的操作步骤适用于同一形态的所有其他查询，并在回忆时通过 slots_resolved 绑定当前查询的规范形式。

如果未来回忆时确实找到 playbook，请将其视为事实依据：使用 slots_resolved 替换项重放步骤，跳过操作流程中已有记录的探索，并在执行任何步骤前阅读 notes。

步骤 6：当调试响应指出需要更正时，使用 playbook amend &

如果你的调试协议响应指出 notes 或 playbook 应记录一项具体更正——例如变通方法、未记录的端点结构、过时的字段名称、观察到的架构漂移、空负载回退方案——请在生成面向用户的响应之前触发 playbook amend。与 teach 一样，采用触发后即不等待结果的方式。

bambu-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

哪些内容值得修订：本次会话中你 OBSERVED 到、且未来的你会受益于了解的行为。值得修订的示例：

• CLI 界面会静默丢弃或调整标记顺序时的变通方法。
• 未记录的端点结构（响应封装在 {meta, results} 中，负载嵌套层级比文档所述多两层）。
• 观察到的架构漂移（字段重命名、索引在不同赛季间发生变化、API 现在返回小写的类别标签）。

哪些内容不应写入 notes：

• 用户问题中与年份或实体相关的答案。这是响应内容，不是学习内容。
• playbook 已在运行时获取的团队、运动员或行数据。
• 只是转述现有 notes 内容的陈述。

amend 命令会将内容追加到该类别现有的 notes 中，并附加带时间戳的标记（[amend YYYY-MM-DDTHH:MMZ]: <text>）。多次 amend 会累积，且审计记录可见。如果该类别尚无 playbook，amend 会创建一个仅含 notes 的 playbook（因此冷启动时发现的更正也能记录下来）。

amend notes 中的 PII 规范

playbook amend notes 可能会在未来版本的 Printing Press 中作为共享知识向上游传递。请勿在其中包含可识别用户身份的内容，以便保持向上游贡献的渠道畅通，避免之后再进行清理：

• 请勿嵌入用户文件系统路径、个人 API 密钥或令牌、用户电子邮件地址、用户 GitHub 用户名，或与单个用户关联的特定查询历史记录。
• 可以包含：端点结构、未记录的字段名称、API 问题、观察到的架构漂移、CLI 界面的变通方法、可泛化的分页或重试策略。

如果某项更正只有结合用户特定的上下文才有意义，就应写入个人笔记，而不是 playbook amend。

衡量闭环

bambu-pp-cli learnings stats 会根据本地 learn_events 表报告召回命中率、教学复用率、操作手册解决率，以及候选项确认/拒绝次数。尚无分母时，相关比率为 null；所有数据都保留在本机。可用它检查此 CLI 的闭环是否发挥了应有作用。

禁用学习

• 在单条命令中使用 --no-learn，即可同时跳过 recall 和 teach 写入路径。适用于确定性 Agent 工作流，或不得受累积学习内容影响的测试。
• 在环境中设置 BAMBU_NO_LEARN=true，即可全局禁用此流程。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

bambu-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
bambu-pp-cli feedback --stdin < notes.txt
bambu-pp-cli feedback list --json --limit 10

条目会以 feedback.jsonl 的形式存储在解析后数据目录下。除非设置了 BAMBU_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 BAMBU_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认情况下，反馈只保存在本地。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这才是会不断累积的部分。

输出交付

每条命令都接受 --deliver <sink>。输出会发送到指定的接收端，并同时输出到 stdout，或取代 stdout 输出，以便 Agent 无需手动管道传输即可路由命令结果。支持三种接收端：

接收端	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（tmp + rename）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

遇到未知方案时，将返回结构化错误并列出支持的方案。Webhook 失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时运行或定期运行的 Agent 每次输入不同，但会重复使用同一组保存的标志，就可以使用配置。

bambu-pp-cli profile save briefing --json
bambu-pp-cli --profile briefing observations
bambu-pp-cli profile list --json
bambu-pp-cli profile show briefing
bambu-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，供进行自省的 Agent 在运行时发现。

打印机配置

单台打印机的常见设置使用 BAMBU_SERIAL 和 BAMBU_ACCESS_CODE。对于多台打印机，只需保存名称和环境变量引用，然后使用全局 --printer 选择器：

export OFFICE_BAMBU_SERIAL="<office-printer-serial>"
export OFFICE_BAMBU_ACCESS_CODE="<office-local-access-code>"
bambu-pp-cli profile printer-add --name office --serial-env OFFICE_BAMBU_SERIAL --access-code-env OFFICE_BAMBU_ACCESS_CODE
bambu-pp-cli profile printer-list --agent
bambu-pp-cli events monitor --printer office --agent
bambu-pp-cli profile printer-delete --name office

打印机配置不会保存序列号或访问代码。--printer 适用于实时命令、限定打印机的历史记录以及 observations；自由格式的 search 和 sql 则需要显式指定持久化的 printer_key 谓词。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求受限（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 bambu-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/devices/bambu/cmd/bambu-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add bambu-pp-mcp -- bambu-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which bambu-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
2. 根据上文的独特功能和命令参考，将用户查询匹配到最合适的命令。
3. 使用 --agent 标志执行：

   bambu-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：bambu-pp-cli <command> --help。