Skip to content

Commit cf9c78f

Browse files
newbe36524hagicode-ai
newbe36524
and
hagicode-ai
committed
docs(faq): add FAQ section with Steam Linux startup guide
Add FAQ section with bilingual content including common questions and Steam Linux startup troubleshooting guide. Co-Authored-By: Hagicode <noreply@hagicode.com> Signed-off-by: newbe36524 <newbe36524@qq.com>
1 parent c2b5215 commit cf9c78f

4 files changed

Lines changed: 236 additions & 0 deletions

File tree

‎src/content/docs/en/faq/index.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: FAQ
3+
description: Review common HagiCode runtime notes, startup caveats, and future troubleshooting entries in one place.
4+
sidebar:
5+
order: 1
6+
---
7+
8+
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
9+
10+
This page collects common questions and runtime guidance for HagiCode.
11+
12+
The first FAQ entry explains the Steam for Linux startup compatibility path and why the default launch currently disables Electron's sandbox layer.
13+
14+
## Current FAQ Entries
15+
16+
<CardGrid>
17+
<LinkCard
18+
title="Steam Linux Startup Notes"
19+
href="/en/faq/steam-linux-startup"
20+
description="Understand why the default Steam launch uses no-sandbox compatibility flags, what security trade-off that creates, and how to launch hagicode-desktop directly to keep Electron's default sandbox."
21+
/>
22+
</CardGrid>
23+
24+
## What This Section Covers
25+
26+
The FAQ section is the place for:
27+
28+
- startup and runtime caveats
29+
- compatibility notes tied to platforms, distribution channels, or packaging
30+
- troubleshooting topics that deserve a stable standalone explanation page
31+
32+
If you are troubleshooting Steam for Linux startup behavior right now, open [Steam Linux Startup Notes](/en/faq/steam-linux-startup).

‎src/content/docs/en/faq/steam-linux-startup.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: Steam Linux Startup Notes
3+
description: Explains why the default Steam for Linux launch disables Electron sandboxing, the security trade-off involved, and how to launch hagicode-desktop directly to preserve the default sandbox.
4+
sidebar:
5+
order: 10
6+
---
7+
8+
If you start HagiCode Desktop from Steam for Linux, the default launch path currently prioritizes startup compatibility over preserving Electron's default sandbox protection.
9+
10+
This is not presented as the ideal long-term technical fix. It is the current compatibility fallback for the unresolved conflict between the Steam sandbox and the Electron sandbox during startup.
11+
12+
## Start with the short version
13+
14+
Think of the current behavior as two startup choices:
15+
16+
1. **Default Steam launch**: compatibility first, launches with `--disable-setuid-sandbox -no-sandbox`, and avoids the known startup conflict more reliably, but does not keep Electron's default sandbox.
17+
2. **Manual direct launch of `hagicode-desktop`**: requires you to enter the actual install directory and start the desktop binary yourself, which avoids the Steam launcher flags and preserves Electron's default sandbox.
18+
19+
:::caution[The default Steam path is not risk-free]
20+
`--disable-setuid-sandbox -no-sandbox` is the current compatibility path, but it also removes one of Electron's default runtime protection layers.
21+
:::
22+
23+
## Why the default Steam launch disables Electron sandboxing
24+
25+
On Linux, Steam introduces its own sandbox layer around the application environment. When HagiCode Desktop starts as an Electron application inside that environment, keeping Electron sandboxing enabled in the default way can currently lead to a sandbox conflict and startup crashes.
26+
27+
That is why the current default Steam launch path appends `--disable-setuid-sandbox -no-sandbox`. The goal is straightforward:
28+
29+
- keep the app launchable inside Steam
30+
- avoid the immediate startup crash path
31+
- use a compatibility default while a cleaner technical resolution is still unavailable
32+
33+
:::note[Current status]
34+
The team does not yet have a clearer technical fix that keeps Electron's default sandbox enabled inside the Steam sandbox environment while still avoiding the current startup failures.
35+
:::
36+
37+
## Startup choice A: use the default Steam launch
38+
39+
If your priority is "open the app from Steam and get in reliably," stay with the default Steam startup path.
40+
41+
Its characteristics are:
42+
43+
- it matches the current packaged default behavior
44+
- it does not require you to inspect the install directory
45+
- it automatically uses the compatibility flags `--disable-setuid-sandbox -no-sandbox`
46+
- the trade-off is that Electron's default sandbox is not preserved
47+
48+
This path fits users who:
49+
50+
- want the standard Steam launch experience
51+
- value startup reliability first
52+
- do not want to manage a manual launch command
53+
54+
## Startup choice B: launch `hagicode-desktop` directly
55+
56+
If your priority is preserving Electron's default sandbox behavior, do not use the default Steam launcher path for that startup. Instead, go to the installed HagiCode Desktop directory and run the `hagicode-desktop` binary directly.
57+
58+
Use this general process:
59+
60+
1. Locate the actual HagiCode Desktop install directory inside your Steam library
61+
2. Enter the directory that contains the `hagicode-desktop` binary
62+
3. Run `hagicode-desktop` directly
63+
4. Avoid starting that session through Steam's default launch button
64+
65+
:::tip[Why this preserves the default Electron sandbox]
66+
When you launch `hagicode-desktop` directly, you avoid the default Steam startup path and its compatibility flags, so the app starts in Electron's default mode instead of inheriting `--disable-setuid-sandbox -no-sandbox`.
67+
:::
68+
69+
:::note[This guidance stays path-agnostic on purpose]
70+
There is no single install path that is correct for every Linux distribution, Steam library location, or custom user setup. The stable instruction is to find your own install directory first and launch `hagicode-desktop` from there.
71+
:::
72+
73+
## How to choose
74+
75+
Use this rule of thumb:
76+
77+
- if you want the most compatible "launch from Steam" path, choose **Default Steam launch**
78+
- if you want to preserve Electron's default sandbox, choose **Manual direct launch of `hagicode-desktop`**
79+
80+
This is a trade-off between the compatibility-first default and the sandbox-preserving manual path, not a claim that one choice is universally correct for every user.
81+
82+
## Why this page exists as a stable help target
83+
84+
If HagiCode Desktop later adds a startup help entry such as "how to enable sandbox," this FAQ page is intended to remain the canonical explanation target.
85+
86+
For this change, the deliverable is documentation only: explain the current behavior, state the trade-off, and document the manual alternative without changing runtime behavior.

‎src/content/docs/faq/index.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: 常见问题
3+
description: 集中查看 HagiCode 使用过程中的常见运行说明、启动注意事项与后续补充条目。
4+
sidebar:
5+
order: 1
6+
---
7+
8+
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
9+
10+
本页汇总 HagiCode 文档中的常见问题与运行说明。
11+
12+
当前第一条 FAQ 重点说明 Steam for Linux 环境下的启动兼容策略，以及为什么默认启动会关闭 Electron 的沙箱保护层。
13+
14+
## 当前 FAQ 条目
15+
16+
<CardGrid>
17+
<LinkCard
18+
title="Steam Linux 启动注意事项"
19+
href="/faq/steam-linux-startup"
20+
description="了解默认 Steam 启动为何使用 no-sandbox 兼容参数、这带来的安全权衡，以及如何手动直启 hagicode-desktop 保留 Electron 默认沙箱。"
21+
/>
22+
</CardGrid>
23+
24+
## 这个分区会放什么
25+
26+
FAQ 分区用于集中收纳以下内容：
27+
28+
- 启动和运行时的特殊说明
29+
- 与平台、发行渠道或打包方式相关的兼容性提示
30+
- 适合做成独立说明页的常见排障入口
31+
32+
如果你当前遇到的是 Steam for Linux 下的启动问题，请直接阅读 [Steam Linux 启动注意事项](/faq/steam-linux-startup)。

‎src/content/docs/faq/steam-linux-startup.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: Steam Linux 启动注意事项
3+
description: 说明 Steam for Linux 默认启动为何关闭 Electron 沙箱、这带来的安全权衡，以及如何手动直启 hagicode-desktop 保留默认沙箱。
4+
sidebar:
5+
order: 10
6+
---
7+
8+
如果你通过 Steam for Linux 启动 HagiCode Desktop，默认启动路径会优先保证应用能稳定启动，而不是优先保留 Electron 的默认沙箱保护。
9+
10+
这不是更理想的长期技术方案，而是当前为了避开 Steam 沙箱与 Electron 沙箱冲突所采用的兼容性默认值。
11+
12+
## 先看结论
13+
14+
目前可以把启动方式理解成两个选项：
15+
16+
1. **Steam 默认启动**：兼容性优先，默认附带 `--disable-setuid-sandbox -no-sandbox`，更容易避免启动崩溃，但不会保留 Electron 默认沙箱。
17+
2. **手动直启 `hagicode-desktop`**：需要你进入实际安装目录自行启动二进制文件，不走 Steam 默认启动参数，因此可以保留 Electron 默认沙箱。
18+
19+
:::caution[默认 Steam 启动并非“无风险”]
20+
`--disable-setuid-sandbox -no-sandbox` 的作用是绕开当前 Steam for Linux 环境中的启动冲突，但它也意味着 Electron 少了一层默认运行时保护。
21+
:::
22+
23+
## 为什么 Steam 默认启动会关闭 Electron 沙箱
24+
25+
在 Steam for Linux 环境里，Steam 本身会带来一层自己的沙箱约束。HagiCode Desktop 作为 Electron 应用启动时，如果继续按默认方式启用 Electron 沙箱，当前实现下可能出现沙箱冲突并导致启动失败或直接崩溃。
26+
27+
因此，当前默认 Steam 启动路径会附带 `--disable-setuid-sandbox -no-sandbox`。这样做的目标很明确：
28+
29+
- 优先让应用在 Steam 环境中成功启动
30+
- 避免用户一启动就遇到崩溃
31+
- 以兼容性默认值替代尚未解决的更理想技术方案
32+
33+
:::note[当前状态]
34+
团队目前还没有一个更清晰、可稳定交付的技术修复方案，能够在 Steam 沙箱环境内同时保留 Electron 默认沙箱并避免启动崩溃。
35+
:::
36+
37+
## 启动选项 A：使用 Steam 默认启动
38+
39+
如果你的首要目标是“直接从 Steam 点开就能正常进入应用”，那就继续使用 Steam 默认启动方式。
40+
41+
它的特点是：
42+
43+
- 最贴近当前发布包的默认使用路径
44+
- 不需要额外查找安装目录
45+
- 会自动沿用当前兼容性参数 `--disable-setuid-sandbox -no-sandbox`
46+
- 代价是 Electron 默认沙箱不会保留
47+
48+
这种方式适合：
49+
50+
- 想保持 Steam 内一键启动体验的用户
51+
- 更在意先稳定进入应用的用户
52+
- 暂时不准备手动管理启动命令的用户
53+
54+
## 启动选项 B：手动直启 `hagicode-desktop`
55+
56+
如果你更在意保留 Electron 默认沙箱，可以不要通过 Steam 的默认启动入口，而是直接启动安装目录中的 `hagicode-desktop` 可执行文件。
57+
58+
操作原则如下：
59+
60+
1. 找到 Steam 库中 HagiCode Desktop 的实际安装目录
61+
2. 进入包含 `hagicode-desktop` 二进制文件的目录
62+
3. 直接运行 `hagicode-desktop`
63+
4. 不通过 Steam 默认“启动游戏/应用”按钮触发这次启动
64+
65+
:::tip[为什么这种方式能保留 Electron 默认沙箱]
66+
直接启动 `hagicode-desktop` 时，你绕开的是 Steam 默认启动路径附带的兼容性参数，因此应用会回到 Electron 的默认启动模式，而不是沿用 `--disable-setuid-sandbox -no-sandbox`。
67+
:::
68+
69+
:::note[刻意保持路径无关]
70+
这里不提供单一硬编码安装路径，是因为不同 Linux 发行版、不同 Steam 库位置、以及不同用户的自定义库目录都可能不同。对多数用户更稳定的做法，是先确认自己的 Steam 安装目录，再在该目录中直接运行 `hagicode-desktop`。
71+
:::
72+
73+
## 怎么选
74+
75+
可以用这个判断方式：
76+
77+
- 如果你优先要“从 Steam 里稳定打开”，选 **Steam 默认启动**
78+
- 如果你优先要“保留 Electron 默认沙箱”，选 **手动直启 `hagicode-desktop`**
79+
80+
本质上，这是“兼容性默认值”和“保留默认沙箱”的取舍，不是哪个方案对所有人都绝对更好。
81+
82+
## 这个说明页未来会继续复用
83+
84+
后续如果 HagiCode Desktop 增加了“如何启用沙箱”之类的启动帮助入口，这一页会作为稳定的说明目标继续复用。
85+
86+
这也意味着：当前这篇 FAQ 的职责是解释现状、说明权衡、给出手动替代路径，而不是在这次变更里修改应用运行逻辑。

0 commit comments

Comments
 (0)