AGENT SKILL

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

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, or opencontext.spec;
  • copy-prebuilt-backend, missing frontend/backend/main, missing dist/main/main, or backend executable copy failures;
  • window_inspector, window_capture, Quartz, macOS helper binaries, screen helper build skips, or helper dist/ outputs;
  • signing, notarization, Gatekeeper, keychain, electron-builder, frozen-lockfile failures, or build script failures.

First checks

  1. 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, and frontend/package.json.

  2. 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.

  3. 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 . --yes
    

    scripts/build_backend.sh wraps the repo backend PyInstaller build, verifies dist/main/main or dist/main/main.exe, and can optionally copy the built backend into frontend/backend/.

  4. If the task needs packaged app artifacts, read references/build-and-package.md for the exact backend, dependency, frontend copy, and Electron command sequence.

  5. If the failure involves window_inspector, window_capture, Quartz, or a non-macOS helper skip, read references/helper-binaries.md.

  6. 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 root dist/, root build/, frontend/dist/, and frontend/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-backend failures by reinstalling frontend dependencies first. Check whether the root backend executable exists.
  • On Linux or Windows, a skipped window_inspector/window_capture build 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

VectorSpaceLab
VectorSpaceLab/AREX-Skill

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.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

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.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

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.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

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.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

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.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

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).

★ 351