codehealth-mcp

用途

Code Health MCP（CodeScene）为 AI 辅助编程提供结构化的可维护性反馈。它补充了风格与 lint 类技能（如 coding-standards、plankton-code-quality），从设计层面给出健康评分与回归门禁。

上游项目：codescene-oss/codescene-mcp-server 包名：@codescene/codehealth-mcp（通过 npx 以 stdio 方式运行）

安全与边界

选择性启用（ECC）：mcp-configs/mcp-servers.json 中的 codescene 块仅为模板。ECC 插件安装不会自动启用捆绑的 MCP 服务器。只有在你需要时才将该条目复制到你的配置中。你可以在 ECC 安装/同步时通过 ECC_DISABLED_MCPS=codescene,... 将其排除。
凭据：不捆绑令牌。请自行设置 CS_ACCESS_TOKEN（参见上游仓库中的 getting-a-personal-access-token.md）。切勿将令牌提交到仓库。
工具读取的内容：调用时，工具会分析你指向的本地仓库中的文件和 git 状态（你传入的路径，以及 analyze_change_set 的分支上下文）。它们不会自行运行。独立模式下，请遵循上游隐私文档：codescene-mcp-server README 和 CodeScene 政策。不要将此技能用于机密、凭据或你不希望被分析的路径。
如果 MCP 不可用（离线、令牌错误、服务器崩溃）：不要编造 Code Health 评分。告知用户检查已跳过。仅在用户明确批准后继续。MCP 不可用时，优先使用 lint/测试/verification-loop 进行门禁。服务器连接后重新启用检查。

何时使用

用户要求审查代码质量、重构文件，或检查 AI 改动是否降低了可维护性
编辑热点、遗留模块或不熟悉的文件之前
提交或拉取请求之前，需要可维护性保障时
大型 agent 编写的 diff 之后——验证 Code Health 未退化
与 verification-loop、tdd-workflow 或 /quality-gate 搭配作为结构检查（不能替代测试/lint）

何时激活

与上述“何时使用”相同的触发条件——此标题是 ECC 用于技能自动激活的依据。

工作原理

1. 连接 MCP 服务器

将 mcp-configs/mcp-servers.json 中的 codescene 条目复制到你的 harness MCP 配置中。

Claude Code（~/.claude.json → mcpServers）：

"codescene": {
  "command": "npx",
  "args": ["-y", "@codescene/codehealth-mcp"],
  "env": {
    "CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
  }
}

项目级：将同一块合并到仓库根目录的 .mcp.json 中。

令牌设置记录在上游仓库中（链接见上）。独立模式不需要付费 CodeScene 平台账号即可使用下面列出的四个工具。重启会话，并在依赖评分之前确认 codescene 服务器已连接。

2. 仅调用独立工具

工具	何时使用
code_health_review	修改文件前的完整结构分析
code_health_score	每次改动后的快速数值评分（增量检查）
pre_commit_code_health_safeguard	阻止引入 Code Health 退化的提交
analyze_change_set	开 PR 前的分支级检查

不要调用仅平台可用的工具（例如仓库级技术债务热点列表）。不要引用 delta_analysis——独立模式下不可用。

3. 解读评分（1–10）

范围	含义	Agent 行为
9.0–10.0	绿色——健康	较安全地扩展；仍优先垂直切片
4.0–8.9	黄色——债务	谨慎行事；不要顺手重构
1.0–3.9	红色——严重债务	仅限窄范围

4. 运行反馈循环

触碰文件之前

对目标路径运行 code_health_review。
记录基线评分和列出的代码异味。
规划解决任务的最小改动。
按评分限定范围：低于 5——仅最小 diff；5–7——不做大范围重构；高于 7——重构较安全，但每次编辑后仍需验证。

每次改动之后

对同一文件运行 code_health_score。
与 code_health_review 的基线比较。
如果评分退化，继续之前先修复。评分低于开始时，绝不标记任务完成。

每次提交之前——对仓库路径运行 pre_commit_code_health_safeguard。

PR 之前——针对基础分支（例如 main）运行 analyze_change_set。

示例

示例：Flask 可维护性改进

在 pallets/flask 上，仅使用独立工具的 agent 循环：

对目标模块运行 code_health_review（基线 4.82）
针对列出的异味进行定向重构
每次编辑后运行 code_health_score
提交前运行 pre_commit_code_health_safeguard
PR 前运行 analyze_change_set

结果：Code Health 4.82 → 9.1（仅使用免费独立令牌）。

示例：AGENTS.md 强制块

粘贴到项目 AGENTS.md 或 CLAUDE.md：

## Code Health (CodeScene MCP)

Before modifying any file: run `code_health_review`, note score and issues.

- Score below 5: problematic range — scope changes narrowly.
- Score 5–7: warning range — no broad refactors.

After each change: run `code_health_score` to verify delta.

- If score regressed: fix before continuing; never declare done if score dropped.

Before every commit: run `pre_commit_code_health_safeguard`.

Before PR: run `analyze_change_set`.

示例：反模式 vs 正确循环

# BAD: Edit first, check later
[large refactor without code_health_review]

# BAD: Ignore score drop
"Tests pass" → mark task done while Code Health decreased

# BAD: Broad refactor on red-score file (below 5)
Drive-by cleanup across the module

# GOOD: review → small change → score → commit safeguard → analyze_change_set

与 ECC 搭配

ECC 技能/流程	Code Health MCP 角色
coding-standards	风格/命名；Code Health = 结构/复杂度
plankton-code-quality	写入时 lint/format；Code Health = 编辑前后结构门禁
verification-loop / /quality-gate	在“完成”前增加结构回归检查
security-review	安全 vs 可维护性——相关时两者都用
tdd-workflow	测试通过 ≠ 设计健康——重构后检查评分

上下文提示：ECC 建议保持较低的 MCP 数量。进行实质性编辑时启用 codescene；不需要时禁用。

技能介绍

用途