AI 编码 Agent 做着做着就跑偏了？Mindlas 实时捕捉上下文腐烂，在坏代码落地前喊停

用过 Claude Code、Codex 或 Cursor 做复杂重构的人，大概率都经历过这个场景：前 20 个回合一切正常，代码在往正确的方向演进。到第 40 个回合，Agent 开始做奇怪的事——改了一个不该改的文件，重复调用同一个失败的工具，或者干脆忘记了最初要解决的问题。

问题不在第一回合，而在第四十回合。

Agent 不会突然变笨。它的上下文在悄悄腐烂（Context Rot）：工具输出堆积、早期决策被淹没、错误循环没有被识别。而最危险的是，Agent 仍然在自信地输出代码，没有任何错误信号告诉你它已经跑偏了。

这就是 Mindlas（Mind-Atlas）要解决的问题——一个开源的、本地的、纯确定性的实时 Agent 漂移检测器。

问题的本质：你的 Agent 不像人，不会说”等一下，我好像偏了”

人在做复杂任务时，如果发现自己在绕圈子或忘记上下文，会有直觉——”不太对劲”。但 AI 编码 Agent 没有这种直觉。它会在工具输出噪音中继续推进任务，在最原始的任务描述被埋没后仍然声称”Done”。

Mindlas 的 README 一句话点出了核心洞察：

“A coding agent rarely fails at turn one. It fails at turn forty.”

这不是 Agent 的模型问题，而是会话衰减问题：上下文窗口被大量工具输出填满，早期任务契约被推挤到窗口边缘，编辑散布在多个文件中，同一个工具调用反复失败却没有任何停止机制。

Mindlas 的做法：四组仪表盘，实时读数

Mindlas 不依赖另一个 LLM 来”评估”当前 Agent 的状态（那本身就是一个不可复现、昂贵且有循环依赖风险的做法）。它的所有评分都是纯确定性函数——相同的会话事件账本，永远产生相同的评分结果。没有网络调用，没有模型推理，纯本地执行。

它定义了四种已知的衰减原因，每个原因对应一个仪表盘（Gauge）和一个修复动作：

每个仪表盘有三个阈值带：WATCH（提示）、WARNING（正式建议）、ALERT（必须修复）。每个修复动作都是一个可预览的干运行命令，执行前后都会记录评分变化。

安装：一行命令搞定

pip install mindlas

安装后可以直接用 demo 模式体验完整流程：

mindlas status --demo context_rot_alert

mindlas context repair --apply --demo context_rot_alert

两条命令不需要实际的 Claude Code 会话——demo 模式使用内置的离线 fixture，零网络、零 API 费用。

接入你的实时会话：两种方式，任选其一

方式 A — 插件模式（推荐）

在 Mindlas 克隆目录中，用 --plugin-dir 启动 Claude Code：

claude --plugin-dir /path/to/MINDLAS
mindlas install-statusline

插件模式会加载 8 个事件钩子（hook）和 5 个修复斜杠命令。钩子负责记录会话事件到账本，斜杠命令执行修复操作。修复命令包括：

• /mindlas-repair — 上下文修复
• /mindlas-verify — 验证门禁
• /mindlas-blast-split — 补丁拆分
• /mindlas-loop-stop — 循环停止
• /mindlas-loop-release — 循环释放

每个钩子都是 best-effort 设计，执行失败不会阻塞或中断 Agent 的会话——安全第一条。

方式 B — CLI 钩子安装

当无法加载插件时（比如你的环境限制），可以通过 CLI 直接安装相同的 8 个钩子到 Claude Code 的 settings.json：

mindlas install-hooks
mindlas install-statusline

CLI 模式下没有斜杠命令，修复操作通过等效的子命令执行：mindlas context repair、mindlas verify gate、mindlas loop stop 等。

无论哪种方式，两样东西是一体的：记录会话事件的钩子，和始终显示在 Prompt（提示符）下方的状态行。

深入四个仪表盘

Context Rot（上下文腐烂）

六个信号综合评分：会话轮数、大型工具输出量、任务契约年龄、未解决的用户修正次数、以及自上次修复以来的会话轮数。最后一个信号只有 Context Repair 运行时才会重置——原生 /compact 不会，因为压缩短了对话但不会重建 Agent 的工作状态。

当 ROT 达到 ALERT 阈值（80+），执行 /mindlas-repair。它会从事件账本重建一个紧凑的九段修复包：任务契约、约束条件、仓库状态、差异状态、下一步行动、以及一个带 SHA256 引用的证据索引。八道验证门禁必须全部通过，修复包才会生效。

Verification Debt（验证债务）

代码改了但还没有新鲜证据证明它仍然正确工作时，VERIFY 开始累积。计分因子包括：变更文件数和行数、最近验证结果的时效性、线上变更没有伴随测试（额外扣分）、”Done”声明没有附带证据（额外扣分）。如果树是干净的，VERIFY 就是 0。

Change Blast Radius（变更冲击半径）

一个补丁跨越了多少文件、目录和关注点——不是代码错了，而是审核风险高了。小范围的高内聚补丁会得到”内聚信用分”，不会触发 BLAST。当 BLAST 升高时，用 /mindlas-blast-split 将大补丁拆成可独立审核的小包（存在 .mindlas/splits/ 下，不触碰源文件）。

Tool Failure Loop（工具失败循环）

Agent 卡在重复调用同一个失败的工具上。LOOP 计分基于当前证据段内的重复次数——一次成功调用或用户输入都会打破循环。检测到循环时，LOOP 仪表盘转为 controlled（受控）状态而非”已修复”——因为只有用户确认问题已解决才算数。

证据主义：分数卡，不靠感觉

每次修复执行后，Mindlas 生成一个可导出的 JSON 分数卡：

mindlas scorecard --json

{
  "session_id": "demo",
  "features": {
    "context_rot":         { "max": 100, "final": 4, "alerts": 1 },
    "verification_debt":   { "max": 0, "final": 0, "alerts": 0 },
    "change_blast_radius": { "max": 0, "final": 0, "final_status": "planned" },
    "tool_failure_loop":   { "max": 0, "final": 0, "final_status": "controlled" }
  },
  "corrections": [
    {
      "type": "context_repair",
      "applied": true,
      "validation": "pass",
      "before": 100,
      "modeled_after_ctx": 4
    }
  ]
}

每个 after-score 都被明确标注其性质：modeled（建模估算）、measured（实际测量）、evidence-based、planned 或 controlled。没有虚假的高置信度标签——一个只检查了两个文件的验证门禁，不会声称覆盖了十个。

适合谁用？

• 重度 Claude Code / Codex 用户：每天有 100+ 轮次长会话，出现过”Agent 做了一半跑偏”的情况
• 团队代码审查者：审查 Agent 产生的代码时，想确认变更前后上下文是否完整
• 安全敏感的 Agent 工作流：可以用 MINDLAS_GATE=block 和 MINDLAS_LOOP_GUARD=block 让 Mindlas 在检测到风险时直接阻断操作而非仅警告

总结

Mindlas 解决的是 AI 编码 Agent 的一个真实盲点——会话衰减。它不做”Agent 能力评判”这种模糊的事，而是聚焦在一个狭窄但可验证的目标上：从确定性本地信号中检测已知的衰减原因，应用非侵入式的修复，记录修复前后的效果，并输出可导出的分数卡。

项目完全开源（Apache 2.0），纯 Python 实现，pip 一键安装。对于每天和 Claude Code 或 Codex 打交道的开发者来说，这是一个值得放在工具箱里的实用工具。

相关链接

• GitHub: https://github.com/Evolutionairy-AI/MINDLAS
• PyPI: https://pypi.org/project/mindlas/