基于用户影响的 PR 定价实践：解读 obsidian-copilot 的 pr-pricing 智能体（.claude/agents/pr-pricing.md）

• AI 应用
• 大模型
• AI Agent
• 交互助手
• RAG

导读

本文围绕 obsidian-copilot（在 Obsidian 中运行 OpenCode、Codex、Claude Code 等 Agent 的插件）仓库内的 .claude/agents/pr-pricing.md 展开，系统拆解这个 Claude Code 智能体的完整设计：它如何以**用户可见影响（user-facing impact）**为第一原则，用六档定价层级（XS–XXL）为每个 PR 定级定价，并以统一的 Markdown 表格输出。读完本文，你将掌握一套可直接复制到任何开源项目中的 PR 规模评估与定价方法论，包括定档规则、校准样本、五步工作流和对应的ghCLI 命令。

一、Agent 是什么：一份 Markdown 定义文件背后的运行机制

.claude/agents/pr-pricing.md是 Claude Code 生态中的智能体定义文件，采用 YAML frontmatter + 系统提示词的结构。文件头部声明了四个关键元数据：

--- name: pr-pricing description: 'Use this agent to size and price a PR (or list of PRs) based on the project''s PR pricing tiers. Provide PR numbers as the prompt. Example: "Price PRs #2100 #2101 #2102"' model: sonnet color: green ---

• name：智能体唯一标识，也是被调用时的名称；
• description：注册给宿主模型的"名片"。它同时定义了触发条件（对 PR 定价）与调用方式（直接把 PR 编号作为 prompt，如Price PRs #2100 #2101 #2102），支持一次对多个 PR 批量定价；
• model：指定运行该智能体时使用的模型，本文件固定为sonnet，保证定价结论的模型行为可复现；
• color：在交互界面中的展示颜色标识，纯 UI 属性，不影响逻辑。

在同一个 .claude/agents 目录下，还并列放置了 code-reviewer.md（代码优雅性评审）、prerelease.md（预发布管理）、release.md（正式发布管理）等同类智能体。可以看到 obsidian-copilot 把"代码评审—PR 定价—发版"编排成了一条完整的工程流水线：pr-pricing负责在合并前对每个 PR 的工作量级与商业价值给出量化评估，其输出可作为贡献者激励与排期优先级的依据。

值得留意的是，frontmatter 中的description出现在name之前、正文系统提示词之前，是 Claude Code 读取智能体"何时该被调用"的入口。它的措辞（"Provide PR numbers as the prompt"）直接决定了使用者的交互方式，因此在自定义智能体时应像写 API 文档一样认真打磨这段描述。

二、定价第一原则：用户影响优先于代码规模

文档开篇用加粗强调的方式立下了整个定价体系的基石：

The most important factor isuser-facing impact— what changes for the user, not how many files were touched.

即：评估的是"用户能感知到什么变化"，而不是"改了多少个文件"。这一原则具体化为三条操作规则：

1. 默认取每个区间（range）的低端；
2. 当 PR 还包含测试、文档、边界情况处理或高完成度打磨（high polish）时，才向高端移动；
3. 在两个档位之间拿不准时，选更低的一档。

这套规则的设计意图非常明确：防止"按代码量计费"导致的两个失真——大段机械重构被高估（改动大、用户无感），小而精的功能被低估（改动小、体验显著提升）。它与仓库中 code-reviewer.md 反复强调的"能少写就少写、每一行代码都要证明自己存在的价值"在价值观上完全同构：代码的价值由结果定义，不由行数定义。

从工程实践看，这条原则还隐含一个可操作化的思路：在阅读 PR 时先回答三个问题（文档第 3 步原文）——

• 用户看到或体验到的差异是什么？
• 这是新工作流、对现有工作流的改进，还是完全不可见（invisible）的内部改动？
• 与参考 PR 对照，规模处于什么位置？

三、六档定价层级（Tiers）完整对照

文档给出了完整的六档定价表，从"用户几乎无感"的 XS 到"足以支撑一个大版本号"的 XXL：

逐档拆解其语义：

• XS（$25–50）：纯粹的低风险微调，例如修正拼写、调整 tooltip、微小的样式改动。技术范围被限定在"孤立的 1–2 个文件变更"，几乎不引入回归风险；
• S（$50–150）：修复一个恼人的小问题，或新增一个次要选项。典型场景是小 bug 修复、配置项新增，不引入新工作流；
• M（$150–300）：对现有工作流产生可感知的改进。技术形态是多文件修复、简单功能或聚焦的重构；
• L（$300–600）：用户会在 review 中主动点赞的新能力，通常是一个独立的完整功能、新 UI 组件或新系统；
• XL（$600–1,200）：改变用户与插件核心部分的交互方式。往往伴随新模块引入与核心集成，风险与价值同步上升；
• XXL（$1,200–2,000）：旗舰级功能，足以支撑一次 major 版本号跃迁，通常是全新子系统与深度的跨模块集成。

观察档位划分可以提炼出两个隐含的判定坐标：横轴是"用户可感知度"（从"无感"到"改变核心交互"），纵轴是"技术辐射范围"（从单文件到跨模块子系统）。两者并不总是同步——这正是档位判定需要人工判断、而非简单按 diff 行数自动计算的原因。

四、用参考 PR 校准定价

为了让档位判断具备可复现性，文档内置了四个已定价的真实 PR 作为校准锚点（它们均来自 obsidian-copilot 仓库历史）：

从当前仓库源码结构看，这四条校准样本恰好能一一对应到真实模块，可以作为理解"为什么这么定档"的旁证：

• #2003（S / $50）：模型 API Key 处理的重构。当前仓库中的 src/modelManagement/providers 目录集中了 ProviderRegistry、providerRequiresApiKey、selfHostPolicy 等模块——内部清理类改动，用户侧只获得"模型过滤更清晰"这类隐性收益，因此被压在 S 档低端；
• #2087（M / $150）：文件状态徽章 + think block 状态修复。仓库中 ChatSingleMessage.tsx 与 ActivityGroupCard.tsx 等组件承载流式消息与状态渲染，这类"可见状态展示 + 流式体验 bug 修复"的组合符合 M 档"现有工作流的可感知改进"定位；
• #2077（M / $150）：聊天/项目的近期使用排序。仓库中的 src/utils/recentUsageManager.ts 实现了SORT_STRATEGIES = ["recent", "created", "name", "manual"]四种排序策略及对应比较器，是一个典型"给现有列表加排序选项"的功能——改进现有工作流而非新增能力，恰好落在 M 档；
• #1969（XL / $900）：系统提示词管理系统。仓库中的 src/system-prompts 目录是完整的一等公民模块：index.ts统一导出类型、常量、工具函数、状态管理、构建器与注册器（SystemPromptRegister），并附 migration.ts 承担从旧设置迁移的历史兼容。**"新用户界面系统 + 9 个测试文件"**正是 XL 档"新模块 + 核心集成 + 高质量交付（测试覆盖）"的完整写照。

这套"参考 PR 校准法"的工程价值在于：新 PR 定价时不需要从零抽象判断，而是先与这四条基准线比对——"它更像 #2087 还是更像 #1969？"，从而显著降低不同分析师之间的定价漂移。

五、五步定价工作流（含完整 gh CLI 命令）

文档为每个传入的 PR 编号定义了严格的五步处理流程：

Step 1 — 拉取 PR 元数据

gh pr view <number> --json title,additions,deletions,changedFiles,body

一次调用即可拿到标题、增删行数、变更文件数与正文描述，作为后续所有判断的输入。

Step 2 — 检查是否含测试与文档

gh pr view <number> --json files --jq '.files[].path'

用--jq提取文件路径列表后，过滤其中的 test/doc 文件。这一步对应"向档位高端移动"的加分级依据：测试与文档的存在是向上调价的充分理由之一（参考 #1969 明确注明"includes 9 test files"）。

Step 3 — 评估用户可见影响（核心步骤）

文档强调这是首要定价因素，并给出三个自问：

• 用户看到或体验到了什么不同？
• 这是新工作流、对现有工作流的改进，还是完全不可见？
• 与参考 PR 对照，如何校准？

Step 4 — 确定档位并给出具体金额

先在 XS–XXL 六档中定位，再在档位区间内选择一个具体美元值（而非只写区间），默认靠向低端。

Step 5 — 一句话论证

用一句话说明为什么落在该档，必须引用用户影响作为依据，例如"新增了用户可见的状态徽章并修复了明显的流式 UX bug"。

这套流程的输入输出都是纯文本/JSON，完全可由 CLI 驱动，意味着它可以被脚本化、批量化执行——description中"Price PRs #2100 #2101 #2102"的多 PR 批量用法就是为这种场景设计的。

六、输出格式：一张可机器解析的定价表

所有定价结论必须收敛为一张标准 Markdown 表格，并在底部附加Total汇总行：

（随后是Total行）

这种输出设计的优点有三：

1. 列结构固定（PR / Title / Size / Value / Rationale），便于后续脚本解析与归档；
2. Rationale 强制单句论证，倒逼定价过程"先定理由、后定价格"；
3. Total 行提供批量汇总，多个 PR 一起评估时可以直接得出总量，服务于预算与排期决策。

七、保守原则：宁可低估，不可高估

文档结尾用"Be conservative"重申了整个定价体系的默认姿态：

• 默认取低端（Default to the lower end）；
• 只有出现明确的加分项才上移：测试（tests）、文档（docs）、高完成度打磨（high polish）、显著 UX 影响（significant UX impact）；
• 两档之间拿不准时，选更低的一档。

与第 2 节的三条规则互为表里：前者定义了"何时上移"的正向条件，后者定义了"何时下移"的兜底规则。这套对称设计让定价行为在缺乏信息时自动偏向保守，避免因高估而扭曲激励信号——也呼应了 release.md 中"release notes 要诚实、不要过度推销"的同类保守取向。

八、把 pr-pricing 接入你的工作流

在 obsidian-copilot 仓库中使用该智能体的方式是标准的 Claude Code Agent 调用：由宿主模型根据description判断场景，然后在对话中给出 PR 编号列表，例如：

Price PRs #2100 #2101 #2102

即可触发该智能体执行五步流程并返回定价表。值得注意的是：

• 定价结论仅依赖ghCLI 返回的公开 PR 数据，不依赖任何本地私有状态，因此同一 PR 在不同时间被评估，只要输入数据一致，结论可复现；
• 该智能体与同目录的 code-reviewer.md、prerelease.md、release.md 组合使用，可形成"评审 → 定价 → 发版"的完整闭环；
• 如果你想在自己的项目复用这套方法论，只需照搬 .claude/agents/pr-pricing.md 的 frontmatter 与正文模板，并替换参考 PR 表格为你们仓库自己的历史样本——校准锚点必须来自目标项目，否则档位判断会失真。

小结

.claude/agents/pr-pricing.md 虽然只有一屏篇幅，却浓缩了一套完整的、可落地的开源 PR 定价方法论：以用户可见影响为唯一核心坐标，配合 XS–XXL 六档区间、四条历史校准锚点、五步gh工作流和强制表格化输出，把"这个 PR 值多少钱"这一主观判断变成了可复现、可校准、可批量的工程流程。对于维护者而言，它是贡献者激励与优先级排序的量化工具；对于想自建评估体系的项目而言，它是结构清晰、可直接移植的参考模板。

进一步阅读：若想理解该智能体所处的完整工程上下文，可对照阅读 .claude/agents/release.md（正式发布流程）、.claude/agents/prerelease.md（预发布流程）、.claude/agents/code-reviewer.md（代码评审），以及本仓库的 RELEASES.md（发布历史）与 manifest.json（插件版本元数据）。

• AI 应用
• 大模型
• AI Agent
• 交互助手
• RAG