用途
Desktop Development Harness 用于把桌面开发工作组织成一套紧凑的闭环（harness loop）：收集运行时上下文、在代理可见的 UI 与日志下复现问题、做最小修复、通过同一路径验证，并把缺失的能力补回仓库。当任务涉及 packages/desktop、Electron 主进程、preload、渲染进程、共享桌面包、服务端、消息网关或浏览器 CDP 时使用。
当任务会改变开发工作流、可观测性、文档、测试或面向代理的 harness 本身时，应阅读 references/harness-principles.md。
快速上下文
对于 bug 报告、UI 失败、卡死、启动问题、消息问题，或任何涉及运行中桌面应用的情况，直接检查运行时日志。重要路径：
- ~/Library/Logs/@craft-agent/electron/main.log
- ~/Library/Logs/@craft-agent/electron/main.old.log
- ~/.craft-agent/logs/messaging-gateway.log
在猜测之前先搜索日志：
rg -n "error|warn|failed|exception|crash|Unhandled|rejection|browser-cdp|messaging-gateway" \
"$HOME/Library/Logs/@craft-agent/electron/main.log" \
"$HOME/.craft-agent/logs/messaging-gateway.log"
Harness 闭环
- 映射表面。判断任务涉及 Electron 主进程、preload、渲染进程、共享桌面包、服务端、消息还是浏览器 CDP。编辑前先阅读附近代码与测试。
- 收集实时证据。复现时读取并跟踪相关日志。把缺失或含糊的日志视为 bug 的一部分。
- 驱动 UI。当涉及浏览器/渲染页面时使用 Chrome DevTools MCP：list_pages、select_page、take_snapshot，然后检查 console/network。推理时优先使用无障碍快照而非截图。
- 先复现。对于 bug，捕获确切观察到的行为以及证明它的证据。如果复现结果与用户报告不同，比较环境、应用状态、构建产物、账号、时序和日志。
- 窄范围修补。把改动限制在已证明的原因范围内。只有当能消除真实重复工作或让应用对未来的代理更可读时，才添加结构。
- 通过同一路径验证。重新运行复现，再次检查日志和 DevTools，然后对触及的包运行聚焦的测试/类型检查。
- 必要时改进 harness。如果修复需要隐藏知识，添加小文档、测试、日志字段或技能更新，让下一个代理能直接看到它。
运行桌面应用
在 packages/desktop 中使用桌面专用命令：
cd packages/desktop
bun run electron:dev
bun run electron:dev:terminal
bun run electron:dev:logs
当 bug 涉及进程输出、启动或关闭时使用 electron:dev:terminal。当应用已在运行且需要实时日志跟踪时使用 electron:dev:logs。
Chrome DevTools MCP
如果 DevTools 工具未加载，先搜索 chrome-devtools 工具。然后：
- 调用 mcp__chrome_devtools.list_pages。
- 用 mcp__chrome_devtools.select_page 选择相关页面。
- 用 mcp__chrome_devtools.take_snapshot 捕获无障碍快照。
- 用 mcp__chrome_devtools.list_console_messages 检查运行时失败，然后用 mcp__chrome_devtools.get_console_message 查看重要条目。
- 当涉及网络状态时，用 mcp__chrome_devtools.get_network_request 检查选定的网络请求。
- 对于内存问题，用 mcp__chrome_devtools.take_heapsnapshot 保存堆快照，并保存在 .qwen/ 或 /tmp 下，不要放在源码目录中。
每次改变 UI 的操作后都要重新获取快照。不要依赖过期的元素 id 或旧的 console 状态。
聚焦验证
选择覆盖所触及表面的最窄检查：
cd packages/desktop && bun run typecheck:electron
cd packages/desktop && bun run typecheck:all
cd packages/desktop && bun run validate:dev
cd packages/desktop/apps/electron && bun run lint
cd packages/desktop/packages/shared && bun test path/to/file.test.ts
对于根 CLI/core 改动，改用 AGENTS.md 中的根仓库命令。对于仅桌面改动，优先使用桌面包命令。
面向代理可读的改动
优先选择未来代理可以检查和验证的改动：
- 在失败边界附近添加结构化日志字段，而不是含糊的消息。
- 当 DevTools 快照难以解读时，添加无障碍名称或稳定的 UI 能力。
- 把文档保持为带深层来源链接的地图。不要创建庞大的手册。
- 把重复的手动调试步骤转化为文档、测试或结构化日志。
- 在 .qwen/investigations/ 中记录非平凡的调查笔记。
只有当缺失的输入无法在本地发现，且合理假设会有改变错误行为的风险时，才停下来询问用户。