pp-home-assistant

Home Assistant — Printing Press CLI

前置条件：安装 CLI

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

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

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

2. 验证：home-assistant-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/home-assistant/cmd/home-assistant-pp-cli@latest

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

本 CLI 提供与 hass-cli 和 ha-mcp 同样广泛且实用的功能，并新增预览/应用/验证模式、常规调试、引用 lint 检查、健康热点和家庭例外检查。同一套 Go 类型化命令树适用于用户、脚本、Agent 和 MCP 客户端。

何时使用此 CLI

当 Agent 需要检查或控制 Home Assistant 家庭环境、调试例程、维护可自托管的安装，或回答涉及多个实体和历史记录的问题时，请使用此 CLI。如果更改必须经过预览、以机器可读的方式呈现并得到验证，而不是根据易读名称猜测，此 CLI 尤其有用。

不适用场景

请勿在以下情况下使用此 CLI：

• 请勿使用此 CLI 控制 Apple“家庭”应用，或控制未桥接到 Home Assistant 的 HomeKit 设备。
• 请勿使用此 CLI 绕过 Home Assistant 身份验证，或将私有实例直接暴露到公共互联网。
• 未检查试运行或计划输出前，请勿使用具有破坏性的注册表、恢复、重启或更新命令。
• 同步所需资源前，请勿使用仅限本地的复合命令。

独特功能

这些功能是此 API 的其他任何工具都不具备的。

安全地执行家庭操作

• mode run — 预览场景或脚本，运行它，并验证所有产生的实体状态。

  当 Agent 需要安全地更改多个家庭设备，而不是直接触发未经验证的场景或服务调用时，请使用此功能。

  home-assistant-pp-cli mode run movie-night --agent
  

了解家庭情况

• house check — 一次性查看打开的窗户、未上锁的门锁、未关的灯、低电量设备以及不可用的安全设备。

  当需要快速回答涉及多个实体域的家庭安全与舒适度问题时，请使用此功能。

  home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity
  

• house recap — 回顾近期的家庭活动、例程故障、人员在场状态变化、门窗开启情况以及设备不可用时长等客观事实。

  此功能可生成简明、基于证据且离线时仍有用的家庭摘要。

  home-assistant-pp-cli house recap --since 7d --agent
  

例程智能分析

• routine why — 根据跟踪记录、状态变化、日志簿条目和错误，还原自动化或脚本失败的原因。

  当 Agent 需要查明某个例程失败的证据，而不是转储难以理解的跟踪记录时，请使用此功能。

  home-assistant-pp-cli routine why automation.movie_night --agent
  

• routine lint — 查找缺失的实体、不可用的服务、已停用的依赖项、含义模糊的名称以及过时的例程引用。

  在更改配置或升级前，请使用此功能，以便在 Home Assistant 执行例程前发现可确定的故障。

  home-assistant-pp-cli routine lint --agent
  

• routine impact — 查看更改某个实体或例程会影响的所有自动化、脚本、场景、辅助项和服务目标。

  在重命名、停用或移除某项内容前，请使用此功能，以免影响依赖它的其他家庭例程。

  home-assistant-pp-cli routine impact light.living_room --agent
  

自托管维护

• health hotspots — 将反复出现的不可用、过时、电量低和断连实体按设备、房间、集成和无线网络归类。

  当多个实体症状可能源于同一台故障设备、集成、房间或无线网络时，使用此命令。

  home-assistant-pp-cli health hotspots --agent
  

• energy standby — 查找在明确指定的时段内持续耗电，且相关家庭状态显示无人活动的设备。

  使用此命令，将家庭能源历史记录整理成一份简短的待机耗电设备清单，以便采取行动。

  home-assistant-pp-cli energy standby --since 7d --agent
  

命令参考

calendars — 管理日历

• home-assistant-pp-cli calendars list — 列出日历
• home-assistant-pp-cli calendars list-events — 列出日历事件

components — 管理组件

• home-assistant-pp-cli components — 列出已加载的组件

config — 管理配置

• home-assistant-pp-cli config get-system-info — 获取 Home Assistant 配置和版本
• home-assistant-pp-cli config validate — 验证 Home Assistant 配置

error-log — 管理错误日志

• home-assistant-pp-cli error-log — 获取当前错误日志

events — 管理事件

• home-assistant-pp-cli events fire — 触发事件
• home-assistant-pp-cli events list — 列出事件类型

history — 管理历史记录

• home-assistant-pp-cli history <timestamp> — 获取指定时间范围内的实体历史记录

intent — 管理意图

• home-assistant-pp-cli intent — 处理 Assist 意图

logbook — 管理日志簿

• home-assistant-pp-cli logbook <timestamp> — 获取指定时间范围内的日志簿记录

services — 管理服务

• home-assistant-pp-cli services call — 调用 Home Assistant 服务
• home-assistant-pp-cli services list — 列出服务域和服务

states — 管理状态

• home-assistant-pp-cli states delete — 移除自定义实体状态
• home-assistant-pp-cli states get — 获取实体状态
• home-assistant-pp-cli states list — 列出当前实体状态
• home-assistant-pp-cli states set — 设置自定义实体的状态

template — 管理模板

• home-assistant-pp-cli template — 渲染 Home Assistant 模板

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接向 CLI 提问：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可靠匹配项，此时可改用 --help 或缩小查询范围。

使用示例

检查住宅

home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity

将全屋异常报告缩小到 Agent 判断下一步行动所需的字段。

预览电影之夜

home-assistant-pp-cli mode run movie-night --dry-run --agent

解析家庭模式并检查每项操作，而不更改任何设备。

说明例行任务失败的原因

home-assistant-pp-cli routine why automation.movie_night --agent

将相关跟踪记录、状态、日志簿和错误证据整合到一条事件时间线中。

检查维护热点

home-assistant-pp-cli health hotspots --agent

将反复出现的症状按最可能需要关注的设备、集成、区域或无线网络归类。

身份验证设置

将 HASS_SERVER 设置为 Home Assistant 实例的 URL，并将 HASS_TOKEN 设置为从 Home Assistant 个人资料创建的长期访问令牌。CLI 会将令牌作为承载凭据发送到 REST，并在 WebSocket 身份验证期间将其作为访问令牌发送；它不会打印或同步该令牌。

运行 home-assistant-pp-cli doctor 以验证设置。

Agent 模式

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

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

• 可筛选 — --select 保留部分字段。点分隔路径可深入嵌套结构；数组会逐元素遍历。在响应冗长的 API 中，这对于控制上下文大小至关重要：

  home-assistant-pp-cli calendars list --agent --select id,name,status
  

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

• 适合离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用它

• 非交互式 — 绝不会提示输入，每项输入都通过标志指定

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应信封

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

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

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

路径和状态

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

• 使用 --home <dir> 指定单次调用的目录，或设置 HOME_ASSISTANT_HOME=<dir>，将四种路径统一迁移到一个根目录下。

• 仅当某种特定路径需要单独设置时，才使用对应类型的环境变量：HOME_ASSISTANT_CONFIG_DIR、HOME_ASSISTANT_DATA_DIR、HOME_ASSISTANT_STATE_DIR、HOME_ASSISTANT_CACHE_DIR。

• 解析顺序为：对应类型的环境变量、--home、HOME_ASSISTANT_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。

• 运行 home-assistant-pp-cli doctor --fail-on warn，检查路径和凭据位置警告。对于需要解析后目录的 Agent，agent-context 会提供 schema v4 的 paths 区块。

• 对于 MCP，通过 MCP 主机配置传递路径迁移设置。MCP 二进制程序不会继承 CLI 标志：

  {
    "mcpServers": {
      "home-assistant": {
        "command": "home-assistant-pp-mcp",
        "env": {
          "HOME_ASSISTANT_HOME": "/srv/home-assistant"
        }
      }
    }
  }
  

集群优先级：继承的对应类型环境变量会覆盖该类型显式指定的 --home。使用 HOME_ASSISTANT_HOME 或对应类型的环境变量作为持久的集群配置手段；--home 仅用于单次调用。取消设置环境变量无法撤销路径迁移；清除 HOME_ASSISTANT_HOME 前，请手动移动文件，否则 doctor 将无法找到留在原根目录下的凭据。

自动学习

此 CLI 内置了自捕获学习循环。CLI 会自行记录：每次调用都会在本地记入日志；标志使用失败后经修正重试时，会自动生成 flag_alias 候选项；对没有操作手册的查询类别执行 teach 时，会根据会话日志自动合成 playbook_candidate。你只需进行判断：先执行 recall，再根据发现的候选项采取行动；teach 最终答案；观察到修正时执行 playbook amend。你无需手动记录失败。

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

对于新的用户问题，在执行 list/search/drill 命令之前，先运行：

home-assistant-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>", "home-assistant-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] 和 warnings：

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 `home-assistant-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.

Playbook 和 Notes 与各资源的处理路径相互独立。一次 recall 响应可能同时包含 Playbook 和 Results[] 命中项——两者都要使用：Playbook 会告诉你要执行哪种处理流程；资源命中项则会跳过特定步骤。默认跳过 mismatches；仅在调查冷启动异常时传入 --debug-mismatches。

候选项判断详情：learnings confirm <id> 会在将候选项写入之前打印其完整载荷——请检查打印的载荷是否与已验证的行为一致。learnings reject <id> 会将推导签名标记为已废弃，避免同一候选项再次出现。信封中只包含当前值得处理的少数候选项；home-assistant-pp-cli learnings candidates 会列出所有未处理项。

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

步骤 3：始终读取 warnings

• low_confidence：存在 confidence<2 的行。将其视为提示，而不是可跳过发现步骤的命中项。
• resource_not_in_store：本地存储中没有该学习记录指向的资源。匹配验证器无法对实体进行分类——请直接获取资源并重新评估。
• cross_alias_match（针对单条结果）：该行是在其他别名下记录的，并通过 entity_lookups 与当前查询的规范实体匹配（例如，“USA”的学习记录命中了“United States”的 recall）。请相信 resource_id。
• similar_shape_different_entity:<canonical>（顶层）：存在结构匹配但规范实体与当前查询不同的行。按冷启动处理；warning 会提供冲突规范实体作为提示，但该行不会提升为 Results。
• ambiguous_alias（顶层）：单个查询实体解析出了多个规范实体（例如，“Cards” → Arizona Cardinals + St. Louis Cardinals）。在确定资源之前，先根据上下文说明存在歧义。
• candidates_present（顶层）：信封中包含 candidates 部分。先按照步骤 2 中的候选项分支处理，再处理其他内容。
• lookup_refresh_available（顶层）：查询中的实体尚无 lookup 行，但同步数据可能提供该行。运行 home-assistant-pp-cli sync，以刷新实体查找数据。
• 顶层 no_learnings_for_query_family：表中没有达到 Jaccard 阈值的行。纯冷启动。

步骤 4：完成回答后始终执行 teach &

教学无条件执行。解决存储无法回答的查询后，在后台教学最终资源映射——不设调用次数阈值，也不判断这次学习是否“值得”。教学是整个循环的锚点：对于没有 playbook 的查询族，它会触发 playbook 合成；同一指涉对象的不同表述会归并到同一查询族，因此近似重复的教学不会导致存储碎片化。整理好面向用户的回答后、发送回答前，通过 shell 中的 & 执行它，让调用立即返回：

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

成功时不输出任何内容。错误只会写入解析后的状态目录中的 teach.log。教学时应选择最具体的资源——如果用户提出了宽泛问题，而你通过逐级检查父记录找到了具体答案，则应教学叶节点 id，而不是父节点。CLI 会在 recall 时使用预置的 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.
home-assistant-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).
home-assistant-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 一样，采用触发后即不等待结果的方式。

home-assistant-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。

衡量循环效果

home-assistant-pp-cli learnings stats 会根据本地 learn_events 表报告召回命中率、教学到复用率、操作手册解决率，以及候选项确认／拒绝次数。分母尚不存在时，相关比率为 null；所有数据都保留在此设备上。使用它来检查这个 CLI 的循环是否值得投入。

禁用学习

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

Agent 反馈

当你（或 Agent）发现这个 CLI 有不对劲的地方时，请记录下来：

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

条目会以 feedback.jsonl 的形式存储在解析后的数据目录中。除非设置了 HOME_ASSISTANT_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 HOME_ASSISTANT_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为是仅存储在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这部分会不断累积效果。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定目标，此外（或替代）标准输出，因此 Agent 无需手动通过管道传输即可路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入标准输出
file:<path>	以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回列出支持方案的结构化错误。Webhook 失败会返回非零状态，并在标准错误中记录 URL 和 HTTP 状态。

命名配置

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

home-assistant-pp-cli profile save briefing --json
home-assistant-pp-cli --profile briefing calendars list
home-assistant-pp-cli profile list --json
home-assistant-pp-cli profile show briefing
home-assistant-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add home-assistant-pp-mcp -- home-assistant-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   home-assistant-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，则查看子命令帮助：home-assistant-pp-cli <command> --help。