NepTrainKit 2.8.3.dev0__tar.gz → 2.8.4__tar.gz

{neptrainkit-2.8.3.dev0 → neptrainkit-2.8.4}/.gitignore

@@ -3,8 +3,11 @@
 /build
 /dist
 /docs/build
+/docs/_build
+/.tmp/docs-screenshots
 .idea/
 /src/NepTrainKit/?.py
+/src/NepTrainKit/_version.py
 /src/NepTrainKit/Log/*.log
 .pytest_cache/
 tests/_sandbox_tmp/

{neptrainkit-2.8.3.dev0 → neptrainkit-2.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: NepTrainKit
-Version: 2.8.3.dev0
+Version: 2.8.4
 Summary: NepTrainKit is a Python package for visualizing and manipulating training datasets for NEP.
 Author: Chen Cheng bing
 Author-email: Chen Cheng bing <1747193328@qq.com>
@@ -167,7 +167,7 @@ A standalone executable is available for Windows users.
 For detailed usage documentation and examples, please refer to the official documentation:  
 [https://neptrainkit.readthedocs.io/en/latest/index.html](https://neptrainkit.readthedocs.io/en/latest/index.html)
 
-- What's new: see `docs/source/changelog.md` or the Documentation "Changelog" page.
+- What's new: see [GitHub Releases](https://github.com/aboys-cb/NepTrainKit/releases).
 
 ---
 

{neptrainkit-2.8.3.dev0 → neptrainkit-2.8.4}/README.md

@@ -121,7 +121,7 @@ A standalone executable is available for Windows users.
 For detailed usage documentation and examples, please refer to the official documentation:  
 [https://neptrainkit.readthedocs.io/en/latest/index.html](https://neptrainkit.readthedocs.io/en/latest/index.html)
 
-- What's new: see `docs/source/changelog.md` or the Documentation "Changelog" page.
+- What's new: see [GitHub Releases](https://github.com/aboys-cb/NepTrainKit/releases).
 
 ---
 

neptrainkit-2.8.4/skills/make-dataset-card-dev/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: make-dataset-card-dev
+description: 将“需求描述”或“已有小脚本”转化为 NepTrainKit 的 Make Dataset 卡片实现或维护现有卡片。适用于新增、迁移、重构 Make Dataset 卡片时，按 Operation/Params 架构拆分 core 业务逻辑与 PySide UI，完成卡片注册、参数序列化、文档、测试和 `tools/docs/audit_card_docs.py` 检查。
+---
+
+# Make Dataset Card Dev
+
+## 目标
+
+把需求文本、已有脚本或现有卡片重构需求稳定转换为可交付卡片：
+
+1. 业务逻辑在 `src/NepTrainKit/core/cards/`，不依赖 PySide、qfluentwidgets 或 MessageManager。
+2. UI 只负责控件、参数读写、序列化和调用 operation。
+3. `Params dataclass`、operation、UI、文档、测试保持同一套参数契约。
+4. 注册、在线文档路径、测试和文档审计闭环。
+
+## 协作规则
+
+先从需求本质确认卡片类型，再动代码。以下情况先和用户确认：
+
+1. 需求表述存在多种合理解读。
+2. 方案会改变已有行为、默认值或旧 JSON 兼容性。
+3. 需要引入新依赖、跨页改运行时框架，或影响已有工作流。
+4. 存在明显更短或更稳的实现路径。
+
+当存在更优路径时，先给出“当前方案 vs 替代方案”的简短对比（收益、代价、风险），由用户拍板后再实施。
+
+## 先判定卡片语义
+
+不要强行把所有卡片塞进同一个接口。先选 operation 类型：
+
+- `StructureOperation`: 单结构变换，签名为 `run_structure(structure, params) -> list[Atoms]`。
+- `DatasetOperation`: 全数据集过滤或排序，签名为 `run_dataset(dataset, params) -> list[Atoms]`。
+- `GeneratorOperation`: 无输入生成结构，签名为 `generate(params) -> list[Atoms]`。
+
+对应参数必须用 frozen dataclass 表达，例如 `FooParams`。UI 通过 `get_params()` 构造 dataclass，通过 `set_params(params)` 恢复控件。
+
+## 工作流
+
+### 1. 需求/脚本解析为卡片规格
+
+先产出一个“卡片规格草案”，至少包含：
+
+- `card_name`、`group`、`menu_icon`、`requires_input_dataset`
+- operation 类型：`StructureOperation` / `DatasetOperation` / `GeneratorOperation`
+- `Params dataclass` 字段清单：名称、类型、默认值、范围、是否必填
+- 处理逻辑摘要：输入对象 -> 输出结构列表
+- 随机性与 seed 策略
+- `Config_type` 标签策略
+
+如果是脚本输入，额外提取：
+
+- 脚本里的硬编码常量，改为 Params 字段和 UI 参数。
+- 文件 I/O 副作用，改为内存数据流；不要覆盖用户文件。
+- 随机数入口，明确是否暴露 `use_seed` 和 `seed`。
+
+### 2. 实现 core operation
+
+优先在已有模块里放置逻辑：
+
+- 晶格/结构变换：`core/cards/lattice.py` 或 `core/cards/structure.py`
+- 随机/组成/替换：`core/cards/alloy.py`
+- 缺陷/表面：`core/cards/defect.py`
+- 磁性：`core/cards/magnetism.py`
+- 数据集过滤：`core/cards/filter.py`
+
+实现规则：
+
+- operation 不导入 `PySide6`、`qfluentwidgets`、`MessageManager`。
+- 参数校验失败时抛出明确异常；UI 层负责展示错误。
+- 结构变换后使用 `append_config_tag(...)` 写入可追溯标签。
+- 不做静默物理替换、降级模型或伪成功返回；unsupported 就明确失败。
+- 若需要序列化 dataclass，用 `params_to_dict(params)`；tuple 字段在 UI `to_dict()` 中按文档契约转成 list。
+
+### 3. 实现 UI 卡片
+
+UI 类放在 `src/NepTrainKit/ui/views/_card/*.py`，遵循现有风格：
+
+- 新卡片默认继承 `MakeDataCard`。不要因为 operation 是 dataset 级别就新建 `FilterDataCard` 子类；当前 `FilterDataCard` 只保留给既有过滤卡的显示差异。
+- `init_ui()` 构建控件。
+- 数值参数用 `SpinBoxUnitInputFrame`，枚举用 `ComboBox`，开关用 `CheckBox` / `RadioButton`，字符串用 `LineEdit`。
+- 提供 `create_operation()`、`get_params()`、`set_params(params)`。
+- 所有卡片禁止覆盖 `run()`：基类 `MakeDataCard.run()` 已根据 `create_operation()` 返回的 operation 类型自动分发到正确线程。
+- `process_structure()` 若保留，只能作为兼容委托层。结构卡调用 `run_structure(...)`；dataset/generator 卡片不要新增伪 `process_structure()` 通路。
+- 生成型卡片使用 `GeneratorOperation` 和 `requires_input_dataset = False`。
+
+### 4. 完成序列化
+
+绑定必须完整：
+
+- `to_dict()` 写入 `"params": params_to_dict(self.get_params())`。
+- 保留必要的旧 key，保证旧 JSON 可加载。旧 key 双写是过渡态；新增持久化格式时再引入版本字段清理。
+- `from_dict()` 优先读 `params`，没有时按旧 key 构造 Params，再调用 `set_params(params)`。
+- 文档里的 `serialized_keys`、默认值和运行时 `to_dict()` 一致。
+
+### 5. 注册、文档和在线路径
+
+- 类上加 `@CardManager.register_card`。
+- 在 `src/NepTrainKit/ui/views/_card/__init__.py` 导入并加入 `__all__`。
+- 每张内置卡片必须有对应文档：
+  - 源码：`src/NepTrainKit/ui/views/_card/foo_bar_card.py`
+  - 文档：`docs/source/module/make-dataset-cards/cards/foo-bar-card.md`
+  - 在线链接：`https://neptrainkit.readthedocs.io/en/latest/module/make-dataset-cards/cards/foo-bar-card.html`
+
+**文档写作核心原则：从训练集诊断出发。**
+
+操作示例必须回答"模型哪里不行 → 训练集缺什么 → 这张卡怎么补 → 怎么验证改善"，而不是只写"设参数→得结果"。禁止以下内容：
+
+- 模板填充句："先用默认值跑小样本；只有当你能明确说明它会改变当前结果分布时再偏离"
+- 同义反复开关建议："需要启用 XXX 时开启 / 希望保持默认时关闭"
+- 把 `params`（序列化实现细节）作为用户参数列出
+- 三档预设 JSON 几乎一样（Safe/Balanced/Aggressive 应有实质性参数差异）
+
+详细规范见 `docs/source/module/make-dataset-cards/writing-guide.md`。
+
+参数文档必须按 `Params dataclass` 字段逐项落标题：无功能组时使用 `### 参数名（key）`，有功能组时使用 `### 功能组` + `#### 参数名（key）`。不要把多个 key 合在一个标题里；枚举表必须写真实选项，不能写“以 UI 下拉项为准”；物理直觉不能用可套在任何参数上的模板句。`tools/docs/audit_card_docs.py` 会按这一契约检查。
+
+### 6. 测试
+
+最少覆盖：
+
+- operation 可脱离 UI 直接运行，不需要 `QApplication` 或 Qt 控件。
+- UI `get_params()` / `set_params()` / `to_dict()` / `from_dict()` 往返一致。
+- 关键参数生效。
+- 文档审计通过。
+
+新建或实质修改卡片时，测试不能只验证“不报错”。必须在 `tests/cards/` 对应领域文件中覆盖该卡片的核心输出语义：
+
+- 每个用户可选模式、关键参数分支和随机 seed 策略都要有代表性用例。
+- 边界条件和非法参数要验证明确失败原因，不做静默降级或伪成功。
+- 输出结构要检查可决策结果，例如数量、元素组成、cell/position/magmom 变化、过滤保留/剔除集合、`Config_type` 追踪标签。
+- 随机型卡片要验证固定 seed 的可复现性；没有 seed 的随机分布只检查物理/几何约束，不写脆弱的逐坐标快照。
+- dataset/generator 卡片要直接测 `run_dataset(...)` 或 `generate(...)` 的输入输出契约；UI 往返测试只验证参数绑定，不能替代 operation 行为测试。
+
+## 验证
+
+从仓库根目录运行 `python skills/make-dataset-card-dev/scripts/run_card_checks.py --quick`。更多模式见 `references/validation-playbook.md`。
+
+## 交付格式
+
+执行此 skill 时，输出按以下结构组织：
+
+1. 卡片规格摘要
+2. 实现清单
+3. 验证结果
+4. 未覆盖风险
+
+## 质量门槛
+
+- core operation 与 UI 解耦。
+- UI 参数、Params dataclass、文档默认值一一对应。
+- 没有“UI 有参数但逻辑没用”的死参数。
+- 没有“逻辑硬编码但 UI 没暴露”的隐含参数。
+- `to_dict` / `from_dict` 无丢字段和错类型。
+- `tools/docs/audit_card_docs.py` 和相关 pytest 通过。
+
+## Resources
+
+### references/
+
+- `references/card-touchpoints.md`：代码/文档/测试触点。
+- `references/validation-playbook.md`：验证与排错路径。
+- `references/requirements-to-card-spec-template.md`：把需求/脚本先落成实现规格。
+
+### scripts/
+
+- `scripts/run_card_checks.py`：统一执行交付检查，并包含 operation 架构审计。

neptrainkit-2.8.4/skills/make-dataset-card-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Make Dataset Card Dev"
+  short_description: "按 Operation 架构开发 NepTrainKit Make Dataset 卡片"
+  default_prompt: "根据需求描述、脚本或现有卡片，按 Params dataclass + core Operation + UI 绑定的架构实现或重构 Make Dataset 卡片，并补齐文档和测试。"

neptrainkit-2.8.4/skills/make-dataset-card-dev/references/card-touchpoints.md

@@ -0,0 +1,38 @@
+# Card Touchpoints
+
+Use this map to edit only what is needed.
+
+## Core code paths
+
+- `src/NepTrainKit/core/cards/operation.py`: `StructureOperation`, `DatasetOperation`, `GeneratorOperation`, and `params_to_dict`.
+- `src/NepTrainKit/core/cards/*.py`: UI-independent Params dataclasses and operation implementations.
+- `src/NepTrainKit/ui/views/_card/*.py`: PySide card UI, parameter binding, serialization, and operation delegation.
+- `src/NepTrainKit/ui/views/_card/__init__.py`: card imports and exports.
+- `src/NepTrainKit/core/card_manager.py`: registration mechanics.
+- `src/NepTrainKit/ui/widgets/card_widget.py`: base `MakeDataCard` operation dispatch.
+- `src/NepTrainKit/ui/threads.py`: operation execution threads.
+- `src/NepTrainKit/ui/pages/makedata.py`: workflow runtime integration.
+
+## Docs paths
+
+- `docs/source/module/make-dataset-cards/cards/*.md`: per-card docs.
+- `docs/source/module/make-dataset-cards/writing-guide.md`: **authoritative doc style reference.** Read before writing any card doc.
+- `tools/docs/audit_card_docs.py`: minimal integrity check (key consistency, code-doc defaults match). Does NOT enforce style — style is enforced by the writing guide.
+- `skills/make-dataset-card-dev/references/requirements-to-card-spec-template.md`: pre-coding card spec template.
+
+## Tests to touch first
+
+- `tests/test_makedata_source_card.py`: source-card execution in MakeData page.
+- `tests/cards/`: operation, card transformation, and serialization tests grouped by card domain.
+- Operation tests should avoid Qt setup: call `Operation().run_structure(atoms, Params(...))`, `run_dataset(...)`, or `generate(...)` directly.
+
+## CI references
+
+- `.github/workflows/pytest.yml`: local checks expected by CI.
+
+## Architecture audit
+
+- Built-in `MakeDataCard` and `FilterDataCard` subclasses should provide `create_operation()`.
+- Structure cards use `StructureOperation`; dataset filters use `DatasetOperation`; no-input generators use `GeneratorOperation`.
+- `src/NepTrainKit/core/cards/*.py` must not import `PySide6`, `qfluentwidgets`, or `MessageManager`.
+- Built-in cards should not override `run()`; dispatch belongs in `MakeDataCard.run()`.

neptrainkit-2.8.4/skills/make-dataset-card-dev/references/requirements-to-card-spec-template.md

@@ -0,0 +1,84 @@
+# 需求/脚本到卡片规格模板
+
+按下面模板先产出规格，再写代码。
+
+## 1. 输入信息
+
+- 输入类型：需求描述 / 小脚本 / 现有卡片迁移
+- 原始输入摘要：
+- 目标数据处理动作：
+
+## 2. 卡片基础定义
+
+- 类名：
+- `card_name`：
+- `group`：
+- `menu_icon`：
+- `requires_input_dataset`：
+- Operation 类型：`StructureOperation` / `DatasetOperation` / `GeneratorOperation`
+- Core 模块：`lattice.py` / `structure.py` / `alloy.py` / `defect.py` / `magnetism.py` / `filter.py`
+
+## 3. 操作示例（先写这个）
+
+在写代码前先把操作示例定下来。必须从训练集诊断出发：
+
+- **模型故障现象：** 模型在什么任务上、什么指标变差了
+- **根因诊断：** 训练集缺了什么数据导致这个问题
+- **输入结构：** 具体是什么输入
+- **预期改善：** 加入这批数据后，重训模型应该看到什么变化
+- **参数设置：** 解决这个问题大概需要什么参数/量级
+- **验证方法：** 怎么判断训练集质量确实改善了
+
+## 4. 参数设计（Params + UI）
+
+对每个参数填写：
+
+- 参数名（代码 key）：
+- Params 字段类型：
+- UI 控件类型（SpinBoxUnitInputFrame / ComboBox / CheckBox / LineEdit）：
+- 类型与范围：
+- 默认值：
+- 使用建议（场景 + 量级，不要泛化模板句）：
+- 参数联动 / 生效条件（仅在条件生效时写）：
+
+## 4. 业务逻辑设计
+
+- Operation 方法：`run_structure(structure, params)` / `run_dataset(dataset, params)` / `generate(params)`
+- 输入对象：
+- 输出对象：`list[ase.Atoms]`
+- 核心算法步骤（3-8 条）：
+- 随机性与 seed 策略：
+- 异常处理策略（core 抛异常，UI 展示错误）：
+- `Config_type` 标签策略：
+
+## 5. 绑定与序列化
+
+- 哪些 UI 字段参与运行时逻辑：
+- `create_operation()` 返回什么：
+- `get_params()` 如何从 UI 构造 Params：
+- `set_params(params)` 如何恢复 UI：
+- `to_dict` 字段清单：
+- 是否写入 `"params"`：
+- `from_dict` 默认值与兼容策略：
+- 如果 `process_structure()` 存在，是否只做兼容委托：
+  - Structure: `return self.create_operation().run_structure(structure, self.get_params())`
+  - Dataset / Generator: 不新增伪 `process_structure()` 通路
+- 是否覆盖 `run()`：必须为否
+
+## 6. 接入与验证
+
+- 注册改动：
+- 文档改动：
+- 测试改动：
+- operation 直接测试：
+- UI 参数往返测试：
+- 验证命令：
+
+## 7. 评审检查点
+
+- core operation 是否完全不依赖 UI？
+- UI 是否只委托 operation，而不是实现算法？
+- 是否存在“UI 有参数但逻辑没用”的死参数？
+- 是否存在“逻辑有硬编码但 UI 没暴露”的隐含参数？
+- 参数名/默认值在代码和文档是否一致？
+- 老配置 JSON 能否安全加载？

neptrainkit-2.8.4/skills/make-dataset-card-dev/references/validation-playbook.md

@@ -0,0 +1,79 @@
+# Validation Playbook
+
+Run from repo root.
+
+## Quick path (default)
+
+```bash
+python skills/make-dataset-card-dev/scripts/run_card_checks.py --quick
+```
+
+Runs:
+
+- operation architecture audit
+- `pytest tests/test_makedata_source_card.py tests/cards -q`
+- `python tools/docs/audit_card_docs.py`
+
+## Include docs build
+
+```bash
+python skills/make-dataset-card-dev/scripts/run_card_checks.py --with-docs
+```
+
+Adds:
+
+- `python -m sphinx -W -b html docs/source docs/build/html`
+
+## Full regression path
+
+```bash
+python skills/make-dataset-card-dev/scripts/run_card_checks.py --full
+```
+
+Runs:
+
+- operation architecture audit
+- `pytest tests/`
+- `python tools/docs/audit_card_docs.py`
+- `python -m sphinx -W -b html docs/source docs/build/html`
+
+## Card generation benchmark
+
+Use this when a new or changed card may be slow:
+
+```bash
+python tools/benchmark_card_operations.py
+```
+
+This benchmarks structure-generating operations directly, without Qt UI startup. It also runs lightweight semantic checks on every scenario, so a faster path must still generate the expected output shape, tags, composition, geometry, or magnetic moments. Useful filters:
+
+```bash
+python tools/benchmark_card_operations.py --only spin --repeat 5
+python tools/benchmark_card_operations.py --profile count50
+python tools/benchmark_card_operations.py --only slab --json card_bench.json
+```
+
+## Triage order
+
+1. Fix operation architecture violations first; do not leave core logic in UI cards.
+2. Fix code/runtime errors from pytest.
+3. Fix schema/section mismatches reported by `audit_card_docs.py`.
+4. Fix docs warnings or broken references from Sphinx.
+
+## New card test bar
+
+When adding a card, update `tests/cards/` in the domain file that matches the card. The test must prove the card behavior, not only that execution finishes:
+
+- cover each public mode and key parameter branch;
+- cover invalid or boundary params with explicit errors;
+- assert output semantics such as structure count, composition, cell/position/magmom changes, dataset filter decisions, generated tags, and `Config_type`;
+- cover deterministic seed behavior for random operations;
+- keep UI round-trip tests focused on parameter binding and serialization; operation behavior belongs in direct operation tests.
+
+## Operation architecture audit
+
+The validation script checks:
+
+- every built-in `MakeDataCard` / `FilterDataCard` subclass has `create_operation()`;
+- no built-in card has a custom `run()` unless the architecture is explicitly changed;
+- `src/NepTrainKit/core/cards/*.py` does not import `PySide6`, `qfluentwidgets`, or `MessageManager`.

neptrainkit-2.8.4/skills/make-dataset-card-dev/scripts/run_card_checks.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+"""Run focused validation checks for Make Dataset card development."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_repo_root(start: Path) -> Path:
+    """Return the nearest parent containing pyproject.toml."""
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    raise FileNotFoundError("Could not locate repo root (pyproject.toml not found).")
+
+
+def audit_operation_architecture(repo_root: Path) -> int:
+    """Check Make Dataset cards follow the core operation architecture."""
+    import ast
+
+    errors: list[str] = []
+    card_dir = repo_root / "src" / "NepTrainKit" / "ui" / "views" / "_card"
+    core_cards_dir = repo_root / "src" / "NepTrainKit" / "core" / "cards"
+
+    for path in sorted(card_dir.glob("*.py")):
+        if path.name == "__init__.py":
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
+        for node in tree.body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+            bases = []
+            for base in node.bases:
+                if isinstance(base, ast.Name):
+                    bases.append(base.id)
+                elif isinstance(base, ast.Attribute):
+                    bases.append(base.attr)
+            if not any(base in {"MakeDataCard", "FilterDataCard"} for base in bases):
+                continue
+
+            methods = {item.name for item in node.body if isinstance(item, ast.FunctionDef)}
+            if "create_operation" not in methods:
+                errors.append(f"{path.relative_to(repo_root)}:{node.name} missing create_operation()")
+            if "run" in methods:
+                errors.append(f"{path.relative_to(repo_root)}:{node.name} defines custom run()")
+
+    forbidden_modules = ("PySide6", "qfluentwidgets")
+    forbidden_names = {"MessageManager"}
+    for path in sorted(core_cards_dir.glob("*.py")):
+        tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    root_name = alias.name.split(".", 1)[0]
+                    if root_name in forbidden_modules or alias.name in forbidden_names:
+                        errors.append(f"{path.relative_to(repo_root)} imports UI dependency {alias.name}")
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                root_name = module.split(".", 1)[0]
+                if root_name in forbidden_modules:
+                    errors.append(f"{path.relative_to(repo_root)} imports UI dependency {module}")
+                for alias in node.names:
+                    if alias.name in forbidden_names:
+                        source = module or "."
+                        errors.append(f"{path.relative_to(repo_root)} imports UI dependency {source}.{alias.name}")
+
+    if errors:
+        print("[fail] operation architecture audit failed")
+        for error in errors:
+            print(f"  - {error}")
+        return 1
+
+    print("[ok] operation architecture audit passed")
+    return 0
+
+
+def run_commands(commands: list[list[str]], cwd: Path) -> int:
+    """Run commands sequentially and stop at first failure."""
+    audit_result = audit_operation_architecture(cwd)
+    if audit_result != 0:
+        return audit_result
+    env = os.environ.copy()
+    src_path = str(cwd / "src")
+    env["PYTHONPATH"] = src_path if not env.get("PYTHONPATH") else src_path + os.pathsep + env["PYTHONPATH"]
+    for cmd in commands:
+        print(f"[run] {' '.join(cmd)}")
+        result = subprocess.run(cmd, cwd=cwd, env=env)
+        if result.returncode != 0:
+            print(f"[fail] exit code {result.returncode}")
+            return result.returncode
+    print("[ok] all checks passed")
+    return 0
+
+
+def build_commands(full: bool, with_docs: bool) -> list[list[str]]:
+    """Build command list based on mode flags."""
+    py = sys.executable
+    if full:
+        return [
+            [py, "-m", "pytest", "tests/"],
+            [py, "tools/docs/audit_card_docs.py"],
+            [py, "-m", "sphinx", "-W", "-b", "html", "docs/source", "docs/build/html"],
+        ]
+
+    commands: list[list[str]] = [
+        [py, "-m", "pytest", "tests/test_makedata_source_card.py", "tests/cards", "-q"],
+        [py, "tools/docs/audit_card_docs.py"],
+    ]
+    if with_docs:
+        commands.append([py, "-m", "sphinx", "-W", "-b", "html", "docs/source", "docs/build/html"])
+    return commands
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--quick",
+        action="store_true",
+        help="Run focused tests and doc audit (default mode if no flags provided).",
+    )
+    parser.add_argument(
+        "--with-docs",
+        action="store_true",
+        help="Include Sphinx docs build in quick mode.",
+    )
+    parser.add_argument(
+        "--full",
+        action="store_true",
+        help="Run full test suite plus docs audit and docs build.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print commands without executing them.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.full and args.quick:
+        print("Choose either --full or --quick, not both.")
+        return 2
+
+    script_path = Path(__file__).resolve()
+    repo_root = find_repo_root(script_path.parent)
+    commands = build_commands(full=args.full, with_docs=args.with_docs)
+
+    if args.dry_run:
+        print(f"[info] repo root: {repo_root}")
+        print("[dry-run] operation architecture audit")
+        for cmd in commands:
+            print(f"[dry-run] {' '.join(cmd)}")
+        return 0
+
+    return run_commands(commands, cwd=repo_root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

neptrainkit-2.8.4/src/NepTrainKit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.8.4'
+__version_tuple__ = version_tuple = (2, 8, 4)
+
+__commit_id__ = commit_id = 'g6a1cf180c'

{neptrainkit-2.8.3.dev0 → neptrainkit-2.8.4}/src/NepTrainKit/core/__init__.py

@@ -19,10 +19,10 @@ from typing import Any
 
 __all__ = [
     'MessageManager',
-    'CardManager', 'load_cards_from_directory',
+    'CardManager', 'CardContributor', 'CardMetadata', 'load_cards_from_directory',
 ]
 
-from .card_manager import CardManager, load_cards_from_directory
+from .card_manager import CardContributor, CardManager, CardMetadata, load_cards_from_directory
 from .message import MessageManager
 
 # 可选：通过环境变量 NEP_NATIVE_STDIO 控制原生 stdout/stderr 重定向