Lovewc3 CLI

当前 npm 最新版本：1.0.25

🚀 npm 安装（推荐）

# 1. 全局安装
npm install -g lovewc3

# 2. 初始化环境（首次使用必须执行）
lovewc3 init

lovewc3 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 文档查询功能。

开发者快速启动

1. 配置环境变量：复制 .env.example 为 .env，填入 SILICONFLOW_API_KEY
2. 安装依赖：npm install
3. 安装 Python 依赖：pip install -r tools/rag/requirements.txt 和 pip install -r tools/mcp/requirements.txt
4. 安装 Go 1.20+（CLI 会在 /run、/editor 中使用 go run 生成 h-lua-slk；如 go 不在 PATH，可设置 GO_BIN）
5. 在支持 TTY Raw Mode 的终端中运行：npm run dev
   • 如必须在不支持 Raw Mode 的终端里运行，先执行：set INK_NO_RAW_MODE=1 && npm run dev
6. 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 滚动查看历史记录。
• 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 指定。

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"，然后按需调用生成的可执行文件。

Lovewc3 CLI 内置指令

• /list：进入地图列表模式，使用 ↑/↓、Enter、Esc 选择主地图；目录为空时列表显示 (空)。
• /refresh：立即重新扫描当前目录下的 .w3x/.w3m，并刷新主地图与地图数量提示。
• /settings：打开设置面板配置 Warcraft III 与 KKWE 路径。
• /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 会实时输出运行日志；若服务已在运行则仅返回状态。
• 自然语言查询：在命令行输入不以 / 开头的内容时，系统会执行 RAG+LLM 流程：先检索相关文档，再调用 DeepSeek-V3.2-Exp 模型生成回答。回答后会附带参考来源和 Token 用量统计。
• 默认状态下，命令行上方会实时展示 user: 与 love:（系统回答）对话历史，高度自动适应终端大小；有新消息时自动滚动到底部，支持 PageUp/PageDown（或 Ctrl+↑/↓）上下滚动查看更早的消息。

RAG + LLM 集成

1. 复制 .env.example 为 .env，填入 SILICONFLOW_API_KEY（SiliconFlow 控制台创建），其余端口可保持默认。
2. 安装 Python 依赖（建议使用 uv 或 pip）：
   • pip install -r tools/rag/requirements.txt
   • pip install -r tools/mcp/requirements.txt
3. 可选手动命令：
   • npm run rag:ingest：重新向 SiliconFlow 发送嵌入请求并刷新本地 rag_store/。
   • npm run rag:serve：仅启动 FastAPI RAG 服务（默认端口 8900）。
   • npm run mcp:serve：单独启动 MCP Server（默认端口 8901）。
4. 在 CLI 中执行 /rag 后，系统会自动启动两个 HTTP 服务：
   • RAG 服务 (端口 8900)：提供文档检索与索引刷新功能。
   • MCP 服务 (端口 8901)：提供标准化的 API 接口供 AI Agent 调用。
5. MCP 服务提供的接口：
   • POST /query_docs：语义检索 + bge-reranker-v2-m3 精排。
   • POST /refresh_index：触发 RAG 服务重新索引指定文档。
   • POST /read_document：直接获取原始 Markdown 文档内容。
   • GET /health：健康检查。
6. LLM 生成：自然语言查询会调用 SiliconFlow 的 deepseek-ai/DeepSeek-V3.2-Exp 模型：
   • 默认关闭思考模式（enable_thinking: false），响应更快
   • 温度设为 0.3，保证回答准确性
   • 最大输出 2048 tokens
7. CLI 退出时会自动停止 RAG/MCP 子进程，无需手动清理。

日志输出

• CLI 的所有系统消息与命令反馈会同步追加到根目录的 log.txt，格式为 [ISO时间][角色] 内容，便于排查问题。
• 如需清空记录，可删除该文件，运行时会自动重新创建。
• 设置面板会将“打开文件选择器”“取消/失败/成功”等过程写入日志，并在 30 秒无响应时自动超时记录，文件选择器会强制置顶防止被遮挡。

地图管理

• 启动 CLI 时会自动扫描当前目录下的 .w3x/.w3m 地图，并默认选中排序后的第一张作为主地图。
• 默认界面仅保留命令输入框和状态栏：状态栏在同一行展示 main map、KKWE 两条信息（未设置时提示 /settings），若终端宽度不足会自动换行。
• 命令行具备 default/cmd 状态机：输入 / 自动进入 cmd 状态并列出可用指令，可用 ↑/↓ 切换候选；Tab 会把候选指令补全到输入框并将光标移动到文本末尾，Enter 则直接执行当前高亮候选（即使输入只写了前缀），完全匹配的指令不会继续展示在候选列表里；执行或 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 二次开发，感谢原作者与贡献者。”以致敬原项目。