# 纸上春秋 · 学习笔记 — 全文聚合 > 全部公开笔记正文,生成时间 2026-11-14T14:28:43.501Z,共 4 篇。 本站为个人学习笔记,内容仅供参考,不构成法律、医疗、金融、安全等专业建议。 部分内容经 AI 辅助整理,已尽量人工校对;仍可能存在错误、遗漏或过时信息,请以官方文档与实测结果为准。 文中命令、配置与代码请自行评估风险,并在受控环境执行;因使用本内容造成的损失,作者不承担责任。 第三方产品名称与商标归各自所有者,提及不代表背书;外部链接内容不受本站控制。 版权:保留所有权利。引用、转载须注明出处(标题 + 站点名 + 原文 URL),不得删改后冒用。 纠错与联系:https://zhishangchunqiu.cn/about(含举报入口)。 内容可能随时更新或删除,不另行通知。 ============================================================================== # Claude 5.x 在 OpenAI 兼容中转上返回 400:一条规则表的修法 URL: https://note.zhishangchunqiu.cn/ai/claude-5x-adaptive-thinking 分类: 人工智能 | 日期: 2026-11-12 | 标签: Claude、API、排错、OpenAI 兼容 ------------------------------------------------------------------------------ # Claude 5.x 在 OpenAI 兼容中转上返回 400:一条规则表的修法 ## 结论先说 报错不是账号问题、不是网络问题、也不是"思考等级"开关没关。 真正的原因:桌面端内置的模型目录里,有一条对所有 **OpenAI 兼容渠道**生效的通用规则,把思考等级翻译成 `thinking.type = "enabled"`;而新模型只接受 `adaptive` 或干脆不带 `thinking`。 修法是往规则表末尾追加一条优先级更高的规则,把这几个模型的映射改成 `thinking.type = adaptive` + `output_config.effort`。**不用改代码、不用改密钥。** ## 错误原文 ```text status_code=400 claude-opus-5-5 requires adaptive thinking; omit thinking or use thinking.type=adaptive and output_config.effort (request id: 2026...) ``` 上下文: | 项目 | 值 | | --- | --- | | 请求模型 | `claude-fable-5.1`(中转侧实际落到 `claude-opus-5-5`) | | 端点 | `/v1/chat/completions` | | 渠道类型 | `openai-chat-completions` | | 同渠道可用 | `claude-opus-4.6`、`claude-fable-5` | 同渠道旧模型正常、新模型 400,基本就把范围缩小到"请求形状"而不是"账号/额度/网络"。 ## 工具与源码 - GitHub 仓库(图形化工具 + 命令行脚本 + 规则原文 + 单元测试): - v1.0.0 Release(含 zip 包): ## 第一步:把真实请求体拿出来 桌面端会把每次模型请求落盘(模型调用轨迹),格式是 JSONL,一条记录里带 `request.body`: ```text <应用数据目录>/cli/rollout/model-io-sess_.jsonl ``` 从里面能直接看到出事时发出的字段: ```json { "thinking": { "type": "enabled" }, "enable_thinking": true, "reasoning_effort": "max", "reasoning": { "effort": "max" } } ``` 对照上游要求,问题就明确了:`type` 应该是 `adaptive`,而不是 `enabled`;effort 应该放在 `output_config` 里。 这一步很重要——它把"猜"变成了"读"。后面所有验证都以这份请求体为准。 ## 第二步:排除三个常见误判 排查时先后试过、并且都**无效**的做法: | 尝试 | 为什么无效 | | --- | --- | | 改 `ZCODE_STORAGE_DIR` | 它只影响 `cli/exec`、剪贴板等零散目录,与请求体无关 | | 改桌面数据根 `dataBaseDir` | 只管桌面配置/任务索引,不参与模型请求 | | 反复重启、换 key、关思考 | 请求体形状不变,400 依旧 | 真正决定字段的是模型目录里的**推理等级映射**,属于数据,不在设置里。 ## 第三步:找到规则表 ```text <安装目录>/resources/glm/provider/zcode-builtin.json ``` 结构大致是: ```json { "config": { "modelConfigRules": { "modelApiRules": [ { "modelMatch": ".*", "apiTypeMatch": "openai-chat-completions", "config": { "optionSpecs": { "reasoningLevel": { "map": "..." } } } } ] } } } ``` 那条 `modelMatch: ".*"` 的通用规则就是元凶,它的 map 把等级翻译成: ```json { "thinking": { "type": "enabled" }, "enable_thinking": true, "reasoning_effort": "", "reasoning": { "effort": "" } } ``` 关键机制:规则按数组顺序加载并逐层 overlay,**后出现的规则会覆盖前面同名字段**。所以不需要动内置规则,只要在末尾追加一条更窄的规则。 ## 第四步:追加覆盖规则 ```json { "modelMatch": ".*(?:claude-fable-5[.\\-][1-9]|claude-opus-5(?:[.\\-]\\d)?)(?:[.\\-:/\\[].*)?", "apiTypeMatch": "openai-chat-completions", "config": { "optionSpecs": { "reasoningLevel": { "map": "reasoningLevel == \"disabled\" ? {} : { \"thinking\": { \"type\": \"adaptive\" }, \"output_config\": { \"effort\": reasoningLevel == \"enabled\" ? \"high\" : reasoningLevel } }" } } } } ``` 三条设计取舍: 1. **正则只圈新模型**。`claude-fable-5`(无 `.1`)、`claude-opus-4.6`、`gemini-*`、`deepseek-*` 都不命中,避免把能用的渠道改坏。 2. **`disabled` 返回 `{}`**。上游明确说"omit thinking"是合法写法,关思考时不发字段最稳。 3. **保留 `adaptive` + `output_config.effort`**。这样思考等级还能用,不是靠"关掉功能"绕过错误。 ## 第五步:验证 改完至少做三层验证,缺一层都可能白折腾: ```text 1) 正则范围:只命中 claude-fable-5.1 / claude-opus-5,不命中 4.6 和 gemini 2) 表达式可编译:用 Node 把 map 求值三种等级,得到预期对象 3) 落盘后再解析一遍 JSON,确认文件没写坏 ``` 映射结果: | 等级 | 请求体新增字段 | | --- | --- | | `enabled` | `thinking:{type:"adaptive"}`、`output_config:{effort:"high"}` | | `low`/`medium`/`high`/`max` | `thinking:{type:"adaptive"}`、`output_config:{effort:"<原值>"}` | | `disabled` | 无 | 然后**重启应用**(catalog 只在启动时读),再发一次请求,回到"第一步"看落盘请求体是否变化。以落盘为准,不以界面显示为准。 ## 兜底 如果中转站不认 `output_config`(表现为未知字段错误),把 map 换成: ```json {} ``` 也就是彻底不带 thinking。这是上游错误信息里给出的另一条合法路径,代价是这次请求没有扩展思考。 ## 可复现的最小操作 图形化: ```bat start-gui.cmd ``` 命令行: ```bat python fix_catalog.py status python fix_catalog.py apply adaptive python fix_catalog.py apply omit REM 兜底 python fix_catalog.py revert REM 回滚 ``` 所有写操作都会先备份成 `zcode-builtin.json.bak-<时间戳>`;`revert` 用最近一份备份覆盖回来。应用升级可能重置这个文件,升级后重跑一次即可。 ## 经验总结 - **先拿真实请求体,再谈原因。** 有落盘记录就不用猜;没有的话优先找请求日志或抓包。 - **区分"配置"和"数据"。** 环境变量、设置项、规则表三层各自管什么,改错层再多次重启也没用。 - **优先追加覆盖,不改内置。** 覆盖规则可以回滚、可以按模型收窄,改内置则要和版本升级赛跑。 - **用正则收窄影响面。** 同一条通用规则服务所有渠道,修复必须只对目标模型生效。 - **验证要以"发出去的字节"为准。** 界面上思考开关亮着,不代表请求体里字段对。 ## 边界 本方法针对**带外部 catalog 的桌面版**。单文件打包的 13 MB 版本把同样的映射编进了 bundle,没有外部 catalog,需要另行打补丁;原理相同,只是要改的是代码而不是 JSON。 ============================================================================== # 把 ZCode 数据根迁到 F 盘:为什么改环境变量没用,junction 才是解 URL: https://note.zhishangchunqiu.cn/programming/windows-zcode-data-migration 分类: 编程 | 日期: 2026-11-12 | 标签: ZCode、Windows、存储迁移、junction ------------------------------------------------------------------------------ # 把 ZCode 数据根迁到 F 盘:为什么改环境变量没用,junction 才是解 ## 结论先说 报错是 `database or disk is full`,但内存/CPU 都正常,原因是 C 盘只剩 1 GB 出头,而应用的数据根占着 10.7 GB 且**不在**设置里。 关键认知:**设置环境变量只能搬一部分**。真正吃空间的是硬编码在 `%USERPROFILE%\.zcode` 下的数据库、日志和设置。要一次性全部搬走,得用 NTFS **目录联接(junction)**:把真实目录移到新盘,再让原路径指向它。 ## 现象 ```text Turn execution failed database or disk is full ``` 同一时段还有衍生错误: ```text usage.tool.write.failed database or disk is full ``` 这类报错有个特征:**不影响读,只影响写**。会话还能翻,但新消息、用量记录、工具结果落不了盘。因为 SQLite 在 WAL 模式下追加事务时磁盘没有余量。 ## 第一步:先确认到底是哪套目录 同一次排查里发现同一个应用至少有 **三套互不相干**的"根目录": | 开关 | 实际作用 | | --- | --- | | `ZCODE_STORAGE_DIR` | `cli/exec`、剪贴板、打包工具解包目录 | | 桌面数据根(`dataBaseDir` / `*_DATA_BASE_DIR`) | 桌面配置、任务索引、主日志 | | 代码里硬编码的 `~/.zcode` | **会话数据库、运行日志、设置文件** | 前两者走配置,第三个走代码。所以: - 只设环境变量 → 数据库和日志照旧写 C 盘; - 只改桌面数据根 → 同上; - 反复重启、换 key、清缓存 → 完全没用。 验证办法很简单:看文件更新时间。 ```text cli\db\db.sqlite-wal ← 数据库还在 C 盘增长 cli\log\zcode-<日期>.jsonl ← 日志还在 C 盘增长 cli\exec\... ← 这个才跟着环境变量走 ``` 一眼就能看出"哪些文件不听话"。 ## 第二步:为什么不能只拷 SQLite 直接把 `db.sqlite` 拷到 F 盘、再改个配置指过去,是行不通的——代码里路径写死,没有可改的开关。 而且即使能改,也有坑: - WAL 模式下,已提交事务可能还在 `-wal` 文件里,只拷主库会丢数据; - 应用运行时拷贝,文件句柄和事务状态都不一致; - `-shm` 是共享内存索引,跟主库版本必须匹配,不能随便留下旧文件。 安全做法只有两类:**停机拷贝**,或**用 SQLite 在线备份接口**(`sqlite3.Connection.backup`),后者可以在应用运行时拿到一致快照。 ## 第三步:用 junction 让路径"就地搬家" 思路是把 `%USERPROFILE%\.zcode` 变成一个指向新盘的目录联接: ```text 1. 完全退出应用(含托盘进程、agent 子进程) 2. 把整个 ~/.zcode 复制到 F:\ZCodeData\.zcode 3. 校验:文件数、字节数、SQLite PRAGMA integrity_check 4. 把原目录改名成 .zcode.rollback-<时间戳>(保留可回滚) 5. mklink /J "C:\Users\\.zcode" "F:\ZCodeData\.zcode" 6. 启动应用,确认新写入落在 F 盘 ``` 命令只有一条: ```bat mklink /J "C:\Users\\.zcode" "F:\ZCodeData\.zcode" ``` 之后所有硬编码 `~/.zcode` 的代码都会透明地读写 F 盘,不需要改程序,也不需要管理员权限(`/J` 不需要)。 ## 第四步:验证"真的搬过去了" 不要看界面提示,看文件: | 检查项 | 通过标准 | | --- | --- | | 路径属性 | `C:\Users\\.zcode` 是 `ReparsePoint`,Target 指向新盘 | | 新盘目录 | 是普通目录(数据真的在那) | | 写入落点 | 新日志/`db.sqlite-wal` 的 mtime 在增长,且 C/F 两个视角看到同一文件 | | 回滚副本 | mtime 停在切换前,不再增长 | | 数据库 | `PRAGMA integrity_check` 返回 `ok` | 本次实测:7,717 个文件 / 10.77 GB;切换后 `db.sqlite-wal` 与日志持续更新,回滚副本保持静态,两个库 `integrity_check` 都是 `ok`。 ## 第五步:写工具时踩到的坑 手搓一遍之后就把它做成了图形化工具,过程中有几个必须处理的细节: 1. **不要在应用运行时改 SQLite 目录**。复制可以,切换不行;切换前必须确认进程全部退出(托盘的"关闭"往往只是隐藏窗口)。 2. **删联接不能递归**。`rmdir /s` 会把**目标盘的真实数据**一起删掉;只能用 `rmdir`(无 `/s`)或 `os.rmdir`。 3. **遍历要跳过重解析点**,否则目标里再有联接就会自循环。 4. **保留回滚副本**。迁完先留 `.zcode.rollback-*`,跑一两天没问题再删;删之前 C 盘的 10.7 GB 不会释放。 5. **预检查同盘**。目标与源在同一分区时迁移毫无意义,应该直接拒绝。 ## 可复现工具 图形化(tkinter,零依赖)与命令行都在同一个仓库,包含预检、增量同步、SQLite 校验、改名回滚、建联接、恢复原状: - GitHub: - 用法:`start.cmd` 打开界面,或 `python app.py` 界面里的按钮顺序就是上面的步骤;「执行切换」会把关闭应用 → 同步 → 校验 → 改名 → 建联接 → 启动串起来,任何一步失败都会中止而不是留下半切换状态。 ## 经验总结 - **报错位置不等于问题位置。** `database or disk is full` 是结果,原因往往是某个目录悄悄长到把盘吃满。 - **先搞清楚"哪个开关管哪部分"。** 一个应用同时存在环境变量、桌面配置、硬编码路径三套根目录,很常见。 - **改代码路径不如改文件系统语义。** junction 让硬编码路径"就地生效",比逐个打补丁可靠。 - **验证要看写入。** 路径改了不代表写过去了,必须看 mtime 和文件大小在不在变化。 - **回滚副本先留着。** 空间紧张时最容易冲动删备份,出了问题就没退路。 ## 边界 - 仅 Windows(`mklink /J`)。 - 只迁移用户目录下的数据根;桌面配置根(`dataBaseDir`)是另一个独立开关,需要单独处理。 - 联接对备份/杀软工具可能表现为"重复计数",属正常现象。 ============================================================================== # 在浏览器里批量解码 HEIC:libheif WASM 的四个坑和一个 4.5MB 的内存方案 URL: https://note.zhishangchunqiu.cn/programming/web/heic-wasm-batch-decode 分类: Web | 日期: 2026-11-01 | 标签: HEIC、WebAssembly、libheif、前端、内存优化 ------------------------------------------------------------------------------ # 在浏览器里批量解码 HEIC:libheif WASM 的四个坑和一个 4.5MB 的内存方案 HEIC 是 iPhone 默认的照片格式,但浏览器厂商出于专利原因普遍不支持。想让用户把 iPhone 照片拖进网页就转成 JPG,就得自己在浏览器里解码 HEIC。 能用的方案只有一个:[libheif](https://github.com/strukturag/libheif) 编译成 WASM,也就是 npm 上的 `libheif-js`。它确实能用,但文档几乎为零,实际接进去踩了四个坑。 先说结论:**一个 decoder 实例复用到底,每张图解码完立刻 `free()`,100 张图只增加 4.5MB 内存**。如果每张图 new 一个 decoder,100 张图的峰值是 195MB。 ## 坑一:默认导出不是对象,是工厂函数 大部分 WASM 库的用法是 `import libheif from 'libheif-js'` 然后直接用。libheif-js 不是。 ```js // ❌ 得到的 HeifDecoder 是 undefined import libheif from 'libheif-js/wasm-bundle'; const decoder = new libheif.HeifDecoder(); // TypeError // ✅ 要先调用一次拿到实例 const mod = await import('libheif-js/wasm-bundle'); const libheif = typeof mod.default === 'function' ? await mod.default() : mod.default; const decoder = new libheif.HeifDecoder(); ``` `await mod.default()` 这个调用是初始化 WASM 运行时。它返回 Promise,不 await 就会拿到一个空壳。 如果是 Vite / esbuild 打包,还需要把 libheif 的 bundle 作为 external 保留,用动态 `import(url)` 加载,否则打包器会试图解析它的内部路径然后失败。 ## 坑二:display() 是异步回调,不是返回值 其他解码库一般是 `const imageData = decoder.decode(buffer)`。libheif 不是: ```js // ❌ 拿到的 pixels 是空的 img.display({ data: out, width: w, height: h }, () => {}); console.log(out); // 全黑或全透明 // ✅ 必须等回调 await new Promise((resolve, reject) => { img.display({ data: out, width: w, height: h }, (result) => { if (!result) return reject(new Error('decode failed')); resolve(); }); }); ``` `display()` 内部用 `setTimeout` 把实际的像素拷贝推迟到下一轮事件循环。如果不等待回调就读 `out` 缓冲区,读到的是上一张图的残留数据,或者全黑。 这个坑很隐蔽:**单张图测试时不一定出错**,因为同步路径有时能跑完;批量处理时才稳定复现。 ## 坑三:is_primary 会指向 150×150 的缩略图 HEIC 文件内部可以有多张图:主图、缩略图、深度图等。直觉上应该用 `is_primary()` 挑主图: ```js const imgs = decoder.decode(buffer); const primary = imgs.find(x => x.is_primary()); ``` 但实测有照片的 `is_primary` 标记指向一个 150×150 的缩略图,直接对它调 `display()` 会失败或者得到一张缩略图。 原因不深究(不同编码器的写出行为不一致),解决办法是按面积加权,只在 `is_primary` 的图**足够大**时才信它: ```js const imgs = decoder.decode(buffer); const primary = imgs.find(x => x.is_primary && x.is_primary()); const largest = imgs.reduce((best, x) => { const ax = x.get_width() * x.get_height(); const bx = best ? best.get_width() * best.get_height() : 0; return ax > bx ? x : best; }, null); const primPixels = primary ? primary.get_width() * primary.get_height() : 0; const largestPixels = largest ? largest.get_width() * largest.get_height() : 0; // 主图至少要有最大图的 25%,否则认为标记不可信,用最大的 const chosen = (primary && primPixels >= largestPixels * 0.25) ? primary : largest; ``` 按这个规则,一批 34 张图里那张解码失败的 C039.heic 也通过了,最终 34/34 全部成功。 ## 坑四:free() 的时机决定成败 libheif 的每张子图都要手动 `free()`,否则 WASM 堆会一直涨。但**在哪一刻 free** 很关键: ```js // ❌ 先 free 再 resolve —— 成功数从 34 掉到 33 img.display({...}, (result) => { freeAll(imgs); resolve(result); // 此时缓冲区可能已被回收 }); // ✅ 先 resolve 再 free img.display({...}, (result) => { resolve({ data: out, width: w, height: h }); freeAll(imgs); // 在 resolve 之后 }); ``` 看起来反直觉,但 `resolve` 只是把 Promise 标记为完成,后续的 `.then()` 是微任务。只要 free 放在 `resolve` 之后,调用方拿到的 `out` 缓冲区仍然是有效的。 ## 内存:从 195MB 到 4.5MB 前三坑解决后功能通了,但批量处理 100 张图时浏览器直接 OOM。原因是每个文件都 new 一个 decoder: ```js // ❌ 195MB(100 张) for (const file of files) { const decoder = new libheif.HeifDecoder(); // 每次都初始化 WASM const imgs = decoder.decode(await file.arrayBuffer()); ... } ``` `HeifDecoder` 的构造会实例化一套 WASM 上下文,几十上百次累积起来非常可观。改成单个实例复用 + 输出缓冲区复用: ```js // ✅ 4.5MB(100 张) const decoder = new libheif.HeifDecoder(); // 全局只建一次 let out = null; // 输出缓冲区也复用 for (const file of files) { const imgs = decoder.decode(new Uint8Array(await file.arrayBuffer())); // 按坑三的规则挑图 const img = pickImage(imgs); const w = img.get_width(), h = img.get_height(); const need = w * h * 4; // 缓冲区够大就复用,只在需要更大时才重新分配 if (!out || out.length < need) out = new Uint8ClampedArray(need); await new Promise((resolve, reject) => { img.display({ data: out, width: w, height: h }, (result) => { if (!result) { freeAll(imgs); return reject(new Error('decode failed')); } resolve(); freeAll(imgs); }); }); // out 里的像素已经是 RGBA,直接画到 canvas 导出 JPG/PNG ctx.putImageData(new ImageData(new Uint8ClampedArray(out.buffer, 0, need), w, h), 0, 0); const blob = await canvas.convertToBlob({ type: 'image/jpeg', quality: 0.92 }); results.push(blob); } ``` 关键就三点: 1. **decoder 全局一个**,不要 per-file 2. **输出缓冲区复用**,只在尺寸变大时才重新分配 3. **每张图 free 掉 imgs**,且放在 `resolve` 之后 100 张实测下来峰值内存增量约 4.5MB,处理过程中浏览器完全流畅。 ## 顺带一提:Live Photo Live Photo 是一对文件:`.heic`(静图)+ `.mov`(约 3 秒视频)。要做成 GIF 或 MP4,得先按文件名配对,再把 MOV 拆帧。 MOV 解码不能靠 libheif,要用 `