Maka 依赖补丁治理实战解读 patches 目录的机制、语义与源码级原理【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本篇技术指南以 Apache MakaIncubating仓库根目录下的 patches/README.md 为骨架结合 scripts/apply-dependency-patches.mjs、package.json 以及packages/runtime、scripts/perf中的源码与测试系统讲解 Maka 如何通过patch-package对第三方依赖实施最小必要修补。读完你将掌握补丁从安装期到运行期的完整应用链路、如何在依赖升级后安全重建补丁、当前 9 组补丁各自修复的底层缺陷及其源码依据以及什么条件下可以安全删除每一组补丁。补丁机制总览postinstall 时代的依赖修补链Maka 是一个以 npm workspaces 组织的多包 monorepo工作区包括packages/core、packages/runtime、packages/runtime-host、packages/cli、apps/desktop等见 package.json。第三方依赖一旦在安装后被修改普通的npm ci重新安装就会覆盖改动。Maka 的解决方案是把所有补丁集中存放在根目录patches/下在根postinstall阶段统一回放。安装期应用链路从 package.json 可以看到根脚本postinstall: node scripts/apply-dependency-patches.mjs node scripts/install-electron-with-retry.mjsscripts/apply-dependency-patches.mjs 是这个链路的实际执行者其核心逻辑可以概括为三步目录守卫若patches/目录不存在或不含任何*.patch文件直接以状态码 0 退出L41-L46。依赖探测通过createRequire(import.meta.url).resolve(patch-package/index.js)定位patch-package仓库固定为patch-package8.0.1见 package.json。若未安装则打印警告并跳过——因为npm ci --workspace name和npm ci --omitdev会安装一棵没有 devDependencies的树此时失败会破坏原本能正常工作的安装模式L21-L27 注释。严格回放以仓库根为工作目录执行patch-package --error-on-fail。--error-on-fail是关键开关补丁存在但无法干净应用时安装必须失败而不是静默跳过L58-L61。脚本注释还给出了一个跳过是安全的底气来源跳过场景下安装的树并不是发布产物每次 release 与 CI 都会执行完整的根npm ci且未打补丁的树会让 packages/runtime/src/tests/model-factory-tool-call-index.test.ts 变红——也就是说有一组回归测试天然充当补丁是否生效的哨兵。补丁的更新与重建流程原文档给出了补丁的常规更新路径这里结合仓库实际做完整展开直接在node_modules中编辑已安装的包node_modules/name运行node node_modules/patch-package/index.js name重新生成补丁文件升级依赖后先把仍然需要的编辑应用到新版本再重新生成补丁——这一点至关重要patch-package记录的是当前已安装的文件快照而不是旧的补丁文本直接对旧补丁做文本搬运在版本差异下通常无法应用在根目录执行一次npm ci或至少重跑node scripts/apply-dependency-patches.mjs验证补丁能干净回放。治理原则小而精而非大而全原文档明确提出两条铁律这也是patches/目录的长期治理准则保持目录精简优先使用依赖的已发布公开 API 编写产品代码只在阻塞发布且调用点无法绕开时才打补丁补丁意味着 fork 依赖的私有实现每多一个补丁就多一份升级成本因此必须把修补范围收敛到不得不改的地方。这两条原则贯穿下面每一组补丁的取舍逻辑。run2.1.4 与 ai-sdk/code-mode1.0.56执行预算语义的重塑这是整个patches/目录中技术含量最高的一组补丁涉及 Code Mode 沙箱的超时语义。问题本质墙钟截止时间会杀死异步宿主等待ai-sdk/code-mode运行 Maka 的代码单元cell时会等待 Runtime 侧的普通工具调用——包括用户交互这类可能持续很久的等待。上游默认的 wall墙钟超时模式用一个绝对截止时间中断这些等待导致模型正在等用户确认、却被超时强杀。解决方案opt-in 的timeoutMode: execution补丁引入的timeoutMode: execution把计费对象从墙钟时间换成累积的同步 QuickJS 执行时间异步等待宿主工具期间不再消耗预算VM 与正常的 Promise 完成顺序得以保留取消机制、worker 池与内存上限依然生效timeoutMode只改变超时的计量口径不放松资源边界wall 模式行为完全不变执行模式会拒绝同步宿主函数 / 模块加载器——Maka 恰好不暴露这类同步宿主能力因此无兼容性损失。补丁的实际消费端在 packages/runtime/src/code-mode.tsMaka 冻结的默认执行策略DEFAULT_CODE_MODE_EXECUTION_POLICY显式写有timeoutMode: execution与timeoutMs: 30_000同时给出 64 MiB 内存、2 MiB 最大栈、1 MiB 最大结果/工具输入/工具输出、maxBridgeRequests: 32、maxInFlightBridgeRequests: 8等一整套沙箱边界。调用方契约可到达的取消信号是硬性要求原文档特别强调了一个容易被忽略的语义约束调用方必须提供可到达的取消信号。若一个 guest Promise 永远不 settle即便当前没有任何挂起的 Host 工具调用其 Worker 也会一直保留到被取消为止——补丁不提供自动的存活期限或死锁检测器。这意味着产品侧要把AbortSignal正确贯穿到executeCodeCellcode-mode.ts 中通过AbortSignal.any([input.signal, fatalAbortController.signal])合成调用信号并依赖drainHostToolOperations在成功与失败两条路径上都等到宿主操作全部 settle。版本基线调整与 TypeScript 去耦补丁同时把run的引擎基线从20.19.0提升到22.19.0见 patches/run-2.1.4-source.diff并删除上游旧 Node 回退方案才需要的可选 TypeScript peer 依赖。原因有二Maka 使用 Node 原生node:module.stripTypeScriptTypes剥离类型无需第二套编译器上游的 peer 范围5.1.6 7与仓库锁定的 TypeScript 7 冲突仓库 devDependencies 为typescript: ^7.0.2见 package.json。SDK 侧补丁makaruntimeai-sdkcode-mode1.0.56.patch只是把这条策略转发到锁定的 workspace 安装路径node_modules/maka/runtime下的嵌套补丁不会给 Maka 增加任何 continuation、replay、结果排序或 Worker 池语义。从源码 diff 重建补丁的完整流程run-2.1.4-source.diff是对应于 run 补丁的可读源码 diff。要重建# 1. 检出上游 vercel-labs/run 的 run2.1.4 标签提交 0207eebde4fc9c04b35d8414773a7dea6c552115 # 2. 应用该 diff # 3. 以冻结锁文件、跳过脚本的方式安装依赖 pnpm install --frozen-lockfile --ignore-scripts --filter run... # 4. 构建 pnpm --filter run build然后把改动后的dist文件拷回已安装的 run 包用node node_modules/patch-package/index.js run重新生成。注意两点包清单package.json也要一并拷贝并且重新生成时要加--exclude ^$否则 patch-package 会忽略这次 manifest 改动。diff 中那个巨大的生成 hunk 是内联 Worker内含未改动的 WASM其内嵌的依赖声明保存在 patches/run-2.1.4-notices.md。回归测试矩阵回归覆盖集中在 packages/runtime/src/tests/code-mode.test.ts630 行原文档列出的关键用例包括长宿主等待 依赖Promise.race的进度推进慢工具不消耗执行预算快工具先胜出随后所有挂起工具被 await 收口L40-L77pending-host 计算超时执行预算只累计同步执行跨 await 的累积计算多次 await 之间累计的 CPU 时间会计入预算取消 / drain 与资源上限既有的取消与资源限制语义保持不回归。此外该套件还验证了沙箱安全性guest 拿不到process、require、fetch、WebAssembly、evalFunction构造被拦截、每个 cell 独立 fresh 全局上下文、沙箱console.log不会泄漏到宿主 stdout 等后者通过 spawn 子进程观测真实 stdout见 L214-L246。删除条件当发布的run版本原生支持相同的执行预算语义时可以同时移除这两个补丁与根 package.json 中的overridesai-sdk/code-mode → run: 2.1.4。xterm/xterm6.0.0隐藏终端的选区重绘风暴问题本质RenderService.handleSelectionChanged绕过了渲染器既有的隐藏暂停机制。当 DOM 终端处于隐藏状态时选区刷新依然会触发整屏重绘而零宽字符的度量没有缓存输出负载下会反复触发同步布局造成严重卡顿。补丁策略补丁保留最新选区并复用现有的 selection/full-refresh 标志在可见性恢复时统一绘制不停止 PTY、解析器或输出订阅。之所以只能打补丁而非调用点绕开是因为 xterm 没有公开 API 能在内部重绘发生前拦截它。补丁同时覆盖两个发布入口lib/xterm.js与lib/xterm.mjs及其 TypeScript 源码diff 中巨大的篇幅来自厂商压缩后的 bundle 行而非新增实现。可复现的验证脚本仓库在 scripts/perf/xterm-hidden-selection.mjs 提供了基于 CDP 的真实 Chromium 验证node scripts/perf/xterm-hidden-selection.mjs port脚本针对一次性 CDP 启用的 Electron fixture 运行分别加载lib/xterm.js与lib/xterm.mjs两个发布产物用真实的IntersectionObserver模拟可见性切换通过MutationObserver统计.xterm-rows的 DOM 变更——隐藏期间修改选区不应产生任何行变更恢复可见后无需再次写入即绘制最新选区。脚本对未打补丁的 bundle 会失败从而把回归钉死在补丁语义上。删除条件上游把选区变更路由到其 paused-render 契约且两个 bundle 的回归测试在无补丁时全部通过。earendil-works/pi-tui0.84.4粘贴字符串的复制放大问题本质编辑器撤销快照会对每输入一个单词时存储的所有粘贴字符串做深拷贝。一个 1 MiB 的粘贴随后敲 60 个词就会在内存里保留约 60 MiB 的重复文本——典型的复制放大内存泄漏。补丁策略编辑器现在复制其可变状态、行数组与粘贴 Map但共享不可变字符串。原有行为全部保留所有撤销步骤、粘贴重新编号、提交清理逻辑不变Input 使用的通用撤销栈也不受影响。之所以不能调用点修复是因为快照的创建与存储是私有实现没有公开的克隆策略可供产品代码配置。删除条件上游在撤销快照间共享不可变粘贴字符串。zod4.5.4递归 Schema 的解析上下文泄漏问题本质递归 schema 会把最后一次解析的上下文与桶保留在 schema 闭包中导致输入/输出对象图在 schema 的整个生命周期内无法被回收同时容器在同步解析抛错时包括经由 transforms 的环会把条目遗留在全局分配栈上。补丁策略把 memoization 保留在解析上下文内在finally中恢复分配状态包括重入解析期间挂起的外层分配递归环与共享别名仍使用既有的 per-parse memoization。回归测试是 packages/runtime/src/tests/zod-recursive-contract.test.ts覆盖两个发布入口ESM 与 CJS。删除条件上游在 ESM 与 CJS 两种产物中都发布完整解析状态释放。升级 Zod 前需要针对新 memoizer 与容器实现重新验证分配交接、重入解析、环/别名同一性。modelcontextprotocol/client2.0.0传输背压下的观察者生命周期问题本质挂起的传输发送在收到响应、中止、超时或连接关闭后仍会通过错误观察者持有已 settle 的请求参数与结果造成引用长期不释放。补丁策略ESM 与 CJS 两份补丁独立地限定取消观察者的作用域并在请求清理时撤销请求观察者持有的原生reject引用。行为细节保持精确迟到的发送错误仍会移除进度处理函数取消发送错误仍能到达onerror排队帧与连接行为保持不变。无法调用点修复的原因是SDK 的私有请求漏斗没有公开的观察者生命周期钩子。删除条件上游在传输背压下发布已 settle 的请求观察者。tufjs/models5.0.0 与 sigstore/core4.0.1Electron 43 的默认摘要回归问题本质这两个包的公开 ECDSA 校验路径依赖crypto.verify在收到undefineddigest 时由 Node 自行选择摘要算法。但 Electron 43 的 crypto 运行时会直接拒绝该调用抛出ERR_OSSL_EVP_NO_DEFAULT_DIGEST——结果是打包后的 Desktop 无法加载 Sigstore TUF 根也无法为更新验证 Rekor 与 DSSE 签名属于阻塞桌面端自动更新的发布级缺陷。补丁策略在两个共享的 crypto 接缝处显式选择 SHA-256覆盖 RSA/ECDSA同时保留 EdDSA 的无摘要校验路径。补丁按包分别管理tufjs/models5.0.0.patch与sigstore/core4.0.1.patch。删除条件对应包发布显式 SHA-256 校验且无补丁时 Electron 回归测试全部通过——每个补丁独立删除。node-pty1.2.0-beta.15Unix 下的文件描述符复用写入问题本质Unix 上CustomWriteStream通过 libuv 提交裸文件描述符写入。这些写入可能存活到 PTY 退出之后一旦描述符被操作系统复用就会写入无关文件——这是典型的使用后释放类安全问题文档标注关联上游 issue #2978。补丁策略写入保持同步落在 node-pty 的非阻塞 PTY master 上重试前检查fstat指纹验证描述符仍然指向同一个文件尝试之间让出执行权yield在原生退出栅栏处取消整个队列。删除条件node-pty 发布等价的 Unix 写入生命周期修复。ai-sdk/provider-utils5.0.40流式工具调用的 index/id 关联问题本质某些网关Ollama 风格以及 Anthropic→OpenAI 转换器会重用或省略流式工具调用块中的index/id字段导致流式分片无法正确关联到同一个工具调用。补丁策略为这些场景补齐工具调用关联守卫。相关讨论见上游 issue #1967 / #1976回归测试在 packages/runtime/src/tests/model-factory-tool-call-index.test.ts——该测试同时充当补丁哨兵未打补丁的树会在此变红见 scripts/apply-dependency-patches.mjs。删除条件该守卫在未打补丁的包上通过。astryxdesign/core0.5.2最大的一组多 hunk 修补这是目录中 hunk 最多的一组补丁覆盖 UI 层的多处行为缺陷分为缺陷修复与宿主语义透传两类。缺陷修复类共享代码 tokenizer 缓存无效语言定义缓存null会让进程生命周期内的 Map 不断增长短标签可能是切片字符串卸载后仍保留整条 Markdown 消息。补丁后未知标签保持纯文本回退已知语言继续复用已编译的正则。调用点无法替代——语言过滤会复制依赖的语言表、丢弃展示标签且会漏掉共享的 CodeEditor 路径。CodeBlock稳定几何代码块保留 memoized 行分块但布局时未使用推测的内在高度intrinsic heights首次可见时替换这些估计值会改变 transcript 滚动范围#5184。补丁要求保持 layout/style/paint 隔离性。默认模式下的几何 CI 覆盖 1200 行且无任何 ablation 覆盖。ChatComposerInput同步时序外部受控值在 layout effect 中同步进可编辑 DOM而 passive effect 会在已发送消息渲染后的一帧内仍显示旧多行草稿随后清除时收缩 dock、挪动已定位的 transcript。补丁后既有的 echo 与选区守卫保持不变。apps/desktop/stories/app-shell.stories.tsx中的短、多行、高与补全提交 stories 保护这一布局契约。宿主语义透传类ChatLayout.autoScroll转发既有 hook 的enabled选项让 Maka 的 transcript 权威接管滚动不与依赖的自动跟随监听与写入竞争ChatToolCalls需要一个稳定的行槽位供产品样式与 E2E 几何使用List必须把公开的aria-label转发到渲染出的列表元素SideNavItem需要在导航控件与嵌套项之间放一个可交互的trailingAction兄弟节点——endContent渲染在主控件内部而SideNavItem外部的兄弟只能出现在项目控件之前或所有任务之后都得不到任务栏使用的视觉 Tab 顺序DropdownMenuItem必须转发aria-busy到其行composer 的 Skills 入口在 Skill 目录刷新期间保持外观不变并推迟激活没有该属性时无障碍技术会播报available并静默忽略点击。流式文本的settledText接缝流式文本与 Markdown 暴露显式settledText接缝渲染器可以据此校验并推进已经展示过的精确前缀而不重放。默认行为对全新流保持渐进式被改写或更晚出现的文本仍在解析可见边界处淡入淡出。Markdown 还允许在既有增量解析器之前立即变换已展示前缀使数学公式等宿主语法保持在流式光标之后无需新增解析器或调度器。一个几何修复frosted dock 层的密度常量ChatLayout的毛玻璃 dock 层是每密度常量80/100/120px而它淡出的 dock 由内容决定尺寸。balanced密度下 100px 层从 90px 处开始盖在不透明 composer 上斜坡在 composer 绘制处不可见dock 下 134px 的 transcript 始终清晰——渐变只在 composer 两侧的沟槽里出现。补丁让该层填满 dock 容器并置于其 chrome 之后滚动按钮在上方依然清晰。产品层无法覆盖该层仅用stylex.props()渲染没有themeProps、data-*或自定义属性唯一句柄是结构选择器一旦调用方传scrollButton{null}就失效#3446。删除条件每个 hunk 在 Astryx 上游发布对应行为后独立删除。回归防线补丁不是一次性 hack纵观全部补丁可以总结出 Maka 依赖修补工程化的三个可复用特征每条补丁都配有可执行防线code-mode.test.ts验证执行预算语义zod-recursive-contract.test.ts覆盖两个发布入口model-factory-tool-call-index.test.ts充当安装哨兵xterm-hidden-selection.mjs用真实 Chromium 复现选区回归app-shell.stories.tsx保护布局契约每条补丁都有明确的删除条件原文档逐条写清了上游需要发布什么能力、什么测试需在无补丁时通过把技术债显式登记为可追踪的升级清单修补范围被严格限定语义性修补如timeoutMode集中在一个 opt-in 选项上wall 模式与既有资源限制完全不动纯转发性补丁SDK patch明确声明不引入新行为。对维护者而言patches/目录的日常动作收敛为三条命令升级依赖后编辑node_modules中对应包 →node node_modules/patch-package/index.js name重建 → 跑一遍node scripts/apply-dependency-patches.mjs或完整npm ci与相关回归测试确认哨兵不变绿。这套机制让 Maka 在锁定的 Node 22.19 基线上既能及时跟进上游修复又能把 fork 私有实现的范围和退出路径都保持透明可控。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考