helix-pyinstaller-packager
Package the helix repository into PyInstaller onefile executables with the built-in skills tree embedded. Use when Codex needs to build, repair, validate, or document Windows, Linux, or macOS helix release artifacts; create platform-tagged release archives; explain PyInstaller's per-OS build requirement; or verify that packaged helix can load bundled skills.
- License 许可
- Apache-2.0
- 所属仓库
- Piagari/helix
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- helix-pyinstaller-packager
- description
- Package the helix repository into PyInstaller onefile executables with the built-in skills tree embedded. Use when Codex needs to build, repair, validate, or document Windows, Linux, or macOS helix release artifacts; create platform-tagged release archives; explain PyInstaller's per-OS build requirement; or verify that packaged helix can load bundled skills.
02 资源文件 2
- 参考文档agents/openai.yaml329 B
- 参考文档references/platform-builds.md3.0 KB
03 SKILL.md 正文
Helix PyInstaller Packager
Core Rule
PyInstaller is not a cross-compiler. Build Windows artifacts on Windows, Linux artifacts on Linux, and macOS artifacts on macOS. Do not claim that one host can produce native executables for every OS unless a separate VM/container/CI runner for each target OS is actually used.
Expected Repository Shape
Use this skill for a helix repository that has:
pyproject.tomlmanaged byuv- CLI entrypoint
helix.cli:main - source under
src/helix/ - a top-level
skills/directory that must be bundled as runtime data - a PyInstaller build script at
scripts/build-pyinstaller.py - a PyInstaller spec at
packaging/helix.spec; if it is missing, the build script can create a default one
Packaging Mode
Build onefile executables by default. The release output should expose a single executable in each platform artifact directory, for example:
dist/pyinstaller/helix-windows-x86_64/helix.exe
The built-in skills/ tree must still be included as PyInstaller data. In onefile mode, do not expect a visible _internal/skills directory in the release output. PyInstaller extracts embedded data to a temporary _MEI* directory while the process is running, and src/helix/resources.py must resolve frozen resources through sys._MEIPASS.
This mode reduces source exposure in the distributed artifact, but it is not encryption or a hard reverse-engineering boundary.
Workflow
- Inspect the repository before editing:
pyproject.tomlpackaging/helix.specsrc/helix/resources.py- current resource path usage for
skills/
- Ensure
pyinstalleris available throughuv:- If missing, add it as a dev dependency with
uv add --dev pyinstaller.
- If missing, add it as a dev dependency with
- Ensure runtime resource lookup supports both source and frozen execution:
- Source mode should resolve the repository root.
- Frozen mode should resolve PyInstaller bundle resources.
- All runtime access to bundled
skills/should flow through one resource helper.
- Ensure the spec recursively includes
skills/as data:- If
packaging/helix.specis missing, let the build script create its default spec or create an equivalent spec before building. - Include
SKILL.md,references/,scripts/,.json, and other non-cache skill files. - Exclude
__pycache__and.pyc. - Build a onefile
EXEby passinga.binariesanda.datasintoEXE; do not create aCOLLECTonedir bundle for the default release path.
- If
- Build the current OS executable with the repository build script:
uv run python scripts/build-pyinstaller.py --clean
- Validate the artifact:
- Run packaged
helix --help. - Confirm the platform artifact directory contains the onefile executable.
- Run one command that loads bundled skill resources, such as
compare-perfwith tiny temp perf files. - For agent-backed commands, use
--verboseto confirm skill staging into.codex/skills,.claude/skills, or the selected backend directory.
- Run packaged
- Report produced executable and release archive paths, validation results, and remaining environment limitations.
Build Script
Use the repository-owned scripts/build-pyinstaller.py for the normal build path. The skill does not keep a second packaging implementation; keeping one script avoids drift between manual packaging, CI packaging, and skill-guided packaging.
The script:
- detects the current OS and CPU architecture
- creates a default
packaging/helix.specwhen the requested spec is missing - invokes
uv run pyinstaller - writes platform-tagged output under
dist/pyinstaller/ - validates the expected onefile executable
- creates a release archive unless
--no-archiveis used:.zipon Windows,.tar.gzon Linux and macOS - includes the onefile executable and
README.mdin the release directory and archive
Examples:
uv run python scripts/build-pyinstaller.py --clean
uv run python scripts/build-pyinstaller.py --clean --no-archive
uv run python scripts/build-pyinstaller.py --clean --platform-tag linux-aarch64
Multi-OS Release Procedure
For a release that needs Windows, Linux, and macOS artifacts:
- Run the same script on a Windows host.
- Run the same script on a Linux host.
- Run the same script on a macOS host.
- Collect the generated release archives from
dist/pyinstaller/.
Read references/platform-builds.md when explaining this limitation to users or designing CI jobs.
Validation Notes
- A packaged CLI can be validated without NPU hardware by checking
--help, bundled skills, and pure parser/comparison commands. - Real
run-test,run-bench,verify, andoptimizevalidation requires a Python environment with the target dependencies, often includingtorch,torch_npu,triton, and Ascend/CANN runtime. - A packaged executable does not include external agent CLIs. Users still need
codex,claude,opencode,pi, or other selected backend tools available onPATH. - If generated tests or benchmarks are executed by a frozen app, ensure local execution uses an external Python interpreter, typically through
HELIX_PYTHON.
04 同仓库更多 Skills
triton-npu-repair-guide
Heuristic fixes for Ascend Triton compile/JIT/kernel errors and numerical precision mismatches when editing or converting the operator. Does not replace ascend-npu-gen-test, ascend-npu-gen-bench, or harness specs.
triton-npu-optimize
Iteratively optimize a Triton Ascend NPU operator with correctness and performance gates. Use for operator optimization tasks that need repeated correctness validation, benchmark validation, multi-round experiment tracking, reusable optimization notes, and profiler-backed performance analysis when benchmark results need deeper explanation.
triton-npu-optimize-knowledge
Generic reference-only optimize knowledge for pattern triage and evidence-backed symptom routing. This skill does not define optimize workflow or own round artifacts.
triton-npu-optimize-knowledge-v3
Generic reference-only optimize knowledge (v3 working copy) for pattern triage and evidence-backed symptom routing. This skill does not define optimize workflow or own round artifacts; prefer this tree for ongoing knowledge updates.
triton-npu-optimize-knowledge
Generic reference-only optimize knowledge for pattern triage and evidence-backed symptom routing. This skill does not define optimize workflow or own round artifacts.
triton-npu-convert-pytorch-operator
Convert one PyTorch operator into a Triton NPU-backed PyTorch operator, preserve the trailing input-helper block, and validate the converted output through standalone or differential testing.