pyattacker 0.3.0__tar.gz → 0.3.2__tar.gz

{pyattacker-0.3.0 → pyattacker-0.3.2}/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.2] — 2026-09-21
+
+### Changed
+
+* **Handoffs and forward/backward jumps are supported public features.** `Handoff.to`,
+  `Handoff.end`, `Handoff.rewind`, `Handoff.retry_all` and their `control` declarations now
+  follow the project's regular versioning policy, without a separate experimental tier.
+  Code documentation and both language editions use this status consistently, including
+  the companion payload-history guide. Explicit declarations, finite backward budgets,
+  atomic store capabilities, execution semantics and persisted identities remain unchanged.
+  Documentation links use the new headings; legacy anchors preserve published bookmarks.
+  Earlier release entries below describe their status at the time of release.
+
+### Added
+
+* **Experiment suites** (#68): reference existing configurations and schedule their inputs
+  round-robin through one Runner with shared global concurrency and explicit local pool bindings.
+  Stable Suite/member identities preserve original local keys and isolate checkpoints and metrics.
+* Optional `by_experiment` output directories alongside default `combined` storage, with a
+  persistent catalog, source-exhaustion state, selective resume and bounded child connections.
+  Directory-aware report/watch/serve/export provide cumulative and durable invocation views,
+  preserving historical failures, skips and execution timing after resume. Recovery finalizes
+  abandoned catalog runs as interrupted, freezing their elapsed time. Unselected member
+  databases remain untouched. Pool environment placeholders allow credential rotation;
+  reopening validates the persisted artifact backend.
+* `export --rows results`, `--by-experiment`, member-scoped reported metrics, and task context
+  experiment/output-directory fields. Split export filenames follow the selected row kind.
+  Single-store exports atomically replace completed files; admitted specs repair migrated repeats.
+* English and Chinese Suite guides and a runnable JSON example. Existing standalone path/ID
+  semantics remain unchanged; Suite mode explicitly rejects independent process shards/custom stores.
+
+## [0.3.1] — 2026-09-19
+
+### Added
+
+* **Application-reported live metrics.** `Runner.report_metric()` and `TaskContext.report_metric()`
+  publish latest values scoped to a run or pipeline. Applications can observe committed pipeline
+  completions with `on_pipeline_finished(runner, record, artifact)` and compute their own accuracy or
+  other cross-pipeline measures. SQLite and in-memory stores persist the reports; `/metrics`, the HTML
+  dashboard, and terminal `watch` display them. See `examples/live_metrics.py` for a restart-aware
+  accuracy monitor. Metric calculation remains application-owned.
+
+### Fixed
+
+* **Consistent monitoring scope.** With no explicit run ID, the dashboard, JSON endpoints and terminal
+  `watch` all select the latest started run. The dashboard uses that same ID for statistics, metrics,
+  pipelines and events, including when only pipeline-scoped values were reported. `run_id=all` requests
+  aggregate operational statistics without mixing in a single run's application metrics.
+
 ## [0.3.0] — 2026-09-19
 
 ### Added
@@ -27,7 +78,7 @@ All notable changes to this project are documented here. The format follows
   keeps the append-only history, and a store that has committed its first revisit records a `base` → `visits-v1`
   feature level (`store.feature_level()`, `StoreFeatureUnsupported`) so lineage-unaware writers are refused
   rather than silently mutating the wrong occurrence. See
-  [reference → advanced: backward traversal](docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits).
+  [reference → advanced: backward traversal](docs/reference.md#backward-traversal-rewind-retry-all-visits).
 
 * **Advanced feature: handoffs — a task can skip ahead, on the record (opt-in, experimental).** A task may
   return `Handoff.to(target, value)` to continue at a declared later station, or `Handoff.end(value)` to
@@ -50,9 +101,9 @@ All notable changes to this project are documented here. The format follows
   commit them atomically; both built-in backends can, and a store that cannot is refused up front with a
   `ConfigError` rather than silently writing a non-durable jump. Marked *experimental until 1.0*;
   the forward declaration excludes backward targets; joins and cross-pipeline jumps are not included. See
-  [`docs/design.md` §4.8](docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental),
-  the [API reference](docs/reference.md#advanced-handoffs-opt-in) and
-  [tutorial step 15](docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
+  [`docs/design.md` §4.8](docs/design.md#48-handoffs--declared-forward-jumps-opt-in),
+  the [API reference](docs/reference.md#handoffs-opt-in) and
+  [tutorial step 15](docs/tutorial.md#step-15--skipping-stations-handoffs).
 
 ### Fixed
 
@@ -188,9 +239,9 @@ All notable changes to this project are documented here. The format follows
 
 * **The backward-traversal guide is merged into the tutorial and the reference.** `docs/backward.md` was a
   seventh document that a reader had to find before they could use the feature; its usage now lives where
-  the rest of the API does. [Tutorial step 16](docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all)
+  the rest of the API does. [Tutorial step 16](docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all)
   keeps the rewind/retry-all walkthrough and a new step 17 builds an optional `HistoryArtifact` payload,
-  while [reference → advanced: backward traversal](docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits)
+  while [reference → advanced: backward traversal](docs/reference.md#backward-traversal-rewind-retry-all-visits)
   gains the `Handoff.rewind`/`Handoff.retry_all` signatures, the backward `control` keys, the visit and
   occurrence model, the budget and recovery rules, and the inspection surface; `HistoryArtifact` is
   documented next to the codecs it belongs to, and the store capability and compatibility/backup rules moved

{pyattacker-0.3.0 → pyattacker-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyattacker
-Version: 0.3.0
+Version: 0.3.2
 Summary: Artifact-centric, resumable async task orchestration: pipeline / task / resource pool.
 Project-URL: Homepage, https://github.com/Hazer-BJTU/pyattacker
 Project-URL: Repository, https://github.com/Hazer-BJTU/pyattacker
@@ -93,7 +93,7 @@ Five concepts, and that is the whole vocabulary:
 | Concept | Meaning | In one line |
 |---|---|---|
 | **artifact** | the persisted state of a task | content-addressed, **persisted as soon as it is produced** → checkpoint granularity = task |
-| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([advanced](#advanced-handoffs-opt-in)) |
+| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([handoffs](#handoffs-opt-in)) |
 | **pipeline** | the unit of completion | `fetch \| ask \| judge \| metrics` chained linearly, semantically independent of each other |
 | **resource** | a leasable external capability | one endpoint / one key; once pooled, it can be published and subscribed to concurrency-safely |
 | **algorithm** | the policy for acquiring resources | `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`, `immediate` — orthogonal to "retry on failure" |
@@ -202,7 +202,7 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * Failed pipelines → continue from **the first task that produced no artifact**: **if task C died, only task C
   reruns when task B's checkpoint is durable**;
 * The seed artifact is persisted too → recovery **does not depend on the original dataset file**;
-* A pipeline that **handed off** ([advanced](#advanced-handoffs-opt-in)) resumes at the station it jumped to,
+* A pipeline that **handed off** ([handoffs](#handoffs-opt-in)) resumes at the station it jumped to,
   with the entry state the ledger recorded — the task that handed off is not re-run;
 * Changed a task's source code (`spec_digest` includes source digests) → treated as a new pipeline, so old
   results are not incorrectly reused. Factory parameters, fanout children, retry/algorithm policies and
@@ -213,10 +213,13 @@ rerun and old explicit keys conflict. Finish old runs with the old package, then
 [resume identity and idempotency reference](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#resume-identity)
 for migration guidance, dynamic functions and external configuration.
 
-## Advanced: Handoffs (Opt-In)
+<a id="advanced-handoffs-opt-in"></a>
 
-**Advanced tier: opt-in, changes the execution model, not needed for ordinary pipelines, experimental until
-1.0.** A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
+
+A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
 failure or hiding the branch inside one step. It **returns** a directive — `Handoff.to(target, value)` to
 continue at a declared later station, `Handoff.end(value)` to finish the pipeline right there:
 
@@ -284,8 +287,8 @@ with Runner(store=":memory:", concurrency=4) as runner:
 * **It is a durable checkpoint.** The jump is committed atomically (source task, attempt, entry artifact,
   ledger row and cursor together), so a killed process resumes **at the target** with the recorded entry
   state and does not re-run the source task. On a control-enabled pipeline `n_tasks_done` is a *position*,
-  not a progress count: skipped stations have no task rows. `report`/`watch` count commits in the selected
-  scope (one run when filtered, all history otherwise); `/pipelines.handoffs` counts active execution records and `handoffs_historical` counts all ledger
+  not a progress count: skipped stations have no task rows. `watch` counts commits in the selected
+  run by default (`--run-id all` selects all history); `/pipelines.handoffs` counts active execution records and `handoffs_historical` counts all ledger
   records. A resume can use an earlier run's active handoff while recording no new handoffs. Pipeline
   exports include ledger identity and the watermark to distinguish the scopes.
 * **Opt-in and inert.** Without the `control` block nothing changes — not one row, not one counter, and not a
@@ -296,16 +299,16 @@ with Runner(store=":memory:", concurrency=4) as runner:
   payloads provide explicit snapshots and restoration; ordinary dictionaries remain author-controlled.
   Visits and exact artifact occurrences retain history and make recovery safe. The APIs, budgets and
   recovery boundaries are in
-  [reference → advanced: backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits),
+  [reference → backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#backward-traversal-rewind-retry-all-visits),
   with working programs in
-  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all).
+  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all).
 
-The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-handoffs-opt-in)),
+The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#handoffs-opt-in)),
 one declaration — `control={"edges": {...}}` for forward jumps, `control.rewind` / `control.retry_all` /
 `control.max_handoffs` for backward traversal — and one optional store capability; a custom store that cannot
 commit a handoff atomically is refused up front instead of writing a jump that would not survive a crash.
-Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
-Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental).
+Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--skipping-stations-handoffs).
+Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-handoffs--declared-forward-jumps-opt-in).
 
 When a pipeline restarts from the seed, previous task rows and chain artifacts are reset atomically with the cursor/watermark;
 previous handoffs stay in its history but no longer act as
@@ -427,13 +430,15 @@ keeps everything in the store.
 
 ```bash
 uv run pyattacker serve runs/qa.db        # http://127.0.0.1:8787
-# /  dashboard   /stats  /events  /pipelines  /resources  /errors   (JSON)
+# /  dashboard   /stats  /metrics  /events  /pipelines  /resources  /errors   (JSON)
 ```
 
 It opens a fresh read-only connection per request, so it runs happily beside a live run. It has **no
 authentication** and binds to loopback: there is no artifact route, but it does expose what your run recorded —
 event `data` and stored error messages — so treat it as a debug view over your own data and do not put it on a
 public interface without your own proxy in front.
+Applications can publish live values with `runner.report_metric("accuracy", value, display="percent")`;
+the framework displays them without calculating the metric. See [`examples/live_metrics.py`](examples/live_metrics.py).
 
 **Branching inside a step** — `fanout(a, b)` runs several tasks on the same input concurrently and
 returns `{task_name: value}`. Retry granularity becomes the group, which is the honest price of not
@@ -474,8 +479,8 @@ what they do not say.
 
 | Document | What is in it |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation and the advanced handoff/backward tiers — rewinds, retry-all and payload history included; each one executed by the test suite |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including the advanced backward-traversal tier and `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation, handoffs and backward traversal — rewinds, retry-all and payload history included; each one executed by the test suite |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including backward traversal and `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md) | every subcommand, every flag, exit codes, config reference |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) | conceptual model, the six invariants, the lease contract, data model, tradeoffs |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/benchmark.md) | the algorithm benchmark: what the scenarios assume, what the metrics mean, how to read the table |
@@ -508,7 +513,7 @@ These are design decisions, not missing features:
 * **Semantic reduction** — accuracy, pass@k, F1 and any cross-pipeline aggregation. Export the artifacts and
   compute it outside, or write a sink pipeline out of the primitives.
 * **DAG orchestration** — a pipeline is a linear chain; branch inside a task with `fanout`. The one
-  qualification is the opt-in [handoff](#advanced-handoffs-opt-in): it changes the traversal of
+  qualification is the opt-in [handoff](#handoffs-opt-in): it changes the traversal of
   the chain along declared edges, never its topology (no joins, no second entry point, no cross-pipeline
   jumps).
 * **A serving gateway** — the only HTTP surface is the read-only debug endpoint above.
@@ -519,11 +524,25 @@ every known tradeoff with its reason.
 
 ## Status
 
-**0.3.0 — advanced control flow (opt-in), and the documentation in Chinese.** Tasks can now
-[hand off](#advanced-handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
+**0.3.2 — experiment suites and supported control flow.** Independent experiments can share resource
+pools and global concurrency, with unified run/resume/report commands and optional per-experiment output
+directories. Durable run histories preserve earlier outcomes after resume. Handoffs, forward jumps,
+rewinds and retry-all are supported public features, enabled through explicit `control` declarations.
+See the [Suite guide](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/suites.md) and
+[release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21).
+
+**0.3.1 — application-reported live metrics.** Applications can publish values such as accuracy to the
+read-only monitoring dashboard through `Runner.report_metric()` or `TaskContext.report_metric()`. A completion
+callback receives committed pipeline results; the application owns the calculation. The dashboard and
+`watch` now follow one run consistently by default. See [`examples/live_metrics.py`](examples/live_metrics.py).
+
+**0.3.0 — control flow (opt-in), and the documentation in Chinese.** Tasks can now
+[hand off](#handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
 early, recorded in a durable ledger that recovery resumes from. It is opt-in and inert — a pipeline without a
-`control` block writes no new rows and keeps a byte-identical `spec_digest` — and marked experimental until
-1.0. Backward traversal now adds declared rewind and retry-all with visits and optional payload history. The
+`control` block writes no new rows and keeps a byte-identical `spec_digest`. Handoffs and backward traversal
+were experimental in 0.3.0 and became supported features in 0.3.2
+(see [0.3.2 release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)). Backward traversal adds declared rewind and retry-all with visits
+and optional payload history. The
 whole documentation set also ships in Simplified Chinese ([`README.zh-CN.md`](README.zh-CN.md),
 [`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)), kept in sync by CI. One
 rename to know about when upgrading: `MergedReport.events_total` is now `source_events_total`, because that
@@ -580,3 +599,6 @@ extracted and executed by `tests/test_tutorial.py`, so documentation that rots f
 
 MIT — see [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE).
 
+## Experiment suites
+
+Combine existing configuration files under one Runner with shared resource pools and total concurrency. Optional per-experiment directories separate checkpoints, results and file artifacts. Suite reports include prior successes across resumes. See the [Suite guide](docs/suites.md) and [runnable configuration](examples/suites/suite.json).

{pyattacker-0.3.0 → pyattacker-0.3.2}/README.md

@@ -68,7 +68,7 @@ Five concepts, and that is the whole vocabulary:
 | Concept | Meaning | In one line |
 |---|---|---|
 | **artifact** | the persisted state of a task | content-addressed, **persisted as soon as it is produced** → checkpoint granularity = task |
-| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([advanced](#advanced-handoffs-opt-in)) |
+| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([handoffs](#handoffs-opt-in)) |
 | **pipeline** | the unit of completion | `fetch \| ask \| judge \| metrics` chained linearly, semantically independent of each other |
 | **resource** | a leasable external capability | one endpoint / one key; once pooled, it can be published and subscribed to concurrency-safely |
 | **algorithm** | the policy for acquiring resources | `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`, `immediate` — orthogonal to "retry on failure" |
@@ -177,7 +177,7 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * Failed pipelines → continue from **the first task that produced no artifact**: **if task C died, only task C
   reruns when task B's checkpoint is durable**;
 * The seed artifact is persisted too → recovery **does not depend on the original dataset file**;
-* A pipeline that **handed off** ([advanced](#advanced-handoffs-opt-in)) resumes at the station it jumped to,
+* A pipeline that **handed off** ([handoffs](#handoffs-opt-in)) resumes at the station it jumped to,
   with the entry state the ledger recorded — the task that handed off is not re-run;
 * Changed a task's source code (`spec_digest` includes source digests) → treated as a new pipeline, so old
   results are not incorrectly reused. Factory parameters, fanout children, retry/algorithm policies and
@@ -188,10 +188,13 @@ rerun and old explicit keys conflict. Finish old runs with the old package, then
 [resume identity and idempotency reference](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#resume-identity)
 for migration guidance, dynamic functions and external configuration.
 
-## Advanced: Handoffs (Opt-In)
+<a id="advanced-handoffs-opt-in"></a>
 
-**Advanced tier: opt-in, changes the execution model, not needed for ordinary pipelines, experimental until
-1.0.** A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
+
+A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
 failure or hiding the branch inside one step. It **returns** a directive — `Handoff.to(target, value)` to
 continue at a declared later station, `Handoff.end(value)` to finish the pipeline right there:
 
@@ -259,8 +262,8 @@ with Runner(store=":memory:", concurrency=4) as runner:
 * **It is a durable checkpoint.** The jump is committed atomically (source task, attempt, entry artifact,
   ledger row and cursor together), so a killed process resumes **at the target** with the recorded entry
   state and does not re-run the source task. On a control-enabled pipeline `n_tasks_done` is a *position*,
-  not a progress count: skipped stations have no task rows. `report`/`watch` count commits in the selected
-  scope (one run when filtered, all history otherwise); `/pipelines.handoffs` counts active execution records and `handoffs_historical` counts all ledger
+  not a progress count: skipped stations have no task rows. `watch` counts commits in the selected
+  run by default (`--run-id all` selects all history); `/pipelines.handoffs` counts active execution records and `handoffs_historical` counts all ledger
   records. A resume can use an earlier run's active handoff while recording no new handoffs. Pipeline
   exports include ledger identity and the watermark to distinguish the scopes.
 * **Opt-in and inert.** Without the `control` block nothing changes — not one row, not one counter, and not a
@@ -271,16 +274,16 @@ with Runner(store=":memory:", concurrency=4) as runner:
   payloads provide explicit snapshots and restoration; ordinary dictionaries remain author-controlled.
   Visits and exact artifact occurrences retain history and make recovery safe. The APIs, budgets and
   recovery boundaries are in
-  [reference → advanced: backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits),
+  [reference → backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#backward-traversal-rewind-retry-all-visits),
   with working programs in
-  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all).
+  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all).
 
-The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-handoffs-opt-in)),
+The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#handoffs-opt-in)),
 one declaration — `control={"edges": {...}}` for forward jumps, `control.rewind` / `control.retry_all` /
 `control.max_handoffs` for backward traversal — and one optional store capability; a custom store that cannot
 commit a handoff atomically is refused up front instead of writing a jump that would not survive a crash.
-Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
-Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental).
+Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--skipping-stations-handoffs).
+Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-handoffs--declared-forward-jumps-opt-in).
 
 When a pipeline restarts from the seed, previous task rows and chain artifacts are reset atomically with the cursor/watermark;
 previous handoffs stay in its history but no longer act as
@@ -402,13 +405,15 @@ keeps everything in the store.
 
 ```bash
 uv run pyattacker serve runs/qa.db        # http://127.0.0.1:8787
-# /  dashboard   /stats  /events  /pipelines  /resources  /errors   (JSON)
+# /  dashboard   /stats  /metrics  /events  /pipelines  /resources  /errors   (JSON)
 ```
 
 It opens a fresh read-only connection per request, so it runs happily beside a live run. It has **no
 authentication** and binds to loopback: there is no artifact route, but it does expose what your run recorded —
 event `data` and stored error messages — so treat it as a debug view over your own data and do not put it on a
 public interface without your own proxy in front.
+Applications can publish live values with `runner.report_metric("accuracy", value, display="percent")`;
+the framework displays them without calculating the metric. See [`examples/live_metrics.py`](examples/live_metrics.py).
 
 **Branching inside a step** — `fanout(a, b)` runs several tasks on the same input concurrently and
 returns `{task_name: value}`. Retry granularity becomes the group, which is the honest price of not
@@ -449,8 +454,8 @@ what they do not say.
 
 | Document | What is in it |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation and the advanced handoff/backward tiers — rewinds, retry-all and payload history included; each one executed by the test suite |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including the advanced backward-traversal tier and `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation, handoffs and backward traversal — rewinds, retry-all and payload history included; each one executed by the test suite |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including backward traversal and `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md) | every subcommand, every flag, exit codes, config reference |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) | conceptual model, the six invariants, the lease contract, data model, tradeoffs |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/benchmark.md) | the algorithm benchmark: what the scenarios assume, what the metrics mean, how to read the table |
@@ -483,7 +488,7 @@ These are design decisions, not missing features:
 * **Semantic reduction** — accuracy, pass@k, F1 and any cross-pipeline aggregation. Export the artifacts and
   compute it outside, or write a sink pipeline out of the primitives.
 * **DAG orchestration** — a pipeline is a linear chain; branch inside a task with `fanout`. The one
-  qualification is the opt-in [handoff](#advanced-handoffs-opt-in): it changes the traversal of
+  qualification is the opt-in [handoff](#handoffs-opt-in): it changes the traversal of
   the chain along declared edges, never its topology (no joins, no second entry point, no cross-pipeline
   jumps).
 * **A serving gateway** — the only HTTP surface is the read-only debug endpoint above.
@@ -494,11 +499,25 @@ every known tradeoff with its reason.
 
 ## Status
 
-**0.3.0 — advanced control flow (opt-in), and the documentation in Chinese.** Tasks can now
-[hand off](#advanced-handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
+**0.3.2 — experiment suites and supported control flow.** Independent experiments can share resource
+pools and global concurrency, with unified run/resume/report commands and optional per-experiment output
+directories. Durable run histories preserve earlier outcomes after resume. Handoffs, forward jumps,
+rewinds and retry-all are supported public features, enabled through explicit `control` declarations.
+See the [Suite guide](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/suites.md) and
+[release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21).
+
+**0.3.1 — application-reported live metrics.** Applications can publish values such as accuracy to the
+read-only monitoring dashboard through `Runner.report_metric()` or `TaskContext.report_metric()`. A completion
+callback receives committed pipeline results; the application owns the calculation. The dashboard and
+`watch` now follow one run consistently by default. See [`examples/live_metrics.py`](examples/live_metrics.py).
+
+**0.3.0 — control flow (opt-in), and the documentation in Chinese.** Tasks can now
+[hand off](#handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
 early, recorded in a durable ledger that recovery resumes from. It is opt-in and inert — a pipeline without a
-`control` block writes no new rows and keeps a byte-identical `spec_digest` — and marked experimental until
-1.0. Backward traversal now adds declared rewind and retry-all with visits and optional payload history. The
+`control` block writes no new rows and keeps a byte-identical `spec_digest`. Handoffs and backward traversal
+were experimental in 0.3.0 and became supported features in 0.3.2
+(see [0.3.2 release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)). Backward traversal adds declared rewind and retry-all with visits
+and optional payload history. The
 whole documentation set also ships in Simplified Chinese ([`README.zh-CN.md`](README.zh-CN.md),
 [`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)), kept in sync by CI. One
 rename to know about when upgrading: `MergedReport.events_total` is now `source_events_total`, because that
@@ -555,3 +574,6 @@ extracted and executed by `tests/test_tutorial.py`, so documentation that rots f
 
 MIT — see [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE).
 
+## Experiment suites
+
+Combine existing configuration files under one Runner with shared resource pools and total concurrency. Optional per-experiment directories separate checkpoints, results and file artifacts. Suite reports include prior successes across resumes. See the [Suite guide](docs/suites.md) and [runnable configuration](examples/suites/suite.json).

{pyattacker-0.3.0 → pyattacker-0.3.2}/README.zh-CN.md

@@ -51,7 +51,7 @@ uv run pyattacker demo       # zero-config smoke test: 50 simulated pipelines, r
 | 概念 | 含义 | 一句话 |
 |---|---|---|
 | **artifact（产物）** | 任务持久化后的状态 | 内容寻址，**一产生就落盘** → 检查点粒度 = 任务 |
-| **task（任务）** | 调度的最小单位 | 一个一元函数 `(artifact) -> artifact`，同步异步都行——也可以 `-> artifact \| Handoff` 来跳过后续步骤（[进阶](README.zh-CN.md#进阶交接可选启用)） |
+| **task（任务）** | 调度的最小单位 | 一个一元函数 `(artifact) -> artifact`，同步异步都行——也可以 `-> artifact \| Handoff` 来跳过后续步骤（[交接](README.zh-CN.md#交接可选启用)） |
 | **pipeline（流水线）** | 完成和恢复的单位 | `fetch \| ask \| judge \| metrics` 线性串起来，各步语义独立 |
 | **resource（资源）** | 可租用的外部能力 | 一个端点 / 一把 key；放进资源池后可以并发安全地发布和订阅 |
 | **algorithm（算法）** | 获取资源的策略 | `wait`、`backoff`、`least_busy`、`failover`、`sticky`、`quota_aware`、`immediate`——和"失败了怎么重试"是两回事 |
@@ -147,14 +147,16 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * 任务和输入都没变、已经成功的流水线 → 直接跳过。
 * 失败的流水线 → 从**第一个没产出 artifact 的任务**接着跑：任务 C 挂了，只要 B 的检查点已经落盘，就只重跑 C。
 * 种子数据也持久化了 → 续跑**不需要原始数据集文件**。
-* 走过交接的流水线（[进阶](README.zh-CN.md#进阶交接可选启用)）会在跳转目标处恢复，用账本里记好的入口状态——发起跳转的那个任务不重跑。
+* 走过交接的流水线（[交接](README.zh-CN.md#交接可选启用)）会在跳转目标处恢复，用账本里记好的入口状态——发起跳转的那个任务不重跑。
 * 改了任务源码（`spec_digest` 包含源码摘要）→ 视为全新流水线，不会拿旧结果瞎复用。工厂参数、fanout 子任务、重试/算法策略、显式的 `config`/`version` 都算在内。手动指定 key 的话，定义或输入变了会直接拒绝。
 
 **升级已有存储：** fingerprint v2 改了默认 ID 和分片分配方式。旧任务可能会重跑，旧的手动 key 会冲突。建议用旧版本把手上的跑完，再换新存储。迁移指引、动态函数和外部配置详见 [恢复同一性与幂等性参考](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#恢复同一性)。
 
-## 进阶：交接（可选启用）
+<a id="进阶交接可选启用"></a>
 
-**这是进阶功能：需要手动开启，会改变执行模型，普通流水线用不上，1.0 之前算实验性。**
+## 交接（可选启用）
+
+**交接、正向跳转和回退都是正式的控制流特性，通过 `control` 显式声明后启用。**
 
 任务可以判断"后面的步骤不用跑了"，然后*明确说出来*，而不是硬编一个失败或者把分支藏在某一步里面。它**返回**一条指令——`Handoff.to(target, value)` 表示跳到指定的后续步骤继续跑，`Handoff.end(value)` 表示直接收尾：
 
@@ -215,13 +217,13 @@ with Runner(store=":memory:", concurrency=4) as runner:
 
 * **边是显式声明的，不是猜的。** 走了没声明的边，或者一个没有 `control` 块的流水线里出现了 `Handoff`，都是致命配置错误——不重试，也不会静默跳转。目标步骤必须在来源步骤之后；最后一步发起 `end` 会被拒绝（因为没意义）。
 * **交接是一种处置结果，不是失败。** 它是个返回值，所以重试策略根本看不到它，任务里写的 `except Exception:` 也吞不掉它。租约的归还和成功时完全一样，被取消或超时的尝试压根走不到返回这一步。
-* **它是持久化的检查点。** 跳转是原子提交的（源任务、尝试、入口产物、账本记录、游标一起提交），进程被杀了会在目标步骤恢复，带着记录好的入口状态，不会重跑源任务。开了控制流的流水线里，`n_tasks_done` 是个*位置*，不是进度计数——被跳过的步骤没有任务记录。`report`/`watch` 统计选定范围内的提交数（过滤时是单次运行，否则是全部历史）；`/pipelines.handoffs` 统计活跃执行记录，`handoffs_historical` 统计全部账本记录。续跑时可以用之前某次运行的活跃交接，同时不记录新的交接。导出的流水线数据里会带上账本身份和水位标记，用来区分这些范围。
+* **它是持久化的检查点。** 跳转是原子提交的（源任务、尝试、入口产物、账本记录、游标一起提交），进程被杀了会在目标步骤恢复，带着记录好的入口状态，不会重跑源任务。开了控制流的流水线里，`n_tasks_done` 是个*位置*，不是进度计数——被跳过的步骤没有任务记录。`watch` 默认统计选定运行的提交数（`--run-id all` 查看全部历史）；`/pipelines.handoffs` 统计活跃执行记录，`handoffs_historical` 统计全部账本记录。续跑时可以用之前某次运行的活跃交接，同时不记录新的交接。导出的流水线数据里会带上账本身份和水位标记，用来区分这些范围。
 * **不开就完全没影响。** 没有 `control` 块的流水线，一行数据、一个计数器、`spec_digest` 的一个字节都不会变。
-* **往回跳需要单独声明。** `Handoff.rewind(target, value)` 把作者指定的状态送回更早的步骤；`Handoff.retry_all()` 从最初的种子重新开始。需要声明 `control.rewind` / `control.retry_all`，还要设一个有限的 `control.max_handoffs`。可选的 `HistoryArtifact` 载荷可以做显式快照和恢复；普通字典的控制权完全在作者手里。访问记录（visits）和精确的产物出现记录会保留历史，保证恢复安全。API、预算和恢复边界见 [reference → 进阶：反向遍历](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#进阶反向遍历rewindretry-allvisits)，可运行的示例见 [tutorial 第 16–17 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-16-步--高级用回退和全部重试重新生成)。
+* **往回跳需要单独声明。** `Handoff.rewind(target, value)` 把作者指定的状态送回更早的步骤；`Handoff.retry_all()` 从最初的种子重新开始。需要声明 `control.rewind` / `control.retry_all`，还要设一个有限的 `control.max_handoffs`。可选的 `HistoryArtifact` 载荷可以做显式快照和恢复；普通字典的控制权完全在作者手里。访问记录（visits）和精确的产物出现记录会保留历史，保证恢复安全。API、预算和恢复边界见 [reference → 反向遍历](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#反向遍历rewindretry-allvisits)，可运行的示例见 [tutorial 第 16–17 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-16-步--用回退和全部重试重新生成)。
 
-API 就是一个类（[`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#进阶交接可选启用)）、一条声明——正向跳转用 `control={"edges": {...}}`，反向遍历用 `control.rewind` / `control.retry_all` / `control.max_handoffs`——再加一项可选的存储能力。无法原子提交交接的自定义存储会直接被拒绝，不会让你写一个崩了就丢的跳转。
+API 就是一个类（[`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#交接可选启用)）、一条声明——正向跳转用 `control={"edges": {...}}`，反向遍历用 `control.rewind` / `control.retry_all` / `control.max_handoffs`——再加一项可选的存储能力。无法原子提交交接的自定义存储会直接被拒绝，不会让你写一个崩了就丢的跳转。
 
-上手示例：[教程第 15 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-15-步--高级跳过站点交接)。模型和规则：[设计 §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md#48-进阶交接--声明式正向跳转可选启用实验性)。
+上手示例：[教程第 15 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-15-步--跳过站点交接)。模型和规则：[设计 §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md#48-交接--声明式正向跳转可选启用)。
 
 流水线从种子重新开始时，之前的任务记录和链上产物会和游标/水位一起原子重置。之前的交接还留在历史里，但不再当检查点用。之后的续跑只看当前这轮执行的交接，完成时选一个最终产物。支持交接的自定义存储必须把持久化的 `handoff_floor` 水位和游标一起存，还要实现原子的 `reset_pipeline(record)`。详见 [恢复契约](docs/zh-CN/reference.md#表与读取器)。
 
@@ -322,10 +324,12 @@ uv run pyattacker run -c examples/qa_eval.yaml --artifact-backend file:///data/b
 
 ```bash
 uv run pyattacker serve runs/qa.db        # http://127.0.0.1:8787
-# /  dashboard   /stats  /events  /pipelines  /resources  /errors   (JSON)
+# /  dashboard   /stats  /metrics  /events  /pipelines  /resources  /errors   (JSON)
 ```
 
 每个请求都新开一个只读连接，所以可以和正在跑的进程并存。**没有认证**，只绑回环地址——它没有 artifact 路由，但会暴露这次运行记下来的东西：事件的 `data`、存下来的错误信息。当调试工具用就好，别裸暴露到公网。
+应用可用 `runner.report_metric("accuracy", value, display="percent")` 汇报实时指标；框架只展示，
+不计算指标。参见 [`examples/live_metrics.py`](examples/live_metrics.py)。
 
 **步骤内分支**——`fanout(a, b)` 拿同一份输入并发跑多个任务，返回 `{task_name: value}`。重试粒度变成整个组，这是不把流水线做成 DAG 的代价。组是 Runner 看到的唯一规格，所以子任务们对 `resource`、`algorithm`、`timeout_s` 达成一致时，这些参数从子任务继承（此时 `timeout_s` 限制整个组）。
 
@@ -349,8 +353,8 @@ uv run pyattacker bench --algorithms wait,backoff --seeds 5 --json runs/bench.js
 
 | 文档 | 内容 |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md) | 17 个可运行步骤，从"一个任务"到分片评测和高级交接/反向遍历——回退、全量重试、载荷历史都有；每个步骤都有测试执行 |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md) | 所有公开类和函数：签名、参数、示例——包括高级反向遍历和 `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md) | 17 个可运行步骤，从"一个任务"到分片评测、交接和反向遍历——回退、全量重试、载荷历史都有；每个步骤都有测试执行 |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md) | 所有公开类和函数：签名、参数、示例——包括反向遍历和 `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/cli.md) | 每个子命令、每个参数、退出码、配置参考 |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md) | 概念模型、六条不变量、租约契约、数据模型、设计权衡 |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/benchmark.md) | 算法基准测试：场景假设了什么、指标怎么看、表格怎么读 |
@@ -381,7 +385,7 @@ uv run pyattacker run -c examples/qa_eval.yaml --limit 40
 
 * **网络请求**——openai/anthropic 的调用你自己写。内核从不碰 socket。
 * **指标计算**——准确率、pass@k、F1，以及任何跨流水线的汇总计算。把产物导出来在外面算，或者用原语自己拼一条汇总流水线。
-* **DAG 编排**——流水线就是一条直线链，要分支就在任务内部用 `fanout`。唯一例外是可选的[交接](README.zh-CN.md#进阶交接可选启用)：它只是沿着声明的边改变链的遍历方式，拓扑不变（没有汇合节点、没有第二个入口、没有跨流水线跳转）。
+* **DAG 编排**——流水线就是一条直线链，要分支就在任务内部用 `fanout`。唯一例外是可选的[交接](README.zh-CN.md#交接可选启用)：它只是沿着声明的边改变链的遍历方式，拓扑不变（没有汇合节点、没有第二个入口、没有跨流水线跳转）。
 * **服务网关**——唯一的 HTTP 接口就是上面那个只读调试面板。
 * **分布式调度**——横向扩展用 `--shard`，多进程就是上限。
 
@@ -389,7 +393,17 @@ uv run pyattacker run -c examples/qa_eval.yaml --limit 40
 
 ## 当前状态
 
-**0.3.0——高级控制流（可选），以及中文文档。** 任务现在可以做[交接](README.zh-CN.md#进阶交接可选启用)：返回一个 `Handoff` 跳过声明的后续步骤或提前收尾，记录在持久化账本里，续跑时从账本接着走。需要手动开启，不开完全没影响——没有 `control` 块的流水线不写新数据，`spec_digest` 逐字节不变。1.0 之前标记为实验性。反向遍历现在支持声明式回退和全量重试，带 visits 和可选的载荷历史。整套文档也提供了简体中文版（[`README.zh-CN.md`](README.zh-CN.md)、[`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)），由 CI 保持同步。升级时有一个改名要知道：`MergedReport.events_total` 现在叫 `source_events_total`，因为它是合并报告里**唯一**不去重、按源库原始累加的计数（旧名字仍可作为废弃别名使用）。
+**0.3.2——组合实验与正式控制流特性。** 独立子实验可共享资源池和总并发，统一运行、恢复和查看结果，
+并可按实验分目录存储。持久化的运行历史在恢复后仍保留此前的结果。交接、正向跳转、回退和全量重试
+作为正式公共特性维护，通过 `control` 显式声明后启用。
+详见 [Suite 指南](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/suites.md) 和
+[发布说明](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)。
+
+**0.3.1——应用汇报的实时指标。** 应用可用 `Runner.report_metric()` 或 `TaskContext.report_metric()`
+把准确率等数值汇报到只读监控面板。完成回调提供已提交的流水线结果，指标计算仍由应用负责。
+面板和 `watch` 默认统一跟随同一个运行。参见 [`examples/live_metrics.py`](examples/live_metrics.py)。
+
+**0.3.0——控制流（可选），以及中文文档。** 任务现在可以做[交接](README.zh-CN.md#交接可选启用)：返回一个 `Handoff` 跳过声明的后续步骤或提前收尾，记录在持久化账本里，续跑时从账本接着走。需要手动开启，不开完全没影响——没有 `control` 块的流水线不写新数据，`spec_digest` 逐字节不变。交接与反向遍历在 0.3.0 发布时属于实验性特性，在 0.3.2 中提升为正式特性（见 [0.3.2 发布说明](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)）。反向遍历现在支持声明式回退和全量重试，带 visits 和可选的载荷历史。整套文档也提供了简体中文版（[`README.zh-CN.md`](README.zh-CN.md)、[`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)），由 CI 保持同步。升级时有一个改名要知道：`MergedReport.events_total` 现在叫 `source_events_total`，因为它是合并报告里**唯一**不去重、按源库原始累加的计数（旧名字仍可作为废弃别名使用）。
 
 **0.2.0——基准测试、更严格的身份校验、三处正确性修复。** 新增 `pyattacker bench`：一个模拟接口方的世界，用一组指标对比各获取算法，而不是一个加权分数（[`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/benchmark.md)）。新增 `Retrying.decide`：把重试决策暴露为策略上的方法。新增分页的整类读取（`pyattacker.store.iter_*`，由可选的 `PagedStore` 扩展提供），导出大存储不再需要全量加载。0.1.x 已经实现了 M0–M4 计划的全部内容：内核、持久化和任务级恢复、重试和错误分类、带 7 种获取算法的资源池、延迟延续和 write-behind 批处理、分片和合并报告、三种格式五种导出形状、入口点插件、外部产物后端、fan-out 辅助函数、HTTP 监控端点。
 
@@ -415,3 +429,7 @@ uv build                     # sdist + wheel
 ## 许可证
 
 MIT——见 [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE)。
+
+## 实验集合
+
+把已有配置文件组合到同一个 Runner，共享资源池和总并发。可选的按子实验分目录布局分别保存检查点、结果和文件产物；Suite 报告包含恢复前已完成的结果。参见 [Suite 指南](docs/zh-CN/suites.md) 和 [可运行配置](examples/suites/suite.json)。