企业官网建设流程全解析

导读：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_files），CLI、MCP server 与 Web 仪表盘都从同一份数据读取。

一次典型运行的数据流是：ingestion（AST + git）→HealthAnalyzer→ HealthReport → 持久化；全程无 JSON 缓存、无中间文件、无 LLM 参与。

二、何时使用 health 命令

命令文档规定了清晰的入口判断：如果仓库还没有.repowise/索引目录，CLI 会提示 "This repo isn't indexed yet. Runrepowise initfirst." 并停止。也就是说：

repowise init # 首次全量索引，健康分随索引一起写入 repowise health # 读取索引并出报告 repowise update # 增量路径：只对变更文件重新打分

从源码看，repowise health有两种数据来源（command.py）：

1. 已索引仓库：从HealthFileMetric/HealthFinding读取，快且与仪表盘、MCP 完全一致；
2. 未索引仓库：回退到进程内实时分析（live in-process analysis），代价是较慢，但功能不变。

命令文档要求 Agent 在拿到结果后给出可读摘要——分数、顶部 marker 发现及其含义——而不是原样倾倒原始表格。这一原则同样适用于所有下游使用场景。

三、六种调用模式：从默认仪表盘到细分视图

repowise health默认（无参数）输出仪表盘 KPI + 最低分文件：

repowise health

CLI 会通过$ARGUMENTS自动解析你的意图，映射到不同参数：

其他常用旗标：--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 开始生效

从 架构文档 看，覆盖率摄入后不仅折叠进健康 marker（untested_hotspot、coverage_gap、coverage_gradient），当报告带上下文时还会构建 per-test 映射。支持 LCOV、Cobertura、Clover、JaCoCo、Go coverprofile 与 Repowise JSON 六种格式的自动检测。没有覆盖率报告时，只有untested_hotspot按"是否有测试触及"来判定，行覆盖率类 marker 保持静默——缺失的覆盖率永远不会被当作 0 来推断。

四、分数波段：五个固定词

命令文档要求，所有出现分数的地方一律使用同一套绝对波段词汇，不要自创说法：

波段是绝对值而非百分位：同一个 6.2 在任何仓库都代表同样的含义。分级逻辑集中在 grading.py，CLI 表格渲染时按波段着色（command.py）。

五、如何解读：下降 ≠ 回归

命令文档给出了三条最重要的解读纪律：

1. 分数的一半是变更历史，随文件被修改而上升。因此下降不自动等于回归——如果趋势报告给出history_drag，请如实说明：代码形状没有变差，修改这些文件也无法"修复"这一下降。history_drag是趋势层专门识别的一种告警：复合头部数字下跌、但 driver 是history且结构那一半持平或改善（见 trends.py 与 架构文档 §8）。
2. 既低分又是 churn 热点的文件优先级最高，应交叉引用{{cmd:risk}}或get_risk。从 MCP 侧看，get_risk(targets)的每个目标行都携带health_score、top_biomarkers、line_coverage_pct、branch_coverage_pct，天然支持这种交叉验证。
3. 如果所有文件都高分，就直说，不要凭空制造担忧。

另外两点值得记住：文件在健康层不支持的语言里（如 Markdown、JSON、YAML 等非代码语言）会被计为"未分析"，永远不会被当成 10 分（scope.py）；一个简单但频繁变动的文件只可能因为历史扣到 9.0 以下，而不会低于该值——历史单独最多扣 1.0 分。

六、分数如何计算：从 10 分出发的扣分制

每个文件从10.0起步。每个 finding 按严重度扣分（low=0.3、medium=0.7、high=1.2、critical=2.0），再乘以其 marker 的标定权重，然后按类别聚合、每类设上限，最终结果钳制在[1.0, 10.0]（见 架构文档 §6）。当某类超过上限时，该类内所有 finding 的扣分按比例缩放，保证界面上"该 finding 扣了你 X 分"依然真实成立——即使十个 critical 结构类 finding 同时出现，结构复杂度一类最多也只扣 3.5 分。

主要类别及上限（对 defect 分数）：

同一条 finding 流还会以独立的权重/上限表驱动maintainability（可维护性）与performance risk（性能风险）两个并列信号，三个信号共用一套打分内核、互不反哺，从不混成一个数字。权重表由缺陷语料离线标定（以 NLOC 为显式控制变量做 L2 逻辑回归），而非手工调参；运行时保持确定性，只发布学习到的常量（架构文档 §6.1）。

七、机器可读输出与 CI 集成

--format json输出结构化结果，可直接管道给jq：

repowise health --format json | jq .kpis

从 command.py 可以看到 JSON 载荷结构：kpis（average_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）以及findings（biomarker_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 个。告警规则（架构文档 §8）：

• Declining Health：当前分比 5 个快照前低至少 0.5；
• Predicted Decline：最近三个快照逐个严格递减（不看幅度，方向即信号）；
• history_drag：两种告警中驱动者是历史半分的变体——结构半分持平或改善，此时代码本身没有可行动项。

--trend读取的是已存快照，所以--scope和--counts对它不适用，命令会明确提示。趋势在历史过薄时保持静默（少于两个数据点不输出单文件序列）。

九、Agent 使用的最佳实践清单

综合命令文档与源码，把repowise health正确嵌入工作流的关键点：

1. 先索引：无.repowise/时先跑repowise init，不要跳过。
2. 按需选择模式：全局 KPI 用默认；单个文件深潜用--file <path>；定位清理对象用--refactoring-targets；观察退化用--trend；过滤测试文件用--scope production；评估纯代码形状用--counts code_shape。
3. 先摄入覆盖率再打分：repowise coverage add支持六种格式自动检测，重复执行会覆盖旧数据。
4. 解读时用固定波段词：Excellent / Good / Fair / Needs work / At risk，区间为 8.5+ / 7.0–8.5 / 5.5–7.0 / 4.0–5.5 / <4.0。
5. 区分"下降"与"变差"：看到history_drag就明说代码形状没恶化；低分 + churn 热点的文件优先处理，并交叉引用get_risk。
6. 机器输出走--format json：stdout 纯净，可管道jq；json/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。