dsh-runnpu 0.1.0

package/training-mode/preset/skills/swanlab-skill/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: swanlab-skill
+metadata:
+  version: "0.3.0"
+description: >
+  Interact with SwanLab — both writing tracking code (init/log/finish/multimedia) and querying
+  experiment data via CLI (`swanlab api`). Use this skill when the user wants to write training
+  tracking code, log metrics or media, manage experiments, inspect metrics/logs/keys, list
+  projects/runs, filter experiments, manage self-hosted users, automate queries via CLI, or
+  mentions "swanlab", "experiment tracking", "log metrics", "swanlab api", "swanlab cli".
+---
+
+# SwanLab Skill
+
+SwanLab is an AI training experiment tracking platform. This skill covers two usage patterns:
+
+- **Writing tracking code** — use the Python SDK (`swanlab.init`, `swanlab.log`, `swanlab.finish`, media helpers)
+- **Reading experiment data** — use the `swanlab api` CLI to query metrics, logs, summaries, media, etc.
+
+---
+
+## Reference Routing
+
+| If the user wants to...                                                | Read this reference              |
+| ---------------------------------------------------------------------- | -------------------------------- |
+| Write tracking code (init/log/finish/media)                            | `references/SDK_QUICKSTART.md`   |
+| Query data via CLI (metrics/summary/logs/filter/etc.)                  | `references/CLI_REFERENCE.md`    |
+| Understand data model / terminology / filter syntax                    | `references/SWANLAB_CONCEPTS.md` |
+| Analyze runs/projects, compare experiments, write an experiment report | `references/ANALYSIS_GUIDE.md`   |
+| Plot metrics or compare experiments visually                           | See **Scripts** below            |
+
+> **Version note (SDK ≥ 0.9.0)**: use `swanlab api run series` to discover an experiment's metric keys. `run column` / `run columns` are deprecated since `0.9.0` and do not apply to multi-view experiments — only fall back to them when the installed SDK is `< 0.9.0`. See `CLI_REFERENCE.md > Version Applicability`.
+
+---
+
+## Run Modes
+
+`swanlab.init(mode=...)` controls where data goes:
+
+| Mode       | Local Storage  | Cloud Upload                           | Use Case                             |
+| ---------- | -------------- | -------------------------------------- | ------------------------------------ |
+| `online`   | Yes (protobuf) | Yes (Transport → HTTP)                 | Normal cloud usage. Requires login.  |
+| `local`    | Yes (protobuf) | No                                     | Air-gapped / no account needed.      |
+| `offline`  | Yes (protobuf) | No (syncable later via `swanlab sync`) | Save locally, upload to cloud later. |
+| `disabled` | No             | No                                     | Completely disable all logging.      |
+
+Default is `online` if logged in; otherwise an interactive prompt offers login, registration, or `offline`. In non-interactive environments without an API key, init raises an error instead of falling back.
+
+---
+
+## Scripts
+
+Two helper scripts are available for visualizing experiment data:
+
+### `scripts/plot_metrics.py` — Single Experiment Line Chart
+
+Trigger when the user wants to **visualize scalar metrics from one experiment** (e.g. "plot my loss curve", "show training metrics chart").
+
+```bash
+python scripts/plot_metrics.py username/project_name/run_id --keys loss,acc
+python scripts/plot_metrics.py user/proj/run1 -k loss -o loss_chart.png -s 500
+python scripts/plot_metrics.py --data metrics.json -k loss,acc -o chart.png   # from saved JSON
+```
+
+### `scripts/runs_benchmark.py` — Cross-Experiment Comparison
+
+Trigger when the user wants to **compare the same metric across multiple experiments** (e.g. "compare loss across runs", "benchmark these experiments").
+
+```bash
+python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 user/proj/run3 -k loss
+python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 -k loss --direction lower
+python scripts/runs_benchmark.py user/proj/run1 user/proj/run2 -k loss,acc --normalize
+python scripts/runs_benchmark.py --data benchmark_data.json -k loss              # from saved JSON
+```
+
+Both scripts require `swanlab login` (or `--api-key` / `--host` flags).
+
+---
+
+## Path Convention
+
+CLI commands use `username/project_name` (project) or `username/project_name/run_id` (experiment). See `SWANLAB_CONCEPTS.md > Path Convention` for details.
+
+---
+
+## Quick Disambiguation
+
+| User says...                                     | They probably mean...    | Route                                     |
+| ------------------------------------------------ | ------------------------ | ----------------------------------------- |
+| "track my training" / "log metrics"              | Write tracking code      | `SDK_QUICKSTART.md`                       |
+| "log images/audio/text"                          | Log media data           | `SDK_QUICKSTART.md`                       |
+| "my loss curve" / "experiment metrics"           | Query scalar data        | `CLI_REFERENCE.md > run metrics`          |
+| "filter experiments"                             | Query by conditions      | `CLI_REFERENCE.md > run filter`           |
+| "my experiments" / "list runs"                   | List experiments         | `CLI_REFERENCE.md > run list`             |
+| "compare runs visually"                          | Cross-experiment chart   | `scripts/runs_benchmark.py`               |
+| "plot metric chart"                              | Single-experiment chart  | `scripts/plot_metrics.py`                 |
+| "experiment config"                              | Hyperparameters          | `CLI_REFERENCE.md > run info`             |
+| "console output"                                 | Captured logs            | `CLI_REFERENCE.md > run logs`             |
+| "what metrics are tracked"                       | Metric keys              | `CLI_REFERENCE.md > run series`           |
+| "check connectivity" / "can I reach swanlab"     | Environment check        | `swanlab ping`                            |
+| "check login status" / "am I logged in"          | Verify credentials       | `swanlab verify`                          |
+| "project not found" / a query returns 404        | Wrong host (most likely) | `CLI_REFERENCE.md > Troubleshooting`      |
+| run fields / run list or run info response       | Run object schema        | `SWANLAB_CONCEPTS.md > Run Object Schema` |
+| "analyze this project/run" / "experiment report" | Analysis pipeline        | `ANALYSIS_GUIDE.md`                       |
+
+---
+
+## Environment Connectivity
+
+Before writing tracking code or running CLI queries, especially in `online` mode, run these two checks to confirm the environment is ready:
+
+### 1. `swanlab ping` — Test network reachability
+
+The fastest way to diagnose connectivity issues. Run it first when a user reports upload failures, login problems, or unknown mode fallbacks.
+
+```bash
+swanlab ping
+# Reports: API host, web host, latency, and login status.
+# If ping fails, check SWANLAB_API_HOST / network proxy / firewall settings.
+```
+
+### 2. `swanlab verify` — Validate login credentials
+
+After confirming the server is reachable, use `swanlab verify` to check that stored credentials are valid and have not expired. This reads the API key and host from the local `.netrc` file (created by `swanlab login`).
+
+```bash
+swanlab verify
+# Validates stored API key against the server.
+# Reports: which host (default https://swanlab.cn) and the logged-in username.
+# Fails if: not logged in, API key is invalid, or key has expired.
+
+swanlab verify --local
+# Check local login status (.swanlab in current directory) instead of the global one.
+```
+
+**Recommended pre-flight sequence**:
+
+1. `swanlab ping` → confirm the server is reachable
+2. `swanlab verify` → confirm credentials are valid, and **note which host you are logged into**
+3. **Confirm the target project lives on that host.** SwanLab has multiple independent instances (public `swanlab.cn` + self-hosted deployments) and credentials are per-instance — see `SWANLAB_CONCEPTS.md > Instances, Hosts & Credentials`. If the project is on another instance, pass `--host` / `--api-key` on every command (or export `SWANLAB_API_HOST` / `SWANLAB_API_KEY`). A `404 Not_Found` from `project info` / `run list` means **wrong host, not a missing project** — see `CLI_REFERENCE.md > Troubleshooting`.
+4. Proceed with `swanlab api` queries or SDK code
+
+---
+
+## Behavioral Constraints
+
+See `CLI_REFERENCE.md > Behavioral Constraints` for the full list. Key rules:
+
+- **Use `--all` only when the user explicitly asks for it** (e.g. "fetch all", "get everything", "complete list"). For paginated list commands, always use default pagination (`--page_num` / `--page_size`).
+- **Always ask for specific metric keys before running `run metrics` or `run medias`.** If the user doesn't know the key names, first run `run series PATH` to discover them (`run columns PATH` only as a fallback on SDK `< 0.9.0`).
+- **Always persist large metric data to file via `--save`**, then visualize with `scripts/plot_metrics.py --data file.json` or use `run summary` for aggregate stats.
+
+---
+
+## Further Reading
+
+This skill covers the most common SwanLab workflows for AI coding agents. For
+details that are out of scope here (full SDK surface, advanced CLI flags,
+self-hosted deployment, integrations, etc.), consult the official SwanLab
+documentation:
+
+- **Cloud guide (what is SwanLab, concepts, usage)**: https://docs.swanlab.cn/guide_cloud/general/what-is-swanlab.md
+- **Python SDK & OpenAPI reference**: https://docs.swanlab.cn/api/api-index.md

package/training-mode/preset/skills/swanlab-skill/VENDOR.txt

@@ -0,0 +1,9 @@
+vendored swanlab-skill v0.3.0 from https://github.com/SwanHubX/SwanLab-Skill (MIT)
+upstream commit: 6fa471b "Fix/env name (#9)" 2026-09-07 (synced 2026-09-13)
+LICENSE 来自上游仓库根目录。
+
+LOCAL PATCHES：无。
+v0.2.5 时期本地补过 SDK_QUICKSTART.md 的环境变量表（SWANLAB_NAME 已过时、SDK 0.9.8 实际读
+SWANLAB_EXP_NAME）；0.3.0 上游已改为 SWANLAB_EXPERIMENT_NAME 主名 + SWANLAB_EXP_NAME 旧别名
+（SDK ≥ 0.8.0，两者同设时主名优先），补丁作废。训练模式提交时三个名字都注入
+（shared/swanlab.mjs），与哪个 SDK 版本都对得上。

package/training-mode/preset/skills/swanlab-skill/references/ANALYSIS_GUIDE.md

@@ -0,0 +1,83 @@
+# Analysis Guide — Experiment Analysis Pipelines
+
+Workflow recipes for turning `swanlab api` queries into analysis or reports. Command syntax: `CLI_REFERENCE.md`. Response schemas: `SWANLAB_CONCEPTS.md`.
+
+| User says...                                               | Pipeline      |
+| ---------------------------------------------------------- | ------------- |
+| "analyze this run" / "why did it crash or diverge"         | Run-level     |
+| "analyze this project" / "write a report" / "compare runs" | Project-level |
+
+Pre-flight first: confirm host + credentials (`SKILL.md > Environment Connectivity`). A 404 on project-scoped queries means wrong host, not missing data.
+
+---
+
+## Run-Level Pipeline
+
+```
+run info → run series → branch by intent
+```
+
+1. **`run info PATH`** — what the run actually was.
+   - Hyperparameters: `profile.config.<key>.value` (nested `{value, desc, sort}`, not flat).
+   - Environment: `profile.metadata` (`command`, `git_info`, `gpu`, `swanlab.version`).
+   - Duration = `finished_at` − `created_at`.
+   - **Trust config over run name** — names are free-text and can contradict config.
+2. **`run series PATH`** — discover metric keys (`--class system` for hardware, `--type media` for media).
+3. **Branch by intent**:
+
+| Intent                                | Next step                                                   |
+| ------------------------------------- | ----------------------------------------------------------- |
+| Quick conclusion / final numbers      | `run summary` (latest + min/max/avg per key, one call)      |
+| Curve shape, convergence, overfitting | `run metrics --keys k1,k2 --save` → plot (see below)        |
+| State `CRASHED` / suspicious          | `run logs --level ERROR` first; bulk-read via `export-logs` |
+| A step range or tail                  | `run metrics` with `--range-start/--range-end/--range-tail` |
+| Logged images/audio/text              | `run medias --keys KEY --step N`                            |
+
+---
+
+## Project-Level Pipeline
+
+```
+run list → (optional) run filter → per-run info + summary → synthesize
+```
+
+1. **`run list PROJECT_PATH`** — inventory. Items embed the full `profile`; extract only `run_id` / `name` / `state` / `description` / timestamps with `jq`/`python` instead of dumping raw JSON.
+2. **`run filter`** (optional) — narrow the set first: by `state`, config dimension, metric threshold, or time range (`SWANLAB_CONCEPTS.md > Filter Query`).
+3. **Per-run `run info` + `run summary`** — loop over shortlisted `run_id`s into a table. Check exit codes and retry transient failures before parsing stdout.
+   - Summary gives only the latest value + aggregates. For per-key fine-grained analysis — trends, oscillation, when a metric peaked — also pull the time series: `run metrics PATH --keys KEY --save` per run, then compare curves or plot them (see Visualization). Don't rank runs on final values alone.
+4. **Synthesize** — group by config dimensions (model, dataset, lr, ...), rank by the target metric, cite run names/ids as evidence.
+
+### Analysis discipline
+
+- **Config is truth, names are labels.** Names are not unique and can drift from config; group and compare by config values.
+- **`description` often carries variant labels** — read it together with `name`.
+- **Watch for invalidated batches.** Mid-project pipeline fixes make older runs incomparable; time clusters and description markers reveal the boundary. Flag suspect batches, don't average them in.
+- **Single-run ablations are directional only.** Within-noise differences need repeated seeds before becoming conclusions.
+- **Check convergence before ranking.** If val `max ≈ last`, training hadn't saturated — note it instead of ranking undertrained runs.
+
+---
+
+## Visualization
+
+Charts are a pipeline step, not a separate task:
+
+| Scenario                  | Script                       |
+| ------------------------- | ---------------------------- |
+| One run, several keys     | `scripts/plot_metrics.py`    |
+| Same key across runs      | `scripts/runs_benchmark.py`  |
+| Unequal-length runs       | add `--normalize`            |
+| Only final numbers needed | no chart — use `run summary` |
+
+**Data bridge (no double-fetching)**: both scripts accept `--data FILE.json` and skip API calls:
+
+```bash
+swanlab api run metrics user/proj/RUN_ID --keys val/loss --save
+python scripts/plot_metrics.py --data swanlab-YYYYMMDD_HHMMSS-xxxx.json -k val/loss -o val_loss.png
+```
+
+**Benchmark path list from a project**: extract run ids from `run list` output and expand to `user/proj/<id>` paths, then pass them to `runs_benchmark.py`.
+
+Notes:
+
+- Scripts use the OOP `swanlab.api.Api`, which reuses the saved login state (`.netrc` / `SWANLAB_API_KEY`): no flags needed on the logged-in default instance; pass `--host` / `--api-key` only for other instances.
+- Scripts render static matplotlib images. For interactive ECharts needs, implement equivalent rendering over the same fetched JSON (from `run metrics --save` or the scripts' `--data` format); the data-acquisition half of `plot_metrics.py` is the reference to follow.