OpenWork 社区支持指南：从 SUPPORT.md 到 Settings → Debug 的调试信息采集与高质量 Issue 上报

OpenWork 社区支持指南：从 SUPPORT.md 到 Settings → Debug 的调试信息采集与高质量 Issue 上报

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork

OpenWork（基于 opencode 构建的 Claude Cowork 开源替代品）在仓库根目录维护了一份 SUPPORT.md，规定了求助渠道、Issue 提交规范、调试信息采集与维护者分流机制。本文以该文档为主体骨架，结合仓库内实际的 Issue 模板（bug.yml、feature.yml）、安全策略（SECURITY.md）以及 Settings → Debug 页面的源码实现，讲解如何在遇到问题时快速、准确、可复现地获得官方支持。读完本文，你将掌握：OpenWork 各类问题的正确求助渠道与模板选择、提交 Issue 前必须准备的上下文（版本、OS、复现步骤、调试产物），以及如何从桌面端 Debug 面板导出"运行时 debug 报告 + 开发者日志"这两份排查利器。

选择合适的求助渠道

SUPPORT.md 的核心建议是"使用正确的渠道以获得更快的帮助"（Use the right channel to get faster help）。不同性质的问题走不同的通道，避免把安全漏洞、功能建议混入普通问答：

从 SECURITY.md 可以看到安全报告的完整约定：请将漏洞细节通过邮件发送至ben@openworklabs.com，邮件主题使用[OpenWork security] <简短摘要>前缀，并附带问题描述、复现步骤或 PoC、影响评估以及（如已知的）修复建议。官方承诺 3 个工作日内确认收到、7 个工作日内给出初步分流（triage）状态，并尽快分享修复或缓解指引；在修复或缓解方案可用且维护者确认公开时机之前，请保持细节私密。

提交 Issue 前：自查清单

SUPPORT.md 要求开 Issue 前完成以下准备，这也是维护者能高效处理你问题的前提：

1. 搜索已有 Issue，避免重复（Search existing issues to avoid duplicates）。
2. 包含精确的 OpenWork / OpenCode 版本、操作系统与复现步骤（Include exact OpenWork/OpenCode versions, OS, and reproduction steps）。
3. 针对桌面端、worker 或会话类 Bug：打开Settings -> Debug，同时附带两类产物——运行时 debug 报告（runtime debug report）与开发者日志导出（developer log export）。
4. 截图：当截图有助于说明流程或失败状态时附上截图（Add screenshots when they help explain the flow or failure state）。

其中"版本 + OS"字段在 Bug 模板中有明确占位示例：OpenWork version: [e.g. 0.1.166]、OS: [e.g. macOS Tahoe 26.2]，并提示可从Settings > General查看版本号；复现步骤要求用"最小化步骤"（Minimal Steps to reproduce）逐条列出（1. Go to '...' → 2. Click on '....' → ... → See error）。

Bug 模板字段速览

bug.yml 定义的必填与选填字段如下：

• Summary（必填）：什么问题 / 哪里不对。
• To Reproduce（必填）：最小复现步骤。
• Expected behavior（必填）：期望发生什么。
• Actual behavior（必填）：实际发生了什么。
• Screenshots（选填）：有助于解释问题的截图或视频。
• OW version & Desktop info（选填）：OS 与 OpenWork 版本。
• Additional context（选填）：其他背景信息。

Feature 模板的独特要求

feature.yml 与常规功能请求模板不同，额外要求贡献者思考：

• OpenCode primitive alignment：是否存在已覆盖该能力的 OpenCode 原语或 API（如session.*、permission.*、skills/plugins、mcp）？若没有，为什么仍需要一层薄薄的 OpenWork 层？
• Alignment with VISION/PRINCIPLES/PRODUCT：该功能如何与VISION.md、PRINCIPLES.md、PRODUCT.md对齐。
• Testability：如何测试（手动步骤、工具、截图，示例为pnpm dev + chrome mcp + screenshots）。
• Ready to build it yourself：是否愿意自行实现（Yes/No）。
• Primary user(s)：目标用户（Bob：IT/高级用户；Susan：非技术用户；其他团队角色）。

Settings → Debug：运行时调试信息的采集实现

SUPPORT.md 反复强调的"Settings -> Debug"并非纸面建议，它对应桌面端真实的开发者调试页面。该页面在 debug-view.tsx 中渲染，状态与命令逻辑集中在 debug-view-model.ts，仅在**开发者模式（developerMode）**开启时可见（if (!props.developerMode) return null;）。页面上与你上报 Bug 直接相关的核心能力如下。

运行时 debug 报告（Runtime debug report）

页面顶部是 "Runtime debug report" 区块，提供一键复制（Copy JSON）与导出（Export）。从 debug-view-model.ts 的runtimeDebugReport构建逻辑可见，导出的 JSON 快照包含：

• collectedAt：采集时间（ISO 8601）。
• app：桌面应用构建信息（版本、git commit SHA）。
• engine：opencode 引擎的baseUrl、runtime、pid、hostname、port、opencodeBinPath及来源、最近 stdout/stderr。
• openworkServer：hostInfo、diagnostics（版本、uptime、readOnly、approval 模式与超时、工作区数量、config 路径、token 来源）、capabilities（skills/plugins/mcp/commands/config 的读写能力、浏览器与文件工具提供方、sandbox 后端）、settings、status、url。
• runtimeWorkspaceId、selectedWorkspaceRoot、bootstrap.prepared（agent-first 安装的 org 与首个 skill 摘要）。

导出的文件名形如openwork-runtime-<timestamp>.json（见onExportRuntimeDebugReport）。这些字段覆盖了 SUPPORT.md 要求的"精确版本"信息——应用版本、OpenCode 版本、OpenWork server 版本在同一份报告中一次集齐。

服务状态卡片与日志

Debug 页面以两张 ServiceCard 展示两个核心服务的运行状态（见 debug-view.tsx 中的 Services 区块）：

• OpenWork server：Base URL、托管 opencode 二进制路径与来源、服务端日志文件路径、Connect URL、LAN URL、mDNS URL、PID、远程访问开关。
• OpenCode engine sidecar：Base URL、runtime、opencode 二进制路径与来源、PID、hostname、port。

每张卡片都提供Restart（重启服务）、Copy logs、Export logs按钮，并内置可展开的last stdout / last stderr原始输出。导出文件分别命名为openwork-server-<timestamp>.log与openwork-opencode-<timestamp>.log。对于会话异常、worker 掉线等场景，这两份服务日志与运行时报告组合，基本可以还原故障现场的完整链路。

开发者日志流（Developer log stream）

Debug 页面底部的 "Developer log stream" 区块（标题文案见 en.ts 中settings.developer_log_title："App, workspace, session, and perf events captured while Developer Mode is on"）对应的是 debug-logger.ts 实现的开发期可观测性客户端。该模块会：

• 拦截浏览器console.log/info/warn/error/debug，并记录uncaught全局错误与unhandledrejection未处理 Promise 拒绝；
• 包装window.fetch，记录每次网络请求的方法、URL、状态码与耗时，便于定位卡死前的挂起请求；
• 以 1 秒间隔的心跳检测主线程卡顿：心跳间隔超过3 秒记录hang（真实 JS 线程停滞）事件，超过10 秒则降级记录为meta级"webview 被后台节流/恢复"事件（用于区分 macOS App Nap 导致的假卡死）；
• 将事件批量 POST 到 openwork-server 的/dev/logsink（带 500ms 批量合并与 200 条队列上限），并同步保留一份到window.__openwork.events()供操作者本地查阅；生产构建中默认全部为 no-op，除非显式设置localStorage.openwork.debug.enableLoggerInProd = "1"。

开发者日志的复制与导出对应openwork-developer-<timestamp>.log，且页面保留最近500 条记录（pushDeveloperLog中的截断逻辑）。上报会话类 Bug 时，这段日志可以精确还原"卡死 / 异常前最后发生了什么"。

维护者分流（Maintainer triage）

SUPPORT.md 声明维护者会依据TRIAGE.md中的评分细则（rubric）对 Issue 打标签并路由处理。需要说明的是：当前仓库根目录下并未发现TRIAGE.md实体文件（仅在 SUPPORT.md 与 translated_readmes/README_JA.md 中被引用），因此从仓库证据看，该文件可能作为维护者内部文档或暂未随仓库公开，普通用户无需直接接触它——你只需保证 Issue 信息完整、属于正确类别，分流自然会更快。

小结：一份"高通过率"Issue 的构成

结合 SUPPORT.md 与仓库实现，一份能被高效处理的 OpenWork Bug 报告应包含：

1. 在 .github/ISSUE_TEMPLATE/bug.yml 模板中逐字段填写：Summary、最小复现步骤、Expected / Actual、截图；
2. 明确 OpenWork / OpenCode 版本与 OS（可从Settings > General查看）；
3. 桌面端、worker、会话类问题，务必先进入Settings -> Debug，导出 runtime debug 报告 JSON并导出开发者日志（.log），随 Issue 一并附上；
4. 若涉及安全漏洞，改走 SECURITY.md 的私密邮件通道，绝不在公开 Issue 中披露。

这套"先自查、再取证、后提交"的流程，既能避免重复 Issue 与无效往返，也能让维护者基于运行时报告与开发者日志快速定位问题根因——这正是 SUPPORT.md 想要传达的支持效率哲学。

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork