Onetimesecret MCP

🚀 Amp CLI 橋接器 - 基於文件的通信系統

Amp CLI 橋接器是一個基於文件的消息隊列系統，允許 Claude Code 在不消耗自身積分的情況下，利用 Amp CLI 的功能。

🚀 快速開始

1. 啟動監視器

在一個獨立的終端中運行以下命令：

./scripts/amp/start-amp-watcher.sh

這將啟動一個後臺監視器進程，用於監視 prompts/pending/ 目錄中的新文件。

2. 在 Claude Code 中使用

在你的 Claude Code 會話中輸入：

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

代理將執行以下操作：

1. 在 prompts/pending/ 目錄中創建一個提示文件。
2. 等待監視器處理該文件。
3. 從 responses/ready/ 目錄中讀取響應。
4. 向你展示結果。

3. 停止監視器

當你完成操作後，運行以下命令：

./scripts/amp/stop-amp-watcher.sh

✨ 主要特性

• 零 Claude Code 積分消耗：所有 Amp API 調用均來自獨立的認證會話。
• 異步處理：Claude Code 無需等待響應，不會被阻塞。
• 容錯性：基於文件的隊列在崩潰和重啟後仍能正常工作。
• 審計跟蹤：所有提示和響應都會被保存，便於調試和審查。
• 可複用性：可以重新執行提示或查看過去的響應。

📦 安裝指南

如果 .claude/amp 目錄不存在或不完整，請創建它：

# 從項目根目錄執行
mkdir -p .claude/amp/prompts/pending
mkdir -p .claude/amp/responses/{ready,consumed}

注意：該目錄已被添加到 .gitignore 中（屬於用戶特定的工作空間），會根據需要在本地創建。

💻 使用示例

基礎用法

在 Claude Code 中發起研究請求：

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

高級用法

自定義每個請求的超時時間：

{
  "prompt": "Complex analysis task",
  "options": {
    "timeout": 600000  // 10 minutes
  }
}

📚 詳細文檔

架構

Claude Code (@agent-amp-bridge)
    ↓
    writes prompt to → prompts/pending/{uuid}.json
                              ↓
                    amp-watcher.js (separate process)
                              ↓
                    executes → amp -x "prompt"
                              ↓
                    writes → responses/ready/{uuid}.json
                              ↓
    Claude Code reads ← response

目錄結構

.claude/amp/
├── prompts/
│   ├── pending/        # 新提示的隊列（由 amp-watcher.js 監視）
│   └── processed/      # 已完成提示的存檔
├── responses/
│   ├── ready/          # Amp 的響應（供 Claude Code 讀取）
│   └── consumed/       # 已使用響應的存檔
├── amp-watcher.js      # 處理提示的 Node.js 文件監視器
├── config.json         # 配置文件
├── amp-watcher.log     # 監視器日誌
└── README.md           # 本文件

配置

編輯 .claude/amp/config.json：

{
  "pollInterval": 1000,      // 每 1 秒檢查一次新提示
  "timeout": 300000,          // 每個提示的超時時間為 5 分鐘
  "debug": false,             // 啟用調試日誌
  "ampCommand": "amp"         // Amp CLI 命令路徑
}

消息格式

提示文件

位置：prompts/pending/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:00:00.000Z",
  "prompt": "Your research question or task here",
  "context": {
    "project": "mcp-memory-service",
    "cwd": "/path/to/project",
    "tags": ["research", "typescript"]
  },
  "options": {
    "timeout": 300000,
    "format": "markdown"
  }
}

響應文件

位置：responses/ready/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:05:00.000Z",
  "success": true,
  "output": "Amp CLI response content here...",
  "error": null,
  "duration": 300000,
  "originalPrompt": { /* echo of prompt for reference */ }
}

輔助腳本

位於 scripts/amp/ 目錄下：

• start-amp-watcher.sh - 後臺啟動監視器。
• stop-amp-watcher.sh - 優雅地停止監視器。
• test-amp-bridge.sh - 集成測試（創建測試提示，等待響應）。

故障排除

監視器未處理提示

檢查是否正在運行：

cat .claude/amp/amp-watcher.pid
ps -p $(cat .claude/amp/amp-watcher.pid)

檢查日誌：

tail -50 .claude/amp/amp-watcher.log

重啟監視器：

./scripts/amp/stop-amp-watcher.sh
./scripts/amp/start-amp-watcher.sh

Amp CLI 錯誤

直接測試 Amp：

amp -x "What is 2+2?"

常見錯誤：

• Insufficient credit balance - 免費額度已用完。
  • 解決方案：等待積分刷新或在 https://ampcode.com/settings 升級。
• Command not found: amp - Amp CLI 未安裝。
  • 解決方案：npm install -g @sourcegraph/amp

集成測試

./scripts/amp/test-amp-bridge.sh

該命令將創建一個簡單的測試提示（"What is 2+2?"），等待響應並驗證是否成功。

使用場景

✅ 網絡研究："Research latest React 18 features and concurrent rendering" ✅ 代碼分析："Analyze the storage backend architecture in src/storage/" ✅ 文檔生成："Generate comprehensive API docs for MCP tools" ✅ 代碼生成："Create TypeScript type definitions for the API" ✅ 最佳實踐："Find OAuth 2.1 security recommendations and implementation patterns"

侷限性

• ⏱️ 延遲：文件輪詢每次請求會增加約 1 秒的開銷。
• 💰 Amp 積分：仍然會消耗 Amp API 積分（受免費額度限制）。
• 🔄 手動啟動：監視器必須在獨立的終端中手動啟動。
• 📝 適用於研究：針對異步研究任務進行了優化，不適合即時交互。

🔧 技術細節

監視器實現

amp-watcher.js 腳本的工作流程如下：

1. 每 1 秒（可配置）輪詢 prompts/pending/ 目錄。
2. 對於找到的每個 .json 文件：
   • 讀取提示。
   • 執行 amp -x "{prompt}" 命令。
   • 捕獲標準輸出和標準錯誤。
   • 將響應寫入 responses/ready/ 目錄。
   • 將提示移動到 prompts/processed/ 目錄。
3. 優雅地處理錯誤（寫入錯誤響應）。
4. 支持優雅關閉（SIGTERM/SIGINT）。

代理實現

@agent-amp-bridge Claude Code 代理的工作流程如下：

1. 生成用於跟蹤請求的 UUID。
2. 將提示 JSON 寫入 prompts/pending/ 目錄。
3. 輪詢 responses/ready/ 目錄，查找匹配的 UUID。
4. 當響應可用時，讀取並解析響應。
5. 將響應移動到 responses/consumed/ 目錄。
6. 向用戶展示格式化的輸出。

文件清理

存檔文件用於調試：

• prompts/processed/ - 已完成的提示。
• responses/consumed/ - 已使用的響應。 手動清理（可選）：

# 刪除 7 天前的存檔
find .claude/amp/prompts/processed -name "*.json" -mtime +7 -delete
find .claude/amp/responses/consumed -name "*.json" -mtime +7 -delete

👨‍💻 開發者指南

擴展系統

自定義每個請求的超時時間

{
  "prompt": "Complex analysis task",
  "options": {
    "timeout": 600000  // 10 minutes
  }
}

調試模式

node .claude/amp/amp-watcher.js --debug

自定義輪詢間隔

node .claude/amp/amp-watcher.js --interval 500  // 500ms

測試更改

1. 對 amp-watcher.js 或代理進行更改。
2. 重啟監視器：./scripts/amp/stop-amp-watcher.sh && ./scripts/amp/start-amp-watcher.sh
3. 運行集成測試：./scripts/amp/test-amp-bridge.sh

📄 許可證

未提供相關許可證信息。

📞 支持

• 文檔：請參閱 CLAUDE.md 中的 "Amp CLI Bridge" 部分。
• 問題反饋：請在 https://github.com/doobidoo/mcp-memory-service/issues 提交問題。
• Amp CLI 文檔：https://ampcode.com/manual