feat(skills): add treeland-debug skill for AI debugging - #1347
Merged
zccrs merged 1 commit intoAug 31, 2026
Conversation
Reviewer's GuideIntroduces a comprehensive treeland-debug agent skill that standardizes live compositor inspection, control, logging, symptom-based diagnosis, and post-fix verification. Sequence diagram for treeland runtime diagnosissequenceDiagram
participant AI as AI debugger
participant DConfig
participant Service as treeland.service
participant CLI as treeland-debug
participant Tree as WindowTree
participant Journal as journalctl
AI->>DConfig: set debugSource true
AI->>Service: restart treeland
AI->>CLI: windows or tree
CLI->>Tree: inspect live compositor state
Tree-->>CLI: window/layout data
CLI-->>AI: diagnostic result
AI->>CLI: screenshot output or screenshot window
CLI->>Tree: capture rendered image
Tree-->>CLI: PNG bytes
CLI-->>AI: screenshot path
AI->>Journal: read treeland.service logs
Journal-->>AI: runtime diagnostics
Flow diagram for symptom-based treeland debuggingflowchart TD
A["Reproduce runtime symptom"] --> B{"What is affected?"}
B -->|Window state| C["Inspect windows, tree, and scene"]
B -->|Focus or input| D["Inspect active window and cursor; inject event"]
B -->|Output or rendering| E["Inspect tree and capture screenshot"]
B -->|Crash or hang| F["Read service or ASAN logs; inspect clients/top"]
C --> G["Match logs to affected category"]
D --> G
E --> G
F --> G
G --> H["Fix root cause and rerun the same treeland-debug check"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 security issue, and 3 other issues
Security issues:
- Insecure WebSocket Detected. WebSocket Secure (wss) should be used for all WebSocket connections. (link)
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path=".agents/skills/treeland-debug/SKILL.md" line_range="27-30" />
<code_context>
+## Runtime context
+treeland runs in two modes:
+
+- **Global mode** (preferred, on DDM): one process manages all users; it runs as the **`dde`** user under systemd user service `treeland.service`, bus name `org.deepin.Compositor1`. `ExecStart=.../treeland.sh --lockscreen`.
+- **User mode**: starts per-user as a normal window manager.
+
+Because of global mode, most runtime debugging commands must run **as the `dde` user**: `sudo -u dde -- <cmd>`. The debug Remote Object's local socket is owner-only, so a non-`dde` user cannot connect.
+
+## Enable the debug source (first step)
</code_context>
<issue_to_address>
**issue:** The skill treats `treeland.service` as a systemd user service and instructs `systemctl --user`/`journalctl --user`, but the unit is installed as a system service with `User=dde`; these commands address the wrong manager and do not find or configure the compositor service. In addition, the unit sets `StandardOutput=null` and `StandardError=null`, so the documented journal commands cannot retrieve Treeland's normal stdout/stderr logs.
**Triggers:** When debugging global-mode Treeland using the documented logging workflow.
**Suggested fix:** Use the system-manager commands for the unit, such as `systemctl restart treeland.service` and `journalctl -u treeland.service`; document the actual mechanism for applying `QT_LOGGING_RULES` to this system service and note that the current unit discards standard output and error.
</issue_to_address>
### Comment 2
<location path=".agents/skills/treeland-debug/SKILL.md" line_range="66" />
<code_context>
+---
+name: treeland-debug
+description: Use this skill whenever a task asks you to debug, diagnose, reproduce, or analyze a problem in the running treeland compositor — window/workspace/input/output/rendering issues, crashes, hangs, focus problems, or requests to inspect live state. Trigger on `treeland-debug`, `debugSource`, `WindowTree` Remote Object, `QT_LOGGING_RULES`, treeland logging categories, `journalctl` for treeland, `org.deepin.Compositor1`, window tree inspection, input event injection, or screenshot capture from a live compositor. Pair with the systematic-debugging approach: reproduce, isolate, then fix at the root cause.
</code_context>
<issue_to_address>
**issue (bug_risk):** The skill says raw Linux evdev keycodes are accepted, but `treeland-debug` passes numeric key arguments through as `Qt::Key` values and the Remote Object API expects `Qt::Key`; supplying an evdev code such as Linux `KEY_ENTER` therefore injects the wrong key.
**Triggers:** When an AI follows the documented raw numeric evdev-keycode syntax.
**Suggested fix:** Document numeric arguments as Qt::Key values, or change the CLI/server conversion so documented Linux evdev codes are translated before calling `sendKey`.
```suggestion
`move-cursor <x> <y>`, `event motion <x> <y>`, `event button <btn> [press|release|click]`, `event key <key> [press|release|tap]`. Pointer buttons use Linux input codes (`left`=0x110, `right`=0x111, `middle`=0x112); numeric keys use Qt::Key values or common names (`enter`, `esc`, `space`, `a`–`z`, `0`–`9`, `f1`–`f12`, arrows). Keys go to the **keyboard-focused** surface — `activate` a window first; pointer buttons go to the surface under the cursor — move the cursor there first.
```
</issue_to_address>
### Comment 3
<location path=".agents/skills/treeland-debug/SKILL.md" line_range="94" />
<code_context>
+sudo -u dde -- treeland-debug event button left click
+
+# screenshot
+sudo -u dde -- treeland-debug screenshot output /tmp/ss.png
+sudo -u dde -- treeland-debug screenshot window 93824992268800
+```
</code_context>
<issue_to_address>
**issue:** The example `screenshot output /tmp/ss.png` supplies `/tmp/ss.png` as the output name, not the file path, because the command syntax is `screenshot output [name] [file]`; the command consequently captures the primary output to an auto-generated `/tmp/treeland-debug-*.png` path instead of writing `/tmp/ss.png`.
**Triggers:** When following the quick-start screenshot example.
**Suggested fix:** Use `screenshot output '' /tmp/ss.png` if the parser supports an empty name, or document the required output name explicitly, for example `screenshot output DP-1 /tmp/ss.png`.
```suggestion
sudo -u dde -- treeland-debug screenshot output DP-1 /tmp/ss.png
```
</issue_to_address>
### Comment 4
<location path=".agents/skills/treeland-debug/SKILL.md" line_range="72" />
<code_context>
`shell` — interactive REPL. `listen [--port <p>] [--host <a>]` — HTTP/WebSocket server exposing the same capabilities for a browser frontend (`/api/*`, `ws://host:port/ws`). See `tools/treeland-debug/README.md` for the full REST/WS reference.
</code_context>
<issue_to_address>
**security (javascript.lang.security.detect-insecure-websocket):** Insecure WebSocket Detected. WebSocket Secure (wss) should be used for all WebSocket connections.
*Source: opengrep*
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
deepin-wm
pushed a commit
to deepin-wm/treeland
that referenced
this pull request
Aug 28, 2026
Address the review comments on PR linuxdeepin#1347: - treeland.service is a system unit (User=dde), not a user unit: use systemd drop-in for QT_LOGGING_RULES and the system journal; note the unit discards stdout/stderr (StandardOutput/StandardError=null). - event key numeric args are Qt::Key values, not Linux evdev keycodes. - fix screenshot output example to the correct [name] [file] syntax. - document listen mode as unauthenticated and defaulting to 0.0.0.0, recommend binding to 127.0.0.1.
|
TAG Bot New tag: 0.9.1 |
deepin-wm
pushed a commit
to deepin-wm/treeland
that referenced
this pull request
Aug 31, 2026
Address the review comments on PR linuxdeepin#1347: - treeland.service is a system unit (User=dde), not a user unit: use systemd drop-in for QT_LOGGING_RULES and the system journal; note the unit discards stdout/stderr (StandardOutput/StandardError=null). - event key numeric args are Qt::Key values, not Linux evdev keycodes. - fix screenshot output example to the correct [name] [file] syntax. - document listen mode as unauthenticated and defaulting to 0.0.0.0, recommend binding to 127.0.0.1.
deepin-wm
force-pushed
the
agent/developer/55500acb-skill
branch
from
August 31, 2026 08:16
7a1218b to
dad2586
Compare
zccrs
approved these changes
Aug 31, 2026
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: deepin-wm, zccrs The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
deepin-wm
force-pushed
the
agent/developer/55500acb-skill
branch
from
August 31, 2026 08:27
dad2586 to
2571034
Compare
添加给 AI 调试 treeland 使用的 debug 技能，覆盖 treeland-debug CLI、 日志分类、运行时诊断流程等，协助 AI 排查合成器运行期问题。
deepin-wm
force-pushed
the
agent/developer/55500acb-skill
branch
from
August 31, 2026 08:31
2571034 to
43e1898
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
为 AI 调试 treeland 新增一个可复用的 debug 技能，协助 AI 理解、分析和排查 treeland（基于 wlroots 与 QtQuick 的 Wayland 合成器）运行期问题。
Changes
.agents/skills/treeland-debug/SKILL.md，沿用仓库已有.agents/skills/<name>/SKILL.md约定。技能覆盖：
debugSourceDConfig 开关 + 重启 treeland 的步骤src/common/treelandlogging.*分类、QT_LOGGING_RULES、journalctl --user -u treeland.service、ASAN 落盘、treeland.shpixman 软渲染回退dde用户运行、用截图作为渲染判定依据、修码后回到同一treeland-debug命令复验Summary by Sourcery
Add a comprehensive treeland-debug skill to guide AI-assisted diagnosis and verification of runtime compositor issues.
New Features:
Enhancements:
Documentation: