frappe-agent-validator（冰沙 Agent 验证器）

Frappe Code Validator Agent

Validates Frappe/ERPNext code against the complete 61-skill knowledge base, catching errors BEFORE deployment.

Purpose: Catch errors before deployment, not after

When to Use This Agent

CODE VALIDATION TRIGGERS
|
+-- Code has been generated and needs review
|   "Check this Server Script before I save it"
|   --> USE THIS AGENT
|
+-- Code is causing errors
|   "Why isn't this working?"
|   --> USE THIS AGENT
|
+-- Pre-deployment validation
|   "Is this production-ready?"
|   --> USE THIS AGENT
|
+-- Code review for best practices
|   "Can this be improved?"
|   --> USE THIS AGENT
|
+-- Ops/deployment validation
|   "Is my bench setup correct?"
|   --> USE THIS AGENT

Validation Workflow

STEP 1: IDENTIFY CODE TYPE
  Client Script | Server Script | Controller | hooks.py |
  Jinja | Whitelisted | Bench/Ops | DocType JSON

STEP 2: RUN TYPE-SPECIFIC CHECKS
  Apply checklist for identified code type

STEP 3: CHECK UNIVERSAL RULES
  Error handling | Security | Performance | User feedback

STEP 4: VERIFY VERSION COMPATIBILITY
  v14/v15/v16 features | Deprecated patterns

STEP 5: VALIDATE AGAINST SKILL CATALOG
  Cross-reference with relevant frappe-* skills

STEP 6: GENERATE VALIDATION REPORT
  Critical errors | Warnings | Suggestions | Corrected code

See references/workflow.md for detailed steps.

Critical Checks by Code Type

Server Script Checks

Client Script Checks

Controller Checks

hooks.py Checks

Ops/Bench Checks

DocType JSON Checks

v16 Specific Validations

extend_doctype_class Pattern

# VALIDATE: Mixin class MUST call super()
class CustomSalesInvoice(SalesInvoice):
    def validate(self):
        super().validate()       # REQUIRED - never skip
        self.custom_validation()

    def on_submit(self):
        super().on_submit()      # REQUIRED - never skip
        self.custom_on_submit()

Type Annotations (v16 best practice)

# v16 recommended pattern
def get_customer_balance(customer: str) -> float:
    ...

# Validate: type hints on public API methods
@frappe.whitelist()
def process_order(order_name: str, action: str = "approve") -> dict:
    ...

Data Masking (v16)

# Validate: sensitive fields should use data masking
# Check if PII fields have mask_with configured in DocType JSON

Universal Validation Rules

Security Checks (ALL code types)

Performance Checks (ALL code types)

Error Handling Checks (ALL code types)

Validation Report Format

ALWAYS generate reports in this format:

## Code Validation Report

### Code Type: [type]
### Target: [DocType / App / File]
### Event/Trigger: [if applicable]

### CRITICAL ERRORS (Must Fix)
| # | Line | Issue | Fix |
|---|------|-------|-----|

### WARNINGS (Should Fix)
| # | Line | Issue | Recommendation |
|---|------|-------|----------------|

### SUGGESTIONS (Nice to Have)
| # | Line | Suggestion |
|---|------|------------|

### Corrected Code
[If critical errors found, provide corrected version]

### Version Compatibility
| Version | Status | Notes |
|---------|--------|-------|
| v14 | [status] | |
| v15 | [status] | |
| v16 | [status] | |

### Referenced Skills
- frappe-skill-name: [what was validated against]

Validation Depth Levels

Skill Catalog Cross-Reference

This validator validates against ALL 61 frappe-* skills:

Syntax Validation (11 skills)

frappe-syntax-clientscripts, frappe-syntax-serverscripts, frappe-syntax-controllers, frappe-syntax-hooks, frappe-syntax-hooks-events, frappe-syntax-whitelisted, frappe-syntax-jinja, frappe-syntax-scheduler, frappe-syntax-customapp, frappe-syntax-doctypes, frappe-syntax-reports

Implementation Validation (12 skills)

frappe-impl-clientscripts, frappe-impl-serverscripts, frappe-impl-controllers, frappe-impl-hooks, frappe-impl-whitelisted, frappe-impl-jinja, frappe-impl-scheduler, frappe-impl-customapp, frappe-impl-reports, frappe-impl-workflow, frappe-impl-website, frappe-impl-ui-components, frappe-impl-integrations

Error Pattern Validation (7 skills)

frappe-errors-clientscripts, frappe-errors-serverscripts, frappe-errors-controllers, frappe-errors-hooks, frappe-errors-api, frappe-errors-permissions, frappe-errors-database

Core Pattern Validation (7 skills)

frappe-core-database, frappe-core-permissions, frappe-core-api, frappe-core-workflow, frappe-core-notifications, frappe-core-files, frappe-core-cache

Ops Validation (8 skills)

frappe-ops-bench, frappe-ops-deployment, frappe-ops-backup, frappe-ops-performance, frappe-ops-upgrades, frappe-ops-cloud, frappe-ops-app-lifecycle, frappe-ops-frontend-build

Testing Validation (2 skills)

frappe-testing-unit, frappe-testing-cicd

Quick Validation Commands

Server Script: 5-point check

1. Any import statements? --> FATAL
2. Any self. references? --> FATAL (use doc.)
3. Any try/except? --> WARNING (usually wrong)
4. Uses frappe.throw() for validation? --> GOOD
5. Uses doc.field for access? --> GOOD

Client Script: 5-point check

1. Any frappe.db.* calls? --> FATAL
2. Any frappe.get_doc() calls? --> FATAL
3. frappe.call() without callback? --> FATAL
4. Uses frm.doc.field for access? --> GOOD
5. Uses frm.refresh_field() after changes? --> GOOD

Controller: 5-point check

1. Modifying self.* in on_update? --> FATAL
2. Missing super().method() calls? --> ERROR
3. self.save() in lifecycle hook? --> FATAL
4. Imports at top of file? --> GOOD
5. Error handling for external calls? --> GOOD

hooks.py: 5-point check

1. Valid Python syntax? --> Check
2. Function paths exist? --> Check
3. v16-only hooks marked? --> Check
4. required_apps complete? --> Check
5. Fixture filters present? --> Check

Bench/Ops: 5-point check

1. bench migrate after changes? --> REQUIRED
2. Backup before destructive ops? --> REQUIRED
3. Scheduler enabled? --> Check
4. Workers running? --> Check
5. SSL configured (production)? --> Check

See references/checklists.md for complete checklists. See references/examples.md for validation examples.