菜单
Known System Bridge build and runtime failures and their fixes, plus per-OS token/log/settings/data file locations. Use when a system-bridge build fails, the web-client embed is stale, ports conflict, token auth fails, cross-compilation breaks, or you need the on-disk data/log paths.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | troubleshooting |
| description | Known System Bridge build and runtime failures and their fixes, plus per-OS token/log/settings/data file locations. Use when a system-bridge build fails, the web-client embed is stale, ports conflict, token auth fails, cross-compilation breaks, or you need the on-disk data/log paths. |
Missing web-client/dist/index.html:
mise run clean:web-client
mise run build:web-client
Go embed stale after web-client changes: the //go:embed directive bundles files at compile time, so rebuild the binary:
mise run build:all # rebuilds web client AND Go binary
Module / dependency issues:
go clean -modcache
go mod download
go mod verify
go mod tidy
TypeScript errors after a dependency update:
cd web-client
rm -rf node_modules bun.lock
bun install
bun run build
Port in use (default 9170):
lsof -i :9170 # Linux/macOS
netstat -ano | findstr :9170 # Windows
export SYSTEM_BRIDGE_PORT=9171
Token / auth failures: regenerate with system-bridge client token. Token path is under the per-OS data dir (see below).
Cross-compilation:
GOOS=linux GOARCH=amd64 go build -o system-bridge-linux
GOOS=windows GOARCH=amd64 go build -o system-bridge.exe
Some modules may not cross-build due to OS-specific dependencies.
libayatana-appindicator; some modules need root.mise run processes:list / mise run processes:stop, and mise run build:console / mise run run:console for terminal logs.App data (settings, token):
Linux: ~/.local/share/system-bridge/v5/
Windows: %LOCALAPPDATA%\system-bridge\v5\
macOS: ~/Library/Application Support/system-bridge/v5/
Token: <app data>/token
Logs:
Linux: ~/.local/state/system-bridge/YYYY-MM-DD.log
Windows: %LOCALAPPDATA%\system-bridge\logs\YYYY-MM-DD.log
macOS: ~/Library/Logs/system-bridge/YYYY-MM-DD.log
Legacy system-bridge.log files in the v5 app-data dir are migrated on next startup; daily logs older than 7 days are removed on startup.
System Bridge Go backend conventions - error wrapping, graceful degradation for data modules, nil-pointer safety, context-aware Module.Update, structured slog logging, and errcheck-clean deferred cleanup. Use when writing or reviewing Go code in the system-bridge backend (data modules, HTTP/WebSocket APIs, CLI, discovery).
How to test System Bridge - Go table-driven tests and commands, web-client quality checks (lint/typecheck/format, no unit tests), the Chrome DevTools MCP interactive test loop for UI and WebSocket, the generate:schemas verification cycle, and running GitHub workflows locally with act. Use when writing or running system-bridge tests, verifying Go type/schema changes, or interactively testing the web client.
Add or restructure a page in the System Bridge Astro + Starlight docs site under docs/ - create the content file, set frontmatter, and wire the sidebar. Use when adding, moving, or restructuring documentation pages in docs/src/content/docs/.
Update the System Bridge marketing landing page in the Astro + Starlight docs site. Use when editing the landing page (docs/src/content/docs/index.mdx), its LandingCard/CardGrid components, or the landing styles.