Devtap

🚀 devtap

devtap 能够自动将构建/开发过程的输出信息桥接到 AI 编码会话中。它可以捕获构建和开发命令的标准输出和标准错误输出，并通过 MCP（模型上下文协议）将这些信息提供给 AI 编码工具会话。此外，它还能将相同的输出信息分发给多个编码代理，每个代理独立处理自己的副本，确保并行会话不会相互干扰。

🚀 快速开始

📦 安装

go install github.com/killme2008/devtap/cmd/devtap@latest

或者通过 Homebrew 进行安装：

brew install killme2008/tap/devtap

也可以从 GitHub Releases 下载。

⚙️ 配置

cd /path/to/your-project
devtap install --adapter claude-code

此命令会配置 MCP 服务器，并将 devtap 指令注入到项目的指令文件（例如 CLAUDE.md）中。所有可用的适配器请参考 支持的工具。

🛠️ 技能（可选）

devtap 自带一个内置 技能，当 MCP 不可用时，它可以作为 CLI 的备用方案。安装该技能后，代理可以按需获取构建输出：

# Claude Code
mkdir -p ~/.claude/skills && cp -r skills/devtap-get-build-errors ~/.claude/skills/

# Codex CLI
mkdir -p ~/.codex/skills && cp -r skills/devtap-get-build-errors ~/.codex/skills/

或者直接从仓库获取，无需克隆：

DEST=~/.claude/skills/devtap-get-build-errors
mkdir -p "$DEST" && cd "$DEST"
for f in SKILL.md scripts/get_build_errors.sh; do
  mkdir -p "$(dirname "$f")"
  curl -sL "https://raw.githubusercontent.com/killme2008/devtap/main/skills/devtap-get-build-errors/$f" -o "$f"
done
chmod +x scripts/get_build_errors.sh

💻 使用示例

基础用法

终端 A — 捕获构建输出：

devtap -- cargo check
devtap -- go build ./...
devtap --filter-regex "error|warning" -- npm run build

# 长时间运行的开发服务器（默认每 2 秒刷新一次输出）
devtap -- npm run dev

终端 B — 像往常一样使用你的 AI 编码工具。它将通过 MCP 自动调用 get_build_errors 来获取捕获的构建错误。

如果你想在不使用 MCP 的情况下进行验证，运行：

devtap drain

典型输出如下：

[devtap: cargo check] Build failed (exit code 101):
...

提示：由于 devtap 可以捕获任何命令的标准输出，你可以向编码代理发送任意消息：

devtap -- echo "Please refactor the auth module to use JWT"

这使得 devtap 成为一个通用的人→代理消息通道，无需复制粘贴。

✨ 主要特性

解决的问题

在氛围编码工作流程中，你通常在一个终端运行 AI 编码工具，在另一个终端运行构建命令。当出现错误时，你需要手动将日志复制粘贴到编码会话中。devtap 则可以自动完成这个反馈循环。以下三种常见情况会让手动操作变得尤为痛苦：

1. 多个本地开发进程（前端 + 后端 + 工作进程）需要你密切关注并快速修复问题。
2. 多个编码代理在同一个项目上工作，你希望它们并行分析相同的失败情况并比较结果。
3. 在远程机器（CI、开发环境）上进行构建/测试运行，你需要将其输出反馈给本地的编码代理。

工作原理

本地模式（默认，基于文件）

Terminal A (Claude Code)          Terminal B (build/dev)
┌──────────────────┐             ┌────────────────────────────┐
│  MCP tool call:  │   stdio     │  devtap -- cargo check     │
│  get_build_errors├─────────────┤                            │
│                  │  JSON-RPC   │  captures stdout/stderr,   │
│  receives errors,│             │  fans out to all adapters: │
│  fixes code      │             │  ~/.devtap/<s>/claude-code/│
└──────────────────┘             │  ~/.devtap/<s>/codex/      │
                                 └────────────────────────────┘

跨机器模式（使用 GreptimeDB）

Your laptop                       CI / remote build server
┌──────────────────┐             ┌────────────────────────────┐
│  Claude Code     │             │  devtap -- make            │
│  get_build_errors│             │                            │
│                  │             │  captures stdout/stderr    │
│  receives errors,│             └─────────────┬──────────────┘
│  fixes code      │                           │ write
└────────┬─────────┘                           ▼
         │ drain              ┌────────────────────────────┐
         └───────────────────►│        GreptimeDB          │
                              │  (shared session store)    │
                              └────────────────────────────┘

1. devtap install 为你的 AI 工具配置 MCP 服务器（跨机器设置时需传递 --session 和 --store）。
2. devtap -- <cmd> 运行你的命令，捕获标准输出和标准错误输出，并将其分发给所有已注册的适配器。
3. 每个 AI 工具通过 get_build_errors 独立获取自己的副本。
4. AI 工具检测到错误并进行修复。

当 mcp-serve/drain 以显式的 --session 或 --store 启动时，devtap 可以合并来自两个源的输出：

• local：从默认后端自动检测到的项目会话。
• configured：显式的 --session/--store 目标。

如果两者解析到相同的后端和会话，devtap 将使用单一源。否则，它将从两个源获取数据，去重相同的消息，并在标签前添加源信息（例如 myhost/local |）。

支持的工具

任何支持 MCP 的工具都可以直接使用 devtap mcp-serve。

自动循环模式（Claude Code）

Claude Code 支持一个停止钩子，当存在错误时可以阻止 Claude 停止：

devtap install --adapter claude-code --auto-loop --max-retries 5

此命令会进行以下配置：

• 配置 MCP 服务器以按需查询错误。
• 设置停止钩子，当构建错误未解决时阻止 Claude 完成。
• 设置安全限制，最多重试 5 次后允许停止。

存储后端

文件（默认）

零依赖的 JSONL 文件存储在 ~/.devtap/<session>/<adapter>/pending.jsonl。每个适配器都有自己的队列，以便独立消费。使用原子重命名确保并发安全。

GreptimeDB（可选）

用于持久化历史记录、基于 SQL 的过滤和更丰富的统计信息。使用远程 GreptimeDB 实例时，构建和 AI 工具甚至可以不在同一台机器上 — 详情请参考 跨机器构建。

更多安装选项请参考 GreptimeDB 安装指南。

使用 Docker 快速开始：

docker run -d \
  --name greptime-devtap \
  --restart unless-stopped \
  -p 127.0.0.1:4000-4002:4000-4002 \
  -v ~/.devtap/greptimedb_data:/greptimedb_data \
  greptime/greptimedb:latest standalone start \
  --http-addr 0.0.0.0:4000 \
  --rpc-bind-addr 0.0.0.0:4001 \
  --mysql-addr 0.0.0.0:4002

容器在后台运行（-d），并在 Docker 启动时自动启动（--restart unless-stopped）。-v 标志将 ~/.devtap/greptimedb_data/ 挂载用于持久化存储。

# 在 ~/.devtap/config.toml 中进行配置（这将成为默认存储）
cat > ~/.devtap/config.toml <<EOF
[store]
backend = "greptimedb"

[store.greptimedb]
endpoint = "127.0.0.1:4001"
mysql_endpoint = "127.0.0.1:4002"
database = "public"
EOF

# 现在 devtap 默认使用 GreptimeDB
devtap -- cargo check

# 基于 SQL 的过滤
devtap drain --filter-sql "content LIKE '%error%'"

# 查询构建错误历史记录
devtap history --since 24h

# 或者为每个命令覆盖配置（例如，回退到文件存储）
devtap --store file -- cargo check

# 在 GreptimeDB 仪表板中查看日志
open http://127.0.0.1:4000/dashboard/#/dashboard/logs-query

通过环境变量设置凭证：

export DEVTAP_GREPTIMEDB_USERNAME=...
export DEVTAP_GREPTIMEDB_PASSWORD=...

高级用法

多个实例

使用 --tag 为同一会话运行并行监视器：

devtap --tag cargo-check -- cargo watch -x check
devtap --tag cargo-test --debounce 5s -- cargo watch -x test

多适配器分发

当安装了多个 AI 工具时，构建输出将自动分发给所有工具。每个工具独立消费自己的副本。

跨机器构建

使用共享的 GreptimeDB 实例，构建和 AI 工具可以在不同的机器上运行。使用 --session 为双方指定相同的逻辑会话名称：

# 机器 B（你的笔记本电脑） — 安装一次，将 --session 和 --store 写入 MCP 配置
devtap install --adapter claude-code --session myproject --store greptimedb

# 机器 A（CI / 远程构建服务器）
devtap --store greptimedb --session myproject -- make

devtap install 将 --session 和 --store 标志写入 MCP 配置文件（例如 .mcp.json），因此 AI 工具的 MCP 服务器会自动连接到正确的 GreptimeDB 实例和会话。

多个构建机器可以同时写入同一个会话 — 每个条目都会标记其来源，AI 工具会获取所有条目。

本地 + 远程合并获取

同时查看本地循环和远程共享会话的输出：

# 笔记本电脑：本地输出（默认源）
devtap -- cargo check

# 远程机器：共享会话输出（配置源）
devtap --store greptimedb --session myproject -- make

# 笔记本电脑：使用显式远程会话安装 MCP
devtap install --adapter claude-code --store greptimedb --session myproject

# 可选的手动检查（不使用 MCP 客户端）
devtap drain --store greptimedb --session myproject

devtap drain 会显示一个合并的标题（Draining from N sources），当部分失败发生时会发出源不可达的警告，但仍会返回可访问源的可用输出。

典型的合并标题如下：

[devtap] Draining from 2 sources (2 reachable)

会话自动检测

当使用 --session auto（默认）时，devtap 会按以下方式解析项目目录：

1. Git 根目录（最近的包含 .git 的父目录）。
2. 项目标记文件（最近的包含以下文件之一的父目录：go.mod、package.json、pyproject.toml、Cargo.toml、pom.xml、build.gradle、build.gradle.kts、composer.json、Gemfile、setup.py）。
3. 当前工作目录。

命令链

devtap 会捕获 -- 后面的单个命令。如果你需要使用 shell 操作符（如 &&），可以将命令包装在 shell 中：

devtap -- sh -c "npm install && npm run dev"

或者分别运行它们：

devtap -- npm install
devtap -- npm run dev

CLI参考

devtap [flags] -- <command> [args...]

Flags:
  -a, --adapter <name>       AI 工具适配器（默认 "claude-code"）
  -s, --session <id>         目标会话（"auto"、"pick" 或显式名称）
      --store <backend>      存储后端（"file" 或 "greptimedb"）
      --filter-regex <pat>   输出行的正则表达式过滤器
      --filter-invert        反转过滤器（排除匹配的行）
      --max-lines <n>        每次获取的最大行数（默认 10000）
      --tag <label>          日志标签前缀（默认：命令名称）
      --debounce <dur>       捕获输出的刷新间隔（默认 "2s"，0 表示禁用）

Subcommands:
  install     配置 AI 工具集成（--session 和 --store 会传递给 MCP 配置）
  mcp-serve   启动 MCP 标准输入输出服务器
  drain       以纯文本形式读取待处理消息
                -q, --quiet      无来源/标签标题的原始输出
  status      显示待处理消息数量
                -q, --quiet      紧凑输出（仅显示待处理数量）
  history     查询构建错误历史记录（仅适用于 GreptimeDB）
                --since <dur>    时间范围（默认 "24h"）
                --tag <label>    按标签过滤
                --limit <n>      最大条目数（默认 20）
  gc          删除过期的会话数据（默认 TTL：7 天）

超过 --max-lines 的行将被智能截断：保留头部和尾部，并显示省略通知。连续的重复行将被合并。

devtap mcp-serve 和 devtap drain 可以如上所述聚合多个源（本地 + 配置）。devtap drain --filter-sql 是单源模式，需要 --store greptimedb。

🛠️ 故障排除

• 没有输出但你期望有日志：先运行 devtap status，然后运行 devtap drain --max-lines 200。
• 使用了意外的会话：运行一次 --session pick 以确认目标会话。
• 多源获取显示警告：仍会返回可访问源的输出；警告表示某个源不可用。
• MCP 工具未被调用：在项目根目录重新运行 devtap install --adapter <adapter>，并重启 AI 工具会话。

🔐 安全与隐私

• 所有数据都保留在本地。构建输出存储在你的机器上的 ~/.devtap/（文件后端）或自托管的 GreptimeDB 实例中。不会将任何数据发送到外部服务器。
• MCP 通信是本地标准输入输出。MCP 服务器作为 AI 工具的子进程运行，通过标准输入/输出的 JSON-RPC 进行通信。不会打开网络套接字。
• 无遥测。devtap 不收集任何使用数据、分析信息或崩溃报告。
• --filter-sql 不是安全边界。它包含一个尽力而为的关键字黑名单，但设计目的是为了方便，而不是处理恶意输入。用户已经拥有完整的本地和数据库访问权限。
• 清理：运行 devtap gc 删除过期的会话数据，或者完全删除 ~/.devtap/ 以删除所有存储的数据。

📄 许可证

MIT