Signalint

Signalint

Signalint 是一个可靠的诊断智能层，默认只读，面向 AI 编码 Agent（Claude Code、Cursor、Codex、VS Code）和 CI 工作流。

Signalint 不会用数千行原始编译器输出淹没 Agent 的上下文窗口，而是将编译器、代码检查工具和语言服务器的诊断信息标准化为数量受限、按优先级聚类的问题摘要，根据明确的基线计算验证差异，并检测修复循环振荡。

---

主要特色

• **13 个完整的 MCP 工具：**涵盖增量检查、不可变快照、实时诊断信息采集，以及带日志记录的事务性修复应用。
• **验证差异：**通过语义身份匹配，对新增、已解决和未变更的诊断进行精确计算，即使行号发生偏移也能保持匹配。
• **不可变快照与并发安全：**按 checkId 索引的隔离内存快照存储，可消除并发检查时的竞态冲突。
• **感知 Monorepo 的规划：**整合通过纯 JavaScript YAML 解析的包清单（pnpm-workspace.yaml）、带 glob 否定规则的排除项和 TypeScript Project References，并按拓扑顺序安排检查。
• **多源溯源：**区分 JavaScript、TypeScript、Python（Ruff/Mypy）、Rust（Clippy）和 Go（GolangCI-Lint）中的编译器、代码检查工具和编辑器/LSP 诊断信息。
• **可移植的宿主挂钩：**为 Claude Code、Cursor、Codex 和 VS Code 提供原生的变更后验证适配器。
• **内存预览与进程内回滚：**内存预览不会触碰磁盘；应用修复时会逐文件使用相邻临时文件进行替换、在写入前检测偏移，并在多文件写入时尽力在进程内回滚（不承诺在意外中止后持久恢复）。

---

快速开始

1. 环境要求

• Node.js >= 22.12.0（使用原生 node:sqlite）。
• 项目需自行安装诊断引擎（typescript、oxlint、eslint 和/或 @biomejs/biome）。Signalint 会检测项目本地的安装，不会随附诊断引擎。

2. 在代码库中初始化

npx signalint init

此操作会检测项目中的代码检查工具和编译器，生成 signalint.config.json，并配置已安装的 MCP 客户端。

3. 添加到 MCP 客户端

将 Signalint 添加到 MCP 配置中（例如 claude_desktop_config.json、.cursor/mcp.json）：

{
  "mcpServers": {
    "signalint": {
      "command": "npx",
      "args": ["-y", "signalint-mcp"]
    }
  }
}

---

完整的 MCP 工具目录

Signalint 通过标准输入/输出公开 13 个严格类型化的 MCP 工具：

工具	类别	安全注释	描述
ping	诊断	只读（idempotent）	验证服务响应情况和规范项目根路径。
check_project	诊断	只读（idempotent）	使用所有已启用的引擎全面扫描项目/工作区。
check_files	诊断	只读（idempotent）	使用内容哈希缓存，对指定文件进行快速增量检查。
get_issue_detail	诊断	只读（idempotent）	获取以不可变的 checkId 为锚点的完整、未省略的问题记录。
get_loop_status	诊断	只读（idempotent）	返回会话中检测到的循环振荡修复特征和规则变动。
get_diagnostic_snapshot	快照	只读（idempotent）	获取不可变检查快照的完整状态和指标。
compare_diagnostics	差异	只读（idempotent）	计算基线检查与当前检查之间的验证差异。
after_edit_check	差异	只读（idempotent）	对已编辑文件运行增量检查，并与基线检查进行差异比较。
ingest_diagnostics	实时 / LSP	只读（openWorld: false）	将外部 LSP 或编译器诊断信息导入 Signalint 的聚类模型。
get_live_diagnostics	实时 / LSP	只读（idempotent）	返回带来源信息的活动缓冲诊断信息。
preview_diagnostic_fix	事务	只读（destructive: false）	在内存中暂存提议的代码修复。不会写入磁盘。
apply_diagnostic_fix	事务	会修改数据（destructive: true）	按文件通过相邻临时文件替换，执行写入前偏移检查，并在进程内尽力回滚。
discard_diagnostic_fix	事务	只读（idempotent）	丢弃内存中的修复事务，不触碰磁盘。

完整的 JSON Schema 和错误代码请参阅 docs/mcp-contract.md。

---

CLI 命令

Signalint 提供了功能全面的命令行界面：

# Run a project diagnostic scan:
npx signalint check .
npx signalint check src/ --format github    # GitHub Actions annotations

# View session statistics and cache economics:
npx signalint stats

# Verify local engine availability and configuration:
npx signalint doctor

# Manage host verify-after-change hooks:
npx signalint hooks preview --runtime claude
npx signalint hooks install --runtime cursor --confirm
npx signalint hooks run --runtime claude --payload '<json-event>'

---

Monorepo 支持

Signalint 原生支持多包 Monorepo：

• 在 signalint.config.json 中配置 "monorepoMode": "auto"，即可通过纯 JavaScript YAML 解析检测 pnpm-workspace.yaml，并支持 glob 否定排除规则（!）。
• 严格区分本地工作区包（workspace:*）与外部 npm 注册表依赖项。
• 构建整合包清单和 TypeScript 项目引用的拓扑依赖图。
• 在隔离的包级目录（.signalint/cache/tsc/<project-id>/）中缓存整个程序的 TypeScript 构建。
• 对共享包的更改会自动使依赖包的缓存失效，同时保留独立同级包的缓存。

有关配置和架构，请参阅 docs/monorepo.md。

---

更改后验证钩子

自动执行编辑后的验证，同时避免形成无限 Agent 循环：

• 提供适用于 Claude Code、Cursor、Codex 和 VS Code 的原生适配器。
• 向提示词窗口发送有界上下文，并且仅在存在未解决的语法/类型错误时阻止操作。

有关设置说明，请参阅 docs/hooks.md。

---

文档索引

• 架构与子系统
• MCP 协议契约与 Schema
• 宿主钩子适配器指南
• Monorepo 规划与增量 TypeScript
• 已知限制与风险登记表
• 线缆传输精简基准测试
• 安全与威胁模型

---

许可证

MIT © 2026 Tran Trong Qui