SuperAPI AI 工具集

fix-jsonl-surrogates

通用与其它

查看项目

更新于 10-16 06:41

技能介绍

用途:修复 Claude Code 聊天 JSONL 文件中的孤立 Unicode 代理项,这类字符会让 Anthropic API 拒绝请求并报「invalid high surrogate in string」。背景是 Node.js 内部使用 UTF-16,JSON.stringify() 不校验代理对,来自文件读取、终端输出或网页内容的孤立代理项可能被序列化为 \uD8xx。Windows 上常见触发源包括代码注释或终端输出中的 emoji、构建日志中的制表符绘制字符、以及编码损坏的网页内容。

主要能力:脚本以 errors='surrogateescape' 读取文件,解析 JSON 并递归检查所有字符串值中的代理码点,用 str.encode('utf-8', 'surrogatepass').decode('utf-8', 'replace') 将孤立代理项替换为 U+FFFD,修改前会备份为 .bak,并输出发现与修复摘要。脚本支持单个文件、会话目录或整个项目树。

使用方式:定位会话可用 grep -rl "req_XXXXX" ~/.claude/projects/*/。扫描单个文件及其会话目录:python {SKILL_DIR}/scripts/fix_surrogates.py <path-to-file.jsonl>;先试运行:加 --dry-run --verbose;扫描项目目录:python {SKILL_DIR}/scripts/fix_surrogates.py ~/.claude/projects/<project-dir>/;递归含子代理文件:再加 --recursive。{SKILL_DIR} 需替换为该技能目录实际路径。

限制与注意:代理项常是瞬时的,可能只存在于 Node.js 构造请求时的内存中而非存储的 JSONL;若脚本未发现任何内容,说明错误是瞬时的,重试会话即可。脚本会自动扫描主 JSONL 及会话目录中的子代理文件和工具结果缓存,且具幂等性,可安全重复运行。若脚本无发现但错误持续,可用 python {SKILL_DIR}/scripts/fix_surrogates.py ~/.claude/ --recursive --dry-run 扫描 CLAUDE.md、记忆文件等请求时加载的内容。上游问题见 anthropics/claude-code#44230。