Vortex 日志工作流追踪实战:基于 watch-log 技能 §E Trace 模式的生命周期分析指南

原创2026-10-13 18:27:371,705 阅读
文章标签:桌面应用游戏开发前端插件系统

Vortex 日志工作流追踪实战:基于 watch-log 技能 §E Trace 模式的生命周期分析指南

导读

本指南以 watch-log 技能 六大模式之一的 Trace(§E) 为核心,讲解如何从 Vortex 的多 MB 原始日志中,把一次**下载(download)/ 安装(install)/ 合集(collection)/ 部署(deployment)/ 档案切换(profile switch)**完整地按时间线抽出来,还原其"第一行日志到最后一行的完整生命周期"。读完本文,你将掌握线程键(thread key)选取、有序时间线抽取与阶段耗时(Δ)计算、成功/失败/卡死三分法判定,以及集合安装的"是否完全安装(fully installed)"判定公式,并理解这些判定背后的源码发射点,可直接用于排查"某 Mod 装到一半不动了""合集到底装完没有""部署为什么这么慢"等实战问题。

一、技能定位:thin router 与 Trace 模式

watch-log 是一个针对 Vortex 日志的 Claude Code 技能,其入口 SKILL.md 本身只是一个薄路由器(thin router):它总是先读取核心事实文件 reference.md,再按请求从 modes/ 目录按需加载模式文件(§A 实时、§B 调查、§C 持久化、§D 关联、§E 追踪、§F 合集审计),并按 Prereq 行加载对应的 shared/ 共享块,从而把上下文占用压到最小。

Trace 与 Collection install audit 的分工(见 SKILL.md):§E 只跟一个实体、报告它卡在哪里;§F 则审计整个合集安装是否满足安装完成不变量(每个成员到达终态、无 requeue 循环、阶段推进、错误路径收敛),并指出是哪个不变量被破坏。§F 同时承担 LAZ-483 回归检查的角色。因此:

  • 想追查单个 Mod 安装、单个下载、单次部署的来龙去脉 → 用 §E Trace;
  • 想审计整个合集安装的健康度 → 用 §F,且 §E 是其前置基础。

Trace 模式的触发词($ARGUMENTS):trace / track / follow this install / download / collection / deployment,或直接给出 mod id / 归档名 / nxm url / downloadId / 合集名。

二、前置知识:Vortex 日志的基础事实(reference.md)

Trace 之前必须掌握以下核心事实(全部来自 reference.md,并已针对真实 Vortex 日志验证):

日志行格式:TIMESTAMP [LEVEL] [SOURCE] message {json}

  • 级别是 4 字符令牌:[DEBG] [INFO] [WARN] [ERRO] —— 注意错误是 [ERRO] 而不是 [ERROR];
  • 来源是 [MAIN](主进程)或 [RENDERER](渲染进程);
  • 消息后跟随的 {json} 是结构化载荷,承载实体 ID、耗时等关键字段。

日志目录:

  • Dev(@vortex/main,开发构建):$APPDATA/@vortex/main/
  • Prod(正式安装):$APPDATA/Vortex/
  • 两个目录下都有独立的 network.log,组装日志集合时必须排除它。

轮转与写入顺序:条目按迭代(时间先后)顺序追加,因此任何文件的尾部都是其最近的活动,最新会话位于当前 vortex.log 的底部。文件约 11 MB 轮转一次:vortex.log = 当前/最新,vortex1.log … vortexN.log = 更旧,且编号越大越旧。只有当会话跨越上次轮转、或用户需要历史时才需要读取更旧的文件。

解析日志集合(rotation-aware, dev/prod-aware),按优先级:

  1. $ARGUMENTS 中给出显式文件路径 → 原样使用(单文件;只有用户要历史时才并入轮转兄弟文件);
  2. 出现 prod 关键字 → 使用 prod 目录 $APPDATA/Vortex/;
  3. 默认 → Dev 目录 $APPDATA/@vortex/main/;
  4. 完全没有本地日志目录(如在 claude.ai 沙箱中)→ 日志作为上传文件出现,先解压 zip,视为显式路径处理。

需要轮转历史时,用 Bash 组装"从旧到新"的有序列表(reference.md 原文命令,已排除 network.log):

D="$APPDATA/@vortex/main"   # 或 "$APPDATA/Vortex",或显式路径所在目录
{ ls "$D"/vortex[0-9]*.log 2>/dev/null \
    | sed -E 's/.*vortex([0-9]+)\.log/\1 &/' | sort -rn | cut -d' ' -f2- ; \
  echo "$D/vortex.log" ; }

该命令按后缀降序打印带编号文件(旧的在前),最后是 vortex.log。

三、会话界定:Trace 的默认范围(shared/sessions.md)

Trace 默认只追踪一个会话(默认为最新会话,按 §B/investigate.md 的规则界定),报告时必须说明使用的是哪个会话。会话边界标记(来自 shared/sessions.md):

  • 起始锚点:[INFO] [MAIN] Vortex Version "…"(前面有一行 [INFO] [MAIN] -------------------------- 分隔线),引号内数值即该会话的应用版本;
  • instanceId:[DEBG] [MAIN] startup instance {"instanceId":"…"};
  • 关闭标记:[INFO] [MAIN] Vortex closing(退出发起)→ [INFO] [MAIN] clean application end(退出完成)。

界定方法:最新会话位于当前 vortex.log 的尾部——从后往前扫描最后一个起始锚点,锚点 → EOF 即为最新会话。仅当起始锚点不在 vortex.log 中(会话开始于上次轮转之前)才需要回溯 vortex1.log、vortex2.log,以保证会话连续。若最旧文件从会话中途开始(会话起点已被轮转丢弃),则需注明"会话起点不在保留日志内,窗口不完整"。

instanceId 语义:在 prod 上同一安装跨重启稳定,因此变化意味着重装/全新安装,需要标记并突出;在 dev 上它每次测试运行都可能变化,属噪音。共享同一 instanceId 的多个异名外部文件可能是同一安装的轮转集合(见 shared/multi-file.md)。

四、核心工作流:把一次生命周期从顶到底追完(§E 七步法)

本模式文件 modes/trace.md 把一次完整追踪定义为 7 个步骤,下面逐条展开,并补入共享块中的标记细节与源码发射点。

第 1 步:识别实体与其线程键(thread key)

从 $ARGUMENTS 确定要追踪的实体类型,并选对"线程键"——后续所有 grep 都围绕这个键展开:

用户给出 实体 → 线程键
mod id / 归档名(如 Atomic Lust-31853-2-7b-…) 安装线程,键 = modId / archivePath
nxm url 或 downloadId / collationId 下载线程
合集名 / 合集 id 合集线程(及其成员安装)
profile id 或档案切换(可附带游戏) 档案线程,键 = from / to / current
关键词 deployment / deploy / purge(可附带游戏) 部署线程

若有歧义(比如日志里同时有多个同名安装),先在选定日志中 grep 该词,把候选实体(带 id)列出来让用户挑选,不要擅自决定。

第 2 步:抽取有序切片(ordered slice)

grep 出携带线程键的每一行,以及它扇出(fans out)的相关键,再按时间戳排序合并成一条自上而下的单一时间线。跨阶段用共享字段桥接,链路为:

nxm url / downloadId(下载) → archivePath(交接) → modId(安装) → 下一份 deployment 摘要中的成员关系

例如一个下载的 nxm url 会引出最终生成的 archivePath,再引出对应安装的 modId。这一"键接力"是 §E 把下载与安装两段日志缝合成一条连续生命周期的方法。

第 3 步:映射到预期阶段并渲染时间线

依据 shared/lifecycle.md 中定义的生命周期标记,把抽取的日志行映射到预期阶段,并渲染为 阶段 → 时间戳 → 距上一阶段的 Δ,让慢步骤(例如 extract vs install vs deploy 的耗时差异)一眼可见。同时计算总耗时;对于安装,优先采用 Installation completed successfully 载荷中记录的 duration 字段(它由源码在回调中实测计算,见下文源码佐证)。

第 4 步:结果分类(outcome & gaps)

把实体终点归入三类:

  • completed(已完成)——存在终态成功标记:finish mod install {outcome:"success"} / Installation completed successfully / download completed / 最终 deployment {…} / postprocess collection / switched to profile;
  • failed(失败)——线程上出现 [ERRO],或 outcome != success;
  • incomplete / stuck(不完整/卡死)——有起始阶段但会话结束前没有到达终态阶段;最后到达的阶段就是它卡住的位置(与 §D 相同的"应有却缺失"逻辑)。

第 5 步:列出交错问题(interleaved problems)

列出实体时间窗口内、载荷引用了线程键的任一 [ERRO]/[WARN],例如:Buggy installer 错误、failed to parse esp、安装期间一次缓慢的 level_pivot 写入。这些交错信号往往是"为什么卡住/为什么失败"的直接线索。

第 6 步:合集特殊处理(collections)

合集安装需要报告两层内容:

合集级信封(envelope):starting install of collection {totalMods, missing} → postprocess collection。注意:所有合集相关日志都是 [RENDERER],且没有 [collections] 前缀。

逐成员汇总(per-member roll-up):每个成员的 modId、结果(outcome)、耗时(duration),并标记失败或从未到达终态的成员;同时注意 collationId 把成员们的下载串在一起。

必须明确回答"合集是否完全安装",使用 §F(modes/collection-install.md)的完全安装判定公式:

installed = (totalMods - missing) + completed-this-run

对照 totalMods 判断:starting install of collection {totalMods, missing} 给出了成员总数与本次启动时尚需安装的数量,因此 totalMods - missing 是本次运行前已装好的成员;再统计窗口内记录 Installation completed successfully 的成员数得到 completed-this-run。判定三态:

  • 完全安装(Fully installed):到达 postprocess collection 且 installed == totalMods,无失败/卡死成员;
  • 完成但未完全安装(Completed, not fully installed):到达 postprocess 但有缺口——缺口必须分类为 failed / stuck / skipped-or-unaccounted。特别注意:跳过(用户跳过、可选成员默认跳过)成功时不写日志行,只写会话状态;因此"没有安装线程、也没有失败"的成员归类为"skipped or unaccounted",本身不是错误。跳过的唯一日志是失败路径:could not find collection rule for skipped download;
  • 未完成(Not completed):从未到达 postprocess collection:stuck / interrupted / parked,同样给出计数。

第 7 步:输出

输出内容清单:带 Δ 的阶段时间线、结果判定、总耗时/最长步骤耗时、交错出现的错误与警告,以及(合集场景的)逐成员表格。

五、各类实体生命周期标记速查(shared/lifecycle.md)

Trace 的映射工作完全依赖下面的标记集合(均已按 shared/lifecycle.md 整理):

下载(Download)

start download mod {urlStr}
→ starting download {encodedUrl, dest, collationId}
→ download resolved
→ (MAIN) queuing download {downloadId}
→ download starting {downloadId}
→ download completed {downloadId}

线程键:downloadId、collationId(把合集的下载分组)、或 nxm url(形如 nxm://<game>/mods/<modId>/files/<fileId>)。失败标记:[ERRO] / download failed。

安装(Install,per mod)

start mod install {id}
→ mod id for newly installed mod {archivePath, modId}
→ installing to {modId, destinationPath}
→ extracting mod archive
→ invoking installer {installer}
→ finish mod install {id, outcome}
→ Installation completed successfully {installId, modId, duration}
→ Mod installed, scheduling debounced health check

线程键:modId(= id,例如 Atomic Lust-31853-2-7b-…)/ archivePath / installId。依赖处理:start/done installing dependencies {modId};推荐项类似。

合集(Collection)

starting install of collection {totalMods, missing}(InstallDriver)→ 成员安装(每个成员走上面的安装序列)+ add collection rule {…} → did install dependencies {gameId, modId} → postprocess collection(postprocessCollection)。全部 [RENDERER],无 [collections] 前缀。

部署(Deploy)与清除(Purge)

deployment progress {text, percent} 依次推进: Loading deployment manifest → Running pre-deployment events → Checking for external changes → Starting deployment → Sorting mods → Running post-deployment events,最终收尾为 deployment {added, removed, "source changed", modified}。

清除:[mod-dependency-manager] starting purge activity → finished purge activity in N seconds。

外部变更:found external changes {automated, user}([INFO])+ external changes diagnostic {surfaced: [{typeId, filePath, source, changeType}]}([DEBG]),仅在 user > 0 时出现;对话框阻塞,Starting deployment 之前不会推进。批量 changeType: "srcdeleted" 表示暂存源已消失。

档案切换(Profile switch)

profile change {from, to}
→ removing info of missing mod from profile {profile, game, modId}(爆发式出现 = mod 表/档案失同步)
→ will deploy pending profile "<id>"(跨游戏,入站档案不是其游戏最后激活的,游戏有未部署变更)
→ starting refresh profile export
→ will deploy previously active profile "<id>"(仅同游戏)
→ will deploy next active profile "<id>"(返回某游戏最后激活档案时不出现)
→ switched to profile {gameId, current}(停用时为 switched to no profile)

线程键:from / to / current。关键判别规则:被跳过的部署既不记 will 也不记 did deploy;只有 will 而无 did = 部署失败且切换被取消(Failed to set profile,[ERRO]/[WARN]);active profile switch didn't get confirmed?([WARN])= 确认超时但切换成立。跨游戏另有:running checks {event:"gamemode-activated", count} → all checks completed,以及 manual mod changed {stagingFolder, addedMods, removedMods}([WARN],暂存文件夹在 Vortex 之外被改动,会弹窗询问是否应用)。

六、gamebryo 部署追踪的特殊性(shared/gamebryo.md)

追踪gamebryo 游戏(上古卷轴/辐射系列等)的部署时,需加载 shared/gamebryo.md,其核心是 deploy → sort 不变量:

  1. 每次完成的部署或清除后,恰好出现一次 sorting plugins finished {elapsedMS}([DEBG]),且必须位于部署活动清空之后。若排序出现在 Starting deployment 与最终 deployment {added, removed, …} 摘要之间,或一次部署出现 0/多次排序,即不变量被破坏。空排序集时会出现 nothing to sort([WARN],标记保留);
  2. 合集会话中扩展不处理 did-deploy;由 postprocess collection 启用 manifest 中的插件并执行唯一一次排序。若排序出现在 starting install of collection 与 postprocess collection 之间,即破坏;
  3. 被中断合集安装所欠的排序会在下次档案激活时补上:draining pending collection plugin sort {profileId, gameId}([INFO])后跟一次排序。

插件相关失败标记:failed to parse esp {path, error}([WARN],插件页,区别于 blueprint-master 检查的 failed to parse esp file {name, err});LOOT process died([WARN],worker 重启最多 3 次);failed to initialize LOOT([ERRO])。自 #24273 起,ghosted 插件(.ghost,任意大小写)与其他插件一样参与解析,因此一串 .ghost 路径上的解析失败是回归信号。

七、源码佐证:关键标记的发射点

以下发射点均已在本仓库源码中核实(Trace 报告里引用的每个成功/失败标记都对应真实的 log(...) 调用):

八、实战要点与常见坑

  • 级别令牌严格区分:错误一定是 [ERRO] 而非 [ERROR];grep 时不要把 [WARN] 误当 [ERRO] 计数。
  • 先选会话,再下结论:Trace 报告必须声明覆盖哪个会话及其精确窗口,绝不静默混合多个会话(规则来自 §B modes/investigate.md 第 6 条)。
  • "应有却缺失"即卡死:起始阶段存在、终态阶段缺失 = 卡死/不完整,而不是成功;最后到达的阶段就是卡点。
  • 合集缺口先分类再下结论:skipped 成功路径没有日志行,因此"无线程且无失败"的成员要标为 skipped-or-unaccounted 而非错误;只有失败路径才有 could not find collection rule for skipped download 日志。
  • 键接力是跨阶段追踪的灵魂:nxm url/downloadId(下载)→ archivePath(交接)→ modId(安装)→ 部署摘要成员关系(部署),每一步都要在上一段的载荷里找下一段的键。
  • dev/prod 语义不同:prod 的 instanceId 变化 = 重装(要突出);dev 的 instanceId 变化是噪音;dev 会话经常只到 Vortex closing 就结束(无 clean application end),属"退出期间被杀",不是硬崩溃(分类见 shared/sessions.md 的 4 态终止模型)。
  • 版本陈旧检查:对 prod/外部日志,先按会话的 Vortex Version 引号值对照最新 stable/beta 做陈旧检查;旧日志的结论可能"已修复",需先询问再继续。会话记录 Vortex Version "1.0.0" 恒为 dev 构建,永远视为当前版本。
  • 日志文本可能漂移:§F 明确要求在使用"缺失即结论"前,先 grep 对应源码确认消息字符串仍然存在(可复用 drift-check 的标记清单思路)。

九、一个完整的 Trace 输出模板

把第 1–7 步产出拼成一份自洽报告,建议结构如下:

【追踪范围】会话 <version> @ <window>,文件 <files>(轮转集合已解析)
【实体】<modId/collection/deployment/profile>,线程键 <key>
【阶段时间线】phase → timestamp → Δ(附总耗时与最长步骤)
【结果判定】completed / failed / incomplete-stuck(卡点 = 最后到达阶段)
【交错问题】窗口内引用线程键的 [ERRO]/[WARN] 列表
【合集附加】(若为合集)信封:starting install of collection {totalMods, missing}
            → did install dependencies → add collection rule → postprocess collection
           逐成员表:modId · 阶段 · outcome · duration · 重试次数
           完全安装判定:installed = (totalMods - missing) + completed-this-run vs totalMods
           缺口分类:failed / stuck / skipped-or-unaccounted

照此模板输出,一份可转发、可引用的 Vortex 生命周期追踪报告即可完成,且每一步都有日志行、共享块标记与源码发射点三重依据支撑。

登录后查看全文
Vortex