Axıs
随笔
技能目录

overhaul

Overhaul

是什么

一次性、全链路的仓库升级工程：把「能跑」的仓库推向「简约而专业，优雅而高效，别致而深刻」，并安全发布。

不是什么：

  • 不是日常结构治理（butler 的常驻职责）
  • 不是单次交付的验收（visible/review）
  • 不是堆砌功能——默认动作是删繁就简，迁移取舍服从方向，不服从热闹

十条原则

  1. 先理解，再改动。 未梳理架构、数据流、公共契约与发布意图前，不动一行代码。
  2. 方向高于形式。 不为徽章数量、视觉新奇、README 戏剧性优化；为清晰、正确与长期方向优化。形式不是重点，方向才是。
  3. 先量前提再动手。 用户给的病因是假设：量化可否证它，报数字，再修真因。
  4. 真实高于体面。 测试真实运行，数据不虚构；部署声明实测后才写；私有化部署不流畅就如实报告并修复，不绕过。
  5. 单一权威。 品牌资产、版本、配置、文档各有唯一真相源；其余处引用，不复制。
  6. 奥卡姆剃刀。 如无必要，勿增实体。需要专业，但不为简单问题引入复杂机制。
  7. 证据高于观点。 每条发现附 file:line 或可复现命令；数字带口径；假设标注为假设。
  8. 一致高于新奇。 新模式只在降低复杂度或提升正确性时引入，否则遵循仓库既有约定。
  9. 发布之前先安全。 敏感数据扫描未通过，不 push。
  10. 决定，而非列菜单。 规划输出一个推荐方案 + 「已替你决定」清单，只把真正的分歧点留给用户。

主路径（八阶段）

阶段即门禁：每阶段以可验证动作收尾，未达标不进入下一阶段。

0. 通读理解

  • 盘点技术栈、入口、依赖、测试、CI、文档、配置、资产、git 历史与 tag
  • 梳理架构边界、数据流、公共契约、构建/测试/发布路径
  • 产出 ≤10 行摘要：仓库是什么、为谁服务、当前状态
  • 本阶段不改任何文件

1. 深度审计

按 references/audit.md 执行。

  • 每条发现分类（bug / 漏洞 / 死代码 / 未完成 / 缺失 / 薄弱抽象 / 重构机会 / 待讨论 / 可替换 / 可撤销 / 可丰富）并定级 P0–P4
  • 每条发现附证据（file:line 或复现命令）与影响
  • 区分系统问题与硬件/环境限制：系统问题必须修，硬件限制如实标注，不互相伪装
  • 私有化部署实测：干净环境从零跑通，记录全部卡点
  • 发现在对话中交付摘要，不止存进文档

2. 对标分析（横向 + 纵向）

按 references/benchmark.md 执行。

  • 选 2–4 个成熟同类项目，建功能/架构/工程化对比矩阵
  • 纵向：归纳本领域能力清单，逐项判定 存在且正确 / 存在但浅 / 缺失 / 不适用
  • 每个差距给 adopt / adapt / defer / reject 判定与一句话理由；只有强化核心方向才 adopt

3. 重构计划

  • 产出可执行文档：目标与非目标、按优先级排序的变更、迁移与回滚策略、测试策略、里程碑
  • 一个推荐方案 + 「已替你决定」清单
  • 高风险重构前先补测试；除非有意变更并记录，行为保持不变

4. 执行

  • 小步原子提交，每步过测试与 lint
  • 真实运行验证，性能数字带口径与复现命令
  • 不顺手重构无关代码，不静默改变行为

5. 文档与品牌对齐

按 references/release.md 的品牌节执行。

  • 默认英文 README；用户要求时提供本地化版本（如 README_zh.md），内容同源
  • logo 用仓库权威资产，居中；badge 少量、核心、反映真实状态
  • 删除 agent 自造的品牌替代品与孤立资产；README 每条声明在代码中真实存在

6. 安全与发布

按 references/release.md 执行。

  • 扫描工作树、暂存区、待推送 diff 与 git 历史中的密钥与敏感数据
  • 版本、CHANGELOG、元数据、tag 一致；push 后验证远端状态
  • 无显式授权不 force push

7. Shuffle 终审

打 tag 前的最后一道闸，协议见 references/release.md。

  • 随机重排检查顺序，打破路径依赖
  • 以维护者 / 新贡献者 / 运维 / 攻击者 / 终端用户五种视角各审一遍
  • 四个对照一致：文档↔代码、资产↔品牌权威源、版本↔CHANGELOG↔tag、本地↔远端
  • 修复发现项，重跑质量门禁，再定稿

反模式

  • 未理解即重构；对同类功能 cargo cult
  • 已有权威 logo 却自造 SVG 替换
  • 把用户给的病因直接当真因，不量化验证
  • 虚构测试数据或未实测就写部署声明
  • 装饰性 README 掩盖薄弱实质
  • 把系统问题归因给硬件，或把硬件限制伪装成已优化
  • 破坏性变更无迁移说明；大规模重写无检查点
  • 推送密钥；打了 tag 但未验证远端
  • 选项菜单式规划；把形式当方向

质量门禁

以下未全部通过不得发布：

  • 测试绿、lint 绿
  • 安全扫描干净
  • 文档与代码一致，README 声明属实
  • 品牌资产与权威源一致
  • 版本 / CHANGELOG / 元数据 / tag 一致
  • 远端推送结果已验证
  • shuffle 终审完成

参考

规范依据

本规范依据 apps/skills/axiom/axiom.md 第零部·二「从实践到原则的提炼方法」、第零部·五「面向代理的文档写作」制定。