@bitget-ai/getagent-skill 0.2.1 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -6,23 +6,34 @@
   },
   "metadata": {
     "description": "Official GetAgent Agent Skill for trading Playbook authoring",
-    "version": "0.2.1"
+    "version": "0.3.0"
   },
   "plugins": [
     {
       "name": "getagent",
       "source": "./",
       "description": "Create, validate, upload, backtest, publish, and enable GetAgent quantitative trading Playbooks.",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "author": {
         "name": "GetAgent",
         "email": "support@bitget.com"
       },
       "repository": "git@gitlab.bitget.tools:algorithm/upex-algorithm-getall-skill-sdk.git",
       "license": "Proprietary",
-      "keywords": ["getagent", "trading", "playbooks", "backtesting", "agent-skills"],
+      "keywords": [
+        "getagent",
+        "trading",
+        "playbooks",
+        "backtesting",
+        "agent-skills"
+      ],
       "category": "external-integrations",
-      "tags": ["trading", "backtesting", "agent-skills", "playbooks"]
+      "tags": [
+        "trading",
+        "backtesting",
+        "agent-skills",
+        "playbooks"
+      ]
     }
   ]
 }

package/.claude-plugin/plugin.json

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

package/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitget-ai/getagent-skill",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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.3.0
 ---
 
 # GetAgent Playbook Creator
@@ -66,6 +66,10 @@ D. 我已有策略代码（贴在这里或给路径），先 review 修复再跑
 
 Use the English equivalent when the user's first message is English.
 
+For option A, do not author from scratch: use the bundled runnable demo at
+`examples/btc-ema-cross-demo/` (read its `README.md` first), validate it
+locally, then walk the user through upload and a sandbox run.
+
 ## Default Workflow
 
 1. Clarify only missing strategy requirements that block authoring. Ask one
@@ -73,18 +77,24 @@ Use the English equivalent when the user's first message is English.
 2. Scaffold the package shape from `references/package-schema.md`.
 3. Write strategy code against `getagent.*` imports only, plus allowed
    scientific/runtime packages documented in the schema.
-4. Validate locally:
+4. Validate locally (requires Python 3.11+; install PyYAML once with
+   `pip install pyyaml` if missing — without it the validator falls back to a
+   weaker parser):
 
    ```bash
-   conda activate get_agent_test
-   python "scripts/validate.py" ./my-strategy/
+   python3 scripts/validate.py ./my-strategy/
    ```
 
+   If validation fails, fix every reported issue and re-run until it prints
+   `Validation PASSED`. Never upload a package that fails local validation.
 5. Ask for the user's Bitget OpenAPI `ACCESS-KEY` only before the first
    authenticated upload/run/publish/enable call. Never write credentials to disk.
-6. Upload the package through the documented control-plane API.
+6. Upload the package through the documented control-plane API; uploads are
+   temporary iteration artifacts until confirmed.
 7. Run a sandbox evaluation before publish when the package supports backtests.
 8. Read results back in plain language before proposing publish or iteration.
+9. When the user accepts the final package, confirm the latest temporary as a
+   draft. Publish only after explicit user intent.
 
 ## Reference Map
 
@@ -93,11 +103,151 @@ Use the English equivalent when the user's first message is English.
 - Sandbox runtime and blocked imports: `references/sandbox-runtime.md`
 - Backtest engine behavior: `references/backtest-engine.md`
 - Control-plane APIs: `references/api/index.md`
-- Data SDK: `references/sdk/data/playbook-supported.md`
+- Data SDK domain index: `references/sdk/data/catalog.md`; high-frequency
+  domain files: `references/sdk/data/crypto.md`,
+  `references/sdk/data/equity.md`, `references/sdk/data/economy.md`,
+  `references/sdk/data/derivatives.md` (other domains via the catalog)
 - Trade SDK: `references/sdk/trade/patterns.md`
 - Backtest SDK: `references/sdk/backtest/catalog.md`
 - Runtime SDK: `references/sdk/runtime/catalog.md`
 - LLM SDK: `references/sdk/llm/catalog.md`
+- Runnable demo package: `examples/btc-ema-cross-demo/` (BTC EMA cross,
+  signal-only; used by option A of the opening)
+
+## 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`.
+
+## Data SDK Constraints
+
+Rules that apply every time `getagent.data` is used in Playbook code.
+
+### Before writing any data call
+
+1. Read `references/sdk.md` §`getagent.data` read order. Follow its links to
+   `references/sdk/data/catalog.md` (domain table), then open the matching
+   domain file (e.g. `references/sdk/data/crypto.md`).
+2. Locate the exact endpoint section and read its **Query parameters** table
+   and **Response fields** table before writing any code.
+3. Never invent endpoint names, namespaces, or keyword arguments by guessing
+   from plausible names. If the needed capability is absent, report missing
+   coverage instead of falling back to a direct HTTP client.
+
+### Symbol format
+
+There are **two separate symbol namespaces**. Always check the endpoint's
+parameter note to determine which one it expects.
+
+**Exchange-native format** — e.g. `"BTCUSDT"`, `"RAAPLUSDT"` (no slash,
+no colon). Used by all price / OHLCV / derivatives data endpoints:
+
+- `crypto.futures.kline`, `crypto.spot.kline`
+- `crypto.futures.funding_rate`, `crypto.futures.taker_volume`
+- `crypto.futures.open_interest`, `crypto.futures.long_short_ratio`
+- `crypto.spot.ticker`, `crypto.spot.taker_volume`, `crypto.spot.trades`
+- Most other time-series endpoints under `crypto.futures.*` and
+  `crypto.spot.*`
+
+This is the format used by `bitget_data` provider. Pass the symbol
+exactly as the exchange exposes it (e.g. `"BTCUSDT"`, `"RAAPLUSDT"`).
+
+**CCXT unified format** — e.g. `"BTC/USDT"` (spot), `"BTC/USDT:USDT"`
+(perpetual linear), `"BTC/USD:BTC"` (inverse). Used by the market
+metadata endpoint:
+
+- `crypto.market` — `symbol` filter param uses CCXT format; response
+  `symbol` field also returns CCXT format.
+  - ccxt provider: response `exchange_id` field returns the exchange-native ID.
+  - bitget_data provider: no `exchange_id` field; use `symbol` directly.
+
+**How to resolve an unknown symbol:**
+
+```python
+rows = data.crypto.market(symbol="BTC/USDT", exchange="bitget",
+                          market_type="perpetual").to_dataframe()
+# ccxt provider response:
+exchange_id = rows["exchange_id"].iloc[0]   # → "BTCUSDT"
+unified    = rows["symbol"].iloc[0]         # → "BTC/USDT:USDT"
+# bitget_data provider response: no exchange_id field;
+# use unified = rows["symbol"].iloc[0] directly
+```
+
+Use `exchange_id` (ccxt only) when calling kline / taker_volume / funding_rate etc.
+Use the `symbol` (unified) when passing to `manifest.trading_symbols` and
+`backtest.yaml` instruments.
+
+- Do not mix the two formats. Do not pass `"BTC/USDT:USDT"` to `kline`
+  and do not pass `"BTCUSDT"` to `crypto.market(symbol=...)`.
+- When the parameter note is ambiguous (just says "Symbol to get data for"),
+  default to exchange-native format for all `crypto.futures.*` /
+  `crypto.spot.*` endpoints.
+
+### Parameter compliance
+
+- Pass only parameters that appear in the endpoint's documented signature.
+  Never add undocumented kwargs.
+- Required parameters (marked `yes` in the table) must always be supplied.
+  Optional parameters with a documented default may be omitted.
+- Respect documented enum values exactly (e.g. `interval` must be one of
+  `5m`, `15m`, `1h`, `4h`, `1d` for kline endpoints; `market_type` must be
+  one of `spot`, `perpetual`, `future`, `option`).
+- For paginated endpoints, respect the documented maximum `size`/`limit`
+  (e.g. `size ≤ 200` for `crypto.market`, `limit ≤ 1000` for klines).
+  Loop over pages when more data is needed rather than requesting beyond
+  the cap.
+
+### Time ranges
+
+- Use `start_time` / `end_time` (millisecond Unix-epoch integers) in
+  preference to the deprecated `start_date` / `end_date` string params.
+- `crypto.futures.kline` and `crypto.spot.kline` cap **each request** at
+  **90 days** of data. This is a per-fetch API limit, not a backtest window
+  restriction — when the replay window is longer, fetch multiple 90-day
+  chunks and concatenate them.
+- The canonical datetime column in SDK responses is `time`. Call
+  `data.to_dataframe(bars)` without `datetime_index` to let the SDK pick it;
+  only override when the endpoint's response fields table names a different
+  time column (e.g. `date`).
+
+### Response handling
+
+- Always convert `OBBject` responses with `data.to_dataframe()`,
+  `data.to_dict()`, or `data.to_records()` before accessing individual fields.
+- Reference only field names that appear in the endpoint's **Response fields**
+  table. Never guess a field name from context.
+- Fields documented as `string` from market info endpoints (e.g.
+  `min_order_qty`, `price_precision`) are decimal strings, not floats.
+  Cast explicitly when arithmetic is needed.
+- Endpoints that return a context-only snapshot (no `time` column) cannot
+  be aligned into a replay feature frame. Use them as decision context only
+  and do not declare their fields in `backtest.yaml.data_requirements`.
+
+### Endpoint discovery
+
+- When in doubt which endpoint to use, read `catalog.md` for the domain
+  table, then read the domain file. Do not rely on memory or path guessing.
+- Domain files are large (crypto.md ≈ 4000 lines). Jump to an endpoint
+  section with grep instead of reading the whole file, e.g.
+  `grep -n "crypto.futures.funding_rate" references/sdk/data/crypto.md`,
+  then read that section's parameter and response tables.
+- `data.coverage.commands()` lists every available endpoint at runtime.
+  Use it programmatically if the domain file and catalog are insufficient.
+- CoinGecko-based endpoints (`crypto.coin_info`, `crypto.coin_history`, etc.)
+  accept a **CoinGecko coin ID** (e.g. `"bitcoin"`), not a trading-pair symbol.
+  Futures/spot kline endpoints accept trading-pair symbols. These are
+  different namespaces — do not mix them.
 
 ## Hard Boundaries
 
@@ -111,6 +261,19 @@ 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`, never pass `provider=...`, and ensure any
+  `data_requirements.required_bar_fields` are actually built and referenced in
+  `src/**`. The `execution.start` / `execution.end` replay window is entirely
+  the author's choice — the platform never polices window presence, length,
+  or recency; the only hard rule is that evidence must be real, never
+  fabricated.
+- 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/confirm.md

@@ -0,0 +1,59 @@
+# Confirm Playbook Draft
+
+Confirm the final temporary Playbook artifact and save it as a draft. Use this
+after the package has passed the required sandbox evaluation and the user agrees
+that this is the version to keep.
+
+## `POST /api/v1/playbook/confirm`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+**Content-Type**: `application/json`
+
+### Request
+
+```json
+{
+  "temporary_id": "temporary-playbook-id"
+}
+```
+
+For backward compatibility, the server also accepts `draft_id` or `playbook_id`
+with the same value.
+
+### Success Response
+
+```json
+{
+  "strategy_id": "strategy-...",
+  "draft_id": "draft-playbook-id",
+  "name": "btc-ema-crossover",
+  "status": "draft",
+  "suggested_version": "1.0.1"
+}
+```
+
+The id does not change during confirmation. The same package id that was used
+for the final backtest becomes the draft id used by `publish`.
+
+### When To Call
+
+Call `confirm` only after:
+
+1. local validation passed,
+2. required sandbox backtests completed successfully,
+3. you summarized the results for the user, and
+4. the user accepted this package as the final draft to keep.
+
+Do not confirm every failed iteration. Upload replaces older temporary artifacts
+automatically; confirm is the boundary where the final package becomes visible
+as a draft.
+
+### Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Missing `ACCESS-KEY` header |
+| 403 | Not the Playbook owner, access key revoked, or principal not found / inactive |
+| 404 | temporary id not found |
+| 409 | The package is neither `temporary` nor already `draft` |

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

@@ -11,19 +11,21 @@ Use these docs after the local package is ready. For Python imports inside
 
 ## Read order
 
-1. [`upload.md`](upload.md) — upload a packaged Playbook archive
-2. [`publish.md`](publish.md) — publish a validated Playbook
-3. [`run.md`](run.md) — trigger a manual backtest/evaluation run
-4. [`list.md`](list.md) and `detail` response docs — inspect public Playbooks
-5. [`enable.md`](enable.md) and [`my-playbooks.md`](my-playbooks.md) — manage
+1. [`upload.md`](upload.md) — upload a temporary packaged Playbook archive
+2. [`run.md`](run.md) — trigger a manual backtest/evaluation run
+3. [`confirm.md`](confirm.md) — save the final temporary artifact as a draft
+4. [`publish.md`](publish.md) — publish a validated draft Playbook
+5. [`list.md`](list.md) and `detail` response docs — inspect public Playbooks
+6. [`enable.md`](enable.md) and [`my-playbooks.md`](my-playbooks.md) — manage
    subscriptions
-6. [`error-responses.md`](error-responses.md) — common failure modes
+7. [`error-responses.md`](error-responses.md) — common failure modes
 
 ## Control-plane docs
 
 | Document | Purpose |
 |---|---|
-| [`upload.md`](upload.md) | Request format, package validation, and server-side checks |
+| [`upload.md`](upload.md) | Request format, package validation, temporary artifact behavior, and server-side checks |
+| [`confirm.md`](confirm.md) | Convert the accepted temporary artifact into a draft |
 | [`publish.md`](publish.md) | Publish contract, evidence requirements, and 409 cases |
 | [`run.md`](run.md) | Manual run contract and runtime gating |
 | [`list.md`](list.md) | Public list surface |

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

@@ -1,7 +1,7 @@
 # Publish Playbook
 
-Publish a draft Playbook to make it publicly available. Publishing is the only
-step that assigns the formal public version number.
+Publish a confirmed draft Playbook to make it publicly available. Publishing is
+the only step that assigns the formal public version number.
 
 ## `POST /api/v1/playbook/publish`
 
@@ -22,6 +22,10 @@ step that assigns the formal public version number.
 `minor`, and `major`. The server computes the final semver from the strategy's
 latest published version; clients must not edit `manifest.version` manually.
 
+New clients should call [`confirm.md`](confirm.md) before publish. For backward
+compatibility, publishing a temporary id directly is accepted and the server
+internally confirms it before assigning the published version.
+
 ### Success Response
 
 ```json
@@ -40,9 +44,9 @@ Only the Playbook owner can publish. Others receive 403.
 
 ### Publish Contract
 
-Publishing freezes the draft artifact into an immutable version and records its
-parent version within the same strategy tree. A published Playbook should carry a
-stable public contract for:
+Publishing freezes the confirmed draft artifact into an immutable version and
+records its parent version within the same strategy tree. A published Playbook
+should carry a stable public contract for:
 
 - `decision_mode`
 - `backtest_support`
@@ -55,6 +59,9 @@ 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 —
+    this is an anti-fabrication check, not a window check: curve density,
+    window length, and recency are never validated
   - 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`
@@ -73,4 +80,4 @@ performance is not.
 | 401 | Missing `ACCESS-KEY` header |
 | 403 | Not the Playbook owner, access key revoked, or principal not found / inactive |
 | 404 | draft_id not found |
-| 409 | Status is not draft; no successful historical evaluation exists for `backtest_support=full`; or runtime profile is not currently publishable |
+| 409 | Status is not draft/temporary; no successful historical evaluation exists for `backtest_support=full`; or runtime profile is not currently publishable |

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

@@ -14,13 +14,13 @@ the run reaches `completed` or `failed`.
 
 ```json
 {
-  "version_id": "draft-or-version-id"
+  "version_id": "temporary-draft-or-version-id"
 }
 ```
 
 ### Supported Use Cases
 
-- creator runs a draft or published Playbook to validate a new version
+- creator runs a temporary, draft, or published Playbook to validate a new version
 - any authenticated user runs a published Playbook evaluation when `backtest_support = full`
 
 ### Backtest Eligibility
@@ -40,7 +40,7 @@ fairly replayable on historical data.
 {
   "run_id": "e5f6g7h8-...",
   "strategy_id": "strategy-...",
-  "version_id": "draft-or-version-id",
+  "version_id": "temporary-draft-or-version-id",
   "status": "pending",
   "dispatched": true
 }
@@ -125,9 +125,9 @@ public backtest.
 
 ### Permissions
 
-- Owner can run draft and published Playbooks they control
+- Owner can run temporary, draft, and published Playbooks they control
 - Any authenticated user can run published Playbooks when `backtest_support = full`
-- Users must not be allowed to run draft versions they do not own
+- Users must not be allowed to run temporary or draft versions they do not own
 
 ### Error Responses
 

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

@@ -1,6 +1,6 @@
 # Upload Playbook
 
-Upload a Playbook package draft to GetAgent Cloud.
+Upload a Playbook package to GetAgent Cloud as a temporary iteration artifact.
 
 > Before dispatching this call, follow the **Endpoint Confirmation Discipline** in `SKILL.md` — echo a one-line preflight (`upload draft {name} → GetAgent prod https://api.bitget.com with ACCESS-KEY=<masked>`) and obtain the user's Bitget OpenAPI `ACCESS-KEY` if not already collected this session.
 
@@ -30,13 +30,31 @@ curl -X POST \
 ```json
 {
   "strategy_id": "strategy-...",
-  "draft_id": "draft-...",
+  "draft_id": "temporary-playbook-id",
   "name": "btc-ema-crossover",
-  "status": "draft",
+  "status": "temporary",
   "suggested_version": "1.0.1"
 }
 ```
 
+`draft_id` is the package id to pass to `run` during this iteration. It is
+named `draft_id` for backward compatibility, but uploads now remain temporary
+until confirmed.
+
+### Temporary Artifact Behavior
+
+- Every upload is persisted because backtests are asynchronous and run by
+  workers that load the package later by id.
+- When a newer package for the same strategy is uploaded, GetAgent deletes the
+  previous temporary package record and package archive after any active run has
+  finished.
+- Temporary packages are hidden from user-facing draft lists and "my creations".
+- Once the package is final and acceptable to the user, call
+  [`confirm.md`](confirm.md) to convert the latest temporary package into a
+  real draft.
+- Publishing a temporary package directly is accepted for older clients, but new
+  clients should call `confirm` before `publish` so the workflow is explicit.
+
 ### Server-side Validation
 
 The server runs these checks on upload (client-side validation is not trusted):
@@ -49,7 +67,7 @@ The server runs these checks on upload (client-side validation is not trusted):
 6. **backtest.yaml shape** — only valid when `backtest_support: full`; basic type checks enforced
 7. **Syntax** — Python files under `src/**` must compile
 8. **Import allowlist** — Only `getagent`, `pandas`, `numpy`, `json`, `math`, `datetime`, `pathlib`, `asyncio`, etc. Imports like `requests`, `subprocess`, `os` are blocked.
-9. **Version assignment** — upload never consumes a public version. The server returns a `draft_id`; the formal version is assigned later by `publish`.
+9. **Version assignment** — upload never consumes a public version. The server returns a temporary `draft_id`; the formal version is assigned later by `publish`.
 10. **Local-only paths rejected** — `tests/`, `research/`, `data/`, `output/`, caches and virtualenv folders must not be included
 
 ### Error Responses