用途:作为 windowctl 的自然语言入口,把用户的窗口操作意图映射到对应的 windowctl 命令,覆盖列出窗口、列出显示器(含 ACTIVE / FOCUSED)、移动窗口、原地调整大小、聚焦/提升窗口等场景。
主要能力:技能负责意图路由与配方知识,windowctl 负责各操作系统底层窗口操作,不直接调用 Quartz、Win32、X11 或 wmctrl。显示器按 (X, Y) 原点升序 1 起始编号,最左侧显示为 1,编号跨重启与重新插拔稳定;可通过 monitors list --json 把“笔记本”“外接”“当前活动”“光标所在”等描述映射为整数 ID 再传 --monitor。windows list --json 提供每个窗口的 Focused 标志,monitors list --json 提供每个显示器的 Active(光标)与 Focused(最前窗口质心),用于判断“这个窗口”。
使用方式:行动前先发现,任何移动/聚焦/缩放前运行 windowctl windows list --json 确认唯一匹配;--title 为不区分大小写子串,--app 为不区分大小写精确匹配,空字符串会被拒绝。--zone 与 --x/--y/--w/--h 互斥,坐标模式下 --w/--h 必须大于 0。带 --monitor 时原始 --x/--y 相对该显示器原点,不带则为全局虚拟桌面绝对坐标。macOS 首次拒绝辅助功能权限时需运行 windowctl permissions 触发授权提示,授权后重跑原命令;调试可用 WCTL_AX_DEBUG=1 查看每 PID 的 AX 转储。缺失安装时执行 npm install -g @muthuishere/windowctl。
限制:Linux 适配器依赖 wmctrl 与 xrandr,Wayland 仅限 wmctrl 能模拟的范围,不保证像素级精确放置。操作系统或应用拒绝所请求几何尺寸时(如 Chrome 最小尺寸、沙箱限制、全屏窗口),move/resize 以非零退出并返回提示,属软失败,需原样呈现且不要自动重试。不要一次性输出庞大窗口列表。每个成功操作后停止,不自动串联后续操作。会话上下文仅保存在对话记忆中,不写文件。