dsh-runnpu 0.1.0

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

@@ -0,0 +1,523 @@
+# SwanLab Concepts & Data Model
+
+Reference for understanding SwanLab's entity hierarchy, terminology, and data model. Read this when interpreting user requests or deciding which CLI command to use.
+
+---
+
+## Product Overview
+
+SwanLab is an AI training experiment tracking platform. The Python SDK records metrics, configs, media, console output, and hardware stats during training. Data is persisted locally and optionally synced to the SwanLab cloud (or self-hosted instance).
+
+The CLI (`swanlab api`) provides read-only query access to all tracked data from the command line.
+
+---
+
+## Instances, Hosts & Credentials
+
+SwanLab exists as multiple **independent instances**:
+
+- **Public cloud**: `https://swanlab.cn` (the default)
+- **Self-hosted instances**: private deployments on custom domains (e.g. `https://dev.example.com`)
+
+**Credentials are per-instance.** An API key issued on one instance is rejected by every other instance (`401 Unauthorized`). Being logged in to instance A grants no access to instance B.
+
+**A `404 Not_Found` from a project-scoped query (`project info`, `run list`, `run info`) almost always means you are querying the wrong host — not that the project is missing.** Before concluding a project doesn't exist (or paging through `project list` hunting for it), check the host reported by `swanlab verify` and re-issue the query against the correct instance with `--host` / `--api-key`.
+
+To work against an instance other than the logged-in one (without re-login), pass per-command overrides:
+
+```bash
+swanlab api run list user/project --host https://swanlab.cn --api-key <KEY>
+```
+
+For a stretch of commands against a non-default host, export `SWANLAB_API_HOST` / `SWANLAB_API_KEY` (see Key Environment Variables) once instead of repeating the flags — this also keeps the key out of repeated terminal echo.
+
+---
+
+## Core Entity Hierarchy
+
+```
+User (authenticated account)
++-- Workspace (personal or team namespace, identified by username)
+|   +-- Project (groups related experiments)
+|   |   +-- Experiment / Run (a single training execution)
+|   |   |   +-- Config (input hyperparameters, mutable during the run via `swanlab.config`)
+|   |   |   +-- Column (a metric definition — e.g. "loss", "acc", "image")
+|   |   |   |   +-- Scalar Metrics (time-series numeric data)
+|   |   |   |   +-- Media Metrics (images, audio, video, molecules, etc.)
+|   |   |   +-- Console Logs (captured stdout/stderr output)
+|   |   |   +-- Profile (metadata: config, requirements, conda, hardware)
+```
+
+### Entity Reference
+
+| Entity               | Identified by                         | Description                                                                                                      |
+| -------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **User**             | implicit (logged-in)                  | The authenticated account. Has `username`, `name`, `bio`, `email`, etc.                                          |
+| **Workspace**        | `username`                            | A personal or team namespace. Type is `PERSON` or `TEAM`. Every project belongs to a workspace.                  |
+| **Project**          | `username/project_name` (path)        | Groups related experiments. Has visibility (`PUBLIC` / `PRIVATE`), description, labels.                          |
+| **Experiment (Run)** | `username/project_name/run_id` (path) | The atomic unit — one execution of training code. Created by `swanlab.init()`. Has state, config, metrics, logs. |
+| **Column**           | `key` within an experiment            | A metric definition. Belongs to either `CUSTOM` (user-defined) or `SYSTEM` (auto-collected). Has a data type.    |
+| **Metric**           | queried via column key                | The actual time-series data for a column. Three categories: Scalar, Media, Log.                                  |
+
+---
+
+## Key Terminology
+
+### Experiment States
+
+An experiment (run) is always in one of these states:
+
+| State      | Meaning                                 |
+| ---------- | --------------------------------------- |
+| `RUNNING`  | Currently executing                     |
+| `FINISHED` | Completed successfully                  |
+| `CRASHED`  | Terminated due to an error              |
+| `ABORTED`  | Manually stopped by the user            |
+| `OFFLINE`  | Created in offline mode, not yet synced |
+
+### Column Classes
+
+| Class    | Description                                               |
+| -------- | --------------------------------------------------------- |
+| `CUSTOM` | User-defined metrics logged via `swanlab.log()` (default) |
+| `SYSTEM` | Auto-collected system metrics (CPU, GPU, memory, etc.)    |
+
+> **SDK ≥ 0.9.0**: metric keys are discovered via `swanlab api run series`, whose `--class` option takes the lowercase values `custom` / `system` mapping to these classes. The `column` / `columns` commands (and the data-type filters below) are deprecated for multi-view experiments.
+
+### Column Data Types
+
+| Type       | Category | Description                         |
+| ---------- | -------- | ----------------------------------- |
+| `FLOAT`    | Scalar   | Floating-point numeric values       |
+| `BOOLEAN`  | Scalar   | True/false values                   |
+| `STRING`   | Scalar   | Text values                         |
+| `IMAGE`    | Media    | Image files (PNG, JPG, etc.)        |
+| `AUDIO`    | Media    | Audio files                         |
+| `VIDEO`    | Media    | Video files                         |
+| `OBJECT3D` | Media    | 3D point cloud data (JSON)          |
+| `MOLECULE` | Media    | Biochemical molecule structures     |
+| `ECHARTS`  | Media    | Custom chart configurations (JS/TS) |
+| `TABLE`    | Media    | Tabular data                        |
+| `TEXT`     | Media    | Rich text content                   |
+
+### Project Visibility
+
+| Visibility | Description                                    |
+| ---------- | ---------------------------------------------- |
+| `PRIVATE`  | Only accessible to workspace members (default) |
+| `PUBLIC`   | Visible to anyone                              |
+
+---
+
+## Path Convention
+
+The SwanLab API uses a hierarchical path format to address entities:
+
+```
+username                        → Workspace
+username/project_name           → Project
+username/project_name/run_id    → Experiment
+```
+
+- `username`: The workspace's unique identifier.
+- `project_name`: Human-readable project name (1-100 chars, `0-9a-zA-Z-_.+`).
+- `run_id`: A unique identifier for each experiment. Auto-generated as a short experiment_id/run_id by default, not acutally CUID, or user-supplied custom ID (1–512 chars, no `<>:"/\|?*#%` or control chars).
+
+---
+
+## Run Object Schema (`run list` / `run info`)
+
+`run list` and `run info` return the same run-object shape — `run list` wraps it in pagination (`data.list[]` plus `data.total` / `data.page` / `data.size` / `data.pages`), `run info` returns a single object in `data`. **All field names are snake_case.**
+
+| Field                         | Description                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| `run_id`                      | Unique experiment identifier — use this in `username/project_name/run_id` paths       |
+| `name`                        | Display name. Free-text, **not necessarily unique** (several runs may share one name) |
+| `state`                       | `RUNNING` / `FINISHED` / `CRASHED` / `ABORTED` / `OFFLINE`                            |
+| `description`                 | Free-text description — often used for variant/ablation labels                        |
+| `created_at` / `finished_at`  | ISO 8601 UTC timestamps. The difference is the run's wall-clock duration              |
+| `created_at_ts`               | `created_at` as Unix seconds                                                          |
+| `group` / `job_type`          | Experiment group / distributed job type (empty when unused)                           |
+| `labels`                      | Tag list attached to the run                                                          |
+| `show`                        | Whether the run is visible in the UI                                                  |
+| `type`                        | Run type (e.g. `CHAPTER`)                                                             |
+| `url`                         | Full web URL of the run's chart page                                                  |
+| `user`                        | Owner object: `{username, name, avatar, status}`                                      |
+| `project_id`                  | Internal project id                                                                   |
+| `root_exp_id` / `root_pro_id` | Resume-chain ids (empty when the run was not resumed)                                 |
+| `profile`                     | Config + environment profile — see Experiment Profile below                           |
+
+> **Note**: `run list` embeds the **full `profile`** (including the bulky `requirements` / `conda` strings) in every item, so list responses can be hundreds of KB. Extract only the fields you need (pipe to `jq` / `python`) instead of dumping raw output into context.
+
+---
+
+## Three Metric Categories
+
+Understanding which metric type to query is critical for answering "where's my data?":
+
+### Scalar Metrics (e.g. loss, accuracy)
+
+Numeric time-series data logged at each training step.
+
+Structure per data point:
+
+```
+{
+  "index": 0,        // step number or custom x-axis value
+  "data": 0.523,     // the metric value (can be int, float, or "NaN"/"INF"/"-INF")
+  "timestamp": 1714368000  // Unix timestamp
+}
+```
+
+Full response structure (SDK `Experiment.metrics()` / CLI `run metrics`; CLI wraps it in `{"ok", "errmsg", "data"}`):
+
+```
+{
+  "keys": ["loss", "acc"],
+  "metricType": "SCALAR",
+  "list": [
+    {
+      "key": "loss",
+      "metrics": [ { "index": 0, "data": 0.523, "timestamp": 1714368000 }, ... ],
+      "min":    { "index": 12, "data": 0.498 },   // server-side statistics,
+      "max":    { "index": 0,  "data": 0.523 },   // each stat is a point object
+      "avg":    { "index": 0,  "data": 0.510 },   // whose "data" holds the stat value
+      "median": { "index": 0,  "data": 0.509 },
+      "latest": { "index": 99, "data": 0.501 }
+    }
+  ]
+}
+```
+
+**Statistics** are computed server-side per scalar column: `min`, `max`, `avg`, `median`, `latest` — read `data.list[<entry>].<stat>.data` for a quick aggregate without parsing all points. `stdDev` is **not** included here; it is only available via `run summary` (see Scalar Summary below).
+
+> **Tip**: When metric data is large, use `--save` to persist JSON to file, then visualize with `scripts/plot_metrics.py --data file.json -k loss`. For quick stats without full time-series, prefer `run summary`.
+
+**Sampling**: By default, `--sample 1500` returns downsampled data for visualization. Use `--all` to fetch all data points without sampling limit.
+
+**Range Query** (client-side CSV filtering): When you need only a subset of scalar data points, use range query options to download the full CSV and filter client-side:
+
+| Option          | Default | Description                                                                                                                                   |
+| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--range-type`  | `step`  | Filter axis: `step` (by step number) or `timestamp` (by Unix timestamp in **milliseconds**)                                                   |
+| `--range-start` | none    | Start value, inclusive (int ≥ 0)                                                                                                              |
+| `--range-end`   | none    | End value, inclusive (int ≥ 0)                                                                                                                |
+| `--range-head`  | none    | First N data points (int ≥ 1). Mutually exclusive with `--range-tail`                                                                         |
+| `--range-tail`  | none    | Last N data points (int ≥ 1). Mutually exclusive with `--range-head`                                                                          |
+| `--range-last`  | none    | Last N milliseconds of data (int > 0). Mutually exclusive with `--range-start`/`--range-end`. Can combine with `--range-head`/`--range-tail`. |
+
+- `--range-head` and `--range-tail` are mutually exclusive, acted as post-sampling.
+- `--range-last` is mutually exclusive with `--range-start`/`--range-end`.
+- `--range-head`/`--range-tail` can be combined with `--range-last` or `--range-start`/`--range-end`.
+- `--range-start` must be ≤ `--range-end`.
+- When `--range-type timestamp` is used, rows missing a timestamp column are skipped.
+- Range query bypasses the sampling API entirely — it streams and filters the CSV export directly. Statistics (min/max/avg/median/latest) come from a separate value-stats endpoint (fetched concurrently with the CSV export) and are **not** affected by the range filter.
+
+### Scalar Summary
+
+A lightweight aggregate view of scalar metrics, returning per-key statistics without the full time-series. Useful for comparing experiments at a glance.
+
+```
+Structure per key:
+{
+  "step": 222,        // last step number
+  "value": 0.523,     // last step value
+  "minMax": [0.1, 0.9],  // [min, max] across all steps
+  "min": {...},       // min scalar point
+  "max": {...},       // max scalar point
+  "avg": 0.45,        // average across all steps
+  "median": 0.44,     // median across all steps
+  "stdDev": 0.12      // standard deviation across all steps
+}
+```
+
+- `step` and `value` are from the **last** step.
+- `min`, `max`, `avg`, `median`, `stdDev` are aggregated across **all** steps.
+- If a value is `NaN`, `Inf`, or `-Inf`, it is returned as a **string**.
+- Omit `--keys` to query all scalar keys for the experiment.
+
+### Media Metrics (e.g. images, audio)
+
+File-based data stored per step. Each media item has a presigned download URL.
+
+```
+Structure:
+{
+  "steps": [0, 1, 2],           // available steps
+  "step": 0,                     // current step
+  "metrics": [
+    {
+      "index": 0,
+      "items": [
+        { "url": "https://..." }  // presigned download URL
+      ]
+    }
+  ]
+}
+```
+
+**Step-based**: Media is retrieved one step at a time by default (`--step N`). Use `--all` to fetch all steps.
+
+### Console Logs
+
+Captured stdout/stderr output from the training process.
+
+```
+Structure per log entry:
+{
+  "epoch": 0,            // shard index (logs are paginated by shards)
+  "level": "INFO",       // DEBUG | INFO | WARN | ERROR
+  "message": "Epoch 1/10",
+  "tag": "",             // optional tag
+  "timestamp": "..."     // ISO timestamp
+}
+```
+
+**Shard-based pagination**: Logs are fetched by `--offset` (shard index), not page number. Increase offset to get later shards.
+
+### Log Export
+
+Console logs can be bulk-exported as a downloadable `.log` file via a presigned URL. This is distinct from shard-based log viewing — export retrieves raw log rows by row index range.
+
+| Parameter | Default | Description                            |
+| --------- | ------- | -------------------------------------- |
+| `start`   | 0       | Start row index (0-based)              |
+| `rows`    | 500,000 | Number of rows to export (max 500,000) |
+
+The API returns a presigned download URL (`{"url": "https://..."}`) that is valid for a limited time. No file content is downloaded by the CLI — only the URL is returned.
+
+---
+
+## Experiment Profile
+
+Each experiment carries a `profile` object containing metadata about the run:
+
+```
+{
+  "config": { ... },           // Hyperparameters set at swanlab.init(config={...})
+  "metadata": { ... },         // Hardware & environment info (auto-collected)
+  "requirements": "...",       // pip requirements string
+  "conda": "..."               // conda environment YAML
+}
+```
+
+- **Config** = user inputs. Initialized at `swanlab.init(config={...})`; mutable during the run — `swanlab.config["k"] = v` / `.update()` take effect immediately and are uploaded.
+- **Metadata** = auto-collected system info (Python version, GPU model, OS, etc.).
+- **Requirements / Conda** = captured from the active Python environment.
+
+**Config entries are nested objects, not plain values.** Each config key maps to `{value, desc, sort}`:
+
+```
+{
+  "learning_rate": { "value": 0.0001, "desc": "", "sort": 0 },
+  "batch_size":    { "value": 512,    "desc": "", "sort": 1 },
+  ...
+}
+```
+
+Always read hyperparameters as `profile.config.<key>.value`. When analyzing runs, **trust config values over run names** — names are free-text and can drift out of sync with the actual config.
+
+**Metadata keys** (auto-collected): `os`, `cpu` (`{brand, cores}`), `gpu` (vendor-keyed, e.g. `nvidia: {type[], memory[], cores, cuda, driver}`), `memory`, `python`, `python_verbose`, `executable`, `command` (the training command line), `cwd`, `pid`, `hostname`, `git_info` (`[branch, commit]`), `git_remote`, `swanlab` (`{version, logdir, _monitor}`).
+
+> Metadata key names vary with the SDK version that recorded the run — the list above matches what existing experiments typically carry. Newer SDKs collect the same information under different names, e.g. `python_version` / `python_executable` instead of `python` / `executable`, a single `git` object (`{remote_url, branch, commit}`) instead of `git_info` / `git_remote`, and `swanlab.run_dir` instead of `swanlab.logdir`.
+
+---
+
+## Self-Hosted Instance
+
+> **Self-hosted commands are only available for self-hosted (private) deployments.** Only proceed with these commands when the resolved host points to a self-hosted deployment.
+
+SwanLab can be deployed as a self-hosted instance (private deployment). **Use `swanlab api self-hosted` subcommands exclusively on self-hosted deployments. Always verify the host points to a private server before invoking these commands.**
+
+**Host detection rule**: Before using any self-hosted command, check where requests will be sent:
+
+1. If the user passes `--host` explicitly → use that value.
+2. Otherwise, check `SWANLAB_API_HOST` / `SWANLAB_WEB_HOST` environment variables.
+3. Otherwise, check `.netrc` or SwanLab config (`~/.swanlab`).
+
+Self-hosted commands only succeed on self-hosted deployments. Always confirm the resolved host points to a private server before proceeding.
+
+Self-hosted-specific features:
+
+| Property  | Description                                |
+| --------- | ------------------------------------------ |
+| `enabled` | Whether this is a self-hosted deployment   |
+| `expired` | Whether the license has expired            |
+| `root`    | Whether the current user is a root (admin) |
+| `plan`    | License plan: `free` or `commercial`       |
+| `seats`   | Number of allowed user seats               |
+
+Management operations (create user, list users, list projects, list workspaces, summary) all require root privileges. If a non-root user attempts any of these, the API returns a permission error.
+
+### Instance-Level Management
+
+On a self-hosted deployment, the root (admin) user can query across the entire instance, not just within a single workspace:
+
+| Operation       | Root Required | Description                                                                                   |
+| --------------- | ------------- | --------------------------------------------------------------------------------------------- |
+| Create User     | Yes           | Add a new user to the instance                                                                |
+| List Users      | Yes           | All registered users across the instance                                                      |
+| List Projects   | Yes           | All projects across all workspaces, with optional filters for creator, workspace, and keyword |
+| List Workspaces | Yes           | All workspaces (personal + team) on the instance, with optional keyword search                |
+| Usage Summary   | Yes           | Aggregate statistics: total users, projects, experiments, storage, etc.                       |
+
+This differs from the regular `project list` / `workspace info` commands, which are scoped to a single workspace. Instance-level queries have a global view.
+
+### Quick Disambiguation (Self-Hosted)
+
+| User says...                 | They probably mean...           | CLI command                               |
+| ---------------------------- | ------------------------------- | ----------------------------------------- |
+| "all projects on the server" | Instance-wide project listing   | `swanlab api self-hosted list-projects`   |
+| "all workspaces"             | Instance-wide workspace listing | `swanlab api self-hosted list-workspaces` |
+| "server usage / disk usage"  | Usage summary                   | `swanlab api self-hosted summary`         |
+| "all users on the server"    | Instance-wide user listing      | `swanlab api self-hosted list-users`      |
+
+---
+
+---
+
+## Filter Query (Experiment Filtering)
+
+Experiments can be filtered by submitting a JSON array of filter objects to the runs/shows API. Each filter describes a condition on an experiment field.
+
+### Filter Object Structure
+
+Each filter object must contain four fields:
+
+```json
+{
+  "key": "state",
+  "type": "STABLE",
+  "op": "EQ",
+  "value": ["FINISHED"]
+}
+```
+
+| Field   | Type   | Required | Description                                   |
+| ------- | ------ | -------- | --------------------------------------------- |
+| `key`   | string | yes      | The field name to filter on                   |
+| `type`  | string | yes      | Sidebar type: `STABLE`, `CONFIG`, or `SCALAR` |
+| `op`    | string | yes      | Filter operator                               |
+| `value` | array  | yes      | Values to compare against (always a list)     |
+
+### Filter Types (`type`)
+
+| Type     | Description                                       | Valid Keys                                                                                                                                          |
+| -------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STABLE` | Built-in experiment fields (see table below)      | `state`, `name`, `description`, `show`, `pin`, `baseline`, `colors`, `cluster`, `job`, `createdAt`, `updatedAt`, `finishedAt`, `pinnedAt`, `labels` |
+| `CONFIG` | Hyperparameters from `swanlab.init(config={...})` | Any key from the config dict, e.g. `learning_rate`, `batch_size`                                                                                    |
+| `SCALAR` | Scalar metrics from `swanlab.log(...)`            | Any metric key, e.g. `train/loss`, `val/acc`                                                                                                        |
+
+### STABLE Keys
+
+| Key           | Type     | Description                                                              |
+| ------------- | -------- | ------------------------------------------------------------------------ |
+| `state`       | enum     | Experiment state: `RUNNING`, `FINISHED`, `CRASHED`, `ABORTED`, `OFFLINE` |
+| `name`        | string   | Experiment display name                                                  |
+| `description` | string   | Experiment description text                                              |
+| `show`        | boolean  | Whether the experiment is visible in the UI                              |
+| `pin`         | boolean  | Whether the experiment is pinned to the top                              |
+| `baseline`    | boolean  | Whether this experiment is marked as a baseline for comparison           |
+| `colors`      | string   | Assigned color identifier                                                |
+| `cluster`     | string   | Experiment group/cluster name                                            |
+| `job`         | string   | Distributed job type (e.g. `worker`, `master`)                           |
+| `createdAt`   | datetime | Time the experiment was created (UTC+8 on filter, UTC in response)       |
+| `updatedAt`   | datetime | Time the experiment was last updated (UTC+8 on filter, UTC in response)  |
+| `finishedAt`  | datetime | Time the experiment finished (UTC+8 on filter, UTC in response)          |
+| `pinnedAt`    | datetime | Time the experiment was pinned (UTC+8 on filter, UTC in response)        |
+| `labels`      | array    | Tags/labels attached to the experiment                                   |
+
+### Filter Operators (`op`)
+
+| Operator  | Meaning               | Notes                              |
+| --------- | --------------------- | ---------------------------------- |
+| `EQ`      | Equals                | Single value                       |
+| `NEQ`     | Not equals            | Single value                       |
+| `GTE`     | Greater than or equal | Numeric / date / string comparison |
+| `LTE`     | Less than or equal    | Numeric / date / string comparison |
+| `IN`      | In list               | Value is an array of options       |
+| `NOT IN`  | Not in list           | Value is an array of options       |
+| `CONTAIN` | Fuzzy contains        | Substring / partial match          |
+
+### Time Fields & Range Queries
+
+Time-type fields (`createdAt`, `updatedAt`, `finishedAt`, `pinnedAt`) are **range-queried** using `GTE` and `LTE` together to define a time interval.
+
+**Important timezone note:**
+
+- **Filter values** use **UTC+8** (Asia/Shanghai). Input times are interpreted as Beijing time.
+- **Response timestamps** are in **UTC**. The returned experiment fields (`createdAt`, `finishedAt`, etc.) are UTC ISO strings.
+
+To filter experiments within a time range, combine `GTE` and `LTE` filters on the same key:
+
+```json
+[
+  { "key": "createdAt", "type": "STABLE", "op": "GTE", "value": ["2026-01-01T00:00:00"] },
+  { "key": "createdAt", "type": "STABLE", "op": "LTE", "value": ["2026-04-29T23:59:59"] }
+]
+```
+
+- **Value format**: ISO 8601 string (e.g. `"2026-01-01T00:00:00"`). The server interprets filter values as UTC+8 and compares as date objects.
+- When reading results, remember the returned timestamps are UTC — they will be 8 hours behind the filter input times.
+
+### Operator Constraints
+
+- Array-type fields (e.g. `labels`) only support `EQ`, `NEQ`, `IN`, `NOT IN`, `CONTAIN`.
+- Date-type fields use range queries with `GTE`/`LTE` (see above).
+- Numeric fields prefer numeric comparison, falling back to string comparison.
+
+### Examples
+
+Filter by state:
+
+```json
+[{ "key": "state", "type": "STABLE", "op": "IN", "value": ["FINISHED", "RUNNING"] }]
+```
+
+Filter by config value:
+
+```json
+[{ "key": "learning_rate", "type": "CONFIG", "op": "EQ", "value": ["0.01"] }]
+```
+
+Filter by scalar metric:
+
+```json
+[{ "key": "train/loss", "type": "SCALAR", "op": "LTE", "value": ["0.5"] }]
+```
+
+Filter by time range (filter values in UTC+8, response in UTC):
+
+```json
+[{ "key": "finishedAt", "type": "STABLE", "op": "GTE", "value": ["2026-04-01T00:00:00"] }]
+```
+
+Multiple filters combined:
+
+```json
+[
+  { "key": "state", "type": "STABLE", "op": "EQ", "value": ["FINISHED"] },
+  { "key": "learning_rate", "type": "CONFIG", "op": "GTE", "value": ["0.001"] },
+  { "key": "train/loss", "type": "SCALAR", "op": "LTE", "value": ["0.5"] }
+]
+```
+
+---
+
+## Key Environment Variables
+
+| Variable           | Purpose                                           |
+| ------------------ | ------------------------------------------------- |
+| `SWANLAB_API_KEY`  | API authentication key                            |
+| `SWANLAB_API_HOST` | API server URL (default `https://api.swanlab.cn`) |
+| `SWANLAB_WEB_HOST` | Web dashboard URL (default `https://swanlab.cn`)  |
+| `SWANLAB_LOG_DIR`  | Custom local log directory (default `./swanlog`)  |
+| `SWANLAB_ROOT`     | Root dir for SwanLab files (default `~/.swanlab`) |
+
+> Legacy aliases still honored for backward compatibility: `SWANLAB_LOGDIR` → `SWANLAB_LOG_DIR`, `SWANLAB_SAVE_DIR` → `SWANLAB_ROOT`.
+
+---
+
+## Run Modes
+
+See `SKILL.md > Run Modes` for the mode table. CONCEPTS focuses on data model, not SDK configuration.