desktop-packaging
Build and troubleshoot MineContext desktop packaging, including the PyInstaller backend, Electron packages, frontend backend copy, and macOS helper binaries.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- desktop-packaging
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Build and troubleshoot MineContext desktop packaging, including the PyInstaller backend, Electron packages, frontend backend copy, and macOS helper binaries.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/build-and-package.md8.6 KB
- 参考文档references/helper-binaries.md4.4 KB
- 参考文档references/troubleshooting.md6.8 KB
- 脚本scripts/build_backend.sh4.5 KB
- 脚本scripts/check_packaging_env.sh7.2 KB
03 SKILL.md 正文
desktop-packaging
Use this sub-skill when a task asks to build or troubleshoot the MineContext
standalone desktop application: the PyInstaller opencontext backend
executable, copying that backend into frontend/backend/, Electron packaging
from the frontend/ package, macOS helper binaries, signing/notarization
preflight, or failures in the build scripts.
Route backend server startup, FastAPI routes, runtime configuration, and
opencontext start behavior to runtime-service
instead of diagnosing them here. This sub-skill only owns build/package
mechanics and package-time file placement.
Natural triggers
Use this sub-skill for requests that mention:
- "build MineContext app",
pnpm build:mac,pnpm build:win,pnpm build:linux, or Electron packaging; - "build backend",
build.sh,build.bat,PyInstaller, oropencontext.spec; copy-prebuilt-backend, missingfrontend/backend/main, missingdist/main/main, or backend executable copy failures;window_inspector,window_capture, Quartz, macOS helper binaries, screen helper build skips, or helperdist/outputs;- signing, notarization, Gatekeeper, keychain,
electron-builder, frozen-lockfile failures, or build script failures.
First checks
-
Confirm the agent is operating from a MineContext checkout or has a repo root path. Package scripts expect a root containing
opencontext.spec,hook-opencontext.py,build.sh, andfrontend/package.json. -
Run the bundled preflight before any mutating build:
bash path/to/desktop-packaging/scripts/check_packaging_env.sh --repo-root .scripts/check_packaging_env.sh reports Python, uv, Node, pnpm, platform, required packaging files, helper-binary paths, and backend-copy readiness without installing anything.
-
If the task is only to produce the backend executable, use the safer backend wrapper and explicitly acknowledge its mutation of build outputs:
bash path/to/desktop-packaging/scripts/build_backend.sh --repo-root . --yesscripts/build_backend.sh wraps the repo backend PyInstaller build, verifies
dist/main/mainordist/main/main.exe, and can optionally copy the built backend intofrontend/backend/. -
If the task needs packaged app artifacts, read references/build-and-package.md for the exact backend, dependency, frontend copy, and Electron command sequence.
-
If the failure involves
window_inspector,window_capture, Quartz, or a non-macOS helper skip, read references/helper-binaries.md. -
If a command failed, map the symptom in references/troubleshooting.md before reinstalling dependencies or deleting outputs.
Build ownership map
| Surface | Owned here | Key expectation |
|---|---|---|
| Backend executable | Yes | Root build.sh/build.bat invoke PyInstaller with opencontext.spec and produce dist/main/main or dist/main/main.exe. |
| Frontend backend copy | Yes | frontend/scripts/copy-prebuilt-backend.js deletes and recreates frontend/backend/ from root dist/main/ plus dist/config/. |
| Electron package | Yes | Run package scripts from frontend/, not the root package.json. macOS/Windows package scripts copy the backend first; Linux currently requires an explicit backend copy before packaging. |
| macOS helpers | Yes | window_inspector and window_capture are Quartz/PyObjC helpers copied into the macOS app as bin/window_inspector and bin/window_capture. |
| Server behavior | No | Route CLI flags, FastAPI health/API behavior, backend logs at runtime, and config semantics to runtime-service. |
Safe operating rules
- Treat
build.sh,build.bat,pnpm run build*,electron-builder, and backend copy commands as mutating. They may delete or recreate rootdist/, rootbuild/,frontend/dist/, andfrontend/backend/. - Do not run release/publish commands or signing/notarization flows by default. Packaging can be tested unsigned; signed release builds require the user's explicit credential setup and approval.
- Do not fix
copy-prebuilt-backendfailures by reinstalling frontend dependencies first. Check whether the root backend executable exists. - On Linux or Windows, a skipped
window_inspector/window_capturebuild is expected for the JavaScript helper build path because those helpers use macOS Quartz APIs. - Keep runtime API/config/document-processing questions in runtime-service; use this sub-skill only for package-time mechanics.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).