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/测试/验证循环作为门禁。当服务器重新连接后，再恢复检查。
何时使用
- 用户要求审查代码质量、重构文件，或检查 AI 修改是否降低了可维护性
- 在编辑一个热区、遗留模块或不熟悉的文件之前
- 在提交或拉取请求之前，需要可维护性保障
- 在大型 Agent 编写的 diff 之后 —— 验证 Code Health 没有退化
- 与
verification-loop、tdd-workflow或/quality-gate配合使用，作为结构性检查（不是替代测试/Lint）
何时激活
与上述何时使用的触发条件相同 —— 此标题是 ECC 用于技能自动激活的依据。
工作原理
1. 连接 MCP 服务器
将 mcp-configs/mcp-servers.json 中的 codescene 条目复制到你的主环境 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 | 每次修改后快速获取数值分数（Delta 检查） |
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)
在修改任何文件之前：运行 `code_health_review`，记录分数和问题。
- 分数低于 5：问题范围 —— 窄范围限定修改。
- 分数 5–7：警告范围 —— 不做广泛重构。
每次修改后：运行 `code_health_score` 验证 Delta。
- 如果分数下降：修复后再继续；分数下降时绝不要声明完成。
每次提交前：运行 `pre_commit_code_health_safeguard`。
PR 前：运行 `analyze_change_set`。
示例：反模式 vs 正确循环
# 错误：先编辑，后检查
[不运行 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 | 安全 vs 可维护性 —— 在相关时同时使用 |
tdd-workflow | 测试通过 ≠ 设计健康 —— 重构后检查分数 |
上下文提示： ECC 建议保持较少的 MCP 数量。在执行实质性编辑时启用 codescene；不需要时禁用它。
相关技能
coding-standards—— 基础约定plankton-code-quality—— 编写时 Lint/格式化钩子verification-loop—— 构建/测试/Lint 门禁tdd-workflow—— 测试驱动开发security-review—— 安全检查清单documentation-lookup—— 通过 Context7 查找库文档（正交）