SKILL.md
只读
名称
cmux-socket-policy
描述
cmux CLI/Socket 开发中的 Socket 命令线程与焦点控制策略。适用于添加或修改 Socket 命令、CLI 命令、遥测（telemetry）命令，调整焦点/选择/打开/关闭/发送按键（focus/select/open/close/send-key）行为，或编写可能抢占应用焦点的自动化脚本等场景。
cmux Socket 策略
线程策略
- 禁止在高频 Socket 遥测（telemetry）命令（如
report_*、ports_kick、状态/进度更新或日志元数据更新）中使用DispatchQueue.main.sync。 - 对于遥测热路径（hot paths），应在主线程之外（off-main）完成参数解析与校验。
- 优先在主线程之外完成去重（dedupe）与合并（coalesce）。
- 仅在必要时才通过
DispatchQueue.main.async调度最少量的 UI 或数据模型变更。 - 直接操作 AppKit/Ghostty UI 状态的命令允许运行在 main actor（主线程）上。
- 添加新的 Socket 命令时，默认应在主线程之外处理；若必须在主线程执行，须在代码注释中给出明确理由。
焦点策略
- Socket/CLI 命令严禁抢占 macOS 应用的焦点。
- 除非命令显式具备焦点意图（focus intent），否则不得激活应用或拉起窗口。
- 只有明确具备焦点意图的命令才可以修改应用内部的焦点/选中状态。
- 具备明确焦点意图的命令包括：
window.focus、workspace.select/next/previous/last、surface.focus、pane.focus/last、浏览器焦点命令以及 v1 等价的焦点命令。 - 所有非焦点命令在应用数据/模型变更的同时，必须保持用户当前的焦点上下文不受干扰。
详细参考
- 添加命令、变更命令执行上下文或评估是否允许修改焦点时，请查阅 references/threading-and-focus.md。
