frappe-agent-interpreter

Frappe 代码解释器 Agent

将模糊或不完整的 Frappe/ERPNext 开发需求转化为清晰、可执行的技术规范，并映射到完整的 61 项技能目录。

目的：弥合“用户想要什么”与“需要构建什么”之间的差距

何时使用此 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 has clear technical specs already
|   "Create Server Script on validate for Sales Invoice"
|   --> Skip agent, use relevant frappe-* skills directly

需求解读工作流

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?
  - v16 extend_doctype_class applicable?

STEP 4: GENERATE SPECIFICATION
  - DocType(s), event/trigger, mechanism, data flow
  - Error handling requirements
  - Version compatibility (v14/v15/v16)

STEP 5: MAP TO SKILLS
  - List required frappe-* skills from full catalog
  - Note dependencies between skills

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

机制选择矩阵

需求模式	机制	需要自定义应用？
“在表单上自动计算”	Client Script + Server Script	否
“保存前验证”	Server Script (validate)	否
“提交后发送通知”	Server Script (on_submit)	否
“在表单中添加按钮”	Client Script	否
“定时报告/同步”	hooks.py scheduler_events	是
“按用户筛选列表”	Server Script (Permission Query)	否
“自定义 REST API”	Server Script (API) 或 @frappe.whitelist()	视情况而定
“包含回滚的复杂事务”	Controller	是
“需要外部库 (requests)”	Controller	是
“审批工作流”	内置 Workflow + 可选的 Server Script	否
“自定义打印格式”	Jinja 模板 (Print Format)	否
“自定义报告”	Script Report 或 Query Report	视情况而定
“后台处理”	frappe.enqueue()	是
“文件上传处理”	Controller + File hooks	是
“缓存失效”	Cache API + hooks	是
“网站/门户页面”	Web 模板 + 路由	是
“UI 组件（仪表板等）”	Page 或 Custom Page	是

澄清问题框架

1. WHAT 类问题

• 涉及哪些 DocType？
• 需要更改哪些数据？
• 预期结果是什么？

2. WHEN 类问题

• 表单加载时？字段变更时？保存前/后？
• 提交前/后？按计划执行？点击按钮时？

3. WHO 类问题

• 所有用户？特定角色？仅文档所有者？

4. WHERE 类问题

• 在表单中（UI）？仅在数据库中？报告中？外部系统中？

5. ERROR 类问题

• 阻止操作？显示警告？静默记录？

6. VERSION 类问题（v16 注意事项）

• 针对单一版本，还是需要兼容多个版本？
• 可以使用 extend_doctype_class（v16），还是需要使用 doc_events（v14+）？
• 是否需要类型注解？（v16 最佳实践）

输出规范模板

始终按以下格式生成规范：

## Technical Specification

### Summary
[One sentence describing what will be built]

### Business Requirement
[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] |

### Data Flow
1. [Step 1]
2. [Step 2]

### Error Handling
[Strategy]

### Required Skills
- [ ] frappe-skill-name - for [purpose]

### Validation Criteria
[How to verify it works]

完整技能目录（61 项技能）

语法层（11 项技能）

技能	用途
frappe-syntax-clientscripts	Client Script JS 语法
frappe-syntax-serverscripts	Server Script Python 沙箱语法
frappe-syntax-controllers	Controller 类语法
frappe-syntax-hooks	hooks.py 配置语法
frappe-syntax-hooks-events	文档事件钩子语法
frappe-syntax-whitelisted	@frappe.whitelist() 语法
frappe-syntax-jinja	Jinja 模板语法
frappe-syntax-scheduler	Scheduler/enqueue 语法
frappe-syntax-customapp	应用结构语法
frappe-syntax-doctypes	DocType JSON 定义语法
frappe-syntax-reports	报告定义语法

核心层（7 项技能）

技能	用途
frappe-core-database	数据库操作、ORM、原始 SQL
frappe-core-permissions	权限系统、角色、规则
frappe-core-api	REST API、资源 API
frappe-core-workflow	工作流引擎、状态、转换
frappe-core-notifications	电子邮件、推送、系统通知
frappe-core-files	文件上传、附件、存储
frappe-core-cache	Redis 缓存、缓存失效

实现层（12 个技能）

技能	用途
frappe-impl-clientscripts	Client Script 实现模式
frappe-impl-serverscripts	Server Script 实现模式
frappe-impl-controllers	Controller 实现模式
frappe-impl-hooks	Hook 实现模式
frappe-impl-whitelisted	白名单方法模式
frappe-impl-jinja	Jinja 模板模式
frappe-impl-scheduler	定时任务／后台作业模式
frappe-impl-customapp	自定义应用开发工作流
frappe-impl-reports	报表构建模式
frappe-impl-workflow	工作流实现模式
frappe-impl-website	网站／门户开发
frappe-impl-ui-components	UI 组件模式
frappe-impl-integrations	外部系统集成

错误层（7 个技能）

技能	用途
frappe-errors-clientscripts	Client Script 错误模式
frappe-errors-serverscripts	Server Script 错误模式
frappe-errors-controllers	Controller 错误模式
frappe-errors-hooks	Hook 错误模式
frappe-errors-api	API 错误模式
frappe-errors-permissions	权限错误模式
frappe-errors-database	数据库错误模式

运维层（8 个技能）

技能	用途
frappe-ops-bench	Bench CLI 命令
frappe-ops-deployment	生产环境部署
frappe-ops-backup	备份与恢复
frappe-ops-performance	性能调优
frappe-ops-upgrades	版本升级流程
frappe-ops-cloud	云托管（FC、AWS 等）
frappe-ops-app-lifecycle	应用版本管理与发布
frappe-ops-frontend-build	前端资源构建

测试层（2 个技能）

技能	用途
frappe-testing-unit	单元与集成测试
frappe-testing-cicd	CI/CD 流水线配置

Agent 层（5 个技能）

技能	用途
frappe-agent-interpreter	本技能——需求解读
frappe-agent-validator	部署前代码验证
frappe-agent-debugger	调试 Frappe 问题
frappe-agent-migrator	数据迁移规划
frappe-agent-architect	架构决策

技能依赖关系图

机制	所需技能
Client Script	frappe-syntax-clientscripts、frappe-impl-clientscripts、frappe-errors-clientscripts
Server Script（Doc Event）	frappe-syntax-serverscripts、frappe-impl-serverscripts、frappe-errors-serverscripts
Server Script（API）	frappe-syntax-serverscripts、frappe-core-api、frappe-errors-api
Server Script（Scheduler）	frappe-syntax-serverscripts、frappe-syntax-scheduler、frappe-impl-scheduler
Server Script（Permission）	frappe-syntax-serverscripts、frappe-core-permissions、frappe-errors-permissions
Controller	frappe-syntax-controllers、frappe-impl-controllers、frappe-errors-controllers
Hooks	frappe-syntax-hooks、frappe-impl-hooks、frappe-errors-hooks
Custom App	frappe-syntax-customapp、frappe-impl-customapp、frappe-ops-bench
Jinja Template	frappe-syntax-jinja、frappe-impl-jinja
数据库操作	frappe-core-database、frappe-errors-database
Whitelisted Method	frappe-syntax-whitelisted、frappe-impl-whitelisted
Workflow	frappe-core-workflow、frappe-impl-workflow
Reports	frappe-syntax-reports、frappe-impl-reports
Website/Portal	frappe-impl-website、frappe-syntax-jinja
集成	frappe-impl-integrations、frappe-impl-customapp
后台作业	frappe-impl-scheduler、frappe-syntax-scheduler
测试	frappe-testing-unit、frappe-testing-cicd
部署	frappe-ops-deployment、frappe-ops-bench

常见模式识别

用户表述	机制	关键技能
“自动计算”“自动填充”	客户端脚本 + 服务端脚本	frappe-impl-clientscripts、frappe-impl-serverscripts
“验证”“保存前检查”	服务端脚本（validate）	frappe-impl-serverscripts
“阻止”“拦截”“不允许”	服务端脚本 + frappe.throw()	frappe-errors-serverscripts
“发送电子邮件”“通知”	服务端脚本或通知	frappe-core-notifications
“同步”“集成”“API”	控制器（自定义应用）	frappe-impl-integrations
“每天”“定时”	调度器或 hooks.py	frappe-impl-scheduler
“只能看到自己的”	权限查询	frappe-core-permissions
“审批”“授权”	内置工作流	frappe-core-workflow、frappe-impl-workflow
“添加按钮”“自定义操作”	客户端脚本	frappe-impl-clientscripts
“打印格式”“PDF”	Jinja 模板	frappe-impl-jinja
“报表”“仪表板”	脚本报表/查询报表	frappe-impl-reports
“部署”“上线”	部署工作流	frappe-ops-deployment
“测试”“CI”	测试框架	frappe-testing-unit
“缓存”“性能”	缓存 + 优化	frappe-core-cache、frappe-ops-performance

版本兼容性

务必考虑版本兼容性：

功能	v14	v15	v16
服务端脚本沙箱	是	是	是
extend_doctype_class	否	否	是
Chrome PDF 渲染	否	否	是
数据脱敏	否	否	是
UUID 命名规则	否	否	是
类型注解（最佳实践）	否	否	是
调度器间隔（秒）	240	60	60
job_id 去重	否	是	是

Agent 输出检查清单

完成需求解读前，务必确认：

• 业务需求清晰明确
• 已确定触发条件/事件
• 已选择机制并说明理由
• 已指定 DocType
• 已记录数据流
• 已定义错误处理方式
• 已注明版本兼容性（v14/v15/v16）
• 已从完整目录中列出所需的 frappe-* 技能
• 已定义验证标准
• 已注明 v16 注意事项（extend_doctype_class、类型注解）

详细检查清单请参阅 references/checklists.md。 需求解读示例请参阅 references/examples.md。