LiDAR Harness

增量验证引擎 — 作为可插拔 MCP 中间件，用于 Claude Code、OpenCode 等代码代理。

受 SLAM 建图中 PGO（位姿图优化）启发，LiDAR Harness 提供四层验证架构，在不增加每轮上下文负担的前提下，确保 agent 输出的代码质量。

---

核心概念

大多数代码 agent 的工作方式是：每轮修改代码后，全量运行 tsc / lint，把全部错误注入回上下文。这在 10 轮以上的任务中会浪费大量 token。

LiDAR Harness 的 PGO（Pose Graph Optimization）引擎采用 增量机制：

首次:  tsc --noEmit  → 发现 7 个错误  → 全部注入
第 2 轮: 修复了 3 个 → 剩余 4 个已知，0 个新增 → 不注入，agent 不被打断
第 3 轮: 引入了 1 个新错误 → 只注入这 1 个新错误
...

效果：上下文占用减少 60-80%，且与 DeepSeek V4 MLA KV cache 复用机制兼容——固定的输出 schema 结构确保每轮前缀缓存命中。

---

功能

工具	用途	典型时机
harness_init	初始化项目，自动检测 typecheck/lint 命令，建立基线	会话开始一次
harness_classify	判断任务是 "simple"（问答）还是 "complex"（编码）	用户发消息后
harness_pgo	增量检查 — 只返回新出现的 typecheck/lint 错误	每轮修改代码后
harness_review	多视角代码审查（安全扫描、正确性、风格）	每 3 轮
harness_reset	重置 PGO 状态	切换任务时

架构

Model completes a turn (modifies code)
       │
       ▼
  ┌──────────────────────┐
  │ Layer 0: Gate        │  ─── 简单任务（问答/解释）→ 跳过后续所有验证
  └────────┬─────────────┘
           ▼
  ┌──────────────────────┐
  │ Layer 2: PGO         │  ─── typecheck + lint，增量注入（核心功能）
  └────────┬─────────────┘
           ▼
  ┌──────────────────────┐
  │ Layer 3: MultiReview │  ─── 安全/正确性/风格（每 3 轮）
  └──────────────────────┘

---

v0.2.0 新增（2026-06）

被绑架机器人自动恢复（Auto-reset on error explosion）

灵感来自 SLAM 的 kidnapped robot problem。

当单轮新增错误数超过阈值（默认 15）时，说明 PGO 状态已失效（典型场景：依赖升级、tsconfig 大幅变更）。引擎会自动重新建立基线，并在结果中标注 autoReset: true，让 agent 知道发生了状态重置。

之前的行为（手动 harness_reset）：agent 在废墟上无限迭代。
现在：自动识别失效状态，重新校准，继续收敛。

输出 schema 稳定化（KV cache 友好）

harness_pgo 的输出字段顺序固定为：

{
  "converged": false,
  "autoReset": false,
  "newErrorCount": 2,
  "totalUniqueErrors": 5,
  "newErrors": ["..."],
  "message": "..."
}

每轮只有值变化，结构不变。配合 DeepSeek V4 MLA 的 KV cache 机制，可显著提升多轮 session 的 prefill 缓存命中率。

---

快速开始

前提

• Node.js >= 18
• 一个 MCP 客户端（Claude Code、OpenCode、或任何 MCP 兼容工具）

安装

git clone https://github.com/bernardleex526-png/lidar_harness_mcp.git
cd lidar_harness_mcp
npm install
npm run build

集成到 Claude Code

在项目 .claude/settings.local.json 中添加：

{
  "mcpServers": {
    "lidar-harness": {
      "command": "node",
      "args": ["/path/to/lidar_harness_mcp/dist/index.js"]
    }
  }
}

重启 Claude Code 后，5 个工具会自动可用。

集成到 OpenCode

{
  "mcpServers": {
    "lidar-harness": {
      "command": "node",
      "args": ["/path/to/lidar_harness_mcp/dist/index.js"]
    }
  }
}

直接测试

# 列出工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# 初始化项目
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"harness_init","arguments":{"cwd":"/your/project","taskMessage":"fix the build"}}}' | node dist/index.js

---

工作流程示例

User: 帮我重构这个模块
Claude: [调用 harness_init 初始化，检测到 tsc 和 lint]
Claude: [完成任务，调用 harness_pgo 检查]
Claude: → 编译通过，无新错误
Claude: 重构完成。

User: 添加一个 API 端点
Claude: [修改代码，调用 harness_pgo]
Claude: → 发现 2 个新类型错误，需要修复
Claude: [修复错误，再次调用 harness_pgo]
Claude: → 0 个新错误，autoReset: false，编译通过

---

自动检测支持的语言

语言	检测文件	默认命令
TypeScript	tsconfig.json	npx tsc --noEmit, npm run lint（如果有 lint script）
Go	go.mod	go vet ./...
Rust	Cargo.toml	cargo check
Java (Maven)	pom.xml	mvn compile -q
Java (Gradle)	build.gradle	gradle build -q

---

项目结构

lidar-harness-mcp/
├── src/
│   ├── index.ts           # MCP Server 入口，工具注册
│   └── harness/
│       ├── pgo.ts         # PGO 增量验证引擎
│       ├── pgo.test.ts    # 单元测试（vitest）
│       ├── review.ts      # 多视角代码审查
│       └── gate.ts        # 复杂度门控
├── package.json
├── tsconfig.json
└── README.md

零运行时依赖（除 @modelcontextprotocol/sdk 外）。

---

License

MIT