dsh-miliastra

原神 · 千星奇域（Miliastra Wonderland）UGC 的 DSH 插件：把「文件层」的开发闭环做成原生工具 —— 让 AI Agent 自己定位活文件、读地图存档、跑试玩探针、取运行时日志、看画面，不用你手动复制粘贴。

版本 0.6.4（见 CHANGELOG） · GPL-3.0-only · 适用于 DeepSeek Harness（dsh）0.1.2-rc.1+ · Windows。

🎯 目标是让 AI 更好用。 这个插件是一个 AI 写给其它 AI 用的：不是"替人省点击"， 而是让 AI 少问一句、少猜一次、少返工一轮就把活干完 —— 你用着别扭的地方，正是我猜不到的地方。 有想法直接写进 AI 反馈区，或开一个 Issue。

实机截图（部分账号信息已打码）· 面板六个页面 —— 左：初级功能（① 当前关卡 / ② 存盘与进程）； 右：预制效果（粒子与图元预设 · 二级分类 · 独立会话预览）与 网格计算（灰字坐标 · 多选 · 带色导出）。

预制效果	网格计算

六个页面各干什么、面板怎么用 → docs/面板与活文件安全.md； 要改面板本身 → docs/配置与开发.md（只改 lib/client.js 刷新页面即可，Host 半边才要重启 dsh web）。

30 秒上手

第一次上手（人或 AI）只要记住三步。第一条直接照抄 —— 它把路径、活文件、地图、日志目录一次全报出来：

miliastra_health {}

第几步	调什么	你会拿到什么
① 定位	上面那条 miliastra_health {}	当前正在开发的关卡 / 活文件绝对路径 / 地图 .gil / 日志目录 —— 这些路径每次都变，禁止写死
② 读或写代码	miliastra_code {"op":"inspect"} 先看病 → miliastra_code {"op":"deploy","source":"<本地 .lua 绝对路径>"} 投进去	体检（BOM / 行数 / SHA / 有没有被编辑器写回旧版）；部署自带备份 + SHA 校验 + Lua 结构校验，失败不碰活文件
③ 验证	miliastra_playtest {"op":"status"} → 请人点试玩 → miliastra_log {"op":"tail","tag":"<脚本里打的 TAG>"}	是否在试玩、开了几秒；脚本 print 的运行时正文（运行时结果只能靠 print + 取证，别靠猜）

三条铁律（先记住，能省掉大部分返工）：

1. 路径不写死 —— 换账号、换图、重建关卡都会换目录，一律从 miliastra_health 拿。
2. 写操作只发生在 miliastra_code / miliastra_probe / miliastra_sim —— 前两个自带备份、审计与双钥匙；miliastra_sim 只写本插件数据目录下的 simulator/ 与 shots/，不碰游戏存档、地图与活文件；其余工具一个字节都不写。
3. 不做越界的事 —— 不读游戏内存、不连游戏进程的端口、不冒充编辑器；试玩按钮只能人点（没有自动化通道，也不做）。

装法 + 面板在哪 + 常见坑 → docs/快速上手与教程.md； 不知道该调哪条 → 下面的工具导航，或 docs/工具参考.md（自动生成，不会过时）。

为什么需要它

千星奇域的 UGC 脚本只活在米哈游的本地存档目录里，而且路径每次都变（换账号 / 换图 / 重建关卡）：

…\AppData\LocalLow\miHoYo\原神\BeyondLocal\<账号ID>\Beyond_Local_Save_Level\<关卡ID>\ 下就三样东西： external_lua_file\<脚本名>.lua（真正跑在游戏里的活文件）、<关卡ID>.gil（地图存档，protobuf）、Beyond_Debug_Log\*.gia（客户端运行时日志）。

.lua 没有 git、没有撤销，覆盖即丢失；带 UTF-8 BOM 的脚本会让 Lua 直接报错；.gil 是二进制 protobuf，看不出「模板区里到底有没有模板」； .gia 是二进制日志，print 的东西肉眼很难捞 —— 每次排障都在「人肉找路径 → 手动拷贝 → 复制日志给 AI」里打转。 本插件把这套动作变成 11 个工具 + 一个侧边栏面板。

安装

方式一：npm（推荐）

dsh plugin --profile web add [email protected]

装完重启 dsh web（插件在启动时加载）。包页：https://www.npmjs.com/package/dsh-miliastra

方式二：源码 / git（要改插件本身时用）

克隆 → 软链进 profile 的 node_modules → 注册进 dsh.profile.bundles → 重启 dsh web。 三步细节、装完怎么自查、常见坑、发版流程 → docs/快速上手与教程.md。

⚠️ 只放软链没用：少了注册 dsh.profile.bundles 这一步，插件完全不会加载（原因见教程）。

---

工具

这一屏是导航（按问题找工具）。每个工具的每个 op 与参数在 docs/工具参考.md 里 —— 那一篇是生成的，不会过时。

工具	干什么	什么时候用
miliastra_health	扫出所有客户端安装 / 关卡 / 活文件 / 地图 / 日志目录，并判定「当前正在开发的关卡」	任何操作前先调它。路径随账号与换图变化，禁止写死
miliastra_code	活文件的 11 个 op：read 读正文（给了 source 就读任意本地 .lua，只读）/ deploy 投进沙箱（多文件批量也行，任一失败整体回滚）/ inspect 体检 / backup+backups 备份与清单 / restore 还原 / fixbom 只去掉那 3 字节 BOM / levels 读关卡表算几何事实（stage=N 选第几关）/ rects 比对两套矩形 / lint-ui 平台级 UI 门禁（画在哪=点哪算 · 8 的倍数 · 字号档位 · 高度够不够）/ preflight 投递前自检（summaryOnly 省上下文）。部署一律：先备份 → 二进制拷贝 → 比对 SHA-256 → 校验无 BOM，并先做 Lua 结构校验；部署成功后在备份目录写部署指纹，之后 op=inspect 会报「活文件是不是被编辑器写回了旧版」；回执里带部署后对账结论	改完本地脚本要投进沙箱时；想知道「这块平台和那块有没有叠上 / 头顶还剩几 px / 字号与高度合不合规」时
miliastra_map	读 <关卡ID>.gil（4 个 op：summary 概况 / clientui 客户端控件谱系（控件模板索引 / 名字 / 父 / 子） / script 脚本源码快照比对 / strings 提可读字符串，存盘前后 diff 用）	判断「哪些控件能被脚本动态创建」、判断「跑的是不是本地这版代码」
miliastra_log	读 .gia 运行时日志：sessions 列局面、tail 结构化读正文、grep 按 TAG / 正则过滤、tags 汇总标签、runs 按「局」切分 + 局间 diff、metrics 指标汇总（见下）。可用 run=<epoch> 只看某一局	运行时取证（Lua 里 print，别靠猜）。比让人手动贴日志可靠得多
miliastra_playtest	试玩开跑 / 结束的实时侦测（见下）：status 看现在在不在试玩、开了几秒；wait 等下一次开跑（可 afterSec 要「开跑 N 秒后」）	想知道「开跑那一刻」时 —— 这是唯一能看到开跑的通道，.gia 不行
miliastra_probe	试玩探针模板化：7 个模板 —— ping 探活 / tree 看控件 / instantiate 试钥匙 / api-surface 翻字典 / api-check 核文档 / perf 采样帧率 / custom（传一段完整 Lua 当正文，走同一条流水线）。渲染 → 部署 → 试玩后 collect 回收结论（list 先看每个模板的白话说明）	需要运行时真相时（某个控件号能不能建、某个枚举到底叫什么名）
miliastra_sim	内置模拟器：bind 把真机工程搬进来（活文件 + 控件模板索引 —— 优先自动拿：op=handover 从源码抽（可带 source 读任意本地 .lua）/ miliastra_map op=clientui 从 .gil 读，都拿不到才问创作者 → 回「脚本跑没跑、控件建了几个」）、state 看工程/控件树/属性、patch 改工程（加控件/改字段/挂脚本）、play 控制试玩（start/step/pointer/key/click/serverSet…）、verify 一条调用 = 操作+断言+判定、cases 验收单（自动项重放 / 人工项只列出等人打勾）、frames 动画证据、shot 出 PNG（ui 编辑器视图 / play 试玩画面）、load/save 模拟器工作区存档	想在游戏之外先跑一遍（搭界面 / 改控件 / 跑 levelScript / 看画面 / 自测逻辑）时。⚠️ 引擎吸收自 miliastra-beyond-simulator；模拟器通过 ≠ 真机通过
miliastra_shot	截图（5 个 op）：capture 截游戏/编辑器窗口、burst 连拍（awaitPlaytest:true 可「等开跑 → 等 N 秒 → 连拍」，一次调用；dryRun 先看计划）、list 看截到哪了、clean 清理（默认只报告）、targets 列出当前能截哪些窗口	需要「看画面对不对」时 —— 日志回答不了观感
miliastra_asset	插件级素材库 + 两个平台目录通道（11 个 op）：add 入库（绝对路径 / base64 / data URL，可带 tags）、list（tag/limit/summaryOnly）、get（回 dataUrl 或写到 out）、remove、rebuild（索引丢了从目录重建）、prune（默认只报告）、stats。按内容寻址：文件名 = sha256 前 16 位 + 原扩展名，同图只存一份。★ op=catalog = 查平台图片资源库（离线快照 1543 条 / 14 类）：按分类 / 颜色档 / simOnly / imgExists（21 条"目录里有、图却缺"）筛，回 id + 分类 + 有没有图 + 模拟器认不认（单图没名字 ⇒ 不编名字）。★ op=icon-search = 按语义找图标（不传参数给分类概览）。★ op=sound-search / op=sound-get = 平台音效库（1997 条 / 7 类）按中英文名模糊搜（五档相关性 + weak 标记；不支持拼音）。★ 回执体积：发现调用给全表、过滤调用只给结论 —— 要全表或 sha256 就传 withMeta:true	要把图片素材存下来反复引用时（UI 动画 / 粒子 / 像素画的图源）—— ⚠️ 只写插件数据目录，不进游戏存档、不碰活文件；素材绝不自动删（remove 要显式 confirm，删字节再加 deleteFile）。要挑平台素材 / 配音效时用后几个 op（离线快照、运行时零联网、不下载素材本体）
miliastra_gen	离线生成器（4 个 op，零平台 API、不写任何文件）：text-gradient 一次调用就出可部署的 Lua（逐帧刷字：script:EnableUpdate + OnUpdate 换帧 + 第一帧立刻上屏；output:"data" 才只要数据）；struct-json 出可直接导入千星的变量 JSON（24 个 ParamType、结构体/字典/列表嵌套、两种形态）；pixel-art 图片 → 可部署的像素画 Lua（图片控件的矩形块拼图，不是"一个像素一个控件"：关平滑降采样 → 行内行程 + 跨行同色同宽合并；output 另可要 struct 变量 JSON / data 块表；像素画是静态的 ⇒ 不加 EnableUpdate）；★ vfx-lua 粒子特效 → 可部署 Lua（17 个粒子预设（含 4 个组合预设：星光爆发 / 金币喷泉 / 雪中花瓣 / 孔雀终幕 —— 多层同屏，层全部取自已验证的预设）+ 3 个图元预设：环刃 / 刀光 / 新月；二级分类：粒子（光与火 / 天气 / 收集与庆祝 / 形态与轨迹 / 组合）· 图元（形状沿路径）；驱动层逐字取自真机定稿；preset:"list" 按需枚举（每条带分类），贝塞尔可用 path 给"钢笔"三手柄；imageId=真机任意素材号、previewImageId=模拟器预览号）。⚠️ <size=N>、4bit、真机渲染与粒子帧率均未经真机验证（4bit 默认关，启用时 Lua 顶部就有注释）；结构体 ID 必须 10 位数字、单条文本 ≤500 字符（不通过直接报错）；24 个类型是否等于 7.1 完整集未证实	要「AI 出参数 → 回执里就是能直接用的东西」时。交接值（文本框控件名 / 控件模板索引 / 图片模板 + 容器节点 / 粒子贴图号）先自动读当前关卡 .gil（只有唯一候选才采用），拿不到就报错点名让你去问创作者（绝不编索引）。细节见 docs/功能详解.md §生成器 / §vfx；粒子参数全表在工作区文档 docs/千星奇域_粒子特效配置格式.md §5.0（不在本包里，故不作链接）
miliastra_echo	回显参数	怀疑插件没生效 / 参数丢了时先调它

每个 op 与参数的完整说明在 docs/工具参考.md —— 由 node tools/gen-readme-tools.mjs --write 从 index.js 的 TOOLS 生成，自动生成不会过时（tests/readme-test.mjs 逐字比对，手写的清单一定会漂移）。

深入阅读（按需加载，不用一次读完）

上面解决怎么调；下面这几篇解决为什么与翻过什么车。每篇独立成文 —— 用到哪条读哪篇。

文档	什么时候读它
docs/工具参考.md	查「某个 op 干什么、某个参数取什么值」：每个工具的完整说明（由 TOOLS 生成，不会过时）
docs/快速上手与教程.md	第一次装：源码 / git 完整安装步骤（软链 + 注册 bundles + 重启）、装完怎么自查、面板在哪、常见坑、以后要发 npm 时怎么做
docs/功能详解.md	想知道某个工具到底怎么工作：试玩开跑与连拍、部署安全（备份 / 部署指纹 / fixbom / lintMode）、按「局」切分日志与指标汇总
docs/模拟器与视图.md	要用内置模拟器：三档（看 / 玩 / 判）在流程里的位置、画面怎么来的、AI 怎么自测（verify / frames / cases）、哪些还没验证
docs/面板与活文件安全.md	用人眼看面板：六个页面各干什么（初级 / 高级 / 模拟器 / 预制效果 / 像素画 / 网格计算）、「整体存盘状态」怎么算、自动跟随换图、多活文件、一键还原，以及活文件「宁可失败不许损坏」的约定
docs/关键知识与能力边界.md	动手前先认清边界：哪些控件能被脚本动态创建、prefabIndex 的坑、为什么试玩没有自动化通道
docs/配置与开发.md	要改这个插件 / 改环境变量与数据目录时要看：改代码后的验证阶梯、生效边界（Host 是启动快照）、试玩探针硬边界、排障
CHANGELOG.md	每个版本加了什么、修了什么、怎么验的

想知道「模拟器是怎么融进来的、上游源码在哪、没搬的那些读哪篇」→ 工作区文档 docs/dsh-miliastra_对比_miliastra-beyond-simulator_2026-09-24.md（含原《上游源码索引与吸收地图》全文， 以及融合决策与许可结论）—— 不在本包里，故不作链接（2026-10-01 从本仓库 docs/ 挪过去： 它讲的是本机 _ref/ 那份只读克隆，帮的是"继续读上游"的人，不是 npm 使用者）。

AI 反馈区：目标是让 AI 更好用

用它的 AI 和写它的 AI 是同一条战线的：哪里绕、哪里缺参数、哪里报错说不清、哪里该给数字却给了文字，直接说。 想法池（docs/源码质量与想法池.md）已按创作者要求于 2026-09-29 删除 —— 提想法直接走 Issue —— 最值钱的写法：「我在做什么」+「调了什么」+「期待什么」+「实际得到什么」。

---

License

GNU GPL v3.0（GPL-3.0-only） · Copyright 2026 LoktLin

可自由使用、修改、分发（含商用），但衍生作品必须以同一许可（GPL-3.0-only）发布，并保留版权与许可声明；不提供任何担保。完整条款见 LICENSE；引擎部分的来源与归属见 NOTICE。