lovewc3
v1.0.32
Published
魔兽争霸3 地图开发工具 - CLI + RAG 文档查询 + Cursor MCP 集成
Maintainers
Readme
Lovewc3 CLI
当前 npm 最新版本:
1.0.30
🚀 npm 安装(推荐)
# 1. 全局安装
npm install -g lovewc3
# 2. 初始化环境(首次使用必须执行)
lovewc3 initlovewc3 init 会自动完成以下步骤:
- 复制 h-lua 文档到
~/.lovewc3/h-lua-main/(文档已内置于 npm 包) - 构建 RAG 向量索引到
~/.lovewc3/rag_store/ - 配置 Cursor MCP 到
~/.cursor/mcp.json
注意:构建索引需要 SiliconFlow API Key,请在
~/.lovewc3/.env中配置:SILICONFLOW_API_KEY=your_api_key_here获取地址:https://cloud.siliconflow.cn/
初始化完成后,重启 Cursor 即可在 AI 对话中使用 h-lua 文档查询功能。
开发者快速启动
- 配置环境变量:复制
.env.example为.env,填入SILICONFLOW_API_KEY - 安装依赖:
npm install - 安装 Python 依赖:
pip install -r tools/rag/requirements.txt和pip install -r tools/mcp/requirements.txt - 安装 Go 1.20+(CLI 会在
/run、/editor中使用go run生成 h-lua-slk;如go不在 PATH,可设置GO_BIN) - 在支持 TTY Raw Mode 的终端中运行:
npm run dev- 如必须在不支持 Raw Mode 的终端里运行,先执行:
set INK_NO_RAW_MODE=1 && npm run dev
- 如必须在不支持 Raw Mode 的终端里运行,先执行:
- CLI 启动时会自动启动 RAG 和 MCP 服务
常用指令
- 直接用魔兽客户端加载地图(参考
share/script/ydwe_on_test.lua的构造逻辑)"<War3目录>/war3.exe" -loadfile "<地图路径>.w3x" [其他参数]
w2l是一个强大的工具,可以把w3x格式的地图解压缩(lni)为文件夹,直接用IDE编写脚本,也可以同时通过obj把lni格式的地图文件夹重新打包为w3x格式的地图
通过 KKWE 编辑器打开地图(参考
share/script/util.lua的sys.restart)"<KKWE目录>/kkwe.exe" -loadfile "<地图路径>.w3x"将lni格式的转换为 OBJ(参考
w3x2lni/script/locale/zhCN/raw.lng的 w2l 命令说明)w2l obj "<地图路径>" ["<输出路径>"]将地图转换为 LNI 以便文本化管理(同上)
w2l lni "<地图路径>" ["<输出路径>"]
Structure
src/utils/warcraftLauncher.ts:封装通过 YDWEConfig.exe 启动 Warcraft III 的逻辑(支持 JAPI 和 Lua),从 KKWE 路径推算bin/YDWEConfig.exe位置。src/utils/warcraftWatcher.ts:使用 PowerShell 轮询方式监听war3.exe进程,用于在游戏退出前阻塞 CLI。src/utils/ragService.ts:负责启动/复用 RAG(FastAPI)与 MCP(HTTP)服务。src/utils/sdkRunner.ts:封装go run ./h-lua-main/depend/sdk/slkgen,在w2l obj前生成h-lua-slk/与HSLK_*数据。src/utils/ragQuery.ts:封装对 MCP 服务的 HTTP 请求,提供queryRag(纯检索)和askWithRag(RAG+LLM)两种模式。src/utils/llmService.ts:封装 SiliconFlow Chat Completions API,支持流式/非流式调用,使用deepseek-ai/DeepSeek-V3.1-Terminus模型。src/components/ConversationPreview.tsx:展示user:/love:对话历史,自动适应终端高度计算可见行数,支持 PageUp/PageDown 滚动查看历史记录。src/utils/viewerServer.ts:HTTP 服务器模块,为 BLP/MDX 查看器提供静态文件服务和文件读取 API(端口 8910)。src/utils/electronViewer.ts:封装拉起 Electron 窗口打开 BLP/MDX 查看器页面(复用 viewerServer URL),Windows 下通过--分隔参数避免 Electron 误解析--url/--title造成闪退。src/utils/assets/png2blpRuntime.ts:图片(png/jpg/jpeg)→ BLP1(含 DIS 灰度图标)转换运行时;首次使用自动准备 Python+Pillow(Windows 无 Python 时自动下载到~/.lovewc3/runtime/python/)。src/components/AssetManager.tsx:资源管理器 UI(支持在面板内拖入图片:优先导入到项目resource/ReplaceableTextures/...并生成正常.blp + DIS*.blp;无项目时回退导入全局库)。tools/png2blp/*.py:png2blp_cli.py(图像→BLP1)与image_to_grayscale.py(生成 DIS 灰度源图),由png2blpRuntime调用。src/viewers/blp.html:BLP 纹理查看器页面,显示图像信息和所有 Mipmap 级别的预览。src/viewers/mdx.html:MDX 3D 模型查看器页面,使用 WebGL 渲染,支持动画、队伍颜色、相机控制。src/viewers/electron-viewer.cjs:Electron 主进程入口脚本,创建/复用BrowserWindow并加载查看器 URL(单例锁避免多开;对 cache/userData 做了可写目录兼容处理)。h-lua-main/docs/HSLK.md:HSLK 物编系统指南(构建期/运行期 API、示例、注意事项)。
Functions
launchWarcraft(kkwePath, mapPath, options?):从 KKWE 路径推算 YDWEConfig.exe 位置,使用-launchwar3 -loadfile参数启动 Warcraft III(支持 JAPI/Lua)。getYdweConfigPath(kkwePath):将 KKWE 路径(如D:\KKWEPlugin\KKWE.exe)转换为 YDWEConfig.exe 路径(如D:\KKWEPlugin\bin\YDWEConfig.exe)。watchWarcraftProcess(options?):检测war3.exe是否启动并在其退出前保持 Promise 阻塞,同时对"检测到/退出"事件提供回调。chatCompletion(messages, config?):调用 SiliconFlow Chat API(非流式),返回完整回答。支持enableThinking切换思考模式。chatCompletionStream(messages, config?):调用 SiliconFlow Chat API(流式),返回 AsyncGenerator 逐步产出内容。queryRag(question, topK?, candidates?):纯检索模式,返回匹配的文档 chunk 列表。askWithRag(question, options?):RAG+LLM 模式,检索文档后调用 LLM 生成回答,返回答案及参考来源。ensureHslkArtifacts(mapFolder, projectName):检查同名目录并调用 Go sdk 的slkgen生成h-lua-slk/slk.lua、HSLK_*全局数据;若 Go 不在 PATH,可通过GO_BIN指定。ensureViewerServer():启动 BLP/MDX 查看器 HTTP 服务器(端口 8910),提供静态文件服务和文件读取 API。getViewerUrl(type, filePath):生成查看器 URL,type为'blp'或'mdx',返回带文件路径参数的完整 URL。openViewerWindow(url, options?):启动 Electron 并打开新窗口加载查看器 URL(非阻塞)。ensurePng2BlpRuntime():确保本机具备可用的 Python + Pillow(优先用系统 Python;Windows 下缺失会自动下载并配置到~/.lovewc3/runtime/python/)。convertImageToIconBlps(inputImagePath, options?):将png/jpg/jpeg转为两张 BLP:<name>.blp与DIS<name>.blp(灰度禁用图标)。
HSLK 物编系统
概述
HSLK 是 h-lua 附带的物编(SLK/INI)生成系统,采用“构建期生成 + 运行期访问”的两段式流程:
| 阶段 | 执行时机 | 执行者 | 作用 |
| --- | --- | --- | --- |
| 构建期 | npm run build、/run、/editor 触发的 slkgen | Go + gopher-lua | 执行 hslk_* API,生成 hslk/*.ini、HSLK_* 数据 |
| 运行期 | Warcraft III Lua 启动后 | War3 Lua 引擎 | 通过 hslk.* API 查询/使用物编数据 |
项目根目录下若存在 hslk/*.lua,会在 slkgen 阶段自动装载;生成结果位于 map/h-lua-slk/ 与 map/HSLK_*(由 CLI 注入地图目录)。
构建期 API(项目/hslk/*.lua 内使用)
常用函数均定义在 h-lua-main/depend/sdk/lib/embeds/slk/*.lua,以下列出最常见条目(完整字段可参考 h-lua-main/depend/sdk/lib/embeds/slk/pilot.lua):
hslk_ability(options):基于_parent技能模板批量覆写字段,可配置levels、DataA/DataB、热键、图标等。返回{ _id = "Axxx" }自动分配的物编 ID。hslk_ability_empty(options):用于创建隐藏属性技能(默认继承Aamk),常搭配属性系统。hslk_unit(options):自定义普通单位,支持血量、攻防、移动、模型、音效等字段。hslk_hero(options):英雄模板,支持三围初始值与成长、主属性、技能列表等;默认_parent = "Hpal"。hslk_item(options):物品模板,可设置class/goldcost/uses/perishable、内嵌_attr()属性加成。hslk_buff(options)、hslk_upgrade(options)、hslk_destructable(options)、hslk_doodad(options):分别对应 Buff、科技、可破坏物、装饰物。
构建期脚本全部放在
hslk/目录,修改后需重新触发slkgen(执行/run、/editor或手动node src/utils/sdkRunner.ts)才能生成最新数据。
运行期 API(游戏内 Lua 使用)
运行期 hslk.* 接口来自 require "h-lua-slk.slk",允许按名称或 ID 查询数据:
hslk.n2i(name):名称 → 物编 ID(若重名返回数组);常搭配type(id) == "table"判断。hslk.i2v(id, ...fields):按 ID 读取数据;hslk.i2v("H001")返回整棵对象,或hslk.i2v("H001", "slk", "Primary")直取字段。hslk.n2v(name, ...fields):名称 → 数据,内部等价于n2i + i2v。hslk.classIds(classOrList):按类别收集 ID,如hslk.classIds("item")。hslk.typeIds(type):按类型(unit/hero/item 等)收集 ID。hslk.misc(section?, key?):读取平衡常数,hslk.misc("Misc", "HeroExpRange")获取经验设定,hslk.misc()返回全集。
示例
构建期(hslk/abilities.lua)
local summon_phoenix = hslk_ability({
_parent = "AHwe",
Name = "召唤凤凰群",
Hotkey = "W",
levels = 3,
UnitID = { [1]="hphx", [2]="hphx", [3]="hphx" },
DataA = { [1]=5, [2]=5, [3]=5 },
Cost = { [1]=200, [2]=175, [3]=150 },
Cool = { [1]=30, [2]=25, [3]=20 },
})
print("技能ID:", summon_phoenix._id)运行期(map/main.lua)
local skillId = hslk.n2i("召唤凤凰群")
if type(skillId) == "table" then
skillId = skillId[1]
end
if skillId then
local hero = cj.CreateUnit(cj.Player(0), c2i("Hblm"), 0, 0, 270)
cj.UnitAddAbility(hero, c2i(skillId))
cj.SetUnitAbilityLevel(hero, c2i(skillId), 3)
end注意事项
hslk/*.lua仅在构建阶段执行;修改后需重新运行/run、/editor或npm run build。- 物编 ID 由 HSLK 自动分配,通过返回值的
._id获取;若需固定 ID,可在 options 里显式传_id="A000"。 - 运行期 API 仅在 Warcraft III Lua 环境中可用,确保
require "h-lua-slk.slk"成功。 HSLK_MISC/I2V/N2I等全局表位于map/h-lua-slk/下,若 Go 未正确安装会导致缺失。
FAQ
- 为什么
/run或/editor会提示缺少 Go?
这两个指令会在w2l obj前执行go run ./h-lua-main/depend/sdk/slkgen,触发 sdk 的War3()/Lua()流程生成h-lua-slk以及HSLK_MISC/I2V/N2I等全局数据。请安装 Go 1.20+,或通过GO_BIN指定可执行路径。 - 能否直接在 npm 中执行 Go 命令?
可以,CLI 自身会在需要时调用go run。如果要手动编译 sdk,也可在项目中添加 npm 脚本或直接运行cd h-lua-main/depend/sdk && go build -ldflags "-s -w",然后按需调用生成的可执行文件。
输入增强功能
- ↑/↓ 历史输入:在输入框中按 ↑/↓ 可回溯/前进历史输入内容;在
cmd模式且存在命令候选时,↑/↓ 仍用于候选切换(不触发历史回溯)。历史记录会持久化到$LOVEWC3_HOME/input_history.json(默认~/.lovewc3/input_history.json),重启 CLI 仍可找回。 - Ctrl+V 粘贴:支持从剪贴板粘贴文本到输入框。在终端中按 Ctrl+V 即可将剪贴板内容插入当前光标位置。
- 拖入文件获取路径:将文件拖入终端窗口时,会自动获取文件的绝对路径。系统会自动去除路径两端的引号(Windows 终端拖入时会自动添加引号),方便直接使用。
- 例如拖入
D:\maps\demo.w3x后,输入框会显示不带引号的完整路径。 - 配合
/blp或/mdx指令,可以快速预览拖入的资源文件。
- 例如拖入
- 支持输入空格:输入框会保留输入过程中的空格(例如
hello world、或带空格的文件路径),避免出现“按空格导致光标异常/空格被吞”的问题;提交执行命令时仍会对首尾空白做统一处理。
Lovewc3 CLI 内置指令
/list:进入地图列表模式,使用 ↑/↓、Enter、Esc 选择主地图;目录为空时列表显示(空)。/refresh:立即重新扫描当前目录下的.w3x/.w3m,并刷新主地图与地图数量提示。/settings:打开设置面板配置 Warcraft III 与 KKWE 路径。/assets:打开资源管理器(Tab 切换 Project/Global,M/T 切换 Models/Textures,↑↓ 选择,Enter 预览,Esc 退出;列表过多时自动滚动;终端高度变化会自动重算可见条目数;预览窗口会自动尝试置顶)。- E 导出(Project 模式):导出 MDX 时会自动导出其引用的 BLP,并在全局库中建立依赖关系;后续从全局库导入 MDX 会自动带贴图。
- A 导入(Global 模式):导入文件/目录到全局库;支持
png/jpg/jpeg,会自动生成正常.blp + DIS*.blp并写入索引(列表仅显示正常 BLP,隐藏 DIS)。 - I 导入(Global→Project):若选择的是“图标正常 BLP”(存在 DIS 配对),会同时导入到项目
resource/ReplaceableTextures/CommandButtons/与CommandButtonsDisabled/。 - 拖拽导入(在资源管理器面板内):将
png/jpg/jpeg拖入终端窗口(资源管理器打开时)会自动触发导入;优先导入到项目图标目录并生成正常.blp + DIS*.blp,无项目时回退导入全局库。 - 绿色标注:表示该资源在“另一侧”(Project/Global)已存在,用于避免重复导出/导入。
- Textures 列表过滤:被 MDX 引用的 BLP 不再显示(只保留“纯贴图”)。
- MDX 贴图依赖解析:从 MDX 的
TEXS提取贴图路径并匹配项目内 BLP,用于tex x/y统计与导出依赖。
/editor:设置 KKWE 路径后执行。主地图为.w3x且存在同名目录时,会先执行w2l obj用目录里的最新内容覆盖主地图,再启动 KKWE 并开启监听;监听结束后立即执行w2l lni将主地图回写到同名目录。若无主地图或文件不是.w3x,则跳过自动同步流程。/editor启动WorldEditKKWE.exe后会同步阻塞:执行while ($true) { Get-Process WorldEditKKWE ... }的 PowerShell 采集脚本侦测输出,若某次获取不到进程就立即退出;10 秒内未出现任何输出则报错提示“未检测到 KKWE 输出”。监听期间仅在首次捕获输出与检测到KKWE - [时写入提示,结束后提示“KKWE 输出结束”。/run:主地图需为.w3x且存在同名目录。指令会先执行w2l obj将目录内容打包回主地图,再调用YDWEConfig.exe -launchwar3 -loadfile <主地图>启动 Warcraft III(支持 JAPI/Lua),并持续监听war3.exe进程,直至游戏关闭才解除阻塞。缺少主地图、目录或 KKWE 路径未配置时会给出错误提示。- 触发
slkgen时,Go 侧 stdout/stderr 会以[sdk] .../[sdk][ERR] ...的形式直接回显在 CLI 中,方便排查脚本错误。
- 触发
/obj:主地图需为.w3x。执行时会在同级目录查找同名文件夹(如demo.w3x->demo/),对该目录运行w2l obj并将生成的demo.w3x覆盖现有主地图。/lni:主地图存在时会调用w2l lni生成同名目录;若目录已存在会先删除再覆盖,便于以文本方式继续编辑。/init:将 h-lua 框架和 sdk 拷贝到主地图的 lni 目录中。如果 lni 目录不存在,会先自动执行/lni生成。拷贝内容包括const/、foundation/、lib/、builtIn/、sdk/目录和h-lua.lua文件到<lni>/map/目录下。/update:更新 lovewc3 到最新版本(执行npm install -g lovewc3@latest),更新完成后需重启 CLI 生效。/rebuild:更新文档并重建 RAG 索引。会先从 npm 包复制最新的 h-lua 文档到用户目录,然后重建索引。更新 lovewc3 后执行此命令即可刷新文档和索引。/rag:构建/启动 RAG 服务与 MCP Server。首次执行会自动运行tools/rag/ingest.py对h-lua文档嵌入,随后后台常驻tools/rag/server.py与tools/mcp/hlua_mcp.py,CLI 会实时输出运行日志;若服务已在运行则仅返回状态。/blp <path>:在 Electron 窗口中查看 BLP 纹理文件。会启动本地 HTTP 服务器(端口 8910),自动打开 Electron 窗口展示 BLP 图像的详细信息(尺寸、内容类型、Alpha 位数、Mipmap 层级)及所有 Mipmap 的预览。/mdx <path>:在 Electron 窗口中查看 MDX 3D 模型。使用 WebGL 渲染模型,支持鼠标拖拽旋转视角、滚轮缩放、切换动画序列、选择队伍颜色、循环播放控制等功能。- 自然语言查询:在命令行输入不以
/开头的内容时,系统会执行 RAG+LLM 流程:先检索相关文档,再调用DeepSeek-V3.2-Exp模型生成回答。回答后会附带参考来源和 Token 用量统计。 - 默认状态下,命令行上方会实时展示
user:与love:(系统回答)对话历史,高度自动适应终端大小;有新消息时自动滚动到底部,支持 PageUp/PageDown(或 Ctrl+↑/↓)上下滚动查看更早的消息。
RAG + LLM 集成
- 复制
.env.example为.env,填入SILICONFLOW_API_KEY(SiliconFlow 控制台创建),其余端口可保持默认。 - 安装 Python 依赖(建议使用
uv或pip):pip install -r tools/rag/requirements.txtpip install -r tools/mcp/requirements.txt
- 可选手动命令:
npm run rag:ingest:重新向 SiliconFlow 发送嵌入请求并刷新本地rag_store/。npm run rag:serve:仅启动 FastAPI RAG 服务(默认端口 8900)。npm run mcp:serve:单独启动 MCP Server(默认端口 8901)。
- 在 CLI 中执行
/rag后,系统会自动启动两个 HTTP 服务:- RAG 服务 (端口 8900):提供文档检索与索引刷新功能。
- MCP 服务 (端口 8901):提供标准化的 API 接口供 AI Agent 调用。
- MCP 服务提供的接口:
POST /query_docs:语义检索 +bge-reranker-v2-m3精排。POST /refresh_index:触发 RAG 服务重新索引指定文档。POST /read_document:直接获取原始 Markdown 文档内容。GET /health:健康检查。
- LLM 生成:自然语言查询会调用 SiliconFlow 的
deepseek-ai/DeepSeek-V3.2-Exp模型:- 默认关闭思考模式(
enable_thinking: false),响应更快 - 温度设为 0.3,保证回答准确性
- 最大输出 2048 tokens
- 默认关闭思考模式(
- CLI 退出时会自动停止 RAG/MCP 子进程,无需手动清理。
日志输出
- CLI 的所有系统消息与命令反馈会同步追加到根目录的
log.txt,格式为[ISO时间][角色] 内容,便于排查问题。 - 如需清空记录,可删除该文件,运行时会自动重新创建。
- 设置面板会将“打开文件选择器”“取消/失败/成功”等过程写入日志,并在 30 秒无响应时自动超时记录,文件选择器会强制置顶防止被遮挡。
War3 控制台输出抓取
- 当使用
/run启动 War3 且出现 PowerShell 控制台窗口时,可运行powershell -NoProfile -File tools/console_dump.ps1 -TargetPid <war3_pid> -MaxChars 8000抓取当前控制台缓冲(<war3_pid>可通过Get-Process war3 | Select Id获取;亦可用参数别名-Pid)。 - 该脚本通过
AttachConsole+ReadConsoleOutputCharacterW读取控制台内容,仅供调试查看 War3/KKWE 输出。
地图管理
- 启动 CLI 时会自动扫描当前目录下的
.w3x/.w3m地图,并默认选中排序后的第一张作为主地图。 - 默认界面仅保留命令输入框和状态栏:状态栏在同一行展示
main map、KKWE 两条信息(未设置时提示/settings),若终端宽度不足会自动换行。 - 命令行具备
default/cmd状态机:输入/自动进入 cmd 状态并列出可用指令,可用 ↑/↓ 切换候选;Tab 会把候选指令补全到输入框并将光标移动到文本末尾,Enter 则直接执行当前高亮候选(即使输入只写了前缀),当输入已完全匹配某个指令(如/RUN)时,候选会坍缩为唯一一条该指令;执行或 Esc 后恢复 default 状态。 - 在 cmd 状态下按一次 Esc 会立即回到 default 并清空当前指令;快速连续按两次 Esc(双击)会在任意状态下清空输入框内容。
- 指令候选区域一次最多显示 5 条记录,当候选超过 5 条时会围绕当前光标滚动视窗,并在列表下方展示上下箭头提示,其中可继续向下滚动时下箭头会高亮。
- 输入框 placeholder 固定为
waiting for your command...,无需额外提示文字。 - 当终端高度过小时,界面会自动收缩(必要时隐藏对话预览),以保证命令输入框不被候选列表挤压变形。
设置面板
- 执行
/settings后,界面切换到设置面板,提供 "KKWE" 选项,可用 Enter 选择、Esc 退出。 - Enter 会调起系统文件资源管理器选择 KKWE 可执行文件(例如
KKWE.exe),结果立即保存并写入~/.lovewc3/settings.json,同时同步到状态栏展示。 /run指令会根据 KKWE 路径自动推算bin/YDWEConfig.exe位置来启动游戏,支持 JAPI 和 Lua。
地图列表模式
- 执行
/list后,命令状态栏隐藏,仅显示地图列表;使用 ↑/↓、Enter、Esc 操作主地图。 - 若不存在
.w3x/.w3m文件,则列表显示(空),仍可通过 Esc 返回默认界面。
w2l 转换输出
/lni与/obj指令会直接调用内置(或同目录)w2l.exe。执行前会删除同名目录(lni 输出)或同名文件(w3x 输出),确保结果完全覆盖旧内容。/editor自动串联 obj → 编辑器 → lni,整个流程都会调用 w2l 保证主地图文件与同名目录保持最新。
ASCII Logo
程序启动时,会在左上角用蓝色圆角框包裹下方 ASCII Logo,并依次显示 READY TO WORK!!!(冰青 → 深海蓝渐变)与 press enter to continue... 提示;按 Enter 进入主界面:
██╗ ██████╗ ██╗ ██╗███████╗██╗ ██╗ ██████╗██████╗
██║ ██╔═══██╗██║ ██║██╔════╝██║ ██║██╔════╝╚════██╗
██║ ██║ ██║██║ ██║█████╗ ██║ █╗ ██║██║ █████╔╝
██║ ██║ ██║╚██╗ ██╔╝██╔══╝ ██║███╗██║██║ ╚═══██╗
███████╗╚██████╔╝ ╚████╔╝ ███████╗╚███╔███╔╝╚██████╔╝██████╔╝
╚══════╝ ╚═════╝ ╚═══╝ ╚══════╝ ╚══╝╚══╝ ╚═════╝ ╚═════╝启动界面 Logo 下方会显示“基于 H-lua 二次开发,感谢原作者与贡献者。”以致敬原项目。
