desic-okx-agent 0.3.0 → 0.3.2

package/dist/tui/file-completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-completion.js","sourceRoot":"","sources":["../../src/tui/file-completion.ts"],"names":[],"mappings":"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"}

package/docs/strategy-research.md

@@ -199,9 +199,7 @@ desic-okx strategy validate --file ema.py
 
 ### 多周期
 
-```bash
-desic-okx strategy backtest --file s.py --inst BTC-USDT-SWAP --intervals 30m,1H
-```
+**直接写就行，不需要声明。** 引擎会读你的源码，把 `ctx.market.bars(..., "30m")` 里出现的周期自动加进来：
 
 ```python
 buckets = ctx.market.bars(ctx.instrument_id, "30m", lookback=2)
@@ -209,8 +207,32 @@ if not buckets[-1].confirmed:
     return ctx.no_action("等 30m 收线")
 ```
 
+```bash
+desic-okx strategy backtest --file s.py --inst BTC-USDT-SWAP    # 30m 自动派生
+```
+
+报告的 `assumptions.intervals` 记录的是**实际派生的**那些，不是你请求的 —— 所以你能核对引擎理解得对不对。
+
+`--intervals` 仍然保留，用于**周期名是算出来的**情况 —— 那种源码里读不出来：
+
+```python
+chosen = ctx.params.get("tf", "15m")        # 读不出来
+ctx.market.bars(ctx.instrument_id, chosen)  # 需要 --intervals 15m
+```
+
 注意：`ctx.indicators` 只接受 `1m`。高周期的当前桶在确认前还可能被修正，用它做增量指标状态，缓存值会悄悄依赖于"第一次算的时间点"。
 
+### 只要尾部就一定传 `lookback`
+
+`ctx.market.bars()` 的开销取决于你要多少根，**传了 `lookback` 就只付那么多**。省略它会返回至今全部可见 K 线，而这个方法每根收线都会被调一次 —— 长窗口下这是"几秒"和"几分钟"的差别。
+
+```python
+bars = ctx.market.bars(ctx.instrument_id, "1m", lookback=period + 3)   # 只付 period+3
+bars = ctx.market.bars(ctx.instrument_id, "1m")                        # 26 万根全拿
+```
+
+只用 `ctx.indicators.*` 的策略完全不碰这条路径 —— 指标是增量维护的。
+
 ### 看不到未来
 
 `ctx.market.bars()` 只暴露到当前可见长度，物理上取不到之后的 K 线。任何可见 K 线的 `closeTime ≤ ctx.as_of_ms`。测试里专门构造了"能看到未来就会盈利"的策略，断言它无法盈利。
@@ -509,6 +531,8 @@ MCP 工具（`desic-okx setup` 会自动为 Codex 和 Claude Code 装好）：
 | `strategy_run_optimize` | 参数搜索，入队 |
 | `strategy_get_optimization` | 排名后的候选表，含训练/验证指标 |
 | `strategy_compare_runs` | 多运行对比，含差异参数与警告 |
+| `strategy_open_report` | 生成单次运行的 HTML 报告并在浏览器打开 |
+| `strategy_open_comparison` | 同上，多运行对比，叠加权益曲线 |
 | `strategy_get_run` | 状态、进度、汇总指标 |
 | `strategy_get_run_equity` / `_trades` / `_actions` | 分页读明细 |
 | `strategy_settings` / `_update` | 读写回测参数 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "desic-okx-agent",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Independent Desic runtime, MCP server, CLI, and agent skills for OKX",
   "type": "module",
   "license": "MIT",

package/python/desic_strategy/context.py

@@ -24,19 +24,24 @@ class ContextError(Exception):
 class MarketView:
     """Point-in-time K-line access across derived timeframes."""
 
-    __slots__ = ("_aggregates", "_instrument_id", "_minutes", "_visible")
+    __slots__ = ("_aggregates", "_aggregators", "_instrument_id", "_minutes", "_visible")
 
     def __init__(
         self,
         instrument_id: str,
         minutes: list[Bar],
         visible: int,
-        aggregates: Mapping[str, tuple[Bar, ...]],
+        aggregates: Mapping[str, tuple[Bar, ...]] | None = None,
+        aggregators: Mapping[str, TimeframeAggregator] | None = None,
     ) -> None:
         self._instrument_id = instrument_id
         self._minutes = minutes
         self._visible = visible
-        self._aggregates = aggregates
+        # Either form works. `aggregators` applies a lookback before the tuple is built,
+        # which is the cheap path; `aggregates` keeps a caller that already holds
+        # snapshots working unchanged.
+        self._aggregates = aggregates or {}
+        self._aggregators = aggregators or {}
 
     def bars(self, instrument_id: str, interval: str = "1m", lookback: int | None = None) -> tuple[Bar, ...]:
         if instrument_id != self._instrument_id:
@@ -44,18 +49,28 @@ class MarketView:
                 f"Market data is available for {self._instrument_id}, not {instrument_id}"
             )
         interval_ms(interval)
-        if interval == "1m":
-            series: tuple[Bar, ...] = tuple(self._minutes[: self._visible])
-        else:
-            found = self._aggregates.get(interval)
-            if found is None:
-                raise ContextError(f"Series '{interval}' is not available in this run")
-            series = found
-        if lookback is None:
-            return series
-        if not isinstance(lookback, int) or isinstance(lookback, bool) or lookback <= 0:
+        if lookback is not None and (
+            not isinstance(lookback, int) or isinstance(lookback, bool) or lookback <= 0
+        ):
             raise ValueError("lookback must be a positive integer")
-        return series[-lookback:]
+        if interval == "1m":
+            # Sliced before the copy, not after. `_minutes` holds the whole run, so
+            # copying the visible prefix and then discarding all but the tail costs one
+            # copy of everything seen so far, on every bar — quadratic in the window
+            # length. Measured on a 260k-bar run: a strategy asking for 17 bars here
+            # took 576 us/bar, against 16 us/bar for one that never called this method.
+            stop = self._visible
+            start = 0 if lookback is None else max(0, stop - lookback)
+            return tuple(self._minutes[start:stop])
+        # The aggregator path slices before building the tuple, so a lookback costs the
+        # window rather than every bucket accumulated so far.
+        aggregator = self._aggregators.get(interval)
+        if aggregator is not None:
+            return aggregator.tail(lookback)
+        found = self._aggregates.get(interval)
+        if found is None:
+            raise ContextError(f"Series '{interval}' is not available in this run")
+        return found if lookback is None else found[-lookback:]
 
 
 class StrategyContext:
@@ -162,3 +177,13 @@ class SeriesSet:
 
     def snapshot(self) -> dict[str, tuple[Bar, ...]]:
         return {interval: agg.snapshot() for interval, agg in self._aggregators.items()}
+
+    @property
+    def aggregators(self) -> Mapping[str, TimeframeAggregator]:
+        """The live aggregators, for a reader that wants only a tail.
+
+        Handed over instead of a snapshot so the slice happens before the tuple is
+        built. Materializing every bucket on every bar is the cost this avoids; the
+        aggregators are only read through `tail`, which returns a new tuple.
+        """
+        return self._aggregators

package/python/desic_strategy/engine.py

@@ -236,7 +236,10 @@ class Engine:
 
     def _context(self, bar: Bar, visible: int, bars: list[Bar], series: SeriesSet) -> StrategyContext:
         instrument = self._config.instrument
-        market = MarketView(instrument.inst_id, bars, visible, series.snapshot())
+        # Aggregators rather than snapshots: this runs once per bar, and materializing
+        # every derived bucket here cost 14.5 us/bar at 4,000 buckets against 1.9 us/bar
+        # for the tail a strategy actually reads.
+        market = MarketView(instrument.inst_id, bars, visible, aggregators=series.aggregators)
         return StrategyContext(
             kind="bar",
             as_of_ms=bar.close_time_ms,

package/python/desic_strategy/live.py

@@ -133,7 +133,7 @@ class LiveSession:
             instrument_id=self._instrument_id,
             interval="1m",
             bar=bar,
-            market=MarketView(self._instrument_id, self._bars, len(self._bars), self._series.snapshot()),
+            market=MarketView(self._instrument_id, self._bars, len(self._bars), aggregators=self._series.aggregators),
             portfolio=portfolio,
             params=self._params,
             indicators=IndicatorView(self._series.indicators, self._instrument_id, len(self._bars)),

package/python/desic_strategy/policy.py

@@ -191,3 +191,54 @@ def _check_handlers(tree: ast.Module) -> list[PolicyViolation]:
                     )
                 )
     return found
+
+
+def discover_intervals(source: str) -> tuple[list[str], bool]:
+    """Finds the higher timeframes a strategy reads, from the source alone.
+
+    Higher timeframes are aggregated incrementally: an aggregator has to see every
+    one-minute bar from the start, so one cannot be created partway through a run.
+    Declaring them was therefore a real requirement — but the declaration duplicated
+    something the source already states, and getting it wrong failed at bar one with
+    "Series '15m' is not available in this run".
+
+    Returns the intervals found as literals, and whether any call could not be read
+    statically. A `bars(id, chosen)` where `chosen` is computed cannot be resolved
+    here, so the caller keeps the explicit list as the way to cover that.
+
+    Deliberately syntactic. It matches `.bars(...)` by attribute name and takes only
+    string literals in the interval position, so it never runs strategy code and
+    cannot be tricked into reporting an interval that will not be requested. Over-
+    reporting is harmless (an unused aggregator costs one pass over the bars);
+    under-reporting is what the returned flag warns about.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return [], False
+
+    found: set[str] = set()
+    dynamic = False
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        function = node.func
+        if not isinstance(function, ast.Attribute) or function.attr != "bars":
+            continue
+        argument = _interval_argument(node)
+        if argument is None:
+            continue
+        if isinstance(argument, ast.Constant) and isinstance(argument.value, str):
+            found.add(argument.value)
+        else:
+            dynamic = True
+    return sorted(item for item in found if item != "1m"), dynamic
+
+
+def _interval_argument(node: ast.Call) -> ast.expr | None:
+    """The interval argument of a `bars` call, positional or by keyword."""
+    for keyword in node.keywords:
+        if keyword.arg == "interval":
+            return keyword.value
+    # bars(instrument_id, interval, ...) — the instrument is first.
+    return node.args[1] if len(node.args) > 1 else None

package/python/desic_strategy/runner.py

@@ -21,7 +21,7 @@ from .actions import StrategyError
 from .engine import Costs, Engine, Instrument, RunConfig, Sizing
 from .indicators import IndicatorError
 from .live import LiveSession, parse_portfolio
-from .policy import validate_source
+from .policy import discover_intervals, validate_source
 from .report import build_report, calculate_metrics
 from .timeframe import Bar, DataContractError, ONE_MINUTE_MS, interval_ms
 
@@ -170,7 +170,7 @@ def _backtest(request: dict[str, Any]) -> dict[str, Any]:
     bars = _parse_bars(request.get("bars"))
     config = _parse_config(request)
     params = dict(request.get("params") or {})
-    intervals = _parse_intervals(request.get("intervals"))
+    intervals = _parse_intervals(request.get("intervals"), source)
     handlers = _load_handlers(source)
 
     total = len(bars)
@@ -182,6 +182,10 @@ def _backtest(request: dict[str, Any]) -> dict[str, Any]:
         "protocol": PROTOCOL_VERSION,
         "barCount": total,
         "preloadBars": config.preload_bars,
+        # Reported because the engine resolves this, not the caller: intervals read from
+        # the source are added to whatever was requested, so the request is no longer
+        # what the run used. A report naming the request would state the wrong thing.
+        "intervals": intervals,
         "report": report,
     }
 
@@ -224,7 +228,7 @@ def _live(request: dict[str, Any]) -> int:
         _emit({"ok": False, "error": {"code": "bad_request", "message": "instrument.instId is required"}})
         return 2
     instrument_id = str(instrument_raw["instId"])
-    intervals = _parse_intervals(request.get("intervals"))
+    intervals = _parse_intervals(request.get("intervals"), source)
     handlers = _load_handlers(source)
     session = LiveSession(instrument_id, handlers, dict(request.get("params") or {}), intervals)
 
@@ -309,7 +313,7 @@ def _optimize(request: dict[str, Any]) -> dict[str, Any]:
 
     bars = _parse_bars(request.get("bars"))
     base_config = _parse_config(request)
-    intervals = _parse_intervals(request.get("intervals"))
+    intervals = _parse_intervals(request.get("intervals"), source)
     handlers = _load_handlers(source)
     segments = _parse_segments(request.get("segments"), len(bars))
     candidates = _parse_candidates(request.get("candidates"))
@@ -470,17 +474,40 @@ def _parse_bars(value: Any) -> list[Bar]:
     return bars
 
 
-def _parse_intervals(value: Any) -> list[str]:
-    if value is None:
-        return ["1m"]
-    if not isinstance(value, list):
+def _parse_intervals(value: Any, source: str | None = None) -> list[str]:
+    """Resolves which timeframes to aggregate for a run.
+
+    Anything the request names is honoured, and anything the source visibly reads is
+    added to it. Requiring the declaration meant a strategy calling
+    `ctx.market.bars(id, "15m")` failed on its first bar over a fact its own source
+    already stated. Reading it instead removes a step that could only be got wrong.
+
+    The request still matters. A timeframe reached through a computed name cannot be
+    found by reading the source, so naming it explicitly remains the way to cover
+    that; and an interval named but never used costs only one pass over the bars.
+    """
+    if value is not None and not isinstance(value, list):
         raise DataContractError("'intervals' must be an array of interval names")
     intervals = ["1m"]
-    for item in value:
+    for item in value or []:
         name = str(item)
         interval_ms(name)
         if name not in intervals:
             intervals.append(name)
+    if source is not None:
+        discovered, _ = discover_intervals(source)
+        for name in discovered:
+            # Validated like a declared one, but named as read from the source: the
+            # strategy would reach that line and fail anyway, so failing now with the
+            # reason is strictly better than failing on bar one without it.
+            try:
+                interval_ms(name)
+            except DataContractError as error:
+                raise DataContractError(
+                    f"The strategy reads interval '{name}', which cannot be aggregated. {error}"
+                ) from error
+            if name not in intervals:
+                intervals.append(name)
     return intervals
 
 

package/python/desic_strategy/timeframe.py

@@ -139,6 +139,23 @@ class TimeframeAggregator:
             return tuple(self._completed)
         return (*self._completed, self._current)
 
+    def tail(self, lookback: int | None) -> tuple[Bar, ...]:
+        """The last `lookback` buckets, or all of them when it is None.
+
+        Sliced before the tuple is built. `snapshot()` copies every accumulated bucket,
+        and it is called once per one-minute bar, so a 180-day run over 15m and 1H
+        rebuilt ~21,600 elements 260,000 times. Measured at 4,000 buckets: 14.5 us/bar
+        for the full snapshot against 1.9 us/bar for a 96-bucket tail.
+        """
+        if lookback is None:
+            return self.snapshot()
+        if self._current is None:
+            return tuple(self._completed[-lookback:])
+        # The forming bucket occupies one slot of the requested window.
+        if lookback <= 1:
+            return (self._current,)
+        return (*self._completed[-(lookback - 1):], self._current)
+
     def latest(self) -> Bar | None:
         return self._current
 

package/skills/okx-strategy-research/SKILL.md

@@ -77,6 +77,29 @@ describe a backtest result as expected future return.
 When `marginExhausted` is true, say the run hit its simulated collateral limit
 and that this is a research risk boundary, not an OKX liquidation estimate.
 
+### Offer the visual report
+
+After reporting the numbers for a completed backtest, call `strategy_open_report`
+with its `runId`. It writes a standalone HTML file and opens it in the operator's
+browser: the equity curve, the drawdown shape, and where the trades landed. Those
+are the parts of a result that are read as a picture rather than as figures — an
+equity curve is tens of thousands of points, and paging it into the conversation
+would cost a great deal and show less.
+
+Say the file was opened, and give the path as well: a browser may not launch in
+every environment, and `opened: false` means the file is written but the operator
+has to open it.
+
+For two or more runs use `strategy_open_comparison`, which overlays the curves and
+lists the assumptions that differ. Repeat its `warnings` in your own reply rather
+than leaving them in the document — two runs over different data, instruments,
+windows, or costs are not two answers to one question, and the operator who
+switches to the browser should not be the only one who learns that.
+
+Do not open a report for a run that failed or was cancelled; report the error
+instead. There is no curve to show and the file would be empty of the thing it
+exists for.
+
 ## Judging a result
 
 A high trade count with a profit factor near or below 1 usually means fees

package/skills/okx-strategy-research/references/python-api.md

@@ -37,6 +37,17 @@ bars = ctx.market.bars(ctx.instrument_id, "1m", lookback=240)
 intervals are `1m`, `3m`, `5m`, `15m`, `30m`, `1H`, `2H`, `4H`, `6H`, `12H`, and
 `1D`, but a higher timeframe must be requested for the run before it is readable.
 
+Always pass `lookback` when only a tail is needed. It costs the size of the window
+asked for, whereas omitting it copies every bar seen so far on every call — on a
+long run that is the difference between a few seconds and a few minutes.
+
+A higher timeframe does not have to be declared on the request. The engine reads the
+source and aggregates whatever interval a `bars` call names, so writing
+`ctx.market.bars(id, "15m")` is enough. The run's `assumptions.intervals` reports what
+was actually aggregated, which is what to quote. An interval built at runtime —
+`bars(id, ctx.params["tf"])` — cannot be read from the source, so that case still needs
+`intervals` on the request.
+
 `Bar` fields: `openTimeMs`, `closeTimeMs`, `open`, `high`, `low`, `close`,
 `volume`, `confirmed`.
 

package/skills/okx-strategy-research/references/tools-and-data.md

@@ -30,9 +30,16 @@ There is no `bar` parameter on any data tool.
 | `strategy_get_run_trades` | Paged closed trades. |
 | `strategy_get_run_actions` | Paged decisions the strategy emitted. |
 | `strategy_compare_runs` | Two or more runs side by side, with the assumptions that differ and comparability warnings. |
+| `strategy_open_report` | Write a standalone HTML report for one run and open it in the operator's browser. |
+| `strategy_open_comparison` | The same for two or more runs, overlaying their equity curves. |
 | `strategy_cancel_run` | Cancel a queued or running run. |
 | `strategy_delete_run` | Delete a run and its stored series. Confirm with the user first. |
 
+Both `open_*` tools return `{ file, opened }`. `opened: false` means the document was
+written but no browser launched, so give the path either way. Pass `open: false` to
+write without launching. `strategy_open_comparison` also returns `warnings`, which
+belong in your reply and not only in the document.
+
 ## Check coverage before backtesting
 
 ```