mcpField
P
platform-apex-logs-debug

platform-apex-logs-debug

github.com/forcedotcom开发1.1k6.9k 次安装1 天前更新
代码仓库

关于 platform-apex-logs-debug

用于从 Apex 调试日志诊断 Salesforce 运行时问题，包括异常、治理限制和性能瓶颈。它依据日志证据分析根因，并给出验证建议。

主要功能

  1. 01解读异常与堆栈跟踪
  2. 02检查治理限制用量
  3. 03查找重复 SOQL 和 DML
  4. 04调查 CPU 与堆压力
  5. 05依据证据建议修复

适用场景

  1. 01诊断失败的 Salesforce 事务
  2. 02调查循环中的 SOQL 或 DML
  3. 03分析 CPU 或堆限制压力
  4. 04追踪空指针的根因

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-apex-logs-debug

安装后在 Claude Code 中输入/platform-apex-logs-debug确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
assets/
benchmarking-template.cls
cpu-heap-optimization.cls
dml-in-loop-fix.cls
null-pointer-fix.cls
soql-in-loop-fix.cls
references/
analysis-playbook.md
benchmarking-guide.md
cli-commands.md
common-issues.md
debug-log-reference.md
log-analysis-tools.md
scoring-rubric.md

详细介绍

platform-apex-logs-debug：Salesforce 调试日志分析与故障排查

当用户需要通过调试日志进行根因分析时，使用此技能：诊断 Governor 限制、解读堆栈跟踪、调查慢查询、分析堆 / CPU 压力，或根据日志证据完成从复现到修复的循环。

此技能适用的任务

当工作涉及以下内容时，使用 platform-apex-logs-debug：

  • Salesforce 的 .log 文件
  • 堆栈跟踪和异常分析
  • Governor 限制
  • SOQL / DML / CPU / 堆故障排查
  • 从日志中提取的查询计划或性能证据

以下情况应委派给其他技能：

首先收集所需上下文

请询问或推断：

  • org 别名
  • 失败的事务 / 用户流程 / 测试名称
  • 大致时间戳或事务时间范围
  • 用户 / 记录 / 请求 ID（如已知）
  • 目标是仅进行诊断，还是进行诊断并完成修复循环

建议的工作流

1. 获取日志

使用 references/cli-commands.md 中的命令，列出、下载或流式传输目标 org 的日志。

2. 按以下顺序分析
  1. 入口点和事务类型
  2. 异常 / 致命错误
  3. Governor 限制
  4. 重复的 SOQL / DML 模式
  5. CPU / 堆热点
  6. 调用外部服务的时间和外部故障
3. 对严重程度分类
  • 严重 — 运行时故障、硬性限制、数据损坏风险
  • 警告 — 接近限制、非选择性查询、执行路径缓慢
  • 信息 — 优化机会或规范问题
4. 推荐最小且正确的修复方案

优先选择满足以下条件的修复方案：

  • 针对根因
  • 可安全处理批量数据
  • 可测试
  • 易于通过重新运行进行验证

扩展工作流：references/analysis-playbook.md

高信号问题模式

问题主要信号默认修复方向
循环中的 SOQL重复调用路径中反复出现 SOQL_EXECUTE_BEGIN只查询一次，使用映射 / 分组集合
循环中的 DML反复出现 DML_BEGIN 模式收集记录，一次性执行批量 DML
非选择性查询扫描的行数过多 / 选择性较差添加索引筛选条件，缩小范围
CPU 压力CPU 用量接近同步限制降低算法复杂度、使用缓存、在可行时改用异步处理
堆压力堆用量接近同步限制使用 SOQL for 循环进行流式处理，减少内存中的数据
空指针 / 致命错误EXCEPTION_THROWN / FATAL_ERROR对空值假设进行保护，修复空查询处理

扩展示例：references/common-issues.md

输出格式

完成分析时，按以下顺序报告：

  1. 失败情况
  2. 失败位置（类 / 方法 / 行 / 事务阶段）
  3. 失败原因（根因，而不只是症状）
  4. 严重程度
  5. 建议的修复方案
  6. 验证步骤

建议格式：

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

规则 / 限制

规则原因
修复建议始终以日志证据为依据避免推测性诊断——根因必须能在日志中追溯
对发现的每个问题都报告全部六项输出字段确保每个问题的发现结果完整且可执行
将每项发现分类为严重、警告或信息帮助用户确定优先处理哪些问题
将代码生成委派给 platform-apex-generate此技能负责诊断，不负责重写 Apex 代码
将测试执行委派给 platform-apex-test-run此技能不运行或修复测试类
未读取 LIMIT_USAGE 事件前，绝不假设限制处于安全范围失败点之前发生的操作可能已经消耗了限制

注意事项

陷阱解决方案
日志被截断至 2 MB降低调试级别（例如，ApexCode: INFO、ApexProfiling: FINE），然后重新捕获
同一问题同时表现为 SOQL 和 CPU 问题先修复循环中的 SOQL 查询——它通常会进一步导致 CPU 峰值
设置跟踪标志后没有日志出现确认跟踪标志的 ExpirationDate 在未来，并且跟踪的是正确的用户
异步上下文会改变限制值异步 CPU 限制为 60,000 ms，同步为 10,000 ms——报告超限前先检查事务类型
堆栈跟踪指向框架代码行，而非用户代码沿调用堆栈向上查找，越过触发器处理程序，找到源头用户代码

跨技能集成

需求委派给原因
实现 Apex 修复platform-apex-generate生成／审查代码变更
通过测试复现platform-apex-test-run执行测试并循环检查覆盖率
部署修复platform-metadata-deploy部署编排
创建调试数据platform-data-manage创建有针对性的种子数据／复现数据
优化缓慢的 SOQL 查询platform-soql-query调整查询结构／性能

参考文件索引

文件阅读时机
references/analysis-playbook.md从这里开始——适用于任何调试会话的详细分步工作流
references/common-issues.md快速查阅循环中的 SOQL、循环中的 DML、CPU／堆压力、空指针模式
references/cli-commands.md用于检索、流式传输和管理调试日志的 SF CLI 命令
references/debug-log-reference.md完整的事件类型目录、日志级别和治理限制参考值
references/log-analysis-tools.md工具指南：Apex Log Analyzer、Developer Console、CLI grep 模式
references/benchmarking-guide.md性能基准测试技术、基准测试数据和反模式
references/scoring-rubric.md用于评估分析质量的 100 分评分标准
assets/benchmarking-template.cls可复制粘贴的 Anonymous Apex 模板，用于运行性能基准测试
assets/cpu-heap-optimization.cls用于减少 CPU 时间和堆分配的 Apex 模式
assets/dml-in-loop-fix.cls用于解决循环中 DML 违规的修复前后示例
assets/soql-in-loop-fix.cls用于解决循环中 SOQL 违规的修复前后示例
assets/null-pointer-fix.cls防范空指针异常的模式

评分指南

分数含义
90+专业分析，并提供有力的修复指导
80–89分析良好，仅有少量遗漏
70–79可以接受，但可能遗漏次要问题
60–69仅完成部分诊断
< 60分析不完整

评论

支持 Markdown