@bitget-ai/getagent-skill 0.2.1 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official GetAgent Agent Skill for trading Playbook authoring",
-    "version": "0.2.1"
+    "version": "0.2.2"
   },
   "plugins": [
     {
       "name": "getagent",
       "source": "./",
       "description": "Create, validate, upload, backtest, publish, and enable GetAgent quantitative trading Playbooks.",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "author": {
         "name": "GetAgent",
         "email": "support@bitget.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "getagent",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Create, validate, upload, backtest, publish, and enable GetAgent quantitative trading Playbooks.",
   "author": {
     "name": "GetAgent",

package/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitget-ai/getagent-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Install the official GetAgent Agent Skill for Playbook authoring.",
   "license": "Proprietary",
   "homepage": "https://github.com/Bitget-AI/getagent-skill#readme",

package/skills/getagent/SKILL.md

@@ -12,7 +12,7 @@ compatibility: >-
   access to the GetAgent Playbook control-plane API for upload/run/publish.
 metadata:
   author: getagent
-  version: v0.2.1
+  version: v0.2.2
 ---
 
 # GetAgent Playbook Creator
@@ -99,6 +99,22 @@ Use the English equivalent when the user's first message is English.
 - Runtime SDK: `references/sdk/runtime/catalog.md`
 - LLM SDK: `references/sdk/llm/catalog.md`
 
+## Backtest Output Pitfalls
+
+Before writing `main_backtest.py`, read `references/backtest-engine.md` §Backtest
+Output Contract. The three most common publish failures are:
+
+1. **"缺少可发布的真实 equity curve"** — no `output/equity_curve.csv`, and the
+   JSON report is too large for the Runner to read.
+2. **Missing real evidence** — the run did not produce a real
+   `output/equity_curve.csv` or platform-readable historical evidence. Do not
+   fabricate dense points or hand-written summaries.
+3. **Incorrect `total_return_pct` display** — `result.raw` has engine-level
+   summary fields flattened to the top level. The backend merge uses the report
+   as BASE (`setdefault` from signal cannot override). You must overwrite
+   `raw["net_pnl"]` and `raw["total_return_pct"]` with correct absolute values
+   before writing `backtest_report.json`.
+
 ## Hard Boundaries
 
 - Do not tell users to install or execute the private GetAgent SDK locally.
@@ -111,6 +127,18 @@ Use the English equivalent when the user's first message is English.
 - Do not call trade mutation APIs directly in a signal-only branch. Emit the
   signal successfully and let the runtime decide whether follow-trade is
   allowed.
+- For `backtest_support: full`, always declare a bounded
+  `backtest.yaml.execution.start` / `execution.end` window, never pass
+  `provider=...`, and ensure any
+  `data_requirements.required_bar_fields` are actually built and referenced in
+  `src/**`.
+- Keep symbols consistent across `manifest.trading_symbols`, display text,
+  README, `backtest.yaml` instruments, data calls, and emitted signals. If the
+  submitted symbol is a typo or unavailable and you replace it with a supported
+  symbol, rename the package/title and explain the correction in README and the
+  final summary.
+- In Nautilus strategy code, call `self.cancel_all_orders(instrument_id)` and
+  `self.close_all_positions(instrument_id)` with an explicit instrument id.
 - Do not publish or enable without showing the endpoint and masked
   `ACCESS-KEY` prefix and getting the user's intent for that operation.
 

package/skills/getagent/examples/btc-ema-cross-demo/backtest.yaml

@@ -16,6 +16,10 @@ strategy:
     fast_period: 12
     slow_period: 26
 
+execution:
+  start: "2024-01-01T00:00:00Z"
+  end: "2024-04-01T00:00:00Z"
+
 instrument:
   id: BTCUSDT.BINANCE
   kind: perpetual

package/skills/getagent/references/api/publish.md

@@ -55,6 +55,10 @@ stable public contract for:
 - If `backtest_support = full`
   - the current runtime must be able to execute it (`runtime_profile = deterministic`)
   - the owner must first produce one successful historical evaluation run
+  - that run must include a real equity/NAV curve, not only aggregate metrics
+  - the curve must cover the declared replay contract: at least one point per
+    `backtest.yaml` bar interval across `execution.start` / `execution.end`, or
+    at least `lookback_bars` points when the playbook uses a lookback-only replay
   - the Playbook should expose one official public backtest snapshot
   - list / detail surfaces should use that snapshot, not an arbitrary recent run
 - If `backtest_support = none`

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

@@ -94,8 +94,8 @@ Required sections:
   - optional `config_class`
   - optional `config`
 - `execution`
-  - optional `start`
-  - optional `end`
+  - required `start`
+  - required `end`
 
 ## Execution Model
 
@@ -138,7 +138,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 +246,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
-
-- [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)
+### Equity Curve Metadata
 
-## 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
+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.
 
-Not every Playbook can produce a fair historical backtest.
+### Metrics Merge Priority (Critical)
 
-### Use the engine when:
+The Runner builds `metrics_output` with this merge order:
 
-- 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:
-
-- `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`
+```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
+```
 
-## Execution Model
+**`setdefault` does not override existing keys** — even if they are `null`.
 
-The managed flow is:
+`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).
 
-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
+**You must override these top-level keys before writing the JSON:**
 
-For single-instrument strategies the runner auto-injects these config defaults
-when they are absent:
-
-- `instrument_id`
-- `bar_type`
-- `instrument_ids`
-- `bar_types`
+```python
+# Compute correct absolute USDT values
+net_pnl = ending_total - initial_capital
+strategy_return_pct = net_pnl / initial_capital * 100.0
 
-That means the common author pattern is:
+# 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
 
-- define `DemoStrategyConfig(StrategyConfig)`
-- define `DemoStrategy(Strategy)`
-- let `backtest.yaml` carry the wiring
-
-## 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
+3. Slice to the declared [start, end] window without fabricating points
+4. Compute net_pnl from account report
+5. Override raw top-level metrics
+6. Write backtest_report.json (without equity curve)
+7. Write equity_curve.csv
+8. 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,37 @@ 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                  | Required bounded replay window with `start` and `end`               |
 | `data_requirements`           | mapping                  | Optional replay data contract such as required enriched bar columns |
 
 
+`execution.start` and `execution.end` are required for `backtest_support: full`.
+Use ISO dates or datetimes and choose a window that the selected DataSDK endpoint
+actually returns bars for. If the selected replay exceeds endpoint limits, fetch
+history in batches or shorten the declared window. Unbounded backtests and
+windows that produce no rows are rejected because public evidence must be
+reproducible.
+
+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 +398,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,7 @@ Parameters:
     - `venue`
     - `instrument` or `instruments`
     - `strategy`
-    - optional `execution`
+    - required `execution.start` and `execution.end`
     - optional `data_requirements.required_bar_fields`
 
 ### Generate a chart
@@ -98,6 +98,8 @@ Behavior:
 - `win_rate`
 - `profit_factor`
 - `total_trades`
+- `fill_count`
+- `position_count`
 - `summary`
 - `raw`
 
@@ -178,8 +180,18 @@ 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
+- Declare a bounded `backtest.yaml.execution.start` / `execution.end` window,
+  and verify the selected endpoint returns bars inside that window
+- 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 +206,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

@@ -10,7 +10,7 @@ Playbook creator source tree.
 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.
+   and parameter details.
 
 ## Domain index
 
@@ -45,9 +45,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)