pp-openrouter

OpenRouter — Printing Press 命令行工具

前提条件：安装 CLI

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

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

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

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

如果 npx 安装失败，且此 CLI 尚无公共库分类，请先安装 Node，或在发布后使用按分类提供的 Go 后备方案。

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

其他所有 OpenRouter 工具都只是封装了聊天功能；这个工具则负责管理它。通过同步的本地模型、生成记录和额度镜像，可按 cron 归因成本（usage cost-by）、执行飞行前预算检查（budget check）、监控服务商降级情况（providers degraded），并预测额度余量（credits runway）——这些问题都无法通过单次 API 调用解决。完整的端点功能集——目录、密钥管理、活动记录和分析——也以类型化命令的形式提供。

何时使用此 CLI

当任务涉及通过 OpenRouter 运行大模型工作负载时，请使用此 CLI：例如，将支出归因到 cron 或 Agent、根据预算限制定时运行、根据能力和价格筛选模型、在派发前监控服务商健康状况，或预测额度和上限的余量。只要问题需要结合本地历史记录和 API 信息，也就是单次原始 HTTP 调用无法回答的问题，就适合使用此工具。

不适用场景

以下情况请勿使用此 CLI：

• 交互式聊天会话或对话式试验场——请使用聊天客户端；这里的聊天命令用于 Agent 管理，不是用户界面
• 构建应用推理路径——请在应用中使用官方 OpenRouter SDK，而不是通过 shell 调用 CLI
• 组织成员管理、SCIM 配置或 SSO 设置——请使用 OpenRouter 控制台
• 实时 Token 流式显示——CLI 返回完整响应，不提供流式渲染器

独有功能

其他用于此 API 的工具均不具备以下功能。

目录智能

• models query — 基于同步的目录，通过结构化查询按能力、价格和上下文窗口筛选模型；离线执行，即时返回。

  相比获取完整目录，更适合使用此命令：它只需约 200 个 Token 就能回答筛选问题，而非数百 KB 的数据。

  openrouter-pp-cli models query "tools=true cost.completion<5 ctx>=128k" --agent
  

• models churn — 查看各次同步之间模型目录的变化：新增、移除和重新定价，并显示差值。

  使用此命令可在账单显示之前，发现固定使用的模型涨价或消失。

  openrouter-pp-cli models churn --since 7d --agent
  

Agent 集群成本治理

• usage cost-by — 按任意时间范围，将支出归因到产生费用的 cron、Agent 或血缘链路。

  当你想知道“哪个任务花了这笔钱”，而不是“哪个模型花了这笔钱”时，请使用此命令。

  openrouter-pp-cli usage cost-by --since 7d --agent
  

• usage anomaly — 根据过去的基线，标记各模型的成本激增，避免问题持续扩大。

  将此命令设为每日 cron，在血缘链路出现回退的当天就发现异常，而不是等到账单出来。

  openrouter-pp-cli usage anomaly --since 24h --agent
  

• budget — 为每个 cron 或 Agent 设置支出上限，并通过类型化退出码在飞行前强制执行。

  根据退出码 0/8 控制定时运行，确保超出预算的血缘链路不会启动。

  openrouter-pp-cli budget check nightly-drafter
  

• generation explain — 分解单次生成的成本构成：Token、延迟，以及与最便宜服务商相比的差值。

  异常触发后执行的下一条命令：它能将“成本激增”具体拆解为“这次调用、这家服务商、这个差值”。

  openrouter-pp-cli generation explain gen-abc123 --agent
  

• usage reconcile — 将本地用量镜像与上游每日总量核对，并标记数据不一致的日期。

  在信任任何本地成本分析之前，请先运行此命令——它是其他用量命令的信任根。

  openrouter-pp-cli usage reconcile --since 7d --agent
  

提供商健康状况与调度

• providers degraded — 在向提供商或模型调度任务前，查看当前哪些提供商或模型处于降级状态。

  调度前先检查此项，以便绕开问题，而不是在问题出现时反复重试。

  openrouter-pp-cli providers degraded --agent
  

• endpoints failover — 根据状态、价格和观测到的延迟，对为某个模型提供服务的提供商排序，以确定调度顺序。

  将此结果提供给路由器，以便为特定模型提前避开降级的提供商。

  openrouter-pp-cli endpoints failover deepseek/deepseek-v4 --agent
  

额度余量与速率限制余量

• key eta — 根据观测到的消耗速率，预测密钥的支出上限触发日期。

  用它规划本周在上限内的运行安排，而不是等运行过程中才发现达到上限。

  openrouter-pp-cli key eta --agent
  

• limits status — 一览当前余量：密钥上限剩余量、免费层每日配额，以及今日免费模型的消耗量。

  在免费层开发循环或调度集群任务前检查，以避免遇到原因不明的 429 错误。

  openrouter-pp-cli limits status --agent
  

• credits runway — 根据近期消耗速率，预测预付额度归零还剩多少天——这是 402 错误的前置信号。

  每天运行一次 cron 任务查询此项，就能在还有时间充值时回答“我们何时会遇到 402 错误”。

  openrouter-pp-cli credits runway --agent
  

命令参考

activity — 管理活动

• openrouter-pp-cli activity — 返回按端点分组的用户活动数据，涵盖最近 30 个（已完成的）UTC 日。

audio — 管理音频

• openrouter-pp-cli audio create-speech — 根据输入文本合成音频。以请求的格式（例如 mp3、pcm、wav）返回原始音频字节流。
• openrouter-pp-cli audio create-transcriptions — 将音频转录为文本。

benchmarks — 对端点进行基准测试

• openrouter-pp-cli benchmarks — 统一的基准测试端点，汇总来自多个基准测试来源的分数（Artificial Analysis、Design Arena

byok — BYOK 端点

• openrouter-pp-cli byok create-byokkey — 创建新的自带密钥（BYOK）提供商凭据。
• openrouter-pp-cli byok delete-byokkey — 根据其 id 删除（软删除）自带密钥（BYOK）提供商凭据。
• openrouter-pp-cli byok get-byokkey — 根据其 id 获取单个自带密钥（BYOK）提供商凭据。
• openrouter-pp-cli byok list-byokkeys — 列出已通过身份验证的实体的默认工作区中的自带密钥（BYOK）提供商凭据。
• openrouter-pp-cli byok update-byokkey — 根据其 id 更新现有的自带密钥（BYOK）提供商凭据。

chat — 聊天补全端点

• openrouter-pp-cli chat — 为给定的聊天对话发送模型响应请求。支持流式和非流式模式。

classifications — 任务分类市场份额端点

• openrouter-pp-cli classifications — 返回按任务分类划分的 OpenRouter 流量市场份额明细（例如

containers — 容器端点

credits — 额度管理端点

• openrouter-pp-cli credits create-coinbase-charge — 已弃用。
• openrouter-pp-cli credits get — 获取已通过身份验证的用户购买和使用的总额度。

datasets — OpenRouter 公共使用情况数据集。这些端点返回的数据依据 CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) 许可：可重复使用和再发布，包括用于商业用途，但须注明 OpenRouter。

• openrouter-pp-cli datasets get-app-rankings — 返回 OpenRouter 上按请求日期范围内的 token 使用量排名靠前的公共应用
• openrouter-pp-cli datasets get-rankings-daily — 返回 OpenRouter 上每天按 token 总使用量排名靠前的 50 个公共模型
• openrouter-pp-cli datasets get-session-cost — 返回每周更新的已发布测试框架的聚合会话成本数据单元格。

embeddings — 文本嵌入端点

• openrouter-pp-cli embeddings create — 向嵌入路由器提交嵌入请求
• openrouter-pp-cli embeddings list-models — 返回所有可用嵌入模型及其属性的列表

endpoints — 端点信息

• openrouter-pp-cli endpoints — 预览 ZDR 对可用端点的影响

files — 文件端点

• openrouter-pp-cli files delete — 删除请求工作区拥有的文件。删除后无法撤销。
• openrouter-pp-cli files get-metadata — 获取请求工作区拥有的单个文件的元数据。
• openrouter-pp-cli files list — 列出属于认证 API 密钥所在工作区的文件。
• openrouter-pp-cli files upload — 上传文件，供后续 API 调用引用。

generation — 生成历史端点

• openrouter-pp-cli generation get — 获取生成内容的请求和用量元数据
• openrouter-pp-cli generation list-content — 获取生成内容中存储的提示词、补全内容和错误内容
• openrouter-pp-cli generation submit-feedback — 提交经认证用户生成内容的结构化反馈。

guardrails — 防护规则端点

• openrouter-pp-cli guardrails create — 为经认证的用户创建新的防护规则。
• openrouter-pp-cli guardrails delete — 删除现有防护规则。需要管理密钥。
• openrouter-pp-cli guardrails get — 按 ID 获取单条防护规则。需要管理密钥。
• openrouter-pp-cli guardrails list — 列出经认证用户的所有防护规则。
• openrouter-pp-cli guardrails list-key-assignments — 列出经认证用户的所有 API 密钥防护规则分配。
• openrouter-pp-cli guardrails list-member-assignments — 列出经认证用户的所有组织成员防护规则分配。
• openrouter-pp-cli guardrails update — 更新现有防护规则，或实例化未配置的工作区默认防护规则。

images — 图像端点

• openrouter-pp-cli images create — 通过图像生成路由器，根据文本提示词生成图像
• openrouter-pp-cli images list-model-endpoints — 返回图像模型各端点的完整记录：每个端点确定支持的参数、定价
• openrouter-pp-cli images list-models — 列出所有图像生成模型，包括其顶层支持参数的并集，以及指向完整端点信息的 URL

key — 管理密钥

• openrouter-pp-cli key — 获取与当前认证会话关联的 API 密钥信息

keys — 管理密钥

• openrouter-pp-cli keys create — 为经认证的用户创建新的 API 密钥。明文 key 仅在此响应中返回。
• openrouter-pp-cli keys delete — 删除现有 API 密钥。
• openrouter-pp-cli keys get — 按哈希值获取单个 API 密钥。需要管理密钥。
• openrouter-pp-cli keys list — 列出经认证用户的所有 API 密钥。需要管理密钥。
• openrouter-pp-cli keys update — 更新现有 API 密钥。

messages — 管理消息

• openrouter-pp-cli messages — 使用 Anthropic Messages API 格式创建消息。支持文本、图像、PDF、工具和扩展思考。

model — 模型信息端点

• openrouter-pp-cli model <author> <slug> — 返回由作者和 slug 标识的单个模型的完整详情（例如 openai/gpt-4）。

models — 模型信息端点

• openrouter-pp-cli models get — 列出所有模型及其属性
• openrouter-pp-cli models list-count — 获取可用模型的总数
• openrouter-pp-cli models list-user — 根据用户的提供商偏好和[隐私设置](https://openrouter.

observability — 可观测性端点

• openrouter-pp-cli observability create-destination — 创建新的可观测性目标。每种类型最多允许创建 5 个目标。
• openrouter-pp-cli observability delete-destination — 删除现有的可观测性目标。此操作会执行软删除。
• openrouter-pp-cli observability get-destination — 根据 UUID 获取单个可观测性目标。
• openrouter-pp-cli observability list-destinations — 列出已认证实体默认工作区中配置的可观测性目标。
• openrouter-pp-cli observability update-destination — 更新现有的可观测性目标。仅更新请求正文中提供的字段。

openrouter-analytics — 管理 openrouter 分析

• openrouter-pp-cli openrouter-analytics get-meta — 返回分析查询端点可用的指标、维度、筛选运算符和粒度。
• openrouter-pp-cli openrouter-analytics query — 使用指定的指标、维度、筛选条件和时间范围执行分析查询。

openrouter-auth — 管理 openrouter 身份验证

• openrouter-pp-cli openrouter-auth create-keys-code — 为 PKCE 流程创建授权码，以生成由用户控制的 API 密钥
• openrouter-pp-cli openrouter-auth exchange-code-for-apikey — 将 PKCE 流程的授权码交换为由用户控制的 API 密钥

organization — 组织端点

• openrouter-pp-cli organization — 列出与已认证管理密钥关联的组织中的所有成员。

presets — 预设端点

• openrouter-pp-cli presets get — 根据预设的 slug 获取预设，并内联显示当前指定的版本。
• openrouter-pp-cli presets list — 列出已认证用户的所有预设，按最近更新时间从新到旧排序。

providers — 提供商信息端点

• openrouter-pp-cli providers — 列出所有提供商

rerank — 重排序端点

• openrouter-pp-cli rerank — 向重排序路由器提交重排序请求

responses — 兼容 OpenAI 的 Responses API 端点

• openrouter-pp-cli responses — 使用 OpenResponses API 格式创建流式或非流式响应

scim — SCIM 端点

• openrouter-pp-cli scim create-group-mapping — 创建 SCIM 组到工作区角色的映射。
• openrouter-pp-cli scim delete-group-mapping — 删除 SCIM 组到工作区的映射。需要管理密钥。
• openrouter-pp-cli scim get-group-mapping — 获取 SCIM 组到工作区的映射。需要管理密钥。
• openrouter-pp-cli scim list-group-mappings — 列出组织的 SCIM 组到工作区映射。
• openrouter-pp-cli scim list-groups — 列出组织的 SCIM 组。需要管理密钥。
• openrouter-pp-cli scim update-group-mapping — 更新 SCIM 组映射角色。需要管理密钥。

videos — 管理视频

• openrouter-pp-cli videos create — 提交视频生成请求，并返回用于检查状态的轮询 URL
• openrouter-pp-cli videos get — 返回作业状态，以及完成后的内容 URL
• openrouter-pp-cli videos list-models — 返回所有可用视频生成模型及其属性的列表

workspaces — 工作区端点

• openrouter-pp-cli workspaces create — 为已认证用户创建新的工作区。
• openrouter-pp-cli workspaces delete — 删除现有工作区。无法删除包含活跃 API 密钥的工作区；请先移除密钥。
• openrouter-pp-cli workspaces get — 按 ID 或 slug 获取单个工作区。需要管理密钥。
• openrouter-pp-cli workspaces list — 列出已认证用户的所有工作区。
• openrouter-pp-cli workspaces update — 按 ID 或 slug 更新现有工作区。需要管理密钥。

查找合适的命令

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

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

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

操作示例

周一成本审核

openrouter-pp-cli usage cost-by --since 7d --agent

每周进行归因统计：按 cron/Agent 标签汇总支出，可直接粘贴到审核备注中。

两条命令从异常追溯根因

openrouter-pp-cli usage anomaly --since 24h --agent

模型发出标记后，使用 generation explain <id> 继续查看令牌数、延迟，以及该异常调用与最便宜服务提供商之间的差额。

调度前健康检查

openrouter-pp-cli providers degraded --agent

启动调用链前运行此命令；搭配 endpoints failover <model>，为即将使用的模型确定调度顺序。

精简深层端点负载

openrouter-pp-cli models endpoints list deepseek deepseek-v4 --agent --select data.endpoints.provider_name,data.endpoints.pricing.completion,data.endpoints.status

每个模型的服务提供商列表嵌套很深；--select 可将结果限定为路由器实际需要的三个字段。

预算门控的 cron 模式

openrouter-pp-cli budget check nightly-drafter

未超出上限时退出代码为 0，超出时为 8——在计划任务触发前运行此检查，以此作为门控（例如 budget check X && systemctl --user start X.service）。

身份验证设置

使用推理密钥通过 OPENROUTER_API_KEY 进行标准 Bearer 身份验证，即可访问模型、额度、密钥状态和聊天功能。有两个功能需要在控制面板中创建单独的配置（管理）密钥：密钥管理（/keys）和账户级用量汇总（/activity、analytics）。如果其他命令使用密钥正常，但这些命令返回 401 或 403，说明你使用的是推理密钥，而这些命令需要管理密钥——并非配置有误。经实时验证（2026-09）：使用推理密钥访问 /activity 时，会返回 403 'Only management keys can fetch activity'。

CLI 只读取一个环境变量（OPENROUTER_API_KEY）；不会读取 OPENROUTER_MANAGEMENT_KEY。若要调用需要管理密钥的端点，请在该次调用中将管理密钥设为 API 密钥。请先确保环境中已设置 OPENROUTER_MANAGEMENT_KEY：

# Prerequisite: export OPENROUTER_MANAGEMENT_KEY=<your-management-key>
OPENROUTER_API_KEY="${OPENROUTER_MANAGEMENT_KEY}" openrouter-pp-cli keys list --agent
OPENROUTER_API_KEY="${OPENROUTER_MANAGEMENT_KEY}" openrouter-pp-cli activity --agent

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

Agent 模式

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

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

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

  openrouter-pp-cli benchmarks --agent --select accuracy,accuracy_stddev,agentic_index
  

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

• 适合离线使用 — 如果本地 SQLite 存储可用，同步/搜索命令可以使用该存储

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

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

• 明确重试 — 仅当已存在的创建操作应视为成功时，才使用 --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>，或设置 OPENROUTER_HOME=<dir>，将所有四类路径迁移到同一根目录下。

• 仅当某一类路径需要单独设置时，才使用对应的环境变量：OPENROUTER_CONFIG_DIR、OPENROUTER_DATA_DIR、OPENROUTER_STATE_DIR、OPENROUTER_CACHE_DIR。

• 解析顺序为：每类路径对应的环境变量、--home、OPENROUTER_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），然后是平台默认值。

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

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

• 运行 openrouter-pp-cli doctor --fail-on warn，以显示路径和凭据位置警告。agent-context 会公开 schema v4 的 paths 块，供需要已解析目录的 Agent 使用。

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

  {
    "mcpServers": {
      "openrouter": {
        "command": "openrouter-pp-mcp",
        "env": {
          "OPENROUTER_HOME": "/srv/openrouter"
        }
      }
    }
  }
  

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

自动学习

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

步骤 1：任何发现操作前先执行 recall

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

openrouter-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>", "openrouter-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 `openrouter-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> 会将该推导签名标记为墓碑，避免同一候选项再次出现。信封只包含当前值得处理的少数候选项；openrouter-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（顶层）：查询中的某个实体尚无查找行，但同步数据可能会提供。运行 openrouter-pp-cli sync 以刷新实体查找项。
• 顶层 no_learnings_for_query_family：表中没有高于 Jaccard 下限的行。属于纯冷启动。

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

教学是无条件的。解决存储无法回答的查询后，在后台教学最终资源映射——不设调用次数门槛，也不判断这次学习是否「值得」。教学是循环的锚点：如果某个类别还没有 playbook，它会触发 playbook 综合；同一指代对象的不同措辞会归并到同一类别，避免近乎重复的教学使存储内容碎片化。在整理好面向用户的回复后、发出回复前，使用 shell & 启动教学，让调用立即返回：

openrouter-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：操作手册——可选标志、自动综合生成

你不需要判断某个会话是否“值得”编写操作手册：对于尚无操作手册的某个类别，执行 teach 时会根据会话日志自动综合生成一个 playbook_candidate，并由下一次会话通过 confirm/reject 来判定。仅当你已经掌握值得逐字记录的操作流程时，才附上明确的操作手册标志——例如 CLI 未显示的变通方法（被静默丢弃的标志、未公开的参数、分页技巧、有效负载注意事项）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和操作手册：

# Common case: record both the resource learning AND the playbook in one call.
openrouter-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).
openrouter-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 amend。采用与 teach 相同的即发即忘方式。

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

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

• CLI 界面会静默丢弃或重新排序标志时的变通方法。
• 未公开的端点结构（响应包装在 {meta, results} 中；有效负载嵌套层级比文档所述深两层）。
• 观察到的架构变更（字段已重命名、索引在不同赛季间发生偏移，或 API 现在返回小写的类别标签）。

以下内容不应写入备注：

• 用户问题中特定年份或实体的答案。这是响应内容，不是学习所得。
• 操作手册已在运行时检索的每队、每位运动员或每行数据。
• 只是转述现有备注内容的陈述。

amend 命令会将内容附加到该类别现有的备注中，并添加带时间戳的标记（[amend YYYY-MM-DDTHH:MMZ]: <text>）。多次修订会累积，并保留可见的审计记录。如果该类别尚无操作手册，amend 会创建一个仅含备注的操作手册（因此，冷启动时发现的修正也能得到记录）。

amend 备注中的 PII 规范

playbook amend 备注在未来版本的 Printing Press 中可能会作为共享知识上传。因此，请勿在备注中包含可识别用户身份的信息，确保未来仍可向上游贡献，而无需事后清理：

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

如果某项修正只有结合用户特定上下文才有意义，请将其记入个人备注，而非操作手册修订内容。

衡量闭环效果

openrouter-pp-cli learnings stats 会根据本地 learn_events 表，报告召回命中率、教授后复用率、操作手册解决率，以及候选项确认／拒绝数量。分母尚未产生时，相关比率为 null；所有数据都保留在这台机器上。使用此命令检查这个 CLI 的学习闭环是否值得投入。

禁用学习

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

Agent 反馈

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

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

条目会保存在解析后的数据目录下的本地 feedback.jsonl 文件中。只有设置了 OPENROUTER_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 OPENROUTER_FEEDBACK_AUTO_SEND=true，才会发送 POST 请求。默认情况下仅保存在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、单行：这才是能持续积累的内容。

输出传递

每条命令都接受 --deliver <sink>。输出会写入指定目标，并可同时输出到标准输出，也可替代标准输出；这样 Agent 就能路由命令结果，而无需手动通过管道传递。支持三种目标：

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

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

命名配置

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

openrouter-pp-cli profile save briefing --json
openrouter-pp-cli --profile briefing benchmarks
openrouter-pp-cli profile list --json
openrouter-pp-cli profile show briefing
openrouter-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 openrouter-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上方的先决条件
3. 其他情况 → 直接使用（将其作为带有 --agent 的 CLI 命令执行）

安装 MCP 服务

从此 CLI 发布的公共库条目或预构建版本中安装 MCP 二进制文件，然后注册它：

claude mcp add openrouter-pp-mcp -- openrouter-pp-mcp

验证：claude mcp list

直接使用

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

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

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