重构洞察 duyanta123/dsh-refactor-insight

dsh-refactor-insight

DSH 技能插件：把代码库的坏味道转成带定位、优先级和依赖顺序的可执行重构计划——结构健康体检，而非 diff 审查。

Turn codebase smells into an executable, priority-ordered refactoring plan.

定位

与同类工具错位互补：arch-doc 看整库结构（理解现状），现有 code review 类工具看 PR/diff（把关变更），本插件看整库坏味道（输出行动计划）。

它回答：
- 哪些文件、函数、类超出了健康阈值（长度 / 嵌套 / 方法数）？
- 哪些模块耦合过高、是否存在依赖环？
- 问题项的严重度和修复成本怎么排优先级？
- 重构应该按什么依赖顺序做？

边界（红线）：只输出计划、不自动改代码；高风险重构项由 LLM 标注、须人工确认。脚本只给硬事实（确定性扫描，六条规则阈值均可参数覆盖），严重度 / 成本 / 建议动作由 LLM 精修误报后标注推断。

能力（v0）

六条确定性坏味道规则（零依赖启发式）：

- 超长文件（默认 > 400 行）
- 长函数（Python 缩进块 / JS-TS 花括号配对 / Go 函数声明，函数体 > 80 行）
- 深嵌套（默认最大缩进 / 花括号深度 > 5）
- 上帝对象（类方法数 > 10 或类体行数 > 300 / Go 接收者方法数）
- 高耦合模块（复用 arch-profile --deps 输出，按入度/出度识别 hub 模块 + Tarjan 环检测）
- TODO/FIXME 密度（噪音指标，输出每千行计数）

安装

作为 DSH 插件（推荐）：

dsh plugin --profile web add "github:duyanta123/dsh-refactor-insight#v0.1.3"

或从 npm 安装：

npm install dsh-refactor-insight

兼容性分层：独立诊断脚本（refactor-smell.mjs / arch-profile.mjs）可运行在 Node.js >= 18；作为 DSH 0.1.5-rc.2 插件验证统一使用 Node.js >= 22.19。运行 npm run test:compat 可执行隔离 profile 的 add、dump-config 和启动 smoke test。

本地开发：profile 的 package.json 加 "dsh-refactor-insight": "file:<本地路径>/dsh-refactor-insight"，bundles 加 "dsh-refactor-insight"。

快速开始

1. 作为 DSH 技能使用

安装后重启 profile，对 Agent 说：

用 refactor-insight 体检 /path/to/repo

技能按四阶段 runbook 执行（受理 → 扫描 → 诊断 → 排序编排），按 docs/refactor-plan-template.md 骨架生成 REFACTOR-PLAN.md。

2. 只跑诊断 CLI（零依赖，不经过 DSH 也能跑）

六条规则诊断
node scripts/refactor-smell.mjs <repo_path>

复用 arch-profile 的依赖输出做高耦合/环检测
node scripts/arch-profile.mjs <repo_path> --deps > deps.json
node scripts/refactor-smell.mjs <repo_path> --deps-json deps.json

CLI 参数

| 参数 | 默认 | 说明 |
| --max-lines <N> | 400 | 超长文件阈值（行） |
| --max-func-lines <N> | 80 | 长函数阈值（函数体行数） |
| --max-nesting <N> | 5 | 深嵌套阈值（缩进/花括号深度） |
| --max-methods <N> | 10 | 上帝对象阈值（类方法数） |
| --max-class-lines <N> | 300 | 上帝对象阈值（类体行数） |
| --max-coupling <N> | 4 | 高耦合模块阈值（入度/出度） |
| --max-depth <N> | 4 | 目录扫描深度（1–10） |
| --include-dirs | - | 只分析这些目录 |
| --exclude-dirs | - | 额外排除目录 |
| --deps-json <file> | - | 复用 arch-profile --deps 的输出做耦合/环检测 |

示例输出（节选）：

{
"language": "javascript/typescript",
"smells": [
{
"rule": "god-object",
"type": "god_object",
"path": "src/lib/GodService.js",
"name": "GodService",
"methods": 12,
"threshold": 10,
"severity": 2,
"cost": "M"
}
]
}

输出

REFACTOR-PLAN.md：结构化重构计划，固定骨架为概览摘要 → 问题清单表（位置/类型/证据/严重度/成本/建议动作/风险）→ 优先级排序 → 依赖顺序编排 → 附录（规则阈值、扫描范围、生成时间）。

安全边界

- 只输出计划：不生成 diff、不自动改代码；高风险重构项必须人工确认。
- 只读扫描：诊断脚本零依赖、无子进程、无网络，不修改目标仓库源码。
- 事实与推断分离：脚本输出硬事实，LLM 补充的严重度/成本/建议均标注为推断。

排障

高耦合/环检测没有输出？ 该规则依赖依赖图输入：先跑 node scripts/arch-profile.mjs <repo_path> --deps > deps.json，再用 --deps-json deps.json 传入（见「快速开始」）。

诊断结果里混着误报？ 设计如此：脚本只给确定性硬事实，误报精修交给 runbook 中的 LLM 阶段（逐条核对并补充上下文）；CLI 单独使用时以 severity 与 evidence 字段自行判断。

TODO/FIXME 密度告警很多？ 该规则是噪音指标（仅输出每千行计数），不代表必须处理；在报告排序中权重最低。

升级 DSH 宿主到 0.1.5 系后旧会话打不开？ Session format V3 迁移不可逆，属宿主行为；升级宿主前请先备份会话日志（见 CHANGELOG.md 0.1.3 条目）。

文档

- docs/refactor-plan-template.md — REFACTOR-PLAN.md 输出骨架
- CHANGELOG.md — 版本变更记录
- PLUGIN-MAINTENANCE.md — 本仓维护规则
- DSH-REFACTOR-INSIGHT-开发计划.md — 设计决策与迭代历史

License

MIT