Tolaria 的棘轮式 CodeScene 质量门槛把代码健康度写成只能上调的架构策略【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文围绕 Tolaria 的架构决策记录 ADR-0064 展开它如何取代 ADR-0018把 CodeScene 代码健康门槛固化为一个只升不降ratcheted的策略基线并以.codescene-thresholds文件作为唯一权威数值来源。读完本篇你能理解这套棘轮门槛的决策背景与取舍、它在本仓库 git hook 中的真实执行链路远端分数拉取、恢复模式、阈值自动上调以及它与文件级童子军规则、变更集守护机制如何共同构成 Tolaria 直接推main工作流下的完整质量闭环。一、背景ADR-0018 建立门槛后决策文档过期了ADR-0018docs/adr/0018-codescene-code-health-gates.md最初为 Tolaria 引入了 CodeScene 代码健康门槛在 pre-commit 与 pre-push hook 中强制执行Hotspot Code Health ≥ 9.5且Average Code Health ≥ 9.31项目整体任一指标不达标即阻断提交/推送失败时禁止使用// eslint-disable、#[allow(...)]、as any等手段绕过并要求以童子军规则leave every file better than you found it为每次任务的隐含义务。该 ADR 还确定了排除范围.codesceneignore中排除了tools/、e2e/、tests/、scripts/。随后代码库质量持续提升追踪基线被逐步抬高。ADR-0064docs/adr/0064-ratcheted-codescene-thresholds.md状态 active日期 2026-04-14的 Context 部分指出了问题的本质如果继续让 ADR-0018 保持 active架构记录就会失真——实际强制执行的阈值已经比决策文档写的更严格而当前工作流是有意地、持续地把门槛收紧的。二、核心决策.codescene-thresholds成为棘轮式策略基线ADR-0064 的 Decision 明确取代supersedeADR-0018将.codescene-thresholds作为 Tolaria CodeScene 门槛的棘轮式策略基线。该 ADR 落笔时记录的当时最低要求为HOTSPOT_THRESHOLD9.84、AVERAGE_THRESHOLD9.45并规定了一条方向性规则阈值只允许上调且只有在仓库能够持续维持更严格基线而不会立即回退时才上调。值得注意的是棘轮机制是自生效的当前仓库中 .codescene-thresholds 的实际内容已经进一步升到了HOTSPOT_THRESHOLD10.0 AVERAGE_THRESHOLD9.99这恰好印证了 ADR 中阈值随项目持续健康度提升而收紧的机制描述——ADR 正文记录的 9.84 / 9.45 是 2026-04-14 时的快照此后 hook 又继续把文件推高。这也引出了 ADR-0064 的一个后续约束若 Tolaria 再次做出有意义的阈值策略跃迁ADR 需要被再次取代supersede以保持架构记录与实际门槛一致。ADR-0064 的 Options considered 给出过三个候选方案的取舍值得完整保留上调强制阈值并记录新基线选中让 ADR 与真实门槛保持一致保留童子军规则并让代码健康期望随代码库改善而变严。保持 ADR-0018 active把更高阈值视为实现细节文档变更成本低但 active 的 ADR 将无法再描述实际的 CI 与 hook 策略。从 ADR 中彻底移除数值阈值纸面上更持久但失去了开发者应当维护的明确质量标准。其 Consequences 部分列出了四条长期约束.codescene-thresholds是数值门槛的唯一权威位置后续策略跃迁必须再次取代 ADRpre-push 及相关质量检查强制的底线已比 ADR-0018 描述时更严格质量门槛刻意保持单向——放松阈值需要一次显式的架构反转而不是悄悄改配置。三、源码级证据pre-push hook 中的棘轮执行链路ADR 只是决策声明真正的棘轮落在 .husky/pre-push 的第 6 步CodeScene code health gate (ratchet)。从源码看该 hook 的执行逻辑与 ADR 的决策一一对应读取阈值文件。hook 以HOTSPOT_MIN9.45、AVERAGE_MIN9.29作为硬编码兜底值随后若存在.codescene-thresholds就用grep ... | cut -d -f2覆盖为文件中的实际值。即文件是权威硬编码值只是文件缺失时的最后防线。拉取远端分数。hook 调用 CodeScene APIcurl携带CODESCENE_PAT请求https://api.codescene.io/v2/projects/$CODESCENE_PROJECT_ID解析analysis.hotspot_code_health.now与analysis.code_health.now。两个环境变量任一缺失、或远端分数拉取失败时跳过本地比较CI will enforce不做静默放行。恢复模式recovery mode。若远端基线已经低于阈值例如仓库正处于红灯状态hook 打印警告但允许本次推送Recovery mode: allowing this push so refactors can land否则过期的远端分数会把修复门槛所需的重构提交本身也挡住——这是一个务实的逃生口只豁免低于基线的推送不豁免任何上行检查。自动棘轮上调。若远端分数高于当前阈值hook 用math.floor(score * 100) / 100向下取整到百分位计算新下限写入.codescene-thresholds打印 Ratchet updated然后以退出码 3 终止推送并要求开发者把git add .codescene-thresholds后的新下限用一次正常、经验证的提交落入仓库再推一次。hook 自身从不自动提交、也从不绕过自身——这正是 ADR 所说阈值上调必须是一个显式、可见的动作的实现形态。配套的策略文档 .github/HOOKS.md 把这条规则写进了仓库政策层.codescene-thresholdsis a ratchet. It can only move up.远端分数优于当前阈值时hook 更新文件、暂存并停止推送The hook does not auto-commit or bypass itself.pre-push 的完整放行条件包括仅允许main → main推送、Codacy 差异门槛无新发现、TypeScript Vite 构建通过、前端覆盖率达标、src-tauri/变更时的 Rust lint/覆盖率、Playwright 核心 smoke以及当前 CodeScene Hotspot 与 Average 均不低于.codescene-thresholds。四、周边约束文件级童子军规则与变更集守护ADR-0064 解决的是项目级、仓库级的分数门槛Tolaria 直接推main的工作流无 PR 边界还需要补上变更集级的审查这部分由 AGENTS.md 与后续 ADR-0172docs/adr/0172-local-codescene-change-safeguards.md承担构成对 ADR-0064 基线的自然延伸禁止手工下调。AGENTS.md 明确规定 Do not edit.codescene-thresholdsto lower the values被门槛挡住时应当改进代码任何例外都需要仓库所有人事先批准。这与 ADR-0064 放松阈值需要显式架构反转的结论互相印证。文件级童子军规则。修改前必须记录目标文件的文件级 Code Health 分数修改后必须更高已是 10.0 的文件必须保持 10.0新建的可计分代码文件必须达到 10.0 才能提交。变更集守护。ADR-0172 指出远端 Hotspot/Average 分数来自最新一次远端分析无法描述未提交的本地变更因此在每次提交前运行 CodeScene MCP 的pre_commit_code_health_safeguard在最终推送前用analyze_change_setbase_reforigin/main做本地 PR preflight 等价物。该 ADR 明确保留 ADR-0064 的仓库级棘轮作为外层门槛与趋势信号两套机制回答不同的问题守护机制审查即将落地的代码远端分数监控仓库基线与棘轮。五、工程意义与适用前提这套设计的可借鉴点在于把质量基线从一次性决策变成了可观测、可审计、方向受控的策略资产数值集中在一个四十字节的文件里上调动作由 hook 代跑计算并由开发者显式提交架构文档ADR-0018 → ADR-0064 → 后续通过 supersede 链条与实际门槛同步。适用前提同样需要说清该门槛依赖 CodeScene 服务可用性CODESCENE_PATCODESCENE_PROJECT_ID且推送策略绑定 direct-to-main 工作流ADR-0021 一脉在 PR 流程下analyze_change_set这类本地守护的必要性会下降。阈值文件当前已被棘轮推到 Hotspot 10.0 / Average 9.99属于非常激进的基线这是该项目长期童子军规则执行的结果并非通用建议起点新仓库更可能从类似 9.5 / 9.31 的水平起步。排除项分散在 .codesceneignoretools/、e2e/、tests/、scripts/与 .codescenerc另加src-tauri/gen/、coverage/、dist/另有 .codacy.yaml 服务于独立的 Codacy 差异扫描门槛三者职责不同勿混淆。对维护者来说判断这套门槛现在多严只需读一个文件判断它为什么是这个值、何时允许变化则沿着 ADR-0018 → ADR-0064 → ADR-0172 的 supersede 链条即可完整还原。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考