pp-seats-aero

Seats.aero — Printing Press CLI

前提条件：安装 CLI

此技能通过 seats-aero-pp-cli 二进制文件运行。**在调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

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

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

2. 验证：seats-aero-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/travel/seats-aero/cmd/seats-aero-pp-cli@latest

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

seats-aero-pp-cli 封装了全部七个 Partner API 端点（缓存搜索、批量可用性、行程、航线、目的地、刷新、实时查询），并提供适用于 Agent 的输出，随后将航线和可用性同步到类型化 SQLite 表中。本地存储支持 new-since、calendar、direct-scan、reach 和受配额保护的 recheck；轻量封装或 Web 应用都无法实现这些功能。

何时使用此 CLI

只要 Agent 需要按里程计划查询奖励航班可用性，就使用 seats-aero-pp-cli：例如查询某条航线上的最低里程奖励、某个计划的日历、从某机场出发可直飞到达的范围，或在预订前核实缓存的座位。它适用于里程与积分兑换研究，也适用于构建可离线查询的本地奖励航班可用性数据集。

不适用场景

请勿在以下场景使用此 CLI：

• 请勿用它预订或出票；它仅报告可用性，绝不会代为预订。
• 请勿用它查询现金票价、酒店奖励、积分估值或转点合作伙伴计算；Partner API 不提供这些数据。
• 请勿用它设置推送提醒；Seats.aero 提醒是 Web 应用功能，请改为定期使用 new-since。
• 不要期待使用 Pro 密钥进行实时搜索；该端点仅适用于商业协议。

独特功能

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

持续积累的本地状态

• new-since — 根据已同步的本地数据，查看自上次查询以来某条航线新增了哪些奖励座位。

  当用户询问某条航线有哪些变化或新增座位时，使用此功能，而不是重新搜索全部结果并手动比较。

  seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent
  

• direct-scan — 在所有已同步的计划中，一次性查找低于指定里程上限的直飞奖励座位。

  当用户需要跨计划查询已同步数据中的仅限直飞结果，且不想调用 API 时，优先使用此功能，而非奖励搜索。

  seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent
  

• calendar — 将某条航线已同步的可用性转换为按日期和客舱分类的矩阵，方便快速浏览。

  当用户询问某条航线哪些日期有商务舱或头等舱可用时，使用此功能；它只需一次查询本地存储即可作答。

  seats-aero-pp-cli calendar --origin JFK --destination NRT --source united --start 2026-10-01 --end 2026-12-31 --agent
  

配额感知流程

• recheck — 在预订前，重新验证即将过期的奖项行是否仍然有效。每次运行会执行一次实时配额探测（每天调用 1 次）；除非传入 --ignore-quota，否则在配额未知时会拒绝 --apply。

  默认仅打印：列出将要刷新的即将过期行、其存续时间以及剩余每日配额（一次探测调用）。添加 --apply 可消耗刷新额度；除非传入 --ignore-quota，否则在配额未知时会拒绝 --apply。

  seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent
  

• reach — 探索从某个机场出发，里程可直达的目的地，按成本排序，并与实际日期的座位信息交叉核验。

  当用户持有里程但没有固定目的地时，使用此功能。它没有本地模式，且 results 是一个对象 {origin, cabin, max_mileage, source, destinations[]}，而非简单数组。--confirm-live 会额外进行最多 10 次实时 /search 调用（需主动选择；测试框架下绝不调用）。

  seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent
  

命令参考

从 2026.8.1 升级

seats-aero-partner-search 已重命名为 awards；旧命令仍作为隐藏的弃用别名保留一个版本。其 --cabin 标志现为 --cabins，并接受逗号分隔的值。现有存储会在首次读写命令（例如 sync）时迁移；doctor 为只读命令，会报告 migration_pending，但不会更改存储。

凭据环境变量现为 SEATS_AERO_API_KEY。仍支持 SEATS_AERO_PARTNER_PARTNER_AUTHORIZATION 和 TOML 键 aero_partner_partner_authorization；doctor 会报告所选的 credentials_location。

存储会在首次读写命令（sync 或 doctor）时原地迁移，而旧版 seats_aero_partner_search 表保持不变。sync --concurrency 现在默认为 1（原为 4），--timeout 现在默认为 1m（原为 30s）。MCP 工具现为 awards_cached-search。

availability — 管理可用性

• seats-aero-pp-cli availability — 从一个特定里程计划中检索大量可用性对象。

awards — 管理奖项

• seats-aero-pp-cli awards — 搜索 Seats.aero 缓存的奖项可用性，涵盖一个或多个出发机场和目的地机场，以及一个或多个里程计划。

destinations — 管理目的地

• seats-aero-pp-cli destinations — 返回从（或到）单个机场可抵达的机场

live — 管理实时查询

• seats-aero-pp-cli live — 仅限具有商业协议的 API 密钥；Pro 密钥会收到 403——请勿重试。延迟为 5-15 s。

refresh — 管理刷新

• seats-aero-pp-cli refresh — 使用此端点刷新旧缓存数据；按额度计费；响应中的配额块会显示剩余刷新次数；仅限 Pro 密钥。

reach — 探索里程上限内的直达目的地

• seats-aero-pp-cli reach — 没有本地模式，且 results 是一个对象 {origin, cabin, max_mileage, source, destinations[]}，而非简单数组。--confirm-live 会额外进行最多 10 次实时 /search 调用（需主动选择；测试框架下绝不调用）。

recheck — 在预订前重新验证即将过期的奖项行

• seats-aero-pp-cli recheck — 默认仅打印；每次运行会执行一次实时配额探测（每天调用 1 次）。除非传入 --ignore-quota，否则在配额未知时会拒绝 --apply。

routes — 管理航线

• seats-aero-pp-cli routes — 获取某个里程计划所追踪的所有出发地-目的地航线。

trips — 管理行程

• seats-aero-pp-cli trips <id> — 根据搜索或可用性结果中的重新验证 ID／行程 ID，从 Availability 对象中检索航班级别的信息。

新鲜度契约

此打印版 CLI 仅对已注册的、由存储支持的读取命令路径负责有限的新鲜度保证。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有限刷新。--data-source local 不会刷新。--data-source live 会读取 API，且不会修改本地存储。设置 SEATS_AERO_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，而不改变数据源选择。

sync 和 sync --resources availability 无法填充 availability，因为该端点需要 source。请为每个计划运行一次 seats-aero-pp-cli sync --resources availability --resource-param availability:source=<program> --since 7d。routes 资源不需要参数。

覆盖的路径：

• seats-aero-pp-cli availability
• seats-aero-pp-cli availability get
• seats-aero-pp-cli availability list
• seats-aero-pp-cli availability search
• seats-aero-pp-cli awards
• seats-aero-pp-cli awards get
• seats-aero-pp-cli awards list
• seats-aero-pp-cli awards search
• seats-aero-pp-cli destinations
• seats-aero-pp-cli destinations get
• seats-aero-pp-cli destinations list
• seats-aero-pp-cli destinations search
• seats-aero-pp-cli routes
• seats-aero-pp-cli routes get
• seats-aero-pp-cli routes list
• seats-aero-pp-cli routes search

当 JSON 输出使用生成的来源信息封装结构时，新鲜度元数据位于 meta.freshness。应将其视为该命令路径的当前缓存新鲜度，而不是完整历史回填或 API 专属增强的保证。

查找合适的命令

当你知道要做什么，却不知道该用哪个命令时，可以直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中解析出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有足够可靠的匹配项——请改用 --help，或使用更具体的查询。--json（以及其他机器可读格式）会保留此退出代码为 2 的约定，并在标准输出中写入 {"matches":[]}，这样 Agent 可以检查封装结构，而不会将未匹配误认为成功。

使用示例

在所有计划中查找最便宜的商务舱奖励票，并为 Agent 精简结果

seats-aero-pp-cli awards --origin-airport SFO --destination-airport NRT --cabins business --order-by lowest_mileage --take 10 --agent --select data.Date,data.Route.Source,data.JMileageCost,data.JDirect

一次缓存搜索即可覆盖所有计划，并通过 --select 将宽泛的 availability 行精简为最重要的四个字段。

昨天以来新增了什么

seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent

根据 first_seen_at 对本地 availability 表进行差异比较，因此只返回真正新增的行。

预订前进行验证，无需消耗额度

seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent

默认仅打印：列出需要刷新的过期行、其过期时长以及每日剩余额度（一次探测调用）。添加 --apply 即可消耗刷新额度。

三个计划中，里程数低于 90k 且仅限直飞

seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent

对已同步数据进行跨计划联接，这是每次调用仅支持一个计划的批量端点无法回答的问题。

90k 里程可以直飞到哪里

seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent

先查询 destinations，再通过指定日期的座位信息确认每个候选目的地。reach 没有本地模式，且 results 是一个对象 {origin, cabin, max_mileage, source, destinations[]}，而不是单纯的数组。--confirm-live 最多会额外发起 10 次实时 /search 调用（需显式启用；测试框架下绝不会执行）。

身份验证设置

Seats.aero Pro 订阅者可在 Settings 下创建 Partner API 密钥，然后将其导出为 SEATS_AERO_API_KEY。密钥分为 Pro 级（每天 1,000 次调用，在 UTC 午夜重置；X-RateLimit-Remaining 标头会显示剩余额度）和商业协议密钥。Pro 密钥不能调用实时搜索，商业密钥不能调用刷新；doctor 会报告每日剩余调用次数，以及密钥所属的可能级别。

运行 seats-aero-pp-cli doctor 验证设置。

Agent 模式

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

全局格式标志在 promoted、novel、sync 和 --deliver 路径中遵循同一套约定：

• --json — 在 stdout 输出一个 JSON 文档（sync 进度事件输出到 stderr）

• --compact — 保留身份／状态／时间戳字段；不会改变文档与流的形态

• --csv / --plain — 输出表格行（集合封装会解包为行数组）

• --quiet — 每行输出一个身份值，不带封装

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

• 可筛选 — --select 保留指定字段子集。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，这对缩减上下文至关重要：

  seats-aero-pp-cli destinations --agent --select airport,business,economy
  

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

• 支持离线使用 — sync/search 命令在本地 SQLite 存储可用时可以使用它

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

• 明确确认 — --agent 不代表 --yes；只有在明确目标、参数和副作用后，才单独传入 --yes

• 明确重试 — 仅当已存在的创建结果应视为成功时，才使用 --idempotent

响应封装

从本地存储或 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> 设置单次调用的路径，或设置 SEATS_AERO_HOME=<dir>，将所有四类路径迁移到同一根目录下。

• 仅当某一特定类型需要使用不同路径时，才使用对应类型的环境变量：SEATS_AERO_CONFIG_DIR、SEATS_AERO_DATA_DIR、SEATS_AERO_STATE_DIR、SEATS_AERO_CACHE_DIR。

• 解析优先级依次为对应类型的环境变量、--home、SEATS_AERO_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），最后是平台默认路径。

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

• 存储的密钥位于 data 目录下的 credentials.toml 中。为兼容性，仍会读取旧版 config.toml 中的密钥；首次写入认证信息时，会将这些密钥移出 config.toml。

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

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

  {
    "mcpServers": {
      "seats-aero": {
        "command": "seats-aero-pp-mcp",
        "env": {
          "SEATS_AERO_HOME": "/srv/seats-aero"
        }
      }
    }
  }
  

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

自动学习

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

步骤 1：在任何发现操作前运行 recall

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

seats-aero-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>", "seats-aero-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 `seats-aero-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.

操作手册和笔记与各资源的处理路径相互独立。recall 响应可以同时包含操作手册和 Results[] 命中项——两者都要使用：操作手册会告诉你要执行哪套流程；资源命中项则可以跳过特定步骤。默认跳过 mismatches；只有在调查冷启动异常时才传入 --debug-mismatches。

候选项的判定细节：learnings confirm <id> 会在将候选项写入前打印其完整负载——请检查打印出的负载是否与已验证的行为一致。learnings reject <id> 会将推导签名标记为墓碑，从而避免同一候选项再次出现。封装中只包含当前值得处理的少数候选项；seats-aero-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 行，但同步数据可能提供该行。运行 seats-aero-pp-cli sync 以刷新实体查找数据。
• 顶层 no_learnings_for_query_family：表中没有高于 Jaccard 阈值的行。属于纯冷启动。

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

教学是无条件的。解决查询后，如果知识库无法回答，就在后台教学最终资源映射——没有调用次数门槛，也不判断是否「值得」学习。教学是整个循环的锚点：对于尚无操作手册的类别，它会触发操作手册合成；指向同一对象的不同说法会归入同一类别，因此相近的重复教学不会让知识库变得零散。组装好面向用户的回复后、发出回复前，使用 shell & 执行教学，让调用立即返回：

seats-aero-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_candidate，由下一次会话通过确认/拒绝来判定。只有在你已经掌握值得原样记录的操作流程时，才附加明确的操作手册标志——例如 CLI 未显示的变通方法（静默丢弃的标志、未记录的参数、分页技巧、有效载荷注意事项）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和操作手册：

# Common case: record both the resource learning AND the playbook in one call.
seats-aero-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).
seats-aero-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

操作手册文件是包含 steps、entity_slots、expected_tool_calls 的 JSON 文件。备注文件是以 Markdown 编写的文件，其中逐字记录注意事项。不能使用文件的调用方（仅使用 MCP 的 Agent）可内联传入相同内容：在集成式 teach 形式中使用 --playbook-json 和 --playbook-notes，在 teach-playbook 中使用 --playbook-json 和 --notes。在集成式 teach 形式中，操作手册标志是可选的——如果只教学资源，则完全省略这些标志。在独立的 teach-playbook 形式中，必须至少设置操作手册标志或备注标志中的一个；两者都为空时会被拒绝。操作手册按结构性查询类别（剔除实体后）建立索引，因此，从一个具有实体结构的查询中教学得到的流程适用于所有形状相同的其他查询，并由 slots_resolved 在回忆时绑定当前查询的规范形式。

以后回忆时如果确实找到操作手册，就将其视为事实依据：使用 slots_resolved 替换相应内容后重放步骤，跳过操作流程已有说明的探索过程，并在执行任何步骤前阅读 notes。

步骤 6：当调试响应指出需要修正时，执行 playbook amend &

如果你的调试协议响应指出了一项笔记或 playbook 应当了解的具体修正——例如一种变通方法、未记录的端点结构、过时的字段名、观察到的架构漂移或空载荷回退方案——请在输出面向用户的响应之前执行 playbook amend。这与 teach 一样，采用即发即忘的方式。

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

哪些内容值得修订：本次会话中你观察到、未来的自己会从中受益的行为。值得修订的示例：

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

哪些内容不应写入笔记：

• 用户问题中与年份或实体相关的答案。这是响应，不是经验。
• playbook 已在运行时检索的团队、运动员或行数据。
• 对现有笔记内容的转述。

amend 命令会将带时间戳标记的内容（[amend YYYY-MM-DDTHH:MMZ]: <text>）追加到该系列现有笔记中。多次修订会累积，并保留可见的审计记录。如果该系列还没有 playbook，amend 会创建一个仅含笔记的 playbook（因此冷启动时的修正也能记录下来）。

amend 笔记中的 PII 规范

playbook amend 笔记可能会在未来版本的 Printing Press 中作为共享知识流向上游。请勿在其中写入可识别用户身份的内容，以便在无需事后清理的情况下，继续保持上游贡献渠道畅通：

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

如果某项修正只有结合用户特定的上下文才有意义，请将其记入个人笔记，而非 playbook amend。

衡量学习循环

seats-aero-pp-cli learnings stats 会根据本地 learn_events 表报告召回命中率、教授后复用率、playbook 解析率，以及候选项确认／拒绝计数。尚无分母时，相关比率为 null；所有数据都保留在本机。可用它检查此 CLI 的学习循环是否发挥了应有作用。

禁用学习

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

Agent 反馈

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

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

条目会以 feedback.jsonl 的形式存储在解析后的数据目录中。只有在设置了 SEATS_AERO_FEEDBACK_ENDPOINT，且传入 --send 或设置了 SEATS_AERO_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认仅保存在本地。

记录让你感到意外的地方，而不是撰写错误报告。简短、具体，一行即可：真正有价值的内容会由此不断累积。

输出交付

每个命令都接受 --deliver <sink>。除了标准输出之外（或替代标准输出），输出还会发送到指定的接收目标，以便 Agent 无需手动管道传输即可路由命令结果。支持三种接收目标：

doctor、agent-context、learnings 和 feedback 的输出可能包含本地路径或自由文本，不应发送到第三方 Webhook。

接收目标	效果
stdout	默认值；仅写入标准输出
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）。二进制响应命令会写入解码后的负载字节（而非 base64 JSON 信封），并在标准输出上打印简短的 JSON 回执；设置此接收目标时，--json/--csv 不会被拒绝。
webhook:<url>	将输出正文 POST 到该 URL（application/json）

对于未知协议，会拒绝请求并返回结构化错误，其中会列出受支持的协议。Webhook 请求失败时会返回非零状态，并在标准错误上记录 URL + HTTP 状态码。

命名配置

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

seats-aero-pp-cli profile save briefing --json
seats-aero-pp-cli --profile briefing destinations
seats-aero-pp-cli profile list --json
seats-aero-pp-cli profile show briefing
seats-aero-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/travel/seats-aero/cmd/seats-aero-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add seats-aero-pp-mcp -- seats-aero-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   seats-aero-pp-cli <command> [subcommand] [args] --agent
   

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