open-codesign Tweak 编辑链路根因修复指南:从 UI 控件到 EDITMODE 文件更新的全链路追踪与持久化原理

原创2026-09-27 09:39:041,704 阅读
文章标签:人工智能AI 应用桌面应用

open-codesign Tweak 编辑链路根因修复指南:从 UI 控件到 EDITMODE 文件更新的全链路追踪与持久化原理

导读

本文围绕 open-codesign 仓库中 .Codex/workspace/tweaks_root_fix_plan.md 这份"Tweak Editing Root Fix Plan"计划文档展开,讲解如何追踪并修复"Tweak 面板修改控件 → 更新产物源码中的 EDITMODE 声明块 → 预览 iframe 即时刷新"的完整链路。读完本文,你将掌握 EDITMODE/TWEAK_SCHEMA 标记协议的规范格式、tweaks 工具的扫描语义、渲染器面板的 live-token 工作流、防抖持久化的并发安全设计,以及如何用聚焦的失败测试驱动"契约层"(而非面板表面)的修补,并最终验证修复。

一、修复目标:让面板真正改到产物文件

计划文档的开篇 Goal 说得非常直白:

Make the tweaks panel actually edit workspace artifacts by tracing and fixing the full path from UI control changes to EDITMODE file updates and preview refresh.

即:让 Tweak 面板的每一次控件变化,都能真实地落到工作区产物文件(workspace artifact)中的 EDITMODE 块上,并触发预览刷新。所谓"全链路"包含四个环节:

  1. UI 控件变化(renderer 侧 TweakPanel 产生新的 token 值);
  2. 预览桥接(postMessage 到 iframe,更新运行时 token 并重渲染);
  3. IPC/文件 API(把新 token 写回工作区源码文件);
  4. pending tweak delta 处理(防抖队列、基线 rebase、并发/生成冲突取消)。

这份计划同时给出了研究约束:docs/ 目录被 gitignore 且不在当前 worktree 中,因此产品上下文需要回到原始 checkout(/Users/haoqing/Documents/Github/codesign/docs)阅读,仓库内则以源码与测试为准。

二、EDITMODE 标记协议:面板与文件之间的"契约"

链路修复的前提是理解协议本身。核心定义在 packages/shared/src/editmode.ts:

  • 产物源码中嵌入一个 const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{...}/*EDITMODE-END*/; 形式的 JSON 对象,作为 agent 声明的可调默认值;
  • 标记(marker)是 /*EDITMODE-BEGIN*/ 与 /*EDITMODE-END*/,标记之间的内部区间被解析为 JSON 对象字面量;
  • 标记之间的空白在往返改写时被保留,parseEditmodeBlock 只做 JSON 解析,不执行任何 JavaScript;
  • token 值只允许 string | number | boolean 三种原始类型;
  • 缺少标记 = "没有 tweak 块";标记存在但内部 JSON 损坏 = 协议错误(抛 ARTIFACT_PROTOCOL_INVALID);
  • replaceEditmodeBlock(source, newTokens) 用 JSON.stringify(newTokens, null, 2) 序列化后替换标记区间,实现无损改写。

协议解析严格性在 tweaks.ts 的扫描逻辑中体现:inspectTweakSource 对每个文件分类为 ready / empty / missing / invalid,而 tweak-source.ts 中的 inspectTweakSource 会进一步做类型、枚举项、数值范围的交叉校验(例如 number 必须满足 min/max/step 约束)。此外还有一条重要的不修复策略:ensureEditmodeMarkers 在 v0.2 中已退化为原样返回——agent 必须自己按规范协议输出标记,运行时不再代为修补缺失标记。

三、TWEAK_SCHEMA:面板控件的形状声明

与 TWEAK_DEFAULTS 平行,agent 可以再声明一个 TWEAK_SCHEMA 块,为每个 token 指定 UI 控件形状(editmode.ts):

const TWEAK_SCHEMA = /*TWEAK-SCHEMA-BEGIN*/{
  accentColor: { kind: "color" },
  radius: { kind: "number", min: 0, max: 32, step: 2, unit: "px" },
  theme: { kind: "enum", options: ["light", "dark"] },
  dense: { kind: "boolean" },
  label: { kind: "string", placeholder: "输入提示" }
}/*TWEAK-SCHEMA-END*/;

受支持的 entry 类型与字段(依据 validateEntry):

kind 可选字段 面板控件
color — 取色器
number min(默认 0)、max(默认 100)、step(默认 1,必须 > 0)、unit 真实范围滑块
enum options(非空字符串数组) 分段选择器
boolean — 开关
string placeholder 文本框

Schema 是**咨询性(advisory)**的:entry 可以省略,但一旦出现 TWEAK-SCHEMA-BEGIN/END 标记,其内部必须是合法 JSON 且每个 entry 形状有效,否则整块被判为 invalid。replaceTweakSchema 支持覆盖已有块,或在 TWEAK_DEFAULTS 语句之后插入新块,若源码连 EDITMODE 块都没有则原样返回。

四、tweaks 工具:跨文件 EDITMODE 聚合扫描器

packages/core 中实现了一个同名的 agent 工具(tweaks.ts),其语义有三个关键点:

  1. 只读扫描,不创建控件、不持久化、不绑定预览——工具描述中反复强调这一点,避免 agent 误以为扫描结果会自动注册控件;
  2. 默认按 ['**/*.html', '**/*.jsx', '**/*.css', '**/*.js'] 读取工作区文件,可通过 patterns 参数覆盖;
  3. 返回结构化的 TweaksDetails:blocks(每文件 token 包)、fileCount、scannedFileCount、missingFiles、invalidFiles。

两个纯函数 parseTweakBlocks 与 aggregateTweaks 分别产出"按文件分组"与"扁平 {file, key, value} 三元组"两种形态,供不同宿主选择。工具文案特别提示:"渲染器只读取当前激活预览源码;未使用 starter 中的控件不会影响它"——这与 tweaks.test.ts 中"不暗示无关 starter 控件在 App.jsx 中可用"的用例互相印证。

五、TweakPanel 与预览桥:live token 双通道设计

5.1 两条通道:即时预览 vs 持久化

面板核心实现在 TweakPanel.tsx。它对当前预览源码调用 inspectTweakSource 得到 { block, schema },并把 block.tokens 复制进本地 liveTokens 状态作为"实时工作副本":

  • 即时通道:liveTokens 变化后立刻通过 iframeRef.current.contentWindow.postMessage({ type: 'codesign:tweaks:update', tokens: liveTokens }, '*') 推给预览 iframe,避免每次按键都触发一次完整 srcdoc 重载;
  • 持久化通道:同一份 liveTokens 进入防抖队列,最终写回工作区源码文件,使重载/快照/导出能看到已调好的状态。

面板还监听 iframe 回发的 codesign:tweaks:compatibility 消息并弹出提示(TweakPanel.tsx)。

5.2 iframe 内桥接:免重载重渲染

packages/runtime 的 tweaks-bridge.ts 以字符串形式随构建注入 srcdoc,解决了"每次编辑都整页重载"的性能痛点(注释给出量级:~300–500ms 空白闪烁)。其机制为:

  • 用 Object.defineProperty 在 window.__codesign_tweaks__.tokens 上定义可枚举访问器属性,保持 structuredClone/JSON 兼容;
  • 监听 message 事件中的 codesign:tweaks:update,调用 applyTokens 替换 token 集合并调度下一帧重渲染(requestAnimationFrame);
  • 每个 token 还被映射为 --ocd-tweak-<kebab-case> CSS 自定义属性(applyCssVars),字符串/数字原样、布尔值映射为 1/0;
  • 保留组件类型与模块作用域,不重新执行模块,从而不丢弃 hook 状态——但检测到 memoization 钩子或 memo 组件可能捕获旧 token 时,会退回到"兼容模式":重跑模块并回发 codesign:tweaks:compatibility 通知。

六、持久化层:并发安全的三道防线

面板的写回路径集中在 tweak-persistence.ts,全部为可单测的纯函数设计,对应测试见 tweak-persistence.test.ts。

6.1 防抖合并与串行化

createTweakPersistDebounce 维护一个 400ms 的 setTimeout 队列,保证同一时段内多次编辑只触发一次实际写盘;flush 阶段以 active 标志串行化慢保存,防止两次写并发交错。

6.2 基线 rebase:只承认自己的输出

写回成功后,rebaseTweakDraft(acceptedSource, submitted, draft) 以本次被接受的源码为新的基线:仅当草稿值不同于本次提交值时(即用户在我方保存期间又改了新值)才保留为待写状态(tweak-persistence.ts)。测试用例"serializes slow saves, coalesces edits, and rebases only on the accepted own output"验证了这一行为:三次快速编辑最终只产生两次写盘,且第二次写入的是基于首次保存结果的 rebase 值。

6.3 乐观并发校验与变更检测

mergeTweakTokenChanges 在真正写盘前做三类校验(tweak-persistence.ts):

  • 源变更检测:若某个 token 在源码中已被外部修改(当前值与基线不同且不等于本次新值),直接抛错要求"先重载控件再编辑";
  • 类型一致性:新旧值类型不一致(如字符串变成数字)抛 incompatible value type;
  • 范围/枚举约束:number 超出 min/max、非有限值,或 enum 值不在 options 内,均拒绝写入。

persistTweakTokensToWorkspace 还会先解析写目标(resolveTweakWriteTarget 依次尝试 DEFAULT_SOURCE_ENTRY、LEGACY_SOURCE_ENTRY,再沿预览源码解析真正的预览入口),并以 expectedContent 做原子写入的期望值。生成冲突保护:canWrite 闭包校验 currentDesignId 未变化且该设计没有正在进行的生成;一旦检测到生成开始,面板会取消待写、回滚 live tokens 并弹出 "Tweak save cancelled because generation started." 错误提示(TweakPanel.tsx)。

七、按计划落地:失败测试先行、修补契约层

计划文档给出的五个步骤本身就是一套可复现的工程方法论:

  1. 追踪 packages/core 的 tweak schema/工具解析——即本文第四、二、三节所述:parseTweakBlocks、aggregateTweaks、makeTweaksTool 与 parseEditmodeBlock/parseTweakSchema;
  2. 追踪 renderer 面板、预览桥、IPC/文件 API 与 pending delta 处理——即第五、六节:TweakPanel、tweaks-bridge、tweak-persistence;
  3. 先写一个聚焦的失败测试,证明"用户编辑更新了正确的 EDITMODE 块"——仓库里现成的正面用例包括 tweaks.test.ts(聚合与分类)、tweak-persistence.test.ts(rebase 与并发)、tweaks-bridge.test.ts(postMessage 协议与兼容模式);
  4. 修补底层契约而非仅面板表面——协议层(editmode.ts)、持久化层(tweak-persistence.ts)与桥接层(tweaks-bridge.ts)才是"根因"所在,控件渲染只是消费者;
  5. 跑定向单测与相关包类型检查——在 apps/desktop 中,测试命令为 pnpm test(vitest run),类型检查为 pnpm typecheck,等价于 tsc --noEmit -p tsconfig.node.json && tsc --noEmit -p tsconfig.web.json(见 apps/desktop/package.json)。

八、排查 Checklist:面板改了但文件没更新时按序检查

依据协议与源码结构,可将根因排查收敛为以下顺序:

  1. 源码是否真的含 EDITMODE 块? 用 parseEditmodeBlock 检查;若只有 EDITMODE-BEGIN 而无 END,inspectTweakSource 会报 EDITMODE requires matching BEGIN and END markers. 的 invalid 状态;
  2. schema 与 token 是否自洽? number 的 min/max/step、enum 的 options、值类型不一致都会使面板直接显示 invalid 提示(Tweak "key" does not match its declared control type, options, or range.);
  3. 写目标是否解析正确? 检查 resolveTweakWriteTarget 是否沿激活预览源码解析到了正确文件,而不是回落到 DEFAULT_SOURCE_ENTRY;
  4. 是否有 pending 队列未 flush? 确认 persistDebounce.hasPending() 为 false、saving 状态已复位;
  5. 是否触发并发/生成取消? 检查 canWrite 是否因 currentDesignId 变化或 generationByDesign 存在而拒绝写入;
  6. iframe 是否收到消息? 若预览未刷新但文件已更新,问题在桥接层;若两者都无变化,先验证 codesign:tweaks:update 的 postMessage 是否到达(tweaks-bridge.test.ts 提供了可对照的用例)。

结语

这份根因修复计划的核心价值在于把"面板改不动产物"的模糊症状,拆解为协议格式(EDITMODE/TWEAK_SCHEMA)、工具语义(tweaks 只读扫描)、双通道实时架构(postMessage + 防抖持久化)与并发安全(rebase + 乐观校验 + 生成取消)四个可独立验证的层次。修复时遵循"失败测试先行、修补底层契约、最后跑定向单测与 typecheck"的顺序,既能保证用户编辑精确落到正确的 EDITMODE 块,又能维持预览刷新链路在慢保存、快速连续编辑与并发生成场景下的正确性。相关实现与测试均可直接在 packages/shared、packages/core、packages/runtime 与 apps/desktop 中继续深入阅读。

登录后查看全文
open-codesign