多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

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

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。仅重新安装你实际需要的技能或把集成切换到带有明确限制的延迟加载方案详见下文第六节。其中第 25 步的核心逻辑是删除问题技能以切断故障源清空 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 repairStart 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 21 for /d %%x in (%temp%\*) do rd /s /q %%x nul 21 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 repairStart 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 数组每个技能一个对象Schemaschemas/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%每轮技能上限例如 510 个。当阈值被超过时选择其一按时间或优先级缩减包含的技能数量或向用户返回清晰错误例如「Too many skills were requested in a single turn. Reduce the number ofskill-idreferences in your message or split them into multiple turns.」七、推荐的验证场景在修复并改造加载方式后可用以下三个场景验证是否彻底摆脱截断崩溃场景 1 —— 简单消息如 hi无skill-id引用 → 不加载任何SKILL.md→ 提示词保持精简 → 无错误。场景 2 —— 少量技能消息引用 12 个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 Coredocs/users/aas-core.md它通过有界、只读的 MCP 服务器提供中立的、确定性的目录检索并对 agent 选中的 ID 做精确校验从宿主侧规避了本文所述的全量注入风险。九、总结Windows 上的TrajectoryChatConverter截断崩溃循环本质是「全量加载技能 持久化损坏轨迹」共同作用的结果。恢复路径分为三层先备份再按「删技能 → 清存储 → 清临时目录」顺序手动或脚本化修复最后通过skills_index.json清单 懒加载 每轮上限 overflowBehavior: error的配置组合根治问题。仓库内的 loader.mjs、skills-index.v1.schema.json 与 discovery-manifest.md 为这一整套方案提供了可直接复用的实现与契约依据。【免费下载链接】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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表