software-health

软件健康维护

目标是让软件的实际行为、调用方或用户观察到的结果与声明的能力保持一致，并让失败能够收尾、恢复和定位。以可复现的行为及证据判断健康性，不以测试数量、代码行数、报告篇幅或统一评分替代判断。

适用于不同项目与技术栈。检查项按实际入口、运行方式、数据和依赖风险选择；界面、后台任务、模型调用、发布或迁移等环节仅在项目存在且本次范围相关时检查，不预设特定产品、SDK、框架、构建命令或仓库布局。

确定本次工作边界

先读取项目规则、现有变更、运行入口与验证命令，识别项目类型和已有约定。优先复用现有检查，避免引入重复工具链。

区分用户要的是审查建议、执行检查，还是检查并修复。已授权的工作直接推进；只要求审查时不修改产品。启动应用、真实网络/模型请求、生产故障注入、发布等动作按现有授权判断，不因技能被调用就扩大权限，也不对已授权动作重复确认。

选择当前风险相关的检查项，而非固定执行全部项目。局部维护沿改动及其上下游检查；整体审查覆盖高频用户流程和高后果失败路径；发版检查围绕候选版本及明确支持的升级来源。发现具体风险再加深，不把猜测扩展成无边界重构。

按本次问题选择参考，不默认全部加载：

本次范围	参考与重点
指定提交、差异或修复复核	references/change-review.md：需求对账、影响清单、断言有效性、变更归属
模块、页面或子系统的现有实现	references/module-audit.md：入口、契约、字段消费与行为闭环
整体运行、卡顿、故障恢复或升级风险	references/checks.md：状态、并发、资源、性能与兼容性
问题涉及 AI 指令、模型行为或工具调用	references/ai-contracts.md：最终上下文与运行能力

多个范围并存时，以用户目标为主线补充相关参考，不因此扩大成全仓扫描。已有审查结果时复用其结论及证据，只补尚未覆盖的健康风险，不依赖其他技能存在，也避免重复审查。

用用户流程建立检查对象

从关键入口追踪完整路径：用户动作或调用请求 → 请求/事件 → 状态变化 → 副作用与持久化 → 用户反馈或返回结果 → 收尾或恢复。覆盖相关的客户端、服务、后台任务和外部依赖，不把单个函数成功等同于整条流程完成。

为实际风险写出可验证的不变量。例如：

• 显示的运行状态对应真实工作；取消之后不会静默重新开始。
• 每个操作绑定正确的用户、项目、会话或资源；消息载荷不能覆盖可信通道身份。
• 配置变化作用于约定的时机，执行端与展示端对“何时生效”理解一致。
• 失败、取消和超时都能终结等待；重试不会重复产生不可接受的副作用。
• 资源在其所有者结束后释放；仍被后台任务使用的资源不会提前销毁。

这些是不变量示例，按项目取舍；不用为无关状态新建通用框架。

从怀疑推进到证据

结合静态引用、类型/规范检查、状态与事件追踪、测试和运行实测。区分“已复现”“由源码可确定”“尚待验证”，不要把低引用次数、一次超时或单次内存上升直接判为缺陷。

发现问题时记录触发条件、预期、实际结果、位置和影响。将需求、说明及文案中的承诺对应到真实代码路径；核对按名字列举的清单和字段的最终消费方。适合自动化的行为先写失败用例，再修复；难以自动化的保留最小复现和核验方法。验证完整调用链的可观察结果，避免只用测试重复实现中的判断。

复核修复时检查断言能否区分已知错误与正确实现，失败是否确实来自目标行为。破坏性探针放在隔离副本中；不能为验证测试而还原用户工作树、搬动他人的改动或改写提交。

运行时验证优先使用隔离数据和可控依赖，覆盖代表性的成功、失败与中断路径。检查临时目录以外的端口、账户、全局配置和后台任务是否也得到隔离。测试结束停止自建进程、释放连接并仅清理自建资源；用户既有数据按其明确授权范围处理。

真实模型或外部服务评测在授权范围内控制调用次数、耗时和成本，明确停止条件。没有授权或条件不足时继续可做的本地验证，并记录限制，不把模拟结果冒充真实服务结果。

修复与清理的判断

在授权范围内修复已证实且局部可恢复的问题。涉及产品语义、视觉取舍、公共兼容边界、费用或大规模结构调整时，先完成可独立验证的部分，再说明具体取舍。

死代码清理先核对动态入口、配置注册、生成物、测试观察点和外部消费者。确认无用途后清理整条残留链，更新相关声明和失效测试。兼容迁移按支持版本与旧数据验证退役；停止读取旧文件，不等于可以删除用户历史数据或解除遗留凭据保护。