Open CoDesign EDITMODE 协议指南：从 TWEAK_DEFAULTS 声明到可调节控件的完整实现

人工智能AI 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载导读本文以 packages/core/src/prompts/sections/editmode-protocol.md 为主体结合 Open CoDesign 仓库中shared、core、runtime、desktop各包的源码实现完整讲解 EDITMODE 协议Agent 如何在生成的页面源码中声明可调参数品牌色、密度、字号、布局等运行时如何把声明转换为--ocd-tweak-*CSS 变量宿主应用如何据此渲染调节面板并回写源码。读完本文你将掌握 EDITMODE 标记块的语法规范、绑定原则、校验与持久化链路以及一套可直接复用的调参协议设计思路。一、协议定位给生成物注入可控的设计决策EDITMODEEdit Mode是 Open CoDesign 中由 Agent 生成、宿主应用消费的一层源码内嵌调参协议。它解决的是这样一个问题LLM 生成的原生 HTML/JSX/CSS 页面artifact在浏览器里渲染后用户希望像操作设计工具一样拖拽调色、调密度、换布局而不需要重新生成或手改源码。协议的核心约定可以概括为三点暴露少量有意义的决策当需要或确实有用时暴露 25 个关键设计决策例如品牌 tokenbrand token、密度density、字号比例type scale、已实现的布局/强调方式implemented layout/emphasis、内容可见性content visibility不为凑数而加控件不得为了满足某个数量配额而推迟交付第一版可用的切片first working slice也不得添加无实际意义的控件允许空声明当控件没有必要、或用户拒绝提供控件时空对象{}是合法且推荐的答案。这一原则在 packages/core/src/prompts/compose-full.ts 中落地EDITMODE_PROTOCOL是create / tweak / revise三种模式共用系统提示词的固定组成之一而tweak模式还会追加一份更严格的TWEAKS_PROTOCOL小节。二、TWEAK_DEFAULTS源码顶部的扁平 JSON 声明协议要求在源码靠近顶部的位置声明一个扁平的 JSON 对象并用一对注释标记包裹const TWEAK_DEFAULTS /*EDITMODE-BEGIN*/{ accentColor: #28665c, density: 1 }/*EDITMODE-END*/;2.1 标记块marker block格式标记必须成对出现即/*EDITMODE-BEGIN*/与/*EDITMODE-END*/。在 packages/shared/src/editmode.ts 中解析器通过扫描/*注释找到标记名compactMarkerName会剔除标记内的空白因此/* EDITMODE-BEGIN */与/*EDITMODE-BEGIN*/等价并提取两个标记之间的内容作为 JSON 字面量。规则包括缺少标记 没有 tweak 块标记存在但不成对或内容损坏 协议错误标记之间的空白在往返round-trip重写时会被保留嵌套结构非法——只有{ key: value }一层不允许数组、嵌套对象。2.2 值类型约束键使用camelCase值仅允许三种基本类型类型示例说明stringaccentColor: #28665c颜色、字体名、布局名等numberdensity: 1数值型参数必须给出安全取值区间booleanshowFooter: true开关型参数标记块内禁止出现注释、表达式、尾逗号、数组和嵌套对象。这一约束在 parseEditmodeBlock 中被强制执行块内必须是合法 JSON且每个 token 值必须是 string/number/boolean否则抛出ARTIFACT_PROTOCOL_INVALID错误error-codes.ts 中定义的协议错误码。2.3 默认值一致性协议明确要求默认值必须与渲染出的源码一致并且反映用户当前的选择参数名要有意义数字要落在安全区间内可选的TWEAK_SCHEMA细节控件形态、范围、步长属于craft-polish方法阶段不在TWEAK_DEFAULTS中展开。三、绑定把声明变成真实可见的调节声明本身不产生任何效果——关键在绑定binding。3.1 CSS 变量--ocd-tweak-kebab-key运行时会把每个 camelCase 键映射为一条 CSS 自定义属性--ocd-tweak-kebab-key例如density→--ocd-tweak-densityaccentColor→--ocd-tweak-accent-color。源码中普通的视觉值必须通过它们来绑定padding: calc(var(--ocd-tweak-density) * 1rem);实现细节位于 packages/runtime/src/tweaks-bridge.ts桥接脚本里的toKebab()负责把 camelCase 键转成 kebab-case处理大小写边界、下划线、非法字符、连字符折叠applyCssVars()再把这些变量写到document.documentElement上布尔值被映射为1 / 0字符串与数字原样输出。3.2 结构性选择必须选择真实实现协议特别强调结构性的选择structural choices必须真的去切换已实现的代码路径而不是堆一段毫无作用的 JSON。比如layout: split必须让页面实际渲染为分栏布局如果值变了而 UI 不变这个参数就是惰性 JSONinert JSON属于违规。同理共享的选择如品牌色、密度要应用到相关屏幕screens上而不能只改单一文件。3.3tweaks()只发现、不绑定tweaks()是 Agent 侧的只读扫描工具它的职责是发现工作区里已声明的 EDITMODE 值供宿主汇总展示它不会创建控件、建立绑定也不会去更新未绑定到 CSS 变量的文件。这一点在 packages/core/src/tools/tweaks.ts 的注释里写得很直白This tool is advisory. The renderer parses its active source independently; scanner results neither register controls nor bind values to the preview.其默认扫描模式为[**/*.html, **/*.jsx, **/*.css, **/*.js]见 tweaks.ts支持传入自定义patterns结果按每个文件一个 token 袋parseTweakBlocks或扁平三元组aggregateTweaks即{file, key, value}两种形态返回。由于宿主面板只读取当前预览源码扫描未使用的起始模板中的控件并不会影响实际预览。四、校验与自检让声明经得起宿主解析4.1 声明必须通过的类型/范围校验packages/shared/src/tweak-source.ts 中的inspectTweakSource()是宿主的统一校验入口它组合了parseEditmodeBlock与parseTweakSchema输出四种状态状态含义missing源码中没有 EDITMODE 标记块empty标记块存在但内容为{}合法ready块与 schema 解析成功且 token 与 schema 类型/范围一致invalid标记不成对、JSON 非法、token 与 schema 声明的控件类型/选项/范围不符校验严格到控件不能造假的程度tweak-source.test.ts 专门验证——当声明值wide配上{kind:number}、数值32超出min/max、step:0、枚举值不在options中、布尔值不匹配时一律判定为invalid避免宿主渲染出显示假回退值的控件。另外只有 CSS 变量或未加标记的 JS 默认对象如const TWEAK_DEFAULTS {...}但无标记都不会被推断为控件。4.2 Agent 侧自检清单协议要求 Agent 在交付前完成两项核对检查一个代表性的变体representative alternate改动后要实际验证备选值下的渲染效果而不能只在默认值下自证恢复当前默认值验证完毕后把默认值还原保证源码状态与用户当前选择一致。4.3 预览不等于宿主面板一个容易踩的坑artifact 预览里自己写的调参 UI 不能证明宿主调节面板的行为。宿主的面板TweakPanel有自己的读取与绑定逻辑源码里存在变体开关只能说明页面实现了切换能力不代表宿主控件能正常工作。因此在交付前应通过宿主面板或等价通道做端到端验证而不是看源码变体就当验证过了。五、持久化与版本同步用户的每一次选择都要被记住5.1 后续编辑中保留用户选择协议明确要求在之后的编辑revision中保留用户在面板上做出的选择不能一改代码就把参数打回默认值。这也与 docs/research/11-custom-sliders.md 中记录的已知风险一致——陈旧 EDITMODE 块stale EDITMODE block on revision被列为必须规避的坑应用文本修订时要保留 EDITMODE 块里的值而不是重置为默认。5.2 宿主侧postMessage 实时流 防抖回写桌面端的 TweakPanel.tsx 展示了完整的宿主链路面板用inspectTweakSource(previewSource)解析出{block, schema}维护一份liveTokens工作副本每次调节通过postMessage({type: codesign:tweaks:update, tokens})推送给 iframe实现不刷新页面的实时预览持久化回写到工作区源码采用防抖persistTweakDebounce避免每个按键都触发文件写入写回使用persistTweakTokensToWorkspace合并进 EDITMODE 块并做生成中取消保存等并发保护。5.3 iframe 侧桥接脚本保持组件状态packages/runtime/src/tweaks-bridge.ts 注入到 iframe 的桥接脚本解决了每次调参都整页重载的性能问题无桥接时每次编辑都要重新挂载 React、重跑 Babel 与 Agent 脚本产生约 300–500ms 白屏。它把 token 映射为 CSS 变量后在下一帧用cloneElement重渲染已有 React 元素保留组件类型与模块作用域也即 hook 状态。对于useMemo/useCallback缓存了 token 值、或组件是React.memo/纯组件的情况桥接会回退到重跑模块兼容模式并向宿主发送codesign:tweaks:compatibility通知。协议建议在非记忆化组件内读取 token以便交互状态在实时更新时得以保留。对应地editmode-runtime.ts 的bindEditmodeTokensToRuntime()会在注入阶段把源码中的TWEAK_DEFAULTS声明替换为window.__codesign_tweaks__.tokens引用让模块读取的就是活的 token 对象。5.4 实质性 token 变更必须显式同步 DESIGN.md协议最后一条红线在实质性 token 变更substantive token changes时要显式核对并同步对应的 DESIGN.md 条目永远不要假设它会自动同步。这与 docs/v0.2-plan.md 中用户持续调整某 EDITMODE 值 → Agent 主动 propose promote to DESIGN.md的演进方向一致EDITMODE 是设计系统 token 的草稿区而 DESIGN.md 是最终沉淀。六、TWEAK_SCHEMA可选但强力的控件形态声明虽然TWEAK_DEFAULTS只负责值协议允许在craft-polish阶段附带TWEAK_SCHEMA标记块声明每个 token 的控件形态。格式见 editmode.tsconst TWEAK_SCHEMA /*TWEAK-SCHEMA-BEGIN*/{ accentColor: { kind: color }, radius: { kind: number, min: 0, max: 32, step: 2, unit: px }, layout: { kind: enum, options: [split, stacked] }, dense: { kind: boolean }, label: { kind: string, placeholder: Button label } }/*TWEAK-SCHEMA-END*/;支持的五种kind及参数TokenSchemaEntrykind附加字段宿主控件color无颜色选择器numbermin、max、step、unit范围滑块enumoptions: string[]非空分段选择器boolean无开关stringplaceholder文本输入schema 是建议性的条目可以省略但一旦出现TWEAK-SCHEMA-BEGIN/END标记就必须是合法 JSON 且条目形状合法否则整份声明被判为invalid。TweakPanel 正是依据 schema 来决定渲染哪种控件TweakPanel.tsxnumber 用min/max/step/unit的滑块、enum 用选项数组等。七、与 TWEAKS_PROTOCOL 的配合tweak 模式下的收紧editmode-protocol.md是通用规则而 tweaks-protocol.md 是tweak模式下的收紧版二者在 loader.ts 中分别加载由 compose-full.ts 在mode tweak时追加。TWEAKS_PROTOCOL 的要点读取活动源码而不是起始模板的默认值改值时键必须与现有TWEAK_DEFAULTS键一致只改被请求的标记 JSON保留其他值/文件并遵守范围检查渲染绑定只有在被请求时才新增控件通过 EDITMODE CSS 变量或 JSX 绑定已有的有用值并保持初始视觉不变同样的铁律tweaks()只发现、不绑定值编辑期间不做重新设计。八、把协议接到 Agent 提示词一条完整调用链综合各包源码一条完整的 EDITMODE 调用链是compose-full.ts 组装系统提示词EDITMODE_PROTOCOL固定出现tweak模式追加TWEAKS_PROTOCOL每个.md小节由 sections/loader.ts 在模块加载时读取一次暴露为EDITMODE_PROTOCOL、TWEAKS_PROTOCOL等冻结字符串常量PROMPT_SECTIONS还记录editmodeProtocol: sections/editmode-protocol.md的源文件映射便于追溯Agent 按协议在生成源码顶部写出TWEAK_DEFAULTS及可选TWEAK_SCHEMA标记块agent.ts 注册tweaks工具makeTweaksTool当用户偏好为 enabled 时提示实现有用的 source-backed 控件后调用tweaks()用户显式拒绝时则注入不要调用tweaks()agent.ts宿主侧 TweakPanel.tsx 解析预览源码、渲染控件、postMessage 实时更新并防抖回写iframe 侧 tweaks-bridge.ts 消费更新、映射 CSS 变量、保留 React 状态生成测试generate.test.ts与提示词测试connected-product.test.ts都会断言协议措辞例如tweaks()discovers values; it does not create bindings必须出现在提示词中。九、实战检查清单把协议浓缩为交付前可逐条核对的清单只在确有需要时暴露 25 个控件不凑数不需要时写{}TWEAK_DEFAULTS位于源码顶部使用成对/*EDITMODE-BEGIN*/.../*EDITMODE-END*/标记键为 camelCase值仅为 string/number/boolean块内无注释/表达式/尾逗号/数组/嵌套对象默认值与渲染结果、用户当前选择一致数字在安全区间视觉值通过--ocd-tweak-kebab-key绑定如calc(var(--ocd-tweak-density) * 1rem)结构性选择真的切换实现共享选择已应用到相关屏幕tweaks()仅用于发现不代替绑定检查一个代表性变体并恢复默认值不把源码变体当作宿主面板行为的证明后续编辑保留用户选择实质性 token 变更显式同步 DESIGN.md如附带TWEAK_SCHEMA其标记与条目必须合法参考 tweak-source.test.ts 的校验用例遵循这套协议Agent 生成的每一个页面都能获得可被宿主精确调参、可被持久化、可被升级进设计系统的能力——这正是 EDITMODE 与普通硬编码参数的本质区别。赞分享人工智能AI 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载相关推荐open-codesign 自定义滑块与 EDITMODE 参数调节协议从研究文档到运行时落地的完整实现解析open codesign 自定义滑块与 EDITMODE 参数调节协议从研究文档到运行时落地的完整实现解析 本文以仓库研究文档 docs/research/人工智能AI 应用桌面应用Encore 实战指南使用 encore exec 在完整基础设施上下文中运行脚本与数据库种子填充Encore 实战指南使用 encore exec 在完整基础设施上下文中运行脚本与数据库种子填充 encore exec 是 Encore CLI 提供的脚人工智能AI 应用桌面应用如何高效使用开源WeMod增强工具完整实战指南如何高效使用开源WeMod增强工具完整实战指南 WandEnhancer是一款专为WeMod游戏修改器设计的开源增强工具通过本地客户端配置扩展和用户体验优化人工智能AI 应用桌面应用上一篇ADB神器入门Android Debug Bridge完全指南下一篇PP-OCRv6_small_det_onnx性能深度测评84.1%平均精度背后的技术秘密创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考