nova ai v4.x强制要求prompt采用三段式结构：①role声明块（仅agent/tool/orchestrator）；②context块（含domain、intent、constraints三字段，json格式）；③instruction块（纯文本，仅支持{{var}}变量语法），缺一不可且顺序固定。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你正在将Nova AI项目从v3.x升级到v4.x，但发现原有Prompt在新版本中失效、输出不稳定或被拒绝执行——这不是配置错误，而是v4.x对Prompt结构、角色声明和安全校验机制做了强制性变更。
确认当前版本与兼容性边界
进入Nova AI控制台 → 点击右上角用户头像 → 选择“系统信息”，查看当前运行版本号。若显示为v3.9.8或更低，说明尚未升级；若已显示v4.0.0及以上，则必须按v4规范重写Prompt。v3.x的Prompt在v4.x中【默认被拦截】，即使语法合法也会返回“Invalid prompt structure”错误，不报具体行号，仅提示格式不合规。
不要尝试用v3.x模板加version=4声明绕过——该参数已被移除，任何包含此字段的请求均直接拒收。
v4.x Prompt必需的三段式结构
v4.x强制要求Prompt必须由且仅由以下三个区块组成，顺序不可调换，区块间用空行分隔：
① 【Role声明块】：首行必须为ROLE: [agent|tool|orchestrator]，仅接受这三个值之一。agent用于通用对话，tool用于调用插件，orchestrator用于多步骤编排。其他值（如user、system、assistant）全部非法。
② 【Context块】：第二部分以CONTEXT:开头，后接JSON格式上下文描述。必须包含"domain"（字符串，如"finance"）、"intent"（字符串，如"calculate_tax"）、"constraints"（数组，如["no_external_api", "output_chinese_only"]）。缺一不可，字段名大小写敏感。
③ 【Instruction块】：第三部分以INSTRUCTION:开头，后接纯文本指令。禁止出现代码块、Markdown表格、XML标签。若含变量占位符，必须用{{variable_name}}格式，且该变量必须已在CONTEXT中声明。
迁移时最易踩的三个坑
方法一：角色声明写成ROLE: user → 系统直接拒绝，不提示原因。正确写法只有ROLE: agent、ROLE: tool、ROLE: orchestrator三种。
方法二：CONTEXT中漏掉"constraints"字段 → 即使为空数组也要显式写出"constraints": []，否则报错“Missing required field in context”。
方法三：INSTRUCTION里混用${var}和{{var}} → v4.x只认双大括号语法，美元符号语法会触发安全引擎拦截，返回“Unsafe template syntax”。
旧Prompt批量转换脚本（Python示例）
将原v3.x Prompt文本保存为old_prompt.txt，执行以下脚本：
import jsonwith open("old_prompt.txt") as f: raw = f.read().strip()lines = raw.split("\n")role = "agent" # 根据实际用途设为tool或orchestratorcontext = {"domain": "general", "intent": "chat", "constraints": []}instruction = "\n".join(lines)new_prompt = f"ROLE: {role}\n\nCONTEXT:\n{json.dumps(context, indent=2)}\n\nINSTRUCTION:\n{instruction}"with open("v4_prompt.txt", "w") as f: f.write(new_prompt)
注意：此脚本仅处理基础结构转换，【domain和intent必须人工核对并替换】，自动填充的"general"/"chat"会导致部分高权限插件调用失败。
