可维护性量化
§1摘要与结论
别名：SQALE、maintainability quantification、可维护性量化、技术债指数、债务本金与利息 | 英文：Maintainability Quantification | 类型：技术 / tool
§2局部关系图
§3原理 · 为什么
可维护性描述的是修改的有效性与效率，无法由单一静态数字读出，但可通过结构、变更历史与维护过程的多类证据近似判断。可维护性量化工具的价值在于把「系统好不好改」从主观印象变为可比较、可追踪的判断，从而在资源有限时把治理引向真正昂贵之处。以 SQALE 为代表的方法沿质量模型子特性组织一组检查规则，估计修复违规所需成本作为债务本金，并按规则对可维护性的影响折算为利息，形成可排序的债务视图，使模糊的「代码质量」变成有数量级的成本量，可作为治理排序与投入决策的依据。这种成本化表达也便于向非技术干系人解释为何需要偿还技术债。把债务表达为可排序的成本，也使「先还哪笔债」这一决策从直觉争论转为可比较的投入产出判断，便于在有限资源下排序。量化的意义始终是服务决策，而非产出一个好看的数字。
§4机制 · 如何运作
量化沿「规则→违规→成本→评分」链路运作：先按选定质量子特性（如可分析性、可修改性、可测试性）定义检查规则；再对代码库扫描，识别违规并估计每类违规的修复成本；把成本按其所属子特性与严重度归集，折算为债务本金与利息；最后汇总为可比较的指数或分级。结果可映射到模块与文件，定位高风险区域。工具通常把修复成本单位化，使不同语言与规则之间可以叠加与比较。量化应可重复：明确度量口径、数据窗口与判定规则，并记录所依据的代码版本与工具假设，使不同时点的结果可比、趋势可追踪。规则集本身也会演进，需记录其版本，否则历史数据在规则变化后将失去可比性。利息的折算规则体现方法对可维护性的理解，因此不同工具与配置之间的指数并不可直接横比，跨项目比较前须先对齐口径。
§5工程 · 怎么落地
实践中把可维护性量化嵌入日常流程：在迭代或发布节点采集指标，形成趋势而非单点快照，把明显恶化的趋势作为深入分析的信号。结果应转化为具体行动——针对热点模块补充测试、改善依赖方向、拆分或合并模块，并纳入正常重构与演进计划，而非发起孤立的「代码质量专项」。对指标本身保持警惕：单一阈值容易误导，指标一旦被当作考核目标就可能被博弈，因此应组合多信号并关注其变化方向。治理优先级应按变更频率与业务重要性排序，而非按分数高低；量化产出应是可讨论的假设与优先级清单，供团队结合语境做决策，并在下一轮验证改进是否真的降低了变更成本。评估的最终价值在于促成改变，而非产出一份更精细的报告。评估的自动化程度决定了它能否长期坚持；若采集与解读成本过高，指标很快会无人维护而失效，反不如少而稳定。
§6权衡卡
其四，持续采集与解读需要成本，过细的评估会成为负担。
因此量化应以驱动决策为目的，聚焦少数高价值信号，把结果与真实变更成本对照验证，并随系统演化更新口径。
度量的价值在于它引发的行动，而非分数本身的精确，因此应避免为追求指标而做无意义的改动，把力气花在真实的变更成本上。
反例是把量化做成一次性打分排名，既未转化为治理行动，也未纳入演进闭环。
- 可维护性量化有内生的局限。
- 其一，指标只是间接信号：复杂度高未必真的难改，看似整洁的代码也可能因缺乏测试或依赖隐藏而难以安全变更。
- 其二，指标之间存在张力与冗余：降低耦合可能增加模块数量，降低重复可能增加间接层，单一目标的最优化可能损害整体。
- 其三，量化本身可能被博弈，团队会优化数字而非改善可维护性，使评估失去意义。
- 承认度量的近似性，才能把它用在合适的判断上。
- 理想的做法是让量化成为改进的起点：先看趋势与热点，再结合人工判断决定动哪些模块，最后用下一次的变更数据回验决策是否正确。
- 把量化嵌入迭代节奏，比周期性的大审计更易坚持，也更贴近真实变化。
权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。
§7案例带
网申填写扩展逆向架构
对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。
网申 v3 多模块解耦
一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。
网申 v2 深度重构
一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。
preset 通道耦合分析
对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。
§8信源与核验
核验结论：可维护性由多个子特性构成，须综合结构、变更历史与维护过程证据交叉判断；SQALE 等指数仍是对修复成本的近似估计，单一分数只是间接信号，且可能被当作目标而失真 [VEN-011]
§9原始关系清单
展开：本节点的全部原始关系边（3 条，含边 ID 与方向）
| 关系 | 方向 | 对端节点 | 说明 |
|---|---|---|---|
| 组合 | → TEC-M-03 | 可修改性战术实现 E-910 | 可维护性量化与可修改性战术组合治理变更成本 |
| 促成 | ← TEC-M-01 | 质量模型工具化 E-909 | 质量模型为可维护性量化提供子特性框架 |
| 实现 | → MTH-M-05 | 可维护性评估方法 E-907 | SQALE 量化技术债与可维护性实现可维护性评估方法 |