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