• 人工智能
• AI Agent
• AI 应用
• 前端
• 后端
• 即时通讯
• 交互助手
• 工具调用

本篇指南围绕 holaOS 开源仓库的 SUPPORT.md 展开，厘清 OSS 代码支持与托管 Holaboss 服务支持的边界，系统讲解如何提交可被快速定位的高质量 Issue、如何收集本地运行日志，以及哪些能力在完全不登录的情况下即可使用、哪些能力依赖 Holaboss 后端。读完你既能准确判断一个问题该走哪条支持通道，也能掌握在本地复现、取证与排查的完整方法。

目录

• 两种支持通道：OSS 代码支持与托管服务支持
• 高质量 Issue 的四要素与日志取证
• 无需登录即可使用的本地能力
• 依赖 Holaboss 后端的能力与配置边界
• 安全漏洞的私密上报通道
• 本地排查的常用命令路径
• 延伸阅读

两种支持通道：OSS 代码支持与托管服务支持

SUPPORT.md 开篇即明确了 holaOS 的支持模型：本仓库是开源代码库（OSS codebase），而托管的 Holaboss 账户、计费与服务运维支持与 OSS 代码支持是相互独立的两个通道。

• OSS 支持：面向仓库代码本身，通过 GitHub Issues 与 Pull Requests 进行社区协作。凡是涉及安装、构建、运行、运行时行为的问题，都走这条通道。
• 托管服务支持：面向 Holaboss 托管账户下的登录、计费、服务可用性等运营性问题，与仓库代码问题分开处理，不应混入 OSS Issue。

这种区分并非简单的流程划分，它与 holaOS "local-first" 的产品定位直接对应：开源版本的核心工作流（桌面开发、运行时打包、工作区/运行时流程）完全落在用户自己的机器上（见 README.md 的 Local-first 说明），因此绝大多数代码层面的问题都能在本地独立复现，无需后端介入。

高质量 Issue 的四要素与日志取证

SUPPORT.md 明确指出，一份好的 Issue 报告应包含以下四类信息：

如何高效收集运行时日志

桌面运行时把日志写入 Electron userData 目录下深层、按 profile 转义命名（如_Users_you_.holaboss-desktop）的runtime.log，人工定位并不方便。仓库为此提供了专用脚本 scripts/runtime-logs.sh，它会自动发现最新写入的runtime.log并持续 tail：

# 跟踪全部日志 npm run runtime:logs # 只过滤包含 composio 的行（大小写不敏感） npm run runtime:logs -- composio # 用正则同时过滤多个错误模式 npm run runtime:logs -- 'execute.failure|cfRay' # 显式指定日志路径 HOLABOSS_RUNTIME_LOG=/path/to/runtime.log npm run runtime:logs

脚本内部（scripts/runtime-logs.sh）在检测到jq时会自动把 pino 的 JSON 行格式化为人可读输出：将 level 数字映射为TRC/DBG/INF/WRN/ERR/FTL，并提取event/msg、toolSlug、httpStatus、cfRay、originServer等关键字段，过滤时使用grep -iE匹配后仍保持 pretty-print。这意味着提交 Issue 时可以直接附上格式化后的日志片段，而不是原始 JSON 长行。

从日志判断本地与后端边界

日志中是否出现cfRay、originServer字段，是判断一次请求是否真正打到 Holaboss 云端网关的直观信号（见脚本对这两个字段的专门提取逻辑）。httpStatus则可用于区分本地运行时错误与后端接口错误，配合 Issue 第四要素"该流程是否连接了 Holaboss 服务"，能帮助维护者快速归类问题。

无需登录即可使用的本地能力

SUPPORT.md 列出的免登录能力，正是 holaOS 本地优先架构的体现，仓库源码可以逐一印证：

本地桌面开发

即npm run desktop:dev驱动的完整 Electron 开发环境。根目录 package.json 中的对应脚本为：

• desktop:install：bun install，安装桌面端依赖；
• desktop:typecheck：tsc --noEmit非交互验证；
• desktop:dev：bun --elide-lines=0 --filter=holaboss-local run dev，其predev钩子（见 apps/desktop/package.json）会自动执行环境校验、原生模块重建、运行时 bundle 检查等一串步骤，无需人工准备。

安装引导的完整流程记录在 INSTALL.md：从npm run desktop:install、cp apps/desktop/.env.example apps/desktop/.env，到desktop:prepare-runtime:local、desktop:typecheck、desktop:dev，全部不依赖任何云端账户。

本地运行时打包

对应npm run desktop:prepare-runtime:local，它把本地源码打包成运行时 bundle 并暂存到apps/desktop/out/runtime-<platform>。实现见 apps/desktop/scripts/prepare-runtime-local.mjs：

• 通过resolveRuntimePlatform()解析当前宿主平台；
• 自动推断运行时仓库根目录（支持HOLABOSS_OSS_ROOT/HOLABOSS_RUNTIME_REPO_ROOT环境变量覆盖）；
• 调用runtime/deploy下的平台打包脚本，再交由 apps/desktop/scripts/stage-runtime-bundle.mjs 完成暂存与校验。

暂存器支持四种 bundle 来源（本地目录、本地 tarball、远程 URL、默认临时目录），并利用.cache-key做增量复用（tryReuseStagedBundle），避免重复执行约 800MB 的目录拷贝；可用HOLABOSS_RUNTIME_FORCE_STAGE=1强制完整重暂存。校验环节会检查package-metadata.json与各平台必需的可执行文件路径组，缺失即抛错——这正是"本地 runtime 打包可用"的底层保障。

本地工作区 / 运行时流程

工作区文件、内存数据、嵌入向量与会话历史都存放在用户本机磁盘（README 明确 "There is no copy of your work on our servers"），因此工作区创建、切换、运行时启动等流程均可离线进行。仓库还提供隔离启动入口便于无 GUI 或隔离环境下验证：

npm run runtime:start:isolated # 以隔离方式启动运行时 npm run desktop:dev:isolated # 隔离桌面开发环境

依赖 Holaboss 后端的能力与配置边界

SUPPORT.md 同时给出三类可能需要后端接入的能力：登录流程、托管认证支撑的产品功能、以及任何连接后端的 Holaboss 服务。这些依赖在配置层有清晰体现——apps/desktop/.env.example 中的默认值直接指向 Holaboss 云端：

HOLABOSS_AUTH_BASE_URL=https://api.holaboss.ai HOLABOSS_AUTH_SIGN_IN_URL=https://www.holaboss.ai/signin HOLABOSS_BACKEND_BASE_URL=https://api.holaboss.ai HOLABOSS_DESKTOP_CONTROL_PLANE_BASE_URL=https://api.holaboss.ai/gateway/sandbox HOLABOSS_WEB_APP_BASE_URL=https://www.holaos.ai

从这份默认配置可以推断出后端依赖的主要形态：

• 登录与认证：HOLABOSS_AUTH_BASE_URL/HOLABOSS_AUTH_SIGN_IN_URL指向 Holaboss 的认证服务与登录页，涉及 sign-in 的流程必然需要网络与后端；
• 控制平面：HOLABOSS_DESKTOP_CONTROL_PLANE_BASE_URL指向api.holaboss.ai/gateway/sandbox，托管认证支撑的产品功能（如云端账户态功能）经由该网关；
• Web HolaApp 面：HOLABOSS_WEB_APP_BASE_URL决定 Web HolaApp 页面从哪个源加载（生产holaos.ai，示例注释还给出了 staging 源），Web HolaApp 的 MCP 服务则默认复用HOLABOSS_BACKEND_BASE_URL，可单独用HOLABOSS_WEB_HOLAAPP_MCP_BASE_URL覆盖。

需要注意，.env中的后端地址只决定"何时连接 Holaboss 服务"，并不影响本地桌面开发、本地打包与本地运行时流程的可用性——这正是"免登录能力"与"后端依赖能力"的分界线。提交 Issue 时若流程涉及上述地址的请求失败，应明确标注"连接到 Holaboss 服务"这一状态。

安全漏洞的私密上报通道

SUPPORT.md 虽未展开，但安全相关的支持边界记录在配套的 SECURITY.md 中，与 OSS 支持形成互补：安全漏洞不要提交公开 Issue，应私密发送至admin@holaboss.ai，并在报告中包含受影响 commit 或 release、复现步骤、影响评估及建议的缓解措施。仓库将其视为安全敏感的问题类别包括：凭证/令牌/密钥泄露、远程代码执行、沙箱逃逸或提权、认证绕过，以及会暴露本地运行时或用户数据的默认配置。项目要求给出合理的修复验证时间后再公开披露。

本地排查的常用命令路径

结合 SUPPORT.md 的 Issue 四要素，以下是提交前建议走完的本地取证链路（均在仓库根目录执行）：

# 1. 确认环境满足最低要求（Node >= 24，见根 package.json engines 与 .nvmrc） git --version && node --version && npm --version # 2. 安装依赖（与仓库保持一致，使用根 wrapper） npm run desktop:install # 3. 创建本地环境文件（保持与模板一致，仅按需改动） cp apps/desktop/.env.example apps/desktop/.env # 4. 暂存本地运行时 bundle（改的是本地源码时用这个） npm run desktop:prepare-runtime:local # 或拉取最新发布 bundle（验证桌面端与已知 release 产物时用这个） npm run desktop:prepare-runtime # 5. 非交互验证 npm run desktop:typecheck # 6. 启动开发环境（predev 钩子会自动校验环境、重建原生模块、确保 bundle 存在） npm run desktop:dev # 7. 复现问题后采集日志 npm run runtime:logs -- '<错误关键词正则>'

补充说明：

• npm run desktop:dev是交互式长驻进程，在无 GUI/无头环境可能无法打开 Electron 窗口；此时应止步于第 5 步的 typecheck 验证并在报告中注明"安装成功但未尝试交互式启动"（INSTALL.md 对此有明确提示）；
• 打包类问题可按平台隔离验证：desktop:prepare-runtime:local:macos|linux|windows、desktop:dist:mac:local、desktop:dist:win:local等脚本（见 apps/desktop/package.json）在打包前都会先走本地运行时准备，便于复现平台相关的 staging 错误；
• 仓库自带大量单元与 e2e 测试（如desktop:e2e、runtime:test），怀疑是回归问题时，可先跑相关测试套件确认是否为已知行为。

延伸阅读

• SUPPORT.md：支持边界与 Issue 提交通道（本文核心依据）；
• SECURITY.md：安全漏洞私密上报范围与流程；
• INSTALL.md：面向编码 Agent 的确定性安装 runbook；
• README.md：产品能力总览与本地优先架构说明；
• apps/desktop/.env.example：后端相关环境变量默认值；
• apps/desktop/scripts/prepare-runtime-local.mjs 与 apps/desktop/scripts/stage-runtime-bundle.mjs：本地运行时打包与暂存的实现；
• scripts/runtime-logs.sh：运行时日志自动发现、过滤与格式化。

• 人工智能
• AI Agent
• AI 应用
• 前端
• 后端
• 即时通讯
• 交互助手
• 工具调用