desloppify

Desloppify

是的——请保持此文件精简。

此 SKILL.md 是操作入口。这里只放工作流和决策要点。详细的命令／配置／参考资料请放在配套文档中，并仅在需要时加载：

• reference/commands.md
• reference/packs-and-tools.md
• reference/config-and-plugins.md
• reference/overhaul-review.md

此技能的用途

在用户希望进行以下操作时使用：

• 清理仓库中的冗余内容
• 清理 AI 垃圾代码
• 执行代码质量检查
• 扫描死代码／弱类型／复杂度／反模式
• 执行结构化的全面审查或分阶段清理审计

CLI 负责检测。Agent 负责分类并决定要修复的内容。

默认行为仍然是扫描 → 分类 → 修复。只有当用户明确希望进行更广泛的审计或制定分阶段清理计划时，才切换到全面审查模式。

默认工作流

可选的全面审查模式

如果用户希望进行更广泛的审计，而非立即清理，请加载 reference/overhaul-review.md 并先选择一种模式：

• 针对性审查 — 仅针对一个主题
• 系统化审查 — 逐节审查，并在每节后暂停
• 全面审计 — 制定广泛的分阶段路线图

对于普通的 desloppify 请求，不要擅自切换到全面审查模式。

0) 设置

运行：

desloppify check-tools [path]

如果仓库显然需要设置方面的帮助，也请使用：

desloppify install-skill
desloppify install-hooks
desloppify setup

install-hooks 会将 .githooks/ 搭建到当前 git 仓库中并启用它。安装的钩子会从仓库、bunx 或 PATH 中解析 CLI；在目标明确时自动选择仓库建议的 pack；并拒绝覆盖非托管的钩子文件，或替换来自 .git/hooks、.husky 或工作树级钩子配置的其他活动钩子链。钩子运行默认检查当前更改；如果用户希望钩子扫描覆盖整个仓库，请设置 DESLOPPIFY_HOOK_SCOPE=repo。

如果需要确切的命令或 pack／工具设置详情，请阅读：

• reference/commands.md
• reference/packs-and-tools.md

1) 扫描

从最相关的 pack 开始进行常规扫描。

常见默认选项：

desloppify scan [path] --pack js-ts

此默认 JS/TS 路径会有意避免在主流程中运行 madge，这样缺失或运行缓慢的循环依赖分析就不会阻碍常规扫描。只有当用户明确要求分析循环依赖时，才添加 --with-madge 或 --category circular-deps。

然后按以下顺序读取生成的文件：

1. .desloppify/reports/latest.findings.json
2. desloppify report [path]
3. .desloppify/reports/latest.report.md
4. .desloppify/reports/latest.wiki.json 或 .desloppify/reports/latest.handoff.md

首次会写入文件的扫描还会自动将 .desloppify/ 添加到 git 仓库中的 .gitignore，以便默认将此状态保留在本地。

只有在任务需要这些输出时，才使用 --json、--markdown、--wiki、--handoff、--delta 或基准测试命令。对于超大型仓库，优先使用 --json --summary，以保持标准输出简洁，同时仍将完整文件写入磁盘。有关确切的变体，请阅读 reference/commands.md。

2) 分类

对于每类问题，决定：

• 修复 — 值得现在修改
• 跳过 — 属于有意设计或价值较低的改动
• 仅标记 — 公共 API／动态行为／序列化／有风险的重构

注意：

• 不要把外部分析器的警告误认为仓库干净
• 部分扫描会跳过整个项目级分析器
• 完整的 JS/TS 扫描默认跳过 madge，除非你选择启用
• check-tools 可以在扫描前从已提供的 js-ts、python、rust、go 和 ruby packs 中给出建议

如果需要了解 pack／工具的行为详情，请阅读 reference/packs-and-tools.md。

3) 修复

对于并行修复流程，优先使用独立工作树：

desloppify worktrees [path]

然后为每个修复 Agent 提供：

1. 工作树路径
2. 已保存的报告路径或聚焦的扫描范围
3. 先运行 desloppify fix . --safe
4. 编辑后重新扫描

当前经验法则：

• fix --safe 是可靠的默认选项
• 更广泛的修复级别并不完整，需要自行判断

4) 验证

修复后：

desloppify scan [path]
desloppify report [path]

需要进行回归检查或前后对比时，使用 desloppify delta ...。

何时加载配套文档

在需要以下内容时，加载 reference/commands.md：

• 精确的 CLI 调用
• 报告 / 差异 / 基准测试流程
• 产物路径

在需要以下内容时，加载 reference/packs-and-tools.md：

• 支持的包
• 工具适配器
• 安装命令
• madge / partial-scan / 仓库本地工具行为

在需要以下内容时，加载 reference/config-and-plugins.md：

• 配置文件发现
• 支持的配置字段
• 插件示例
• desloppify/plugin-api
• 插件 rules.<id>.options
• 稳定的根级编程 API
• identityGroup / fix 插件行为

在需要以下内容时，加载 reference/overhaul-review.md：

• Surgical / Systematic / Full 审查模式
• 分章节审计流程
• 影响 / 工作量矩阵输出
• 范围外事项 / 失败模式 / 执行顺序摘要

大型问题的处理指引

将 GOD_FILE 视为重构信号，而不是盲目拆分命令。 检查触发原因：

• 导入过多
• 路由和数据库职责混杂
• 导出集中在 barrel 文件中
• 单个路由文件包含过多 HTTP 方法
• useState 调用过多
• 通用存储桶文件结构

安全级别

• T1 — 机械式修复
• T2 — 经 AST 验证的修复
• T3 — 跨文件修复
• 仅标记 — 绝不自动修复

抑制

内联：

console.log("intentional"); // desloppify:ignore CONSOLE_LOG

项目级抑制使用 .desloppifyignore。