Cherry Studio 代码审查中的 Consumer Review：用消费者考古学审共享接口的存废与形态

Cherry Studio 代码审查中的 Consumer Review用消费者考古学审共享接口的存废与形态【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioConsumer Review消费者审查是 Cherry Studio 内置 PR 审查技能gh-pr-review的第二个审查阶段紧跟在 Product Demand 门禁之后、Architecture-First 审查之前专门审计新增或扩展的共享接口是否有真实、合法的消费者。读完本文你将掌握这套七步消费者考古流程、证据分级与决策矩阵能独立判断一个新增 API、路由、参数、类型或扩展点该保留、收窄、拆分、合并、替换、推迟还是删除——先证明存在与归属再谈实现质量。定位五阶段审查流水线中的第二道关卡在 Cherry Studio 仓库的自动化审查体系中每次评审都会按固定顺序执行多个阶段后一个阶段只审查从前一个阶段存活下来的内容不会重新推翻前面的结论。SKILL.md 中的 Review Stages 表格是阶段范围与引用的唯一权威来源阶段名称适用对象1Product Demand门禁语义影响产品的任何改动2Consumer新增或扩展共享接口的任何改动3Architecture-First代码、混合改动、Cherry 架构文档、项目技能4Implementation代码/文档对应各自 checklist5Style / Conventions代码/文档对应各自 checklistConsumer Review 是第二阶段由 consumer-review.md 定义。它审查的是新增或扩展的共享接口是否存在真实、合法的消费者——本质是代码消费者考古code consumer archaeology而不是实现质量审查。实现质量要等这个阶段判定该接口应当存在、且归谁所有之后才交给后续的 Architecture-First 与 Implementation 阶段处理。在 Cherry Studio 这样的大型 Electron 应用中共享接口的真实含义非常具体src/shared/下的跨进程类型与纯工具、src/shared/ipc/与src/main/ipc/、src/preload/组成的 IpcApi 契约、src/main/data/与src/renderer/data/组成的 DataApi 路由、Cache/Preference/BootConfig 的配置键、数据表 schema 字段以及各种注册表与扩展点生命周期容器、Job 调度器、AI runtime 驱动、Tool/MCP 管道等。每一处这类表面的增扩都需要经过消费者考古。触发条件看差异语义不看提交标签Consumer Review 的触发由差异的语义决定绝不看变更标签feat、fix、refactor、docs、test、chore或工具链改动一律不作数。只要 diff 新增或扩展了共享表面——包括一个 API、DataApi/IpcApi 路由或端点一个参数、类型、字段或配置键一个架构扩展点就执行本阶段。哪怕是一次fix或技能/工具文档改动只要引入了新的路由、参数或扩展点也要走同样的消费者考古流程。只有当 diff既没有新增也没有扩展任何共享表面时才能跳过本阶段。这与仓库内多个审查引擎的加载逻辑完全一致local-review.md 和 teams-review.md 都规定当 diff 新增或扩展共享表面时判断依据是 diff 语义而非变更标签首先执行 consumer-review并且只对存活下来的表面继续审查实现质量。核心原则在实现质量之前先审计因果链本阶段审查的是一条因果链root outcome or invariant → normalized demand → owning layer → contract → consumer 根结果或不变式 → 归一化需求 → 归属层 → 契约 → 消费者其中包含两个关键立场调用点只能证明被使用不能证明合法性或形态正确。一个 call site 存在不代表这个契约就该放在这里、该长成这个样子。没有调用点只会提高举证门槛不构成自动否决。真实需求仍可能配错了消费者或抽象层次——也就是说需求是真的但实现它的那一层、那一个消费者选错了。七步工作流对每个新增表面逐项执行以下每一步都应用于 diff 中每一个新增的 API、通道、参数、类型、字段、配置或扩展点。Step 1重建需求Reconstruct the demand列出每一个新表面及其被精确消费的维度——一个合法消费者不能为未使用的字段背书。随后追溯当前及关联的消费者找到它们背后的用户结果、业务规则或系统不变式检查相邻实现反问自己假如没有当前的 API 和历史包袱这个需求是否依然存在这个契约是否依然是自然的形态不要只依赖 PR 描述。PR 描述只能证明作者的意图不能替代考古。Step 2审计消费者合法性Audit consumer legitimacy将消费者归入四类类别含义合法Legitimate使用了正确的归属层与边界补偿性Compensating使用了最接近的 API但因正确能力缺失而叠加了 workaround遗留形态Legacy-shaped反映了过时的格式、过渡期架构或历史包袱错位Misplaced服务了真实需求但放在了错误的层次以下信号都意味着补偿性消费解析parsing、重试retries、自行排序sequencing、重复状态duplicated state、先检查后执行check-then-act、跨层访问cross-layer access。应把这些信号视为上游需求未被满足的证据而不是对当前接口的背书——一旦用补偿型消费者把 workaround 冻结进共享契约后患无穷见下文 Red Flags。Step 3归一化相关需求Normalize related demands剥离需求陈述中的名字、历史格式和 workaround然后按以下维度聚类结果outcome、真相来源source of truth、归属owner、事务transaction、安全security、生命周期lifecycle。合并历史的或调用方特有的差异保持独立契约的条件是存在真正的归属、权限、原子性、生命周期、副作用或失败模型差异。推荐的形态是稳定的核心 薄适配器stable core with thin adapters而不是复制多份工作流也不是造一个最低公分母lowest-common-denominator的 API。Step 4证据分级Classify evidence级别定义直接Direct一个合法的当前消费者正在使用该维度已承诺Committed同一变更或已关联的近期工作中存在具体消费者架构性Architectural必须有一个最小接缝seam先于消费者存在以保护某个具体不变式无依据的猜测Unsupported speculation只提到了某个可能的未来没有具体场景、归属者或遗漏成本注意直接消费证明了压力但不证明放置位置或形态——这正是有消费者与消费者合法之间的鸿沟。Step 5检验架构性需求Test architectural demand对没有合法当前消费者的表面必须同时满足全部五项存在具体的消费者类或扩展场景明确了归属层与被保护的不变式存在因果性的遗漏成本例如边界破坏、重复机制、不兼容实现、安全漏洞或迁移锁定说明为什么接缝必须先于其第一个消费者存在给出保护该不变式的最小稳定机制。对于未来功能、灵活性、集中化、技术约束、迁移风险这类说法必须附上链接证据和因果性的失败场景否则一律拒绝。若检验失败推迟或删除若通过只保留最小铺就之路minimal paved road删除猜测出来的多余维度。Step 6检查职责与重叠Check responsibility and overlap按归属而非代码行数放置行为集中化安全、权限、事务、不变式和共享策略留给消费者展示逻辑与调用方特有的组合逻辑优先尝试执行try-the-operation当归属者可以原子化地强制约束时不要用 check-then-act。判断两个契约是否真的重复要按语义、归属、权限、暴露面、原子性、生命周期、失败模型、成本八个维度逐一比较。仅仅共享数据不构成重复证据——只有这些维度全部等价时才允许复用。Step 7决策然后交接Decide, then hand off对每个表面或归一化后的分组恰好选择一种结果结果含义保留Keep需求与形态都成立收窄Narrow移除无证据支撑的维度拆分Split把合法核心与无关关注点分开合并Consolidate合并表达同一需求的多个表面替换Replace保留需求更换消费者、归属层或抽象推迟Defer暂不提交一个可能的需求删除Remove需求已不存在或已有等价契约接管汇报顺序固定为根结果 → 证据 → 消费者合法性 → 本质差异 → 归属 → 备选方案 → 决策。只有存活下来的表面才继续进入 Architecture-First 与 Implementation 审查。值得注意的是本阶段的归属判断与 Architecture-First 阶段的边界审查是有意重叠的本阶段回答这个表面是否应该存在、由谁拥有而 cherry-review-guidance.md 回答已存在的代码是否尊重了文档化的边界。对同一缺陷在更早的阶段只报一条 finding并且两个阶段都适用cherry-review-guidance.md中Fix Recommendation Policy的修复高度fix-altitude规则。Rationalization Guards理性化辩护的应对表审查中会听到各种为接口存在辩护的常见话术本阶段给出了逐条应对话术应对这个 API 很干净类型很优雅。质量不能证明存在。它有消费者。验证合法性与精确消费量workaround 不背书任何东西。它没有消费者。运行五项架构性检验没有消费者本身不决定任何结论。这个导出没被用加个测试吧。测试验证行为不能创造需求。架构以后会用到它。指出不变式、因果性遗漏成本、消费者类、为什么是现在、最小接缝。技术约束要求它。把约束追溯到根需求约束不是公理。存在本身就是架构师的决定。权威既不能豁免需求审查也不能把问题降格为吹毛求疵。调用方一行就能算出来。策略按归属与不变式放置不按代码长度。现有 API 返回同样的数据。先比较完整语义再宣布重复。这些消费者略有不同。证明差异是语义性的而非历史性或调用方特有的。它是向前兼容的、纯增量。只保留具体需求增量契约携带永久成本。Red Flags立即暂停并回到 Step 1 的信号遇到以下任何情况立即暂停从 Step 1 重新开始在陈述根需求、证据和合法消费者之前实现评论implementation comments就开始堆积把调用点当作契约就该放这里、就该长这样的证据把当前零消费当作自动否决或当作接受某个架构声明的许可用补偿性或充满 hack 的消费者把自己的 workaround冻结进共享契约。Calibration两个校准样例文档给出了两个用于校准判断力避免过严或过松的具体案例独立的关联模块若不如此就会导入特权内部实现→保留最小的注册接缝registration seam删除猜测出来的旋钮guessed knobs。这里的要点是接缝的价值在于保护特权内部不在于提供一堆没人用的配置项。渲染进程因缺少原子操作而解析原始错误并自行重试→替换抽象而不是扩充错误分类体系error taxonomy。这是典型的补偿性消费治理问题出在上游缺少原子操作正确做法是改变契约形态而不是往错误类型上继续叠加维度。与其他阶段的分工与落地Consumer Review 不是孤立运行的。在 pr-review.md 的 PR 审查流程中Consumer 是引擎选定后按顺序执行的阶段之一在单智能体的 local-review.md 流程中它排在 Product Demand 门禁之后在多智能体的 teams-review.md 流程中每个审查模块如src/shared/、src/main/data/、src/shared/ipc/等分区的审阅者都会在检查实现质量之前先运行 consumer-review并在最终报告中给出每个表面的决策。存活表面进入后续阶段被移除、推迟或合并的表面则随决策一并汇报不再接受实现质量审查。最终输出的审查报告中应当能看到每个共享表面的 Consumer 决策清单这是本阶段可独立引用、可复核的交付物。整套机制的目标可以概括为一句话共享接口的存在权必须由真实、合法、形态正确的消费者来证明而不是由实现质量、历史包袱或对未来的一厢情愿来背书。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考