Back to Details

deskctl

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

deskctl

deskctl

Non-interactive desktop control CLI for Linux X11 agents.
All output follows the runtime contract defined in references/runtime-contract.md. Every command returns a stable JSON envelope when called with 
--json
. Use 
--json
whenever you need to parse output programmatically.
面向Linux X11 Agent的非交互式桌面控制CLI工具。
所有输出遵循 references/runtime-contract.md 中定义的运行时契约。所有命令在添加 
--json
参数调用时都会返回稳定的JSON封装结构。如果你需要以编程方式解析输出，请始终使用 
--json
参数。

Quick start

快速开始

bash
npm install -g deskctl
deskctl doctor
deskctl snapshot --annotate
If 
deskctl
was installed through npm, refresh it later with:
bash
deskctl upgrade --yes
bash
npm install -g deskctl
deskctl doctor
deskctl snapshot --annotate
如果是通过npm安装的
deskctl
，后续可以通过以下命令更新：
bash
deskctl upgrade --yes

Agent loop

Agent循环

Every desktop interaction follows: observe -> wait -> act -> verify.
bash
deskctl snapshot --annotate        # observe
deskctl wait window --selector 'title=Chromium' --timeout 10  # wait
deskctl click 'title=Chromium'      # act
deskctl snapshot                   # verify
See workflows/observe-act.sh for a reusable script. See workflows/poll-condition.sh for polling loops.
所有桌面交互都遵循：观察 -> 等待 -> 执行 -> 验证 的流程。
bash
deskctl snapshot --annotate        # 观察
deskctl wait window --selector 'title=Chromium' --timeout 10  # 等待
deskctl click 'title=Chromium'      # 执行
deskctl snapshot                   # 验证
可参考 workflows/observe-act.sh 获取可复用脚本，参考 workflows/poll-condition.sh 实现轮询循环。

Selectors

选择器

bash
ref=w1          # snapshot ref (short-lived)
id=win1         # stable window ID (session-scoped)
title=Chromium   # match by title
class=chromium   # match by WM class
focused         # currently focused window
Bare strings like 
chromium
do fuzzy matching but fail on ambiguity. Prefer explicit selectors.
bash
ref=w1          # 快照引用（短时效）
id=win1         # 稳定窗口ID（会话维度）
title=Chromium   # 按标题匹配
class=chromium   # 按窗口管理器类匹配
focused         # 当前聚焦的窗口
类似 
chromium
这种裸字符串会进行模糊匹配，但存在歧义时会匹配失败，推荐优先使用显式选择器。

References

参考

  • references/runtime-contract.md - output contract, stable fields, error kinds
  • references/commands.md - all available commands
  • references/runtime-contract.md - 输出契约、稳定字段、错误类型
  • references/commands.md - 所有可用命令

Workflows

工作流

  • workflows/observe-act.sh - main observe-act loop
  • workflows/poll-condition.sh - poll for a condition on screen
  • workflows/observe-act.sh - 核心观察-执行循环
  • workflows/poll-condition.sh - 轮询屏幕上的指定条件