@bitget-ai/getagent-skill 0.2.1 → 0.3.0

package/skills/getagent/references/backtest-engine.md

@@ -93,9 +93,10 @@ Required sections:
   - `class`
   - optional `config_class`
   - optional `config`
-- `execution`
-  - optional `start`
-  - optional `end`
+- `execution` (optional)
+  - optional `start` / `end` — bar filters applied when present; omit them to
+    replay every bar you fetched. The window is the author's choice and the
+    platform never polices its presence, length, or recency.
 
 ## Execution Model
 
@@ -138,7 +139,9 @@ instrument frames into the strategy through `set_feature_frames(...)` or
 | `result.sharpe_ratio`     | float | Sharpe ratio                 |
 | `result.max_drawdown_pct` | float | Max drawdown %               |
 | `result.win_rate`         | float | Win rate fraction (0.0-1.0)  |
-| `result.total_trades`     | int   | Total closed position count  |
+| `result.total_trades`     | int   | Filled execution count when fills are available |
+| `result.fill_count`       | int   | Filled execution count       |
+| `result.position_count`   | int   | Nautilus position row count  |
 | `result.profit_factor`    | float | Profit factor                |
 | `result.summary`          | dict  | Stable normalized account-level summary |
 | `result.raw`              | dict  | Full Nautilus-derived output |
@@ -244,185 +247,112 @@ Inspect:
 - `result.raw["reports"]["fills"]`
 - `result.raw["reports"]["positions"]`
 
-## Chart Generation
+## Backtest Output Contract
 
-```python
-chart_path = backtest.generate_chart(result)
-```
+When `main_backtest.py` writes output files, the platform Runner collects them
+and merges them into the run record. Getting this wrong causes publish failures
+("缺少可发布的真实 equity curve") or incorrect metrics display.
 
-The managed chart renderer writes a PNG summary to `/workspace/output/`.
+### Required Output Files
 
-Current chart includes:
+| File | Purpose | Size |
+| ---- | ------- | ---- |
+| `output/backtest_report.json` | Nautilus raw result (summary, stats, reports, config) | Keep small — omit equity curve from JSON |
+| `output/equity_curve.csv` | Lightweight curve the Runner always reads reliably | ~100 bytes/point |
 
-- equity curve when available
-- normalized metrics when no curve is available
-- key summary values
-# Backtest Engine
+The Runner reads **both** files. If `backtest_report.json` is too large (common
+with 3+ month runs), `proxy.read_file()` may silently fail. The CSV is a
+guaranteed fallback.
 
-## Contents
+### Equity Curve Metadata
 
-- [Basic Usage](#basic-usage)
-- [Backtest Eligibility](#backtest-eligibility)
-- [Spec Shape](#spec-shape)
-- [Execution Model](#execution-model)
-- [BacktestResult](#backtestresult)
-- [Multi-Instrument Replays](#multi-instrument-replays)
-- [Zero-Trade Diagnostics](#zero-trade-diagnostics)
-- [Chart Generation](#chart-generation)
-
-## Basic Usage
+The platform records actual curve metadata such as point count and the first /
+last curve timestamp. It does not require a fixed density.
 
 ```python
-from getagent import backtest, data, runtime
-
-bars = data.crypto.futures.kline(symbol="BTCUSDT", interval="1h", exchange="binance")
-ohlcv = data.to_dataframe(bars, datetime_index="date")
-
-result = backtest.run(
-    ohlcv_data={"BTCUSDT.BINANCE": ohlcv},
-    spec=runtime.backtest_spec,
-)
-chart_path = backtest.generate_chart(result)
+expected_points = ceil((execution.end - execution.start).total_seconds() / interval_seconds)
 ```
 
-## Backtest Eligibility
-
-Not every Playbook can produce a fair historical backtest.
-
-### Use the engine when:
-
-- the core trading decision is deterministic
-- the decision can be reconstructed from historical data
-- strategy logic can be expressed as a NautilusTrader `Strategy` subclass
-- any LLM usage is outside the trade decision path
-
-### Do not use the engine as public evidence when:
-
-- open-ended LLM reasoning decides whether to trade
-- the strategy depends on live chat, memory, or search context
-- the decision cannot be reconstructed at the original point in time
-
-Typical outcome:
+That value may still appear as diagnostic metadata in older runs, but it is not
+a publish gate. Do not fabricate forward-filled points just to make the curve
+look dense.
 
-- `backtest_support: full` -> use `backtest.run()` and publish historical metrics
-- `backtest_support: none` -> use paper or live evidence instead
-
-## Spec Shape
-
-The managed engine expects an explicit Nautilus replay spec from `backtest.yaml`,
-usually read through `runtime.backtest_spec`.
-
-Required sections:
-
-- `venue`
-  - `name`
-  - `account_type`
-  - `oms_type`
-  - `starting_balances`
-- `instrument` or `instruments`
-  - `id`
-  - `kind`
-  - `raw_symbol` or `symbol`
-  - `base_currency`
-  - `quote_currency`
-  - `price_precision`
-  - `size_precision`
-  - `price_increment`
-  - `size_increment`
-  - `bar_type`
-  - perpetual instruments also need `settlement_currency`
-- `strategy`
-  - `module`
-  - `class`
-  - optional `config_class`
-  - optional `config`
-- `execution`
-  - optional `start`
-  - optional `end`
+### Metrics Merge Priority (Critical)
 
-## Execution Model
+The Runner builds `metrics_output` with this merge order:
 
-The managed flow is:
+```python
+merged_metrics = dict(backtest_report)           # report is BASE
+for key, value in signal_metrics.items():
+    merged_metrics.setdefault(key, value)         # signal only fills gaps
+```
 
-1. author code fetches historical bars through `getagent.data`
-2. `backtest.run()` normalizes each DataFrame into OHLCV bars
-3. the engine builds Nautilus venue + instrument definitions from `backtest.yaml`
-4. `BarDataWrangler` converts DataFrames into Nautilus bars
-5. the author's `Strategy` subclass is imported from `src/**`
-6. Nautilus `BacktestEngine` runs the replay
-7. the platform normalizes summary metrics and preserves the deeper reports
+**`setdefault` does not override existing keys** — even if they are `null`.
 
-For single-instrument strategies the runner auto-injects these config defaults
-when they are absent:
+`result.raw` from the engine has `result.update(summary)` applied, which
+flattens `net_pnl`, `total_return_pct`, `starting_balance` etc. to the top
+level. These engine-level values may be `null` or denominated by
+`venue.starting_balances` (account basis) rather than `margin_budget` (strategy
+basis).
 
-- `instrument_id`
-- `bar_type`
-- `instrument_ids`
-- `bar_types`
+**You must override these top-level keys before writing the JSON:**
 
-That means the common author pattern is:
+```python
+# Compute correct absolute USDT values
+net_pnl = ending_total - initial_capital
+strategy_return_pct = net_pnl / initial_capital * 100.0
 
-- define `DemoStrategyConfig(StrategyConfig)`
-- define `DemoStrategy(Strategy)`
-- let `backtest.yaml` carry the wiring
+# Override engine values so backend merge picks up correct numbers
+raw["net_pnl"] = round(net_pnl, 4)
+raw["total_return_pct"] = round(strategy_return_pct, 4)
+raw["starting_balance"] = initial_capital
 
-## BacktestResult
+# Write files
+(out_dir / "backtest_report.json").write_text(json.dumps(raw, default=str))
+```
 
+Without this, the platform's `_apply_strategy_basis_metrics` will compute
+`total_return_pct = net_pnl / margin_budget * 100` using the engine's
+potentially wrong `net_pnl`, producing incorrect display values.
 
-| Property                  | Type  | Description                  |
-| ------------------------- | ----- | ---------------------------- |
-| `result.total_return_pct` | float | Account return % using the replay starting balance |
-| `result.sharpe_ratio`     | float | Sharpe ratio                 |
-| `result.max_drawdown_pct` | float | Max drawdown %               |
-| `result.win_rate`         | float | Win rate fraction (0.0-1.0)  |
-| `result.total_trades`     | int   | Total closed position count  |
-| `result.profit_factor`    | float | Profit factor                |
-| `result.summary`          | dict  | Stable normalized account-level summary |
-| `result.raw`              | dict  | Full Nautilus-derived output |
+### Equity Curve CSV Format
 
+```csv
+timestamp,value,nav
+2026-03-01T00:00:00,1000.0,1.0
+2026-03-01T01:00:00,1002.5,1.0025
+...
+```
 
-`result.raw` keeps these top-level sections:
+Do **not** embed the equity curve in `backtest_report.json` (`reports.equity_curve`).
+The Runner reads `equity_curve.csv` independently and attaches it to the report
+via `_attach_equity_curve_to_report`. Keeping the curve out of the JSON reduces
+file size and prevents read failures for long backtest windows.
 
-- `summary`
-- `stats`
-- `reports`
-- `config`
+### Correct Execution Order
 
-## Multi-Instrument Replays
+```
+1. Run backtest.run()
+2. Build an equity curve from real replay/account values — never fabricate
+   or forward-fill points
+3. Compute net_pnl from account report
+4. Override raw top-level metrics
+5. Write backtest_report.json (without equity curve)
+6. Write equity_curve.csv
+7. runtime.emit_signal() with correct metrics
+```
 
-Use `instruments:` when the strategy needs multiple instrument definitions.
+### `csv` Module Is Blocked
 
-Provide one OHLCV DataFrame per declared instrument ID or symbol:
+The sandbox blocks the `csv` stdlib module. Write CSV manually:
 
 ```python
-result = backtest.run(
-    ohlcv_data={
-        "BTCUSDT.BINANCE": btc_df,
-        "ETHUSDT.BINANCE": eth_df,
-    },
-    spec=runtime.backtest_spec,
-)
+csv_lines = ["timestamp,value,nav"]
+for point in equity_curve:
+    csv_lines.append(f"{point.get('timestamp','')},{point.get('value','')},{point.get('nav','')}")
+(out_dir / "equity_curve.csv").write_text("\n".join(csv_lines) + "\n", encoding="utf-8")
 ```
 
-The engine does not synthesize cross-instrument logic for you. Multi-instrument
-behavior belongs in the author's Nautilus strategy code.
-
-## Zero-Trade Diagnostics
-
-If `result.total_trades == 0`, common causes are:
-
-1. bars were filtered out by `execution.start` / `execution.end`
-2. the strategy never subscribed to the declared `bar_type`
-3. instrument IDs in strategy config do not match the spec
-4. order sizing is invalid for the declared increment / lot size
-
-Inspect:
-
-- `result.raw["config"]`
-- `result.raw["reports"]["orders"]`
-- `result.raw["reports"]["fills"]`
-- `result.raw["reports"]["positions"]`
-
 ## Chart Generation
 
 ```python

package/skills/getagent/references/package-schema.md

@@ -357,15 +357,38 @@ Sections:
 | `venue`                       | mapping                  | Venue name, account type, OMS type, and starting balances           |
 | `instrument` or `instruments` | mapping or list[mapping] | Explicit instrument definitions and `bar_type` declarations         |
 | `strategy`                    | mapping                  | Author strategy module/class entry plus config payload              |
-| `execution`                   | mapping                  | Optional replay window such as `start` / `end`                      |
+| `execution`                   | mapping                  | Optional replay window filters `start` and `end`                    |
 | `data_requirements`           | mapping                  | Optional replay data contract such as required enriched bar columns |
 
 
+`execution.start` and `execution.end` are optional bar filters: when present
+the engine drops bars outside the window before replay; when omitted the
+replay covers every bar the strategy fetched. The window is entirely the
+author's choice — the platform never polices window presence, length, or
+recency. Pick whatever range the strategy needs; if a single fetch cannot
+cover it, batch history requests. The only hard rule is honesty: the replay
+must run on real bars, and metrics/curves must come from the actual run.
+
+Symbols are part of the package contract. Keep `manifest.trading_symbols`,
+`display_name`, `description`, README, `backtest.yaml` instrument symbols, data
+calls, and emitted signal symbols aligned. If a user submits a typo such as
+`TCUSDT` and you correct it to `BTCUSDT`, the package must be renamed and the
+README/final summary must explicitly say the submitted symbol was corrected to
+the supported symbol. Never publish a package whose title claims one symbol
+while its backtest uses another.
+
+Do not put `provider` anywhere in `backtest.yaml`. The managed runtime chooses
+the DataSDK provider for the deployment; package authors declare symbols,
+venues, intervals, instruments, and feature requirements only.
+
 Optional `data_requirements.required_bar_fields` lets a deterministic strategy
 declare extra normalized bar columns it expects in addition to core OHLCV.
 These names should use lower snake case to match the replay engine's normalized
 DataFrame columns, for example `quote_volume`, `trade_count`, or
-`taker_buy_volume`.
+`taker_buy_volume`. Every field listed here must also appear in `src/**` code
+and be created by `getagent.backtest.build_feature_frame(...)` or equivalent
+before calling `backtest.run(...)`; otherwise validation rejects the package as a
+custom bar fields mismatch.
 
 Every backtest instrument must declare explicit `maker_fee` and `taker_fee`.
 Do not rely on zero-fee defaults. High-frequency Playbooks can look profitable
@@ -376,12 +399,12 @@ contract assumption.
 
 Data coverage is part of the package contract. If a strategy requires enriched
 columns such as `quote_volume`, `taker_buy_ratio`, open interest, funding, or
-liquidation data, author code must prove that the selected DataSDK
-endpoint/provider/symbol combination returns enough rows for the claimed replay
-window and the exact fields used by the strategy. Do not silently fill a missing
-decision feature with constants such as `0`, `0.5`, or `False` and still claim a
-valid backtest. If a feature is degraded, expose that in metrics/meta or fail
-the run with a clear error.
+liquidation data, author code must prove that the selected DataSDK endpoint,
+symbol, and interval returns enough rows for the claimed replay window and the
+exact fields used by the strategy. Do not pass `provider=...` to `getagent.data`
+calls. Do not silently fill a missing decision feature with constants such as
+`0`, `0.5`, or `False` and still claim a valid backtest. If a feature is
+degraded, expose that in metrics/meta or fail the run with a clear error.
 
 Large multi-symbol backtests must batch data fetches instead of issuing one
 tight loop over every symbol and endpoint. If a Playbook scans many symbols

package/skills/getagent/references/sdk/backtest/catalog.md

@@ -75,7 +75,8 @@ Parameters:
     - `venue`
     - `instrument` or `instruments`
     - `strategy`
-    - optional `execution`
+    - optional `execution.start` / `execution.end` bar filters (the replay
+      window is the author's choice; omit to replay every fetched bar)
     - optional `data_requirements.required_bar_fields`
 
 ### Generate a chart
@@ -98,6 +99,8 @@ Behavior:
 - `win_rate`
 - `profit_factor`
 - `total_trades`
+- `fill_count`
+- `position_count`
 - `summary`
 - `raw`
 
@@ -178,8 +181,19 @@ runtime.emit_signal(
 
 - Use `runtime.backtest_spec` as the default source of replay configuration
 - Keep public backtest claims tied to deterministic strategy logic
+- Do not pass `provider=...` to `getagent.data` calls; the managed DataSDK
+  provider is selected by the platform
+- The `backtest.yaml.execution.start` / `execution.end` window is optional and
+  entirely the author's choice — the platform never polices it. When you do
+  declare one, verify the selected endpoint returns real bars inside it
+- Keep `manifest.trading_symbols`, display text, README, `backtest.yaml`
+  instruments, data calls, and emitted signal symbols aligned. If you correct a
+  typo or replace an unavailable symbol, rename the package/title and explain
+  the correction.
 - Declare enriched replay column dependencies in
   `backtest.yaml -> data_requirements.required_bar_fields`
+- Every required replay field must be created and referenced in `src/**`; remove
+  the declaration if the strategy no longer reads that feature
 - Use `prepare_frame()` / `build_feature_frame()` to standardize multi-endpoint
   replay assembly instead of open-coded timestamp joins
 - Expect `backtest.run()` to fail fast when declared replay columns are missing
@@ -194,7 +208,8 @@ runtime.emit_signal(
 - Strategy classes may import `nautilus_trader`; Playbook code must not import
   legacy backtest engines directly
 - Do not use `backtest.run()` as fake evidence for `llm_bounded` strategies
-- Treat `result.total_trades == 0` as a diagnostic case, not a success story
+- Treat `result.total_trades == 0` as an honest no-trade outcome for the
+  selected window; do not loosen strategy thresholds just to force trades
 - Prefer `generate_chart(result)` over writing ad hoc chart files yourself
 - Do not emit `metrics=result.summary` directly for user-visible backtest
   results when the strategy has a configured budget. Convert `net_pnl` to

package/skills/getagent/references/sdk/data/arxiv.md

@@ -12,7 +12,7 @@ are callable through the DataSDK wrapper.
 ### `arxiv.search`
 
 ```python
-data.arxiv.search(query=None, max_results=10, page=1, sort_by='relevance', sort_order='descending', search_field='all', category=None, provider='arxiv')
+data.arxiv.search(query=None, max_results=10, page=1, sort_by='relevance', sort_order='descending', search_field='all', category=None)
 ```
 
 Summary: Search
@@ -22,7 +22,6 @@ Summary: Search
 | Endpoint ID | `arxiv.search` |
 | HTTP | `GET` |
 | Path | `/inner/v1/agent-data/arxiv/search` |
-| Default provider | `arxiv` |
 | SDK | `supported` |
 | Host | `supported` |
 | Notes | - |
@@ -31,11 +30,10 @@ Summary: Search
 
 | Param | Required | Type | Default | Notes |
 |---|---|---|---|---|
-| `query` | `no` | `string | null` | `-` | Search query string. (provider: arxiv) |
-| `max_results` | `no` | `integer` | `10` | Maximum number of results. (provider: arxiv) |
-| `page` | `no` | `integer` | `1` | Page number, starting at 1. (provider: arxiv) |
-| `sort_by` | `no` | `string` | `relevance` | Sort by relevance, last updated date, or submitted date. (provider: arxiv) |
-| `sort_order` | `no` | `string` | `descending` | Sort direction. (provider: arxiv) |
-| `search_field` | `no` | `string` | `all` | Field to search: all, ti (title), au (author), abs (abstract), cat (category). (provider: arxiv) |
-| `category` | `no` | `string | null` | `-` | Filter by arXiv subject category, e.g. 'cs.AI', 'q-fin.TR'. (provider: arxiv) |
-| `provider` | `no` | `string` | `arxiv` | - |
+| `query` | `no` | `string | null` | `-` | Search query string. |
+| `max_results` | `no` | `integer` | `10` | Maximum number of results. |
+| `page` | `no` | `integer` | `1` | Page number, starting at 1. |
+| `sort_by` | `no` | `string` | `relevance` | Sort by relevance, last updated date, or submitted date. |
+| `sort_order` | `no` | `string` | `descending` | Sort direction. |
+| `search_field` | `no` | `string` | `all` | Field to search: all, ti (title), au (author), abs (abstract), cat (category). |
+| `category` | `no` | `string | null` | `-` | Filter by arXiv subject category, e.g. 'cs.AI', 'q-fin.TR'. |

package/skills/getagent/references/sdk/data/catalog.md

@@ -7,10 +7,8 @@ Playbook creator source tree.
 
 ## Read order
 
-1. Start with [`playbook-supported.md`](playbook-supported.md) for the full
-   Playbook-callable `getagent.data` surface.
-2. Use the domain files below for exact signatures, defaults, enums,
-   provider notes, and parameter details.
+1. Use the domain files below for exact signatures, defaults, enums,
+   and parameter details.
 
 ## Domain index
 
@@ -19,7 +17,7 @@ Playbook creator source tree.
 | `Coverage` | [coverage.md](coverage.md) | 3 |
 | `arxiv` | [arxiv.md](arxiv.md) | 1 |
 | `commodity` | [commodity.md](commodity.md) | 7 |
-| `crypto` | [crypto.md](crypto.md) | 97 |
+| `crypto` | [crypto.md](crypto.md) | 96 |
 | `currency` | [currency.md](currency.md) | 4 |
 | `derivatives` | [derivatives.md](derivatives.md) | 8 |
 | `economy` | [economy.md](economy.md) | 42 |
@@ -45,9 +43,6 @@ Playbook creator source tree.
   separate sandbox allowlist.
 - For backtests, verify the endpoint returns the fields and time axis your
   strategy needs before declaring those fields in `backtest.yaml`.
-- `provider` may be shown with a default even when the upstream OpenAPI
-  marks it as required. That reflects the managed `getagent.data` wrapper,
-  which auto-injects the default provider when one is defined.
 - Time ranges use millisecond Unix-epoch `start_time` / `end_time` and the
   canonical datetime column is `time`. The SDK still accepts the legacy
   `start_date` / `end_date` parameters (and exposes a derived `date` field)