pp-linear

Linear — Printing Press CLI

前提条件：安装 CLI

此 skill 使用 linear-pp-cli 二进制文件。**此 skill 激活时，请勿调用名为 linear 的命令。**如果缺少 linear-pp-cli，请先安装：

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-cli@latest

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

Agent 约定

• 除非明确需要面向人类的表格，否则命令都应添加 --agent。它会启用 JSON、紧凑输出、非交互模式、无颜色以及适用于安全确认的脚本行为。
• 对于需要当前真实状态的关闭、状态和描述检查，请使用 --data-source live。使用 issues search 检查重复项；它会刷新过期的问题搜索数据，或明确报错。只有在有意使用过期/离线本地数据进行重复项搜索时，才使用 --data-source local 或 similar。
• 紧凑输出中未显示的字段并不代表它们不存在于问题中。请明确请求这些字段，包括嵌套标签：linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.name,labels.nodes.id,labels.nodes.name,url。
• 一次调用中使用逗号分隔的标识符，获取多个已知问题：linear-pp-cli issues ENG-123,ENG-124 --agent。结果数组会保留调用方的顺序，并删除重复的标识符；如果其中一个标识符不存在，整个读取操作都会失败，而不会返回部分结果。
• 优先使用此处展示的规范读取和评论形式。常见的 Agent 表述也受支持，且不会改变行为：issues get|view|show ENG-123、documents get|view <ref> 和 comments create 分别是 issues ENG-123、documents <ref> 和 comments add 的兼容别名。这些别名支持与对应规范命令相同的全局标志、逗号分隔的读取、正文文件、目标和媒体标志；刻意不提供 documents show 别名。
• --label 仅接受 UUID；--label-name 会在写入时解析完全匹配的标签名称（由团队所有或全工作区通用）。向 issues create 或 issues edit 传入 UUID 前，请先运行 linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key。CLI 会预先检查所有权，并在修改前拒绝跨团队标签。
• 切勿将多行 Markdown、Shell 片段、GraphQL、日志、反引号、$() 展开或富媒体内容作为内联 Shell 参数传递。请将正文写入文件或 stdin，并使用下方的 *-file / *-stdin 标志。

何时使用此 CLI

当你需要跨问题、周期、项目和里程碑进行联表查询时，请使用此 CLI。这类问题需要 Linear UI 跨多个标签页才能回答，也需要 API 多次往返才能回答。对于通过 MCP 使用 Linear 的 Agent（编排组合与命名意图可用约 1K 个 token 覆盖完整功能），对于准备周五更新的工程经理（周期对比、延期项、燃尽图、阻塞队列），以及任何必须在 pp_created fixture-lifecycle 约定下修改真实工作区的 Agent，这都是合适的选择。

独特能力

这些能力是此 API 的其他工具所不具备的。

可累积的本地状态

• today — 查看你今天在所有团队中负责的事项，并按优先级和周期截止日期排序。

  当 Agent 或人员需要一个跨所有团队的统一排序工作队列，而不想指定底层关联查询时，使用此工具。

  linear-pp-cli today --json --agent
  

• bottleneck — 在冲刺规划前查看哪些团队成员超负荷，以及哪些事项受阻。

  在冲刺规划时，如果需要在一个视图中查看谁超负荷、哪些工作卡住了，请使用此工具。

  linear-pp-cli bottleneck --team ENG --json
  

• stale — 查找 N 天内未更新的事项，并按团队和项目分组。

  在待办事项梳理期间，如果需要找出被遗忘的事项，同时避免耗尽 API 速率限制，请使用此工具。

  linear-pp-cli stale --days 30 --team ENG --json
  

• issues search / similar — 使用本地 FTS5 搜索，查找与查询字符串相似、可能重复的事项。

  在分诊期间，如果怀疑新收到的 Bug 与现有事项重复，请使用此工具。

  linear-pp-cli issues search "login redirect bug" --limit 5 --agent
  linear-pp-cli issues search "pipeline follow-up" --team SYMPH --limit 10 --agent
  linear-pp-cli similar "login redirect bug" --limit 5 --json
  linear-pp-cli similar "pipeline follow-up" --team SYMPH --limit 10 --agent
  

  创建或更新后续工作前检查是否已有相关工单时，优先使用 issues search；这是 Agent 通常会使用的受支持事项搜索写法。它会协调重复检查所需的数据新鲜度：立即搜索新鲜的本地数据；如果事项数据过期或为空，则在跨进程锁的保护下刷新后再搜索；如果刷新失败，则返回带类型的错误，而不是静默提供过期结果。当常见项目名称或标签出现在多个团队中，且重复检查必须限定在目标团队的队列内时，添加 --team <key-name-or-uuid>。issues search 的多词查询可以加引号，也可以作为单独的词传入；这两种形式都会合并为一个 FTS 查询。在 --agent / --json 模式下，issues search 会返回包含新鲜度元数据的来源信息封装；similar 则保留旧版原始结果数组。仅当有意使用过期或离线的本地结果时，才使用 --data-source local。

跨实体汇总

• projects burndown — 根据团队测得的速度，对剩余估算进行线性回归，预测项目的完成日期。

  当利益相关者询问项目何时完成，而项目页面只显示几个月前由某人填写的静态目标日期时，请使用此工具。

  linear-pp-cli projects burndown PROJ_ID --weeks 8 --json
  

• cycles compare — 并排比较任意两个周期的指标：完成率、增加的范围、缩减的范围、结转事项、平均周期时间。

  在周期回顾和周五更新时，如果需要数值差异而不是打开两个浏览器标签页，请使用此工具。

  linear-pp-cli cycles compare 42 43 --json
  

• slipped — 显示从上个周期结转到本周期的事项，并按团队和原因启发式分组。

  在周五向利益相关者更新时，如果需要结构化的上周期结转事项列表，而不只是一个已保存视图，请使用此工具。

  linear-pp-cli slipped --team ENG --json
  

• velocity — 跟踪过去 N 个周期的冲刺完成率，以发现生产力趋势。

  在周一进行冲刺规划时，根据实际完成数据而非仅依据团队上个周期的表现来制定重新平衡决策，请使用此工具。

  linear-pp-cli velocity --weeks 8 --json
  

• initiatives health — 按计划汇总每项计划的组合视图：子项目进度、里程碑目标日期与预测日期、延期标记。

  在组合审查中，如果利益相关者需要计划级汇总，而不是打开七个项目标签页，请使用此工具。

  linear-pp-cli initiatives health --json
  

• milestones at-risk — 列出预测完成日期已晚于目标日期的组合里程碑，并按延期幅度排序。

  在每周组合审查中，如果要了解哪个里程碑风险最高，而不是哪个计划进展健康，请使用此工具。

  linear-pp-cli milestones at-risk --json
  

个人队列

• blocking — 显示你正在阻塞的事项，并按下游影响排序（下游事项数量 × 下游优先级）。

  每天早上，如果需要了解你正在处理的哪些事项会拖慢下游队友，请使用此工具。

  linear-pp-cli blocking --json
  

面向 Agent 的基础设施

• pp-test list — 列出此 CLI 在当前会话或指定会话中创建的 Linear 事项，然后使用 pp-cleanup 将其归档。 当 Agent 需要仅清理自己在某个会话中创建的工单时，使用此功能——不得触碰工作区中已有的数据。

  linear-pp-cli pp-test list --json
  

• issues create --trust-mode strict — 设置 --trust-mode strict 时，拒绝修改本地 pp_created 账本中没有记录的 Linear 工单；适用于创建操作和今后任何修改入口。

  当 Agent 在包含真实数据的真实工作区中运行时，使用此功能——严格模式可避免意外修改。

  linear-pp-cli issues create --title "Test ticket" --team ENG --trust-mode strict
  

• 父级与子工单关联 — 创建子工单并设置、更改或清除父级关联，无需离开 CLI 使用原始 GraphQL。

  当 Agent 创建工单树、史诗或后续任务层级，并需要安全地配置父子关系时，使用此功能。

  linear-pp-cli issues create --title "Child task" --team ENG --parent ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-124 --parent ENG-123 --agent
  linear-pp-cli issues edit ENG-124 --no-parent --agent
  

• 团队安全的工单标签 — 查找适用于目标 Linear 团队的标签，包括全局标签，然后通过 UUID 或完全匹配的名称附加标签。

  附加标签前，使用此功能。--label 仅接受 UUID；输入的是人工可读的标签名称时，请使用 --label-name。Linear 会拒绝归属其他团队的标签，而 CLI 会在修改前预检标签归属。

  linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key
  linear-pp-cli issues create --title "Title" --team ENG --label <global-or-eng-label-id> --agent
  linear-pp-cli issues create --title "Title" --team ENG --label-name "kind:bug" --label-name "source:user-report" --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --dry-run --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --agent
  

  --label-name 始终会实时读取 Linear 以解析 UUID，即使关联的工单写入操作处于试运行模式也是如此。写入要求标签名称规范化后完全匹配。团队拥有的标签和工作区全局标签（没有团队）都可解析；归属其他团队的标签则不可解析。--label 和 --label-name 可以组合使用；修改前会对解析出的 ID 去重。创建时，CLI 会验证修改操作返回的标签 ID；如果 Linear 未附加所请求的标签集合，则会明确报错；退出码为 5 的 Agent 信封包含 created_issue.id、created_issue.identifier 和 created_issue.url，以便在本地无法持久化时仍能找回远程工单。

• 项目和倡议名称解析 — 写入工单关系前，按人工可读名称解析组合对象。

  当用户提供工单标识符以及项目或倡议名称时，使用此功能。--project 仅接受 UUID；输入的是人工可读的项目名称时，请使用 --project-name。

  linear-pp-cli projects list --agent --select id,name,team.key,state,url
  linear-pp-cli projects search "Autonomous Backlog Manager & Dispatch Governance" --team SYMPH --agent --select id,name,team.key,initiative.name,url
  linear-pp-cli initiatives list --agent --select id,name,status,url
  linear-pp-cli initiatives search "Dispatch Governance" --agent --select id,name,status,url
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --dry-run --agent
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --agent
  

  --project-name 始终会实时读取 Linear 以解析 UUID，即使关联的工单写入操作处于试运行模式也是如此。名称不完整时，请先使用 projects search；写入要求项目名称规范化后完全匹配。

• 支持媒体内容且对 Shell 安全的 Linear 写入 — 创建和更新工单描述、评论及 Linear 文档，无需在 Shell 命令行中放入 Markdown 正文。

  正文包含换行、引号、反引号、$() 展开、Shell 命令、图片、日志或 Agent 生成的 Markdown 时，使用此功能。

  linear-pp-cli issues create --title "Title" --team ENG --description-file /tmp/body.md --media /tmp/screenshot.png --agent
  linear-pp-cli issues edit ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-123 --media /tmp/screenshot.png --agent
  linear-pp-cli comments add --issue ENG-123 --body-file /tmp/comment.md --media /tmp/screenshot.png --agent
  linear-pp-cli comments edit <comment-id> --body-file /tmp/comment.md --agent
  linear-pp-cli documents create --title "Runbook" --issue ENG-123 --content-file /tmp/runbook.md --agent
  linear-pp-cli documents create --title "Team runbook" --team ENG --content-file /tmp/runbook.md --agent
  linear-pp-cli documents edit <document-id-or-slug> --content-file /tmp/updated.md --agent
  

  documents create 必须且只能指定一个父级（--issue、--project、--team、--initiative、--cycle、--release 或 --folder）；--team 接受 ENG 之类的键或 UUID。使用 issues edit --media、comments edit --media 或 documents edit --media 且不带正文/内容标记时，会实时获取现有 Markdown 并追加上传媒体的链接。图片会转换为 Markdown 图片嵌入；非图片会转换为 Markdown 链接。仅当上传的资源必须能在 Linear 工作区之外访问时，才添加 --media-public。

• 读取当前工单和评论 — 读取完整工单正文和讨论内容，无需回退到过时的本地状态。comments list 将工单作为位置参数（推荐）或通过 --issue 接收。

  linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.id,state.name,labels.nodes.id,labels.nodes.name,url
  linear-pp-cli issues ENG-123,ENG-124 --agent --data-source live --select identifier,title,description,state.name,url
  linear-pp-cli comments list ENG-123 --agent
  linear-pp-cli comments list --issue ENG-123 --agent --limit 100
  

• 状态转换 — 无需原始 SQL、GraphQL 或通过 api 探查，即可在工作流状态之间移动工单。具体步骤：

  1. 列出工单所属团队的状态：workflow-states list --team <key>（别名：states list）。
  2. 按 name 或 type 选择目标状态，并复制其 id UUID。
  3. 将该 UUID 传给 issues edit --state。

  linear-pp-cli workflow-states list --team ENG --agent --select id,name,type
  linear-pp-cli issues edit ENG-123 --state <state-uuid> --agent
  

  或者，跳过查询，使用针对工单所属团队解析的一条命令完成状态转换：

  linear-pp-cli issues edit ENG-123 --state-name "In Progress" --agent
  linear-pp-cli issues edit ENG-123 --state-type started --agent   # usage error if the team has several 'started' states
  

  issues create 使用同一组三种参数，并根据 --team 解析，因此 issue 可以直接以正确状态创建。--state 需要 UUID（非 UUID 值会导致用法错误，并提示使用 --state-name）：

  linear-pp-cli issues create --title "..." --team ENG --state-name "In Progress" --agent
  

  不要将 linear-pp-cli api 或 linear-pp-cli sql 用于工作流状态 — api 仅提供生成的 REST 形式接口（目前为 integrations），不提供 Linear GraphQL 对象。

• Linear 文档读取 — documents <ref> 接受 Linear 提供的所有标识符形式：文档 UUID、裸 slugId（f7f48ab36080）、完整 URL slug（my-runbook-f7f48ab36080）或整个文档 URL。直接复制你拥有的任一形式即可；无需进行 slug 截断或解析适配。

  linear-pp-cli documents my-runbook-f7f48ab36080 --agent --select title,updatedAt,content
  linear-pp-cli documents "https://linear.app/<org>/document/my-runbook-f7f48ab36080" --agent
  

命令参考

attachments — 管理附件

• linear-pp-cli attachments <id> — 获取单个附件

audit-entry-types — 管理审计条目类型

• linear-pp-cli audit-entry-types — 获取单个审计条目类型

auth-resolver-responses — 管理身份验证解析器响应

• linear-pp-cli auth-resolver-responses — 获取单个身份验证解析器响应

authentication-session-responses — 管理身份验证会话响应

• linear-pp-cli authentication-session-responses — 获取单个身份验证会话响应

email-intake-addresses — 管理电子邮件接收地址

• linear-pp-cli email-intake-addresses <id> — 获取单个电子邮件接收地址

favorites — 管理收藏项

• linear-pp-cli favorites <id> — 获取单个收藏项

initiative-relations — 管理计划关系

• linear-pp-cli initiative-relations <id> — 获取单个计划关系

initiative-to-projects — 管理计划与项目的关联

• linear-pp-cli initiative-to-projects <id> — 获取单个计划与项目的关联

initiatives — 管理计划

• linear-pp-cli initiatives <id> — 获取单个计划
• linear-pp-cli initiatives list — 列出 Linear 计划
• linear-pp-cli initiatives search <query> — 按名称搜索 Linear 计划
• linear-pp-cli initiatives resolve <name> — 将一个 Linear 计划名称解析为其 UUID

integrations — 管理集成

• linear-pp-cli integrations create — 创建集成
• linear-pp-cli integrations delete — 删除集成

issue-priority-values — 管理 issue 优先级值

• linear-pp-cli issue-priority-values — 获取单个 issue 优先级值

labels — 列出带有团队归属信息的 Linear issue 标签

• linear-pp-cli labels list --team ENG — 列出全局标签以及归属于目标团队的标签

organizations — 管理组织

• linear-pp-cli organizations — 获取单个组织

project-labels — 管理项目标签

• linear-pp-cli project-labels <id> — 获取单个项目标签

project-milestones — 管理项目里程碑

• linear-pp-cli project-milestones <id> — 获取单个项目里程碑

project-relations — 管理项目关系

• linear-pp-cli project-relations <id> — 获取单个项目关系

project-statuses — 管理项目状态

• linear-pp-cli project-statuses <id> — 获取单个项目状态

project-updates — 创建和列出 Linear 项目更新（项目状态动态）

• linear-pp-cli project-updates list --project <uuid> --agent — 列出某个项目的更新
• linear-pp-cli project-updates list --project-name "My Project" --limit 10 --agent — 按项目名称列出更新
• linear-pp-cli project-updates create --project <uuid> --body-file /tmp/update.md --health onTrack --agent — 发布带有 Markdown 正文的项目更新
• linear-pp-cli project-updates create --project-name "My Project" --body "Sprint on track." --health onTrack --agent — 按项目名称发布更新
• linear-pp-cli project-updates create --project <uuid> --body-stdin --health atRisk --agent < /tmp/update.md — 从标准输入发布更新

projects — 管理项目

• linear-pp-cli projects <id> — 获取单个项目
• linear-pp-cli projects list — 列出 Linear 项目
• linear-pp-cli projects search <query> — 按名称搜索 Linear 项目
• linear-pp-cli projects resolve <name> — 将单个 Linear 项目名称解析为其 UUID

release-notes — 管理 release-notes

• linear-pp-cli release-notes <id> — 获取单个 releasenote

release-pipelines — 管理 release-pipelines

• linear-pp-cli release-pipelines — 获取单个 releasepipeline

release-stages — 管理 release-stages

• linear-pp-cli release-stages <id> — 获取单个 releasestage

releases — 管理 releases

• linear-pp-cli releases <id> — 获取单个 release

roadmap-to-projects — 管理 roadmap-to-projects

• linear-pp-cli roadmap-to-projects <id> — 获取单个 roadmaptoproject

roadmaps — 管理 roadmaps

• linear-pp-cli roadmaps <id> — 获取单个 roadmap

teams — 管理 teams

• linear-pp-cli teams — 获取单个 team

templates — 管理 templates

• linear-pp-cli templates — 获取单个 template

user-settingses — 管理 user-settingses

• linear-pp-cli user-settingses — 获取单个 usersettings

users — 管理 users

• linear-pp-cli users — 获取单个 user

workflow-states — 列出 Linear 工作流状态（别名：states）

• linear-pp-cli workflow-states list --team ENG --agent --select id,name,type — 列出某个团队的状态及其 UUID，issues edit --state 需要这些 UUID

找到正确的命令

当你知道想做什么，但不知道哪个命令能做到时，直接询问 CLI：

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

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

对于重复项检查，linear-pp-cli which "search issues by text" --agent 应指向 issues search；请使用它，而不是自创 issues search --help 回退方案或原始 SQL。如果本地 issue 缓存已过期，issues search 会刷新它，或失败并返回带类型的新鲜度错误；Agent 不应仅仅因为缓存过期就直接转向原始 GraphQL。 对于父/子 issue 关联，linear-pp-cli which "set issue parent" --agent 应指向 issues edit --parent。

实操示例

周五利益相关者更新

linear-pp-cli cycles compare current previous --json --select completionPct,scopeAdded,scopeCut,carryover,meanCycleTimeHours

当前周期与上一周期的两行差异，范围收窄到写入利益相关者文档的五个字段 — 通过管道传给任意大模型来撰写文字。

Agent 的每日待办

linear-pp-cli today --json --agent --select id,identifier,title,state.name,cycle.endsAt,priority

已排序的工作队列，只包含 Agent 决定要接哪项工作所需的字段；--agent 启用 agent-mode 信封，--select 将负载从每行几 KB 收窄到约 200 字节。

冲刺规划再平衡

linear-pp-cli bottleneck --team ENG --json | jq '.[] | select(.loadIndex > 1.2)'

拉取每位负责人的负载并通过管道传给 jq 以筛出过载部分 — 瓶颈命令暴露连接关系；jq 负责过滤，因此命令保持可组合。

待办事项梳理清扫

linear-pp-cli stale --days 60 --team ENG --json --select identifier,title,assignee.name,updatedAt

过期 issue 扫描，配合精心选择的 --select 投影，小到足以在多次调用间保留在上下文中。

Agent 测试夹具清理

linear-pp-cli pp-test list --session current --json && linear-pp-cli pp-cleanup --session current

列出并仅归档此 CLI 在当前会话中创建的 issue — 绝不触碰预先存在的工作区数据。

认证设置

Linear 个人 API 密钥原样放入 Authorization 头 — 不加 Bearer 前缀。运行 linear-pp-cli auth set-token lin_api_yourkeyhere 保存你的密钥（Linear 个人 API 密钥无需 Bearer 前缀），或导出 LINEAR_API_KEY=lin_api_...。个人 API 密钥作用域为工作区；doctor 命令一次性校验认证、API 连通性和存储健康状况。

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

新鲜度与数据来源（在 Agent 循环中驱动前请先阅读）

命令分为三类，数据源语义各不相同。使用 --data-source auto|live|local 控制读取数据的来源；使用 --max-age <duration> 设置“本地数据已过时”提示的阈值。

类别 1：优先读取实时数据，失败时回退到本地（由规范生成的命令以及经 v4 重构的 issues list/get）

• attachments <id>、projects get <id>、teams <id>、initiatives get <id>、issues <id>、issues list 等。
• 默认（--data-source auto）：调用 Linear API，并将响应写入本地存储；仅在网络错误（DNS／超时／连接被拒绝）时回退到本地存储。4xx 和 5xx 错误会直接返回，不会悄悄使用过时数据。
• --data-source live：始终调用 API；不回退。当 Agent 必须获取最新数据，宁愿明确失败也不愿提供过时数据时使用。
• --data-source local：绝不调用 API。在严格控制的 Agent 循环中使用，以节省 Linear 的复杂度预算（个人密钥每小时约 1500 点）。
• teams 和 projects get 等提升为一等命令的 Linear GraphQL 读取操作，内部使用 POST /graphql。不要将其改写为 shell 层级的 GET /graphql 调用；Linear 会因 CSRF／预检错误拒绝这种请求形式。

类别 2：基于快照计算（因必要性只能使用本地数据）

• today、bottleneck、blocking、similar、velocity、slipped、cycles compare、projects burndown、initiatives health、milestones at-risk
• 这些命令会对已同步的数据集执行联接／聚合／FTS5 匹配——Linear API 没有任何单个实时调用能返回这些数据结构。--data-source 标志会被忽略；它们始终从本地存储读取。
• 使用这些命令前必须先运行 sync。 冷启动提示：结果为空时，会向 stderr 输出 (no <resource> in local store — run 'linear-pp-cli sync' to populate)。
• 过时数据提示：如果本地存储的同步时间超过 --max-age（默认 30 minutes），读取时会向 stderr 输出 (<resource> data is Xm old, exceeds --max-age=30m — run 'linear-pp-cli sync' to refresh)。--json 输出保持干净（提示仅输出到 stderr）。

协调数据新鲜度的本地搜索

• issues search
• 使用本地 FTS issue 索引，但会为重复项检查协调数据新鲜度。如果 issues 数据足够新鲜，则立即搜索。如果 issues 数据已过时或为空，则会获取跨进程锁，刷新 teams、workflow states、labels 和 issues，然后执行搜索。
• 如果刷新失败，--agent 会输出带类型的 JSON 错误，而不会返回基于过时数据的重复项搜索结果。Agent／JSON 输出采用带有新鲜度元数据的来源信息封装；refreshed 表示本次调用期间本地 issue 数据发生了变化，refreshed_by 用于标识执行刷新的是本进程、同级进程还是外部同步。仅在明确要使用离线／过时模式时，才使用 --data-source local；JSON 元数据会标记此过时本地数据策略。仅在有意禁用新鲜度检查时，才使用 --max-age 0；元数据会标记 freshness_gate_disabled。空的本地存储会标记为 unsynced。

类别 3：修改操作

• issues create、issues edit、comments add、comments edit、documents create、documents edit、pp-cleanup
• 始终调用 API。成功后，会清除 HTTP 响应缓存，并将新建／变更的实体写回本地存储，因此后续执行 issues list --data-source local 无需再次同步即可看到修改。

仅实时读取的协作数据

• comments list、documents <id-or-slug>、documents list
• 这些命令会读取当前 Linear API 数据，因为评论和工作会话文档属于协作数据；与其提供帮助有限，过时的本地状态反而更容易造成误导。

标签发现

• labels list --team ENG
• 默认情况下（--data-source auto），会读取实时数据，并返回全局标签以及归属指定团队的标签。--data-source local 会在 linear-pp-cli sync 后读取已同步的 issue_labels 表。
• 使用返回的 ID 执行 issues create --label 或 issues edit --label，也可以在创建或编辑时使用 --label-name，跳过 UUID 查询。其他团队拥有的跨团队标签 ID 和名称会在发送问题变更前被拒绝。

节省预算的 Agent 循环：

# 1. Hydrate once (one batched query for everything)
linear-pp-cli sync

# 2. Read freely — store-backed, zero budget
linear-pp-cli today
linear-pp-cli bottleneck --team ENG --data-source local

# 3. Mutate — write-back keeps the store fresh
linear-pp-cli issues create --title "..." --team ENG --pp-session "$SESSION"

# 4. Verify the mutation from local (no extra API call)
linear-pp-cli issues list --data-source local --pp-session "$SESSION"

# 5. Re-sync every ~30 minutes if the session is long
linear-pp-cli sync

清理约定：

每次 issues create 都会将新工单记录在本地 pp_created 表中，并标记所属会话（默认值：时间戳；可通过 --pp-session <tag> 或 PP_SESSION 环境变量覆盖）。pp-cleanup --session <tag> 只会通过真实的 Linear 归档变更归档这些工单。--trust-mode strict 会拒绝对未记录在 pp_created 中的问题执行变更；与会话标签搭配使用，可为防止 Agent 污染工作区设定严格底线。

Agent 模式

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

• 可通过管道传递 — JSON 输出到 stdout。失败时也会返回 JSON：在 --agent/--json 模式下，每种类型化错误（usage、not-found、auth、API、rate-limit、config）都会在 stdout 上输出一行错误信封，因此可以安全地将 stdout 直接传给 JSON 解析器：

  {"error":"document \"missing-doc\" not found","code":3,"type":"not_found"}
  

  进程仍会使用退出代码表中的类型化代码退出；type 是对应的机器可读名称（usage、not_found、auth、api、partial_failure、rate_limit、config）。读取路径无需使用 2>&1 | python json 这类防御性包装。

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

  linear-pp-cli attachments mock-value --agent --select id,name,status
  

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

• 支持离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用它

• 非交互式 — 不会显示提示；所有输入均通过标志传入

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当目标不存在的删除操作应视为成功时才使用 --ignore-missing

响应信封

从本地存储或 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 反馈

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

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

条目会保存在本地的 ~/.linear-pp-cli/feedback.jsonl。除非设置了 LINEAR_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 LINEAR_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”模式。

linear-pp-cli profile save briefing --json
linear-pp-cli --profile briefing attachments mock-value
linear-pp-cli profile list --json
linear-pp-cli profile show briefing
linear-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

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

claude mcp add linear-pp-mcp -- linear-pp-mcp

验证：claude mcp list

直接使用

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

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

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