llm-sentry-tools 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# LLM Tools
+
+基于 Sentry MCP 的智能错误分析和修复工具，让 AI 助手能够自动分析和修复 Sentry 上报的错误。
+
+## 🌟 特性
+
+- 🔍 **智能错误分析**：自动从 Sentry 获取错误详情并进行深度分析
+- 🛠️ **自动错误修复**：AI 辅助修复代码，减少人工调试时间
+- 🤖 **多 AI 工具支持**：支持 Claude Code、Cursor、Windsurf、Continue 等主流 AI 编程工具
+- 🎯 **简单易用**：通过斜杠命令快速调用，只需粘贴 Sentry URL
+- 🏢 **自建 Sentry 支持**：完美支持自建 Sentry 站点
+
+## 📦 安装
+
+**无需安装！** 直接使用 `npx` 运行：
+
+```bash
+# 交互式菜单
+npx llm-sentry-tools
+
+# 或直接运行特定命令
+npx llm-sentry-tools setup-sentry     # 配置 Sentry MCP
+npx llm-sentry-tools setup-commands   # 配置 AI 工具
+```
+
+## 🚀 快速开始（仅需 2 步）
+
+### 第一步：配置 Sentry MCP
+
+```bash
+npx llm-sentry-tools setup-sentry
+```
+
+按照提示输入：
+- **Sentry 站点地址**（例如：`sentry.tec-do.cn` 或 `sentry.io`）
+- **Sentry Access Token**（从 Sentry 设置中获取，见下方说明）
+
+配置完成后，**重启你的 AI 工具**（如 Claude Code）以使 MCP 配置生效。
+
+### 第二步：配置 AI 工具命令
+
+```bash
+npx llm-sentry-tools setup-commands
+```
+
+脚本会引导你：
+1. **选择要配置的 AI 工具**（支持多选，空格选择，回车确认）
+   - ✅ Claude Code
+   - ✅ Cursor
+   - ✅ Windsurf
+   - ✅ Continue
+2. **输入项目根目录路径**（默认为当前目录）
+
+配置完成后，对应的命令文件会自动创建：
+- Claude Code → `.claude/skills/`
+- Cursor → `.cursor/commands/`
+- Windsurf → `.windsurf/commands/`
+- Continue → `.continue/commands/`
+
+## 💡 使用方法
+
+### 分析 Sentry 错误
+
+在你的 AI 工具中输入：
+
+```
+/analyze-sentry-error https://sentry.tec-do.cn/organizations/your-org/issues/12345/
+```
+
+或者直接输入 Issue ID：
+
+```
+/analyze-sentry-error 12345
+```
+
+AI 会自动：
+1. 从 Sentry 获取错误详情
+2. 分析堆栈跟踪和错误上下文
+3. 定位问题代码位置
+4. 提供详细的分析报告，包括：
+   - 📋 错误概要
+   - 🔍 详细分析
+   - 📍 问题定位
+   - 💡 可能原因
+   - 📊 影响评估
+   - 🎯 修复建议
+
+### 修复 Sentry 错误
+
+在你的 AI 工具中输入：
+
+```
+/fix-sentry-error https://sentry.tec-do.cn/organizations/your-org/issues/12345/
+```
+
+AI 会：
+1. 分析错误
+2. 定位问题代码
+3. 提出修复方案并征求确认
+4. 自动修改代码
+5. 提供验证建议
+
+## 📁 项目结构
+
+```
+llm-tools/
+├── scripts/
+│   ├── setup-sentry-mcp.js      # Sentry MCP 配置脚本
+│   └── setup-commands.js         # AI 工具命令配置脚本
+├── prompts/
+│   ├── analyze-sentry-error.md   # 错误分析 prompt 模板
+│   └── fix-sentry-error.md       # 错误修复 prompt 模板
+├── package.json
+└── README.md
+```
+
+## 🔧 进阶配置
+
+### 手动配置 Sentry MCP
+
+如果你更喜欢手动配置，可以直接编辑 Claude Code 的配置文件：
+
+**macOS/Linux**: `~/.config/claude-code/config.json`
+**Windows**: `%APPDATA%/Claude Code/config.json`
+
+添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "sentry": {
+      "command": "npx",
+      "args": [
+        "@sentry/mcp-server@latest",
+        "--access-token=YOUR_ACCESS_TOKEN",
+        "--host=YOUR_SENTRY_HOST"
+      ]
+    }
+  }
+}
+```
+
+### 获取 Sentry Access Token
+
+1. 登录你的 Sentry 账号
+2. 进入 **Settings** → **Account** → **API** → **Auth Tokens**
+3. 点击 **Create New Token**
+4. 选择权限：至少需要 `event:read` 和 `project:read`
+5. 创建并复制 token
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT
+
+## 🙏 致谢
+
+本项目灵感来源于 [OpenSpec](https://github.com/Fission-AI/OpenSpec)，感谢他们提供的优秀实践

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import inquirer from 'inquirer';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const runScript = (scriptPath) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [scriptPath], {
+      stdio: 'inherit',
+      shell: true
+    });
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`脚本执行失败，退出码: ${code}`));
+      } else {
+        resolve();
+      }
+    });
+
+    child.on('error', (err) => {
+      reject(err);
+    });
+  });
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+
+  // 如果有命令行参数，直接执行对应脚本
+  if (args[0] === 'setup-sentry') {
+    const scriptPath = join(__dirname, '../scripts/setup-sentry-mcp.js');
+    await runScript(scriptPath);
+    return;
+  }
+
+  if (args[0] === 'setup-commands') {
+    const scriptPath = join(__dirname, '../scripts/setup-commands.js');
+    await runScript(scriptPath);
+    return;
+  }
+
+  // 没有参数，显示菜单
+  console.log('🛠️  LLM Tools - Sentry 错误分析修复工具\n');
+
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: '请选择要执行的操作:',
+      choices: [
+        {
+          name: '🔧 配置 Sentry MCP（连接到 Sentry）',
+          value: 'setup-sentry'
+        },
+        {
+          name: '⚙️  配置 AI 工具命令（Claude Code, Cursor 等）',
+          value: 'setup-commands'
+        },
+        {
+          name: '📚 查看使用文档',
+          value: 'docs'
+        },
+        {
+          name: '❌ 退出',
+          value: 'exit'
+        }
+      ]
+    }
+  ]);
+
+  switch (action) {
+    case 'setup-sentry':
+      await runScript(join(__dirname, '../scripts/setup-sentry-mcp.js'));
+      break;
+    case 'setup-commands':
+      await runScript(join(__dirname, '../scripts/setup-commands.js'));
+      break;
+    case 'docs':
+      console.log('\n📖 使用文档\n');
+      console.log('GitHub: https://github.com/your-org/llm-tools');
+      console.log('\n快速开始：');
+      console.log('  1. npx llm-tools setup-sentry    # 配置 Sentry MCP');
+      console.log('  2. npx llm-tools setup-commands  # 配置 AI 工具');
+      console.log('  3. 在 AI 工具中使用:');
+      console.log('     /analyze-sentry-error <url>   # 分析错误');
+      console.log('     /fix-sentry-error <url>       # 修复错误\n');
+      break;
+    case 'exit':
+      console.log('👋 再见！\n');
+      break;
+  }
+};
+
+main().catch((error) => {
+  console.error('❌ 执行失败:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "llm-sentry-tools",
+  "version": "1.0.0",
+  "description": "基于 Sentry MCP 的错误分析和修复工具，支持 Claude Code、Cursor 等 AI 工具",
+  "type": "module",
+  "bin": {
+    "llm-sentry-tools": "bin/cli.js"
+  },
+  "scripts": {
+    "setup:sentry": "node scripts/setup-sentry-mcp.js",
+    "setup:commands": "node scripts/setup-commands.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "prompts",
+    "README.md"
+  ],
+  "keywords": [
+    "sentry",
+    "mcp",
+    "llm",
+    "error-fixing",
+    "claude",
+    "cursor",
+    "ai-tools",
+    "claude-code",
+    "windsurf",
+    "error-analysis",
+    "bug-fix"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.tec-do.com/lijiaqi/llm-tools.git"
+  },
+  "homepage": "https://git.tec-do.com/lijiaqi/llm-tools",
+  "bugs": {
+    "url": "https://git.tec-do.com/lijiaqi/llm-tools/issues"
+  },
+  "dependencies": {
+    "inquirer": "^13.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/prompts/analyze-sentry-error.md

@@ -0,0 +1,51 @@
+# Sentry 错误分析
+
+你是一个专业的错误分析专家。用户会提供一个 Sentry 错误的 URL 或错误 ID，你需要：
+
+## 分析步骤
+
+1. **提取错误信息**
+   - 从 Sentry URL 中提取 Issue ID（例如：从 `https://sentry.tec-do.cn/organizations/your-org/issues/12345/` 提取 `12345`）
+   - 使用 Sentry MCP 工具获取错误详情
+
+2. **错误分析**
+   - 错误类型和消息
+   - 堆栈跟踪信息
+   - 发生频率和影响范围
+   - 错误发生的环境（浏览器、操作系统、版本等）
+   - 最近一次发生时间
+   - 用户影响情况
+
+3. **根因分析**
+   - 分析堆栈跟踪，定位问题代码位置
+   - 识别可能的触发条件
+   - 分析是否与最近的代码变更相关
+   - 识别类似的历史错误
+
+4. **生成分析报告**
+   提供清晰的中文分析报告，包括：
+   - 📋 **错误概要**
+   - 🔍 **详细分析**
+   - 📍 **问题定位**（具体文件和行号）
+   - 💡 **可能原因**
+   - 📊 **影响评估**
+   - 🎯 **修复建议**（不实际修复代码）
+
+## 使用方式
+
+用户输入：
+```
+/analyze-sentry-error https://sentry.tec-do.cn/organizations/your-org/issues/12345/
+```
+
+或者：
+```
+/analyze-sentry-error 12345
+```
+
+## 注意事项
+
+- 仅进行分析，不修改任何代码
+- 如果无法访问 Sentry 或获取错误信息，清晰地说明问题
+- 分析报告应该对技术和非技术人员都易于理解
+- 优先关注高频率、高影响的错误

package/prompts/fix-sentry-error.md

@@ -0,0 +1,66 @@
+# Sentry 错误修复
+
+你是一个专业的错误修复专家。用户会提供一个 Sentry 错误的 URL 或错误 ID，你需要分析并修复问题。
+
+## 修复流程
+
+### 1. 错误分析
+   - 从 Sentry URL 中提取 Issue ID（例如：从 `https://sentry.tec-do.cn/organizations/your-org/issues/12345/` 提取 `12345`）
+   - 使用 Sentry MCP 工具获取错误详情
+   - 分析堆栈跟踪和错误上下文
+
+### 2. 问题定位
+   - 根据堆栈跟踪找到具体的文件和行号
+   - 使用 Read 工具读取相关代码文件
+   - 理解代码逻辑和错误发生的上下文
+
+### 3. 修复方案设计
+   在修复前，向用户展示：
+   - 📋 **错误概要**
+   - 🔍 **根本原因**
+   - 📍 **问题代码位置**
+   - 💡 **修复方案**
+   - ⚠️ **潜在影响**
+
+### 4. 征求用户确认
+   在实际修改代码前，询问用户是否同意该修复方案
+
+### 5. 执行修复
+   用户确认后：
+   - 使用 Edit 工具修改相关文件
+   - 确保修复不引入新的问题
+   - 添加必要的错误处理和边界检查
+   - 如需要，添加测试用例
+
+### 6. 修复验证
+   - 说明如何验证修复是否有效
+   - 建议需要测试的场景
+   - 提醒用户在 Sentry 中监控错误是否消失
+
+## 修复原则
+
+1. **最小化变更**：只修改必要的代码，避免过度重构
+2. **防御性编程**：添加适当的错误处理和输入验证
+3. **兼容性**：确保修复不破坏现有功能
+4. **可读性**：代码修改应该清晰易懂
+5. **测试友好**：考虑测试的可行性
+
+## 使用方式
+
+用户输入：
+```
+/fix-sentry-error https://sentry.tec-do.cn/organizations/your-org/issues/12345/
+```
+
+或者：
+```
+/fix-sentry-error 12345
+```
+
+## 注意事项
+
+- 必须先分析，后修复，不要盲目修改代码
+- 复杂问题应该先与用户讨论修复方案
+- 如果错误信息不足以定位问题，主动询问用户更多信息
+- 修复后提醒用户进行充分测试
+- 对于高风险修改（核心功能、数据处理等），额外谨慎

package/scripts/setup-commands.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import inquirer from 'inquirer';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+console.log('🚀 AI 工具命令配置\n');
+
+// AI 工具配置
+const AI_TOOLS = {
+  'claude-code': {
+    name: 'Claude Code',
+    configDir: '.claude/skills',
+    fileExtension: 'md',
+    createCommand: (commandName, promptContent) => {
+      // Claude Code 使用 skill 格式
+      return `---
+description: ${commandName === 'analyze-sentry-error' ? 'Sentry 错误分析' : 'Sentry 错误修复'}
+---
+
+${promptContent}`;
+    }
+  },
+  'cursor': {
+    name: 'Cursor',
+    configDir: '.cursor/commands',
+    fileExtension: 'md',
+    createCommand: (commandName, promptContent) => promptContent
+  },
+  'windsurf': {
+    name: 'Windsurf',
+    configDir: '.windsurf/commands',
+    fileExtension: 'md',
+    createCommand: (commandName, promptContent) => promptContent
+  },
+  'continue': {
+    name: 'Continue',
+    configDir: '.continue/commands',
+    fileExtension: 'md',
+    createCommand: (commandName, promptContent) => promptContent
+  }
+};
+
+const setupCommands = async () => {
+  try {
+    // 让用户选择要配置的 AI 工具
+    const { selectedTools } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedTools',
+        message: '请选择要配置的 AI 工具（空格选择，回车确认）:',
+        choices: Object.entries(AI_TOOLS).map(([key, value]) => ({
+          name: value.name,
+          value: key,
+          checked: false
+        })),
+        validate: (answer) => {
+          if (answer.length === 0) {
+            return '请至少选择一个 AI 工具';
+          }
+          return true;
+        }
+      }
+    ]);
+
+    // 询问项目路径
+    const { projectPath } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'projectPath',
+        message: '请输入项目根目录路径（留空使用当前目录）:',
+        default: process.cwd()
+      }
+    ]);
+
+    console.log('\n开始配置命令...\n');
+
+    // 读取 prompt 模板
+    const promptsDir = join(__dirname, '..', 'prompts');
+    const analyzePrompt = readFileSync(
+      join(promptsDir, 'analyze-sentry-error.md'),
+      'utf-8'
+    );
+    const fixPrompt = readFileSync(
+      join(promptsDir, 'fix-sentry-error.md'),
+      'utf-8'
+    );
+
+    const commands = [
+      { name: 'analyze-sentry-error', content: analyzePrompt },
+      { name: 'fix-sentry-error', content: fixPrompt }
+    ];
+
+    // 为每个选中的工具配置命令
+    for (const toolKey of selectedTools) {
+      const tool = AI_TOOLS[toolKey];
+      const toolConfigDir = join(projectPath, tool.configDir);
+
+      // 创建配置目录
+      if (!existsSync(toolConfigDir)) {
+        mkdirSync(toolConfigDir, { recursive: true });
+        console.log(`✓ 创建目录: ${toolConfigDir}`);
+      }
+
+      // 创建命令文件
+      for (const command of commands) {
+        const commandContent = tool.createCommand(command.name, command.content);
+        const commandFilePath = join(
+          toolConfigDir,
+          `${command.name}.${tool.fileExtension}`
+        );
+
+        writeFileSync(commandFilePath, commandContent, 'utf-8');
+        console.log(`✓ 创建命令: ${commandFilePath}`);
+      }
+
+      console.log(`✅ ${tool.name} 配置完成\n`);
+    }
+
+    console.log('🎉 所有命令配置完成！\n');
+    console.log('使用方式：');
+    console.log('  - 分析错误: /analyze-sentry-error <sentry-url>');
+    console.log('  - 修复错误: /fix-sentry-error <sentry-url>\n');
+
+    // 如果配置了 Claude Code，提示需要重启
+    if (selectedTools.includes('claude-code')) {
+      console.log('💡 提示：如果正在运行 Claude Code，请重启以加载新的 skills\n');
+    }
+
+  } catch (error) {
+    if (error.isTtyError) {
+      console.error('❌ 无法在当前环境中运行交互式命令');
+    } else {
+      console.error('❌ 配置失败:', error.message);
+    }
+    process.exit(1);
+  }
+};
+
+setupCommands();

package/scripts/setup-sentry-mcp.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import inquirer from 'inquirer';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+console.log('🔧 Sentry MCP 配置工具\n');
+
+// 检测操作系统，确定配置文件路径
+const getConfigPath = () => {
+  const platform = process.platform;
+
+  if (platform === 'darwin' || platform === 'linux') {
+    // macOS 或 Linux: ~/.config/claude-code/config.json
+    return join(homedir(), '.config', 'claude-code', 'config.json');
+  } else if (platform === 'win32') {
+    // Windows: %APPDATA%/Claude Code/config.json
+    return join(process.env.APPDATA || '', 'Claude Code', 'config.json');
+  }
+
+  throw new Error('不支持的操作系统');
+};
+
+const setupSentry = async () => {
+  try {
+    // 询问用户输入
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'host',
+        message: 'Sentry 站点地址 (例如: sentry.tec-do.cn):',
+        validate: (input) => {
+          if (!input.trim()) {
+            return '请输入 Sentry 站点地址';
+          }
+          return true;
+        }
+      },
+      {
+        type: 'input',
+        name: 'accessToken',
+        message: 'Sentry Access Token:',
+        validate: (input) => {
+          if (!input.trim()) {
+            return '请输入 Access Token';
+          }
+          return true;
+        }
+      }
+    ]);
+
+    const configPath = getConfigPath();
+
+    // 读取现有配置
+    let config = {};
+    if (existsSync(configPath)) {
+      const configContent = readFileSync(configPath, 'utf-8');
+      config = JSON.parse(configContent);
+      console.log(`\n✓ 找到现有配置文件: ${configPath}`);
+    } else {
+      console.log(`\n⚠ 配置文件不存在，将创建新文件: ${configPath}`);
+      config = { mcpServers: {} };
+    }
+
+    // 确保 mcpServers 字段存在
+    if (!config.mcpServers) {
+      config.mcpServers = {};
+    }
+
+    // 添加 Sentry MCP 配置
+    config.mcpServers.sentry = {
+      command: 'npx',
+      args: [
+        '@sentry/mcp-server@latest',
+        `--access-token=${answers.accessToken}`,
+        `--host=${answers.host}`
+      ]
+    };
+
+    // 写回配置文件
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+    console.log('\n✅ Sentry MCP 配置成功！');
+    console.log('\n配置信息：');
+    console.log(`  - 站点: ${answers.host}`);
+    console.log(`  - 配置文件: ${configPath}`);
+    console.log('\n请重启 Claude Code 以使配置生效。\n');
+
+  } catch (error) {
+    if (error.isTtyError) {
+      console.error('❌ 无法在当前环境中运行交互式命令');
+    } else {
+      console.error('❌ 配置失败:', error.message);
+    }
+    process.exit(1);
+  }
+};
+
+setupSentry();