SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cmux-sidebar-builder

cmux-sidebar-builder

编程与开发

查看项目

更新于 10-15 12:16

技能介绍

用途

cmux-sidebar-builder 用于创建或修改 cmux 自定义侧边栏视图。这些侧边栏是用户或智能体编写的 .swift 文件，位于 ~/.config/cmux/sidebars/，由 cmux 运行时的 SwiftUI 风格解释器渲染，不是编译后的应用代码。主要使用场景是在普通 Bonsplit 面板标签中打开，命令为 cmux sidebar open <name>；左侧侧边栏选择器仍可用于预览。

主要能力

  • 在 ~/.config/cmux/sidebars/ 下创建或编辑自定义侧边栏 .swift 文件。
  • 使用解释器支持的 SwiftUI 风格子集编写界面，例如 VStack、HStack、Text、Image、Button、ForEach、条件语句、受支持的修饰符，以及来自所提供上下文的数据。
  • 通过 cmux sidebar validate <name> 验证侧边栏，通过 cmux sidebar open <name> 打开，通过 cmux sidebar reload --all 重新加载。
  • 在需要时检查 cmux 源码入口点，包括 SwiftViewInterpreter.swift、ExpressionEvaluator.swift、RenderNode.swift、CustomSidebarView.swift、ContentView.swift、CustomSidebarPanel.swift、Workspace+CustomSidebarPane.swift 和 TerminalController+CustomSidebarCommands.swift。
  • 可参考后续实现分支：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 风格表达式。不要假设任意 Swift、导入、异步工作、文件系统访问、网络、自定义类型或编译依赖可用。

  4. 使用提供的数据上下文，而不是调用 shell。如果侧边栏需要未暴露的数据，请在 customSidebarDataContext 中识别缺失字段，并将其视为 cmux worktree 中的应用代码更改。

  5. 如果更改应用或运行时代码，请遵循 cmux 仓库工作流：创建 worktree、阅读仓库本地说明、本地化面向用户的字符串、适当测试，并在 dogfood 交接前用标签重新加载。仅配置的侧边栏 .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> # 在当前构建中应失败；不要用于设置

对于带标签的 dogfood，使用绑定标签的开发 CLI 和 socket，例如 ~/.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 测试指南。

适用场景

  • 侧边栏 vibe coding。
  • 在 Bonsplit 中创建或修改自定义侧边栏。
  • 检查或修订 cmux 自定义侧边栏视图。

限制

  • 自定义侧边栏必须保持在解释器支持的 SwiftUI 风格子集内，不支持任意 Swift、导入、异步工作、文件系统访问、网络、自定义类型或编译依赖。
  • 该功能通过 UserDefaults 键 customSidebars.beta.enabled 选择性启用。
  • 不要将右侧边栏用作自定义侧边栏宿主。
  • 不要使用 cmux right-sidebar set <name> 或右侧边栏配置来设置自定义侧边栏。
  • 除非用户明确要求，否则不要使用 ExtensionKit。
  • 不要在没有检查 ActionCommand.swift 和应用调度接线的情况下发明操作 ID。
  • 仅编辑侧边栏文件本身不应被视为重新加载信号。
  • 不要运行本地 cmux xcodebuild ... test。
  • 原始工作区侧边栏应保持默认，除非用户明确要求激活自定义侧边栏。
  • 对于没有 cmux sidebar 的旧版 cmux 构建，需用户从左侧侧边栏选择器中选择。
  • 避免使用 defaults write 进行侧边栏选择，除非用户明确要求临时本地 dogfood 设置。