AI导哈

Salesforce日志AI分析器

一款本地优先、AI优化的Salesforce调试日志分析工具，通过MCP提供智能问题检测、异步作业关联和隐私保护分析。

  • by SalesforceDiariesBySanket
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 SalesforceDiariesBySanket/salesforce-log-ai-analyzer-mcp

使用说明

Salesforce日志AI分析器-MCP

AI First Salesforce调试日志分析器-通过MCP对Salesforce进行本地优先、AI优化的调试日志分析

概述

SF Debug Analyzer是一个全面的工具，用于解析和分析Salesforce调试日志，重点是AI代理集成。它通过模型上下文协议（MCP）提供智能问题检测、异步作业关联和隐私保护分析。

特性

🔍 智能日志解析

  • 高保真标记器 -逐行准确分析所有Salesforce调试日志事件类型
  • AST构建器 -创建具有适当父子关系的分层调用树
  • 截断处理 -检测日志截断并从中恢复，提供影响分析
  • 流媒体支持 -大型日志文件的内存高效解析

🚨 问题检测

  • SOQL在循环中 -检测迭代块内具有精确行位置的查询
  • N+1查询模式 -识别重复的查询，表明缺少扩展
  • 调速器极限分析 -跟踪CPU时间、堆、SOQL限制以及阈值警告
  • 非选择性查询 -标记没有正确索引的查询
  • 递归触发器 -检测触发再入模式
  • CPU热点 -识别消耗过多CPU时间的方法
  • 异常跟踪 -使用全堆栈跟踪捕获未处理的异常

🏢 管理包支持

  • 命名空间检测 -在日志中标识托管包命名空间
  • 归因引擎 -特定包或组织代码的属性问题
  • 可见性分类 -确定ISV日志中可见与隐藏的内容
  • AI指导 -根据包所有权提供可操作的建议

🔗 异步作业关联

  • 工作提取 -标识可排队、批处理、未来和可调度的引用
  • 交叉日志跟踪 -将父日志与异步子执行相关联
  • 信心评分 -基于时间和背景的利率相关性置信度
  • 统一视图 -将异步链表示为有凝聚力的执行流

🔒 隐私和补救

  • PII检测 -识别电子邮件、电话号码、SSN、信用卡
  • 凭证屏蔽 -Redacts API密钥、令牌、密码
  • 自定义图案 -配置特定于组织的敏感数据模式
  • 审计跟踪 -在不暴露原始值的情况下跟踪已编辑的内容

🧠 存储器系统

  • 解决方案存储 -保存成功的修复以供将来参考
  • 情景记忆 -按上下文回忆过去的调试会话
  • 语义搜索 -使用相似性匹配查找相关的过去解决方案
  • SQLite持久化 -本地优先存储，不依赖云

🤖 MCP服务器集成

通过模型上下文协议为GitHub Copilot、Claude等AI助手构建：

工具 说明
sf_debug_setup 通过SFDX CLI连接到Salesforce组织
sf_debug_list_logs 列出可用的调试日志
sf_debug_get_log 获取特定的调试日志
sf_debug_parse_content 直接解析原始日志内容
sf_debug_parse_file 从文件路径解析日志（建议用于大于1MB的日志）
sf_debug_summary 获取AI优化摘要（<500个令牌）
sf_debug_issues 检测严重性问题并提出解决建议
sf_debug_query 使用灵活的筛选器查询事件
sf_debug_problem_context 针对特定问题获取AI优化的上下文
sf_debug_async_jobs 提取异步作业引用
sf_debug_correlate 将父日志与异步子日志相关联
sf_debug_store_solution 存储学习工作解决方案
sf_debug_memory_stats 获取内存系统统计信息
sf_debug_end_session 以结果反馈结束会议

📟 CLI接口

# Analyze a debug log with full output
sf-debug analyze /path/to/debug.log

# Output as JSON
sf-debug analyze /path/to/debug.log --format json

# Analyze with PII redaction
sf-debug analyze /path/to/debug.log --redact

# List issues with severity filtering
sf-debug issues /path/to/debug.log --min-severity HIGH

# Get a token-efficient summary (<500 tokens)
sf-debug summary /path/to/debug.log

# Query specific events with filtering
sf-debug query /path/to/debug.log --type SOQL_EXECUTE_BEGIN

# Query with pagination
sf-debug query /path/to/debug.log --type SOQL --limit 10

先决条件

安装前，请确保：

  • Node.js >= 18.0.0
  • npm 或 纱线
  • Git （用于克隆存储库）
  • Salesforce命令行界面（SFDX） -可选，但建议用于身份验证
    npm install -g @salesforce/cli

安装

从GitHub克隆

# Clone the repository
git clone https://github.com/SalesforceDiariesBySanket/salesforce-log-ai-analyzer-mcp.git
cd salesforce-log-ai-analyzer-mcp

# Install dependencies
npm install

# Build the project
npm run build

地方发展链接

要在开发过程中全局使用CLI命令，请执行以下操作：

# Link the package globally
npm link

# Now you can use the CLI anywhere
sf-debug --help
sf-debug-mcp --help

快速开始

作为MCP服务器（人工智能助理）

添加到您的VS Code MCP设置中：

  • 视窗: %APPDATA%\Code\User\mcp.json
  • macOS: ~/Library/Application Support/Code/User/mcp.json
  • Linux: ~/.config/Code/User/mcp.json

Windows示例：

{
  "servers": {
    "sf-debug-analyzer": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\salesforce-log-ai-analyzer-mcp\\dist\\mcp\\index.js"]
    }
  }
}

macOS/Linux示例：

{
  "servers": {
    "sf-debug-analyzer": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/salesforce-log-ai-analyzer-mcp/dist/mcp/index.js"]
    }
  }
}

重要提示：

  • 使用 绝对路径 （不是相对路径，如 ./dist/mcp/index.js)
  • 在Windows上，使用双反斜杠(\\)或正斜杠(/)
  • 跑 npm run build 首先创建 dist 文件夹
  • 更改后重新启动VS Code或重新加载MCP连接

适用于克劳德桌面(claude_desktop_config.json):

窗户：

{
  "mcpServers": {
    "sf-debug": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\salesforce-log-ai-analyzer-mcp\\dist\\mcp\\index.js"]
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "sf-debug": {
      "command": "node",
      "args": ["/absolute/path/to/salesforce-log-ai-analyzer-mcp/dist/mcp/index.js"]
    }
  }
}

程序化使用

import { parseLog, analyzeLog, generateSummary } from './dist/index.js';

// Parse a log file
const result = parseLog(logContent);
if (result.success) {
  console.log(`Parsed ${result.data.events.length} events`);

  // Analyze for issues
  const analysis = analyzeLog(result.data);
  analysis.issues.forEach(issue => {
    console.log(`[${issue.severity}] ${issue.title}`);
  });

  // Get AI-optimized summary (<500 tokens)
  const summary = generateSummary(result.data, analysis);
  console.log(`Health: ${summary.health}/100`);
}

Salesforce身份验证

该工具支持连接到Salesforce组织的多种身份验证方法：

方法 最适合 要求
SFDX导入 大多数用户 Salesforce CLI安装了缓存身份验证
OAuth PKCE 本地开发 浏览器访问，本地主机可用
设备代码 远程/无头（SSH、代码空间） 组织允许设备代码流
手动令牌 回退 来自开发人员控制台的会话ID

推荐：使用SFDX CLI

# Authenticate to your org using Salesforce CLI first
sf org login web --alias myorg

# The analyzer will automatically detect and use this auth

发展

# Install dependencies
npm install

# Build
npm run build

# Build in watch mode (for development)
npm run build:watch

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific module tests
npm run test:parser
npm run test:analyzer
npm run test:mcp

# Lint
npm run lint

# Lint and fix
npm run lint:fix

# Format
npm run format

安装后验证

安装后，验证一切正常：

# 1. Check the build completed successfully
npm run build

# 2. Verify CLI is working
node dist/cli/index.js --help

# 3. Run tests
npm test

# 4. Test with a sample log (if available)
node dist/cli/index.js analyze __fixtures__/logs/simple/success.log

建筑

此工具的设计 AI优先 -这意味着AI代理（Claude、GitHub Copilot等）是主要消费者，开发人员通过CLI作为次要用户。

设计原则

  • 结构化输出 → JSON/JSONL，不是散文（AI生成解释）
  • 代币高效 → 先总结，按需提供详细信息
  • 信心得分 → 概率性，而非确定性（使AI能够传达不确定性）
  • 本地优先 → 无云依赖，SQLite持久化
  • 内存已启用 → 从过去的调试会话中学习
  • 隐私意识 → 自动编辑PII，选择持久化

关键能力

能力 描述
流解析器 20MB+日志的内存高效解析
截断处理 当原木被切断时，会出现优雅的退化
调试级别意识 适应基于日志详细程度的分析
多身份验证支持 PKCE、设备代码、SFDX导入、手动令牌
跟踪标志管理 使用最佳调试级别自动创建

项目结构

src/
├── parser/       # Log tokenization and AST building
├── analyzer/     # Issue detection and categorization  
├── async/        # Async job correlation (Batch, Queueable, Future)
├── capture/      # Salesforce authentication and log fetching
├── cli/          # Command-line interface
├── managed/      # Managed package attribution
├── mcp/          # MCP server for AI assistants
├── memory/       # Solution memory with SQLite persistence
├── output/       # Formatters and problem context
├── privacy/      # Data redaction (PII, credentials)
└── types/        # TypeScript type definitions

调试级别预设

该工具包括11个针对不同调试场景的优化调试级别预设：

预设 用例
minimal 低开销，生产监控
soql_analysis SOQL限制问题，查询优化
governor_limits 跟踪所有调速器限制消耗
triggers 触发器递归、DML问题
cpu_hotspots CPU超时，方法分析
exceptions 使用堆栈跟踪进行异常跟踪
callouts 外部HTTP调用调试
visualforce VF页面性能
workflow Process Builder，流程调试
full_diagnostic 最大细节（高开销）
ai_optimized 平衡AI分析

致谢

该项目从社区中的几个优秀的Salesforce调试工具和库中汲取灵感：

日志分析与解析

身份验证和日志捕获

可视化和模式

  • SFDC日志 -Git图形风格可视化概念、触发模式检测方法

机器学习和异常检测（未来路线图）

  • 销售人员/logai -ML异常检测概念（隔离林、LSTM）、漏日志解析器、OpenTetry兼容模式

Salesforce官方工具

故障排除

常见问题

问题 解决方案
better-sqlite3 生成失败 请确保已安装生成工具： npm install -g windows-build-tools （Windows）或 xcode-select --install （macOS）
远程环境中的身份验证失败 使用设备代码流或SFDX导入而不是PKCE
未捕获日志 验证是否在正确的用户上设置了跟踪标志（包括异步作业的“自动处理”）
MCP服务器未连接 1。验证 dist 文件夹存在（运行 npm run build)
2.在mcp.json中使用绝对路径，而不是相对路径
3.在Windows上，使用双反斜杠： C:\\Users\\...\\dist\\mcp\\index.js
4.配置更改后重新启动VS代码
找不到模块错误 检查mcp.json中的路径是否与您的实际项目位置匹配，并包括 \\dist\\mcp\\index.js 最后

异步作业日志记录注意事项

调试异步作业（批处理、排队、未来）时，确保在 两者:

  1. 触发动作的用户
  2. “自动流程”用户（用于系统上下文异步执行）

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关 MCP