agentic-awesome-skills 在 Windows 上的截断崩溃循环恢复：从 TrajectoryChatConverter 错误定位到脚本化修复-酒店常州论坛

agentic-awesome-skills 在 Windows 上的截断崩溃循环恢复：从 TrajectoryChatConverter 错误定位到脚本化修复

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

这篇指南面向在 Windows 上使用 agentic-awesome-skills 仓库、且其宿主（Antigravity 或基于 Jetski/Cortex 的集成）陷入「启动即崩溃 → 恢复同一损坏会话 → 再次崩溃」循环的开发者。读完本文，你将掌握完整的手动恢复流程、可一键执行的社区批处理恢复脚本，以及从根本上杜绝该错误的懒加载（lazy loading）与上下文上限配置方案，这些方案均有仓库内源码与契约文件可查证。

一、故障现象与根因：`TrajectoryChatConverter: could not convert a single message before hitting truncation`

当 Antigravity 或基于 Jetski/Cortex 的集成在 Windows 上陷入重启循环时，通常会看到如下报错：

TrajectoryChatConverter: could not convert a single message before hitting truncation

这个错误本身并不代表技能内容损坏，而是加载方式出了问题。根据仓库集成文档 docs/integrations/jetski-cortex.md 的说明，典型成因有两种：

上一次运行存储了损坏的轨迹（trajectory）：会话历史被持久化到了本地存储，恢复时TrajectoryChatConverter无法把其中的单条消息转换成模型可用的格式。
单个消息中加载了过多技能指令：宿主把整个技能库的内容塞进一条系统消息，导致上下文窗口在用户消息加入之前就被填满，进而触发截断。

仓库中另一份文档 docs/users/windows-truncation-recovery.md 与本文档互为英文/中文对照，二者描述的恢复路径完全一致。

反模式：为什么技能越多越容易触发

Jetski/Cortex 集成指南明确列出了三种必须避免的做法：

启动时读取全部skills/*/SKILL.md目录；
把全部SKILL.md内容拼接进同一条系统提示；
每次请求都重新注入整个技能库。

在拥有 2,100+ 技能的规模下（仓库根目录 skills_index.json 与 data/skills_index.json 记录了全部技能条目），这种「全量注入」会瞬间填满上下文窗口，从而在转换阶段抛出 truncation 错误，并在 Windows 上形成崩溃循环。

二、何时使用本指南

出现以下任一情形时，应立即按本文步骤操作：

Antigravity 在 Windows 上启动后立即崩溃；
应用程序持续恢复同一个损坏的会话；
新安装的技能或捆绑包（bundle）导致了故障；
你已经删除了问题技能，但应用程序仍然打开到同一个错误（说明损坏的会话已被持久化，仅删技能不够，还需清理存储）。

三、安全第一：删除任何内容之前先备份

恢复过程会删除本地存储与临时文件，因此在执行任何删除操作前，请先备份以下目录（若存在）：

%USERPROFILE%\.gemini\antigravity-browser-profile\Default %AppData%\antigravity %USERPROFILE%\.gemini\antigravity

如果你将技能安装到了其他位置，请一并备份该自定义目录。备份的意义在于：清理存储会同时清掉全部会话历史与本地偏好，一旦误删问题技能或需要回滚，备份是唯一恢复手段。

四、手动恢复步骤（完整流程）

请严格按顺序执行：

完全关闭 Antigravity（包括托盘常驻进程，避免文件被占用导致清理失败）。
删除有问题的技能或包，默认安装路径为：
```
%USERPROFILE%\.gemini\antigravity\plugins\skills
```

删除浏览器数据库文件夹（若存在）：

%USERPROFILE%\.gemini\antigravity-browser-profile\Default\Local Storage %USERPROFILE%\.gemini\antigravity-browser-profile\Default\Session Storage %USERPROFILE%\.gemini\antigravity-browser-profile\Default\IndexedDB

删除 Antigravity 应用存储文件夹（若存在）：

%AppData%\antigravity\Local Storage %AppData%\antigravity\Session Storage

清除 Windows 临时目录：
```
%TEMP%
```
重启 Antigravity。
仅重新安装你实际需要的技能，或把集成切换到带有明确限制的延迟加载方案（详见下文第六节）。

其中第 2～5 步的核心逻辑是：删除问题技能以切断故障源，清空 Local/Session Storage 与 IndexedDB 以丢弃损坏轨迹，清理%TEMP%以移除残留的临时转换产物。这四步缺一不可——仅删技能而不同步清理存储，正是「明明删了技能却仍打开到同一错误」的原因。

五、可选的 Windows 批处理恢复助手

仓库文档收录了社区成员 @DiggaX 在 issue #274 中分享的恢复工作流，封装为可直接运行的批处理脚本。请在运行之前仔细阅读脚本内容，确认其行为符合你的预期，尤其是确认三个目标路径与你的安装位置一致。

@echo off setlocal enabledelayedexpansion title Anti-Gravity_Recovery_Tool_Universal set "TIMESTAMP=%date:~6,4%-%date:~3,2%-%date:~0,2%_%time:~0,2%-%time:~3,2%" set "TIMESTAMP=%TIMESTAMP: =0%" set "BACKUP_DIR=%USERPROFILE%\Desktop\AG_Emergency_Backup_%TIMESTAMP%" set "PATH_BROWSER=%USERPROFILE%\.gemini\antigravity-browser-profile\Default" set "PATH_APPCONFIG=%AppData%\antigravity" set "PATH_MAIN=%USERPROFILE%\.gemini\antigravity" echo ============================================================ echo ANTI-GRAVITY RECOVERY ^& REPAIR TOOL (UNIVERSAL) echo ============================================================ echo. echo This tool targets the truncation crash loop on Windows. echo [INFO] Backup location: %BACKUP_DIR% echo. if not exist "%BACKUP_DIR%" mkdir "%BACKUP_DIR%" if exist "%PATH_BROWSER%" xcopy "%PATH_BROWSER%" "%BACKUP_DIR%\Browser_Profile" /E /I /Y /Q if exist "%PATH_APPCONFIG%" xcopy "%PATH_APPCONFIG%" "%BACKUP_DIR%\App_Config" /E /I /Y /Q if exist "%PATH_MAIN%" xcopy "%PATH_MAIN%" "%BACKUP_DIR%\Main_Skills" /E /I /Y /Q ( echo === ANTI-GRAVITY RESTORATION GUIDE === echo. echo Restore Browser_Profile to: %PATH_BROWSER% echo Restore App_Config to: %PATH_APPCONFIG% echo Restore Main_Skills to: %PATH_MAIN% echo. echo Close Antigravity before restoring. ) > "%BACKUP_DIR%\RECOVERY_INSTRUCTIONS.txt" set /p "repair=Start the repair now? [Y/N]: " if /i "%repair%"=="Y" ( if exist "%PATH_BROWSER%\Local Storage" rd /s /q "%PATH_BROWSER%\Local Storage" if exist "%PATH_BROWSER%\Session Storage" rd /s /q "%PATH_BROWSER%\Session Storage" if exist "%PATH_BROWSER%\IndexedDB" rd /s /q "%PATH_BROWSER%\IndexedDB" if exist "%PATH_APPCONFIG%\Local Storage" rd /s /q "%PATH_APPCONFIG%\Local Storage" if exist "%PATH_APPCONFIG%\Session Storage" rd /s /q "%PATH_APPCONFIG%\Session Storage" del /q /s %temp%\* >nul 2>&1 for /d %%x in (%temp%\*) do @rd /s /q "%%x" >nul 2>&1 echo [SUCCESS] Recovery cleanup completed. ) else ( echo Recovery skipped. No files were deleted. ) echo. echo Next step: remove the broken skill from %PATH_MAIN%\plugins\skills pause

脚本行为拆解

自动备份：脚本首先把PATH_BROWSER（浏览器配置）、PATH_APPCONFIG（应用配置）、PATH_MAIN（技能主目录）三处数据用xcopy /E /I /Y /Q完整复制到桌面上的AG_Emergency_Backup_<时间戳>目录，并生成RECOVERY_INSTRUCTIONS.txt说明文件，记录了各目录应恢复到的目标位置。
交互确认：通过set /p "repair=Start the repair now? [Y/N]: "要求用户确认，输入非Y时不执行任何删除。
定向清理：确认后仅删除三处 Local/Session Storage、浏览器 IndexedDB，并递归清空%TEMP%；随后提示用户从%PATH_MAIN%\plugins\skills移除问题技能。

该脚本与手动步骤一一对应，可视为手动流程的自动化封装，适合需要频繁在故障机或团队机器上执行的场景。

六、推荐的预防措施：从恢复走向根治

恢复只是事后补救，仓库集成指南给出了明确的预防策略，这也是避免再次陷入崩溃循环的根本：

不要将每个SKILL.md连接到一个系统提示中。这是触发 truncation 的最直接原因。
使用根目录skills_index.json作为规范轻量级清单；仅在宿主必须读取data/子树时使用 data/skills_index.json 兼容性镜像。两份文件保持相同负载，属于同一契约。
仅在实际请求技能时加载SKILL.md文件，即按@skill-id懒加载。
为每个轮次的技能设置明确限制（maxSkillsPerTurn）。
在参考 Jetski/Gemini 加载器中首选overflowBehavior: "error"，让主机在上下文窗口被静默过度填充之前清晰地失败，而不是静默截断后写入损坏轨迹。

背后的契约：skills_index.json 与 schema

预防措施依赖仓库稳定的清单契约，详见 docs/users/discovery-manifest.md：

规范文件：仓库根目录skills_index.json；
镜像文件：data/skills_index.json必须与规范文件保持完全一致；
格式：JSON 数组，每个技能一个对象；
Schema：schemas/skills-index.v1.schema.json。

清单条目的必填字段包括id（即@skill-id）、path（技能目录相对路径，如skills/brainstorming）、category、name、description、risk、source、date_added。其中path字段在 schema 中被约束为正则以^skills/开头，这意味着所有技能必须位于仓库skills/子树内——这为后文提到的路径安全检查提供了契约前提。

源码级验证：参考加载器的懒加载与安全边界

仓库在 docs/integrations/jetski-gemini-loader/loader.mjs 中提供了可直接参考的 Node.js ESM 实现（配套说明见 docs/integrations/jetski-gemini-loader/README.md），其中三项设计直接对应上述预防措施：

启动引导只读清单：loadSkillIndex(indexPath)仅解析 JSON 并构建id -> meta映射，不读取任何SKILL.md正文，保证启动开销极小。
消息级解析与每轮上限：resolveSkillsFromMessages(messages, index, maxSkills)用正则/@([a-zA-Z0-9-_./]+)/g扫描对话中的@skill-id引用，并且assertValidMaxSkills强制maxSkills必须为正整数；buildModelMessages中默认maxSkillsPerTurn = 8，当overflowBehavior: "error"且引用数超限时直接抛出Too many skills requested in a single turn. Reduce @skill-id usage to N or fewer.的明确错误。
路径安全校验：loadSkillBodies对每个解析出的路径执行三重检查——相对路径不得以..开头、目录必须是常规目录且非符号链接、realpath解析后的最终路径不得逃逸skillsRoot。这正是集成指南强调的「Path safety: verify manifest paths remain inside SKILLS_ROOT」的落地实现，可防止恶意清单条目读取根目录外文件。

上下文溢出处理策略

集成指南建议在宿主侧设置两层保护：

安全阈值：例如上下文窗口的 70%～80%；
每轮技能上限：例如 5～10 个。

当阈值被超过时，选择其一：按时间或优先级缩减包含的技能数量；或向用户返回清晰错误，例如「Too many skills were requested in a single turn. Reduce the number of@skill-idreferences in your message or split them into multiple turns.」

七、推荐的验证场景

在修复并改造加载方式后，可用以下三个场景验证是否彻底摆脱截断崩溃：

场景 1 —— 简单消息（如 "hi"）：无@skill-id引用 → 不加载任何SKILL.md→ 提示词保持精简 → 无错误。
场景 2 —— 少量技能：消息引用 1～2 个@skill-id→ 仅加载对应SKILL.md→ 无溢出。
场景 3 —— 大量技能：消息引用大量@skill-id→maxSkillsPerTurn或 token 保护被触发 → 不再出现静默溢出。

八、进阶控制：技能子集与捆绑包

除懒加载外，仓库还提供两种主动收窄技能面的方式（见 docs/integrations/jetski-cortex.md）：

将不常用技能移入skills/.disabled/，在特定环境中排除它们；
使用仓库的捆绑包（bundle）机制，只加载聚焦的技能组，相关说明见 docs/users/bundles.md。

对于 Codex 或 Claude Code 用户，集成文档建议优先使用 AAS Core（docs/users/aas-core.md）：它通过有界、只读的 MCP 服务器提供中立的、确定性的目录检索，并对 agent 选中的 ID 做精确校验，从宿主侧规避了本文所述的全量注入风险。

九、总结

Windows 上的TrajectoryChatConverter截断崩溃循环，本质是「全量加载技能 + 持久化损坏轨迹」共同作用的结果。恢复路径分为三层：先备份，再按「删技能 → 清存储 → 清临时目录」顺序手动或脚本化修复，最后通过skills_index.json清单 + 懒加载 + 每轮上限 +overflowBehavior: "error"的配置组合根治问题。仓库内的 loader.mjs、skills-index.v1.schema.json 与 discovery-manifest.md 为这一整套方案提供了可直接复用的实现与契约依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析