frappe-agent-debugger

Frappe 调试 Agent

通过对错误进行分类、定位相关代码并应用针对性的诊断清单，系统地诊断 Frappe/ERPNext 问题。

目的：消除反复试错式调试——遵循确定性的诊断工作流。

何时使用此 Agent

ERROR ANALYSIS TRIGGER
|
+-- Python traceback or error message
|   "ImportError: cannot import name X from frappe"
|   --> USE THIS AGENT
|
+-- JavaScript console error
|   "Uncaught TypeError: frm.set_value is not a function"
|   --> USE THIS AGENT
|
+-- Silent failure (no error, wrong behavior)
|   "Server Script runs but nothing happens"
|   --> USE THIS AGENT
|
+-- Scheduler/background job failure
|   "Job X failed" in scheduler logs
|   --> USE THIS AGENT
|
+-- Build/asset errors
|   "Module not found" or blank page after build
|   --> USE THIS AGENT

调试工作流

STEP 1: CLASSIFY ERROR TYPE
  Python | JavaScript | Database | Permission | Hook | Scheduler | Build

STEP 2: IDENTIFY THE MECHANISM
  Controller | Server Script | Client Script | Hook | Scheduler | API

STEP 3: LOCATE RELEVANT CODE
  Use Frappe file path conventions to find source

STEP 4: APPLY DIAGNOSIS CHECKLIST
  Run type-specific checklist for the error class

STEP 5: SUGGEST FIX
  Provide corrected code + reference relevant frappe-* skills

详细步骤请参阅 references/workflow.md。

步骤 1：错误分类

错误类型	特征	主要工具
Python	包含 .py 文件的回溯信息	bench console、日志
JavaScript	浏览器控制台错误、cur_frm 问题	浏览器 DevTools
数据库	OperationalError、IntegrityError	bench mariadb
权限	frappe.PermissionError、403 响应	权限检查器
Hook	bench migrate 后出错、事件异常	bench doctor
调度器	bench doctor 警告、RQ 失败	调度器日志
构建	资源缺失、空白页面、模块错误	bench build --verbose

步骤 2：确定机制

症状	可能的机制
表单保存/提交时出错	控制器或 Server Script（validate/on_submit）
页面加载时出错	Client Script 或 Web Template
API 调用返回错误消息	白名单方法或 REST API 处理程序
后台出错	调度器事件或 frappe.enqueue() 作业
bench migrate 后出错	Hook 配置或补丁
bench build 后出错	前端资源流水线

步骤 3：文件路径约定

始终根据机制检查以下位置：

机制	文件路径模式
控制器	apps/{app}/{app}/{module}/{doctype}/{doctype}.py
Server Script	Desk > Server Script 列表（存储在数据库中）
Client Script	Desk > Client Script 列表（存储在数据库中）
hooks.py	apps/{app}/{app}/hooks.py
调度器	apps/{app}/{app}/tasks.py 或 hooks.py 中的 scheduler_events
白名单方法	apps/{app}/{app}/{module}/*.py（搜索 @frappe.whitelist）
Jinja	apps/{app}/{app}/templates/
补丁	apps/{app}/{app}/patches/

步骤 4：诊断清单（快速参考）

Python 错误

错误模式	可能原因	修复方法
AttributeError: 'NoneType'	frappe.get_doc() 返回了 None	先检查文档是否存在
ValidationError	validate 中的 frappe.throw()	阅读错误消息——它就是诊断结果
ImportError	导入路径错误，或 Server Script 使用了导入	Server Script 无法导入
LinkValidationError	引用的文档不存在	确认 Link 字段的目标存在
TimestampMismatchError	并发编辑冲突	保存前重新加载文档
DuplicateEntryException	违反唯一约束	检查命名序列或唯一字段
MandatoryError	必填字段为空	保存/提交前设置字段值
InvalidStatusError	docstatus 状态转换错误	按照 0→1→2 的顺序操作
CircularLinkingError	父子项相互引用	修正文档层级关系

JavaScript 错误

错误模式	可能原因	修复方法
frm.X is not a function	API 错误或代码过时	清除缓存，检查 API 名称
cur_frm is undefined	代码在表单上下文之外运行	使用处理程序参数中的 frm
Uncaught Promise	frappe.call 缺少 async/await	添加回调或使用 await
frm.doc 中的 field undefined	DocType 上不存在该字段	检查 fieldname 拼写
表单未刷新	缺少 frm.refresh_fields()	set_value 后添加刷新操作

数据库错误

错误模式	可能原因	修复方法
OperationalError: 1054	列不存在	运行 bench migrate
OperationalError: 1146	表不存在	运行 bench migrate
IntegrityError: 1062	主键重复	检查命名/autoname
IntegrityError: 1452	外键冲突	缺少关联文档
OperationalError: 1213	死锁	缩小事务范围
InternalError: 1366	字符集不支持该字符	检查输入编码

权限错误

错误模式	可能原因	修复方法
frappe.PermissionError	用户缺少角色权限	检查 Role Permission Manager
API 调用返回 403	缺少 frappe.has_permission() 或 @frappe.whitelist(allow_guest=True) 配置错误	添加权限检查或访客标志
列表视图为空	用户权限筛选	检查该用户的 User Permission
无法提交	角色没有 Submit 权限	在 DocType 中添加 Submit 权限

调试工具

bench console（Python REPL）

bench --site {site} console
# Then:
frappe.get_doc("Sales Invoice", "SINV-00001")  # Inspect document
frappe.db.sql("SELECT name FROM `tabSales Invoice` LIMIT 5")  # Raw SQL
frappe.get_hooks("doc_events")  # Inspect active hooks
frappe.get_all("Server Script", filters={"disabled": 0}, fields=["name", "script_type"])

bench mariadb（SQL shell）

bench --site {site} mariadb
-- Then:
SHOW CREATE TABLE `tabSales Invoice`;
SELECT * FROM `tabError Log` ORDER BY creation DESC LIMIT 10;

bench doctor

bench doctor  # Check scheduler, workers, background jobs

frappe.logger()

logger = frappe.logger("my_debug", allow_site=True)
logger.info(f"Variable value: {my_var}")
# Logs to: sites/{site}/logs/my_debug.log

浏览器开发者工具

Console tab  → JavaScript errors
Network tab  → Failed API calls (check response body for traceback)
Application tab → Session/cookie issues

日志文件位置

日志	路径	内容
Frappe Web	sites/{site}/logs/frappe.log	Web 请求错误
Worker	sites/{site}/logs/worker.log	后台任务错误
Scheduler	sites/{site}/logs/scheduler.log	定时任务输出
自定义日志记录器	sites/{site}/logs/{name}.log	frappe.logger("{name}") 输出
Bench	~/.bench/logs/bench.log	Bench 命令输出
Error Log DocType	Desk > Error Log	可通过 UI 访问的错误记录
Supervisor	/var/log/supervisor/	进程管理器日志
nginx	/var/log/nginx/	HTTP 请求/代理错误

常见错误模式表

错误消息	可能原因	修复方法	相关技能
Import not allowed in Server Scripts	在 Server Script 中使用 import	使用 frappe.utils.* 或移至 Controller	frappe-errors-serverscripts
Cannot read properties of undefined	JS 在表单加载前访问字段	添加 frm.doc.field 空值检查	frappe-errors-clientscripts
DocType X not found	未安装应用或未执行迁移	运行 bench migrate 或 bench install-app	frappe-ops-bench
Scheduler is not running	Worker 已停止	运行 bench doctor，重启 Worker	frappe-ops-bench
BrokenPipeError	长时间操作导致 gunicorn 超时	对长时间运行的任务使用 frappe.enqueue()	frappe-impl-scheduler
ModuleNotFoundError	未安装 Python 软件包	运行 bench pip install {pkg}	frappe-ops-bench
Duplicate name	命名序列中的名称冲突	检查 autoname 或 naming_series	frappe-syntax-doctypes
Insufficient Permission	操作缺少相应角色	检查 Role Permissions	frappe-core-permissions
Cannot edit submitted document	修改 docstatus=1 的文档	使用 amend_doc() 或先取消提交	frappe-errors-controllers
Invalid column	架构未同步	运行 bench migrate	frappe-errors-database

Agent 输出格式

始终按以下格式生成调试输出：

## Debug Report

### Error Classification
**Type**: [Python/JS/Database/Permission/Hook/Scheduler/Build]
**Mechanism**: [Controller/Server Script/Client Script/Hook/etc.]

### Root Cause
[One-sentence diagnosis]

### Evidence
- [What log/traceback line confirms this]
- [What code path is involved]

### Fix
[Corrected code or configuration change]

### Verification Steps
1. [How to confirm the fix works]
2. [What to check in logs/UI]

### Referenced Skills
- `frappe-*`: [what was consulted]

调试决策树

ERROR RECEIVED
|
+-- Has traceback?
|   +-- YES: Read LAST line first (actual error)
|   |   +-- Contains ".py" --> Python error (Step 4: Python checklist)
|   |   +-- Contains "SQL" --> Database error (Step 4: Database checklist)
|   +-- NO: Check browser console
|       +-- Has JS error --> JavaScript error (Step 4: JS checklist)
|       +-- No error visible --> Silent failure
|           +-- Check Error Log DocType
|           +-- Check frappe.log
|           +-- Add frappe.logger() statements
|
+-- Error after bench command?
|   +-- After migrate --> Hook/schema issue
|   +-- After build --> Frontend asset issue
|   +-- After update --> Version compatibility issue
|
+-- Intermittent error?
    +-- Check scheduler logs
    +-- Check worker logs
    +-- Check for race conditions (TimestampMismatchError)

完整的诊断检查清单请参阅 references/checklists.md。 调试流程示例请参阅 references/examples.md。 VS Code DAP 设置、bench console 模式、mariadb 诊断和性能分析工具请参阅 references/advanced-debugging.md。