pp-wavespeed

WaveSpeed — Printing Press 命令行工具

前提条件：安装 CLI

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

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

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

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

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

WaveSpeed 通过一个 API 提供图像、视频、音频和 3D 模型。此 CLI 提供动态模型运行器，支持使用斜杠分隔的模型 ID、免费价格估算、本地文件上传、附带费用报告的生成库，以及 D2C 内容层（plan、pack、batch、variants、compose、aspects、restyle、brand、qa）。付费提交不会重放；每次提交后的失败都会保留预测 ID 和恢复命令。

何时使用此 CLI

使用此 CLI，可通过脚本或 Agent，借助 WaveSpeed 模型生成或编辑图像和视频：查询价格、上传参考文件、运行模型并等待结果和下载文件，同时在本地记录每次生成及其费用。对于多平台 D2C 内容制作，请使用 plan/pack/batch 命令。

不适用场景

请勿将此 CLI 用于：

• 训练或微调模型
• 托管或提供自己的模型服务

独特功能

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

核心功能

• run — 提交 WaveSpeed 模型运行任务，支持提示词简写、类型化的 --set 输入、本地 @file 媒体上传、价格估算、等待、可安全恢复的下载，以及记录到生成库。

  用于任何单次生成；提交后的任何失败都不会丢失预测 ID 和恢复命令。

  wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "a red mug on oak" --images @ref.png --set aspect_ratio=9:16 --wait --download 'out/mug_{index}.{ext}' --agent
  

• schema — 获取实时 WaveSpeed 模型目录，并打印模型或项目别名的请求架构。

  在付费运行前，检查可接受的输入和枚举值。

  wavespeed-pp-cli schema google/nano-banana-2/edit --agent
  

• price — 使用与 run 相同的输入语法估算 WaveSpeed 模型价格，不会提交预测任务。

  免费；先估算费用，再决定是否付费。

  wavespeed-pp-cli price --model-id google/nano-banana-2/edit --set aspect_ratio=9:16 --set resolution=2k --agent
  

• aliases — 读取 wavespeed.json 中的别名、默认模型和输出目录设置，以便重复执行本地工作流。

  查看哪些短名称对应哪些模型。

  wavespeed-pp-cli aliases --agent
  

• init — 创建包含别名、默认模型和输出目录的初始 wavespeed.json。

  开始一个新的图像项目。

  wavespeed-pp-cli init
  

媒体

• upload — 将本地图像、视频或音频文件上传到 WaveSpeed 媒体存储，以便作为模型输入 URL；上传停滞时，会根据文件大小设定超时时限并重试。

  将本地文件转换为模型可接受的 URL。

  wavespeed-pp-cli upload ./ref.png --agent
  

• download — 下载生成结果的 URL，可将文件保存到指定目录、精确路径或模板路径；绝不向 CDN 主机发送 API 凭据。

  重新获取已完成预测任务的输出。

  wavespeed-pp-cli download "$OUTPUT_URL" --output 'out/{index}.{ext}'
  

• last — 打印或打开最近下载的输出。

  获取最近生成文件的路径。

  wavespeed-pp-cli last
  

规划

• plan brief-to-shotlist — 通过混合确定性解析器和大模型规划器，将自由文本简报转换为适用于多个平台和宽高比的结构化镜头列表。

  为营销活动拟定镜头列表。

  wavespeed-pp-cli plan brief-to-shotlist --prompt "Helm Black launch" --platforms instagram,tiktok --agent
  

• plan model-pick — 根据实时目录，为某项意图推荐模型并说明理由。

  为一项任务选择模型。

  wavespeed-pp-cli plan model-pick "short product video" --agent
  

• plan cost-estimate — 根据实时的 /model/pricing 和账户余额，为镜头列表估算费用；支持使用缓存价格作为回退，并提供逐镜头费用明细。

  检查镜头列表是否符合预算。

  wavespeed-pp-cli plan cost-estimate shotlist.json --agent
  

• qa preflight — 对镜头列表进行通过／警告／失败验证：检查余额与费用、模型可用性、提示词安全性、平台请求格式和品牌覆盖情况。

  在制作前检查素材包。

  wavespeed-pp-cli qa preflight shotlist.json --agent
  

制作

• pack — 根据一个创意制作适用于多个平台的创意素材包，文件位于稳定的 packs/// 路径，并包含各平台清单；支持并发、费用上限和图像尺寸验证；重新运行时会归档被替换的清单。

  制作可直接用于各平台的素材。

  wavespeed-pp-cli pack --concept "Helm Black hero" --platforms instagram,tiktok --max-cost 5.00 --agent
  

• batch — 从 CSV 或 JSON 提交多条提示词，并设置支出上限和快速失败／容错语义；中止前会记录已完成的生成任务。

  在预算内运行提示词列表。

  wavespeed-pp-cli batch --from prompts.csv --max-cost 5.00 --agent
  

• variants — 基于一个基础镜头，变更种子、风格或模型，生成可比较的输出，并列出并排的元数据。

  为一个镜头探索不同种子或模型。

  wavespeed-pp-cli variants --base shotlist.json --vary seed --count 4 --agent
  

• compose — 运行明确的多步骤工作流（文本->图像->放大->视频），将每一步的输出传递给下一步；发生故障时回滚后续步骤。

  将提示词转换为图像，再生成片段。

  wavespeed-pp-cli compose --steps "text->image,image->video" --prompt "..." --models m1,m2 --agent
  

优化

• aspects — 将一张图像重新构图为标准平台宽高比；支持时使用扩图，否则以锚定方式重新渲染。

  为主视觉图制作 9:16 和 1:1 版本。

  wavespeed-pp-cli aspects hero.png --platforms instagram,tiktok --agent
  

• restyle — 通过带有风格提示词的 img2img，将品牌配置文件或明确指定的风格应用到现有素材。

  让素材符合品牌风格。

  wavespeed-pp-cli restyle hero.png --brand helm --agent
  

素材库

• library — 按品牌、模型、平台和标签列出、搜索（FTS5）、查看、标记、导出本地生成素材库，并生成费用报告。

  查找过去生成的内容或总支出。

  wavespeed-pp-cli library cost-report --group-by model --agent
  

• brand — 创建、检查、应用和编辑品牌配置文件；这些配置会自动合并到 pack、compose、variants、restyle 和 run 中。

  设置品牌，以保持输出一致。

  wavespeed-pp-cli brand init helm --palette '#111,#eee' --voice calm
  

命令参考

account_balance — 管理账户余额

• wavespeed-pp-cli account-balance — 获取已认证账户的余额。

billings — 账单和使用记录

• wavespeed-pp-cli billings — 搜索已认证账户的账单记录。

media_uploads — 管理媒体上传

• wavespeed-pp-cli media-uploads — 将一个现有的本地媒体文件（图像、视频或音频）上传到 WaveSpeed 存储，并返回可用于模型输入的 URL。

model_pricing — 管理模型定价

• wavespeed-pp-cli model-pricing — 使用将提交给模型端点的相同输入，估算一次模型运行的单价。

models — 模型目录和模型元数据

• wavespeed-pp-cli models — 列出可用的 WaveSpeed 模型及其 API 架构。

prediction_deletions — 管理预测删除

• wavespeed-pp-cli prediction-deletions — 从历史记录中删除一个或多个预测。

prediction_results — 管理预测结果

• wavespeed-pp-cli prediction-results <task_id> — 获取预测任务的最新状态和结果载荷。

predictions — 预测提交历史和结果获取

• wavespeed-pp-cli predictions — 查询近期预测历史。API 历史记录窗口有限；同步会累积多次运行的数据。

usage_stats — 管理使用统计数据

• wavespeed-pp-cli usage-stats — 获取已认证账户的使用统计数据。

查找合适的命令

当你知道想做什么，但不知道哪个命令可以完成时，直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有足够可靠的匹配项——请改用 --help 或缩小查询范围。--json（以及其他机器可读格式）遵循相同的退出代码 2 约定，并在标准输出中写入 {"matches":[]}，这样 Agent 就能检查返回结构，而不会将未匹配误判为成功。

操作示例

使用参考图进行图像编辑，9:16，2k

wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "$PROMPT" --images https://wavespeed.ai/anchor.png --set aspect_ratio=9:16 --set resolution=2k --wait --download 'raw/shot_{index}.{ext}' --record --agent

传入 URL 或本地 @file；本地文件会自动上传。下载模板会为每个输出命名。

首尾帧视频

wavespeed-pp-cli run --model-id bytedance/seedance-v1.5-pro/image-to-video --prompt "$MOTION" --image https://wavespeed.ai/a.jpg --last-image https://wavespeed.ai/b.jpg --set duration=5 --wait --wait-timeout 10m --download 'clip_{index}.{ext}' --record --agent

--wait-timeout 限制轮询时长；超时后会打印预测 ID 和恢复命令。

查看某个会话的支出

wavespeed-pp-cli billings --page-size 20 --agent

账单行会列出每次预测所收取的价格。

规划推广活动

wavespeed-pp-cli plan brief-to-shotlist --prompt "launch" --platforms instagram,tiktok --agent

保存镜头列表，然后在其上运行 plan cost-estimate 和 qa preflight，再执行 pack。

身份验证设置

WaveSpeed 使用通过 Authorization: Bearer <key> 发送的 API 密钥。请在 https://wavespeed.ai/accesskey 创建密钥，并将其导出为 WAVESPEED_API_KEY。doctor 会通过免费的 /balance 读取验证密钥。

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

Agent 模式

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

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

• --json — 在标准输出中输出一个 JSON 文档（sync 进度事件发送到标准错误）

• --compact — 保留身份、状态和时间戳字段；不改变文档与流的结构

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

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

• 支持管道传输 — JSON 输出到标准输出，错误输出到标准错误

• 支持筛选 — --select 保留指定字段子集。点分隔路径可向下访问嵌套结构；数组会逐元素遍历。在冗长 API 中缩减上下文时尤其有用：

  wavespeed-pp-cli billings --agent --select code,data,message
  

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

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

• 非交互式 — 从不发出提示，所有输入都通过标志传入

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

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

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 了解数据来自实时查询还是本地存储。只有当标准输出连接到终端，且未设置机器可读格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于人类阅读的 N results (live) 摘要打印到标准错误；管道或 Agent 消费者以及显式指定格式的运行会在标准输出中获得纯 JSON。

路径与状态

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

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

• 仅当某一类路径需要单独设置时，才使用对应类型的环境变量：WAVESPEED_CONFIG_DIR、WAVESPEED_DATA_DIR、WAVESPEED_STATE_DIR、WAVESPEED_CACHE_DIR。

• 解析优先级依次为：各类型的环境变量、--home、WAVESPEED_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。

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

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

  {
    "mcpServers": {
      "wavespeed": {
        "command": "wavespeed-pp-mcp",
        "env": {
          "WAVESPEED_HOME": "/srv/wavespeed"
        }
      }
    }
  }
  

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

自动学习

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

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

针对新问题，在执行列表/搜索/深入查询命令前，将问题作为 argv 或 MCP 工具参数传给 recall --agent。不要将用户输入的文本插入 shell 命令行。

带引号的 recall "<question>" 遇到撇号就会出错，而撇号在英语中很常见。带引号的 heredoc 遇到内容行恰好等于分隔符时也会出错，而且这些文档中公开了该分隔符。请使用非 shell 文件写入工具写入问题，再将其作为数据读回：

# Write the question verbatim with your file-writing tool (no shell involved).
# Command substitution on a file only ever yields data — the shell never
# parses the file's bytes as syntax.
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli recall "$QUERY" --agent

优先使用 MCP：将问题作为工具的查询参数传入。读取文件后使用 "$QUERY" 可确保 argv 安全；但不要将问题本身放进命令文本中。

响应信封：

{
  "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>", "wavespeed-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 `wavespeed-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> 会将派生签名标记为已废弃，避免同一候选项再次出现。信封中只包含当前值得采取行动的少数候选项；wavespeed-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 行，但同步数据可能会提供一条。运行 wavespeed-pp-cli sync 以刷新实体查找项。
• 顶层 no_learnings_for_query_family：表中没有高于 Jaccard 下限的行。属于纯冷启动。

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

教学是无条件的。解决存储无法回答的查询后，在后台教学最终资源映射——没有调用次数门槛，也不判断是否“值得”学习。教学是这个循环的锚点：对于尚无操作手册的类别，它会触发操作手册合成；指向同一对象的不同说法会归并到同一个类别，因此近似重复的教学不会让存储变得零散。组装好面向用户的回复后、发出回复前，使用 shell & 执行教学调用，使其立即返回。像 recall 一样传递查询——使用 argv/MCP，或通过文件再传入 $QUERY。不要把问题拼接到命令文本中：

QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach --query "$QUERY" --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_candidate，并由下一次会话通过 confirm/reject 对其进行评估。只有在你已经掌握值得原样记录的操作流程时，才添加明确的操作手册标志——例如 CLI 未显示的变通方法（静默丢弃的标志、未记录的参数、分页技巧、负载易错点）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和操作手册：

# Common case: record both the resource learning AND the playbook in one call.
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach \
  --query "$QUERY" \
  --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).
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach-playbook \
  --query "$QUERY" \
  --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 形式必须设置操作手册标志和备注标志中的至少一个；两者都为空会被拒绝。操作手册以结构性查询类别（剥离实体后）为键，因此，从一个实体形状的查询中教学得出的操作方案适用于其他所有具有相同形状的查询；在 recall 时，slots_resolved 会将当前查询绑定到规范实体。

在后续 recall 中找到操作手册时，应将其视为真实依据：使用 slots_resolved 替换值后重放步骤，跳过操作流程中已经记录的探索过程，并在执行任何步骤前阅读 notes。

第 6 步：调试响应发现需要更正时，执行 playbook amend &

如果你的调试协议响应发现了一项笔记或操作手册应当了解的具体更正——例如变通方法、未记录的端点结构、过时的字段名称、观察到的架构漂移或空载荷回退方案——请在输出面向用户的响应之前执行 playbook amend。与 teach 一样，采用即发即弃的方式。将查询和笔记作为 argv/MCP 参数传入，或者使用非 shell 文件工具分别写入，然后读回（QUERY=$(cat ...)、NOTE=$(cat ...)）。不要将任一字符串插入命令文本：

QUERY=$(cat /path/to/question.txt)
NOTE=$(cat /path/to/note.txt)
wavespeed-pp-cli playbook amend \
  --query "$QUERY" \
  --add-note "$NOTE"
# (append shell `&` to background it)

什么情况值得补充：本次会话中你观察到的、未来的自己也会受益的行为。值得补充的示例：

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

不应写入笔记的内容：

• 用户问题中与年份或实体相关的答案。这属于响应内容，不是经验总结。
• 操作手册已在运行时获取的每队、每位运动员或每行数据。
• 对现有笔记内容的改述。

amend 命令会将带时间戳的标记（[amend YYYY-MM-DDTHH:MMZ]: <text>）追加到该系列现有笔记中。多次 amend 会累积保留，并且可以查看审计记录。如果该系列还没有操作手册，amend 会创建一个仅含笔记的操作手册（因此，冷启动时发现的更正也会被记录下来）。

amend 笔记中的 PII 规范

playbook amend 笔记未来可能会作为共享知识流入 Printing Press 的后续版本。请勿在其中包含可识别用户身份的内容，以便上游贡献流程无需事后清理也能保持开放：

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

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

衡量循环效果

wavespeed-pp-cli learnings stats 会从本地 learn_events 表中报告召回命中率、教学到复用率、操作手册解析率，以及候选项确认／拒绝次数。尚无分母时，相关比率为 null；所有数据都保留在本机。可用它检查此循环是否对这个 CLI 有价值。

禁用学习功能

• 在单条命令中使用 --no-learn，可同时跳过 recall 和 teach 写入流程。适用于确定性 Agent 工作流，或必须不受累积经验影响的测试。
• 在环境中设置 WAVESPEED_NO_LEARN=true，可全局禁用该流程。

Agent 反馈

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

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

条目会以 feedback.jsonl 的形式存储在解析后的数据目录中。除非设置了 WAVESPEED_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 WAVESPEED_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认仅存储在本地。

记录让你感到意外的内容，而不是提交 Bug 报告。简短、具体，写成一行：这才是能不断积累价值的部分。

输出交付

每条命令都接受 --deliver <sink>。输出会写入指定的目标，同时写入标准输出，或替代标准输出，这样 Agent 无需手动传递即可路由命令结果。支持三种目标：

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

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

命名配置文件

配置文件是保存的一组标志值，可在多次调用中重复使用。若定期运行或重复运行的 Agent 会重复使用同一组已保存的标志，同时每次运行提供不同输入，则可使用配置文件。

wavespeed-pp-cli profile save briefing --json
wavespeed-pp-cli --profile briefing billings
wavespeed-pp-cli profile list --json
wavespeed-pp-cli profile show briefing
wavespeed-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add wavespeed-pp-mcp -- wavespeed-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

4. 如果存在歧义，请通过子命令帮助深入了解：wavespeed-pp-cli <command> --help。