Vortex 日志工作流追踪实战:基于 watch-log 技能 §E Trace 模式的生命周期分析指南
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),按优先级:
$ARGUMENTS中给出显式文件路径 → 原样使用(单文件;只有用户要历史时才并入轮转兄弟文件);- 出现
prod关键字 → 使用 prod 目录$APPDATA/Vortex/; - 默认 → Dev 目录
$APPDATA/@vortex/main/; - 完全没有本地日志目录(如在 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 不变量:
- 每次完成的部署或清除后,恰好出现一次
sorting plugins finished {elapsedMS}([DEBG]),且必须位于部署活动清空之后。若排序出现在Starting deployment与最终deployment {added, removed, …}摘要之间,或一次部署出现 0/多次排序,即不变量被破坏。空排序集时会出现nothing to sort([WARN],标记保留); - 合集会话中扩展不处理
did-deploy;由postprocess collection启用 manifest 中的插件并执行唯一一次排序。若排序出现在starting install of collection与postprocess collection之间,即破坏; - 被中断合集安装所欠的排序会在下次档案激活时补上:
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(...) 调用):
Installation completed successfully:发射于 src/renderer/src/extensions/mod_management/InstallManager.ts,由trackedCallback在安装回调无错误时记录,duration: Date.now() - activeInstall.startTime即安装实测耗时——这正是 §E 第 3 步优先采用该duration字段的原因;finish mod install:发射于 src/renderer/src/extensions/mod_management/InstallContext.ts,载荷为{id, outcome},outcome === "success"时把 mod 状态置为"installed";start download mod:发射于 src/renderer/src/extensions/nexus_integration/util.ts;starting download发射于 src/renderer/src/IPCDownloadAdapter.ts(测试用例可见 redact.test.ts,其 URL 载荷中的 md5 会被脱敏为REDACTED,追踪下载线程时注意载荷已被脱敏);download completed发射于 src/main/src/downloading/manager.ts;deployment progress:发射于 src/renderer/src/extensions/mod_management/index.ts,携带{text, percent},是部署阶段推进与 Δ 计算的主要依据;profile change(src/renderer/src/extensions/profile_management/index.ts,载荷{from, to})与switched to profile(同文件 L478,载荷{gameId, current})——档案线程的起止键;- 合集信封:
starting install of collection发射于 src/renderer/src/extensions/collections/util/InstallDriver.ts,did install dependencies于同文件 L674,postprocess collection于 src/renderer/src/extensions/collections/postprocessCollection.ts; - 卡死/救援信号:
InstallManager: Called callback for stuck installation发射于 src/renderer/src/extensions/mod_management/InstallManager.ts(安装超时强清理路径);Collection install stalled, attempting rescue于同文件 L2833,Collection install stalled after rescue attempt, resolving于 L2861(第一次超时尝试救援、第二次超时强制 resolve 阶段,属于 §E 第 5 步与 §F 不变量 1/6 的判定依据);MAX_DEPENDENCY_RETRIES = 3定义于同文件 L567——同一modId的start mod install出现超过 3 次即为 requeue 循环(§F 不变量 3); level_pivot slow Write:发射于 src/main/src/store/LevelPersist.ts,默认超过SLOW_WRITE_THRESHOLD_MS(250 ms)才触发<a href="https://link.gitcode.com/i/6f78b70bdf2f8b87b74c5be08ab6a65f" target="_blank">WARN]——§E 第 5 步把"安装期间一次缓慢的 level_pivot 写入"列为交错问题,正可据此判定([LevelPersist.test.ts 中有对应断言)。
八、实战要点与常见坑
- 级别令牌严格区分:错误一定是
[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 生命周期追踪报告即可完成,且每一步都有日志行、共享块标记与源码发射点三重依据支撑。