在 cmux 中编写/修改解释型自定义侧边栏时，用…

适用于为 cmux 创建、检查或修订 ~/.config/cmux/sidebars/*.swift 自定义侧边栏，并希望在不改变默认侧边栏的前提下，用 Bonsplit 面板和 CLI 验证渲染与交互。

适用场景

解决思路

1. 需要追溯实现时，查看原始工作 PR：https://github.com/manaflow-ai/cmux/pull/5254（作者 Aziz Albahar）。
2. 确认自定义侧边栏特性由 UserDefaults-backed key `customSidebars.beta.enabled` 控制；侧边栏文件位于 `~/.config/cmux/sidebars/`，可用 `cmux sidebar open <name>` 作为普通 Bonsplit pane tab 打开，并在启用 beta 后出现在左侧 sidebar picker。
3. 从 cmux app checkout 文档 `repo/docs/custom-sidebars.md` 开始阅读。
4. 需要查实现时，检查这些入口：`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`、`repo/Sources/Workspace+CustomSidebarPane.swift`、`repo/Sources/TerminalController+CustomSidebarCommands.swift`。
5. 需要跟进实现时，检查分支 `origin/feat-interpreter-primitives`（更广泛的 SwiftUI-ish primitive 支持面）和 `origin/feat-sidebar-interpreter-isolation`（进程外崩溃隔离的解释器 worker）。
6. 编写前检查当前 app 文档和解释器支持面：`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`。
7. 创建或编辑用户配置目录中的侧边栏文件：`mkdir -p ~/.config/cmux/sidebars`；`$EDITOR ~/.config/cmux/sidebars/<name>.swift`。
8. 保持在解释器子集内：优先使用简单 SwiftUI 风格表达式 `VStack`、`HStack`、`Text`、`Image`、`Button`、`ForEach`、条件语句、受支持的 modifier，以及来自所提供 context 的数据。
9. 不要假设任意 Swift、`imports`、async 工作、文件系统访问、网络、自定义类型或编译依赖可用。
10. 使用提供的 data context，而不是 shelling out；如果侧边栏需要未暴露的数据，在 `customSidebarDataContext` 中定位缺失字段，并将其视为 cmux worktree 中的 app code change。
11. 如果修改 app/runtime code，遵循 cmux repo workflow：创建 worktree、阅读 repo-local instructions、本地化 user-facing strings、适当测试，并在 dogfood handoff 前用 tag reload。
12. 仅编辑配置侧边栏 `.swift` 不需要 app rebuild。
13. 不要用 `cmux right-sidebar set <name>` 或 right-sidebar configuration 来设置 custom sidebars；用户想在 work 旁看到侧边栏时，应通过 `cmux sidebar open <name>` 渲染到 Bonsplit pane。
14. 左侧 sidebar picker 是 preview/selection surface；不要把 right sidebar 当作 custom-sidebar host。
15. 除非用户明确要求，否则不要使用 ExtensionKit。
16. 保持 custom sidebar 文件小且可检查；如果设计变复杂，只有在解释器支持时才把行为拆成简单 helper functions。
17. 每个可见 action 都要通过受支持的 `Button` action payload 明确表达；不要在未检查 `repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swift` 和 app dispatch wiring 的情况下发明 action id。
18. 优先使用 cmux context 中真实的 workspace、surface、notification、port、git 和 progress 字段；除非任务只是 mockup，否则避免 placeholder dashboards。
19. 发生 rendering failure 时，缩减到能复现问题的最小 sidebar 文件，再与 `CmuxSwiftRender` tests 和 corpus examples 对比。
20. 仅配置侧边栏的验证：`ls ~/.config/cmux/sidebars`；`cmux sidebar validate <name>`；`cmux sidebar open <name>`。
21. 正常 authoring 时不要改变用户已选择/默认的 sidebar；除非用户明确要求激活 custom sidebar，否则 original workspaces sidebar 应保持默认。
22. 打开后验证 custom sidebar 是 pane surface，而不是 right sidebar：`cmux identify --json --id-format both`；`cmux tree --workspace <workspace-ref> --json --id-format both`；`cmux right-sidebar set <name>`（当前 build 应失败；不要用它做 setup）。
23. 进行 tagged dogfood 时，使用 tag-bound dev CLI 和 socket，例如：`~/.local/bin/cmux-dev --socket /tmp/cmux-debug-<tag>.sock sidebar open <name> --json`，然后验证 focused surface 报告 `surface_type: customSidebar`。
24. 如果运行中的 cmux build 支持，在不选择某个 sidebar 的情况下 reload 有效 custom sidebars：`cmux sidebar reload --all`。
25. 不要仅把编辑 sidebar 文件当作 reload signal；写完后再用 CLI reload command，避免半写入文件替换已挂载的 sidebar。
26. 只有用户明确要求激活 custom sidebar 时，才验证并选择：`cmux sidebar select <name>`。
27. 对于没有 `cmux sidebar` 的旧 cmux build，请用户从左侧 sidebar picker 中选择命名 sidebar；避免用 `defaults write` 做 sidebar selection，除非用户明确要求临时本地 dogfood setup，并说明这不是 product default。
28. 对于 interpreter 或 app changes，优先跑 `CmuxSwiftRender` 的 focused package tests，再加最小的真实 dogfood reload；不要运行本地 cmux `xcodebuild ... test`，使用项目的 remote 或 CI test guidance。

适用边界 · 注意事项

• 没有 cmux 应用、未启用 customSidebars.beta.enabled，或无法访问 ~/.config/cmux/sidebars/ 时，不适用于本流程。
• 需要任意 Swift、imports、async 工作、文件系统访问、网络、自定义类型或编译依赖时，不适用，因为解释器不支持这些能力。
• 用户明确要右侧边栏、ExtensionKit 或其他非 Bonsplit 面板承载方式时，不要按本技能默认流程处理（除非其明确要求该 surface）。