🦎 CAVETAIL — 代码整洁 MCP 服务器

零废话。自文档化。为人类和 AI 而生。

其他语言版本： 🇬🇧 English · 🇮🇩 Indonesian

项目状态

实验性，早期阶段。 该工具可以工作 —— 它能分析代码，91 个测试全部通过。但它尚未发布到 npm 或投入生产使用。在 Claude Code、Cursor、OpenCode 和其他 MCP 客户端中进行真实世界验证是下一步（尚未完成）。

CAVETAIL 是由 AI 编码代理（Claude Code）构建的，该代理在同一 CAVETAIL 框架下运行。人类负责指导工作、审查每个决策，并根据实际输出验证声明 —— 不对代理自我报告的"完成"或"已确认"盲目信任。本文档中的声明已在开发过程中通过测试运行、AST 转储和直接 CLI 调用进行了验证。

所有有意的限制都通过源文件中的 // tether: 注释记录 —— 该工具自食其狗粮。

目录

• 问题
• 什么是 CAVETAIL？
• CAVETAIL 框架
• 为什么选择 CAVETAIL？
• 功能
• 安装
• 设置指南
  • Claude Code
  • Cursor
  • Windsurf
  • OpenCode CLI
  • 其他 MCP 客户端
• 工具参考
• 测试
• 哲学
• 许可证

问题

AI 生成的代码存在质量问题。不仅仅是 bug —— 而是表面看起来正确但实际存在隐患。

| 问题 | 描述 | |------|------| | 晦涩的命名 | calc(a, b), fn(x), processData() —— AI 默认使用简短、通用的名称，不表达任何意图 | | 无用的注释 | // ini function buat ngitung 写在 function calc(a,b) 之上 —— 注释只解释了 WHAT 而非 WHY | | 隐藏的边界 | users[0] 没有说明这是单用户快捷方式。Promise.all() 没有每个项目的错误处理 | | 没有天花板标记 | 有意的简化不可见。未来的开发者（或 AI 代理）不知道哪些快捷方式是有意的 |

为什么这很重要

80% 的编码时间用于阅读代码，而非编写代码。 —— 行业共识

当 AI 生成代码的速度超过人类审查速度时，瓶颈从编写代码转向理解代码。CAVETAIL 的存在是为了通过强制清晰命名、有意义的结构和明确的边界，使生成的代码与手写代码一样可读。

没有这一点，AI 生成的代码库会积累所谓的 "AI slop" —— 通过审查但侵蚀可维护性、隐藏 bug、减慢每个未来开发者的代码。

什么是 CAVETAIL？

CAVETAIL 是一个 MCP（模型上下文协议）服务器，用于分析和转换代码以强制执行整洁代码标准。它与任何 MCP 兼容的 AI 编码工具一起运行 —— Claude Code、Cursor、Windsurf、OpenCode CLI 等。

CAVETAIL 的名称源自融合为一个原创理念的两个概念：

• CAVE（洞穴） —— 原始、零废话。无需解释即可传达意图的代码。没有不必要的注释。没有多余的包装。直击本质。
• TAIL（尾巴） —— 标记。一个可见的信号，表示"这是一个边界 —— 我知道这是一个简化，这是升级的时机。"

合在一起，CAVETAIL 意味着：直接且最简的代码，每个有意的简化都被明确标记。

与检查风格或安全性的 linter（ESLint、Semgrep）不同，CAVETAIL 检查可理解性 —— 另一个人类或 AI 代理能否在不阅读作者思维的情况下理解这段代码？

CAVETAIL 框架

该项目从头构建的五个原创概念：

| 概念 | 含义 | 示例 | |------|------|------| | Reveal（揭示） | 名称必须立即揭示意图 | calculateAge(birthDate) ✅ 不是 calc(a, b) ❌ | | Single Beat（单一节拍） | 一个函数 = 一个职责 | validateEmail() + saveUser() ✅ 不是 processUserData() ❌ | | Silent（静默） | 代码无需注释即可沟通 | calculateAge(birthDate) 上面不需要 // calculate age | | Tether（系绳） 🪢 | 带有边界和升级路径标记的有意简化 | // tether: single-org only. Expand when multi-tenant. | | Zero Fluff（零废话） | 输出直接。没有"当然，给您..."—— 直接给结果。 |

没有现有工具结合这五个维度。CAVETAIL 是第一个。

为什么选择 CAVETAIL？

不仅仅是另一个 Linter

| 维度 | ESLint / Prettier | Semgrep | DeepSource | CAVETAIL | |------|-----------------|---------|------------|-------------| | 命名质量 | ❌ | ❌ | ❌ | ✅ Reveal | | 无用注释 | ❌ | ❌ | ❌ | ✅ Silent | | 边界标记 | ❌ | ❌ | ❌ | ✅ Tether | | 单一职责检查 | ❌ | ❌ | ❌ | ✅ Single Beat | | AI 生成代码感知 | ❌ | ❌ | 有限 | ✅ 针对 AI 输出优化 | | MCP 原生 | ❌ | ✅ (技能) | ✅ | ✅ 一流 MCP 服务器 |

为 AI 时代而生

CAVETAIL 从第一天起就为 AI 辅助开发而设计：

• AI 代理也阅读代码 —— CAVETAIL 使其对人类和 LLM 都可解析
• 生成的代码没有意图 —— tether 填补了这一空白
• 瓶颈是审查，而非生成 —— CAVETAIL 在进入审查前捕捉问题
• 它是一个 MCP 服务器 —— 直接集成到开发者已经使用的工具中

功能

1. defluff — 清除噪声

移除无用的 WHAT 注释并标记晦涩命名：

// 之前（AI 生成）
// ini function buat ngitung umur
function calc(a, b) {
  return a - b
}

// defluff 之后
function calc(a, b) {
  return a - b
}
// defluff: 1 change(s)
//   removed: "// ini function buat ngitung umur"

• 移除只解释代码 WHAT 的注释
• 标记 1-2 个字符的变量名和参数（基于 AST，正确排除循环变量）
• 保留 tether 注释（它们解释 WHY）
• 支持 JavaScript、TypeScript 和基本 Python

2. tether-scan — 查找隐藏边界

检测缺少 tether 标记的有意简化：

// 之前 —— 缺少 tether
function getOwner() {
  return users[0]  // ⚠️ 硬编码的第一个项目 —— 应该标记吗？
}

// 之后 —— 带有 tether
function getOwner() {
  return users[0]
  // tether: single-org only. Expand when multi-tenant.
}

扫描 14+ 模式，包括：

• users[0] —— 硬编码索引访问
• Promise.all() —— 没有每项错误处理
• as —— 没有验证的类型断言（基于 AST，在 import alias 中零误报）
• TODO / FIXME / HACK —— 没有期限的已知债务
• any —— 跳过的类型安全
• setTimeout —— 基于定时器的等待而非事件

还能检测已有的 tether，并通过 .cavetail/state.json 跨代理会话跟踪其状态（持久化 tether 状态：reviewed/needs-attention/stale/gone）。

3. reveal-check — 命名质量检查

审计函数、变量和参数命名质量：

// 之前
function fn(a) {
  return a * 2
}

// reveal-check 输出：
// ⚠️ 2 naming issue(s) found:
//   Line 1: "fn" → "handler"
//   Line 1: parameter "a" → "value"

检测：

• 单字母名称（a、x、i）
• 通用名称（processData、doStuff、helper、manager）
• 不明确的参数（tmp、val、data）
• 通过有意的名称（getPrefixed、isValid、hasProps、camelCaseBy）

4. beat-check — 单一节拍检查

标记决策点过多的函数（if/switch/三元/for/while —— 7 种节点类型）：

// 之前 —— 5 个决策点
function validateAll(input) {
  if (!input) throw new Error('missing')
  if (input.length < 3) throw new Error('too short')
  if (input.length > 100) throw new Error('too long')
  if (!input.includes('@')) throw new Error('invalid format')
  if (input === input.toLowerCase()) throw new Error('need uppercase')
}

// beat-check 输出：
// ⚠️ 1 function(s) may violate Single Beat...
//   Line 1: "validateAll" — 5 decision points

• 基于 AST 的决策点计数（McCabe 派生，阈值 = 4）
• 尊重嵌套函数边界（内部函数单独计数）
• 严格模式 (strict: true)：报告 FAIL/PASS —— 没有 // tether: 注释解释可接受复杂度的复杂函数被视为违反

5. tether-review — 确认 Tether

在 .cavetail/state.json 中将 tether 标记为 reviewed，跨会话持久化决策：

输入：  { ids: ["src/user.ts::1::single-org only"] }
输出："✓ 1 tether(s) marked as reviewed."

安装

# 通过 npm 全局安装
npm install -g cavetail

# 或直接使用 npx（无需安装）
npx cavetail

前提条件

• Node.js 18+（已在 18、20、22 上测试）
• MCP 兼容的 AI 编码工具（Claude Code、Cursor、Windsurf、OpenCode CLI）

快速开始

# 运行 MCP 服务器（stdio 模式 —— 连接到您的 AI 工具）
npx cavetail

就这样。服务器公开五个工具（defluff、tether-scan、reveal-check、beat-check、tether-review），您的 AI 助手可以直接调用。

设置指南

Claude Code

添加到您的 Claude Code 项目配置：

.claude/settings.local.json

{
  "mcpServers": {
    "cavetail": {
      "command": "npx",
      "args": ["cavetail"]
    }
  }
}

重启 Claude Code。工具即可使用。示例提示：

"Run reveal-check on this function" "defluff this code" "tether-scan my controller file" "beat-check --strict on this module"

Cursor

在 Cursor 中，转到 设置 → MCP 服务器 并添加：

名称: cavetail
类型: stdio
命令: npx cavetail

连接后，工具会自动出现在 MCP 工具列表中。

Windsurf

添加到您的 MCP 配置：

{
  "mcpServers": {
    "cavetail": {
      "command": "npx",
      "args": ["cavetail"]
    }
  }
}

OpenCode CLI

在 OpenCode 设置中配置：

{
  "mcpServers": {
    "cavetail": {
      "command": "npx",
      "args": ["cavetail"]
    }
  }
}

其他 MCP 客户端

服务器使用 stdio 传输（标准 MCP 协议）。任何支持 MCP 服务器的工具都可以连接：

npx cavetail

客户端应根据 MCP 规范 实现 JSON-RPC 2.0 over stdio。

工具参考

defluff

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | code | string | ✅ | 要清理的源代码 | | lang | string | ❌ | 语言提示（省略时自动检测） |

返回： 带更改摘要的清理代码。

tether-scan

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | code | string | ✅ | 要扫描的源代码 | | lang | string | ❌ | 语言提示 | | filePath | string | ❌ | 用于持久化状态跟踪的文件路径 | | projectDir | string | ❌ | .cavetail/state.json 的项目根目录 |

返回： 带有缺失 tether 位置、已有 tether 状态和状态更改的扫描报告。

reveal-check

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | code | string | ✅ | 要审计的源代码 | | lang | string | ❌ | 语言提示 |

返回： 带有命名问题和重命名建议的审计报告。

beat-check

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | code | string | ✅ | 要检查的源代码 | | lang | string | ❌ | 语言提示 | | strict | boolean | ❌ | 默认 false。为 true 时，对超过阈值且缺少 tether 注释的函数报告 FAIL |

返回： 决策点过多的函数报告，或在严格模式下返回 PASS/FAIL。

tether-review

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | ids | string[] | ✅ | 要标记为 reviewed 的完整 tether id（来自 tether-scan 输出） | | notes | string | ❌ | 可选的审查注释 | | projectDir | string | ❌ | .cavetail/state.json 的项目根目录 |

返回： 标记条目的确认。

测试

# 运行所有测试
npm test

# 监视模式
npm run test-watch

# 仅编译检查
npx tsc --noEmit

测试套件（8 个套件，91 个测试）： | 套件 | 测试数 | 覆盖范围 | |------|--------|----------| | defluff.test.ts | 13 | 注释清理、基于 AST 的晦涩命名、循环变量豁免、重命名建议 | | tether-scan.test.ts | 18 | 硬编码访问、Promise.all、TODO、空输入、已有 tether 检测、函数哈希 | | reveal-check.test.ts | 13 | 单字母名称、参数、TS 注解、通用名称、as 表达式防护 | | beat-check.test.ts | 16 | 决策点计数、嵌套函数、方法定义、严格模式 PASS/FAIL | | hash.test.ts | 9 | 空白/分号/注释不变性、逻辑更改敏感性、标识符重命名敏感性 | | manager.test.ts | 11 | 合并结果、状态转换、审查条目、幂等重新合并 | | scan-cycle.test.ts | 1 | 完整端到端：Scan1→审查→代码变更→Scan2→gone→Scan3 | | server.test.ts | 10 | 编译、工具注册、InMemory 传输、通过服务器的严格模式 |

所有测试使用 Vitest，无需模拟库。

哲学

诚实 —— 没有炒作

CAVETAIL 不声称能解决所有代码质量问题。它处理 AI 辅助开发工作流中一个特定的、狭窄的空白：

• 无法检查运行时正确性
• 无法检测逻辑错误
• 无法强制执行除命名之外的架构模式
• 它的启发式方法很基础 —— 在故意简洁的代码（数学、数组回调）上可能产生误报

它擅长的是：

• ✅ 一次通过捕获最常见的 AI 命名失败
• ✅ 防止"隐藏简化"腐烂积累
• ✅ 通过转移样式关注点使代码审查更快
• ✅ 无需繁琐设置即可集成到现有 MCP 工作流中

公开构建

CAVETAIL 是使用其服务的同一范式 —— 即兴编码/工程化代理 —— 构建的。它的源代码遵循 CAVETAIL 框架（您在源代码中看到的每个 tether: 注释都由该工具适用的相同规则强制执行）。我们吃自己的狗粮。

未来方向

这是 Phase 2 版本（Phase 2 —— 基于 Tree-sitter 的 AST 解析 —— 已完成）。计划改进：

• Phase 3: 使用 LLM 上下文理解的 AI 驱动重命名建议
• Phase 4: 用于自定义规则的插件系统
• Phase 5: 用于 PR 级别扫描的 GitHub App / CI 集成

许可证

本项目采用 MIT 许可证授权 —— 请参阅 LICENSE 获取完整文本。