pp-surgegraph

SurgeGraph — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

如果 npx 安装失败（没有 Node、处于离线状态等），则改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

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

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

何时使用此 CLI

当 Agent 需要针对 SurgeGraph 执行任何 AI 搜索内容任务时，请使用此 CLI：监控 AI Visibility 变化、批量起草和发布文章、审核知识库的影响，或为其他 Agent 提供项目当前状态。Web 应用中所有可见的功能都有对应的 CLI 命令，而所有 transcendence 命令都是 MCP 工具——启动流程的 Agent 无需离开终端即可完成整个流程。

独有功能

这些功能在此 API 的其他工具中均不可用。

会逐步积累的本地状态

• visibility delta — 准确查看 AI Visibility 每周的变化——概览、趋势、情绪或流量，无需分别截取两个仪表板标签页的屏幕截图再手动比较。

  当用户询问 AI Visibility 有何变化，或想要一份排名变动报告时使用；无需额外消耗一次 API 往返即可获得答案。

  surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --metric overview,trend --agent
  

• visibility prompts losers — 找出引用次数或首位排名较上一时间窗口下降的已跟踪提示词——这是 CMO 每周一都会要求、但仪表板无法生成的报告。

  当用户想要查找可见度下滑时使用；它会提供一份按排名排序、可供采取行动的列表，而不是两份需要比较的原始快照。

  surgegraph-pp-cli visibility prompts losers --project proj_abc123 --since 720h --agent --select prompt_id,prompt,citation_delta,position_delta
  

• visibility citation-domains rank-shift — 在 30 天时间窗口内，监控哪些域名在项目的 AI 跟踪提示词中增加或失去了引用份额——当竞争对手开始挤占答案集时，这项功能很有用。

  监控 AI 答案中的竞争性声量份额时使用。

  surgegraph-pp-cli visibility citation-domains rank-shift --project proj_abc123 --window 720h --agent
  

• docs stale — 列出过去 N 天未更新的撰稿文档和优化文档，并按近期 AI 来源流量排序——一条查询即可生成内容刷新队列。

  为内容刷新队列确定优先级时使用。

  surgegraph-pp-cli docs stale --project proj_abc123 --older-than 90 --agent --select document_id,title,last_updated,ai_traffic_30d
  

• visibility portfolio — 汇总组织中所有项目的 AI Visibility 变化——这是单项目 UI 无法提供的代理机构项目组合视图。

  当用户管理多个项目（代理机构、多品牌）并要求提供执行摘要时使用。

  surgegraph-pp-cli visibility portfolio --window 168h --agent
  

• account burn — 根据最近 30 天的使用快照预测项目的额度耗尽情况——在排入大型批量发布任务之前，可先进行预检。

  启动批量操作前使用，确认额度充足。

  surgegraph-pp-cli account burn --window 720h --agent
  

无法通过单次 API 调用完成的跨实体联接

• knowledge impact — 根据某个项目的知识库链接实际出现在受追踪的 AI 引用中的频率，为知识库排序，回答“这个知识库值得维护吗？”。

  当用户审核知识库或询问哪个知识库带来了成效时，选择此项。

  surgegraph-pp-cli knowledge impact --project proj_abc123 --agent
  

• research drift — 将 topic_research 的层级地图与已发布的 writer_documents 进行比对，找出已覆盖的内容与缺口，并按优先级排序以便采取行动。

  根据主题研究规划内容冲刺时使用；它会准确告知 Agent 哪些子主题仍需要撰写文章。

  surgegraph-pp-cli research drift --research-id res_xyz789 --project proj_abc123 --agent --select topic,parent,covered
  

• research domain diff — 将竞争对手的 domain_research 主题树与自己的 topic_research 进行差异比较，即时查看对方覆盖了哪些内容而你没有。

  与特定竞争对手比较主题覆盖范围时，选择此项。

  surgegraph-pp-cli research domain diff --project proj_abc123 --mine res_xyz789 --theirs dom_res_aaa --agent
  

• visibility traffic-citations — 针对每个流量最高的页面，列出 AI 引用最终指向该页面的受追踪提示词，回答“这个页面为什么会获得 AI 流量？”。

  解释流量模式，或根据已经带来 AI 点击的内容规划新内容时使用。

  surgegraph-pp-cli visibility traffic-citations --project proj_abc123 --agent --select page_url,ai_visits,citations
  

跨产品的复合工作流

• research gaps publish — 接收主题缺口输出，按每批 50 篇文档批量创建文档，并将其加入 WordPress 集成的队列——通过一条幂等命令完成内容运营的日常流程。

  当用户想要为主题研究发现的所有缺口发布文章时，选择此项；它将多标签页的手动工作流简化为一次调用。

  surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run --agent
  

原生适配 Agent 的基础组件

• context bundle — 输出一个 JSON 数据块，结构适合放入 Agent 的上下文窗口，涵盖一个项目的提示词、引用、文档和主题地图——这是 Agent 循环所需的交接载荷。

  在一次往返中，将你掌握的关于 SurgeGraph 项目的所有信息注入另一个 Agent 的工作记忆时使用。

  surgegraph-pp-cli context bundle --project proj_abc123 --include prompts,citations,docs,topics
  

• search — 在本地缓存中进行全文搜索，涵盖 AI Visibility 提示词、引用、writer documents、optimized documents 和主题地图节点——一次查询即可命中多个实体。

  当 Agent 需要在整个本地缓存中查找任何信号（提示词、引用或草稿）时，选择此项。

  surgegraph-pp-cli search "AI search optimization" --kind prompts,citations,docs,topics --agent --select kind,id,title,snippet
  

• sync diff — 输出本地存储中每项资源的同步游标和行数总计——这是 Agent 循环的检查工具，用于判断是否需要重新同步。

  在 sync 后运行以检查游标的新鲜度，或在 Agent 循环中运行，以决定读取前是否需要重新同步本地存储。

  surgegraph-pp-cli sync diff --agent
  

命令参考

create-ai-visibility-prompt — 管理 AI Visibility 提示词的创建

• surgegraph-pp-cli create-ai-visibility-prompt — 创建用于 AI Visibility 跟踪的新提示词。系统会在各个 AI 答案引擎中跟踪提示词，以监控品牌……

create-api-key — 管理 API 密钥的创建

• surgegraph-pp-cli create-api-key — 为组织创建 LLM 提供商 API 密钥。密钥在存储前会先通过提供商验证……

create-bulk-documents — 管理批量文档的创建

• surgegraph-pp-cli create-bulk-documents — 在单个批次中批量创建多篇 AI 撰写的文档（最多 50 篇）。每篇文章都需要一个提示词；其他所有……

create-document — 管理文档的创建

• surgegraph-pp-cli create-document — 创建并生成一篇 AI 撰写的文档。只需提供“prompt”；其他所有字段都有合理的默认值……

create-domain-research — 管理域名研究的创建

• surgegraph-pp-cli create-domain-research — 开始一项域名研究，用于分析主题覆盖范围。分析某个域名以发现相关主题。结果将……

create-image — 管理图像的创建

• surgegraph-pp-cli create-image — 生成一张 AI 图像并将其存储到 Content Vision 画廊。请先使用 get_content_vision_settings 查看……

create-knowledge-library — 管理知识库的创建

• surgegraph-pp-cli create-knowledge-library — 在项目中创建新的知识库。知识库用于存储可作为 AI 上下文的文档……

create-knowledge-library-document — 管理创建知识库文档

• surgegraph-pp-cli create-knowledge-library-document — 在知识库中创建文本文档。文档内容将建立索引，以便用作 AI 写作上下文……

create-optimized-document — 管理创建优化文档

• surgegraph-pp-cli create-optimized-document — 根据现有的 WordPress 帖子创建内容优化文档。系统会通过……获取帖子内容

create-topic-research — 管理创建主题研究

• surgegraph-pp-cli create-topic-research — 启动主题研究，以分析主题覆盖情况。分析特定主题，发现子主题、相关……

create-topic-research-expansion — 管理扩展主题研究

• surgegraph-pp-cli create-topic-research-expansion — 扩展现有主题研究，在一个或多个宏观主题下生成微观主题。每个宏观主题……

delete-ai-visibility-prompt — 管理删除 AI 可见性提示词

• surgegraph-pp-cli delete-ai-visibility-prompt — 从项目中删除 AI 可见性提示词。使用 get_ai_visibility_prompts 查找提示词 ID。适用于清理……

delete-api-key — 管理删除 API 密钥

• surgegraph-pp-cli delete-api-key — 从组织中删除 API 密钥。使用 get_openai_keys / get_gemini_keys / get_anthropic_keys 查找……

delete-document — 管理删除文档

• surgegraph-pp-cli delete-document — 按 ID 删除 SurgeGraph 文档。使用 get_writer_documents 或 get_optimized_documents 查找文档 ID……

delete-knowledge-library — 管理删除知识库

• surgegraph-pp-cli delete-knowledge-library — 删除知识库及其所有文档。使用 get_knowledge_libraries 查找知识库 ID。这是永久……

delete-knowledge-library-document — 管理删除知识库文档

• surgegraph-pp-cli delete-knowledge-library-document — 从知识库中删除文档。移除 LlamaIndex 索引、向量嵌入和文档行……

get-ai-visibility-citation-domain — 管理获取 AI 可见性引用域名

• surgegraph-pp-cli get-ai-visibility-citation-domain — 深入查看特定域名的引用情况。返回该域名下被引用的页面级 URL，以及引用各页面的引擎……

get-ai-visibility-citation-own-domain — 管理获取 AI 可见性自有域名引用

• surgegraph-pp-cli get-ai-visibility-citation-own-domain — 获取项目自有域名的引用数据。显示用户的哪些页面正被 AI 引擎引用……

get-ai-visibility-citations — 管理获取 AI 可见性引用

• surgegraph-pp-cli get-ai-visibility-citations — 获取 AI 可见性跟踪的高级别引用概览。返回自有域名引用摘要，以及各引擎……

get-ai-visibility-config — 管理获取 AI 可见性配置

• surgegraph-pp-cli get-ai-visibility-config — 获取项目的 AI 可见性跟踪和答案引擎配置。

get-ai-visibility-emerging-topics — 管理获取 AI 可见性新兴主题

• surgegraph-pp-cli get-ai-visibility-emerging-topics — 获取 AI 可见性跟踪中的新兴主题。返回在各 AI……中提及频率不断上升的主题

get-ai-visibility-metadata — 管理获取 AI 可见性元数据

• surgegraph-pp-cli get-ai-visibility-metadata — 获取 AI 可见性项目的筛选元数据。返回受跟踪的答案引擎（模型）列表、受跟踪的……

get-ai-visibility-opportunities — 管理获取 AI 可见性优化机会

• surgegraph-pp-cli get-ai-visibility-opportunities — 获取项目的 AI 可见性优化机会。返回按优先级和类别统计的数据，以及一个列表…… get-ai-visibility-overview — 管理 get ai visibility overview

• surgegraph-pp-cli get-ai-visibility-overview — 获取项目中特定品牌的 AI Visibility 概览。返回该品牌按引擎划分的指标……

get-ai-visibility-prompt-detail — 管理 get ai visibility prompt detail

• surgegraph-pp-cli get-ai-visibility-prompt-detail — 深入查看特定日期的单条提示词。返回完整的品牌表现（可见度、排名、份额……

get-ai-visibility-prompt-response — 管理 get ai visibility prompt response

• surgegraph-pp-cli get-ai-visibility-prompt-response — 获取特定提示词执行的原始 AI 回复。返回结构化回复条目和 Markdown……

get-ai-visibility-prompts — 管理 get ai visibility prompts

• surgegraph-pp-cli get-ai-visibility-prompts — 获取项目中配置用于 AI Visibility 跟踪的提示词。支持分页：默认第 1 页，每页 50 条……

get-ai-visibility-response-structure — 管理 get ai visibility response structure

• surgegraph-pp-cli get-ai-visibility-response-structure — 获取 AI Visibility 跟踪中特定品牌的回复结构分析。返回按引擎划分的回复……

get-ai-visibility-sentiment — 管理 get ai visibility sentiment

• surgegraph-pp-cli get-ai-visibility-sentiment — 获取 AI Visibility 跟踪中特定品牌的情感分析。返回按引擎划分的情感……

get-ai-visibility-topic-gaps — 管理 get ai visibility topic gaps

• surgegraph-pp-cli get-ai-visibility-topic-gaps — 获取 AI Visibility 跟踪的主题缺口。主题缺口是指竞争对手被提及、但你的品牌……

get-ai-visibility-topics — 管理 get ai visibility topics

• surgegraph-pp-cli get-ai-visibility-topics — 获取 AI Visibility 跟踪中的主题集群。返回聚类后的主题、关键词频率、趋势……

get-ai-visibility-traffic-pages — 管理 get ai visibility traffic pages

• surgegraph-pp-cli get-ai-visibility-traffic-pages — 获取包含 AI 流量数据的分页页面列表。返回每个页面的 AI/人工访问量、CTR、爬取错误、热门……

get-ai-visibility-traffic-summary — 管理 get ai visibility traffic summary

• surgegraph-pp-cli get-ai-visibility-traffic-summary — 获取项目的 AI 流量分析摘要。返回 AI/人工访问总量及其趋势、CTR、已索引页面……

get-ai-visibility-trend — 管理 get ai visibility trend

• surgegraph-pp-cli get-ai-visibility-trend — 获取特定品牌每日 AI Visibility 趋势。日期范围不得超过 14 天——该工具将……

get-anthropic-keys — 管理 get anthropic keys

• surgegraph-pp-cli get-anthropic-keys — 列出组织的所有 Anthropic API 密钥。返回已遮蔽的密钥（显示末尾 4 个字符）、启用状态、标签……

get-author-brand — 管理 get author brand

• surgegraph-pp-cli get-author-brand — 获取项目的品牌资料（Author Synthesis）。返回品牌标识值、必需/禁止……

get-authors — 管理 get authors

• surgegraph-pp-cli get-authors — 列出项目配置的所有作者（Author Synthesis）。返回作者资料，包括语气校准、简介……

get-brand-mentions — 管理 get brand mentions

• surgegraph-pp-cli get-brand-mentions — 列出组织配置的所有品牌提及。

get-content-vision-gallery — 管理 get content vision gallery

• surgegraph-pp-cli get-content-vision-gallery — 列出项目 Content Vision 图片库中的图片。支持按类型、风格、搜索查询筛选……

get-content-vision-settings — 管理 get content vision settings

• surgegraph-pp-cli get-content-vision-settings — 获取项目的 Content Vision 设置，包括品牌颜色、精选图片设置和可用图片类型……

get-document — 管理 get document

• surgegraph-pp-cli get-document — 按 ID 检索单篇文档，包括其内容、AEO（AI 引擎优化）建议和 SEO 建议。

get-domain-research — 管理域名研究结果获取

• surgegraph-pp-cli get-domain-research — 获取域名研究的完整结果：域名、提取的主题和完成状态。使用...

get-gemini-keys — 管理 Gemini 密钥获取

• surgegraph-pp-cli get-gemini-keys — 列出组织的所有 Gemini API 密钥。返回经过遮蔽的密钥（显示末 4 位字符）、启用状态、标签以及...

get-knowledge-libraries — 管理知识库列表获取

• surgegraph-pp-cli get-knowledge-libraries — 列出项目的所有知识库。返回各知识库及其文档和聊天数量。

get-knowledge-library-documents — 管理知识库文档获取

• surgegraph-pp-cli get-knowledge-library-documents — 列出知识库中的所有文档/资源。返回文档详情，包括索引状态。

get-languages — 管理语言列表获取

• surgegraph-pp-cli get-languages — 列出创建文档和研究主题时可用的语言。返回语言代码和名称。传入返回的...

get-locations — 管理位置列表获取

• surgegraph-pp-cli get-locations — 列出创建文档和研究主题时可用的位置（国家/地区）。返回位置代码、名称和...

get-openai-keys — 管理 OpenAI 密钥获取

• surgegraph-pp-cli get-openai-keys — 列出组织的所有 OpenAI API 密钥。返回经过遮蔽的密钥（显示末 4 位字符）、启用状态、标签以及...

get-optimized-documents — 管理优化文档获取

• surgegraph-pp-cli get-optimized-documents — 列出内容优化器中的优化文章。支持搜索和分页。

get-organization-cms-integrations — 管理组织 CMS 集成获取

• surgegraph-pp-cli get-organization-cms-integrations — 列出组织连接的所有 CMS 集成，包括每个集成关联的项目。...

get-project-cms-integration — 管理项目 CMS 集成获取

• surgegraph-pp-cli get-project-cms-integration — 获取特定项目连接的 CMS 集成。返回集成类型、站点详情和连接...

get-projects — 管理项目列表获取

• surgegraph-pp-cli get-projects — 列出组织的所有项目。支持搜索和分页。

get-team — 管理团队信息获取

• surgegraph-pp-cli get-team — 列出组织的所有团队成员和待处理的邀请。返回成员详情，包括角色和...

get-topic-map — 管理主题地图获取

• surgegraph-pp-cli get-topic-map — 获取项目的主题覆盖地图。返回完整的主题层级结构，包括支柱主题、子主题、覆盖...

get-topic-research — 管理主题研究结果获取

• surgegraph-pp-cli get-topic-research — 获取主题研究的完整结果：种子主题、位置/语言以及宏观 → 微观主题层级...

get-usage — 管理用量信息获取

• surgegraph-pp-cli get-usage — 获取组织的配额用量、功能限制和点数余额。显示永久配额（团队席位，...

get-wordpress-authors — 管理 WordPress 作者获取

• surgegraph-pp-cli get-wordpress-authors — 列出已连接 WordPress 站点中的作者。按作者返回 ID、姓名、别名、简介和 avatarUrl。支持分页 —...

get-wordpress-categories — 管理 WordPress 分类获取

• surgegraph-pp-cli get-wordpress-categories — 列出已连接 WordPress 站点中的所有分类。返回每个分类的 ID、名称和别名 — 使用这些 ID...

get-wordpress-integrations — 管理 WordPress 集成获取

• surgegraph-pp-cli get-wordpress-integrations — 列出组织连接的所有 WordPress 集成。显示站点详情、经过遮蔽的 API 密钥以及...

get-writer-documents — 管理撰写器文档获取

• surgegraph-pp-cli get-writer-documents — 列出 Content Hub 中的文章。支持筛选和分页。

get-writer-models — 管理 get writer models

• surgegraph-pp-cli get-writer-models — 列出可用于撰写文档的 AI 模型。返回模型 ID、提供商、积分费用，以及是否支持……

list-domain-researches — 管理 list domain researches

• surgegraph-pp-cli list-domain-researches — 列出项目的所有领域研究。返回每个条目的 ID、领域、提取的主题数量，以及……

list-topic-researches — 管理 list topic researches

• surgegraph-pp-cli list-topic-researches — 列出项目的所有主题研究。返回每个条目的 ID、种子主题、主题总数，以及……

publish-document-to-cms — 管理 publish document to cms

• surgegraph-pp-cli publish-document-to-cms — 将 SurgeGraph 文档发布到项目所连接的 CMS（目前支持 WordPress）。在……

update-ai-visibility-prompt — 管理 update ai visibility prompt

• surgegraph-pp-cli update-ai-visibility-prompt — 更新现有的 AI Visibility 提示词。可以修改提示词文本、主题和标签。主题和标签会被解析……

update-api-key — 管理 update api key

• surgegraph-pp-cli update-api-key — 更新现有的 API 密钥。可以更改原始密钥、启用状态、标签或项目分配。传入……

update-document — 管理 update document

• surgegraph-pp-cli update-document — 更新现有 SurgeGraph 文档的基本字段：标题、内容（HTML 正文）、元描述和／或 schema……

update-project-cms-integration — 管理 update project cms integration

• surgegraph-pp-cli update-project-cms-integration — 为项目连接或更改 CMS 集成（目前仅支持 WordPress）。使用 get_wordpress_integrations 来……

查找合适的命令

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

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

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

方案

周一 AI Visibility 回顾

surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --agent --select brand,metric,delta_pct

提取周环比变化最大的项目，并直接传入周一的 CMO 更新。

精简深度嵌套的引文响应

surgegraph-pp-cli get-ai-visibility-citations --project-id proj_abc123 --agent --select data.domains.domain,data.domains.citationCount

引文响应深度嵌套；点分路径 --select 可将负载控制在 Agent 的上下文预算内。

在本地缓存中查找某个主题的所有信号

surgegraph-pp-cli search "AI search optimization" --kind prompt,citation,doc,topic --agent --select kind,id,title,snippet

通过一次往返，对全部四种实体使用 FTS5；结果会统一并可排序。先运行 sync 来填充索引。

将所有缺口主题发布到 WordPress

surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run

串联 get_topic_map → create_bulk_documents → publish_document_to_cms；重试时具备幂等性。

将结果筛选为本地缓存中的一种引文类型

surgegraph-pp-cli search "answer engine" --kind citation --agent

通过 --kind 将 FTS 命中结果限制为一种实体类型；结合 --limit 控制输出范围。

身份验证设置

SurgeGraph 使用 OAuth 2.1，通过 https://mcp.surgegraph.io 实现 Authorization Code + PKCE + Dynamic Client Registration。运行一次 surgegraph-pp-cli auth login；CLI 会注册客户端，引导你完成浏览器流程，并保存 bearer 和 refresh token，供后续调用使用。auth status 会显示当前 TTL，auth logout 会清除这些信息。

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

Agent 模式

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

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

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

  surgegraph-pp-cli create-ai-visibility-prompt --intent example-value --agent --select id,name,status
  

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

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

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

Agent 反馈

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

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

条目保存在本地的 ~/.surgegraph-pp-cli/feedback.jsonl 中。除非设置了 SURGEGRAPH_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SURGEGRAPH_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅保存在本地。

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

输出传递

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

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

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

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果定时 Agent 每次运行都使用相同配置调用同一命令，请使用配置——这就是 HeyGen 的 “Beacon” 模式。

surgegraph-pp-cli profile save briefing --json
surgegraph-pp-cli --profile briefing create-ai-visibility-prompt --intent example-value
surgegraph-pp-cli profile list --json
surgegraph-pp-cli profile show briefing
surgegraph-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

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

claude mcp add surgegraph-pp-mcp -- surgegraph-pp-mcp

验证：claude mcp list

直接使用

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

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

4. 如果有歧义，请进一步查看子命令帮助：surgegraph-pp-cli <command> --help。