---
name: pp-substack
description: "在命令行中运行你的 Substack 增长与创作循环——发布富文本草稿、管理多出版组合、衡量增长驱动力。触发短语：`post a substack note`、`schedule a week of substack notes`、`find substack swap partners`、`which of my notes drove subs`、`what's my engagement reciprocity`、`voice-match a substack note`、`best time to post on substack`、`create a substack draft`、`sync my substack portfolio`、`top posts across my publications`、`search my substack posts`、`use substack`、`run substack`。"
author: "user"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - substack-pp-cli
    install:
      - kind: go
        bins: [substack-pp-cli]
        module: github.com/mvanhorn/printing-press-library/library/media-and-entertainment/substack/cmd/substack-pp-cli
---
<!-- 生成文件 — 请勿编辑。
     本文件是 library/media-and-entertainment/substack/SKILL.md 的逐字镜像，
     合并后由 tools/generate-skills/ 自动重新生成。在此处的手动编辑将在下次重新生成时
     被静默覆盖。请编辑 library/ 源文件。
     参见仓库代理指南中「生成产物：registry.json、cli-skills/」一节。 -->

# Substack — Printing Press CLI

## 前提条件：安装 CLI

本技能驱动 `substack-pp-cli` 二进制程序。**在调用本技能中的任何命令之前，你必须确认 CLI 已安装。** 如果缺失，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 `$HOME/.local/bin`；在 Windows 上默认安装到 `%LOCALAPPDATA%\Programs\PrintingPress\bin`：
   ```bash
   npx -y @mvanhorn/printing-press-library install substack --cli-only
   ```
2. 验证：`substack-pp-cli --version`
3. 确保报告的安装目录位于将调用本技能的代理/运行时的 `$PATH` 中。

如果 `npx` 安装失败（没有 Node、离线等），可回退到直接通过 Go 安装（需要 Go 1.26.3 或更新版本）：

```bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/substack/cmd/substack-pp-cli@latest
```

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

## 何时使用本 CLI

当代理需要端到端地运营 Substack 出版物时，请使用本 CLI：按节奏发布 Notes、起草和发布长文、与小众作者互动、寻找交换伙伴，以及衡量哪些内容真正带来了订阅增长。当你需要代理原生管道（`--json`、`--select`、`--dry-run`、类型化退出码）、离线优先的分析能力（每次关联查询均在本地 SQLite 上运行）、或覆盖那些工具未暴露的作者操作面时，它比 WriteStack/StackSweller 更合适。写操作（`engage like`、`engage restack`、`engage restack-with-comment`）默认打印等效的 curl 命令，仅在添加 `--send` 后才实际执行；请将打印的 curl 输出视为预检检查，而非实际的操作。

## 独特能力

以下是该 API 其他工具不具备的能力。

### 可累积的本地状态
- **`growth attribution`** — 将你发布的每条 Note 与其后 24 小时内实际到达的付费和免费订阅者关联起来，让你不再猜测哪些内容推动了增长。

  _当代理需要决定下周应重复哪些 Note 格式时，选择此命令而非通用统计调用。_

  ```bash
  substack-pp-cli growth attribution --days 30 --json --select rank,note_id,note_excerpt,subs_acquired,paid_subs_acquired
  ```
- **`engage reciprocity`** — 查看与你互动的每位作者的净给予/净索取情况——谁会对你的 restack/评论进行回馈，谁在默默搭便车。

  _当代理决定是否继续投资某个交换伙伴时使用；在关系冷却之前揭示其状态。_

  ```bash
  substack-pp-cli engage reciprocity --days 30 --agent --select handle,outgoing,incoming,net,drift
  ```

### 算法感知的自动化
- **`notes schedule --guard`** — 拒绝发布（或加入队列）一条距离你上一条自己的 Note 不足 30 分钟、或违反了你时段轮换规则的 Note。返回类型化退出码 2 并附带 JSON 诊断信息。

  _防止代理因一次性倾泻整个队列而意外破坏自身触达率。_

  ```bash
  substack-pp-cli notes schedule --at 2026-05-10T13:00:00Z --body "hook line\n\nbody" --guard --json
  ```
- **`growth best-time`** — 按你选择的增长信号（付费订阅、点赞、restack 或评论）排名的最佳星期×小时单元格——而非单一平均值。

  _当代理选择明天 Notes 的发布时间时，可以询问它正在优化的目标，而非猜测。_

  ```bash
  substack-pp-cli growth best-time --days 90 --for-goal subs --json --select day_of_week,hour,rate,sample_size
  ```

### 模式智能
- **`discover patterns`** — 机械地提取哪些钩子模式（好奇缺口冒号式、三句公式、破折号重构式、问句开头式）在某个细分领域中实际排名靠前，附带 restack/评论比率。

  _代理在撰写 Notes 时，可以在生成之前询问当前该细分领域中哪种钩子形状表现更好。_

  ```bash
  substack-pp-cli discover patterns --niche productivity --sort restacks --since 14d --agent --select pattern,sample_count,avg_restacks,avg_comments,top_example
  ```
- **`voice fingerprint`** — 可衡量的声音画像——句子长度、破折号使用率、冒号钩子率、钩子行比例、词汇独特性——针对任意用户句柄，通过 `--diff` 可与另一位作者进行对比。

  _代理为代笔客户撰写 Notes 时，可以验证输出是否保持在客户的声音范围之内。_

  ```bash
  substack-pp-cli voice fingerprint --handle maya --diff devon --json --select metric,self,other,delta
  ```

### 网络杠杆
- **`recs find-partners`** — 根据关注者与推荐图之间的重叠密度，为 Substack 推荐交换对候选出版物进行评分。

  _代理运行每周交叉推广时，可以对候选人进行排名，而非冷启动推销。_

  ```bash
  substack-pp-cli recs find-partners --my-pub on --top 20 --json --select rank,handle,pub,overlap_score,shared_followees
  ```
- **`growth pod`** — 给定一个句柄列表，生成成员×成员互动矩阵——过去 30 天内每对成员之间的 restack/评论/点赞情况。

  _代理组织互助小组时，无需电子表格即可查看谁净贡献为正、谁在搭便车。_

  ```bash
  substack-pp-cli growth pod --members maya,devon,priya,jordan --days 30 --json
  ```

### 富文本字段控制的创作

- **`drafts create` / `drafts update`** — 完整的 Substack 草稿 API 表面：30+ 个标记涵盖标题、副标题、正文（Markdown 自动转换为 ProseMirror）、栏目 ID、类型（newsletter/podcast/video/thread）、受众、署名、SEO 元数据、社交标题、封面图片、评论设置、播客/视频 URL 以及可见性开关。这是唯一一条让代理无需与网页编辑器斗争即可进行字段级控制的创作路径。

  _当代理需要从结构化数据（研究摘要、翻译稿件、代笔文章）构建完整的的长文帖子，并希望在一个命令中完成付费墙、SEO 和栏目设置时使用。_

  ```bash
  export SUBSTACK_PUBLICATION=mypub
  substack-pp-cli drafts create --title "Why X matters" \
    --body-file ./post.md --audience only_paid \
    --seo-title "X explained" --seo-description "How X affects Y" \
    --cover-image https://substackcdn.com/.../cover.jpg --json
  ```

### 投资组合与分析（本地列式存储）

以下命令读取由 `portfolio sync` 填充的**本地 SQLite 存储**。工作流程为：

```
auth login --chrome  →  export SUBSTACK_PUBLICATION=<your-pub>  →  portfolio sync  →  portfolio / posts best / grep / subs churn / …
```

支持自定义域名出版物：`auth login --chrome` 会自动捕获自定义域名的 Creator-session cookie。

- **`portfolio sync`** — 数据填充命令。发现你拥有的所有出版物，并将帖子、订阅者和草稿写入本地列式存储。在 `portfolio`、`posts best`、`grep`、`schedule board`、`subs churn` 和 `subs cross-sell` 能够返回跨出版物数据之前，必须先运行此命令。

  ```bash
  export SUBSTACK_PUBLICATION=mypub
  substack-pp-cli portfolio sync --json
  ```

- **`portfolio`** — 你拥有的每个出版物的一屏状态概览：订阅者数量、付费用户数量、已发布帖子数、待处理草稿数、下次计划发布时间。无需切换标签页，无需导出 CSV。

  ```bash
  substack-pp-cli portfolio --json
  ```

- **`posts best`** — 按阅读量、点赞数、评论数或 restack 数对帖子进行排名。`--cross-pub` 会汇总你所有出版物的数据。

  _当代理需要决定将哪些帖子移植到新出版物或放入每周通讯中时使用。_

  ```bash
  substack-pp-cli posts best --by restacks --window 30d --cross-pub --json
  substack-pp-cli posts best --by views --limit 5 --publication mypub-en
  ```

- **`posts twin <slug> --to <pub>`** — 将一篇已发布的帖子复制为你拥有的另一个出版物中的草稿。保留付费墙标记、栏目映射，并将图片重新上传到目标 CDN。

  ```bash
  substack-pp-cli posts twin my-en-slug --to mypub-de --dry-run --json
  substack-pp-cli posts twin my-en-slug --to mypub-de
  ```

- **`posts pair <en> <de>` / `posts pairs [--missing]`** — 在本地表中记录 EN↔DE 帖子配对。`--missing` 列出没有记录配对的帖子——将该列表输入 `posts twin` 即可补全缺失的翻译。

  ```bash
  substack-pp-cli posts pair my-en-slug my-de-slug
  substack-pp-cli posts pairs --missing --publication mypub-en --json
  ```

- **`grep <query>`** — 跨已同步的帖子、Notes 和评论进行 FTS5 全文搜索，按 bm25 排序，返回摘要和来源 URL。可选的 `--scope`、`--publication` 和 `--since` 过滤条件。

  ```bash
  substack-pp-cli grep "yield curve" --json
  substack-pp-cli grep "rate hike" --scope posts --publication mypub-en --since 2024-01-01
  ```

- **`schedule board`** — 未来 N 天的 ASCII 日历，显示你拥有的所有出版物中已安排的帖子。一屏即可查看多出版物的编辑概览。

  ```bash
  substack-pp-cli schedule board --days 30 --json
  ```

- **`subs churn`** — 对订阅者快照进行差分：谁新订阅、谁取消订阅、谁从免费升级到付费、谁从付费降级到免费。首次运行需先使用 `--snapshot` 创建基准线。

  ```bash
  substack-pp-cli subs churn --snapshot
  substack-pp-cli subs churn --since 7d --json --publication mypub-paid
  ```

- **`subs cross-sell`** — 至少在你一个出版物上付费、但在其他出版物上仍为免费或未订阅的邮箱地址。需要本地存储中有 2 个以上拥有的出版物。这是 Substack UI 不提供的交叉销售列表。

  ```bash
  substack-pp-cli subs cross-sell --json --limit 100
  ```

## 命令参考

**categories** — 全站 Substack 分类列表——文化、科技、美食等。

- `substack-pp-cli categories list` — 列出所有 Substack 分类
- `substack-pp-cli categories list-publications` — 列出某个分类下的出版物

**comments** — 长文帖子评论（区别于 Notes）

- `substack-pp-cli comments get` — 根据 ID 获取单条评论（结构与 Note 相同——Substack 将其统一对待）
- `substack-pp-cli comments list` — 列出帖子上的评论

**discover** — 发现功能——搜索出版物、嵌入元数据

- `substack-pp-cli discover` — 按查询条件搜索 Substack 出版物

**drafts** — 草稿的增删改查 + 发布 + 计划

- `substack-pp-cli drafts create` — 创建新草稿
- `substack-pp-cli drafts delete` — 删除草稿
- `substack-pp-cli drafts get` — 根据 ID 获取草稿
- `substack-pp-cli drafts list` — 列出草稿
- `substack-pp-cli drafts prepublish` — 验证草稿是否可发布；返回阻塞项
- `substack-pp-cli drafts publish` — 立即发布草稿
- `substack-pp-cli drafts schedule` — 安排草稿在未来发布（使用 `--post-date null` 取消安排）
- `substack-pp-cli drafts update` — 更新现有草稿

**feed** — 出版物的 RSS 订阅源

- `substack-pp-cli feed` — RSS XML 订阅源（返回 XML；使用 `--raw` 进行转储）

**images** — 图片上传（data-URI JSON，非 multipart）

- `substack-pp-cli images` — 上传图片；返回 CDN URL。请求体为 data-URI JSON。

**inbox** — 已认证读者的信息流（首页信息流）——当前用户的 Notes + 帖子

- `substack-pp-cli inbox home` — 已认证用户首页信息流
- `substack-pp-cli inbox reader-posts` — 当前用户的帖子信息流

**notes** — Substack Notes——短内容帖子（Substack 内部将 Notes 视为评论）

- `substack-pp-cli notes create` — 发布一条新 Note（POST /comment/feed）。请求体为 ProseMirror JSON。
- `substack-pp-cli notes get` — 根据 ID 获取单条 Note
- `substack-pp-cli notes list-by-profile` — 按用户资料列出 Notes（游标分页）
- `substack-pp-cli notes reply` — 回复现有 Note（parent_id + ProseMirror 请求体）

**grep** — 跨已同步的帖子、Notes 和评论进行全文搜索

- `substack-pp-cli grep <query>` — 按 bm25 排序的 FTS5 搜索，返回摘要和来源 URL。标记：`--scope posts|notes|comments|all`、`--publication`、`--since`、`--limit`

**portfolio** — 多出版物的状态仪表板和数据填充

- `substack-pp-cli portfolio` — 你拥有的每个出版物的一屏状态概览（订阅者、付费用户、帖子、草稿、下次计划时间）。先运行 `portfolio sync`。
- `substack-pp-cli portfolio sync` — 发现你拥有的所有出版物，并填充本地列式存储（publications/posts/subscribers/drafts）。是所有跨出版物分析命令的前提条件。

**posts** — 特定出版物上的长文帖子和归档

- `substack-pp-cli posts archive` — 出版物帖子的公开归档
- `substack-pp-cli posts best` — 按互动指标对缓存的帖子进行排名（`--by views|likes|comments|restacks`、`--window`、`--cross-pub`、`--limit`、`--publication`）
- `substack-pp-cli posts get-by-slug` — 根据 URL slug 获取已发布的帖子
- `substack-pp-cli posts list-published` — 列出出版物上已发布的帖子（需要认证）
- `substack-pp-cli posts pair <en-slug> <de-slug>` — 在本地表中记录 EN↔DE 翻译配对
- `substack-pp-cli posts pairs` — 列出已记录的帖子配对；`--missing` 显示没有配对的帖子；`--publication` 过滤到特定出版物
- `substack-pp-cli posts ranked-authors` — 出版物的作者排名列表
- `substack-pp-cli posts twin <slug> --to <pub>` — 将已发布的帖子复制为你拥有的另一个出版物中的草稿（重新上传图片，保留付费墙标记）

**profiles** — Substack 用户资料——你自己的和其他作者的

- `substack-pp-cli profiles from-linkedin` — 通过 LinkedIn 句柄查找 Substack 用户资料
- `substack-pp-cli profiles get-by-handle` — 按句柄获取公开用户资料（例如 mvanhorn）
- `substack-pp-cli profiles get-by-id` — 按数字用户 ID 获取公开用户资料
- `substack-pp-cli profiles handle-options` — 当前用户可用的句柄建议
- `substack-pp-cli profiles posts` — 某位作者在所有出版物上的全部帖子
- `substack-pp-cli profiles self` — 获取当前认证用户的资料

**recommendations** — Substack 推荐——对外推荐（我推荐的出版物）

- `substack-pp-cli recommendations <publication_id>` — 列出某个出版物推荐的出版物

**sections** — 出版物的栏目（newsletter 可以有多个栏目）

- `substack-pp-cli sections` — 列出栏目及其订阅情况

**settings** — 账户设置 + 连通性探测（由 doctor 使用）

- `substack-pp-cli settings get` — 获取账户设置
- `substack-pp-cli settings ping` — 连通性探测（由 doctor 使用的非破坏性 PUT）

**schedule** — 跨出版物的编辑排期

- `substack-pp-cli schedule board` — 未来 N 天（`--days`）所有拥有出版物的已排期帖子的 ASCII 日历

**subs** — 订阅者数量、流失差分和交叉销售分析

- `substack-pp-cli subs authors` — 列出出版物的署名作者
- `substack-pp-cli subs churn` — 对订阅者快照进行差分（新增/取消订阅/升级/降级）。使用 `--snapshot` 创建基准线，然后使用 `--since` 进行差分。标记：`--publication`、`--since`、`--snapshot`
- `substack-pp-cli subs count` — 获取订阅者数量（从 launch-checklist 载荷中读取）
- `substack-pp-cli subs cross-sell` — 在一个出版物上付费但在其他出版物上为免费或未订阅的邮箱地址（需要本地存储中有 2 个以上拥有的出版物）。标记：`--limit`

**tags** — 帖子标签

- `substack-pp-cli tags create` — 创建新标签
- `substack-pp-cli tags list` — 列出出版物的所有标签

## 新鲜度契约

本打印 CLI 仅对已注册的存储后端读取命令路径拥有有限的新鲜度保证。在 `--data-source auto` 模式下，这些路径会检查 `sync_state` 并可能在读取本地数据之前执行有限刷新。`--data-source local` 从不刷新。`--data-source live` 直接读取 API，不会修改本地存储。设置 `SUBSTACK_NO_AUTO_REFRESH=1` 可在不更改数据源选择的情况下跳过新鲜度检查钩子。

覆盖的路径：

- `substack-pp-cli categories`
- `substack-pp-cli categories get`
- `substack-pp-cli categories list`
- `substack-pp-cli categories search`
- `substack-pp-cli drafts`
- `substack-pp-cli drafts get`
- `substack-pp-cli drafts list`
- `substack-pp-cli drafts search`
- `substack-pp-cli inbox`
- `substack-pp-cli inbox get`
- `substack-pp-cli inbox list`
- `substack-pp-cli inbox search`
- `substack-pp-cli inbox-posts`
- `substack-pp-cli inbox-posts get`
- `substack-pp-cli inbox-posts list`
- `substack-pp-cli inbox-posts search`
- `substack-pp-cli posts`
- `substack-pp-cli posts get`
- `substack-pp-cli posts list`
- `substack-pp-cli posts search`
- `substack-pp-cli posts-published`
- `substack-pp-cli posts-published get`
- `substack-pp-cli posts-published list`
- `substack-pp-cli posts-published search`
- `substack-pp-cli posts-ranked`
- `substack-pp-cli posts-ranked get`
- `substack-pp-cli posts-ranked list`
- `substack-pp-cli posts-ranked search`
- `substack-pp-cli profiles`
- `substack-pp-cli profiles get`
- `substack-pp-cli profiles list`
- `substack-pp-cli profiles search`
- `substack-pp-cli sections`
- `substack-pp-cli sections get`
- `substack-pp-cli sections list`
- `substack-pp-cli sections search`
- `substack-pp-cli subs`
- `substack-pp-cli subs get`
- `substack-pp-cli subs list`
- `substack-pp-cli subs search`
- `substack-pp-cli tags`
- `substack-pp-cli tags get`
- `substack-pp-cli tags list`
- `substack-pp-cli tags search`

当 JSON 输出使用生成的出处信封时，新鲜度元数据出现在 `meta.freshness` 中。请将其视为所覆盖命令路径的当前缓存新鲜度，而非完整历史回填或特定 API 增强的保证。

### 找到正确的命令

当你清楚想做什么但不确定哪个命令可以完成时，直接向 CLI 询问：

```bash
substack-pp-cli which "<用你自己的话描述能力>"
```

`which` 会将自然语言能力查询解析为来自本 CLI 精选功能索引的最佳匹配命令。退出码 `0` 表示至少有一个匹配；退出码 `2` 表示没有置信匹配——回退到 `--help` 或使用更窄的查询。

## 实用配方

### 每日增长循环晨间仪式

```bash
substack-pp-cli growth attribution --days 7 --agent --select rank,note_excerpt,subs_acquired
```

显示昨天的 Note→订阅者胜出者。配合 `substack-pp-cli engage reciprocity --days 7 --agent` 查看谁的回馈与你对等，并在之前运行 `substack-pp-cli sync --since 24h` 保持本地存储新鲜。

### 使用节奏防护安排 Note

```bash
substack-pp-cli notes schedule --at 2030-05-13T09:00:00Z --body 'Tuesday hook line' --guard --json
```

将 Note 加入本地队列；如果计划时间距离现有自己的 Note 不足 30 分钟，`--guard` 将拒绝安排（类型化退出码 2 + JSON 诊断）。去掉 `--guard` 或添加 `--send` 可立即发布。

### 查找本周的交换伙伴

```bash
substack-pp-cli recs find-partners --my-pub on --top 5 --json --select rank,handle,pub,overlap_score
```

按受众重叠度对候选出版物进行排名；将结果导入你选择的外联草稿工具（substack-pp-cli 负责排名；外联草稿由你的代理提示词完成）。

### 以 JSON 格式捕获作者的声音指纹

```bash
substack-pp-cli voice fingerprint --handle alice --diff bob --json
```

所指定句柄的机械声音指标，当设置 `--diff` 时，与另一位作者进行对比。自行保存 JSON；代理生成提示词可以将其纳入。

### 使用 --select 提取深层嵌套的 Note 元数据

```bash
substack-pp-cli notes get c-12345 --agent --select id,body,attachments.url,attachments.image_url,attachments.published_bylines.name,attachments.published_bylines.handle,context.users.name
```

Notes 响应是深层嵌套的（附件、署名、上下文用户）。点分隔的 `--select` 可以缩小载荷范围，避免代理消耗上下文去解析不需要的 30KB JSON。

### 引导投资组合分析存储

```bash
substack-pp-cli auth login --chrome
export SUBSTACK_PUBLICATION=mypub
substack-pp-cli portfolio sync --json
substack-pp-cli portfolio --json
```

登录后运行一次。所有跨出版物分析命令（`posts best`、`grep`、`schedule board`、`subs churn`、`subs cross-sell`）都读取由 `portfolio sync` 填充的本地存储。

### 发布带有 SEO 和封面图片的富文本草稿

```bash
export SUBSTACK_PUBLICATION=mypub
substack-pp-cli drafts create \
  --title "The case for X" \
  --subtitle "Three reasons it matters now" \
  --body-file ./post.md \
  --audience only_paid \
  --seo-title "Case for X" \
  --seo-description "Why X matters for Y" \
  --cover-image https://substackcdn.com/.../cover.jpg \
  --json
```

自动将 Markdown 正文转换为 Substack 的 ProseMirror 格式。目标出版物从 `$SUBSTACK_PUBLICATION` 解析。去掉 `--audience only_paid` 可发布为公开帖子。

### 将最佳 EN 帖子移植到 DE 出版物

```bash
# 先同步，使本地存储包含最新帖子
substack-pp-cli portfolio sync --json

# 按 restack 数查找最佳帖子
substack-pp-cli posts best --by restacks --limit 1 --publication mypub-en --json

# 预览移植操作，然后创建草稿
substack-pp-cli posts twin my-en-slug --to mypub-de --dry-run --json
substack-pp-cli posts twin my-en-slug --to mypub-de --json
```

### 每周订阅者流失摘要

```bash
# 每周运行一次（通过 cron 或代理计划自动化）
substack-pp-cli subs churn --since 7d --json --publication mypub-paid
```

首次运行需要创建基准线：`substack-pp-cli subs churn --snapshot`。之后，`--since 7d` 将该时间窗口内最近的快照进行对比。

### 跨所有出版物进行全文搜索

```bash
substack-pp-cli grep "interest rates" --scope posts --json
substack-pp-cli grep "reader question" --scope notes --since 2025-01-01 --limit 20 --json
```

## 认证设置

Substack 使用会话 cookie（substack.sid）。目前唯一的方式是 `auth login --chrome`（也接受 `--browser` 作为别名）——它通过 pycookiecheat / cookies / cookie-scoop-cli 从你已登录的 Chrome 中读取 cookie 并将其存储在操作系统密钥环中。没有密码登录方式，也没有手动粘贴 cookie 的子命令。如果 cookie 过期，请重新运行 `auth login --chrome`。

运行 `substack-pp-cli doctor` 验证设置。

## 代理模式

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

- **可管道化** — JSON 输出到 stdout，错误输出到 stderr
- **可过滤** — `--select` 保留字段子集。点分隔路径可深入嵌套结构；数组按元素遍历。对于在冗长 API 上保持上下文简洁至关重要：

  ```bash
  substack-pp-cli categories list --agent --select id,name,status
  ```
- **可预览** — `--dry-run` 显示请求但不发送
- **离线友好** — sync/search 命令在可用时可使用本地 SQLite 存储
- **非交互** — 从不提示，每个输入都是标记
- **显式重试** — 仅在已存在的创建应算作成功时使用 `--idempotent`，仅在缺失的删除目标应算作成功时使用 `--ignore-missing`

### 响应信封

从本地存储或 API 读取的命令会将输出包裹在出处信封中：

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

解析 `.results` 获取数据，解析 `.meta.source` 了解数据是实时的还是本地的。仅在 stdout 是终端且未设置任何机器格式标记（`--json`、`--csv`、`--compact`、`--quiet`、`--plain`、`--select`）时，人类可读的 `N results (live)` 摘要会打印到 stderr——管道/代理消费者和显式格式运行会在 stdout 上获得纯 JSON。

## 代理反馈

当你（或代理）发现本 CLI 的异常之处时，记录下来：

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

条目本地存储在 `~/.local/share/substack-pp-cli/feedback.jsonl`。除非设置了 `SUBSTACK_FEEDBACK_ENDPOINT` 并且传递了 `--send` 或设置了 `SUBSTACK_FEEDBACK_AUTO_SEND=true`，否则不会 POST 出去。默认行为仅为本地存储。

写下让你**感到意外**的内容，而非错误报告。简短、具体、一行即可：这些才是能累积价值的内容。

## 输出投递

每个命令都接受 `--deliver <sink>`。输出会发送到指定的接收端，作为 stdout 的补充或替代，这样代理无需手动管道即可路由命令结果。支持三种接收端：

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

未知方案会被拒绝，并返回包含支持集的错误信息。Webhook 失败返回非零退出码，并将 URL + HTTP 状态记录到 stderr。

## 命名配置文件

配置文件是一组已保存的标记值，可在多次调用中复用。当定时代理每次运行都使用相同配置调用相同命令时使用——即 HeyGen 的「Beacon」模式。

```
substack-pp-cli profile save briefing --json
substack-pp-cli --profile briefing categories list
substack-pp-cli profile list --json
substack-pp-cli profile show briefing
substack-pp-cli profile delete briefing --yes
```

显式标记始终优先于配置文件值；配置文件值优先于默认值。`agent-context` 在 `available_profiles` 下列出所有可用配置文件，以便内省代理在运行时发现它们。

## 退出码

| 代码 | 含义 |
|------|---------|
| 0 | 成功 |
| 2 | 使用错误（参数错误） |
| 3 | 资源未找到 |
| 4 | 需要认证 |
| 5 | API 错误（上游问题） |
| 7 | 被限速（等待后重试） |
| 10 | 配置错误 |

## 参数解析

解析 `$ARGUMENTS`：

1. **空、`help` 或 `--help`** → 显示 `substack-pp-cli --help` 输出
2. **以 `install` 开头** → 以 `mcp` 结尾 → MCP 安装；否则 → 参见上方「前提条件」
3. **其他任何内容** → 直接使用（以 `--agent` 作为 CLI 命令执行）

## MCP 服务器安装

1. 安装 MCP 服务器：
   ```bash
   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/substack/cmd/substack-pp-mcp@latest
   ```
2. 注册到 Claude Code：
   ```bash
   claude mcp add substack-pp-mcp -- substack-pp-mcp
   ```
3. 验证：`claude mcp list`

## 直接使用

1. 检查是否已安装：`which substack-pp-cli`
   如果未找到，提供安装选项（参见本技能顶部的「前提条件」）。
2. 将用户查询匹配到上方「独特能力」和「命令参考」中的最佳命令。
3. 使用 `--agent` 标记执行：
   ```bash
   substack-pp-cli <command> [subcommand] [args] --agent
   ```
4. 如果存在歧义，深入子命令帮助：`substack-pp-cli <command> --help`。