Makepad Agent Runbook：AI 代理在 Makepad 仓库中的协同开发工作流

• 前端
• UI组件
• 3D渲染
• 跨平台
• 游戏开发

导读

本文基于仓库根目录的 AGENTS.md（Makepad Agent Runbook，2026-09-16 版工作流）及其链接的参考文档，系统梳理 AI 代理在 Makepad 开源仓库中执行开发任务时必须遵守的运行规则：从本地工作目录约定、local → work → dev三级提交流水线、发布构建与运行时验证门禁，到--remote远程控制、线程实时性约束、平台层改动中立的工程纪律，再到 Director 多代理协作树与 Splash 脚本语法要点。读完本文，你将掌握如何在 Makepad 仓库内以合规、可验证、可复现的方式驱动 Agent 完成从设计、编码、构建、测试到成果提交的完整闭环。

一、Runbook 的定位与文档体系

根目录AGENTS.md是一份"仓库级规则"（Repository-wide rules），它要求代理在任务需要时先阅读链接的参考文档，并以当前源码为准获取 API 签名和可用示例，而不是照搬历史 API。

整个 Agent 协作的知识体系由一份主文档与四份专题文档构成，全部存放在仓库内（以下均为仓库根相对路径）：

例如，远程控制的实现本体在 platform/src/remote.rs，Tweaker 覆盖层在 widgets/families/tweaker/src/tweaker.rs。文档明确提示：运行实例上执行GET /会返回当前路由列表，可能比静态文档更新——"以运行为准"是这套文档体系的一贯原则。

二、本地工作与文档规范

Runbook 对代理产生的文件划分了严格边界：

• 计划写入local/plans/<topic>.md；
• 其他任务设计文档与报告写入local/agent_state/<topic>/，并且必须保持本地私有，不得发布为托管页面或工件；
• 可复用的仓库文档必须落在受版本控制的文件中，工作流不得依赖可能随local/消失的辅助脚本或状态；
• 新增示例 crate 时，需要同步更新其所属的 Cargo workspace 与根目录的makepad.splash。

源码检索上，Runbook 明确优先使用rg/rg --files；在修改 Splash 语法之前，应先查看 widgets/core/src/、widgets/families/、code_editor/ 和 apps/director/ 中已有的写法。特别强调：已归档的old/目录树不是当前 widget API 的参考依据。

三、当前 Agent 工作流：角色分工与会话纪律

截至 2026-09-16，仓库采用了三角色分工并明确"取代旧版角色分配"（此前的 local skills / memories 中的旧角色定义一律让位）：

• Codex 负责管理工作：设计系统与交互，评审 Fable 的设计与成果；
• Fable 负责设计与执行困难实现工作，并可独立提供设计与代码评审；
• Grok 承担有边界的机械性工作与验证，需在精确的简报下执行。

会话纪律上有三条关键要求：

1. 对关联任务保持一个持久的 Fable 会话：后续请求发往该会话或以既有上下文恢复它，不要反复新建 Fable 会话并重复支付相同的输入上下文；
2. 等待关联工作时保持空闲，不进行轮询/模型往返；
3. 在委托场景中必须保留管理/实现的分工（manager/implementer split），不得混用。

这一分工在 apps/director/AGENTS.md 中被进一步细化（Codex / Astra 管理、Fable 实现、Grok 机械验证），并要求在所有新建与恢复的 lane（车道）以及每个委托子任务中保留该上下文。

四、软件安装必须显式审批：一条不可逾越的红线

Runbook 对"安装软件"设定了极严格的门槛：未经用户对该软件及安装行为的事先明确批准，绝不安装、升级、引导或下载运行任何外部软件。范围覆盖工具、应用、运行时、SDK、插件、包管理器安装以及从下载源码编译的第三方工具，且同样适用于系统级、用户级、虚拟环境、仓库内与临时目录安装——把可执行文件放进local/、/tmp、~/.local/或绕开管理员权限都不豁免；仅为本地使用编译第三方工具也算安装。

特别值得注意的判定边界：

• 功能请求、构建/测试许可或缺失依赖，不等于安装许可；
• 安装前必须说明：软件与版本、来源、安装位置、用途、以及将执行的命令或系统改动，然后等待显式批准；
• 不得把外部运行时静默塞进 Studio 或其他应用作为变通方案；
• 优先使用已安装的工具和本仓库的正常构建；确需额外软件时，将安装事项挂起并说明限制，继续做不依赖它的工作。

五、提交内容与 Studio 迭代历史：local → work → dev

5.1 分支纪律

Runbook 对仓库（makepad/makepad）的提交和分支有硬性规定：

• 绝不创建或发布额外的公共分支，只走既定的local → work → dev流程；
• local保持私有、永不推送；
• 特性、测试、发布、打包与分发工作都不构成另开公共分支的理由；使用独立 checkout 或 worktree 也不改变此规则；
• local记录每一次构建迭代；私有并发分支使用流程分配的local-*命名，其 checkpoint 引用与祖先链永不推送、永不合并进公共分支；
• 晋升只允许squash：local压入work，再把特性组从work压入命名dev里程碑；
• 拉取/同步work与dev时不得重写已发布历史或丢弃无关工作。

5.2 提交内容边界

• AI 生成的 Markdown、计划、报告、临时脚本、日志、录制、截屏、构建输出等临时工件不得进入提交；AGENTS.md这类既有说明文件是唯一的 Markdown 例外；
• 绝不提交第三方源码快照（cargo vendor输出、拷贝的 crate、SDK 树）、模型权重、数据集或媒体转储——GitHub 保留每个推送 blob，一次这样的提交会让仓库的所有克隆永久膨胀。依赖来自 crates.io 或仓库内libs/移植；离线镜像放在仓库外；
• 每次提交前执行git diff --stat，遇到非自己写入的路径立即停下；
• 运行仓库既有测试做验证；除非用户明确要求，不新增生成测试文件、内联测试代码或测试脚手架；保留既有测试，不得删除或削弱它们来换取通过。

5.3 Studio 托管构建的固定顺序

对 Studio 管理的流构建，Runbook 规定了严格的执行顺序：

1. 平台构建检查（platform build checks）；
2. 对变更的 Rust 执行 rustfmt；
3. 若格式化改变了源码则重复检查；
4. 将确切的合格源码提交到local；
5. 发布二进制构建；
6. 运行既有原生测试；
7. 启动运行。

二进制需与 checkpoint 哈希及证据一同记录；复用有边界的 worktree，禁止每次构建新建一个。

5.4 验证门禁（Validation Gate）

一个被认定为"已验证"的修订需要同时满足：

• 在其支持平台上cargo check零警告、零错误；
• 在当前宿主机通过既有原生测试；
• 适用时完成发布构建/运行时检查。

判定规则同样严格：缺失 SDK、runner 或必需测试属于被阻塞的覆盖率（blocked coverage），不是通过；不得通过压制警告来换取绿色门禁。对每个特性/里程碑晋升都要验证确切的最终源码树，使dev保持可 bisect 的价值；公开 squash/push 操作必须说明其来源、目标、包含的变更、验证结果与冲突。

六、构建与运行时验证：以真实后端为唯一标准

6.1 构建方式

• 运行时验证、性能剖析、基准与计时测试一律使用发布构建（除非用户明确要求 debug）：从包所属的 workspace 执行cargo build --release -p <package>，然后从本 checkout 启动生成的独立可执行文件；注意部分应用有自己的 workspace，需检查 target 目录与资源工作目录；
• 构建 profile 定义在根 Cargo.toml：dev 仅保留行号表，release 为无 LTO 的增量构建；cargo-makepad 的打包命令则进行非增量发布构建；
• 根级Cargo.toml通过cfg(any())路径依赖把apps/<name>下的私有应用 crate 纳入同一 workspace（匹配apps/*/src/..），使所有 Makepad crate 对全部应用只编译一次；Cargo.lock不提交；
• 并行 rustc 前端是本地可选优化，绝不用在 CI 或发布构建：稳定版需要RUSTC_BOOTSTRAP，约可将干净 dev 构建提速一半。必须写入用户配置~/.cargo/config.toml以保证整机一致（标志差异会触发每个 crate 的重编），禁止用 shell 级RUSTFLAGS临时设置：

[env] RUSTC_BOOTSTRAP = "1" [build] rustflags = ["-Zthreads=8"]

6.2 调试手段

• 使用printf 风格调试（log!、eprintln!或等价 tracing）；禁止启动或附加 LLDB / GDB 等调试器——调试器访问会触发系统权限弹窗。

6.3 渲染验证必须在真实 GPU 后端

Runbook 明确了一条关于渲染验证的关键纪律（用户原话："在 headless 上追 bug 毫无用处"）：

• 任何涉及画面、像素、轮廓、颜色、LOD、瓦片或帧时序的问题，都必须用真实 GPU 后端（macOS 上为 Metal）上--remote实例的发布构建回答，通过/g//gseq抓帧并以 RGB 比对；
• MAKEPAD=gpusim（CPU 模拟 GPU 后端，旧称 "headless"）只用于逻辑与数据结构测试（布局、预算、顺序、解析器）；gpusim 光栅门禁永远不能替代 GPU 证明，也不得用于诊断渲染 bug。gpusim 源码位于platform/src/os/gpusim/；
• 隐藏窗口实例（MAKEPAD_HIDE_WINDOWS=1+ 原生后端）是常规的像素级验证装置：/g强制呈现（隐藏窗口上约 2 秒/帧）；只有"静止/稳定计时"类证明才需要自行呈现的窗口。

6.4 应用嵌入 AI 聊天的构建边界

嵌入 AI 聊天的应用只构建其 CLI/MCP/云端后端；本地模型运行时（Metal/CUDA 上的 Qwen、metallib 与 kernel 构建）通过应用自己的localaicargo 特性引入：

cargo build --release -p <app> --features localai

该特性仅在应用自身任务运行本地模型时默认开启（如apps/ai-hub、route 与 files）。

七、应用归属、焦点与截屏策略

这是代理与用户"共享机器"时的行为准则：

• 用--remote启动打算检查或驱动的任何应用；不驱动、不停用无关的用户实例；
• 对活跃开发工作流中的应用，替换品就绪后可直接优雅关闭并重启（无需单独的用户关闭确认）；新启动前须先优雅关闭上一个工作流实例并确认其退出；
• 远程窗口保持可见但不聚焦；除非用户明确要求，不得激活它们或使用MAKEPAD_FOCUS=1；
• 用户在活跃工作流应用上的交互不会暂停代理测试，也不要求交接：代理可持续检查、驱动、关闭并重启该应用（2026-09-22 用户常设授权），同时保留其 workspace 与已保存状态；
• 每个有界输入序列前读取/activity并携带if_user_seq：计数器变化或 HTTP 409 使该序列的证据失效，但不撤销继续授权——检查动作是否生效、读取新计数器后重试或重启序列，不要盲目重放已应用的开关或编辑（详见 App remote control）；
• 子代理验证运行使用MAKEPAD_HIDE_WINDOWS=1 <bin> --remote，只有主会话打开可见检查窗口，避免重复；
• CEF 应用的浏览器 profile（cookie、登录态）默认存放在$HOME/.makepad-cef/<可执行名>（除非MAKEPAD_CEF_PROFILE_DIR指定）；替换用户 CEF 应用时必须把MAKEPAD_CEF_PROFILE_DIR指向用户实例原本使用的 profile；隐藏原生测试使用各自独立的测试 profile；绝不允许两个实例同时使用用户的 profile；
• 只允许通过/g、/gq、/tweak/grab或应用提供的捕获钩子抓取应用自身的 drawable；禁止 OS/窗口/显示器截屏；若涉及原生 chrome 或其他应用，需向用户索要图片；
• 日志中的user closed表示用户关窗而非崩溃；测试会话以GET /gq（抓帧并退出）收尾，抓帧不可用时用/close和/或/quit；优雅清理失败时才允许停止其确切归属的 PID；除非用户明确要求保留，代理启动的任何进程都不得比任务存活更久。

八、远程控制快速上手：6 步标准流程

Runbook 给出了代理驱动 Makepad 应用的标准流程：

1. 构建发布二进制并以--remote启动自己的实例；
2. 读取启动行的端口、PID 与抓帧目录；
3. GET /获取运行中二进制当前的协议；
4. 用/snap?q=...查找 widget 矩形，然后注入输入；
5. 通过快照/日志检查结果，必要时用/g抓帧；
6. 以/gq收尾并确认关闭。

坐标是窗口本地布局点，无需 DPI 换算；给输入请求加wait=1可等待结果帧。

8.1 启动与发现

文档中的标准示例（在仓库根目录，用隐藏窗口做验证运行）：

cargo build --release -p makepad-example-splash MAKEPAD_HIDE_WINDOWS=1 ./target/release/makepad-example-splash --remote

启动输出包含寻址与清理所需的全部信息：

[makepad-remote] listening on 127.0.0.1:53412 pid=9931 app=makepad-example-splash grabs=/tmp/makepad-remote/makepad-example-splash-9931

端口是临时的；--remote=PORT可固定端口，MAKEPAD_REMOTE=1或MAKEPAD_REMOTE=PORT同样启用该服务。代理检查应优先使用显式启动参数。macOS 上--focus会在窗口打开时将其带到前台。

8.2 常用路由一览

输入细节：鼠标按键b=0左、b=1右、b=2中；滚动取dx/dy；测试硬件指针锁定时加hw=1；键盘修饰键为shift=1、ctrl=1、alt=1、cmd=1。POST 平铺 JSON body 同样受支持，解析器也接受长名称（window、kind、button、text、code）。

8.3 与人类共享实例时的纪律

驱动前读取/activity（/s也含同一对象）：它报告user_active、单调递增的user_seq、idle_ms、两秒quiet_ms、输入是否held及最后输入的种类与窗口——但绝不暴露键入文本、键值与指针坐标。只有原生输入推进计数器；HTTP 与 Studio 注入一律标记为 remote。

自动化序列必须在每个变更请求上携带if_user_seq=N；用户自 N 后交互过则请求被拒（HTTP 409）。/gq也会在抓帧后复查计数器；若拒绝退出，检查状态后用新计数器重试。每次 HTTP 响应（含原始 PNG）都带X-Makepad-User-Seq-Start与X-Makepad-User-Seq头。wait=1命令在帧确认前被打断会返回applied:true（动作已执行），重试可能重复副作用；dispatch 前被拒则applied:false。

8.4 已知远程风险

• 隐藏窗口点击偶发丢失（Event::MouseDown不送达）——调试前先重新启动；
• tick 采样按键需要/k?k=down… ≥150 ms …/k?k=up，press会落在 tick 之间；
• 在 code map 中每个/g都会夺走键盘焦点，下一次按键批处理前需先点击 map；
• MAKEPAD_HIDE_WINDOWS仅在 macOS 实现；
• 有音频或共享 home 的应用的测试实例应使用SANDBOX_MUTE=1及各自的SANDBOX_HOME/--state-dir。

仓库中的 tools/remote_smoke.sh 脚本在示例应用间跑通整个协议，可作冒烟验证参考。

九、线程与实时性所有权：UI 线程的锁纪律

Runbook 对多线程安全给出了明确的架构红线，任何 UI 相关代码都必须遵守：

• UI 线程绝不获取另一线程可能持有的Mutex、RwLock或Condvar，也绝不等待 channel；
• UI → worker/audio 的命令使用有界、非阻塞发送；队列满时报告并保留/重试到下一帧；
• worker/audio 通过原子量、三缓冲或try_recv消费的 channel发布快照；
• 大负载（PCM、stems、网格、图像）以Arc形式穿越 channel；替换下来的负载要归还给 UI 处置，绝不在实时回调中做最终 drop；
• 实时音频回调拥有自己的状态，热路径上不分配内存，也绝不在 UI 或 worker 可能持有的锁上等待；
• 原生与 wasm 使用同一机制；不得在桌面保留共享锁路径的同时在 wasm 另搞 workaround；UI/audio 线程不得使用Atomics.wait或自旋等待回退；
• lock_from_ui只允许用于可证明仅由 UI 触碰的状态；
• 不要为每个任务临时 spawn 线程：使用cx.thread_spawner()、池化 TaskHandle API，或由 channel 喂养的长期平台 worker。

十、平台层改动保持应用中立

platform/、widgets/、draw/及其他共享层服务于所有应用。Runbook 规定：

• 为提速或修复某个特定应用而做的平台改动，不得凭代理自己的判断落地：必须先陈述拟议的平台改动及动机应用，取得用户反馈与检查；
• 绝不把应用特定内容泄漏进这些层：不出现应用名、应用数据形状、应用专属 flag 或仅为单一调用者存在的代码路径；需求要表达为带通用名字的通用设施，否则留在应用内；
• 平台优化落地前须在提出需求的应用之外证明，并在提交中说明检查了哪些应用。

十一、Splash 与着色器要点

Splash 是 Makepad 的脚本语言/着色器 DSL。Runbook 对当前script_mod!时代的写法给出以下纪律：

• 使用script_mod!与当前 widget API；对象属性用name: value；命名 widget 实例用name := Type{...}；模块赋值mod.widgets.Name = ...有效；
• 保留继承字段时用+:合并类型化属性：draw_bg +: {color: #f00}；使用类型化布局值如padding: Inset{left: 10}、align: Align{x: 0.5 y: 0.5}；
• 逐绘制值用instance(...)、实例共享值用uniform(...)（hover 的渐变色绝不能误做成 uniform）；
• Rust 插值用#(expr)；Rust 宏内当数字后跟e/E会触发指数分词时使用#x颜色前缀，如#x1e1e2e；
• 在 UI 使用 widget/组件模块之前完成注册；匹配当前应用的启动与查找签名，不要照抄旧代码；
• 自定义 draw shader 需要#[repr(C)]：非实例字段放在#[deref]draw 基类之前，着色器实例字段只放之后——实例缓冲区是连续读取的，顺序错误会破坏它；
• 着色器内优先用带 catch-all 的 enummatch；若受支持的 enum 匹配失败，应新增编译器回归用例并修复编译器，而不是用整型式if/else链替换。

11.1 最小应用骨架（来自 Splash and widget reference）

pub use makepad_widgets; use makepad_widgets::*; app_main!(App); script_mod! { use mod.prelude.widgets.* startup() do #(App::script_component(vm)){ ui: Root{ main_window := Window{ window.inner_size: vec2(420, 220) body +: { flow: Down status := Label{text: "Ready"} press := Button{text: "Press"} } } } } } #[derive(Script, ScriptHook)] pub struct App { #[live] ui: WidgetRef, } impl MatchEvent for App { fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) { if self.ui.button(cx, ids!(press)).clicked(actions) { self.ui.label(cx, ids!(status)).set_text(cx, "Pressed"); } } }

11.2 自定义 draw shader 的内存布局

#[derive(Script, ScriptHook)] #[repr(C)] pub struct MyDrawShader { #[rust] cached_state: bool, #[deref] draw_super: DrawQuad, #[live] tint: Vec4f, }

DrawVars::as_slice()会从基类跨到尾部实例字段连续读取，非实例状态混入该区域会破坏 GPU 实例缓冲区。

11.3 相关实现入口

Runbook 建议以这些源码为"当前 API 的活参考"：小应用与启动看 examples/counter/src/main.rs，更广的 widget 示例看 examples/splash/src/main.rs，widget 注册与导出看 widgets/core/src/lib.rs，样式与动画看 widgets/core/src/button.rs，虚拟化列表模板看 widgets/core/src/portal_list.rs，生成式 widget API 看 widgets/derive_widget/src/derive_widget.rs。

十二、Director：多代理协作树与 Studio 迭代流

apps/director/AGENTS.md 统管"运行 Studio 迭代流"与"实现 Studio 本身"的代理行为，并要求代理使用运行中的服务清单与当前源码获取确切的工具签名——不得虚构成功的工具响应或绕过不可用的操作。

12.1 委托上下文与 Agent 树

• 每个 lane 是以其稳定终端来源为键的代理节点；合成 Director 根持有独立的根 lane；每个代理可再委托子代理，子代理可再委托（递归委托）；
• 委托可见工作只通过限定操作进行：flow_agent（经POST /call）或director-flow agent '{"action":"start","provider":"codex","title":"...","task":"...","repo":"/abs/worktree"}'；provider取值claude、codex或grok；
• Director 记录子流程、父边与任务作为子代理的第一个需求，创建其控制目录、发布回调绑定，然后在仓库的makepad-agentshelper 中启动已安装的 provider；
• 预算上限：4 个活跃/停止根 lane、总计 16 个活跃/停止代理、每代理 8 个活跃子代理、深度 6 层、64 个保留 lane、每 lane 64 个启动请求、每子代理 8 个工件授权；归档可释放名额；应用进程另有独立预算（所有 lane 最多同时 4 个应用进程，含嵌入与独立、人类与测试）；
• 全局status是有界索引：序列化回复不超过 12 KiB 且始终是完整 JSON，flows.counts永远完整；
• 通信原语：agent list查看直接子代理与未读数；status/result加child检查单个子代理；message带to、kind（task/note/result）与text向直接子代理或父代理排队文本；to可用保留值parent；inbox读取未读消息、inbox加ack确认；
• 结果通过持久 inbox 异步送达；Director 只在接收方终端输入提示可证明为空时，才以一次括号粘贴加一次回车把结果键入其终端，且前缀发送方与消息 id；否则保持queued；绝不向 shell 或未识别程序键入内容。

12.2 上下文文件与启动上下文

代理 lane 的启动上下文是 lane 工作目录内的文件<cwd>/local/director/agent_context/<session>-<created>.context.md（仅属主可读），每次启动、恢复与恢复时重写；provider 的首个提示只提及该文件并请代理阅读它——因此不读取工作目录之外的内容。该文件不含 URL 或 token，向每个子代理逐级传递委托规则；路径上的三个目录必须是真实目录，符号链接/junction/reparse point 一律拒绝。

12.3 Todo 增量与反馈协议

每个新用户消息必须先经其回调到达 Studio，然后才进入实现。发送紧凑的"范围 + todo 增量"：

curl -sS --json '{"i":"msg-17","v":0,"q":"Animate feedback folding","u":[["fold","w","Animate feedback folding"]]}' "$("$MAKEPAD_STUDIO_CLI" --url)/feedback"

v是检视到的 todo 修订号；成功仅当两处变更都持久化后返回{"v":1,"r":1}。后续进度省略q：{"i":"msg-18","v":1,"u":[["fold","d"]]}。todo 状态为q排队、w工作中、d已实现、b阻塞；绿色d只表示代理报告已实现但未验证，绝不等于人类接受。每个不同 delta 用新的i，重试用相同 ID 与 body；旧 ID 换参数会被拒。stale 修订时先取/brief调和再更新，绝不盲目覆盖更新的 todo。202只是意图，需读GET /feedback/<i>获取紧凑结果。

12.4 运行、观察与测试应用

• test start优先走 Director 托管路径（mode默认embedded）：Director 经 broker 注册运行，并以--stdin-loop及全部宿主设置启动保留可执行文件，人可在其 lane 中观看测试；绝不自己裸启带--stdin-loop的二进制；
• 托管启动完成以应用以其拥有 PID 应答远程端口、宿主传输呈现首帧（first_frame；端口存活不能证明渲染表面）且读到输入守卫为准；
• 宿主不可用或 20 秒内未发布端点/呈现帧时，Director 关闭该次尝试、等待退出与注销，然后以新 run id 启动一个 standalone 替换品（旧 run 返回replaced_by）；
• AI 拥有的预览只读：鼠标、键盘、IME、拖放、剪贴板都不穿透，应用不能改人的剪贴板，不可 pop out；
• 测试输入以应用的人类输入计数器为证据：读取/activity、每个有界序列携带if_user_seq，重试前检查响应计数器与applied；
• 每个受支持的 UI 测试都录制为MP4并保留最终帧、run 身份、checkpoint 哈希、结果与录制路径；隐藏测试窗口也必须发布可观察帧；
• 演示新行为：

director-flow test '{"action":"start","artifact_id":"<artifact>","demo":"Counter increments"}'

随后用test '{"action":"snapshot","run_id":"<run>"}'与test '{"action":"input","run_id":"<run>","input":"click","x":390,"y":279}'驱动（坐标取自该应用的 snapshot），每个有意义状态暂停至少两秒，最后test '{"action":"stop","run_id":"<run>"}'并轮询完成、确认 MP4 定稿。演示行为标记为demonstrated，与测试成功或human accepted严格区分。

12.5 本地源码与验证

• 预运行顺序：平台cargo check→ rustfmt → 重新检查格式化后的源码 →local提交 → 发布二进制构建 → 既有原生仓库测试 → 启动；所有声明的支持平台都要检查；
• 零警告零错误是硬性要求；不得压制警告、削弱检查、改写既有测试或将生成的测试脚手架入提交；
• 晋升前给出确切的源/目标哈希、变更路径、验证与冲突；local → worksquash 连贯特性，work → devsquash 更大命名组；验证确切结果树，保持 dev 可 bisect。

12.6 工具链与构建方式

Director 与代理终端 helper 一起构建：

cargo build --release -p makepad-agents -p makepad-director

makepad-agents（crate 清单见 tools/agents/Cargo.toml，TUI 入口在 tools/agents/src/main.rs）是tools/agents（Windows 上为tools/agents.ps1）构建的 release helper，打开其 Rust TUI 管理 provider 会话：C 启动 Codex、A 启动 Claude、R 刷新、Q 退出；另有四行可选的新代理行与两行恢复行（Codex--yolo、Claude--dangerously-skip-permissions，粘贴 UUID 恢复会话）。helper 支持 macOS/Linux PTY 与 Windows ConPTY，共享终端解析/渲染。

外部终端也可附加：makepad-agents attach --state-dir <studio-state>/agent_sessions --session <session-id>，Ctrl+D 分离该客户端并保持代理运行。

Director 本身从仓库 workspace 构建运行：

cargo build --release -p makepad-director ./target/release/director

验证用cargo test --release -p makepad-director；Director 的实现位于 apps/director/src/（迭代流、代理树、用量等模块），测试在 apps/director/tests/architecture_plan.rs 与 apps/director/tests/mcp_battery.rs。需要受控检查实例时加--remote并按 the app remote guide 操作；--cwd <absolute-directory>设置初始终端/仓库上下文，--state-dir <directory>覆盖默认的~/.makepad/studio位置。

12.7 持久终端与 oversight

• lane 的终端连接非排他：另一视图连接不会影响既有客户端与 lane 的原始会话；最后发出 resize 的客户端决定共享 PTY 大小；
• 关闭终端视图或 Studio 只分离（detach），不停止；显式 Stop 在保留可证明的代理恢复身份后才结束会话；
• 核心 AI 进程跨 Studio UI 重启保持持久会话；关闭展示标签/窗口不构成停止代理或在新会话身份下重启它的许可；
• 历史拆分用 lane 的 split 工具（Split here）：选中项及更新内容成为新 lane 的历史，更早前缀归档仍可检视；flow_lane工具接受state:"split"、flow、title、item（artifact/<id>、feedback/<id>、attachment/<id>或recording/<id>）；
• F10 仪表板必须用证据链接汇总摄入的观察，区分观察到的活动、推断活动、未知结果与样本数据；绝不以 demo 输出冒充实时测试或虚构截屏。

十三、综合核对清单

一个符合 Runbook 的 Agent 任务应能对以下问题全部作答：

1. 计划与报告是否落在local/plans/、local/agent_state/，未入提交？
2. 是否未经显式审批就安装/编译了任何软件？
3. 是否遵守local → work → dev且只 squash 晋升、未建公共分支？
4. 提交前是否git diff --stat检查、杜绝第三方快照与生成工件？
5. 是否在支持平台零警告通过cargo check、跑通既有原生测试、完成发布构建？
6. UI/渲染结论是否基于真实 GPU 后端（如 Metal）的--remote发布实例与/g抓帧，而非 gpusim？
7. 是否只用/g、/gq、/tweak/grab捕获 drawable，全程携带if_user_seq，并以/gq收尾且确认进程退出？
8. UI 线程是否未触碰任何可被其他线程持有的锁，worker 快照是否走原子/三缓冲/try_recv，大负载是否走Arc？
9. 平台层改动是否应用中立、经用户反馈并多应用证明？
10. Splash/着色器改动是否符合script_mod!时代语法、#[repr(C)]字段顺序与instance/uniform语义？

Runbook 的最终立意是：让 AI 代理在复杂的多应用仓库中既能高效产出，又不污染 Git 历史、不越权操作系统、不伪造验证证据——所有结论都要求"可观察、可追溯、可复现"。

• 前端
• UI组件
• 3D渲染
• 跨平台
• 游戏开发