paper-test

SKILL.md

---
name: stocki-trading-assistant
version: 0.1.0
description: "Paper trading (simulated) for CN/HK/US equities — place/cancel orders, query balance and positions, order/fill history, market session status. Quotes via Stocki gateway."
metadata:
  openclaw:
    emoji: "💹"
    requires:
      bins: [python3]
      env: [STOCKI_GATEWAY_URL, STOCKI_API_KEY]
      os: [linux, darwin]
    primaryEnv: STOCKI_API_KEY
    envVars: [STOCKI_GATEWAY_URL, STOCKI_API_KEY]
---

# stocki-trading-assistant

Paper trading for CN / HK / US equities. The skill wraps a locally-spawned
`paper-trading` service; the service is auto-started on first use. Orders,
positions, and fills are **simulated** — not a live brokerage account.

This file instructs the **Agent**. Do not quote implementation details
(tokens, ports, file paths, script names) to the user unless they are
explicitly troubleshooting via `INSTALL.md`.

## Core principle

**Use this skill** when the user wants simulated trading — place or cancel
orders, check balance/positions/P&L, order or fill history, market session
status.

**Do NOT use** for real-money brokerage execution or personalized buy/sell
recommendations.

**Never fabricate** balances, positions, fills, or order states. If a value
is missing or the service is down, say so.

**Paper only.** Remind the user when relevant that fills are simulated and
not investment advice.

## Local API convention

All API calls go through `scripts/_http.py` `Client()` — do not hand-build
curl with a fixed port or read auth material for the user.

- **Base URL & port**: `Client()` reads `state/port` (lifecycle may pick
  8000–8010). Do not hardcode `:8000` in user-visible text.
- **Auth**: `Client()` reads `state/token` and sends Bearer automatically.
  Never ask the user for this token or mention `PAPER_TRADING_TOKEN`.
- **Stocki quotes** — same v3 API; quote upstream `auth` in `config/main.yaml` selects credentials:
  - `bearer`: `STOCKI_GATEWAY_URL` + `STOCKI_API_KEY` (export / SkillHub)
  - `none`: `STOCKI_GATEWAY_URL` only (private gateway, auth: none)
  Precedence: process env → optional skill-root `.env`. Never paste API keys in chat.
- **Content-Type**: `application/json` for POST bodies.
- **Error envelope**: `{"error": {"code", "message", "recovery_hint", ...}}`.
  `_http.py` maps `recovery_hint` — see [Error handling](#error-handling).

## Routing rules

Decide which reference to consult by user intent. Each rule names the
reference file containing the contract, error mapping, and worked examples.

- **R1 — place order.** Triggers: "买", "卖", "buy", "sell", "下单",
  "place order", "market buy", "limit sell". → `references/place-order.md`.
  Calls `POST /v1/orders` via `scripts/_http.py`.

- **R2 — cancel order.** Triggers: "撤单", "取消", "cancel", "撤掉".
  → `references/cancel-order.md`. Calls `DELETE /v1/orders/{order_id}`.

- **R3 — account state.** Triggers: "余额", "持仓", "盈亏", "balance",
  "positions", "P&L". → `references/account-state.md`. Calls
  `GET /v1/accounts/{id}` and `GET /v1/accounts/{id}/positions`.

- **R4 — order history.** Triggers: "历史订单", "查订单 ord_xxx",
  "order history", "list orders". → `references/order-history.md`.
  `GET /v1/accounts/{id}/orders`, `GET /v1/orders/{id}`.

- **R5 — fills.** Triggers: "成交", "fills", "成交记录".
  → `references/fill-history.md`. `GET /v1/accounts/{id}/fills`.

- **R6 — market status.** Triggers: "市场", "开盘", "收盘", "market status",
  "open?". → `references/market-status.md`. `GET /v1/capabilities` and
  `GET /v1/markets/{m}/status`.

- **R7 — service troubleshooting.** Triggers: "起不来", "没响应",
  "restart trading", "service status". → `references/troubleshooting.md`.
  Calls `python3 scripts/lifecycle.py {start|stop|status|logs}`.

- **R8 — events / reconnect.** Triggers: "重连", "事件", "replay", "events".
  → `references/events.md`. `GET /v1/events?since=<id>`.

- **R9 — symbol metadata / lot-size discipline.** Triggers: "一手", "最小买",
  "tick", "T+1 吗", "lot size", "minimum order"; OR any time the user-provided
  qty isn't obviously lot-aligned for the market (CN MAIN 100, STAR/CHINEXT
  200+, HK varies, US 1); OR after a prior order rejected with
  `INVALID_LOT_SIZE` / `INVALID_TICK_SIZE` / `SYMBOL_METADATA_UNAVAILABLE`.
  → `references/symbols.md`. `GET /v1/symbols/{symbol}`. **Round qty
  locally** and resubmit; do not surface `INVALID_LOT_SIZE` to the user when
  you could round and proceed. Report `original → rounded` if you change it.

### Routing decision rules

Apply when intent is ambiguous. Later rules override earlier ones.

- **Cancel without order_id** → R4 (`status=WORKING`) first, then R2.
- **Sell / sellable qty** → R3 before R1 (`sellable = qty - qty_pending_t1 - qty_locked_sell`).
- **Invalid-looking qty or price** → R9 before R1; round locally when possible.
- **Poll order state** ("filled yet?") → R4, not R1.
- **MARKET rejected** (`NO_ASK_LIQUIDITY` / `NO_BID_LIQUIDITY`) → explain limit lock; suggest LIMIT (R1).
- **Service / connection errors** → R7; run doctor before asking the user to restart.
- **`recovery_hint=reconcile`** → R8, then retry the original action.

## Confirmation discipline

Mutating calls (R1 place-order, R2 cancel-order) require user confirmation
**by default**. Before sending the POST/DELETE, echo a one-line summary
that includes side, quantity, symbol, type, price (if LIMIT), and account:

  "即将下单：BUY 100 600519.SH MARKET (account: acc_default)，确认?"

Read-only calls (R3–R6, R8, R9) never require confirmation.

### Skipping confirmation

If the user's trade request itself contains any of these phrases, skip
the confirmation for that single call:

  "不要确认" "直接下单" "立即买入" "立即卖出"
  "skip confirm" "no confirm" "just do it"

Skip is **per-call**, not session-wide. The next trade request without
the phrase requires confirmation again.

## Output discipline

When relaying API results to the user, translate implementation detail into
plain language. Follow the same hygiene as `stocki-financial-reader`.

| Category | Do not show | Show instead |
|----------|-------------|--------------|
| Secrets | `state/token`, Bearer headers, API key values, `.env` contents | nothing, or "local auth is configured" |
| Network | `127.0.0.1`, port numbers, `/v1/health` URLs | "local simulator" / "service unavailable" |
| Storage | SQLite paths, `data/`, `state/`, `logs/` | "records stored on this machine" |
| Config | yaml URL fields, `risk.max_working_orders` | env vars; limits in plain words |
| Errors | `recovery_hint`, raw JSON, HTTP status alone | translated `message` + next step |
| Field names | `qty_pending_t1`, `qty_locked_sell`, `floating_pnl` | sellable qty, T+1 lock, unrealized P&L |

Required: label **simulated** on first balance/trade touch in a session;
distinguish open (`WORKING`) vs filled vs cancelled/rejected/expired;
do not invent P&L when quote is missing; no buy/sell/hold advice.

## Default account

Unless the user specifies an account, all R1–R5 calls target `acc_default`.
Power users may add accounts in `config/accounts.yaml`; in that case ask
the user which account they mean if it is not obvious from context.

## Symbol naming

This skill expects exchange-coded symbols: `600519.SH`, `00700.HK`,
`AAPL.US`. If the user gives a natural-language name ("茅台"), ask for the
exchange code. If another name-resolver skill is installed in the environment,
you may use it once, then continue with the returned code — this skill does
not require any specific reader skill.

## Service lifecycle

The local paper-trading process is auto-started on first `_http.py` call.
The user need not invoke `start` manually. For diagnostics:

    python3 {baseDir}/scripts/doctor.py
    python3 {baseDir}/scripts/diagnose.py

R7 covers explicit `lifecycle.py start | stop | status | logs`. In normal
chat, report outcomes only — do not ask the user to run lifecycle commands.

### First-run account setup

Before auto-starting for the very first time, check whether accounts have
been configured:

    python3 -c "from scripts.init import is_first_run; print(is_first_run())"

If `True`, this is the first run and initial cash has not been set yet.
**Before proceeding**, show the user the defaults and ask for confirmation:

> 即将初始化模拟账户，默认初始资金：
> - CNY（人民币）：10,000,000 元
> - HKD（港币）：10,000,000 元
> - USD（美元）：50,000,000 元
>
> 是否调整？（直接回复"确认"或给出修改后的金额）

Once the user confirms (or provides custom amounts), write accounts.yaml
and then proceed with the normal autostart:

    python3 -c "
    from pathlib import Path; from scripts.init import write_accounts_yaml
    write_accounts_yaml(Path('.'), cny=<CNY>, hkd=<HKD>, usd=<USD>)
    "

**Important constraint**: initial cash is a one-time setting. After the
service starts for the first time, accounts are seeded from accounts.yaml
into the local database. Subsequent edits to accounts.yaml have no effect —
changing initial cash after first start requires resetting the simulation,
which permanently deletes all trade history. Warn the user clearly if they ask
to change initial cash after the service has already run. Do not mention
`accounts.yaml` or SQLite in the user dialog — use the prompt above only.

## Error handling

`_http.py` maps trading-assistant error `recovery_hint` (agent-internal —
do not expose hint names to the user):

  - **fix_input** — surface translated `message`; ask the user to correct
  - **retry** — one retry already attempted; propagate if still failing
  - **reconcile** — R8: refresh account + events, then retry

`DUPLICATE_CLIENT_ORDER_ID` returns the existing order — treat as success.
`SERVICE_UNREACHABLE` means autostart already tried; run R7 (doctor /
lifecycle) silently, then tell the user the simulator is temporarily
unreachable and you are fixing it.

## Doctor / diagnose

Run before reporting setup issues:

    python3 {baseDir}/scripts/doctor.py
    python3 {baseDir}/scripts/diagnose.py

Report exit code 0/1 and the one-line status if failed — do not paste token
or path details from the output.

## Cross-ref

See `INSTALL.md` for install and `.env` setup. See `references/*.md` for
per-endpoint contracts.