ra3-lua4-syntax-http

name	ra3-lua4-syntax-http
description	Validates Red Alert 3 map Lua 4.0 script syntax and retrieves error details by calling the Ra3MapUtils local HTTP API. Use when checking .lua map scripts, Lua4 syntax, RA3 triggers/scripts, or when the user asks to verify Lua4 against the running Ra3MapUtils service.

RA3 Lua4 语法校验（HTTP）

前提

• Ra3MapUtils（地编伴侣）已启动，内置 Kestrel 监听 http://127.0.0.1:30033。
• 若连接失败，提示用户先启动 Ra3MapUtils。

接口概览

用途	方法	路径
校验源码字符串	POST	/api/lua4/syntax/code
校验磁盘上的文件	POST	/api/lua4/syntax/file

完整 URL：http://127.0.0.1:30033 + 上表路径。

请求体（JSON，camelCase）

按代码校验

{ "code": "<完整 Lua4 源码>" }

按文件校验

{
  "filePath": "相对或绝对路径",
  "workingDirectory": "可选；若提供则与 filePath 拼接"
}

• 仅 filePath 时：可为绝对路径。
• 提供 workingDirectory 时：须为已存在的目录；最终路径为 Path.Combine(workingDirectory, filePath)。
• 文件不存在时接口返回业务错误（见下），code 为 1003，message 含「文件不存在」等。

响应包装（ApiResponse）

根对象字段：

• code（int）：1000 = 成功；1003 = 参数非法；1001 = 未知错误。
• message（string）：如 success 或错误说明。
• data：成功时为语法结果对象；失败时可能缺省或为 null。

语法结果（data，成功时）

来自 SyntaxCheckResult，常见字段：

• isValid（bool）：是否通过语法检查。
• errorMessage（string）：未通过时的错误信息（可能多行）。
• filePath（string）：按文件校验时可能带有被检路径。

向用户汇报时：先说明 isValid，若不通过则引用 errorMessage（必要时附 filePath）。

代理执行方式

1. 若用户给出的是工作区内的文件路径：可读文件内容后调用 /api/lua4/syntax/code（避免服务端路径与 Cursor 环境不一致）；或在与 Ra3MapUtils 同一台机器且路径可达时，用 /api/lua4/syntax/file 传绝对路径。
2. 使用终端 curl 或等效工具发 POST，Content-Type: application/json。
3. 解析返回 JSON，按 code 与 data.isValid / data.errorMessage 回答用户。

curl 示例

按源码（PowerShell 需注意引号转义，可将 JSON 写入临时文件后 -d @file.json）：

curl -s -X POST "http://127.0.0.1:30033/api/lua4/syntax/code" ^
  -H "Content-Type: application/json" ^
  -d "{\"code\":\"local a = 1\"}"

按文件（绝对路径示例）：

curl -s -X POST "http://127.0.0.1:30033/api/lua4/syntax/file" ^
  -H "Content-Type: application/json" ^
  -d "{\"filePath\":\"C:/path/to/script.lua\"}"