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