用途
ctxlint 用于检查 AI 智能体的上下文文件（如 CLAUDE.md、AGENTS.md、.cursorrules 等）以及 MCP 服务器配置文件，确保它们与代码库保持一致。当文件重命名、构建脚本变更或测试框架切换时，这些上下文文件容易过时，导致 AI 智能体依据错误信息执行任务。ctxlint 能提前发现此类问题。
主要能力
- 上下文文件检查：检测失效路径、错误命令、过时引用以及文件之间的矛盾。
- MCP 配置检查：扫描 .mcp.json 等配置文件，发现硬编码 API 密钥、无效引用、已弃用字段等问题。
- 会话审计：可选地审计智能体会话历史和记忆条目，检查跨项目一致性和缺失设置。
- Token 感知：显示上下文文件消耗的上下文窗口大小，并标记冗余内容。
- 自动修复：通过 --fix 参数，利用 Git 历史自动重写失效路径。
- 多格式输出：支持文本、JSON 和 SARIF（用于 GitHub 代码扫描）。
- MCP 服务器：提供 7 个工具（ctxlint_audit、ctxlint_mcp_audit、ctxlint_session_audit、ctxlint_skill_audit、ctxlint_validate_path、ctxlint_token_report、ctxlint_fix），可与 IDE 或智能体集成。
- 监控模式：--watch 参数在上下文文件变更时自动重新检查。
- 支持广泛：覆盖 Claude Code、Cursor、Copilot、Windsurf、Gemini、Cline、Aider 等 16 种 AI 工具，以及 8 种 MCP 客户端。
使用方式
无需安装直接运行：
npx ctxlint
项目安装（推荐团队使用）：
npm install --save-dev ctxlint
添加到 package.json 脚本：
{
"scripts": {
"lint:ctx": "ctxlint"
}
}
或在每个项目中全局可用而无需逐项目安装。
常用选项：
--strict：在 CI 中强制执行（非严格模式始终退出 0）。--fix：自动修复失效路径。--watch：监控文件变化并重新检查。--mcp：启用 MCP 配置检查。--mcp-global：额外扫描全局 MCP 配置（Claude Desktop、Cursor、Windsurf、Amazon Q）。--session：启用会话检查（可选，访问项目目录外的文件）。--skills：启用技能检查。--config <path>：指定配置文件位置。--no-ignore-file：本次运行跳过忽略文件。
配置文件：在项目根目录创建 .ctxlintrc 或 .ctxlintrc.json。
{
"contextFiles": ["CONVENTIONS.md"],
"exclude": ["test/fixtures/**"]
}
忽略文件：.ctxlintignore，每行格式为 checkName [fileGlob] [# reason]，用于抑制特定发现。
用于 MCP 服务器：
npx ctxlint serve
或在 .mcp.json 中配置：
{
"mcpServers": {
"ctxlint": {
"command": "npx",
"args": ["ctxlint", "serve"]
}
}
}
CI 集成：支持 SARIF 输出用于 GitHub 代码扫描，可设置为 pre-commit 钩子或 pre-commit 框架。
适用场景
- 开发团队维护多个 AI 上下文文件和 MCP 配置时。
- 在 CI 流程中自动检查上下文文件一致性。
- 在提交代码前通过 Git 钩子阻止过时上下文文件进入仓库。
- 作为 MCP 服务器供 IDE 或 AI 智能体调用，实时验证路径和配置。
限制
- 会话检查为可选功能，因需访问项目目录外的文件（如用户主目录下的智能体历史记录、父目录中的兄弟仓库）。
- 非严格模式下始终退出 0，仅在 CI 中通过 --strict 强制执行。
- 具体支持的全部 16 种 AI 工具和 8 种 MCP 客户端的完整列表、收费模式、价格等信息暂未提供。
- 安装包大小约 400 KB（tarball），零运行时依赖。
规范
ctxlint 是四个开放规范的参考实现，包括上下文检查规范、MCP 配置检查规范、会话检查规范和技能检查规范，均提供机器可读的规则目录，任何 linter、IDE 扩展或 CI 系统均可实现。
