cmux-sidebar-builder

cmux 侧边栏构建器

当任务是创建或修改 cmux 自定义侧边栏视图时，使用此技能。这些是由用户或 Agent 编写的 .swift 文件，位于 ~/.config/cmux/sidebars/，由 cmux 的运行时 SwiftUI 风格解释器渲染，而非已编译的应用代码。主要的内部试用方式是在普通的 Bonsplit 窗格标签页中，通过 cmux sidebar open <name> 打开；左侧边栏选择器仍适用于预览。

概览

• 此功能最初由 Aziz Albahar 在 PR https://github.com/manaflow-ai/cmux/pull/5254 中实现。
• 此功能默认关闭，由基于 UserDefaults 的键 customSidebars.beta.enabled 控制。
• 自定义侧边栏位于 ~/.config/cmux/sidebars/ 下。启用 beta 后，可以通过 cmux sidebar open <name> 将它们作为普通的 Bonsplit 窗格标签页打开，也会显示在左侧边栏选择器中。
• 从 cmux 应用仓库的文档开始：repo/docs/custom-sidebars.md。

cmux 源码中的重要入口：

• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/SwiftViewInterpreter.swift
• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ExpressionEvaluator.swift
• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/RenderNode.swift
• repo/Packages/CmuxSwiftRenderUI/Sources/CmuxSwiftRenderUI/Sidebar/CustomSidebarView.swift
• repo/Sources/ContentView.swift，查看 customSidebarsDirectory、customSidebarDataContext 和 CustomSidebarView(...) 附近的代码。
• repo/Sources/Panels/CustomSidebarPanel.swift，了解 Bonsplit 窗格宿主。
• repo/Sources/Workspace+CustomSidebarPane.swift 和 repo/Sources/TerminalController+CustomSidebarCommands.swift，了解 cmux sidebar open <name> 的调用路径。

必要时可查看后续实现分支：

• origin/feat-interpreter-primitives，了解更广泛的受支持 SwiftUI 风格基础组件。
• origin/feat-sidebar-interpreter-isolation，了解进程外、支持崩溃隔离的解释器工作进程。

工作流

1. 编写前，检查当前应用文档和解释器支持的功能：

   sed -n '1,220p' repo/docs/custom-sidebars.md
   rg -n "struct SwiftViewInterpreter|func evaluate|func parse|enum RenderNode|customSidebarDataContext|customSidebarsDirectory" repo/Packages/CmuxSwiftRender repo/Packages/CmuxSwiftRenderUI repo/Sources/ContentView.swift
   

2. 在用户的配置目录中创建或编辑侧边栏文件：

   mkdir -p ~/.config/cmux/sidebars
   $EDITOR ~/.config/cmux/sidebars/<name>.swift
   

3. 将代码限制在解释器支持的子集中。优先使用简单的 SwiftUI 风格表达式：VStack、HStack、Text、Image、Button、ForEach、条件语句、受支持的修饰符，以及提供的上下文中的数据。不要假设可以使用任意 Swift 代码、导入、异步操作、文件系统访问、网络、自定义类型或已编译依赖项。

4. 使用提供的数据上下文，而不是通过 shell 命令获取数据。如果侧边栏需要的数据未公开，请在 customSidebarDataContext 中找出缺失字段，并将添加该字段视为 cmux 工作树中的应用代码更改。

5. 如果更改了应用或运行时代码，请遵循 cmux 仓库工作流：创建工作树，阅读仓库内的说明，将面向用户的字符串本地化，进行适当测试，并在交接内部试用前使用标签重新加载。仅更改配置侧边栏 .swift 文件无需重新构建应用。

编写规则

• 不要将 cmux right-sidebar set <name> 或右侧边栏配置用于自定义边栏。用户希望在工作内容旁查看边栏时，应通过 cmux sidebar open <name> 在 Bonsplit 窗格中呈现自定义边栏。
• 左侧边栏选择器是预览／选择界面。不要将右侧边栏用作自定义边栏的宿主。
• 除非用户明确要求使用 ExtensionKit，否则不要使用它。
• 保持自定义边栏文件精简且便于检查。如果设计变得复杂，只有在解释器支持的情况下才将行为拆分为简单的辅助函数。
• 通过受支持的 Button 操作负载明确呈现每个可见操作。未经检查 repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swift 和应用分发逻辑，不要臆造操作 ID。
• 优先使用 cmux 上下文中的真实工作区、界面、通知、端口、git 和进度字段。除非任务仅是制作模型，否则避免使用占位仪表板。
• 发生渲染失败时，将文件精简到能复现问题的最小边栏，然后与 CmuxSwiftRender 测试和示例库进行比较。

验证

对于仅涉及配置的边栏：

ls ~/.config/cmux/sidebars
cmux sidebar validate <name>
cmux sidebar open <name>

正常编写过程中不要更改用户选定的／默认边栏。除非用户明确要求启用自定义边栏，否则原始工作区边栏应保持为默认项。

打开后，验证自定义边栏是窗格界面，而不是右侧边栏：

cmux identify --json --id-format both
cmux tree --workspace <workspace-ref> --json --id-format both
cmux right-sidebar set <name>   # should fail on current builds; do not use this for setup

对于带标签的 dogfood 测试，请使用与标签绑定的开发 CLI 和套接字，例如 ~/.local/bin/cmux-dev --socket /tmp/cmux-debug-<tag>.sock sidebar open <name> --json，然后验证聚焦界面报告 surface_type: customSidebar。

如果正在运行的 cmux 版本支持，请在不进行选择的情况下重新加载有效的自定义边栏：

cmux sidebar reload --all

仅编辑边栏文件不应被视为重新加载信号。请在写入完成后使用 CLI 重新加载命令，以免尚未写完的文件替换已挂载的边栏。

只有在用户明确要求启用自定义边栏时，才验证并选择它：

cmux sidebar select <name>

对于不支持 cmux sidebar 的旧版 cmux，请让用户从左侧边栏选择器中选取指定名称的边栏。除非用户明确要求进行临时本地 dogfood 设置，否则避免使用 defaults write 来选择边栏，并说明这不是产品默认设置。

对于解释器或应用变更，优先运行 CmuxSwiftRender 的针对性软件包测试，并进行最小规模的真实 dogfood 重新加载。不要在本地 cmux 上运行 xcodebuild ... test；请遵循项目的远程或 CI 测试指南。