多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

Repowise Code Health:用 `repowise health` 读懂每个文件的 1–10 分健康度

Repowise Code Health:用 `repowise health` 读懂每个文件的 1–10 分健康度 【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载导读Repowise 的 Code Health 是一个零 LLM、纯确定性计算的代码健康层为仓库中每个源文件给出一个 1–10 的分数并输出仓库级 KPI、最低分文件、重构目标与趋势告警。本指南围绕 Agent 命令 plugins/shared/commands/health.md 展开完整讲解repowise health的调用模式、参数语义、分数波段与解读原则并结合 health_cmd 源码 与 健康层架构文档 深入说明其工作原理。读完本文你将掌握如何用 CLI 与 MCP 工具定位最值得清理的文件、区分分数下降与代码变差并把覆盖率、重构队列与趋势数据接入日常工作流。一、什么是 Code Health 层Code Health 是 Repowise 的第五个智能层与 Graph、Git、Docs、Decisions 并列。它的核心产出是每个文件的确定性 1–10 分分值来自复杂度、深层嵌套、脑方法brain method、内聚性、重复代码、未测试热点等标记marker而不依赖任何大模型。正如命令文档所强调的No LLM — works even in index-only mode即使仓库只建了索引而没有配置任何 LLM Key健康分析也能完整运行。从实现看该层由packages/core/src/repowise/core/analysis/health/下的纯 Python 管道支撑见 架构文档引擎编排engine.py中的HealthAnalyzer负责遍历文件 → 标记投票 → 分类聚合打分 → 产出 HealthReport标记检测器biomarkers/目录注册了 53 个检测器含 3 个 governance 附加项共 56 个 marker id每个都是无状态的、实现Biomarker协议的类复杂性提取complexity/下的 tree-sitter AST walker 计算 CCN圈复杂度、嵌套深度、认知复杂度、参数个数与 NLOC持久化结果写入仓库.repowise/wiki.db中 SQLite 的四张表health_findings、health_file_metrics、health_snapshots、coverage_filesCLI、MCP server 与 Web 仪表盘都从同一份数据读取。一次典型运行的数据流是ingestionAST git→HealthAnalyzer→ HealthReport → 持久化全程无 JSON 缓存、无中间文件、无 LLM 参与。二、何时使用 health 命令命令文档规定了清晰的入口判断如果仓库还没有.repowise/索引目录CLI 会提示 This repo isnt indexed yet. Runrepowise initfirst. 并停止。也就是说repowise init # 首次全量索引健康分随索引一起写入 repowise health # 读取索引并出报告 repowise update # 增量路径只对变更文件重新打分从源码看repowise health有两种数据来源command.py已索引仓库从HealthFileMetric/HealthFinding读取快且与仪表盘、MCP 完全一致未索引仓库回退到进程内实时分析live in-process analysis代价是较慢但功能不变。命令文档要求 Agent 在拿到结果后给出可读摘要——分数、顶部 marker 发现及其含义——而不是原样倾倒原始表格。这一原则同样适用于所有下游使用场景。三、六种调用模式从默认仪表盘到细分视图repowise health默认无参数输出仪表盘 KPI 最低分文件repowise healthCLI 会通过$ARGUMENTS自动解析你的意图映射到不同参数你的意图实际命令说明看某个文件/目录repowise health path单文件也可用--file path深潜单个文件仓库相对路径重构候选repowise health --refactoring-targets按 impact/effort 排序的队列趋势repowise health --trend最近快照 下降/预测下降告警只看某个模块repowise health --module name只统计路径以该前缀开头的文件只看生产代码repowise health --scope production剔除测试文件见下文语义只看代码形状repowise health --counts code_shape剔除 git 派生的一半churn、co-change、ownership、prior fixes接入覆盖率repowise coverage add file后跟repowise health先摄入覆盖率报告再出健康分其他常用旗标--format json输出机器可读结果、-v/--verbose打印管道调试日志、--repo alias/--no-workspace用于 workspace 多仓库模式。3.1--scope production的语义陷阱命令文档特别提醒测试文件通常得分高于生产代码所以把范围收窄到production会压低每个数字但并不意味着发现了缺陷。默认值始终是all。从实现看scope.py定义了all/production两种取值production 过滤本质是读取HealthFileMetric.is_test列scope.py而该列由共享的路径分类器在入库时打标——所以在任何界面读取都一致。3.2--counts code_shape去掉历史那一半分数中约一半来自 git 变更历史churn、co-change、所有权、既往修复这些信号会随着文件被改动而上升。--counts code_shape把这一半剔除只按代码形状打分——回答的是我的代码本身在变好吗适合在一周重构导致 churn 升高时使用。实现上counts.py由于每个文件存储了structure_deduction与history_deduction两半code_shape_score只是做clamp(10 − structure_deduction)的减法不需要对 findings 重跑一遍。3.3 覆盖率coverage add先摄入健康分随后生效如果你手上有覆盖率报告如cov.lcov、coverage.xml、.coverage先摄入再出报告repowise coverage add coverage.lcov # 自动检测 LCOV 格式 repowise health # 覆盖相关 marker 开始生效从 架构文档 看覆盖率摄入后不仅折叠进健康 markeruntested_hotspot、coverage_gap、coverage_gradient当报告带上下文时还会构建 per-test 映射。支持 LCOV、Cobertura、Clover、JaCoCo、Go coverprofile 与 Repowise JSON 六种格式的自动检测。没有覆盖率报告时只有untested_hotspot按是否有测试触及来判定行覆盖率类 marker 保持静默——缺失的覆盖率永远不会被当作 0 来推断。四、分数波段五个固定词命令文档要求所有出现分数的地方一律使用同一套绝对波段词汇不要自创说法波段分数区间Excellent优秀8.5 及以上Good良好7.0 – 8.5Fair一般5.5 – 7.0Needs work需要改进4.0 – 5.5At risk高风险4.0 以下波段是绝对值而非百分位同一个 6.2 在任何仓库都代表同样的含义。分级逻辑集中在 grading.pyCLI 表格渲染时按波段着色command.py。五、如何解读下降 ≠ 回归命令文档给出了三条最重要的解读纪律分数的一半是变更历史随文件被修改而上升。因此下降不自动等于回归——如果趋势报告给出history_drag请如实说明代码形状没有变差修改这些文件也无法修复这一下降。history_drag是趋势层专门识别的一种告警复合头部数字下跌、但 driver 是history且结构那一半持平或改善见 trends.py 与 架构文档 §8。既低分又是 churn 热点的文件优先级最高应交叉引用{{cmd:risk}}或get_risk。从 MCP 侧看get_risk(targets)的每个目标行都携带health_score、top_biomarkers、line_coverage_pct、branch_coverage_pct天然支持这种交叉验证。如果所有文件都高分就直说不要凭空制造担忧。另外两点值得记住文件在健康层不支持的语言里如 Markdown、JSON、YAML 等非代码语言会被计为未分析永远不会被当成 10 分scope.py一个简单但频繁变动的文件只可能因为历史扣到 9.0 以下而不会低于该值——历史单独最多扣 1.0 分。六、分数如何计算从 10 分出发的扣分制每个文件从10.0起步。每个 finding 按严重度扣分low0.3、medium0.7、high1.2、critical2.0再乘以其 marker 的标定权重然后按类别聚合、每类设上限最终结果钳制在[1.0, 10.0]见 架构文档 §6。当某类超过上限时该类内所有 finding 的扣分按比例缩放保证界面上该 finding 扣了你 X 分依然真实成立——即使十个 critical 结构类 finding 同时出现结构复杂度一类最多也只扣 3.5 分。主要类别及上限对 defect 分数类别上限代表 markerOrganizational组织/流程−3.5天花板实际随结构扣分浮动change_entropy、churn_risk、co_change_scatter、ownership_risk、prior_defect 等Structural complexity−2.5brain_method、low_cohesion、god_class、nested_complexity、bumpy_roadTest coverage−2.0untested_hotspot、coverage_gapTest coverage gradient−2.0coverage_gradientSize complexity−1.5complex_method、large_method、primitive_obsessionDuplication−1.0dry_violationTest quality−0.5large_assertion_block、duplicated_assertion_blockError handling−0.5error_handling同一条 finding 流还会以独立的权重/上限表驱动maintainability可维护性与performance risk性能风险两个并列信号三个信号共用一套打分内核、互不反哺从不混成一个数字。权重表由缺陷语料离线标定以 NLOC 为显式控制变量做 L2 逻辑回归而非手工调参运行时保持确定性只发布学习到的常量架构文档 §6.1。七、机器可读输出与 CI 集成--format json输出结构化结果可直接管道给jqrepowise health --format json | jq .kpis从 command.py 可以看到 JSON 载荷结构kpisaverage_health、hotspot_health、worst_performer_score 等、scope、counts、metrics每个文件带score、max_ccn、max_nesting、nloc、has_test_file、line_coverage_pct、branch_coverage_pct、duplication_pct以及findingsbiomarker_type、severity、file_path、function_name、health_impact、details、reason。此外还支持--format md输出简化的 Markdown 报告。两个实现细节值得注意json/md 格式不写索引避免脚本和 CI 产生副作用且状态输出走 stderr保证 stdout 纯净、可安全管道command.py。repowise status则用同一批表输出一行摘要例如Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: packages/server/.../app.py)八、重构队列与趋势8.1--refactoring-targets按影响/成本排序的队列该模式打印索引里已存好的重构队列顺序与 MCP 和 Web UI 一致command.py。如果仓库还没有存储的分析结果会提示运行repowise init/repowise update或显式加--recompute在进程内分析当前工作树。注意--scope/--counts不作用于已存储的队列需要--recompute才能应用。另有可选的--generate-code SELECTOR按 1 基排名或目标符号匹配让配置的 LLM 生成重构代码与 diff——这是全流程中唯一按需使用 LLM 的地方且必须显式请求、永不自动应用需要配置 API Key。8.2--trend最近 10 个快照与告警repowise health --trend每次运行init、health、update --full都会写入一个快照仓库级滚动保留最近 50 个。告警规则架构文档 §8Declining Health当前分比 5 个快照前低至少 0.5Predicted Decline最近三个快照逐个严格递减不看幅度方向即信号history_drag两种告警中驱动者是历史半分的变体——结构半分持平或改善此时代码本身没有可行动项。--trend读取的是已存快照所以--scope和--counts对它不适用命令会明确提示。趋势在历史过薄时保持静默少于两个数据点不输出单文件序列。九、Agent 使用的最佳实践清单综合命令文档与源码把repowise health正确嵌入工作流的关键点先索引无.repowise/时先跑repowise init不要跳过。按需选择模式全局 KPI 用默认单个文件深潜用--file path定位清理对象用--refactoring-targets观察退化用--trend过滤测试文件用--scope production评估纯代码形状用--counts code_shape。先摄入覆盖率再打分repowise coverage add支持六种格式自动检测重复执行会覆盖旧数据。解读时用固定波段词Excellent / Good / Fair / Needs work / At risk区间为 8.5 / 7.0–8.5 / 5.5–7.0 / 4.0–5.5 / 4.0。区分下降与变差看到history_drag就明说代码形状没恶化低分 churn 热点的文件优先处理并交叉引用get_risk。机器输出走--format jsonstdout 纯净可管道jqjson/md 模式不写索引适合 CI。十、延伸阅读docs/layers/CODE_HEALTH.md用户视角的完整健康层指南——三分信号、Fix first 列表、性能发现与.repowise/health-rules.json配置。docs/architecture/code-health.md贡献者视角的内部实现——53 个检测器名册、类别上限、权重标定协议、趋势与 Fix first 排名规则。docs/BENCHMARKS.md代码健康预测缺陷的公开评测数据与测试方法。docs/reference/CONFIG.md.repowise/health-rules.json完整 schema 与assertions:配置块。MCP 侧对应工具get_health(targets?, include?, repo?, limit?)支持include[biomarkers, coverage, refactoring, trend, accuracy, performance]等选项见 docs/agent/MCP_TOOLS.md。赞分享【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载相关推荐Repowise Code Health 完全指南用 /repowise:health 读懂仓库的确定性 1–10 健康评分Repowise Code Health 完全指南用 /repowise:health 读懂仓库的确定性 1–10 健康评分 本文以 Repowise 插件中RepoWise Code Health 分析层深度解析26 个确定性标记、1–10 分健康评分与重构目标排序RepoWise Code Health 分析层深度解析26 个确定性标记、1–10 分健康评分与重构目标排序 导读 本文以 RepoWise 开源仓库中Repowise 代码健康分析实战指南从 get_health 到 repowise health 的完整工作流Repowise 代码健康分析实战指南从 get_health 到 repowise health 的完整工作流 Repowise 的 Code Health上一篇Android TabLayout终极指南FlycoTabLayout深度解析与实战技巧下一篇零基础掌握v3-admin-vite状态管理Pinia高级实战指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表