Run any Skill in Manus with one click

ai-mode-xml-authoring

Stars0

Forks0

UpdatedJune 23, 2026 at 09:41

emp-script-ai 及其下游项目（travelagent、pf2023）所用 AI Mode XML schema 的撰写参考。覆盖 `<mode>` / `<step>` / `<prompt>` / `<apis>` / `<sqls>` / `<actions>` / `<paramChecks>` / `<ui>` 各块结构、prompt 数据源（sqlRef / api / action / CDATA）、函数调用 prompt（`apisCheck`）、URL / 请求占位符、输出自定义标签（`<day>`、`<rq>`、`<cid>`、`<enj>`、`<id>`、`<num>`、`<sersday>`、`<prices>`、`<gn>`）以及 step 控制属性（`innerCall`、`validateParams`、`multiOnlyUserMsg`、`action`、`actionSqlRef`）。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

gdx1231

gdx1231/emp-script-ai

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

AI Mode XML 撰写参考

Mode XML 文件由 emp-script-ai 的 Modes.loadModes(xml) 解析。它定义一个或多个命名 <mode> 流程，把系统提示、用户提示、SQL 注入数据、HTTP 注入数据、Java 动作、参数校验、HTML UI 事件组合起来。每个解析出的 mode 由 ChatManagerBase 消费，通过 AiStreamOrPost 发送给 LLM。

文件骨架

<?xml version="1.0" encoding="UTF-8"?>
<modes>
    <mode name="..." description="..." temperature="0.3" topP="0.7" thinking="false">
        <step name="..." description="..." stream="true">
            <prompts>
                <prompt name="..." role="system"><![CDATA[ ... ]]></prompt>
                <prompt name="..." role="user" sqlRef="..." api="..." action="..." prefix="..." />
                ...
            </prompts>
        </step>
        <step name="export" stream="false" action="saveLead" actionSqlRef="getLastResponse" />
        <apis>     <api name="..." url="..." method="get|post" refRequest="true" /> ... </apis>
        <sqls>     <sql name="...">SELECT ...</sql> ... </sqls>
        <actions>  <action name="..." class="pkg.ClassName" /> ... </actions>
        <paramChecks> <paramCheck name="..." type="int|enum|date" promptRule="..." /> ... </paramChecks>
        <ui>
            <welcome><![CDATA[<div>...</div>]]></welcome>
            <complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[<div>...</div>]]></complete>
        </ui>
    </mode>
    ...
</modes>

<mode> 内多个 <step> 按文档顺序串行执行；每个 step 的 prompts 拼接到对话末尾再调用 LLM。运行期状态（chat id、ai_id、request_id、ai_provider、ai_model）由框架自动串联。

`<mode>` 属性

属性	必填	说明
`name`	是	查找键，`Modes.getMode(name)` 返回克隆体。
`description`	是	中文描述。
`temperature`	否	小数；结构化抽取建议 `0.1`，对话建议 `0.7`。
`topP`	否	小数。
`thinking`	否	`"true"` 启用推理模式（provider 支持时）。
`responseFormat`	否	`"json_object"` 强制 JSON 输出。
`maxHistoryMessages`	否	多轮历史消息数上限（默认 30）。
`maxHistoryTokensK`	否	历史 token 上限，单位 K（默认 100），超限会截断并打 WARN。
`debugOutput`	否	回显 LLM 原始输出，便于调试。

`<step>` 属性

属性	作用
`name`	step 标识。
`description`	中文描述。
`stream`	`"true"` 走 SSE 流式；`"false"` 走完整 POST。默认 `true`。
`innerCall`	`"true"` 表示本步骤对用户隐藏（用于预校验、参数抽取等），LLM 响应留在对话历史但不发给客户端。
`multiOnlyUserMsg`	`"true"` 时，多轮对话中只把父 chat 的用户消息拉入历史。
`validateParams`	逗号分隔的 `<paramCheck>` 名，step 运行前先校验这些参数。
`action`	`<action>` 中定义的 Java 类名，在 LLM 响应之后调用。
`actionSqlRef`	`<sql>` 名，先执行该 SQL（通常取最后一条 assistant 消息），把结果传给 `action`。
`api`	在调用 LLM 之前，先调 `<api>` 取数注入到 prompt。

典型三段式：<step1 validate innerCall="true"> 校验参数 → <step createEnqJny stream="true"> 生成内容 → <step export stream="false" action="..."> 落库。

`<prompt>` 的 4 种数据源

每个 prompt 必须有 name + role（system 或 user）。内容来自以下唯一一种来源：

属性	来源	说明
（无）	内联 `<![CDATA[...]]>`	纯文本或 JSON schema 示例。
`sqlRef="name"`	`<sqls>/<sql name="name">`	结果按 `dataType="json"` 或 `dataGroupField="..."` 渲染成 JSON / CSV。
`api="name"`	`<apis>/<api name="name">`	每次请求调一次 API，把响应渲染进 prompt。
`action="name"`	`<actions>/<action name="name">`	Java 类（实现 `IAction.execute`）生成内容。

可选 prompt 属性：

prefix="..." — 在内容前固定拼接的文本（常见 "城市数据如下："）。
description="..." — 中文描述，仅给阅读者看，不发给 LLM。
dataType="json" — 告诉渲染器把 SQL 结果按 JSON 输出。
dataGroupField="SER_NAME" — 把 SQL 结果 JSON 数组按指定字段重组成 {field: [rows]} 形式。
showInChat="false" — 在聊天 UI 中隐藏该 prompt 文本，但仍发给 LLM（用于合成预提示）。
apisCheck="true" — 该 prompt 是函数调用指令：LLM 只能输出 [{"tool": "name", "args": {...}}] 或 [{"tool": "none"}]，不得输出其他文字。框架随后按 <api name="..."> 解析工具，把结果以系统消息回灌。典型用法：路由到 getparametersapi、exportapi、createenqjnyapi、checkparamsapi 等。

函数调用 prompt 模板

<prompt name="checkUsingXxx" role="user" apisCheck="true"><![CDATA[
你是一个智能助手，能够根据用户需求调用工具回答问题。
可用工具：

xxxapi(arg: type): description。返回 JSON {...}。

任务：根据用户输入，以 JSON 格式输出工具调用指令：
[{"tool": "工具名", "args": {"参数名": "参数值"}}] 或 [{"tool": "none"}]

严格规则：
1. 仅输出 JSON 工具调用指令，绝对不要输出任何其他文字。
2. 调用 xxxapi 时 args.xxx 必须传用户输入的完整原句，不得改写/截取。
]]></prompt>

对应的 <api> 节点需要 refRequest="true"，框架自动把 request_id 拼到 URL 用于后端关联。

`<apis>` — 外部 HTTP 工具

<apis>
    <api name="getparametersapi"
         description="从用户输入中提取城市/国家、人数和日期参数。"
         url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id&amp;ai_provider=@ai_provider&amp;ai_model=@ai_model"
         refRequest="true" timeout="30000" method="post">
        <form>
            <field name="q" value="@text" />
        </form>
    </api>
</apis>

属性	作用
`name`	工具名，被 `apisCheck` prompt 或 `api="..."` 引用。
`url`	端点 URL。支持占位符：`@EWA.HOST_BASE`、`@request_id`、`@ai_provider`、`@ai_model`、`@text`、`@camp_id`、`@camp_name`、`@export_type`、`@ref_grp_id`、`@enq_id`、`@city_ids` 等（任意 `@` 前缀的请求参数）。
`parameters`	内联 URL query 参数（`a=@x&b=@y`）。
`method`	`get`、`post`、`put`、`delete` 或 `patch`。默认 `get`。
`refRequest="true"`	自动附加当前 `request_id` 用于后端关联。
`key`	覆盖 API key header（极少用）。
`timeout`	毫秒。默认 5000。
`<form><field>`	POST/PUT 等表单字段，`@` 前缀值取自请求参数。与 `<body>` 互斥，优先使用 `<body>`。
`<body>`	请求体 CDATA 内容，用于 POST/PUT/DELETE/PATCH 的 JSON 或自定义 body。与 `<form>` 互斥；当 `method` 为 POST 及以上且 `body` 非空时，框架以 body 模式发送请求。支持 `@` 占位符。
`<headers><header>`	自定义 HTTP header。

@EWA.HOST_BASE 是宿主 EWA 应用的运行期 base URL。后端 JSP 通常挂在 /back_admin/ai/ 下。

`request_id` 必须是 UUID 格式

request_id 是整个对话链路的唯一标识符，由 emp-script-ai 的 AiChatParamsManager 通过 java.util.UUID.randomUUID().toString() 生成，并原样写入 AI_CHAT 表的 AI_UID 列。所有引用 @request_id 的下游链路（<api url> 占位符、AI_CHAT_UID 外键关联、AI_CHAT_PARAMS.AIP_VAL 反查）都依赖该值在数据库内是唯一且可索引的。

硬性约束：

格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（8-4-4-4-12，36 字符，含 4 个连字符，全小写十六进制）。
生成方式：调用方（前端 / 后端 JSP / 单元测试）必须用 java.util.UUID.randomUUID().toString()、crypto.randomUUID()（Node/Web）或等价标准库生成；禁止自造时间戳、Math.random()、Long.toHexString(System.currentTimeMillis()) 等任何非标准 UUID 的伪 ID。
大小写：建议全小写（与框架生成一致），但大小写不敏感；DB 列若为 varchar 不区分大小写，若为带大小写敏感排序规则的 nvarchar 则必须保持调用方与生成方一致。
不要复用：每个 chat / 每次新对话都应生成新 UUID；把同一个 request_id 复用到第二个 step 会让 AI_CHAT_UID 外键串数据。
占位符 @request_id 出现在 <api url> / <api parameters> / <sql> 体里都会被替换为该 UUID 字符串；下游 JSP / Servlet 收到 URL 后再做解析。

错误用法举例（禁止）：

<!-- 错误：自定义前缀 + 时间戳，破坏了 AI_UID 的唯一性假设 -->
url="@EWA.HOST_BASE/...?p_request_id=req_@timestamp_@userid"

<!-- 错误：nanoId / snowflake，虽然唯一但格式不是 UUID，下游 SQL like 'uuid%' 等隐式约束会失效 -->
url="@EWA.HOST_BASE/...?p_request_id=@nanoid"

<!-- 正确：直接传 @request_id，由调用方保证注入的是 UUID -->
url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id"

运行时占位符（`@EWA.*` 与请求参数）

框架在解析 Mode XML 时，会把所有 @xxx 形式的占位符替换为运行期值（定义见 emp-script 框架的 RequestValue 常量）。两类占位符：

系统内置 `@EWA.*` 占位符

由框架在每次请求时填入，与业务无关。常用于让 LLM「知道当前日期 / 主机地址 / 路径」：

占位符	含义	示例值
`@EWA.DATE.YEAR`	当前年	`2026`
`@EWA.DATE.MONTH`	当前月（1-12）	`6`
`@EWA.DATE.DAY`	当前日	`22`
`@EWA.DATE.HOUR`	当前小时（24h）	`14`
`@EWA.DATE.MINUTE`	当前分钟	`37`
`@EWA.DATE.SECOND`	当前秒	`45`
`@EWA.DATE.TIME`	`HH:MM:SS`	`14:37:45`
`@EWA.DATE.STR`	`YYYY-MM-DD` 短日期	`2026-06-22`
`@EWA.DATE.STR1` / `@EWA.DATETIME.STR`	`YYYY-MM-DD HH:MM:SS`	`2026-06-22 14:37:45`
`@EWA.DATE.SEASON`	当前季度	`2`
`@EWA.HOST` / `@EWA.HTTP`	站点完整 URL	`https://www.gdxsoft.com`
`@EWA.HOST_PROTOCOL`	协议	`https`
`@EWA.HOST_PORT`	端口	`443`
`@EWA.HOST_CONTEXT`	项目 contextPath	`/users`
`@EWA.HOST_BASE`	`protocol://host:port/context`	`https://www.gdxsoft.com/users`
`@EWA.CP`	contextPath（不带 host）	`/users`
`@EWA.CPF`	当前 servlet 路径	`/users/userinfo.jsp`
`@EWA.CPF_ALL`	servlet 路径 + 查询串	`/users/userinfo.jsp?user_id=1`
`@EWA_QUERY` / `@EWA_QUERY_ALL`	查询串（不含 / 含 EWA 系统参数）	`user_id=1&type=2`

来源：emp-script/src/main/java/com/gdxsoft/easyweb/script/RequestValue.java:80-211。

典型用法：

<!-- 在 system prompt 中告诉 LLM 当前日期，避免「明天指哪天」的歧义 -->
<prompt name="init_prompt" role="system">
    <![CDATA[你是 GYAP 旅游 AI 行程规划专家。当前日期：@EWA.DATE.STR
用户提到「明天」「下周三」时必须基于此日期换算为 YYYY-MM-DD，禁止再反问。]]>
</prompt>

<!-- 在 <api url> 中拼接宿主地址，确保部署到不同环境都正确 -->
<api name="getservicesapi" url="@EWA.HOST_BASE/back_admin/ai/get_services.jsp?request_id=@request_id" ... />

<!-- 在 <complete test="..."> 中按当前日期判断是否触发 -->
<complete test="@EWA.DATE.MONTH = 12 and @fullText like '%春节%'">...</complete>

请求参数占位符（`@xxx` 取自请求）

任何来自 URL 参数、RequestValue、上游 LLM 抽取的参数都可以用 @name 引用：

上下文	替换时机	典型示例
`<api url="...">`	调用 API 前	`url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id&ai_provider=@ai_provider&ai_model=@ai_model"`
`<api parameters="...">`	同上	`parameters="ENQ_ID=@enq_id&EWA_AJAX=JSON_AI_PROMPT"`
`<api><form><field value="...">`	同上	`<field name="q" value="@text" />`
`<api><headers><header value="...">`	同上	`<header name="x-uid" value="@user_id" />`
`<sql>...</sql>`	执行 SQL 前	`where ai_id = @ai_id`
`<prompt><![CDATA[...]]>`	不替换——按字面量发给 LLM	见下方注意

注意：占位符替换不会发生在 prompt 的 CDATA 文本里。如果你需要把请求参数注入到 prompt，必须借助 <prompt sqlRef="..."> 或 <prompt api="..."> 把动态数据作为单独的 prompt 节点提供，再由框架拼接到对话末尾。在 prompt CDATA 里写 @xxx 只会作为字面量发给 LLM，LLM 看到的就是 @xxx 这个字符串本身。

占位符替换的常见坑

@ 前缀必须紧贴变量名：@ request_id（中间有空格）不会被识别。
大小写敏感：@ewa.date.str 不会匹配 EWA.DATE.STR。
未定义占位符 不会被替换，原样保留 @xxx 字符串。LLM 收到后会看到 @xxx 字面量。
嵌套占位符（@@xxx 或 @EWA.DATE.@xxx）不支持，只能单层。
@ 出现在 JSON / SQL 字面量里：<![CDATA[...]]> 中含 @ 不替换（见上），但 URL/SQL/header 里的 @ 仍按占位符处理。如果 URL 里要表示真正的「@」（如邮箱），请用 %40。

`<sqls>` — 命名 SQL

<sqls>
    <sql name="getLastResponse" description="获取最后一次AI回复">
        <![CDATA[
        select top 1 AIM_MSG as full_text
        from AI_CHAT_MSG
        where AIM_ROLE = 'assistant' and ai_id = @ai_id
        order by aim_id desc
        ]]>
    </sql>
</sqls>

name 被 sqlRef、actionSqlRef 或 paramCheck 引用。
SQL 体里 @param_name 占位符在运行时绑定，值来自 URL 参数、RequestValue，或上游 LLM 抽取出的参数。
必须用 <![CDATA[ ... ]]> 包裹，内部 < / > 安全。
支持多语句、SQL Server TOP n 等方言特有语法；在项目配置的数据库上执行。

`<actions>` — Java 代码动作

<actions>
    <action name="createEnqJny" description="创建询价单和行程及服务"
            class="pf2023.aiAction.ActionEnqJny" />
</actions>

当 <step action="..."> 完成后被调用。
类必须实现 com.gdxsoft.ai.export.IAction（execute(...)）。
actionSqlRef 先跑一条 SQL（通常取最后一条 assistant 消息），把结果（一般是 JSON 文本）传给 action，由 action 解析 JSON 后写库——这是把 LLM 输出落库的标准模式。

`<paramChecks>` — 入参校验

<paramChecks>
    <paramCheck name="people_num" des="团员人数" type="int"
                promptRule="游客人数，不含领队；从'X人''X+Y'格式中的X等表达中提取，返回整数" />
    <paramCheck name="grp_type"   des="行程类型" type="enum" sqlRef="grp_type_options"
                sqlValueField="BAS_TAG" sqlLabelField="BAS_TAG_NAME"
                promptRule="根据行程内容判断最匹配的类型" />
    <paramCheck name="departure_date" des="出发日期" type="date"
                promptRule="从用户输入中提取出发日期（YYYY-MM-DD）" />
</paramChecks>

属性	作用
`name`	存入 `AI_CHAT_PARAMS` 的键。
`des`	中文描述。
`type`	`int`、`enum`、`date`，或不填（自由文本）。
`promptRule`	当 `ChatManagerBase.saveInputParams()` 从对话上下文抽取该参数时，给 LLM 的指令。
`default`	缺失时的默认值。
`options`	`type="enum"` 时的静态枚举值，格式 `KEY1=标签1,KEY2=标签2`。与 `sqlRef` 动态枚举互斥；若同时配置，`sqlRef` 优先（SQL 失败时回退到 `options`）。
`sqlRef` + `sqlValueField` + `sqlLabelField`	`type="enum"` 时使用：从该 SQL 取候选值，强制 LLM 必须选 SQL 结果中的某项。

校验机制：含 validateParams="people_num,departure_date" 的 step 会阻塞流程，直到这些参数都齐备且合法（int 范围、enum 枚举命中、date 可解析）。缺值时会触发一个内部 step，由 LLM 调用 saveInputParams() 补齐。

`<ui>` — HTML 事件

<ui> 块定义两条 HTML 片段，分别在新会话开始（welcome）和响应完成时（complete）下发到前端，作为 SSE 事件中的 ui_html 字段渲染。前端实现参考：static/WebContent/js/ai/StreamChatBot.js。

`<welcome>` — 新会话欢迎 HTML

<welcome> 在页面加载时由前端 StreamChatBot.fetchWelcome(modeName) 调用后端 stream.jsp?ui=welcome&mode=<mode> 取回，包装成 SSE 消息后渲染。完整事件流：

前端                          后端
StreamChatBot.fetchWelcome()
  → GET /back_admin/ai/stream.jsp?ui=welcome&mode=chat
                              → 解析 mode，对应 Mode 取出 <ui><welcome>
                              → SSE 事件 {ui_html: "...", ui_type: "welcome"}
  → respJson.ui_html 注入 <div class="message ui-html ui-welcome">
                       → innerHTML = ui_html

前端渲染逻辑（StreamChatBot.js:458-465）：

if (respJson.ui_html) {
    var uiMsg = document.createElement('div');
    uiMsg.className = 'message ui-html' + (respJson.ui_type ? ' ui-' + respJson.ui_type : '');
    uiMsg.innerHTML = respJson.ui_html;
    chatBox.appendChild(uiMsg);
}

ui_type 会被附加为 CSS class（ui-welcome / ui-complete），用于样式区分。

welcome HTML 可以内嵌交互按钮

由于 innerHTML 直接注入到 DOM，HTML 片段里可以含：

示例卡片：点击后调用 StreamChatBot.sendExample(this)，把卡片文本塞进输入框并自动发送（StreamChatBot.js:110-121）。
跳转链接：普通 <a href="..." target="_blank"> 直接可用。
JS 函数调用：<a onclick="StreamChatBot.xxx()"> 触发前端方法（如导出、刷新等）。

示例（旅游行程 mode 的真实写法）：

<welcome><![CDATA[<div class="welcome-banner">
<div class="welcome-header">
<h3>✈️ 欢迎使用 GYAP 旅游 AI 助手</h3>
<p>告诉我您的旅行计划，我可以帮您规划行程...</p>
</div>
<div class="welcome-examples">
<p class="examples-title">💡 试试这些示例：</p>
<div class="example-cards">
<div class="example-card" onclick="StreamChatBot.sendExample(this)">北京出发-美东名校参访12天游学，12月20日出发，20+2</div>
<div class="example-card" onclick="StreamChatBot.sendExample(this)">香港国际夏令营，7天，港大嘉道理中心，30+3</div>
<div class="example-card" onclick="StreamChatBot.sendExample(this)">中秋八达岭长城1日自由行，公交/地铁，3人</div>
</div>
</div>
</div>]]></welcome>

要点：

sendExample(this) 中的 this 是被点击的 DOM 元素；前端会取 card.textContent 作为输入文本（StreamChatBot.js:114），所以示例文字必须直接写在卡片元素的文本里，不能藏在子节点。
多个示例卡用同一函数 sendExample 即可，无需为每张卡片写不同 JS。
注意 CDATA 里 onclick 的引号是合法的 XML 属性引号，不需要转义。

`<complete test="...">` — 响应完成后追加的 HTML

<complete test="..."> 在主响应（LLM 输出）的最后一条 assistant 消息上评估 SQL 表达式，命中时把 HTML 追加到响应末尾。test 是属性值（非 CDATA），内部 < > & 必须写成 < > &。

<complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[<div class="complete-banner">
<p>行程规划完成！您可以创建团或导出为以下格式：</p>
<p class="export-links">
<a href="@ewa.cp/back_admin/ai/create_enq_jny.jsp?_ui=1&amp;opengrp=1&request_id=@request_id" target="_blank">创建团</a>
<a onclick="StreamChatBot.exportItinerary('pdf')">PDF</a>
<a onclick="StreamChatBot.exportItinerary('excel')">Excel</a>
<a onclick="StreamChatBot.exportItinerary('html')">HTML</a>
<a onclick="StreamChatBot.exportItinerary('word')">Word</a>
</p>
</div>]]></complete>

完整的事件流：

主响应结束（LLM 输出 <day>...</day>...</prices> 后）
                          → 后端评估 complete.test
                          → 命中则作为 SSE 事件追加 {ui_html, ui_type: "complete"}
前端                      → 渲染为 <div class="message ui-html ui-complete">

<complete> HTML 通常用来提供「后续操作」入口：

导出按钮：StreamChatBot.exportItinerary('pdf') 等触发 create.jsp?request_id=<id>&export_type=<type>（StreamChatBot.js:127-145），成功后 window.open(url) 下载文件。
创建团 / 跳转后台：普通 <a href="..." target="_blank">。
继续调整提示：调用 sendExample 或跳转到其它 mode。

前后端约定一览

后端（Mode XML）	前端（StreamChatBot.js）
`<ui><welcome>` 内的 HTML	`respJson.ui_html` → 渲染成 `<div class="message ui-html ui-welcome">`
`<ui><complete test>` HTML	同样渲染，CSS class 加 `ui-complete`
示例卡片 `onclick="StreamChatBot.sendExample(this)"`	取卡片文本塞输入框 + 触发发送
导出按钮 `onclick="StreamChatBot.exportItinerary('pdf')"`	GET `create.jsp?request_id=...&export_type=...`，成功后 `window.open(url)`
`test` 属性里引用 `@fullText` / `@request_id`	由后端评估，前端无感

完整骨架

<ui>
    <welcome><![CDATA[... 示例卡片 + 跳转链接 ...]]></welcome>
    <complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[... 创建团 / 导出按钮 ...]]></complete>
</ui>

输出自定义标签（用户语义锚点）

这些标签不是 XML schema 元素，schema 里没有任何关于 <gn> / <day> / <rq> / <cid> / <enj> / <id> / <num> / <sersday> / <prices> 的定义。它们是项目作者在 system prompt 里约定的语义锚点——LLM 在响应中按约定输出尖括号标签包裹关键字段，后端用 HTML 解析器（或正则）抽出来落库。

要点：

完全由 mode 作者决定：每条 mode 的 system prompt 里写「请把 X 包在 <xxx> 标签里输出」，抽取端就认 <xxx>。换一条 mode 可以定义完全不同的标签集。
不属于固定词汇：schema 不校验标签存在性、闭合性、嵌套关系。LLM 漏写、错写都属于业务问题，不是解析错误。
承载内容由 mode 决定：可以是行程项、表格行、客户线索字段、价格条目、表格、JSON-like 块——任何能被结构化抽取的内容。
配套的后端 action 必须自己写：每个 mode 想要落库，就要写一个 IAction 实现，负责 Jsoup.parse(...) → select(...) → 写表。schema 不会替你生成。

跨领域例子（同一 schema，不同 mode 各自的标签）

领域 / mode	自定义标签	用途
旅游行程（travelagent `chat` mode）	`<gn>` 项目名、`<day>` 单日、`<rq>` 日期、`<cid>` 城市 ID、`<enj>` 行程、`<id>` 服务 ID、`<num>` 数量、`<sersday>` 当日服务汇总、`<prices>` 价格表	抽取后写入 `GRP_MAIN` / `ENQ_MAIN` / `ENQ_JNY` / `ENQ_JNY_SER`
CRM 线索（pf2023 `crmLead` mode）	`<lead>` 单条线索（含 `<company>`/`<contact>`/`<phone>`/`<email>` 等嵌套字段）	抽取后写入 CRM 线索表
机票查询（pf2023 `getairs` mode）	`<flight>` 单航班（含 `<no>`/`<dep>`/`<arr>`/`<duration>` 等）	落库到航班字典或前端直接展示
景点 / 机场信息（pf2023 `getScenicInfo` / `getAirPortInfo` mode）	`<scenic>` / `<airport>` 顶层标签	落库到景点 / 机场字典

后端实现参考：pf2023/aiAction/ActionEnqJny.java:43-105（行程）、ActionCrmLead.java（线索），都用 jsoup 解析。

后端推荐用 jsoup 抽取（通用技术）

LLM 输出是带自定义标签的 Markdown / 自由文本，不是标准 XML；正则匹配脆弱。推荐使用 jsoup 把整段文本当 HTML 片段解析，再用 CSS 选择器取标签——与具体业务无关。

import org.jsoup.Jsoup;
import org.jsoup.nodes.Document;
import org.jsoup.nodes.Element;
import org.jsoup.select.Elements;

// 1. 解析整段 LLM 输出为 Document（HTML 片段模式）
String llmOutput = "...完整的 <day>...</day> 输出...";
Document doc = Jsoup.parse(llmOutput);

// 2. 顶层标签：selectFirst 取第一个
String grpName = doc.selectFirst("gn") != null
        ? doc.selectFirst("gn").text().trim()
        : "";

// 3. 列表标签：select 取全部后遍历
Elements items = doc.select("lead");          // 例：抽 CRM 线索
for (Element item : items) {
    String company = item.selectFirst("company").text().trim();
    String phone   = item.selectFirst("phone").text().trim();
    String email   = item.selectFirst("email").text().trim();
    // ...写库
}

// 4. 嵌套结构：父标签内 selectFirst("child") 取子标签
Elements days = doc.select("day");
for (Element day : days) {
    String date    = day.selectFirst("rq").text().trim();
    Element enj    = day.selectFirst("enj");
    String content = enj != null ? enj.text().trim() : "";

    // 5. 同级成对标签：用 Elements 数组下标配对
    Elements idTags  = day.select("id");
    Elements numTags = day.select("num");
    for (int i = 0; i < idTags.size(); i++) {
        String serConnId = idTags.get(i).text();
        String num = numTags.size() > i ? numTags.get(i).text() : "1";
        // ...写服务清单行
    }
}

jsoup 的通用优点（与业务无关）：

不依赖严格的 XML 闭合顺序，LLM 即使混入 Markdown、表情、换行、注释也能正确解析。
select("xxx") / selectFirst("xxx") 与 CSS 选择器一致，写起来直观。
Element.text() 自动去掉标签内残留的 HTML 实体和多余空白。
对自定义标签完全透明——只要 LLM 输出了对应的尖括号标签，jsoup 就能解析。

不要用 javax.xml.parsers.DocumentBuilder 之类的标准 XML 解析器：LLM 输出常含未转义的 <、>、HTML 实体、表情符号、注释等，会触发 SAXException；用 jsoup 的 HTML 解析模式可以容忍。

给 LLM 立规则的通用原则（具体规则随 mode 而定）

每个 mode 的 system prompt 都要给 LLM 立「自定义标签输出规则」，下面几条是跨领域通用的：

必填锚点要写明：哪些字段如果缺失就视为生成失败（例如行程 mode 的 <rq> 日期、CRM mode 的 <phone>），让 LLM 在缺数据时直接报错而不是跳过。
ID 类标签必须字面存在于上游数据：禁止编造。如服务 ID 必须来自提供的服务清单，景点 ID 必须来自提供的景点字典。
数量、金额配对字段：<id> 与 <num>、<item> 与 <price> 等成对出现的标签，提示 LLM 它们必须严格对齐。
完整性：列表型标签（<day>、<lead>、<flight>）必须一次输出全部条目，不允许中途停止。
不暴露内部字段：所有 ID、原始 JSON、数据库字段名都应包裹在标签里，标签外的中文叙述里只展示人类可读名称。
结束标记：列表结束后追加一个 <prices> / <summary> / <total> 之类的「收尾锚点」，让后端可以判定响应完整。

具体到某条 mode 时，把以上通用原则翻译成该 mode 的业务规则，写进对应的 system prompt。

撰写清单

新增或修改 mode 时：

设定 <mode> 的 temperature（抽取类 0.1，对话类 0.7）；需要 JSON 输出时在 <mode> 上设 responseFormat="json_object"（注意：step 级别不支持覆盖该属性）。
第一个 step 通常是 <step validateParams="..." stream="false" innerCall="true">，用来在主流程前把参数补齐。
主 step 用 stream="true"，包含：
- 一段 <prompt role="system"> 设定人设 + 全部规则（占 prompt 主体）。
- 一个 apisCheck="true" prompt，列出 LLM 可调的工具。
- 每个动态数据源一条 <prompt role="user" api="..." 或 sqlRef="...">。
- 一条 <prompt role="user" prefix="..."> 描述输出格式（XML 自定义标签）。
可选的末 step：stream="false" action="..." actionSqlRef="getLastResponse"，用来落库。
所有 api="..." / sqlRef="..." / action="..." 都要在对应块里声明。
在 step validateParams 中引用的每个参数，都要在 <paramChecks> 里定义。
配 <ui><welcome>，必要时加 <ui><complete test="...">。
mvn -DskipTests compile 仅校验 Java 编译，XML 解析在运行时进行，写完务必在单元测试里调用 Modes.loadModes(xml) 自检。

常见坑

CDATA 不能写在属性里 — 含 < > 的内容必须放元素体（<![CDATA[...]]>），不能放属性。
@request_id 拼写 — 后端 JSP 有的用 p_request_id（带 p_ 前缀），有的用 @request_id；与 JSP 一一对齐。
Step 顺序 — 由文档顺序决定，与 name 无关。step1 校验会先于 step 生成执行。
apisCheck 提示混入散文 — LLM 可能忽略「仅输出 JSON」的规则。system prompt 里也要强调，工具列表尽量短。
thinking="true" + responseFormat="json_object" — 部分 provider 的 reasoning token 会破坏 JSON 解析，严格抽取 step 务必 thinking="false"。
responseFormat 只能设在 <mode> 上 — <step> 不支持 responseFormat 属性，写了也会被忽略。需要 JSON 输出的场景（如参数抽取 step），请在 <mode> 级别设置。
<id> 只出现在 <sersday> 而未出现在 <enj> — 价格表无法绑定数量；每个付费服务必须至少挂一条 <enj> 日程行。
POST <api> 没写 <form> 也没写 <body> — 请求体为空。query 风格的 POST 用 parameters="..."；JSON body 用 <body><![CDATA[...]]></body>。
maxHistoryTokensK 过低 — 多轮中途截断，LLM 丢上下文，关注 WARN 日志。
<prompt> 内容里写 @xxx — @ 前缀的占位符仅在 <sql> / <api url> / <api parameters> 中会替换；写在 prompt 的 <![CDATA[...]]> 文本里只是普通字符。需要引用请求参数请用 prompt 模板或运行时注入。
request_id 不是 UUID — AI_CHAT.AI_UID 列与所有外键（AI_CHAT_MSG.AI_ID、AI_CHAT_PARAMS.AI_ID）隐含假设 request_id 是标准 UUID。调用方必须用 UUID.randomUUID().toString() 生成，框架内部已遵循此约定（AiChatParamsManager.java:278）。任何自造 ID 都会导致 AI_UID 唯一索引冲突或多会话串数据。详见上文「request_id 必须是 UUID 格式」一节。
用标准 XML 解析器抽自定义标签 — LLM 输出不是标准 XML（混入 Markdown、未转义字符、表情、HTML 实体），DocumentBuilder / SAXParser 会抛异常。统一用 jsoup HTML 模式解析，详见上文「后端推荐用 jsoup 抽取」。

name	ai-mode-xml-authoring
description	emp-script-ai 及其下游项目（travelagent、pf2023）所用 AI Mode XML schema 的撰写参考。覆盖 `<mode>` / `<step>` / `<prompt>` / `<apis>` / `<sqls>` / `<actions>` / `<paramChecks>` / `<ui>` 各块结构、prompt 数据源（sqlRef / api / action / CDATA）、函数调用 prompt（`apisCheck`）、URL / 请求占位符、输出自定义标签（`<day>`、`<rq>`、`<cid>`、`<enj>`、`<id>`、`<num>`、`<sersday>`、`<prices>`、`<gn>`）以及 step 控制属性（`innerCall`、`validateParams`、`multiOnlyUserMsg`、`action`、`actionSqlRef`）。
source	synthesized
extracted_at	2026-06-22
synthesized_from	["/Users/admin/java/gyap.org/travelagent/src/main/resources/define/travelAgent.xml","/Users/admin/java/gyap.org/pf2023/src/main/java/ai_mode.xml"]

AI Mode XML 撰写参考

文件骨架

<?xml version="1.0" encoding="UTF-8"?>
<modes>
    <mode name="..." description="..." temperature="0.3" topP="0.7" thinking="false">
        <step name="..." description="..." stream="true">
            <prompts>
                <prompt name="..." role="system"><![CDATA[ ... ]]></prompt>
                <prompt name="..." role="user" sqlRef="..." api="..." action="..." prefix="..." />
                ...
            </prompts>
        </step>
        <step name="export" stream="false" action="saveLead" actionSqlRef="getLastResponse" />
        <apis>     <api name="..." url="..." method="get|post" refRequest="true" /> ... </apis>
        <sqls>     <sql name="...">SELECT ...</sql> ... </sqls>
        <actions>  <action name="..." class="pkg.ClassName" /> ... </actions>
        <paramChecks> <paramCheck name="..." type="int|enum|date" promptRule="..." /> ... </paramChecks>
        <ui>
            <welcome><![CDATA[<div>...</div>]]></welcome>
            <complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[<div>...</div>]]></complete>
        </ui>
    </mode>
    ...
</modes>

`<mode>` 属性

属性	必填	说明
`name`	是	查找键，`Modes.getMode(name)` 返回克隆体。
`description`	是	中文描述。
`temperature`	否	小数；结构化抽取建议 `0.1`，对话建议 `0.7`。
`topP`	否	小数。
`thinking`	否	`"true"` 启用推理模式（provider 支持时）。
`responseFormat`	否	`"json_object"` 强制 JSON 输出。
`maxHistoryMessages`	否	多轮历史消息数上限（默认 30）。
`maxHistoryTokensK`	否	历史 token 上限，单位 K（默认 100），超限会截断并打 WARN。
`debugOutput`	否	回显 LLM 原始输出，便于调试。

`<step>` 属性

属性	作用
`name`	step 标识。
`description`	中文描述。
`stream`	`"true"` 走 SSE 流式；`"false"` 走完整 POST。默认 `true`。
`innerCall`	`"true"` 表示本步骤对用户隐藏（用于预校验、参数抽取等），LLM 响应留在对话历史但不发给客户端。
`multiOnlyUserMsg`	`"true"` 时，多轮对话中只把父 chat 的用户消息拉入历史。
`validateParams`	逗号分隔的 `<paramCheck>` 名，step 运行前先校验这些参数。
`action`	`<action>` 中定义的 Java 类名，在 LLM 响应之后调用。
`actionSqlRef`	`<sql>` 名，先执行该 SQL（通常取最后一条 assistant 消息），把结果传给 `action`。
`api`	在调用 LLM 之前，先调 `<api>` 取数注入到 prompt。

典型三段式：<step1 validate innerCall="true"> 校验参数 → <step createEnqJny stream="true"> 生成内容 → <step export stream="false" action="..."> 落库。

`<prompt>` 的 4 种数据源

每个 prompt 必须有 name + role（system 或 user）。内容来自以下唯一一种来源：

属性	来源	说明
（无）	内联 `<![CDATA[...]]>`	纯文本或 JSON schema 示例。
`sqlRef="name"`	`<sqls>/<sql name="name">`	结果按 `dataType="json"` 或 `dataGroupField="..."` 渲染成 JSON / CSV。
`api="name"`	`<apis>/<api name="name">`	每次请求调一次 API，把响应渲染进 prompt。
`action="name"`	`<actions>/<action name="name">`	Java 类（实现 `IAction.execute`）生成内容。

可选 prompt 属性：

prefix="..." — 在内容前固定拼接的文本（常见 "城市数据如下："）。
description="..." — 中文描述，仅给阅读者看，不发给 LLM。
dataType="json" — 告诉渲染器把 SQL 结果按 JSON 输出。
dataGroupField="SER_NAME" — 把 SQL 结果 JSON 数组按指定字段重组成 {field: [rows]} 形式。
showInChat="false" — 在聊天 UI 中隐藏该 prompt 文本，但仍发给 LLM（用于合成预提示）。
apisCheck="true" — 该 prompt 是函数调用指令：LLM 只能输出 [{"tool": "name", "args": {...}}] 或 [{"tool": "none"}]，不得输出其他文字。框架随后按 <api name="..."> 解析工具，把结果以系统消息回灌。典型用法：路由到 getparametersapi、exportapi、createenqjnyapi、checkparamsapi 等。

函数调用 prompt 模板

<prompt name="checkUsingXxx" role="user" apisCheck="true"><![CDATA[
你是一个智能助手，能够根据用户需求调用工具回答问题。
可用工具：

xxxapi(arg: type): description。返回 JSON {...}。

任务：根据用户输入，以 JSON 格式输出工具调用指令：
[{"tool": "工具名", "args": {"参数名": "参数值"}}] 或 [{"tool": "none"}]

严格规则：
1. 仅输出 JSON 工具调用指令，绝对不要输出任何其他文字。
2. 调用 xxxapi 时 args.xxx 必须传用户输入的完整原句，不得改写/截取。
]]></prompt>

对应的 <api> 节点需要 refRequest="true"，框架自动把 request_id 拼到 URL 用于后端关联。

`<apis>` — 外部 HTTP 工具

<apis>
    <api name="getparametersapi"
         description="从用户输入中提取城市/国家、人数和日期参数。"
         url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id&amp;ai_provider=@ai_provider&amp;ai_model=@ai_model"
         refRequest="true" timeout="30000" method="post">
        <form>
            <field name="q" value="@text" />
        </form>
    </api>
</apis>

属性	作用
`name`	工具名，被 `apisCheck` prompt 或 `api="..."` 引用。
`url`	端点 URL。支持占位符：`@EWA.HOST_BASE`、`@request_id`、`@ai_provider`、`@ai_model`、`@text`、`@camp_id`、`@camp_name`、`@export_type`、`@ref_grp_id`、`@enq_id`、`@city_ids` 等（任意 `@` 前缀的请求参数）。
`parameters`	内联 URL query 参数（`a=@x&b=@y`）。
`method`	`get`、`post`、`put`、`delete` 或 `patch`。默认 `get`。
`refRequest="true"`	自动附加当前 `request_id` 用于后端关联。
`key`	覆盖 API key header（极少用）。
`timeout`	毫秒。默认 5000。
`<form><field>`	POST/PUT 等表单字段，`@` 前缀值取自请求参数。与 `<body>` 互斥，优先使用 `<body>`。
`<body>`	请求体 CDATA 内容，用于 POST/PUT/DELETE/PATCH 的 JSON 或自定义 body。与 `<form>` 互斥；当 `method` 为 POST 及以上且 `body` 非空时，框架以 body 模式发送请求。支持 `@` 占位符。
`<headers><header>`	自定义 HTTP header。

@EWA.HOST_BASE 是宿主 EWA 应用的运行期 base URL。后端 JSP 通常挂在 /back_admin/ai/ 下。

`request_id` 必须是 UUID 格式

硬性约束：

格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（8-4-4-4-12，36 字符，含 4 个连字符，全小写十六进制）。
生成方式：调用方（前端 / 后端 JSP / 单元测试）必须用 java.util.UUID.randomUUID().toString()、crypto.randomUUID()（Node/Web）或等价标准库生成；禁止自造时间戳、Math.random()、Long.toHexString(System.currentTimeMillis()) 等任何非标准 UUID 的伪 ID。
大小写：建议全小写（与框架生成一致），但大小写不敏感；DB 列若为 varchar 不区分大小写，若为带大小写敏感排序规则的 nvarchar 则必须保持调用方与生成方一致。
不要复用：每个 chat / 每次新对话都应生成新 UUID；把同一个 request_id 复用到第二个 step 会让 AI_CHAT_UID 外键串数据。
占位符 @request_id 出现在 <api url> / <api parameters> / <sql> 体里都会被替换为该 UUID 字符串；下游 JSP / Servlet 收到 URL 后再做解析。

错误用法举例（禁止）：

<!-- 错误：自定义前缀 + 时间戳，破坏了 AI_UID 的唯一性假设 -->
url="@EWA.HOST_BASE/...?p_request_id=req_@timestamp_@userid"

<!-- 错误：nanoId / snowflake，虽然唯一但格式不是 UUID，下游 SQL like 'uuid%' 等隐式约束会失效 -->
url="@EWA.HOST_BASE/...?p_request_id=@nanoid"

<!-- 正确：直接传 @request_id，由调用方保证注入的是 UUID -->
url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id"

运行时占位符（`@EWA.*` 与请求参数）

框架在解析 Mode XML 时，会把所有 @xxx 形式的占位符替换为运行期值（定义见 emp-script 框架的 RequestValue 常量）。两类占位符：

系统内置 `@EWA.*` 占位符

由框架在每次请求时填入，与业务无关。常用于让 LLM「知道当前日期 / 主机地址 / 路径」：

占位符	含义	示例值
`@EWA.DATE.YEAR`	当前年	`2026`
`@EWA.DATE.MONTH`	当前月（1-12）	`6`
`@EWA.DATE.DAY`	当前日	`22`
`@EWA.DATE.HOUR`	当前小时（24h）	`14`
`@EWA.DATE.MINUTE`	当前分钟	`37`
`@EWA.DATE.SECOND`	当前秒	`45`
`@EWA.DATE.TIME`	`HH:MM:SS`	`14:37:45`
`@EWA.DATE.STR`	`YYYY-MM-DD` 短日期	`2026-06-22`
`@EWA.DATE.STR1` / `@EWA.DATETIME.STR`	`YYYY-MM-DD HH:MM:SS`	`2026-06-22 14:37:45`
`@EWA.DATE.SEASON`	当前季度	`2`
`@EWA.HOST` / `@EWA.HTTP`	站点完整 URL	`https://www.gdxsoft.com`
`@EWA.HOST_PROTOCOL`	协议	`https`
`@EWA.HOST_PORT`	端口	`443`
`@EWA.HOST_CONTEXT`	项目 contextPath	`/users`
`@EWA.HOST_BASE`	`protocol://host:port/context`	`https://www.gdxsoft.com/users`
`@EWA.CP`	contextPath（不带 host）	`/users`
`@EWA.CPF`	当前 servlet 路径	`/users/userinfo.jsp`
`@EWA.CPF_ALL`	servlet 路径 + 查询串	`/users/userinfo.jsp?user_id=1`
`@EWA_QUERY` / `@EWA_QUERY_ALL`	查询串（不含 / 含 EWA 系统参数）	`user_id=1&type=2`

来源：emp-script/src/main/java/com/gdxsoft/easyweb/script/RequestValue.java:80-211。

典型用法：

<!-- 在 system prompt 中告诉 LLM 当前日期，避免「明天指哪天」的歧义 -->
<prompt name="init_prompt" role="system">
    <![CDATA[你是 GYAP 旅游 AI 行程规划专家。当前日期：@EWA.DATE.STR
用户提到「明天」「下周三」时必须基于此日期换算为 YYYY-MM-DD，禁止再反问。]]>
</prompt>

<!-- 在 <api url> 中拼接宿主地址，确保部署到不同环境都正确 -->
<api name="getservicesapi" url="@EWA.HOST_BASE/back_admin/ai/get_services.jsp?request_id=@request_id" ... />

<!-- 在 <complete test="..."> 中按当前日期判断是否触发 -->
<complete test="@EWA.DATE.MONTH = 12 and @fullText like '%春节%'">...</complete>

请求参数占位符（`@xxx` 取自请求）

任何来自 URL 参数、RequestValue、上游 LLM 抽取的参数都可以用 @name 引用：

上下文	替换时机	典型示例
`<api url="...">`	调用 API 前	`url="@EWA.HOST_BASE/back_admin/ai/get_parameters.jsp?p_request_id=@request_id&ai_provider=@ai_provider&ai_model=@ai_model"`
`<api parameters="...">`	同上	`parameters="ENQ_ID=@enq_id&EWA_AJAX=JSON_AI_PROMPT"`
`<api><form><field value="...">`	同上	`<field name="q" value="@text" />`
`<api><headers><header value="...">`	同上	`<header name="x-uid" value="@user_id" />`
`<sql>...</sql>`	执行 SQL 前	`where ai_id = @ai_id`
`<prompt><![CDATA[...]]>`	不替换——按字面量发给 LLM	见下方注意

占位符替换的常见坑

@ 前缀必须紧贴变量名：@ request_id（中间有空格）不会被识别。
大小写敏感：@ewa.date.str 不会匹配 EWA.DATE.STR。
未定义占位符 不会被替换，原样保留 @xxx 字符串。LLM 收到后会看到 @xxx 字面量。
嵌套占位符（@@xxx 或 @EWA.DATE.@xxx）不支持，只能单层。
@ 出现在 JSON / SQL 字面量里：<![CDATA[...]]> 中含 @ 不替换（见上），但 URL/SQL/header 里的 @ 仍按占位符处理。如果 URL 里要表示真正的「@」（如邮箱），请用 %40。

`<sqls>` — 命名 SQL

<sqls>
    <sql name="getLastResponse" description="获取最后一次AI回复">
        <![CDATA[
        select top 1 AIM_MSG as full_text
        from AI_CHAT_MSG
        where AIM_ROLE = 'assistant' and ai_id = @ai_id
        order by aim_id desc
        ]]>
    </sql>
</sqls>

name 被 sqlRef、actionSqlRef 或 paramCheck 引用。
SQL 体里 @param_name 占位符在运行时绑定，值来自 URL 参数、RequestValue，或上游 LLM 抽取出的参数。
必须用 <![CDATA[ ... ]]> 包裹，内部 < / > 安全。
支持多语句、SQL Server TOP n 等方言特有语法；在项目配置的数据库上执行。

`<actions>` — Java 代码动作

<actions>
    <action name="createEnqJny" description="创建询价单和行程及服务"
            class="pf2023.aiAction.ActionEnqJny" />
</actions>

当 <step action="..."> 完成后被调用。
类必须实现 com.gdxsoft.ai.export.IAction（execute(...)）。
actionSqlRef 先跑一条 SQL（通常取最后一条 assistant 消息），把结果（一般是 JSON 文本）传给 action，由 action 解析 JSON 后写库——这是把 LLM 输出落库的标准模式。

`<paramChecks>` — 入参校验

<paramChecks>
    <paramCheck name="people_num" des="团员人数" type="int"
                promptRule="游客人数，不含领队；从'X人''X+Y'格式中的X等表达中提取，返回整数" />
    <paramCheck name="grp_type"   des="行程类型" type="enum" sqlRef="grp_type_options"
                sqlValueField="BAS_TAG" sqlLabelField="BAS_TAG_NAME"
                promptRule="根据行程内容判断最匹配的类型" />
    <paramCheck name="departure_date" des="出发日期" type="date"
                promptRule="从用户输入中提取出发日期（YYYY-MM-DD）" />
</paramChecks>

属性	作用
`name`	存入 `AI_CHAT_PARAMS` 的键。
`des`	中文描述。
`type`	`int`、`enum`、`date`，或不填（自由文本）。
`promptRule`	当 `ChatManagerBase.saveInputParams()` 从对话上下文抽取该参数时，给 LLM 的指令。
`default`	缺失时的默认值。
`options`	`type="enum"` 时的静态枚举值，格式 `KEY1=标签1,KEY2=标签2`。与 `sqlRef` 动态枚举互斥；若同时配置，`sqlRef` 优先（SQL 失败时回退到 `options`）。
`sqlRef` + `sqlValueField` + `sqlLabelField`	`type="enum"` 时使用：从该 SQL 取候选值，强制 LLM 必须选 SQL 结果中的某项。

`<ui>` — HTML 事件

`<welcome>` — 新会话欢迎 HTML

<welcome> 在页面加载时由前端 StreamChatBot.fetchWelcome(modeName) 调用后端 stream.jsp?ui=welcome&mode=<mode> 取回，包装成 SSE 消息后渲染。完整事件流：

前端                          后端
StreamChatBot.fetchWelcome()
  → GET /back_admin/ai/stream.jsp?ui=welcome&mode=chat
                              → 解析 mode，对应 Mode 取出 <ui><welcome>
                              → SSE 事件 {ui_html: "...", ui_type: "welcome"}
  → respJson.ui_html 注入 <div class="message ui-html ui-welcome">
                       → innerHTML = ui_html

前端渲染逻辑（StreamChatBot.js:458-465）：

if (respJson.ui_html) {
    var uiMsg = document.createElement('div');
    uiMsg.className = 'message ui-html' + (respJson.ui_type ? ' ui-' + respJson.ui_type : '');
    uiMsg.innerHTML = respJson.ui_html;
    chatBox.appendChild(uiMsg);
}

ui_type 会被附加为 CSS class（ui-welcome / ui-complete），用于样式区分。

welcome HTML 可以内嵌交互按钮

由于 innerHTML 直接注入到 DOM，HTML 片段里可以含：

示例卡片：点击后调用 StreamChatBot.sendExample(this)，把卡片文本塞进输入框并自动发送（StreamChatBot.js:110-121）。
跳转链接：普通 <a href="..." target="_blank"> 直接可用。
JS 函数调用：<a onclick="StreamChatBot.xxx()"> 触发前端方法（如导出、刷新等）。

示例（旅游行程 mode 的真实写法）：

<welcome><![CDATA[<div class="welcome-banner">
<div class="welcome-header">
<h3>✈️ 欢迎使用 GYAP 旅游 AI 助手</h3>
<p>告诉我您的旅行计划，我可以帮您规划行程...</p>
</div>
<div class="welcome-examples">
<p class="examples-title">💡 试试这些示例：</p>
<div class="example-cards">
<div class="example-card" onclick="StreamChatBot.sendExample(this)">北京出发-美东名校参访12天游学，12月20日出发，20+2</div>
<div class="example-card" onclick="StreamChatBot.sendExample(this)">香港国际夏令营，7天，港大嘉道理中心，30+3</div>
<div class="example-card" onclick="StreamChatBot.sendExample(this)">中秋八达岭长城1日自由行，公交/地铁，3人</div>
</div>
</div>
</div>]]></welcome>

要点：

sendExample(this) 中的 this 是被点击的 DOM 元素；前端会取 card.textContent 作为输入文本（StreamChatBot.js:114），所以示例文字必须直接写在卡片元素的文本里，不能藏在子节点。
多个示例卡用同一函数 sendExample 即可，无需为每张卡片写不同 JS。
注意 CDATA 里 onclick 的引号是合法的 XML 属性引号，不需要转义。

`<complete test="...">` — 响应完成后追加的 HTML

<complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[<div class="complete-banner">
<p>行程规划完成！您可以创建团或导出为以下格式：</p>
<p class="export-links">
<a href="@ewa.cp/back_admin/ai/create_enq_jny.jsp?_ui=1&amp;opengrp=1&request_id=@request_id" target="_blank">创建团</a>
<a onclick="StreamChatBot.exportItinerary('pdf')">PDF</a>
<a onclick="StreamChatBot.exportItinerary('excel')">Excel</a>
<a onclick="StreamChatBot.exportItinerary('html')">HTML</a>
<a onclick="StreamChatBot.exportItinerary('word')">Word</a>
</p>
</div>]]></complete>

完整的事件流：

主响应结束（LLM 输出 <day>...</day>...</prices> 后）
                          → 后端评估 complete.test
                          → 命中则作为 SSE 事件追加 {ui_html, ui_type: "complete"}
前端                      → 渲染为 <div class="message ui-html ui-complete">

<complete> HTML 通常用来提供「后续操作」入口：

导出按钮：StreamChatBot.exportItinerary('pdf') 等触发 create.jsp?request_id=<id>&export_type=<type>（StreamChatBot.js:127-145），成功后 window.open(url) 下载文件。
创建团 / 跳转后台：普通 <a href="..." target="_blank">。
继续调整提示：调用 sendExample 或跳转到其它 mode。

前后端约定一览

后端（Mode XML）	前端（StreamChatBot.js）
`<ui><welcome>` 内的 HTML	`respJson.ui_html` → 渲染成 `<div class="message ui-html ui-welcome">`
`<ui><complete test>` HTML	同样渲染，CSS class 加 `ui-complete`
示例卡片 `onclick="StreamChatBot.sendExample(this)"`	取卡片文本塞输入框 + 触发发送
导出按钮 `onclick="StreamChatBot.exportItinerary('pdf')"`	GET `create.jsp?request_id=...&export_type=...`，成功后 `window.open(url)`
`test` 属性里引用 `@fullText` / `@request_id`	由后端评估，前端无感

完整骨架

<ui>
    <welcome><![CDATA[... 示例卡片 + 跳转链接 ...]]></welcome>
    <complete test="@fullText like '%&lt;day&gt;%'"><![CDATA[... 创建团 / 导出按钮 ...]]></complete>
</ui>

输出自定义标签（用户语义锚点）

要点：

完全由 mode 作者决定：每条 mode 的 system prompt 里写「请把 X 包在 <xxx> 标签里输出」，抽取端就认 <xxx>。换一条 mode 可以定义完全不同的标签集。
不属于固定词汇：schema 不校验标签存在性、闭合性、嵌套关系。LLM 漏写、错写都属于业务问题，不是解析错误。
承载内容由 mode 决定：可以是行程项、表格行、客户线索字段、价格条目、表格、JSON-like 块——任何能被结构化抽取的内容。
配套的后端 action 必须自己写：每个 mode 想要落库，就要写一个 IAction 实现，负责 Jsoup.parse(...) → select(...) → 写表。schema 不会替你生成。

跨领域例子（同一 schema，不同 mode 各自的标签）

领域 / mode	自定义标签	用途
旅游行程（travelagent `chat` mode）	`<gn>` 项目名、`<day>` 单日、`<rq>` 日期、`<cid>` 城市 ID、`<enj>` 行程、`<id>` 服务 ID、`<num>` 数量、`<sersday>` 当日服务汇总、`<prices>` 价格表	抽取后写入 `GRP_MAIN` / `ENQ_MAIN` / `ENQ_JNY` / `ENQ_JNY_SER`
CRM 线索（pf2023 `crmLead` mode）	`<lead>` 单条线索（含 `<company>`/`<contact>`/`<phone>`/`<email>` 等嵌套字段）	抽取后写入 CRM 线索表
机票查询（pf2023 `getairs` mode）	`<flight>` 单航班（含 `<no>`/`<dep>`/`<arr>`/`<duration>` 等）	落库到航班字典或前端直接展示
景点 / 机场信息（pf2023 `getScenicInfo` / `getAirPortInfo` mode）	`<scenic>` / `<airport>` 顶层标签	落库到景点 / 机场字典

后端实现参考：pf2023/aiAction/ActionEnqJny.java:43-105（行程）、ActionCrmLead.java（线索），都用 jsoup 解析。

后端推荐用 jsoup 抽取（通用技术）

import org.jsoup.Jsoup;
import org.jsoup.nodes.Document;
import org.jsoup.nodes.Element;
import org.jsoup.select.Elements;

// 1. 解析整段 LLM 输出为 Document（HTML 片段模式）
String llmOutput = "...完整的 <day>...</day> 输出...";
Document doc = Jsoup.parse(llmOutput);

// 2. 顶层标签：selectFirst 取第一个
String grpName = doc.selectFirst("gn") != null
        ? doc.selectFirst("gn").text().trim()
        : "";

// 3. 列表标签：select 取全部后遍历
Elements items = doc.select("lead");          // 例：抽 CRM 线索
for (Element item : items) {
    String company = item.selectFirst("company").text().trim();
    String phone   = item.selectFirst("phone").text().trim();
    String email   = item.selectFirst("email").text().trim();
    // ...写库
}

// 4. 嵌套结构：父标签内 selectFirst("child") 取子标签
Elements days = doc.select("day");
for (Element day : days) {
    String date    = day.selectFirst("rq").text().trim();
    Element enj    = day.selectFirst("enj");
    String content = enj != null ? enj.text().trim() : "";

    // 5. 同级成对标签：用 Elements 数组下标配对
    Elements idTags  = day.select("id");
    Elements numTags = day.select("num");
    for (int i = 0; i < idTags.size(); i++) {
        String serConnId = idTags.get(i).text();
        String num = numTags.size() > i ? numTags.get(i).text() : "1";
        // ...写服务清单行
    }
}

jsoup 的通用优点（与业务无关）：

不依赖严格的 XML 闭合顺序，LLM 即使混入 Markdown、表情、换行、注释也能正确解析。
select("xxx") / selectFirst("xxx") 与 CSS 选择器一致，写起来直观。
Element.text() 自动去掉标签内残留的 HTML 实体和多余空白。
对自定义标签完全透明——只要 LLM 输出了对应的尖括号标签，jsoup 就能解析。

不要用 javax.xml.parsers.DocumentBuilder 之类的标准 XML 解析器：LLM 输出常含未转义的 <、>、HTML 实体、表情符号、注释等，会触发 SAXException；用 jsoup 的 HTML 解析模式可以容忍。

给 LLM 立规则的通用原则（具体规则随 mode 而定）

每个 mode 的 system prompt 都要给 LLM 立「自定义标签输出规则」，下面几条是跨领域通用的：

必填锚点要写明：哪些字段如果缺失就视为生成失败（例如行程 mode 的 <rq> 日期、CRM mode 的 <phone>），让 LLM 在缺数据时直接报错而不是跳过。
ID 类标签必须字面存在于上游数据：禁止编造。如服务 ID 必须来自提供的服务清单，景点 ID 必须来自提供的景点字典。
数量、金额配对字段：<id> 与 <num>、<item> 与 <price> 等成对出现的标签，提示 LLM 它们必须严格对齐。
完整性：列表型标签（<day>、<lead>、<flight>）必须一次输出全部条目，不允许中途停止。
不暴露内部字段：所有 ID、原始 JSON、数据库字段名都应包裹在标签里，标签外的中文叙述里只展示人类可读名称。
结束标记：列表结束后追加一个 <prices> / <summary> / <total> 之类的「收尾锚点」，让后端可以判定响应完整。

具体到某条 mode 时，把以上通用原则翻译成该 mode 的业务规则，写进对应的 system prompt。

撰写清单

新增或修改 mode 时：

设定 <mode> 的 temperature（抽取类 0.1，对话类 0.7）；需要 JSON 输出时在 <mode> 上设 responseFormat="json_object"（注意：step 级别不支持覆盖该属性）。
第一个 step 通常是 <step validateParams="..." stream="false" innerCall="true">，用来在主流程前把参数补齐。
主 step 用 stream="true"，包含：
- 一段 <prompt role="system"> 设定人设 + 全部规则（占 prompt 主体）。
- 一个 apisCheck="true" prompt，列出 LLM 可调的工具。
- 每个动态数据源一条 <prompt role="user" api="..." 或 sqlRef="...">。
- 一条 <prompt role="user" prefix="..."> 描述输出格式（XML 自定义标签）。
可选的末 step：stream="false" action="..." actionSqlRef="getLastResponse"，用来落库。
所有 api="..." / sqlRef="..." / action="..." 都要在对应块里声明。
在 step validateParams 中引用的每个参数，都要在 <paramChecks> 里定义。
配 <ui><welcome>，必要时加 <ui><complete test="...">。
mvn -DskipTests compile 仅校验 Java 编译，XML 解析在运行时进行，写完务必在单元测试里调用 Modes.loadModes(xml) 自检。

常见坑

CDATA 不能写在属性里 — 含 < > 的内容必须放元素体（<![CDATA[...]]>），不能放属性。
@request_id 拼写 — 后端 JSP 有的用 p_request_id（带 p_ 前缀），有的用 @request_id；与 JSP 一一对齐。
Step 顺序 — 由文档顺序决定，与 name 无关。step1 校验会先于 step 生成执行。
apisCheck 提示混入散文 — LLM 可能忽略「仅输出 JSON」的规则。system prompt 里也要强调，工具列表尽量短。
thinking="true" + responseFormat="json_object" — 部分 provider 的 reasoning token 会破坏 JSON 解析，严格抽取 step 务必 thinking="false"。
responseFormat 只能设在 <mode> 上 — <step> 不支持 responseFormat 属性，写了也会被忽略。需要 JSON 输出的场景（如参数抽取 step），请在 <mode> 级别设置。
<id> 只出现在 <sersday> 而未出现在 <enj> — 价格表无法绑定数量；每个付费服务必须至少挂一条 <enj> 日程行。
POST <api> 没写 <form> 也没写 <body> — 请求体为空。query 风格的 POST 用 parameters="..."；JSON body 用 <body><![CDATA[...]]></body>。
maxHistoryTokensK 过低 — 多轮中途截断，LLM 丢上下文，关注 WARN 日志。
<prompt> 内容里写 @xxx — @ 前缀的占位符仅在 <sql> / <api url> / <api parameters> 中会替换；写在 prompt 的 <![CDATA[...]]> 文本里只是普通字符。需要引用请求参数请用 prompt 模板或运行时注入。
request_id 不是 UUID — AI_CHAT.AI_UID 列与所有外键（AI_CHAT_MSG.AI_ID、AI_CHAT_PARAMS.AI_ID）隐含假设 request_id 是标准 UUID。调用方必须用 UUID.randomUUID().toString() 生成，框架内部已遵循此约定（AiChatParamsManager.java:278）。任何自造 ID 都会导致 AI_UID 唯一索引冲突或多会话串数据。详见上文「request_id 必须是 UUID 格式」一节。
用标准 XML 解析器抽自定义标签 — LLM 输出不是标准 XML（混入 Markdown、未转义字符、表情、HTML 实体），DocumentBuilder / SAXParser 会抛异常。统一用 jsoup HTML 模式解析，详见上文「后端推荐用 jsoup 抽取」。

ai-mode-xml-authoring

More from this repository

More from this repository

AI Mode XML 撰写参考

文件骨架

<mode> 属性

<step> 属性

<prompt> 的 4 种数据源

函数调用 prompt 模板

<apis> — 外部 HTTP 工具

request_id 必须是 UUID 格式

运行时占位符（@EWA.* 与请求参数）

系统内置 @EWA.* 占位符

请求参数占位符（@xxx 取自请求）

占位符替换的常见坑

<sqls> — 命名 SQL

<actions> — Java 代码动作

<paramChecks> — 入参校验

<ui> — HTML 事件

<welcome> — 新会话欢迎 HTML

welcome HTML 可以内嵌交互按钮

<complete test="..."> — 响应完成后追加的 HTML

前后端约定一览

完整骨架

输出自定义标签（用户语义锚点）

跨领域例子（同一 schema，不同 mode 各自的标签）

后端推荐用 jsoup 抽取（通用技术）

给 LLM 立规则的通用原则（具体规则随 mode 而定）

撰写清单

常见坑

AI Mode XML 撰写参考

文件骨架

<mode> 属性

<step> 属性

<prompt> 的 4 种数据源

函数调用 prompt 模板

<apis> — 外部 HTTP 工具

request_id 必须是 UUID 格式

运行时占位符（@EWA.* 与请求参数）

系统内置 @EWA.* 占位符

请求参数占位符（@xxx 取自请求）

占位符替换的常见坑

<sqls> — 命名 SQL

<actions> — Java 代码动作

<paramChecks> — 入参校验

<ui> — HTML 事件

<welcome> — 新会话欢迎 HTML

welcome HTML 可以内嵌交互按钮

<complete test="..."> — 响应完成后追加的 HTML

前后端约定一览

完整骨架

输出自定义标签（用户语义锚点）

跨领域例子（同一 schema，不同 mode 各自的标签）

后端推荐用 jsoup 抽取（通用技术）

给 LLM 立规则的通用原则（具体规则随 mode 而定）

撰写清单

常见坑

`<mode>` 属性

`<step>` 属性

`<prompt>` 的 4 种数据源

`<apis>` — 外部 HTTP 工具

`request_id` 必须是 UUID 格式

运行时占位符（`@EWA.*` 与请求参数）

系统内置 `@EWA.*` 占位符

请求参数占位符（`@xxx` 取自请求）

`<sqls>` — 命名 SQL

`<actions>` — Java 代码动作

`<paramChecks>` — 入参校验

`<ui>` — HTML 事件

`<welcome>` — 新会话欢迎 HTML

`<complete test="...">` — 响应完成后追加的 HTML

`<mode>` 属性

`<step>` 属性

`<prompt>` 的 4 种数据源

`<apis>` — 外部 HTTP 工具

`request_id` 必须是 UUID 格式

运行时占位符（`@EWA.*` 与请求参数）

系统内置 `@EWA.*` 占位符

请求参数占位符（`@xxx` 取自请求）

`<sqls>` — 命名 SQL

`<actions>` — Java 代码动作

`<paramChecks>` — 入参校验

`<ui>` — HTML 事件

`<welcome>` — 新会话欢迎 HTML

`<complete test="...">` — 响应完成后追加的 HTML