Agent Skills › J-x-Z/cocoa-way › cocoa-way-diagnose

cocoa-way-diagnose

GitHub

用于诊断 Cocoa-Way 显示服务器、Apple Container、Docker 及 OrbStack 等组件的故障。通过收集环境证据、分类主机/传输/运行时/客户机错误，并生成脱敏的 GitHub Issue，辅助 Bug 复现与排查。

skills/cocoa-way-diagnose/SKILL.md J-x-Z/cocoa-way

Trigger Scenarios

复现 Bug 时分析日志以定位根因时检查新机器配置时起草精简的 GitHub Issue 时

Install

npx skills add J-x-Z/cocoa-way --skill cocoa-way-diagnose -g -y

More Options

Use without installing

npx skills use J-x-Z/cocoa-way@cocoa-way-diagnose

指定 Agent (Claude Code)

npx skills add J-x-Z/cocoa-way --skill cocoa-way-diagnose -a claude-code -g -y

安装 repo 全部 skill

npx skills add J-x-Z/cocoa-way --all -g -y

预览 repo 内 skill

npx skills add J-x-Z/cocoa-way --list

SKILL.md

Frontmatter

{
    "name": "cocoa-way-diagnose",
    "description": "Diagnose Cocoa-Way compositor, Apple Container, Docker, OrbStack, waypipe, display, clipboard, performance, and rootless\/desktop failures. Use when reproducing a bug, triaging logs, checking a new machine, or drafting a concise redacted GitHub issue."
}

Diagnose Cocoa-Way

Collect evidence before changing code. Distinguish host compositor, transport, runtime, guest image, and guest application failures instead of treating every warning as the root cause.

Workflow

Call cocoa_way_environment, cocoa_way_features, and cocoa_way_status.
Call cocoa_way_sessions and cocoa_way_displays. If one session is implicated, call cocoa_way_logs for it.
Prefer cocoa_way_diagnostics for a single redacted snapshot. If MCP is unavailable, run cocoa-wayctl --json diagnostics [SESSION] against the local control socket.
Reproduce once with the smallest suitable guest application. Use desktop presentation for niri/Hyprland and rootless only for regular xdg-shell applications.
Classify the first actionable failure:
- host: Cocoa-Way crash, Metal/GLES error, focus/input, resize, or display lifecycle
- transport: waypipe/socket/relay disconnect, latency, clipboard, or audio
- runtime: Apple Container, Docker, OrbStack, image, volume, or machine lifecycle
- guest: missing executable/library/socket, unsupported image, compositor configuration
Confirm whether the process really failed. Locale watcher, missing icon, Xwayland integration, and dmabuf fallback warnings can be non-fatal when the surface still renders.
Call cocoa_way_issue_draft with factual steps, expected result, and actual result. Review and trim the generated Markdown before submission.

Safety

Keep diagnosis read-only unless the user explicitly authorizes a change.
Never delete images, containers, volumes, machines, or profiles as a diagnostic shortcut.
Never post an issue or upload logs automatically.
Preserve the Metal rendering path; do not force software rendering to hide a transport or buffer bug.
Redact home paths, account names, tokens, registry credentials, SSH hosts, and unrelated process output.
Include exact Cocoa-Way, Apple Container, waypipe, macOS, architecture, presentation, and transport versions when relevant.

Issue Quality

Produce one issue per independently reproducible defect. Include the shortest reproduction, whether desktop/rootless and default/dedicated display were used, the first actionable error, and whether the problem survives a clean Cocoa-Way restart. Do not pad reports with harmless warning floods or speculative fixes.