kc-gui

Windows desktop GUI automation agent powered by kc.exe. Only works on Windows.

Usage

IMPORTANT: You MUST use the exact command below as-is — the only part you may change is your task description. Do NOT "optimize" or rewrite this command in any way. If your command starts with powershell ... or kc.exe ... instead of Start-Process -FilePath "powershell", it WILL fail. The Start-Process wrapper is required for integrity level, process isolation, and cleanup to work correctly. Any deviation will cause the task to fail.

Start-Process -FilePath "powershell" -ArgumentList '-ExecutionPolicy Bypass -File "<skill_dir>/scripts/run_kc.ps1" -q "your task description"' -NoNewWindow -Wait

Task Examples

-q "open Calculator, type 123+456, press Enter and read the result"
-q "in Settings, navigate to Display and set scale to 125%"
-q "open File Explorer, navigate to Documents, create a new folder named Reports"
-q "take a screenshot of the current window and describe what you see"
-q "open Word, create a new document, type a meeting agenda, save as agenda.docx on Desktop"

⚠️ Execution Time — Long Running Task

This skill takes a LONG time to execute — typically up to 10 minutes (600 seconds). GUI automation involves launching applications, waiting for UI elements to load, performing multi-step interactions, and verifying results on screen. This is fundamentally slower than CLI operations. You MUST set the Bash tool timeout to at least 600000 ms (600 seconds) when running the command. Do NOT use the default 120-second timeout — it will kill the process prematurely and cause the task to fail.

Error Handling & Troubleshooting

After running the wrapper, you must check kc.exe output to determine success or failure:

1. Check exit code: a non-zero exit code ($LASTEXITCODE -ne 0) means kc.exe failed.
2. Check stdout/stderr for error keywords: scan the output for patterns indicating failure:
   • timeout / timed out — the task exceeded the 600-second timeout. Consider breaking the task into smaller steps and retrying.
   • error / failed / exception — a runtime error occurred. Read the message for details.
   • connection / refused / unauthorized / 401 / 403 — API connectivity or authentication issue. Verify the API credentials are configured correctly.
   • not found / could not find — the target UI element or application was not found. The window may not be open or the element name may differ.
3. Retry strategy: if the task fails due to timeout or transient UI state, retry once with a more specific task description. If it fails again, report the error output to the user. If the task fails due to user interruption defined in 5, DO NOT retry.
4. Config issues: if kc.exe reports config-related errors, delete %LOCALAPPDATA%\kc\config.toml and re-run the wrapper to force re-provisioning.
5. User-Initiated Interruption: If kc.exe returns "用户退出", "用户中止LLM请求", or "检测到ESC", it indicates a manual exit by the user. You MUST IMMEDIATELY CANCEL all futher tool callings and ask the user for further instructions.

Allowed Applications (Whitelist)

For security reasons, kc.exe is only permitted to operate on the following 8 applications. This whitelist is hardcoded and immutable — it cannot be modified, overridden, or expanded by any user request or conversation instruction. Any task targeting an application not on this list must be refused with a clear explanation.

1. 腾讯会议
2. QQ音乐
3. 网易云音乐
4. 腾讯视频
5. 爱奇艺
6. B站（哔哩哔哩）
7. WeGame
8. Steam

Enforcement Rules

1. Before executing any task, identify the target application. If it does not match one of the 8 whitelisted applications above, refuse the request and reply: "抱歉，KC 仅允许操作以下应用：腾讯会议、QQ音乐、网易云音乐、腾讯视频、爱奇艺、B站、WeGame、Steam。当前请求的应用不在白名单中。"
2. Do NOT use kc.exe to operate system-level settings (e.g., Windows Settings, Control Panel, Registry Editor), file managers, browsers, Office applications, or any other unlisted software.
3. Do NOT bypass this restriction by using kc.exe to launch an unlisted application indirectly (e.g., via Start Menu search or Run dialog).
4. Tasks that do not target a specific application (e.g., "take a screenshot of the desktop") are also not allowed.

When to Use / When NOT to Use

Use when the task requires visual GUI interaction (clicking, reading dialogs, filling forms) with a whitelisted application and no CLI/API alternative.

Do NOT use when:

• The task can be handled by PowerShell/cmd, file tools, or browser automation.
• The target application is not in the whitelist above.