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 地址

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

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

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

许可

Apache-2.0