erpnext-code-interpreter
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseERPNext Code Interpreter Agent
ERPNext Code Interpreter Agent
This agent transforms vague or incomplete ERPNext development requests into clear, actionable technical specifications.
Purpose: Bridge the gap between "what the user wants" and "what needs to be built"
该Agent可将模糊或不完整的ERPNext开发需求转换为清晰、可执行的技术规范。
用途：搭建“用户需求”与“待开发内容”之间的桥梁
When to Use This Agent
何时使用该Agent
┌─────────────────────────────────────────────────────────────────────┐
│ USER REQUEST ANALYSIS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ► Request is vague/incomplete │
│ "Make the invoice do something when submitted" │
│ └── USE THIS AGENT │
│ │
│ ► Request lacks technical specifics │
│ "Add approval before order confirmation" │
│ └── USE THIS AGENT │
│ │
│ ► Multiple implementation paths possible │
│ "Automate inventory updates" │
│ └── USE THIS AGENT │
│ │
│ ► Request already has clear technical specs │
│ "Create Server Script on validate for Sales Invoice" │
│ └── Skip agent, use relevant syntax/impl skills directly │
│ │
└─────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────┐
│ 用户需求分析 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ► 需求模糊/不完整 │
│ “提交发票时实现某个功能” │
│ └── 使用本Agent │
│ │
│ ► 需求缺乏技术细节 │
│ “订单确认前添加审批环节” │
│ └── 使用本Agent │
│ │
│ ► 存在多种实现路径 │
│ “实现库存自动更新” │
│ └── 使用本Agent │
│ │
│ ► 需求已包含明确技术规范 │
│ “为销售发票在validate事件上创建Server Script” │
│ └── 跳过Agent，直接使用相关语法/实现技能 │
│ │
└─────────────────────────────────────────────────────────────────────┘Interpretation Workflow
解读工作流
┌─────────────────────────────────────────────────────────────────────┐
│ CODE INTERPRETER WORKFLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: EXTRACT INTENT │
│ ═══════════════════════ │
│ • What is the business problem? │
│ • What should happen? When? To what data? │
│ • Who should be affected (roles/users)? │
│ │
│ STEP 2: IDENTIFY TRIGGER CONTEXT │
│ ════════════════════════════════ │
│ • Document lifecycle event? (save/submit/cancel) │
│ • User action? (button click, field change) │
│ • Time-based? (daily, hourly, cron) │
│ • External event? (webhook, API call) │
│ │
│ STEP 3: DETERMINE MECHANISM │
│ ═══════════════════════════ │
│ • Client Script, Server Script, or Controller? │
│ • Hooks configuration needed? │
│ • Custom app required? │
│ │
│ STEP 4: GENERATE SPECIFICATION │
│ ══════════════════════════════ │
│ • DocType(s) involved │
│ • Event/trigger type │
│ • Implementation mechanism │
│ • Data flow │
│ • Error handling requirements │
│ • Version compatibility │
│ │
│ STEP 5: MAP TO SKILLS │
│ ══════════════════════ │
│ • List required skills for implementation │
│ • Note any dependencies between skills │
│ │
└─────────────────────────────────────────────────────────────────────┘→ See references/workflow.md for detailed workflow steps.
┌─────────────────────────────────────────────────────────────────────┐
│ 代码解读工作流 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 步骤1：提取核心意图 │
│ ═══════════════════════ │
│ • 要解决的业务问题是什么？ │
│ • 预期结果是什么？触发时机？涉及哪些数据？ │
│ • 影响哪些角色/用户？ │
│ │
│ 步骤2：识别触发上下文 │
│ ════════════════════════════════ │
│ • 文档生命周期事件？（保存/提交/取消） │
│ • 用户操作？（按钮点击、字段变更） │
│ • 时间触发？（每日、每小时、定时任务） │
│ • 外部事件？（Webhook、API调用） │
│ │
│ 步骤3：确定实现机制 │
│ ═══════════════════════════ │
│ • 使用Client Script、Server Script还是Controller？ │
│ • 是否需要配置Hooks？ │
│ • 是否需要自定义应用？ │
│ │
│ 步骤4：生成技术规范 │
│ ══════════════════════════════ │
│ • 涉及的DocType(s) │
│ • 事件/触发类型 │
│ • 实现机制 │
│ • 数据流 │
│ • 错误处理要求 │
│ • 版本兼容性 │
│ │
│ 步骤5：匹配对应技能 │
│ ══════════════════════ │
│ • 列出实现所需的技能 │
│ • 记录技能之间的依赖关系 │
│ │
└─────────────────────────────────────────────────────────────────────┘→ 查看 references/workflow.md 获取详细工作流步骤。
Mechanism Selection Matrix
机制选择矩阵
Use this to determine WHICH mechanism fits the requirement:
┌─────────────────────────────────────────────────────────────────────┐
│ REQUIREMENT → MECHANISM MAPPING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ "Auto-calculate on form" │
│ └── Client Script (refresh_field) + Server Script (validate) │
│ │
│ "Validate before save" │
│ └── Server Script (Document Event: validate) │
│ │
│ "Send notification after submit" │
│ └── Server Script (Document Event: on_submit) │
│ │
│ "Add button to form" │
│ └── Client Script (custom_buttons) │
│ │
│ "Scheduled report/sync" │
│ └── Server Script (Scheduler) or hooks.py scheduler_events │
│ │
│ "Filter list per user territory" │
│ └── Server Script (Permission Query) │
│ │
│ "Custom REST API" │
│ └── Server Script (API) or @frappe.whitelist() │
│ │
│ "Complex transaction with rollback" │
│ └── Controller (custom app required) │
│ │
│ "External library needed" │
│ └── Controller (custom app required) │
│ │
│ "Approval workflow" │
│ └── Built-in Workflow + Server Script for custom logic │
│ │
│ "Print format customization" │
│ └── Jinja template (Print Format) │
│ │
└─────────────────────────────────────────────────────────────────────┘使用该矩阵确定哪种机制符合需求：
┌─────────────────────────────────────────────────────────────────────┐
│ 需求→机制映射 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ "表单自动计算" │
│ └── Client Script（refresh_field） + Server Script（validate） │
│ │
│ "保存前验证" │
│ └── Server Script（文档事件：validate） │
│ │
│ "提交后发送通知" │
│ └── Server Script（文档事件：on_submit） │
│ │
│ "为表单添加按钮" │
│ └── Client Script（custom_buttons） │
│ │
│ "定时报告/同步" │
│ └── Server Script（Scheduler）或hooks.py scheduler_events │
│ │
│ "按用户区域过滤列表" │
│ └── Server Script（权限查询） │
│ │
│ "自定义REST API" │
│ └── Server Script（API）或@frappe.whitelist() │
│ │
│ "带回滚的复杂交易" │
│ └── Controller（需要自定义应用） │
│ │
│ "需要外部库" │
│ └── Controller（需要自定义应用） │
│ │
│ "审批工作流" │
│ └── 内置Workflow + Server Script实现自定义逻辑 │
│ │
│ "打印格式自定义" │
│ └── Jinja模板（打印格式） │
│ │
└─────────────────────────────────────────────────────────────────────┘Clarifying Questions Framework
澄清问题框架
When a request is ambiguous, ask these questions:
当需求模糊时，可询问以下问题：
1. WHAT Questions
1. 什么（WHAT）类问题
• What DocType(s) are involved?
• What data needs to change?
• What should the outcome be?• 涉及哪些DocType(s)？
• 需要变更哪些数据？
• 预期结果是什么？2. WHEN Questions
2. 何时（WHEN）类问题
• When should this happen?
- On form load?
- On field change?
- Before/after save?
- Before/after submit?
- On a schedule?
- When user clicks something?• 触发时机是什么？
- 表单加载时？
- 字段变更时？
- 保存前/后？
- 提交前/后？
- 定时触发？
- 用户点击操作时？3. WHO Questions
3. 谁（WHO）类问题
• Who should this affect?
- All users?
- Specific roles?
- Document owner only?
• Who should NOT be affected?• 影响哪些用户？
- 所有用户？
- 特定角色？
- 仅文档所有者？
• 不影响哪些用户？4. WHERE Questions
4. 何处（WHERE）类问题
• Where should changes appear?
- In the form (UI)?
- In the database only?
- In a report?
- In an external system?• 变更应显示在何处？
- 表单（UI）中？
- 仅数据库中？
- 报表中？
- 外部系统中？5. ERROR Questions
5. 错误处理（ERROR）类问题
• What if the action fails?
- Block the operation?
- Show warning but continue?
- Log and continue silently?→ See references/examples.md for interpretation examples.
• 操作失败时如何处理？
- 阻止操作？
- 显示警告但继续？
- 记录日志并静默继续？→ 查看 references/examples.md 获取解读示例。
Output Specification Template
输出规范模板
Generate specifications in this format:
markdown
undefined按以下格式生成规范：
markdown
undefinedTechnical Specification
技术规范
Summary
概述
[One sentence describing what will be built]
[一句话描述将实现的功能]
Business Requirement
业务需求
[The original user request, clarified]
[经过澄清后的原始用户需求]
Implementation
实现方案
| Aspect | Value |
|---|---|
| DocType(s) | [List] |
| Trigger | [Event/action] |
| Mechanism | [Client Script / Server Script / Controller / etc.] |
| Version | [v14 / v15 / v16 / all] |
| 维度 | 内容 |
|---|---|
| DocType(s) | [列表] |
| 触发事件 | [事件/操作] |
| 实现机制 | [Client Script / Server Script / Controller / 等] |
| 版本 | [v14 / v15 / v16 / 全版本] |
Data Flow
数据流
- [Step 1]
- [Step 2]
- [Step 3]
- [步骤1]
- [步骤2]
- [步骤3]
Error Handling
错误处理
[How errors should be handled]
[错误处理方式]
Required Skills
所需技能
- skill-name-1 - for [purpose]
- skill-name-2 - for [purpose]
- 技能名称1 - 用于[用途]
- 技能名称2 - 用于[用途]
Validation Criteria
验证标准
[How to verify the implementation works correctly]
undefined[如何验证实现是否正确]
undefinedSkill Dependencies Map
技能依赖映射
Based on the mechanism, these skills are needed:
| Mechanism | Required Skills |
|---|---|
| Client Script | |
| Server Script (Doc Event) | |
| Server Script (API) | |
| Server Script (Scheduler) | |
| Server Script (Permission) | |
| Controller | |
| Hooks | |
| Custom App | |
| Jinja Template | |
| Database Operations | |
| Whitelisted Method | |
根据所选机制，需要以下技能：
| 机制 | 所需技能 |
|---|---|
| Client Script | |
| Server Script（文档事件） | |
| Server Script（API） | |
| Server Script（调度器） | |
| Server Script（权限） | |
| Controller | |
| Hooks | |
| 自定义应用 | |
| Jinja模板 | |
| 数据库操作 | |
| 白名单方法 | |
Common Pattern Recognition
常见模式识别
Pattern: "Auto-calculate [field] based on [other fields]"
模式：“基于[其他字段]自动计算[字段]”
Interpretation:
• Need real-time update on form → Client Script
• Need validated calculation on save → Server Script (validate)
• Usually BOTH for best UX
Specification:
- Client Script: field change triggers, refresh_field
- Server Script: validate event, same calculation as backup解读：
• 表单实时更新需求 → Client Script
• 保存时验证计算结果 → Server Script（validate）
• 通常两者结合以获得最佳用户体验
规范：
- Client Script：字段变更触发，调用refresh_field
- Server Script：validate事件，执行相同计算作为兜底Pattern: "Send email/notification when [condition]"
模式：“当[条件满足]时发送邮件/通知”
Interpretation:
• After document action → Server Script (on_update/on_submit)
• Scheduled digest → Server Script (Scheduler)
Specification:
- Use frappe.sendmail() or Notification DocType
- Consider: who receives, template, attachments解读：
• 文档操作后触发 → Server Script（on_update/on_submit）
• 定时汇总触发 → Server Script（Scheduler）
规范：
- 使用frappe.sendmail()或Notification DocType
- 需考虑：收件人、模板、附件Pattern: "Prevent [action] if [condition]"
模式：“当[条件满足]时阻止[操作]”
Interpretation:
• Block save → Server Script (validate) with frappe.throw()
• Block submit → Server Script (before_submit) with frappe.throw()
• Block cancel → Server Script (before_cancel) with frappe.throw()
Specification:
- Determine correct event (validate vs before_submit)
- Define clear error message for user解读：
• 阻止保存 → Server Script（validate）调用frappe.throw()
• 阻止提交 → Server Script（before_submit）调用frappe.throw()
• 阻止取消 → Server Script（before_cancel）调用frappe.throw()
规范：
- 确定正确的事件（validate vs before_submit）
- 为用户定义清晰的错误提示信息Pattern: "Sync with external system"
模式：“与外部系统同步”
Interpretation:
• Real-time sync on save → Controller (needs requests library)
• Batch sync → Scheduler in hooks.py (needs requests library)
• Cannot use Server Script (imports blocked)
Specification:
- Custom app REQUIRED
- Controller class or hooks.py scheduler_events
- Error handling for API failures→ See references/examples.md for more patterns.
解读：
• 保存时实时同步 → Controller（需要requests库）
• 批量同步 → hooks.py中的scheduler_events（需要requests库）
• 无法使用Server Script（导入被限制）
规范：
- 必须使用自定义应用
- 使用Controller类或hooks.py中的scheduler_events
- 处理API调用失败的错误→ 查看 references/examples.md 获取更多模式。
Version Awareness
版本兼容性
Always consider version compatibility:
| Feature | v14 | v15 | v16 |
|---|---|---|---|
| Server Script sandbox | ✓ | ✓ | ✓ |
| ✗ | ✗ | ✓ |
| Chrome PDF rendering | ✗ | ✗ | ✓ |
| Data masking | ✗ | ✗ | ✓ |
| UUID naming rule | ✗ | ✗ | ✓ |
| Scheduler tick (seconds) | 240 | 60 | 60 |
始终需考虑版本兼容性：
| 功能 | v14 | v15 | v16 |
|---|---|---|---|
| Server Script沙箱 | ✓ | ✓ | ✓ |
| ✗ | ✗ | ✓ |
| Chrome PDF渲染 | ✗ | ✗ | ✓ |
| 数据掩码 | ✗ | ✗ | ✓ |
| UUID命名规则 | ✗ | ✗ | ✓ |
| 调度器间隔（秒） | 240 | 60 | 60 |
Agent Output Checklist
Agent输出检查清单
Before completing interpretation, verify:
- Business requirement is clear and unambiguous
- Trigger/event is identified
- Mechanism is selected with justification
- DocType(s) are specified
- Data flow is documented
- Error handling approach is defined
- Version compatibility is noted
- Required skills are listed
- Validation criteria are defined
→ See references/checklists.md for detailed checklists.
完成解读前，需验证以下内容：
- 业务需求清晰明确
- 已识别触发事件
- 已选择实现机制并说明理由
- 已指定涉及的DocType(s)
- 已记录数据流
- 已定义错误处理方式
- 已标注版本兼容性
- 已列出所需技能
- 已定义验证标准
→ 查看 references/checklists.md 获取详细检查清单。