xharness

面向 Python 和 TypeScript 的共享基础库，提供 Windows 应用打包、发布部署、配置与日志等运维支持。

最低环境要求：Python 3.12 与 Node.js 22。

安装

Python (uv)

uv add xharness

TypeScript / Node.js (npm)

npm i @lightxlab/xharness

快速上手

xharness 核心用于产品的打包与发布部署。

1. 本地打包 Windows 可执行文件

支持 .py（基于 PyInstaller）和 .js（基于 Node pkg）入口，默认打包输出至 dist/。

Python

from xharness import deploy

request = deploy.BuildRequest(entrypoint="app.py")
output_path = deploy.build(request)

print(f"可执行文件已生成: {output_path}")

也可以直接通过 CLI 打包：

uv run xharness-build --entrypoint app.py

TypeScript

import { deploy } from "@lightxlab/xharness";

const { artifactPath } = await deploy.build({
  entrypoint: "app.js",
});

console.log(`可执行文件已生成: ${artifactPath}`);

2. 打包配置 (xharness.toml)

如果需要自定义打包名称、输出目录或打包工具参数，可在产品根目录创建 xharness.toml：

product = "my-product"
output = "dist"

[pyinstaller]
hidden-imports = ["uvicorn"]
resources = [
  { source = "assets", destination = "assets" }
]

[pkg]
compress = "GZip"

3. 日志

logging.configure() 基于 Loguru 配置控制台与文件日志：

from xharness import logging

logging.configure()

logging.info("应用已启动")

• 控制台输出到 stderr（默认 INFO），文件写入 <product>.log（默认 DEBUG）
• 文件按 10 MB 或每天轮转，保留 14 天
• log_dir、product、level、console_level、file_level 可覆盖默认值，XHARNESS_LOG_DIR、XHARNESS_LOG_LEVEL 作为回退
• product 默认取可执行文件 / 脚本的文件名主干，须符合产品名规范 ^[a-z][a-z0-9_-]*$
• log_dir 默认遵循路径策略：单文件可执行文件写在 <runtime_root>/log/<product>/，否则写在 <state_root>/<product>/log；优先级为 log_dir 参数 > <PRODUCT>_LOG_DIR > XHARNESS_LOG_DIR > 路径策略默认值（越具体越优先）
• 重复调用会替换已有 sink；第三方库的标准库 logging 默认接管，intercept_stdlib=False 可关闭
• 一个日志文件只有一个写入者：同一产品的并发实例需传入不同的 log_dir
• 日志目录不可写时降级为仅控制台输出，并给出警告

4. 运行时配置与打包模式

from xharness import config, env

runtime = env.runtime_name()
settings = config.load()

当前 config.load 仍为接口占位桩函数（调用抛出 NotImplementedError / Error），后续版本开放具体实现；env.runtime_name / runtimeName 已实现打包模式探测（返回 source、pyinstaller、pkg 或 unknown）。

5. 产品发布工具

npm 包提供 xharness-product-release 命令，从产品的 v* CalVer 标签构建并挂载发布产物。一次发布包含可执行文件、manifest 与 SHA-256 校验和，三者共用同一个文件名主干（release trio）：

xharness-product-release pins --entrypoint app.js
xharness-product-release build --ref v2026.10.0 --entrypoint app.js --output dist
xharness-product-release attach --ref v2026.10.0 --output dist

• pins：输出打包工具版本（pkg、pyinstaller、node），产品根目录的 xharness.toml 可以覆盖
• build：从标签构建并校验 release trio。--entrypoint 是产品根目录内的相对路径；--signing-command 接收 JSON 字符串数组，签名密钥取自 XHARNESS_SIGNING_SECRET；--pre-ship-command 在打包前执行。pkg 后端要求 PKG_CACHE_PATH 指向已预取的 Node 基础二进制
• attach：把校验过的 release trio 挂到对应的 GitHub Release，需要 GH_TOKEN 或 GITHUB_TOKEN；GITHUB_REPOSITORY 指定产品仓库，XHARNESS_RELEASE_API 可覆盖 API 地址。--artifact <file> 改为挂载 release pair：产品自己构建的一个文件，名为 <name>-<version>.<rest>，旁边是 <file>.sha256（在该文件的目录里运行 sha256sum 得到的 <sha256hex> <filename>）。--output 和 --artifact 恰好给其中一个

产品 CI 直接调用可复用发布工作流时，见 产品 Windows 发布工作流（公开包、无需 token）。

产品自己构建文件、不发布 Windows 可执行文件时，v* 标签触发构建任务：写出 <name>-<version>.<rest>，在输出目录运行 sha256sum，用 actions/upload-artifact 上传，并把文件名作为 job output。release 任务 needs: build，并声明 permissions: contents: write（被调用的工作流不能超过调用方的权限）：

on:
  push:
    tags: ["v*"]
jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      file: ${{ steps.pack.outputs.file }}
    steps:
      - uses: actions/checkout@v4
      - id: pack
        run: |
          version="${GITHUB_REF_NAME#v}"
          file="widget-${version}.zip"
          mkdir -p dist
          # the product build writes dist/$file
          (cd dist && sha256sum "$file" > "$file.sha256")
          echo "file=$file" >> "$GITHUB_OUTPUT"
      - uses: actions/upload-artifact@v4
        with:
          name: product-file
          path: |
            dist/${{ steps.pack.outputs.file }}
            dist/${{ steps.pack.outputs.file }}.sha256
  release:
    needs: build
    permissions:
      contents: write
    uses: lightxlab/xharness/.github/workflows/product-artifact-release.yml@<harness tag>
    with:
      ref: ${{ github.ref_name }}
      artifact: product-file
      file: ${{ needs.build.outputs.file }}

Python 后端（.py 入口）要求目标 Python 环境能导入 xharness，用 uv pip install xharness 安装。

产品工作流安装的 PyPI xharness 与 npm 包版本保持一致（同一个 tag），两个包成对发布。

版本号与标签门

xharness-bump 和 xharness-check-tag 是 npm 包 @lightxlab/xharness 的 bin，也是 PyPI 包 xharness 的 console script。

xharness-bump --scheme calver --now 2026-10-31T16:00:00Z
xharness-bump --scheme semver --part patch
xharness-check-tag --scheme semver --strict 1.2.3

成功时标准输出只有新版本或标签再加一个换行，xharness-bump 的标准错误是 旧版本 → 新版本 与 suggested tag: 标签 两行，xharness-check-tag 的标准错误为空；失败时退出码为 1，标准输出为空，标准错误的第一行以 error: 开头并以句号结束。

xh

xh 和 xharness 是同一个产品发布命令。npm 包和 PyPI 包都提供这两个入口。

xh bump
xh bump v2026.11.0
xh bump --pr
xh tag
xh check

xh bump 只改版本源文件和适用的 lockfile。默认按 Asia/Shanghai 计算下一个产品版本。显式版本写成 vYYYY.M.N，写入版本源文件的仍是 YYYY.M.N。xh bump --pr 从干净且最新的 main 创建分支 release/v<version>、提交，并打开标题为 Release v<version> 的拉取请求。

合并之后，xh tag 读取最新 main 的产品版本，在该提交上创建轻量 v* 标签并推送。标签已存在或门禁失败时停止，不会强制移动标签。

xh check 检查产品版本、标签、提交和工作区。xh build、xh verify 和 xh release 不接收另一个版本参数，并先做与 xh check 相同的门禁。

xh build 读取产品根目录 xharness.toml 的 [build]。最小声明只有 backend、entrypoint 和 exe 命名模板：

product = "widget"
output = "dist"

[build]
backend = "pkg"
entrypoint = "app.js"
exe = "widget-{tag}.exe"

{version} 展开为 YYYY.M.N，{tag} 展开为 v* 标签。构建器把展开后的名称直接写进输出目录，没有事后改名。backend 为 pyinstaller 时入口是 .py。dependencies 省略时为空；每一项都是运行时 basename，和 exe 放在同一目录。可选 setup、prepare、finalize 和 signing 是命令参数数组。顺序是 setup、prepare、标准构建、可选签名、finalize、文件集合校验。任一步骤非零退出都会停。finalize 的最后两个参数是 exe 路径和输出目录。签名就地改这个 exe，后面的校验看到的是签名后的文件。输出目录必须正好包含这个 exe 和声明的依赖。这条路径不打 ZIP，不写 manifest，也不写 checksum。

xh verify 读取 [verify]，启动输出目录里的最终 exe，并处理启动、等待、timeout、日志和进程树清理。

[verify]
mode = "http"
url = "http://127.0.0.1:8080/health"
timeout = 30
args = ["--port", "8080"]
env = { PORT = "8080" }
check = ["node", "check.js"]

mode 是 command-exit 或 http。timeout 是正整数秒。可选 args 传给 exe。可选 env 只放非机密字符串；机密值从 CI 环境注入，不写进 TOML。http 必须给出 url，返回 2xx 才算就绪。可选 check 做功能检查：http 在 exe 仍在运行时执行，command-exit 在零退出后执行，最后两个参数是 exe 路径和输出目录。日志写在 .xharness/verify.log。成功时写入与当前提交和输出目录一致的 .xharness/windows-verified。标准验证或功能检查失败都会失败，并删除这份记录，因此 xh release 不会创建 Draft。这两份文件都不会上传。未跟踪的 .xharness/windows-verified 和 .xharness/verify.log 不会让 xh check、xh build、xh verify 或 xh release 的干净工作区门禁失败；其它改动仍会挡住。

xh release 同样不接收版本参数，也不接受 --clobber。门禁通过后，只有构建和 Windows 验证都成功才创建 Draft：验证记录在 .xharness/windows-verified，必须与输出目录里的原始文件和当前提交一致，并且不会被上传。全部文件上传成功后 Draft 才公开。上传或公开失败时 Draft 保留；重跑跳过相同资产、替换变化的同名资产、补齐缺失资产并删除过期 Draft 资产。已经公开的 Release 只在必需文件字节一致时成功，不增删改资产，多出来的已公开资产保留。标签或目标提交不一致时直接失败。

产品的 v* 标签调用固定到某个 xh 发布版本的标准 workflow。pkg 在 Ubuntu 上用 Node 22 和 npm 或 pnpm lockfile 构建；PyInstaller 在 Windows x64 上用 Python 3.12、uv 和产品 lockfile 构建。构建、Windows 验证和发布之间传递同一份产品发布文件集，验证成功后才发布。调用方只保留这一个 job。见 产品发布工作流。

许可

Apache-2.0