cmux-sidebar-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux sidebar builder

cmux侧边栏构建器

Use this skill when the task is to create or modify a cmux custom sidebar view. These are user/agent-authored

.swift

files in

~/.config/cmux/sidebars/

rendered by cmux's runtime SwiftUI-style interpreter, not compiled app code. The primary dogfood surface is a normal Bonsplit pane tab opened with

cmux sidebar open <name>

; the left sidebar picker remains useful for previews.

当需要创建或修改cmux自定义侧边栏视图时，请使用此技能。这些是由用户/Agent编写的

.swift

文件，存储在

~/.config/cmux/sidebars/

目录下，由cmux的运行时SwiftUI风格解释器渲染，而非编译后的应用代码。主要的Dogfood测试载体是通过

cmux sidebar open <name>

打开的普通Bonsplit面板标签页；左侧边栏选择器仍可用于预览。

Orientation

说明

The original work is PR

https://github.com/manaflow-ai/cmux/pull/5254

by Aziz Albahar.

The feature is opt-in behind the UserDefaults-backed key
```
customSidebars.beta.enabled
```
.
Custom sidebars live under
```
~/.config/cmux/sidebars/
```
. They can be opened as normal Bonsplit pane tabs with
```
cmux sidebar open <name>
```
and appear in the left sidebar picker when the beta is enabled.
Start from the cmux app checkout docs:
```
repo/docs/custom-sidebars.md
```
.

Important cmux source entrypoints:

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

, around

customSidebarsDirectory

customSidebarDataContext

, and

CustomSidebarView(...)

repo/Sources/Panels/CustomSidebarPanel.swift

for the Bonsplit pane host.

repo/Sources/Workspace+CustomSidebarPane.swift

and

repo/Sources/TerminalController+CustomSidebarCommands.swift

for the

cmux sidebar open <name>

path.

Follow-up implementation branches to inspect when needed:

```
origin/feat-interpreter-primitives
```
for the broader supported SwiftUI-ish primitive surface.
```
origin/feat-sidebar-interpreter-isolation
```
for the out-of-process crash-isolated interpreter worker.

最初的工作由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
```
：进程外崩溃隔离的解释器工作线程实现。

Workflow

工作流程

Inspect the current app docs and interpreter surface before authoring:

bash

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

Create or edit the sidebar file in the user's config directory:

bash

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

Stay inside the interpreted subset. Prefer simple SwiftUI-style expressions:
```
VStack
```
,
```
HStack
```
,
```
Text
```
,
```
Image
```
,
```
Button
```
,
```
ForEach
```
, conditionals, supported modifiers, and data from the provided context. Do not assume arbitrary Swift, imports, async work, filesystem access, networking, custom types, or compiled dependencies are available.
Use the provided data context instead of shelling out. If the sidebar needs data that is not exposed, identify the missing field in
```
customSidebarDataContext
```
and treat adding it as an app code change in a cmux worktree.
If you change app/runtime code, follow the cmux repo workflow: create a worktree, read repo-local instructions, localize user-facing strings, test appropriately, and reload with a tag before dogfood handoff. Config-only sidebar
```
.swift
```
edits do not require an app rebuild.

在编写前先查看当前应用文档和解释器支持范围：

bash

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

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

bash

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

仅使用解释器支持的子集。优先选择简单的SwiftUI风格表达式：
```
VStack
```
、
```
HStack
```
、
```
Text
```
、
```
Image
```
、
```
Button
```
、
```
ForEach
```
、条件语句、支持的修饰符，以及上下文提供的数据。请勿假设任意Swift代码、导入语句、异步操作、文件系统访问、网络请求、自定义类型或编译依赖均可用。
使用提供的数据上下文而非调用外部脚本。如果侧边栏需要的数据未被暴露，请在
```
customSidebarDataContext
```
中找出缺失的字段，并将添加该字段视为cmux工作树中的应用代码变更。
如果修改了应用/运行时代码，请遵循cmux仓库工作流程：创建工作树、阅读仓库本地说明、本地化用户可见字符串、进行适当测试，并在内部测试交付前重新加载标签。仅修改配置文件中的侧边栏
```
.swift
```
文件无需重建应用。

Authoring rules

编写规则

Do not use
```
cmux right-sidebar set <name>
```
or right-sidebar configuration for custom sidebars. Custom sidebars should render in a Bonsplit pane via
```
cmux sidebar open <name>
```
when the user wants to see the sidebar next to their work.
The left sidebar picker is a preview/selection surface. Do not treat the right sidebar as a custom-sidebar host.
Do not use ExtensionKit unless the user explicitly asks for that surface.
Keep custom sidebar files small and inspectable. If a design gets complicated, split behavior into simple helper functions only if the interpreter supports them.
Make every visible action explicit through supported
```
Button
```
action payloads. Do not invent action ids without checking
```
repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swift
```
and app dispatch wiring.
Prefer real workspace, surface, notification, port, git, and progress fields from the cmux context. Avoid placeholder dashboards unless the task is only a mockup.
When a rendering failure happens, reduce to the smallest sidebar file that reproduces it, then compare against
```
CmuxSwiftRender
```
tests and corpus examples.

请勿使用
```
cmux right-sidebar set <name>
```
或右侧边栏配置来设置自定义侧边栏。当用户希望在工作区旁查看侧边栏时，应通过
```
cmux sidebar open <name>
```
在Bonsplit面板中渲染自定义侧边栏。
左侧边栏选择器是预览/选择界面。请勿将右侧边栏视为自定义侧边栏的宿主。
除非用户明确要求，否则请勿使用ExtensionKit。
保持自定义侧边栏文件小巧且易于检查。如果设计变得复杂，仅在解释器支持的情况下将逻辑拆分为简单的辅助函数。
通过支持的
```
Button
```
动作负载明确每个可见操作。在未检查
```
repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swift
```
和应用调度 wiring 的情况下，请勿自行创建动作ID。
优先使用cmux上下文提供的真实工作区、界面、通知、端口、Git和进度字段。除非任务仅为制作原型，否则避免使用占位仪表板。
当出现渲染失败时，将文件简化为能复现问题的最小版本，然后与
```
CmuxSwiftRender
```
测试用例和示例 corpus 进行对比。

Verification

验证

For config-only sidebars:

bash

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

Do not change the user's selected/default sidebar as part of normal authoring. The original workspaces sidebar should remain the default unless the user explicitly asks to activate the custom sidebar.

After opening, verify the custom sidebar is a pane surface, not the right sidebar:

bash

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

For tagged dogfood, use the tag-bound dev CLI and socket, for example

~/.local/bin/cmux-dev --socket /tmp/cmux-debug-<tag>.sock sidebar open <name> --json

, then verify the focused surface reports

surface_type: customSidebar

If the running cmux build supports it, reload valid custom sidebars without selecting one:

bash

cmux sidebar reload --all

Editing a sidebar file alone should not be treated as a reload signal. Use the CLI reload command after writes are complete so half-written files do not replace a mounted sidebar.

Only when the user explicitly asks to activate the custom sidebar, validate and select it:

bash

cmux sidebar select <name>

For older cmux builds without

cmux sidebar

, ask the user to pick the named sidebar from the left sidebar picker. Avoid

defaults write

for sidebar selection unless the user explicitly requests temporary local dogfood setup, and state that it is not a product default.

For interpreter or app changes, prefer focused package tests for

CmuxSwiftRender

plus the smallest real dogfood reload. Do not run local cmux

xcodebuild ... test

; use the project's remote or CI test guidance.

对于仅修改配置的侧边栏：

bash

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

在常规编写过程中，请勿更改用户选中的/默认的侧边栏。除非用户明确要求激活自定义侧边栏，否则原始工作区侧边栏应保持为默认选项。

打开侧边栏后，验证自定义侧边栏是面板界面而非右侧边栏：

bash

cmux identify --json --id-format both
cmux tree --workspace <workspace-ref> --json --id-format both
cmux right-sidebar set <name>   # 在当前版本中应执行失败；请勿使用此命令进行设置

对于标记为Dogfood测试的版本，请使用绑定到标签的开发CLI和套接字，例如

~/.local/bin/cmux-dev --socket /tmp/cmux-debug-<tag>.sock sidebar open <name> --json

，然后验证聚焦界面是否报告

surface_type: customSidebar

。

如果运行中的cmux版本支持，无需选择即可重新加载所有有效的自定义侧边栏：

bash

cmux sidebar reload --all

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

仅当用户明确要求激活自定义侧边栏时，才进行验证并选择它：

bash

cmux sidebar select <name>

对于没有

cmux sidebar

命令的旧版cmux，请让用户从左侧边栏选择器中选择指定名称的侧边栏。除非用户明确要求临时本地Dogfood测试设置，否则请勿使用

defaults write

来选择侧边栏，并说明这并非产品默认设置。

对于解释器或应用变更，优先针对

CmuxSwiftRender

进行聚焦的包测试，再进行最小化的真实Dogfood测试重新加载。请勿运行本地cmux的

xcodebuild ... test

命令；请使用项目的远程或CI测试指南。