ztxexp 是一个面向深度学习和大模型实验的抽象框架，目标是让实验迭代更快、更可复现。
- 2026-03-02 20:05:00 (Asia/Shanghai): 发布
v1.0.3交互式 Command-Line 模板向导，新增ztxexp init-template，通过 7 问配置（消融、模块、模式、指标、追踪器）拼装可运行实验骨架，并提供软依赖检查（init-vibe/init-skill缺失仅告警不阻断）、--dry-run、受管覆盖保护与--force接管能力。 - 2026-03-02 16:15:33 (Asia/Shanghai): 发布
v1.0.2skills 生态支持，新增ztxexp init-skill/show-skill/remove-skill，可将内置ztx-exp-managerskill 注入到用户项目；init-skill在未指定--target时支持交互选择写入skills/、.codex/skills/或两处同时写入，并提供受管标记与安全删除策略。 - 2026-03-02 15:28:11 (Asia/Shanghai): 发布
v1.0.1CLI 能力，新增ztxexp init-vibe/show-vibe/remove-vibe，可在任意目标项目中持久化写入（或移除）Agent 使用区块，支持profile/language/project-root/agents-file/dry-run参数。 - 2026-03-02 13:40:53 (Asia/Shanghai): 版本基线升级为
1.0.0，用于修复历史版本号（0.30.0与0.4.0）导致的升级顺序歧义，确保包管理器始终选择正确的最新版本。 - 2026-03-02 12:22:22 (Asia/Shanghai): 完成
v0.4.0发布级收口，新增 CI 工作流（ruff + pytest + mkdocs --strict + build + twine check）与模板 smoke tests；同时修正依赖分层，mlflow/wandb保持为可选 extras，不再随dev默认安装。 - 2026-03-02 11:56:15 (Asia/Shanghai): 发布
v0.4.0复现与治理闭环能力：新增RunMetadata/MetricEvent、meta.json/metrics.jsonl/events.jsonl、ctx.log_metric(...)、name/group/tags/lineage/retry/random_search/track等接口，并提供JsonlTracker+ 可选MlflowTracker/WandbTracker。 - 2026-03-02 01:25:15 (Asia/Shanghai): 新增
examples/template_library可复制模板库（27 个场景模板），覆盖基础构建、并行调度、分析清理、ML、LLM、工程运维。 - 2026-03-02 00:58:21 (Asia/Shanghai): 在
ztxexp.utils新增 12 个高频实验工具函数，覆盖嵌套配置处理、配置差异比较、可读 run 命名、原子写入、JSONL 读写、重试调用与批处理切分。- 新增函数：
flatten_dict、unflatten_dict、deep_merge_dicts、dict_diff、sanitize_filename、build_run_name、split_batches、write_text_atomic、save_json_atomic、append_jsonl、load_jsonl、retry_call。
- 新增函数：
- 规则（持久化）：后续每次仅在“功能或行为”发生更新时，才在本板块追加记录；文档/样式/站点配置类变更不写入本板块。
在真实项目里，实验常见痛点是：
- 参数空间大，配置组合容易失控。
- 并行执行后目录结构混乱，成功/失败难追溯。
- 结果聚合脚本碎片化，清理成本高。
ztxexp 提供四个核心抽象：
ExpManager: 负责配置构建（grid、variants、modify、where）。ExpRunner: 负责执行调度（sequential/process_pool/joblib/dynamic）。ResultAnalyzer: 负责聚合与清理。ExperimentPipeline: 一体化入口，适合绝大多数场景。
v0.4 统一并扩展了 run 产物协议（schema v2 兼容）：
config.jsonrun.jsonmeta.json（可选）metrics.json（可选）metrics.jsonl（可选，step 级指标）events.jsonl（可选，生命周期事件）artifacts/
成功判定规则：
run.json.status == "succeeded"
pip install ztxexp可选：启用 PyTorch 辅助工具。
pip install "ztxexp[torch]"如果你要导出 Excel 透视表：
pip install "ztxexp[excel]"# 在当前项目中创建或更新受管区块（默认）
ztxexp init-vibe
# 预览将写入内容
ztxexp show-vibe --profile webcoding --language bilingual
# 写入到指定项目根目录
ztxexp init-vibe --project-root /path/to/your-project
# 显式指定目标文件（相对路径基于 project-root）
ztxexp init-vibe --agents-file AGENTS.md
# 仅预览变更，不落盘
ztxexp init-vibe --dry-run
# 移除受管区块（不影响用户自定义内容）
ztxexp remove-vibe --project-root /path/to/your-project# 交互式初始化（未指定 --target 时会提示 1/2/3）
ztxexp init-skill
# 非交互模式：默认写入 skills/
ztxexp init-skill --no-interactive
# 显式指定写入目标
ztxexp init-skill --target skills
ztxexp init-skill --target codex
ztxexp init-skill --target both
# 预览内置 skill 内容
ztxexp show-skill --language bilingual
# 预览并附带 agents/openai.yaml
ztxexp show-skill --language zh --with-openai
# 移除受管安装（默认检查 skills + .codex/skills）
ztxexp remove-skill
ztxexp remove-skill --target both
# 仅预览，不落盘
ztxexp init-skill --dry-run
ztxexp remove-skill --dry-run# 交互式 7 问向导（推荐）
ztxexp init-template
# 非交互模式（需要显式传 name）
ztxexp init-template --name my_experiment --no-interactive
# 快速采用推荐默认值（含交互模式）
ztxexp init-template --name my_experiment --yes
# 仅预览生成计划，不落盘
ztxexp init-template --name my_experiment --no-interactive --dry-run
# 指定输出目录
ztxexp init-template --name my_experiment --output-dir experiments_custom
# 目录已存在时强制接管覆盖
ztxexp init-template --name my_experiment --no-interactive --force生成目录默认位于：<project-root>/experiments/<experiment_name>/。
主脚本 main_experiment.py 内置 run/analyze/clean 子命令，可直接执行实验、结果聚合与清理示例。
参数说明（init-vibe / remove-vibe）：
--project-root PATH：目标项目目录，默认当前工作目录。--agents-file PATH：显式目标文件；未传时按AGENTS.md -> agents.md -> agents.MD自动复用。--dry-run：仅展示 diff，不写文件。
参数说明（init-vibe / show-vibe）：
--profile {webcoding,codex,cursor,cline,copilot}：默认webcoding。--language {bilingual,zh,en}：默认bilingual。
参数说明（init-skill）：
--project-root PATH：目标项目目录，默认当前工作目录。--target {skills,codex,both}：skill 写入目标；不传时进入 1/2/3 交互选择。--language {bilingual,zh,en}：生成的SKILL.md语言，默认bilingual。--dry-run：仅预览变更，不写文件。--no-interactive：禁用交互，默认回退到skills/。--force：允许覆盖未受管目录（谨慎使用）。
参数说明（remove-skill）：
--project-root PATH：目标项目目录，默认当前工作目录。--target {skills,codex,both}：删除范围；不传时默认both。--dry-run：仅预览将删除的目标。--force：允许删除未受管目录（默认仅删除受管安装）。
参数说明（init-template）：
--project-root PATH：目标项目目录，默认当前工作目录。--name NAME：模板名称；交互模式可不传，--no-interactive时必须传。--output-dir PATH：输出根目录，默认<project-root>/experiments。--dry-run：仅预览目录与文件计划，不写入文件。--no-interactive：关闭交互问答并采用推荐默认配置。--force：目标目录已存在且未受管时允许接管覆盖。--yes：交互模式下所有问题采用推荐默认值，加速初始化。
受管区块标记：
<!-- ztxexp:vibe:start --><!-- ztxexp:vibe:end -->
from ztxexp import ExperimentPipeline, RunContext
def exp_fn(ctx: RunContext):
lr = ctx.config["lr"]
model = ctx.config["model"]
# 业务产物统一放 artifacts 目录
(ctx.run_dir / "artifacts" / "info.txt").write_text(
f"run={ctx.run_id}, model={model}, lr={lr}\n",
encoding="utf-8",
)
# 返回 dict 会自动写入 metrics.json
return {"score": round((1.0 - lr) + (0.05 if model == "tiny" else 0.02), 4)}
summary = (
ExperimentPipeline("./results_demo", base_config={"seed": 42})
.grid({"lr": [0.001, 0.01]})
.variants([{"model": "tiny"}, {"model": "base"}])
.exclude_completed()
.run(exp_fn, mode="sequential")
)
print(summary)from ztxexp import ResultAnalyzer
analyzer = ResultAnalyzer("./results_demo")
df = analyzer.to_dataframe(statuses=("succeeded",))
print(df[["run_id", "model", "lr", "score"]])
analyzer.to_csv("./results_demo/summary.csv", sort_by=["model", "lr"])模板库目标是“复制后只改业务逻辑”，尽量覆盖常见 Python 实验场景：
- 基础构建：最小实验、网格+变体、多种子复现、manager/runner 解耦。
- 并行调度：
process_pool、joblib、dynamic、非法配置SkipRun。 - 结果分析：DataFrame 导出、CSV、透视表、清理策略、排行榜。
- ML 场景：分类、回归、时序、异常检测、推荐排序。
- LLM 场景：Prompt、RAG、Tool Use、安全评测、服务压测。
- 工程运维：消融、预算受限搜索、断点恢复、数据版本对比、复现性审计。
文档中可直接复制代码：
-
返回值不是
dict | None会被判定为失败，并写入error.log。 -
仍按旧版
_SUCCESS判断成功 v0.4 不再使用_SUCCESS，以run.json为准。 -
直接把大文件写在 run 根目录 建议统一放到
artifacts/，便于后续清理和归档。 -
dynamic模式用于生产实时场景dynamic是实验特性（experimental），更适合离线批任务。
文档采用“源码注释驱动”模式，不再手工维护 API Markdown：
mkdocs build时自动扫描ztxexp/*.py；- 自动生成首页
index.md与reference/API 页面； mkdocstrings从类/函数 docstring 渲染参数、返回值与示例。
推荐先看用户手册，再查 API：
本地入口：
- 生成脚本：
scripts/gen_ref_pages.py - 模板文档：
examples-lib/（由examples/template_library自动生成） - 构建产物：
docs/index.html与docs/reference/（构建后生成）
常用命令：
pip install -e ".[docs]"
NO_MKDOCS_2_WARNING=1 mkdocs build --strict
NO_MKDOCS_2_WARNING=1 mkdocs serve
# 或使用脚本：sh mk.sh build / sh mk.sh serve可选追踪器安装：
pip install "ztxexp[mlflow]"
pip install "ztxexp[wandb]"欢迎提交 Issue 或 PR：
- Issues: https://github.com/ztxtech/ztxexp/issues
- Repository: https://github.com/ztxtech/ztxexp
MIT License