Skip to content

"Vibe-Trading: Your Personal Trading Agent"

docs(paper-trade): describe 5m order statuses and limit fills as shipped

Haozhe Wue245d3fd94a4
diff --git a/agent/src/tools/paper_trade/README.md b/agent/src/tools/paper_trade/README.md
index 3dde73971..2fc0e2747 100644
--- a/agent/src/tools/paper_trade/README.md
+++ b/agent/src/tools/paper_trade/README.md
@@ -119,11 +119,13 @@ buy, `ref > limit` for a sell) fills at that strictly better price instead,
which wins over the 委托价 even when the bar also crosses. Every fill is
all-or-none; volume share is Phase 3.
-Order statuses use JoinQuant's `OrderStatus` vocabulary for both intervals:
-`filled` means partially filled and still active, so the residual stays in
-`open_orders()` and can be canceled, settled or matched by a later bar; `held`
-means fully filled and terminal. `canceled` and `rejected` are also terminal;
-`new`, `open` and `pending_cancel` are not.
+Inside the five-minute session (the daily path builds no order book), order
+statuses use JoinQuant's `OrderStatus` vocabulary: `held` means fully filled
+and terminal, `canceled` and `rejected` are also terminal, and `new`, `open`
+and `pending_cancel` are not. JoinQuant's `filled` (partially filled, residual
+still in `open_orders()`) exists in the lifecycle but is not reached while
+every fill is all-or-none. These statuses are internal; no result field or
+surface exposes them.
The 5m leg uses Tushare `stk_mins` and is resolved separately from the daily
chain: Tencent's raw loader serves daily bars only. The measured provider limit
diff --git a/agent/src/tools/paper_trade/paper_trade_step-v1.2.json b/agent/src/tools/paper_trade/paper_trade_step-v1.2.json
index 90610411e..ba08d2bca 100644
--- a/agent/src/tools/paper_trade/paper_trade_step-v1.2.json
+++ b/agent/src/tools/paper_trade/paper_trade_step-v1.2.json
@@ -1,5 +1,5 @@
{
- "$comment": "FINALIZED pt-v1.2 — ADDITIVE bump of the frozen pt-v1.1 contract (schema/tool_contracts/paper_trade_step-v1.1.json, which is NOT edited). Scope: the cn_a 5m post-close step (P0 execution plan T2), decisions D1-D8 of the paper-trade-p0-5m-execution decision record. Additions only (REQUIREMENTS §9: additive = minor bump): request-side interval/session/path_model/fill_model are all optional and default to the pt-v1.1 semantics (1d/auto/bar_median/all_or_none); result-side engine_fingerprint/canceled_orders/events are emitted ONLY for a v1.2 call, where v1.2 means at least one new request field is non-default. A call that omits every new field is a pt-v1.1 call: identical bytes, identical received_state_hash, schema_version 'pt-v1.1' (D4/D8). PHASE-2 SEMANTICS: pt-v1.2 adds NO order-level bar/timestamp field, so a fill is attributed to the bar whose reference price produced it, not to a client order timestamp. For interval='5m' the engine matches bar by bar over the 48 continuous bars; a market order fills at the first marketable bar, a limit order rests and is canceled at session end if never marketable, and no partial fills or volume share are modeled (Phase 3). HK/US 5m is out of scope. The dependency-free validator in agent/src/tools/paper_trade/schema.py implements a keyword subset (type/const/enum/required/properties/items/additionalProperties) and ignores the version-gated allOf/if/then block in the result schema; pattern/minLength are documentation for the real jsonschema library, which can consume this standard draft-2020-12 document.",
+ "$comment": "FINALIZED pt-v1.2 — ADDITIVE bump of the frozen pt-v1.1 contract (schema/tool_contracts/paper_trade_step-v1.1.json, which is NOT edited). Scope: the cn_a 5m post-close step (P0 execution plan T2), decisions D1-D8 of the paper-trade-p0-5m-execution decision record. Additions only (REQUIREMENTS §9: additive = minor bump): request-side interval/session/path_model/fill_model are all optional and default to the pt-v1.1 semantics (1d/auto/bar_median/all_or_none); result-side engine_fingerprint/canceled_orders/events are emitted ONLY for a v1.2 call, where v1.2 means at least one new request field is non-default. A call that omits every new field is a pt-v1.1 call: identical bytes, identical received_state_hash, schema_version 'pt-v1.1' (D4/D8). PHASE-2 SEMANTICS: pt-v1.2 adds NO order-level bar/timestamp field, so a fill is attributed to the bar whose reference price produced it, not to a client order timestamp. For interval='5m' the engine matches bar by bar over the 48 continuous bars; a market order fills at the first marketable bar, a resting limit order fills at its limit price once a bar trades strictly through it (pt-rules-v2; on the first continuous bar a strictly better reference price fills at that price) and is canceled at session end if never triggered, and no partial fills or volume share are modeled (Phase 3). HK/US 5m is out of scope. The dependency-free validator in agent/src/tools/paper_trade/schema.py implements a keyword subset (type/const/enum/required/properties/items/additionalProperties) and ignores the version-gated allOf/if/then block in the result schema; pattern/minLength are documentation for the real jsonschema library, which can consume this standard draft-2020-12 document.",
"contract": "paper_trade_step",
"version": "pt-v1.2",
"status": "final",
diff --git a/schema/tool_contracts/paper_trade_step-v1.2.json b/schema/tool_contracts/paper_trade_step-v1.2.json
index 90610411e..ba08d2bca 100644
--- a/schema/tool_contracts/paper_trade_step-v1.2.json
+++ b/schema/tool_contracts/paper_trade_step-v1.2.json
@@ -1,5 +1,5 @@
{
- "$comment": "FINALIZED pt-v1.2 — ADDITIVE bump of the frozen pt-v1.1 contract (schema/tool_contracts/paper_trade_step-v1.1.json, which is NOT edited). Scope: the cn_a 5m post-close step (P0 execution plan T2), decisions D1-D8 of the paper-trade-p0-5m-execution decision record. Additions only (REQUIREMENTS §9: additive = minor bump): request-side interval/session/path_model/fill_model are all optional and default to the pt-v1.1 semantics (1d/auto/bar_median/all_or_none); result-side engine_fingerprint/canceled_orders/events are emitted ONLY for a v1.2 call, where v1.2 means at least one new request field is non-default. A call that omits every new field is a pt-v1.1 call: identical bytes, identical received_state_hash, schema_version 'pt-v1.1' (D4/D8). PHASE-2 SEMANTICS: pt-v1.2 adds NO order-level bar/timestamp field, so a fill is attributed to the bar whose reference price produced it, not to a client order timestamp. For interval='5m' the engine matches bar by bar over the 48 continuous bars; a market order fills at the first marketable bar, a limit order rests and is canceled at session end if never marketable, and no partial fills or volume share are modeled (Phase 3). HK/US 5m is out of scope. The dependency-free validator in agent/src/tools/paper_trade/schema.py implements a keyword subset (type/const/enum/required/properties/items/additionalProperties) and ignores the version-gated allOf/if/then block in the result schema; pattern/minLength are documentation for the real jsonschema library, which can consume this standard draft-2020-12 document.",
+ "$comment": "FINALIZED pt-v1.2 — ADDITIVE bump of the frozen pt-v1.1 contract (schema/tool_contracts/paper_trade_step-v1.1.json, which is NOT edited). Scope: the cn_a 5m post-close step (P0 execution plan T2), decisions D1-D8 of the paper-trade-p0-5m-execution decision record. Additions only (REQUIREMENTS §9: additive = minor bump): request-side interval/session/path_model/fill_model are all optional and default to the pt-v1.1 semantics (1d/auto/bar_median/all_or_none); result-side engine_fingerprint/canceled_orders/events are emitted ONLY for a v1.2 call, where v1.2 means at least one new request field is non-default. A call that omits every new field is a pt-v1.1 call: identical bytes, identical received_state_hash, schema_version 'pt-v1.1' (D4/D8). PHASE-2 SEMANTICS: pt-v1.2 adds NO order-level bar/timestamp field, so a fill is attributed to the bar whose reference price produced it, not to a client order timestamp. For interval='5m' the engine matches bar by bar over the 48 continuous bars; a market order fills at the first marketable bar, a resting limit order fills at its limit price once a bar trades strictly through it (pt-rules-v2; on the first continuous bar a strictly better reference price fills at that price) and is canceled at session end if never triggered, and no partial fills or volume share are modeled (Phase 3). HK/US 5m is out of scope. The dependency-free validator in agent/src/tools/paper_trade/schema.py implements a keyword subset (type/const/enum/required/properties/items/additionalProperties) and ignores the version-gated allOf/if/then block in the result schema; pattern/minLength are documentation for the real jsonschema library, which can consume this standard draft-2020-12 document.",
"contract": "paper_trade_step",
"version": "pt-v1.2",
"status": "final",