fspack 0.1.0__tar.gz

fspack-0.1.0/.copier-answers.yml

@@ -0,0 +1,21 @@
+# Changes here will be overwritten by Copier
+_commit: v0.4.6
+_src_path: https://github.com/gookeryoung/coopie
+author_email: gooker_young@qq.com
+author_name: gooker_young
+coverage_fail_under: 95
+description: 极速 Python 项目打包器。
+initial_version: 0.1.0
+license: MIT
+max_python_version: '3.14'
+min_python_version: '3.8'
+package_name: fspack
+project_name: fspack
+project_type: cli
+use_cicd: true
+use_cli: true
+use_docker: false
+use_docs: true
+use_domestic_mirrors: true
+use_tox: true
+

fspack-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra lint
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: Pyrefly check
+        run: uv run pyrefly check
+
+  test:
+    name: Test (Python 3.8 & 3.14)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra test --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest -m "not slow" --cov=fspack --cov-fail-under=95 --cov-report=term-missing

fspack-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI (OIDC)
+        run: uv publish
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG_NAME" \
+            --title "Release $TAG_NAME" \
+            --generate-notes \
+            dist/*

fspack-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# 测试与覆盖率
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# 工具缓存
+.ruff_cache/
+.pyrefly_cache/
+.mypy_cache/
+.uv-cache/
+
+# IDE
+.idea/
+*_profile.html
+
+# 环境变量与凭证（勿提交）
+.env
+.env.*
+
+# Sphinx 文档构建输出
+docs/_build/
+.trae/refs

fspack-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# prek / pre-commit 配置
+# See https://pre-commit.com for more information
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff 版本 - 与 pyproject.toml 保持同步
+    rev: v0.15.8
+    hooks:
+      # 运行 linter
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      # 运行格式化
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: fix-byte-order-marker
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer

fspack-0.1.0/.python-version

@@ -0,0 +1 @@
+3.8

fspack-0.1.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# ReadTheDocs 配置
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+# 构建配置
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.8"
+
+# Python 依赖与构建命令
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Sphinx 构建
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false

fspack-0.1.0/.trae/.ignore

@@ -0,0 +1,15 @@
+# PYTHON
+.coverage
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+__pycache__/
+
+# NODEJS
+node_modules/
+
+# IDE
+.idea
+.trae
+.vscode

fspack-0.1.0/.trae/docs/iter-01-cli-loader.md

@@ -0,0 +1,103 @@
+# iter-01 CLI 与 C Loader 垂直切片
+
+## 迭代目标
+
+交付 P1：从 pyproject.toml 解析到 `fsp b` 产出可被 `fsp r` 运行的 hello world .exe，全程在 Linux 用 mingw 交叉编译 + wine 运行验证。
+
+## 关键决策与依据
+
+### 模块结构
+```
+src/fspack/
+  __init__.py          # 版本号
+  cli.py               # fsp b/c/r 子命令分发（argparse）
+  commands/
+    __init__.py
+    build.py           # fsp b → builder.build()
+    clean.py           # fsp c → 清理 dist/
+    run.py             # fsp r → wine 运行 dist .exe
+  project.py           # pyproject.toml → ProjectInfo
+  analyzer.py          # AST import 扫描 → DependencyReport
+  mirror.py            # MirrorConfig 国内镜像
+  embed.py             # embed python 下载/解压/_pth
+  loader.py            # C loader 源码生成 + mingw 交叉编译
+  builder.py           # 流水线编排
+  config.py            # dataclass（ProjectInfo/AppType/MirrorConfig 等）
+  exceptions.py        # FspackError 层级
+```
+
+### 镜像选型
+- 华为云（已验证 HTTP 200）：`https://mirrors.huaweicloud.com/python/{ver}/python-{ver}-embed-amd64.zip`，pip 索引 `https://mirrors.huaweicloud.com/pypi/simple/`。
+- 备选阿里云、清华；默认华为云，`--mirror` 可切换。
+
+### embed python _pth
+```
+python3X.zip
+.
+Lib
+Lib\site-packages
+import site
+```
+
+### C loader 设计
+- 不依赖 Python.h（embed 包不含开发头文件），改用动态加载 `python3X.dll`，解析 `Py_Main(argc, argv)` 符号调用。
+- 配置在生成时以 `#define` 烧入：`ENTRY_FILE`、`PYTHON_HOME`（相对 exe 的 runtime 子目录）、`PYTHON_DLL`（如 `python311.dll`）。
+- 设置环境变量 PYTHONHOME/PYTHONPATH 后 `Py_Main(["loader.exe", exe_dir\ENTRY_FILE, ...用户参数])`。
+- GUI 子系统：mingw `-mwindows`；CLI：默认 console。
+- 版本无关：优先加载 `python3.dll`（稳定 ABI），回退 `python3X.dll`。
+
+### 依赖下载策略（Linux dev 拉 Windows wheel）
+- embed python.exe 是 Windows 程序，Linux dev 无法直接跑它的 pip。
+- 方案：dev python 执行 `pip download -d wheelhouse --platform win_amd64 --python-version <ver> --only-binary=:all: -i <镜像> <deps>`，再用 `zipfile` 把每个 .whl 解包到 `dist/Lib/site-packages/`。
+- 无依赖项目（hello world）跳过此步。
+
+### Python 3.8 兼容
+- `.python-version=3.8`，uv 已装 3.8.20。
+- toml：`sys.version_info>=(3,11)` 用 `tomllib`，否则 `tomli`（条件依赖 `tomli; python_version<'3.11'`）。
+- 标准库模块名：`sys.stdlib_module_names`（3.10+）不可用，3.8/3.9 用 curated frozenset 回退。
+- 注解用 `from __future__ import annotations`，可用 `list[str]` 等。
+
+### 测试策略
+- 公共 API 单测：解析、AST、镜像 URL、_pth 内容、loader C 源码字符串、wheel 解包。mock 网络（urllib）与子进程（pip/mingw）。
+- `@pytest.mark.slow`：真实 embed 下载、mingw 编译、wine 运行、端到端 hello world。
+- 门禁：`ruff check`/`ruff format --check`/`pyrefly check`/`pytest -m 'not slow' --cov≥95%`。
+
+## 改动文件清单
+
+新增：
+- src/fspack/{config,exceptions,project,analyzer,mirror,embed,loader,builder,cli}.py
+- src/fspack/commands/{__init__,build,clean,run}.py
+- tests/test_{config,project,analyzer,mirror,embed,loader,builder,cli}.py
+- tests/examples/helloworld/ 示例项目
+- .trae/req/req-01-fspack-p1.md、.trae/docs/iter-01-cli-loader.md
+
+修改：
+- src/fspack/__init__.py（保持版本）
+- src/fspack/cli.py（重写为子命令分发）
+- pyproject.toml（加 tomli 条件依赖）
+- README.md（更新快速上手）
+
+## 验证结果
+
+非 slow 门禁全过（2026-07-12）：
+
+- `uv run ruff check src tests`：All checks passed!
+- `uv run ruff format --check src tests`：27 files already formatted
+- `uv run pyrefly check`：0 errors（1 suppressed）
+- `uv run pytest -m "not slow" --cov=fspack --cov-fail-under=95`：83 passed, 1 deselected, 覆盖率 99.45%
+
+修复要点：
+- `DependencyReport.missing` 用 `re.split(r"[<>=!~;\[]", d, maxsplit=1)` 剥离版本号，修正 "numpy>=1.0" 误判 missing。
+- 移除 `test_analyze_dependencies_classification` 中错误的 `assert 'main' in r.ast_local`（项目名未被 import 不在 ast_local）。
+- 移除 `test_write_pth_content` 中 site-packages 目录断言（该目录由 `ensure_embed` 创建，`write_pth` 只写文件）。
+- 移除 `_infer_app_type` 死代码 try/except（`_has_entry` 已验证解析成功）。
+- 新增 `tests/test_commands.py` 直测 build/clean/run 子命令与 `_build_cmd` Linux(wine 有/无)/非 Linux 分支。
+- 补 project.py 分支测试：[project] 非 dict、_has_entry SyntaxError 跳过、多依赖非 GUI 推断 CLI。
+
+唯一未覆盖行：`project.py:83`（`detect_entry` 中 `mod in seen` 防御性 continue，正常流程无法触发，保留作防御）。
+
+## 遗留事项
+
+- mingw-w64 + wine 需用户 sudo 安装；安装前 slow 测试（真实 embed 下载 + mingw 编译 + wine 运行 + hello world 端到端）无法运行。
+- 需求 #10 端到端验证待 mingw+wine 就绪后跑 `pytest -m slow`。
+- P2：NSIS 安装包；P3：Linux 支持。

fspack-0.1.0/.trae/docs/iter-02-nsis-installer.md

@@ -0,0 +1,67 @@
+# iter-02 NSIS 安装包生成
+
+## 迭代目标
+
+在 P1 dist 产出基础上，生成 NSIS 安装脚本并调用 makensis 编译为单个 `<name>-setup.exe` 安装包，通过 `fsp p`（package）子命令触发。
+
+## 关键决策
+
+### 模块结构
+```
+src/fspack/
+  installer.py         # NSIS 脚本生成 + makensis 编译
+  commands/package.py  # fsp p → 编排 build + installer
+  cli.py               # 加 package/p 子命令
+```
+
+### NSIS 脚本设计
+- 用 MUI2 宏实现现代化安装向导（Welcome/Directory/InstFiles/Finish）。
+- 安装目录 `$PROGRAMFILES64\<name>`，`RequestExecutionLevel admin`。
+- `Section "Main"`：`SetOutPath $INSTDIR` + `File /r "dist\*.*"` 递归复制 dist 全量 + `WriteUninstaller`。
+- GUI 项目额外创建开始菜单与桌面快捷方式（`CreateShortCut`）。
+- `Section "Uninstall"`：`RMDir /r $INSTDIR` + 清理快捷方式。
+- 中英文双语（SimpChinese + English）。
+
+### makensis 调用
+- `subprocess.run(["makensis", str(nsi_path)], check=True, capture_output=True)`。
+- 缺失 makensis 抛 `InstallerError`（提示安装 NSIS）。
+- 编译产出 `<name>-setup.exe` 放 `dist/release/`。
+- 真实编译标 `@pytest.mark.slow`。
+
+### fsp p 命令
+- `fsp p [project] [--no-build] [--mirror X] [--py-version X]`。
+- 默认先 `build` 再生成安装包；`--no-build` 跳过重建直接用已有 dist。
+- dist 不存在或缺 exe 时抛 `FspackError` 提示先 `fsp b`。
+
+## 改动文件清单
+
+新增：
+- src/fspack/installer.py
+- src/fspack/commands/package.py
+- tests/test_installer.py
+
+修改：
+- src/fspack/cli.py（加 package/p 子命令）
+- src/fspack/exceptions.py（加 InstallerError）
+- tests/test_commands.py（补 package.run）
+- tests/test_cli.py（补 fsp p 分发）
+
+## 验证结果
+
+非 slow 门禁全过（2026-07-12）：
+
+- `uv run ruff check src tests`：All checks passed!
+- `uv run ruff format --check src tests`：30 files already formatted
+- `uv run pyrefly check`：0 errors（1 suppressed）
+- `uv run pytest -m "not slow" --cov=fspack --cov-fail-under=95`：96 passed, 1 deselected, 覆盖率 99.53%
+
+模块覆盖：
+- `installer.py` 100%（generate_nsis_script CLI/GUI 内容断言、compile_installer missing/error/no-output/success、build_installer no_build 三分支 + with_build）
+- `commands/package.py` 100%（默认参数 + 显式选项）
+- `cli.py` 98%（`fsp p` 分发已覆盖）
+
+## 遗留事项
+
+- makensis 需用户安装（`sudo apt install -y nsis`）；安装前 slow 编译测试与端到端安装包产出验证无法运行。
+- 需求 #5 端到端验证待 makensis 就绪后跑 `pytest -m slow`。
+- P3：Linux 支持。

fspack-0.1.0/.trae/docs/iter-03-linux-standalone.md

@@ -0,0 +1,72 @@
+# iter-03 Linux 平台支持（python-build-standalone）
+
+## 迭代目标
+
+P3 增加 Linux 打包：用 indygreg python-build-standalone 作为便携式 CPython 运行时，C loader 加载 libpython 调用 Py_Main，思路与 Windows embed 一致。复用 P1/P2 的解析/AST/依赖下载/流水线框架，加平台抽象层。
+
+## 关键决策
+
+### 平台抽象
+- 新增 `platform.py`：`Platform` 枚举（WINDOWS/LINUX）、`detect_platform()` 按 `sys.platform` 识别、平台常量（wheel platform tag、编译器、libpython 后缀）。
+- `BuildConfig` 加 `target: Platform` 字段，流水线按 target 分发。
+
+### python-build-standalone 下载（standalone.py）
+- URL：`https://github.com/indygreg/python-build-standalone/releases/download/{release_tag}/cpython-{ver}+{release_tag}-x86_64-unknown-linux-gnu-install_only.tar.gz`。
+- 缓存到 `~/.fspack/cache/standalone/`，命中跳过下载。
+- 解压到 `dist/runtime/`，解压后顶层 `python/` 目录为 Python 根（含 bin/python3.X、lib/libpython3.X.so、lib/python3.X/）。
+- `ensure_standalone` 幂等：`runtime/python/bin/python3` 存在则跳过。
+
+### Linux C loader
+- 模板用 `dlopen(libpython.so, RTLD_NOW|RTLD_GLOBAL)` + `dlsym("Py_Main")` + `setenv("PYTHONHOME", "runtime/python")`。
+- 入口路径烧入：`ENTRY_FILE`（如 `src/helloworld.py`）、`LIBPYTHON`（如 `runtime/python/lib/libpython3.11.so`）、`PYTHONHOME`（`runtime/python`）。
+- `exe_dir` 用 `readlink("/proc/self/exe")` 获取 loader 所在目录。
+- gcc 编译：`gcc -O2 -o <exe> <c> -ldl`（Linux 无 GUI 子系统，AppType.GUI 仅影响快捷方式/安装包，loader 不区分）。
+
+### 流水线分支
+- `builder.build(target=...)`：
+  - WINDOWS：ensure_embed + write_pth + mingw loader + wheel `win_amd64`
+  - LINUX：ensure_standalone（不写 _pth，用 PYTHONHOME）+ gcc loader + wheel `manylinux2014_x86_64`
+- Linux 不写 _pth（PYTHONHOME 已定位标准库，site-packages 在 `runtime/python/lib/python3.X/site-packages`）。
+
+### CLI
+- `fsp b --target linux|windows`（默认当前平台）。
+- `fsp p --target` 同理。
+
+## 改动文件清单
+
+新增：
+- src/fspack/platform.py
+- src/fspack/standalone.py
+- tests/test_standalone.py
+- tests/test_platform.py
+
+修改：
+- src/fspack/config.py（BuildConfig 加 target）
+- src/fspack/loader.py（generate_loader_source/compile_loader 加 platform 分支 + Linux 模板）
+- src/fspack/builder.py（build 加 target 参数，按平台分支）
+- src/fspack/commands/build.py、package.py（透传 target）
+- src/fspack/cli.py（--target 选项）
+
+## 验证结果
+
+四项门禁全过（2026-07-12）：
+
+- `ruff check src tests`：All checks passed
+- `ruff format --check src tests`：34 files already formatted
+- `pyrefly check`：0 errors（2 suppressed）
+- `pytest -m "not slow" --cov=fspack`：118 passed, 1 deselected, cov 99.08%
+
+修复要点：
+- `loader.generate_loader_source` Linux 分支 libpython 路径漏 "python" 前缀（`lib3.11.so` → `libpython3.11.so`），与 `platform.libpython_so` 对齐。
+- `test_loader.py` 缺 `Platform`/`gcc_available` 导入。
+- `test_builder.py` Windows 测试的 `fake_compile` 缺 `platform` 参数、`download_wheels` lambda 缺 `platform_tag` 关键字参数（builder.build 现按 target 透传）。
+
+未覆盖行（非新增）：
+- `platform.py:21`（detect_platform 的 Windows 分支，Linux dev 不可达）
+- `project.py:83`（防御性 `mod in seen` continue）
+- `cli.py:66->exit`/`82`（argparse 错误分支）
+
+## 遗留事项
+
+- python-build-standalone 真实下载/gcc 编译标 slow，待环境验证。
+- P4：macOS 支持；Linux 安装包（.deb/.rpm/AppImage）。

fspack-0.1.0/.trae/docs/iter-04-code-quality.md

@@ -0,0 +1,51 @@
+# iter-04 代码质量改进与覆盖率提升
+
+## 迭代目标
+
+P1/P2/P3 三阶段交付后，清理冗余字段并补齐未覆盖分支，提升覆盖率与代码质量。
+
+## 关键决策
+
+### BuildConfig.arch 移除
+- `arch: str = "win_amd64"` 字段未被任何业务代码使用（builder.py 用 `wheel_platform_tag(target)` 派生），且默认值对 Linux target 不正确。
+- 移除字段，test_config.py 断言改为 `cfg.target == Platform.WINDOWS`（真正表达平台语义）。
+
+### detect_platform Windows 分支
+- `platform.py:21` 的 Windows 分支在 Linux dev 下不可达。用 monkeypatch `_platform.system` 返回 "Windows"/"Linux" 分别测试两个分支。
+
+### detect_entry 去重分支（核心发现）
+- `project.py` 的 `if mod in seen or not path.is_file(): continue` 长期显示 line 83 (continue) missing。
+- 根因：Python sys.settrace 对 `if: continue` 的 JUMP_ABSOLUTE 指令不触发 continue 行的 line event，导致 coverage 误报。用 sys.settrace 追踪 locals 确认 `mod in seen` 确实为 True 但 continue 行未被记录。
+- 修复：改写为正向条件 `if mod not in seen and path.is_file():`，消除 continue 语句。De Morgan 等价，语义不变，coverage 正确记录。
+
+### _parse_target windows 分支
+- `cli.py:82` 的 `return Platform.WINDOWS` 未覆盖（之前只测 --target linux）。加 `test_build_target_windows_dispatch`。
+
+## 改动文件清单
+
+修改：
+- src/fspack/config.py（移除 BuildConfig.arch）
+- src/fspack/project.py（detect_entry 改写正向条件）
+- tests/test_config.py（断言 arch → target）
+- tests/test_platform.py（+2 detect_platform Windows/Linux 分支测试）
+- tests/test_project.py（+1 dedup 同名无 entry 测试）
+- tests/test_cli.py（+1 --target windows 分发测试）
+
+## 验证结果
+
+四项门禁全过（2026-07-12）：
+
+- `ruff check src tests`：All checks passed
+- `ruff format --check src tests`：34 files already formatted
+- `pyrefly check`：0 errors（2 suppressed）
+- `pytest -m "not slow" --cov=fspack`：122 passed, 1 deselected, cov 99.87%
+
+覆盖率演进：
+- P3：118 passed, cov 99.08%（未覆盖：platform.py:21、project.py:83、cli.py:82）
+- P4：122 passed, cov 99.87%（project.py 达 100%，platform.py 100%，cli.py 99%）
+- 仅剩 cli.py `66->exit`（argparse choices 限制，command 非 build/run/clean/package 的分支不可达）
+
+## 遗留事项
+
+- cli.py `66->exit` 为 argparse 结构性不可达分支，接受现状（99.87% 已远超 95% 门槛）。
+- slow 端到端验证仍待外部环境（mingw/wine/makensis/python-build-standalone 真实下载）。

fspack-0.1.0/.trae/req/req-01-fspack-p1.md

@@ -0,0 +1,48 @@
+# fspack P1 需求清单
+
+参考本人 fspacker（PyPI）设计的新一代 Python 打包 CLI 工具 `fspack`。
+
+## 总体目标
+
+构建一个类似 cargo 的简洁 Python 打包工具，使用 embed python 调用用户脚本，通过 C loader 配置运行环境，最终用 NSIS 打包为 Windows 安装包分发。本文件记录第一阶段（P1）需求。
+
+## 平台与范围（用户确认）
+
+- 目标平台：Windows 优先，Linux 后续阶段。
+- Loader 实现：C + Python 引导（C 设置环境加载 embed python，重逻辑放 Python）。
+- 安装包工具：NSIS（后续阶段，P1 不含）。
+- 开发环境：Linux 交叉编译（mingw-w64 + wine）。
+
+## P1 范围（垂直切片：能运行 hello world）
+
+[x] 1. CLI 骨架：`fsp b`(build) / `fsp c`(clean) / `fsp r`(run) / `fsp -V`(version)，cargo 风格短命令，argparse 子命令分发。
+[x] 2. 项目元数据解析：解析 pyproject.toml（name/version/dependencies），识别入口（`def main()` 或 `if __name__=='__main__'`），判定 CLI/GUI 类型。
+[x] 3. AST 依赖分析：扫描源码 import，提取顶层模块，与标准库/本地包/第三方分类，补全未声明依赖。
+[x] 4. embed python 下载：国内镜像源（华为云优先，阿里云/清华备选）下载 `python-X.Y.Z-embed-amd64.zip`，缓存到 `~/.fspack/cache/embed/`，解压到 `dist/runtime/`。
+[x] 5. _pth 配置：生成 `python3X._pth` 启用 site-packages，创建 `Lib/site-packages` 目录。
+[x] 6. 依赖下载：用 dev python 的 `pip download --platform win_amd64 --only-binary=:all:` 拉取 Windows wheel 到 wheelhouse，解包到 `dist/runtime/Lib/site-packages/`。
+[x] 7. C loader 生成与编译：生成 C 源码（动态加载 python3X.dll，调用 `Py_Main` 运行入口脚本），支持 CLI(console)/GUI(windows) 子系统，用 `x86_64-w64-mingw32-gcc` 交叉编译为 .exe（编译命令已实现并单测 mock，真实编译待 mingw）。
+[x] 8. 构建流水线编排：parse → download embed → download deps → copy src → gen loader → compile → assemble dist/。
+[x] 9. run/clean 命令：`fsp r` 用 wine 运行 dist 下的 .exe；`fsp c` 清理 dist/。
+[] 10. hello world 端到端验证：一个无依赖的示例项目能 `fsp b` 后 `fsp r` 输出 "hello, world"（待 mingw-w64 + wine 安装后跑 slow 测试验证）。
+
+## 不在 P1 范围
+
+- NSIS 安装包生成（P2）。
+- Linux 平台支持（P3+）。
+- 源码加密（pyarmor）、nuitka 编译优化。
+- 多项目批量打包。
+
+## 验收标准
+
+- `fsp b` 对无依赖项目产出 `dist/<name>.exe` + `dist/runtime/` + `dist/src/` + `dist/runtime/Lib/site-packages/`。
+- `fsp r` 通过 wine 运行 .exe 输出预期内容。
+- `fsp c` 清空 dist/。
+- 全套门禁通过：`ruff check`、`ruff format --check`、`pyrefly check`、`pytest --cov≥95%`（mingw/wine/网络相关标 slow）。
+- Python 3.8 兼容。
+
+## 约束
+
+- 国内镜像优先；网络/编译/运行类测试标 `slow`。
+- 不引入 requests 等重依赖，下载用 urllib + tomli（仅 py<3.11）。
+- 遵循 rule-11 Python 规范与既有工具链配置。

fspack-0.1.0/.trae/req/req-02-fspack-p2.md

@@ -0,0 +1,31 @@
+# fspack P2 需求清单
+
+P1 已交付 CLI + 解析 + 下载 + loader 垂直切片（非 slow 门禁全过）。P2 在此基础上增加 NSIS 安装包生成，使用户能产出可分发的 Windows 安装程序。
+
+## P2 范围
+
+[x] 1. NSIS 脚本生成器：根据 ProjectInfo 与 dist 目录内容生成 `.nsi` 脚本，含 Name/OutFile/InstallDir/Section(File /r)/UninstallSection/CreateShortCut（GUI 时）。
+[x] 2. makensis 编译调用：调用 `makensis` 将 .nsi 编译为单个 `<name>-setup.exe` 安装包，输出到 `dist/release/`（编译命令已实现并单测 mock，真实编译待 makensis）。
+[x] 3. `fsp p`(package) 子命令：在 `fsp b` 产出 dist 基础上生成安装包；支持 `--no-build` 跳过重建直接打包已有 dist。
+[x] 4. 单测：NSIS 脚本内容断言（Name/OutFile/File/Shortcut/Uninstall）、makensis 调用 mock、`fsp p` 命令分发。
+[] 5. 端到端验证（slow）：真实 makensis 编译安装包，断言 .exe 产出（待 makensis 安装）。
+
+## 不在 P2 范围
+
+- 数字签名（signtool）。
+- 自动更新（在线升级机制）。
+- 多语言安装界面（仅中文 + 英文默认）。
+- Linux 平台支持（P3）。
+
+## 验收标准
+
+- `fsp p` 对已构建项目产出 `dist/release/<name>-setup.exe`。
+- NSIS 脚本含完整安装/卸载逻辑，GUI 项目额外创建开始菜单与桌面快捷方式。
+- 全套门禁通过：`ruff check`、`ruff format --check`、`pyrefly check`、`pytest --cov≥95%`（makensis 相关标 slow）。
+- Python 3.8 兼容。
+
+## 约束
+
+- 不引入新依赖，NSIS 脚本用字符串模板生成。
+- makensis 调用用 subprocess，标 slow。
+- 遵循 rule-11 Python 规范。

fspack-0.1.0/.trae/req/req-03-fspack-p3.md

@@ -0,0 +1,33 @@
+# fspack P3 需求清单
+
+P1/P2 已交付 Windows 优先的完整链路（CLI + 解析 + embed + loader + NSIS）。P3 增加 Linux 平台支持，运行时用 indygreg 的 python-build-standalone 便携式 CPython，C loader 加载 libpython 调用 Py_Main，思路与 Windows embed 一致。
+
+## P3 范围
+
+[x] 1. 平台抽象：新增 `Platform` 枚举（WINDOWS/LINUX），`BuildConfig` 带 target 字段，`detect_platform()` 识别当前系统。
+[x] 2. python-build-standalone 下载与解压：新增 `standalone.py`，从 GitHub releases 下载 `cpython-{ver}+{date}-x86_64-unknown-linux-gnu-install_only.tar.gz`，缓存到 `~/.fspack/cache/standalone/`，解压到 `dist/runtime/python/`。
+[x] 3. Linux C loader：扩展 `loader.py` 生成 Linux C 源码（dlopen libpython.so + dlsym Py_Main + setenv PYTHONHOME），用 gcc 编译为 ELF 可执行文件（`-ldl`）。
+[x] 4. Linux 依赖下载：扩展 `builder.download_wheels` 支持 `--platform manylinux2014_x86_64` 拉 Linux wheel。
+[x] 5. 流水线平台分支：`builder.build` 加 `target` 参数，按平台调 standalone/embed + 对应 loader + 对应 wheel 平台。
+[x] 6. CLI `--target`：`fsp b`/`fsp p` 加 `--target windows|linux`，默认当前平台。
+[x] 7. 单测：standalone 下载/解压 mock、Linux loader 源码内容断言、gcc 编译 mock、build target 分支、CLI --target 分发。
+[] 8. 端到端验证（slow）：真实下载 python-build-standalone + gcc 编译 + 运行 hello world。
+
+## 不在 P3 范围
+
+- macOS 支持（P4+）。
+- Linux 安装包（.deb/.rpm/AppImage），P3 仅产出可运行目录。
+- Linux GUI（无 windows 子系统概念，Tk/Qt 直接运行）。
+
+## 验收标准
+
+- `fsp b --target linux` 在 Linux 上产出 `dist/<name>`（ELF 可执行文件）+ `dist/runtime/python/` + `dist/src/` + `dist/runtime/python/lib/python3.X/site-packages/`。
+- `dist/<name>` 直接运行输出预期内容（无需 wine）。
+- 全套门禁通过：`ruff check`、`ruff format --check`、`pyrefly check`、`pytest --cov≥95%`（standalone 下载/gcc 编译标 slow）。
+- Python 3.8 兼容（dev 环境）。
+
+## 约束
+
+- python-build-standalone 从 GitHub 下载（无稳定国内镜像），标 slow；单测 mock urllib。
+- Linux loader 用 gcc（系统自带），不需 mingw。
+- 遵循 rule-11 Python 规范，平台分支用枚举分发，避免字符串判断。

fspack-0.1.0/.trae/req/req-04-fspack-p4.md

@@ -0,0 +1,27 @@
+# fspack P4 需求清单
+
+P1/P2/P3 已交付三阶段完整链路。P4 聚焦代码质量改进与覆盖率提升，消除冗余字段并补齐未覆盖分支。
+
+## P4 范围
+
+[x] 1. 移除 `BuildConfig.arch` 冗余字段：实际平台标签由 `wheel_platform_tag(target)` 派生，arch 字段未被使用且默认值 "win_amd64" 对 Linux 不正确。同步清理 test_config.py 对应断言。
+[x] 2. 补 `detect_platform` Windows 分支测试：monkeypatch `platform.system` 返回 "Windows"，覆盖 platform.py:21。
+[x] 3. 补 `detect_entry` 重复候选测试：构造项目名与 .py 同名且该文件无 entry、另一文件有 entry 的场景，触发 `mod in seen` continue 分支（project.py:83）。
+[x] 4. 补 `_parse_target` windows 分支测试：`fsp b --target windows` 分发，覆盖 cli.py:82 的 `return Platform.WINDOWS`。
+[x] 5. 全套门禁通过：ruff check / ruff format --check / pyrefly check / pytest --cov≥95%（覆盖率不得低于 99.08%）。
+
+## 不在 P4 范围
+
+- macOS 支持、Linux 安装包（P5+ 候选）。
+- slow 端到端验证（依赖外部环境安装）。
+
+## 验收标准
+
+- `BuildConfig` 无 arch 字段，所有引用清理干净。
+- 四项门禁全过，覆盖率不低于 99.08%。
+- 未覆盖分支数减少。
+
+## 约束
+
+- 遵循 rule-11 Python 规范。
+- 测试用 monkeypatch，禁用 @patch 装饰器。