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_DISABLED_MCPS=codescene,... 在 ECC 安装/同步时排除它。
凭据： 无捆绑令牌。请自行设置 CS_ACCESS_TOKEN（参见上游仓库中的 getting-a-personal-access-token.md）。切勿将令牌提交到仓库。
工具读取内容： 调用时，工具会分析您指定的本地仓库中的文件和 git 状态（您传入的路径，以及 analyze_change_set 的分支上下文）。它们不会自动运行。对于独立模式，请遵循上游隐私文档：codescene-mcp-server README 和 CodeScene 政策。不要将此技能用于您不希望被分析的机密、凭据或路径。
如果 MCP 不可用（离线、令牌失效、服务器崩溃）： 不要自行编造 Code Health 评分。告知用户该检查已跳过。仅在获得用户明确批准后继续。当 MCP 宕机时，优先使用 lint/测试/验证循环作为门控。一旦服务器重新连接，重新启用检查。
何时使用
- 用户要求审查代码质量、重构文件，或检查 AI 更改是否降低了可维护性
- 在编辑热点文件、遗留模块或不熟悉的文件之前
- 在需要可维护性保障的提交或拉取请求之前
- 在 AI 产生的大幅 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）
| 范围 | 含义 | 智能体行为 |
|---|---|---|
| 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 上，仅使用独立工具的智能体循环：
- 对目标模块进行
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)
修改任何文件之前：运行 `code_health_review`，记录分数和问题。
- 分数低于 5：问题范围——严格限制改动范围。
- 分数 5–7：警告范围——不要进行大规模重构。
每次更改后：运行 `code_health_score` 验证差值。
- 如果分数退化：修复后再继续；分数下降时绝不可声明完成。
每次提交前：运行 `pre_commit_code_health_safeguard`。
发起 PR 前：运行 `analyze_change_set`。
示例：反模式与正确循环
# 错误：先编辑，后检查
[未使用 code_health_review 的大规模重构]
# 错误：忽略分数下降
"测试通过" → 在 Code Health 下降时标记任务完成
# 错误：对红色分数文件（低于 5）进行大规模重构
跨模块的附带清理
# 正确：审查 → 小改动 → 评分 → 提交防护 → analyze_change_set
与 ECC 配合
| ECC 技能/流程 | Code Health MCP 角色 |
|---|---|
coding-standards | 风格/命名；Code Health = 结构/复杂度 |
plankton-code-quality | 编写时的 lint/格式；Code Health = 编辑前后的结构性门控 |
verification-loop / /quality-gate | 在"完成"前添加结构性回归检查 |
security-review | 安全与可维护性——两者相关时同时使用 |
tdd-workflow | 测试通过 ≠ 优秀设计——重构后检查评分 |
上下文提示： ECC 建议保持 MCP 数量较低。在进行实质性编辑时启用 codescene；不需要时禁用它。
相关技能
coding-standards—— 基线约定plankton-code-quality—— 编写时的 lint/格式钩子verification-loop—— 构建/测试/lint 门控tdd-workflow—— 测试驱动开发security-review—— 安全检查清单documentation-lookup—— 通过 Context7 查阅库文档（正交功能）