LobeHub 新功能设计评审维度指南:从「领域模型」到「持久化与可观测」的系统化 Review 方法

LobeHub 新功能设计评审维度指南:从「领域模型」到「持久化与可观测」的系统化 Review 方法 LobeHub 新功能设计评审维度指南从「领域模型」到「持久化与可观测」的系统化 Review 方法【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub本文以 new-feature.md 为骨架讲解 LobeHub 深度代码评审体系deep-review skill中feature维度的完整规则如何把一次引入新能力新 provider、新 operator tool、新后端工作流、新自托管能力等的改动当作「一个自洽的产品与领域模型」整体评审而非逐文件局部判断。读完你将掌握一套可直接复用的审查清单与严重度校准方法用于评估新功能在词汇/结构、数据库与生命周期、分析与可观测性三个层面是否在发布后真的「可回答它是否生效」。这个维度解决什么问题局部正确、整体错误在 LobeHub 的多维评审体系.agents/skills/deep-review/SKILL.md中代码改动通常被拆成 14 个维度并行审查。new-featureid 前缀feature针对的是一种特别隐蔽的失败模式一个能力在每一层看起来都局部正确但作为一个整体它可能使用了错误的概念、持久化了错误的状态或者发布后根本无法回答「它是否真的工作」。这正是其核心定位——在评判新能力的单个文件之前先把它当作一个连贯的产品与领域模型来评审。该文件 frontmatter 中声明了适用前提skip_when: diff does not introduce a new product, operator, or platform capability与参与验证机制verify: true意味着该维度的发现与其他大多数维度一样会交由独立验证子代理逐一判定真伪而不是直接作为结论上报。适用边界什么算「新功能」判断是否运行本维度的门槛很关键不运行纯粹的 bug 修复、重构、删除或纯文档改动运行新的provider、后端、工作流、operator 工具或自托管能力即使它没有新增任何 UI也算 feature。在 LobeHub 这种扁平 monorepo 中一条新增能力往往同时触碰packages/model-runtime新模型 provider、apps/server后端 workflow/trpc router、packages/builtin-tool-*新的内置工具与packages/database持久化层因此在为 diff 选定维度前先用 pruning 语义对照 SKILL.md 的维度剪枝表判断是否引入上述能力是走该维度的第一步。快速检查清单Quick checklist逐条拆解维度文件将评审内容收敛为三大块共三条主线领域模型/命名/结构、数据库与生命周期、产品分析与可观测性。Light 模式的独立评审员只读本清单Deep 模式则读完整文件并接入规则来源。1. 领域模型、命名与结构清单要求评审员验证五件事一句话可表述 词汇统一能力应当能用一句话、以清晰的领域名词说清。跨 interface、实现、配置、任务、遥测、数据库对象和文档中必须使用同一套词汇。这直接对应 LobeHub 对命名收敛的要求——例如 drizzle 技能 强调新建表要遵循既有「名词家族 后缀」约定user_xxx_logs对应workspace_xxx_logs而不是另造_records同义词。区分能力 / 实现 / 生命周期三层概念能力capability不等于其具体 provider 或实现也不等于它的运维生命周期。provider 特有实现不得借用更宽泛的平台名去暗示它并不提供的行为对比同类实现时要「作为一个命名系统整体比对」而非一次只看一个符号。先查最近的同类功能与领域技能再决定落位接受新文件夹、新 service、新 repository 或新配置面之前先核对仓库中最近的同类能力和.agents/skills/下对应的领域技能。当多个仓库/层都「可能放」时必须要求显式的产品与工程归属决策不能仅凭当前部署形态、技术可移植性或保密需求去推断落点。能力可用性与实现/provider 选择分开建模feature flag 只负责「增加或移除一项能力」不要把 flag 扭曲成多值 provider 或运行模式注册表。临时灰度 flag 必须带移除条件自托管产品则可以有意保留能力型 flag 作为长期定制开关。保留点号后缀的既有语义.test、.server、.desktop这类点号后缀只留给已确立的工具或运行时含义普通分组一律走仓库的文件夹或连字符惯例。2. 数据库与生命周期这一部分把审查火力对准持久化设计核心是四连问每个新表/列/索引/触发器/持久化状态都要被挑战它「拥有」什么持久化事实谁写谁读何时被移除——不得持久化本可从权威系统推导出的部署/安装状态。正式 schema 必须走正常迁移路径可选运行时安装runtime installation只允许用于「对象的存在确实取决于启用该能力」的场景。未启用该功能的实例不应承担其持续写入或运维成本。开发期迁移只应描述最终形态核对 schema、生成的 SQL、snapshot 与迁移历史只描述最终模型不要为未发布的草稿保留兼容。这与仓库的 db-migrations 技能 完全一致——该技能明确规定迁移尚未发布前不应手工修补旧的草稿迁移 SQL而是删除该分支新增的草稿 SQL/snapshot/journal 条目后bun run db:generate重新生成让产物只反映最终形态。当迁移成本或锁行为改变发布计划时必须实测在项目真实的 Dev 数据库上执行实际操作或可逆等价操作如临时建同名探测索引、事务内装触发器再回滚记录观测到的规模与耗时并把对生产的推算显式标注为推断而非事实。db-migrations 技能中同样给出了这条「用 Dev 证据替代空想假设」的原则不要在未测量的性能担忧上仅凭「这个迁移可能很慢」就引入人工发布步骤或延迟激活路径。与 LobeHub 的持久化规范drizzle 技能互相印证本仓库新 schema 默认「单列代理主键 uniqueIndex」而非复合主键因为当唯一性范围日后被一个可空维度扩展时复合主键需要整体拆建业务状态用text/varchar.$typeUnionType()表达而非pgEnum枚举每加一个值都要ALTER TYPE迁移而 TS 值类型只是纯类型变更。这些约定本质上都是在回答本维度那四连问中的「这个对象代表什么生命周期、将来如何演化」。3. 产品分析与可观测性Analytics Observability该小节先在文件中划清边界单个事件是否形状良好、位置得当属于observability维度见 observability.md本节只问一件事——发布后功能作为一个整体能否回答它的结果问题。规则有四条列出发布后必须回答的问题覆盖用户可感知的性能、结果/成果质量、使用或持续使用意向、以及主要失败模式如适用不要添加没有决策依附的信号。这与 observability 维度的口径一致「衡量标准不是『我们记录了用户做了什么』而是『是否有决策在等这份数据』」。产品分析与后端遥测分离用户事件解释「人们看到了什么、选择了什么」而 metrics/traces 解释延迟、错误、吞吐与资源成本。单靠后端 span 不能确立产品质量或使用意愿。在真实入口与完成点埋点包括有意义的空结果/被放弃的结果埋点失败不得改变功能行为即测量不得侵入业务路径。事件属性与 metric 标签保持有界且尊重同意绝不仅为了让调试更轻松就去记录原始用户内容、搜索文本、密钥、用户 ID、文档 ID 或其他高基数标识符。observability 维度对此有更强的互补表述搜索类面记录查询的「形状」而不是文本0 结果的 miss 事件才是最值得记录的信号。对易回归的主路径要求一条绑定「用户可见失败」的可行动告警并给出具体阈值不要为每个内部步骤都索要告警。深度模式必读的规则来源Deep 模式评审员在开工前必须先读new-feature.md 的 Rule sources 节定义该新能力及其目标用户的需求/issue最近的同类功能及其落地 PR/commit.agents/skills/下直接匹配的领域技能project-overview 技能 与仓库 AGENTS.md用于确认归属与结构schema 变更时读 db-migrations 技能 与 drizzle 技能最近同类功能使用的可观测性与分析路径对应仓库中如 src/components/Analytics 的分析埋点面与 packages/observability-otel 的后端链路面。以 LobeHub 的代码事实看这些规则来源都指向真实存在的落点持久化约定集中在 packages/database/src/schemas 与packages/database/migrations/drizzle 技能标明 Drizzle 配置在 drizzle.config.ts分析埋点形如analytics?.track()HomePageTracker.tsx 即为既有范例后端链路则经由 OTEL 包装。如何检查四步操作法维度给出了评审员应实际执行的四步Light/Deep 两模式共用写一张词汇映射表vocabulary map把「能力 / provider 与变体 / 生命周期操作 / 持久化实体 / 遥测名称」逐一列出然后在 diff 及邻近调用方里搜索竞争的措辞——这是发现「同义名词满天飞」的最快手段。画出功能的完整路径从入口点贯穿运行时、持久化、后台工作、恢复、配置与文档报告缺失或错位的生命周期部件。逐个数据库对象问「持久化事实 生命周期」检查生成的迁移并在推荐手工发布工作前使用已批准的 Dev 证据。把每个新增事件/指标/链路/告警翻译成「它回答的问题」找出「重要产品问题无信号」与「信号没有可行决策」两类空洞。什么是违规、什么不是违规文件用两份对照清单收敛「该不该报」的判断避免过度打扰Violations应上报词汇或结构让能力、provider、生命周期概念在层与层之间变得含糊某数据库对象没有必要的持久化职责、脱离了正确的迁移或激活生命周期或基于未测量的成本假设改变发布计划快速、有用的结果或持续使用意愿这些居于需求核心的结果功能却无法回答尽管对需求是核心分析/遥测引入了敏感或高基数数据、记录失败会改变产品行为、或制造不可行动的噪音。Not violations不应上报体现 calibration 原则小功能既有领域模型、持久化与埋点已能回答相关问题无需新增抽象provider 实现内部的 provider 专有名称共享能力保持 provider 中立即可确实既不需要新表也不需要新分析事件仅云端的告警阈值或操作被放在通用开源实现之外。这条「Not violations」与 light-review-prompt 的硬性校准规则同源评审要校准到 codebase 已经达到的标准而不是理想标准——若某模式在既有代码中广泛存在、本 diff 没有使其更糟就不该成为 finding。严重度校准P1 与 P2 的判别文件把发现的严重度收敛为两级P1必须修模型会破坏持久化状态、使功能在其目标部署形态下不可用、或让需求关键的失败在发布后无法被发现。P2可延后误导性词汇、可避免的结构债务、或缺失「有用但非关键」的信号。值得注意的是该维度文件自身只定义 P1/P2 两级语义而 LobeHub 的深度评审输出契约report-template.md与 light-review 提示模板light-review-prompt.md在此基础上还引入了 P0事故级影响、introduced / exposed_legacy性质判定与likelihood可能性分级用于最终决定是否阻断合并。因此本维度的 P1/P2 分级是进入全局报告前的一道语义过滤器。在评审流程中的落位Light 与 Deep 如何消费本文件回顾 deep-review/SKILL.md 的运行机制能看清本文件的「读者」是谁Light 模式默认一个独立评审员不共享作者上下文只读本文件的Quick checklist全节按 pruning 表对给定 diff 跑适用清单Deep 模式显式/deep-review才触发独立维度评审 agent 读完整文件 规则来源 被触碰面相关的定向引用随后进入流水化的独立验证每个 finding 由验证子代理返回confirmed / false_positive / need_more_context三值判定、全局去重合并与结构化报告扩展包机制同目录下与deep-review-*匹配的兄弟技能可作为扩展包同名维度叠加加载如本文件的 frontmatter 在扩展场景下的归属规则见 SKILL.md 第 93-95 行。这也解释了为什么本文开头强调「先整体后局部」——因为一旦新功能在发布后无法回答「用户是否获得了快速、有用的结果、是否愿意继续使用」任何单文件层面的正确性都无法弥补。对 LobeHub 这样的 AI Agent 工作台项目如 project-overview 技能 所描述的多平台、约 80 个lobechat/*workspace 包、数千个 feature/store 文件的规模一次新能力的落位往往横跨数据库 schema、迁移产物、trpc router 与前端埋点多处new-feature维度提供的正是把这条横贯链路当成「一个产品」来审查的纪律。小结把本维度落到日常 Review 的三个行动开审先写词汇映射表把能力、provider、生命周期、持久化实体、遥测名一次列清在全 diff 里 grep 竞争措辞凡新增持久化对象必回答「事实/写入者/读取者/移除时机」并用bun run db:generate的产物核对迁移是否只含最终形态慢迁移疑虑一律到真实 Dev 库实测后再定发布方案凡发布后必须回答的核心结果问题没有对应信号或信号没有依附任何决策都按 P1/P2 语义如实上报交由 deep-review 的独立验证流程判定真伪后进入报告。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考