tt-a1i/simplify-codebase

简化代码库 – 用于安全代码库清理的 AI 代理技能

是什么

• 一种 AI 编码代理（如 Codex、基于 OpenAI 的机器人）的 技能（插件），帮助它们 审计 现有仓库，证明 某段代码可安全移除，然后 应用 移除操作，同时保留完整的证据记录。
• 它不是通用的 linter 或死代码移除工具；它专注于 意外复杂性，如过时的 API、孤立的状态、重复的抽象或兼容性适配层，仅在收益超过维护成本时才删除。

如何工作

模式	范围	功能
调查（只读）	聚焦 – 单个子系统，或 广泛 – 整个仓库	扫描文件、运行时注册、数据格式和外部消费者，生成带证明记录的“简化候选”排名列表。
变更（授权编辑）	相同范围	候选项被证明安全后，执行删除，运行最小验证套件，并生成回滚计划。

每个候选项都附带一个 证明记录，列出：

• 所有权边界、文件和行号
• 引入的维护负担
• 谁（测试、运行时、外部服务）在使用它
• 精确的删除边界（包括共享文件成员）
• 将丢失的兼容性或可观测行为
• 捕获错误删除的最小测试
• 与迁移成本相比的净复杂性降低量

关键防护机制

• 绝不触碰公共 API、插件注册、数据迁移路径、并发原语，或任何仍有已验证消费者的工件。
• 如果无法识别真实消费者，则建议 保留 代码，而非猜测。

安装

# 推荐用于 Codex 兼容代理
git clone https://github.com/tt-a1i/simplify-codebase.git ~/.codex/skills/simplify-codebase

• 任何尊重 SKILL.md 元数据的代理平台均可加载该技能。
• 内置轻量级 HTML 渲染器（Node ≥ 18，无需额外 npm 包），支持可选的可视化报告。

典型使用模式

# 1️⃣ 审计整个仓库，不作更改
$simplify-codebase audit --scope broad --dry-run

# 2️⃣ 调查特定标志或状态
$simplify-codebase survey --focus readiness-flags

# 3️⃣ 应用已验证的简化
$simplify-codebase change --candidate 42 --apply

# 4️⃣ 合并来自 PR 的发现
$simplify-codebase integrate --pr 123

# 5️⃣ 生成交互式清理地图（HTML）
$simplify-codebase report --visual

• 命令默认返回 文本证明报告；添加 --visual 会生成一个自包含的 HTML 地图，展示已确认的组件及其关系。

输出

• 调查报告 – 覆盖范围描述、排名证明记录、反例、未解决问题和下一步所需证据。
• 变更报告 – 实际文件差异、分层验证结果、残余风险评估、操作收据和可逆的“撤销”脚本。
• 可选可视化报告 – 使用内建的 Archify 渲染器构建的交互式桌面友好 HTML 页面；仅显示已验证发现，从不展示推测的运行时影响。

成熟度

• 在一个包含 973 个文件的混合 Python/TypeScript 项目中验证，涵盖变更、广泛、集成和决策记录场景。
• 测试套件和契约文件位于 visualization/test/ 和 docs/validation.md。

贡献

• 欢迎提交问题和 PR，尤其是那些揭示遗漏消费者、误删或验证流程空白的情况。

许可证

• MIT（见 LICENSE）。

---

Simplify Codebase 是一种专门的 AI 代理扩展，为大型遗留代码库引入形式化、基于证据的精简，帮助团队在不冒隐藏破坏风险的前提下降低长期维护负担。