\r \r

stocki-trading-assistant\r

\r Paper trading for CN / HK / US equities. The skill wraps a locally-spawned\r paper-trading service; the service is auto-started on first use. Orders,\r positions, and fills are simulated — not a live brokerage account.\r \r This file instructs the Agent. Do not quote implementation details\r (tokens, ports, file paths, script names) to the user unless they are\r explicitly troubleshooting via INSTALL.md.\r \r

Core principle\r

\r Use this skill when the user wants simulated trading — place or cancel\r orders, check balance/positions/P&L, order or fill history, market session\r status.\r \r Do NOT use for real-money brokerage execution or personalized buy/sell\r recommendations.\r \r Never fabricate balances, positions, fills, or order states. If a value\r is missing or the service is down, say so.\r \r Paper only. Remind the user when relevant that fills are simulated and\r not investment advice.\r \r

Local API convention\r

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

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

Routing rules\r

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

• R1 — place order. Triggers: "买", "卖", "buy", "sell", "下单",\r "place order", "market buy", "limit sell". → references/place-order.md.\r Calls POST /v1/orders via scripts/_http.py.\r 下单后根据订单类型执行下单通知流程。\r \r
• R2 — cancel order. Triggers: "撤单", "取消", "cancel", "撤掉".\r → references/cancel-order.md. Calls DELETE /v1/orders/{order_id}.\r \r
• R3 — account state. Triggers: "余额", "持仓", "盈亏", "balance",\r "positions", "P&L". → references/account-state.md. Calls\r GET /v1/accounts/{id} and GET /v1/accounts/{id}/positions.\r \r
• R4 — order history. Triggers: "历史订单", "查订单 ord_xxx",\r "order history", "list orders". → references/order-history.md.\r GET /v1/accounts/{id}/orders, GET /v1/orders/{id}.\r \r
• R5 — fills. Triggers: "成交", "fills", "成交记录".\r → references/fill-history.md. GET /v1/accounts/{id}/fills.\r \r
• R6 — market status. Triggers: "市场", "开盘", "收盘", "market status",\r "open?". → references/market-status.md. GET /v1/capabilities and\r GET /v1/markets/{m}/status.\r \r
• R7 — service troubleshooting. Triggers: "起不来", "没响应",\r "restart trading", "service status". → references/troubleshooting.md.\r Calls python3 scripts/lifecycle.py {start|stop|status|logs}.\r \r
• R8 — events / reconnect. Triggers: "重连", "事件", "replay", "events".\r → references/events.md. GET /v1/events?since=\x3Cid>.\r \r
• R9 — symbol metadata / lot-size discipline. Triggers: "一手", "最小买",\r "tick", "T+1 吗", "lot size", "minimum order"; OR any time the user-provided\r qty isn't obviously lot-aligned for the market (CN MAIN 100, STAR/CHINEXT\r 200+, HK varies, US 1); OR after a prior order rejected with\r INVALID_LOT_SIZE / INVALID_TICK_SIZE / SYMBOL_METADATA_UNAVAILABLE.\r → references/symbols.md. GET /v1/symbols/{symbol}. Round qty\r locally and resubmit; do not surface INVALID_LOT_SIZE to the user when\r you could round and proceed. Report original → rounded if you change it.\r \r

Routing decision rules\r

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

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

Order notification flow\r

\r After placing an order (R1), the agent must follow the notification flow\r based on order type. This is mandatory for every R1 invocation.\r \r

MARKET order — single-stage notification\r

\r

1. Call POST /v1/orders\r
2. Check the response state:\r
   • FILLED — immediately notify the user with fill details:\r fill price, quantity, fees, order ID\r
   • REJECTED — immediately notify with the rejection reason and\r suggested next step\r
   • Other errors — notify the user about the error\r \r

LIMIT order — two-stage notification\r

\r Stage 1: Order-placed notification (immediate — in conversation)\r \r This is a direct agent response, not a cron notification.\r \r

1. Call POST /v1/orders\r
2. Check the response state:\r
   • WORKING → immediately reply to the user in Chinese:\r

     ✅ 挂单成功\r 订单号：ord_xxx\r 股票：600601.SH（方正科技）\r 方向：买入 | 数量：100 股 | 限价：13.77 元\r 正在等待成交，成交/失败后将自动通知你\r

   • FILLED (rare, limit crossed immediately) → follow MARKET flow\r
   • REJECTED → notify the rejection reason\r \r Stage 2: State-change monitoring (single global cron job)\r \r One cron job manages all orders. Not one per order.\r \r On the first LIMIT placement that results in WORKING, check if a cron job\r named stocki-trading-assistant-order-monitor already exists (via cronjob(action='list')).\r If none exists, create a single cron job:\r \r

cronjob(\r
  action='create',\r
  name='stocki-trading-assistant-order-monitor',\r
  schedule='every 1m',\r
  skills=['stocki-trading-assistant'],\r
  deliver='origin'\r
)\r
```\r
\r
This cron job polls **all** `WORKING` orders. It stores a snapshot of\r
previous states (e.g. `state/order_snapshot.json`) to detect changes.\r
\r
Cron job behaviour each tick:\r
\r
1. Fetch all orders via `GET /v1/accounts/acc_default/orders`\r
2. Filter to `state=WORKING`\r
3. Compare against previous snapshot:\r
   - If a previous `WORKING` order is now **gone from the list** (filled,\r
     rejected, or cancelled → check each with `GET /v1/orders/{id}`)\r
   - If a previous `WORKING` order is still `WORKING` → skip (no change)\r
4. Collect **all state changes** into a list\r
5. At the end of the tick:\r
   - **Changes found** → send **one** notification in Chinese listing all\r
     changes (e.g. "以下订单状态已更新：\
- ord_xxx：已成交 100 股 @ 13.77\
- ord_yyy：已撤单")\r
   - **No changes** → send nothing (silent)\r
6. If **zero** `WORKING` orders remain → `cronjob(action='remove')` — stop\r
   the monitor automatically\r
\r
Key rules:\r
- **No repeat limit** — runs until all orders resolve\r
- **No duplicate notification** — `WORKING→WORKING` is silent\r
- **Multiple changes batched** — one message per tick, not one per order\r
- **Cron never re-announces "挂单成功"** — that's done in Stage 1\r
\r
The cron job prompt **must** include:\r
- stocki-trading-assistant skill path: `/home/agentuser/.hermes/skills/stocki-trading-assistant/`\r
- Snapshot file path: `state/order_snapshot.json` under the skill root\r
- Clear instructions: detect state changes, batch notifications, self-remove\r
  when no orders remain\r
- Produce an **empty response** when no changes detected (silent tick)\r
\r
## Confirmation discipline\r
\r
Mutating calls (R1 place-order, R2 cancel-order) require user confirmation\r
**by default**. Before sending the POST/DELETE, echo a one-line summary\r
that includes side, quantity, symbol, type, price (if LIMIT), and account:\r
\r
  "即将下单：BUY 100 600519.SH MARKET (account: acc_default)，确认?"\r
\r
Read-only calls (R3–R6, R8, R9) never require confirmation.\r
\r
### Skipping confirmation\r
\r
If the user's trade request itself contains any of these phrases, skip\r
the confirmation for that single call:\r
\r
  "不要确认" "直接下单" "立即买入" "立即卖出"\r
  "skip confirm" "no confirm" "just do it"\r
\r
Skip is **per-call**, not session-wide. The next trade request without\r
the phrase requires confirmation again.\r
\r
## Output discipline\r
\r
When relaying API results to the user, translate implementation detail into\r
plain language. Follow the same hygiene as `stocki-financial-reader`.\r
\r
| Category | Do not show | Show instead |\r
|----------|-------------|--------------|\r
| Secrets | `state/token`, Bearer headers, API key values, `.env` contents | nothing, or "local auth is configured" |\r
| Network | `127.0.0.1`, port numbers, `/v1/health` URLs | "local simulator" / "service unavailable" |\r
| Storage | SQLite paths, `data/`, `state/`, `logs/` | "records stored on this machine" |\r
| Config | yaml URL fields, `risk.max_working_orders` | env vars; limits in plain words |\r
| Errors | `recovery_hint`, raw JSON, HTTP status alone | translated `message` + next step |\r
| Field names | `qty_pending_t1`, `qty_locked_sell`, `floating_pnl` | sellable qty, T+1 lock, unrealized P&L |\r
\r
Required: label **simulated** on first balance/trade touch in a session;\r
distinguish open (`WORKING`) vs filled vs cancelled/rejected/expired;\r
do not invent P&L when quote is missing; no buy/sell/hold advice.\r
\r
## Default account\r
\r
Unless the user specifies an account, all R1–R5 calls target `acc_default`.\r
Power users may add accounts in `config/accounts.yaml`; in that case ask\r
the user which account they mean if it is not obvious from context.\r
\r
## Symbol naming\r
\r
This skill expects exchange-coded symbols: `600519.SH`, `00700.HK`,\r
`AAPL.US`. If the user gives a natural-language name ("茅台"), ask for the\r
exchange code. If another name-resolver skill is installed in the environment,\r
you may use it once, then continue with the returned code — this skill does\r
not require any specific reader skill.\r
\r
## Service lifecycle\r
\r
The local paper-trading process is auto-started on first `_http.py` call.\r
The user need not invoke `start` manually. For diagnostics:\r
\r
    python3 {baseDir}/scripts/doctor.py\r
    python3 {baseDir}/scripts/diagnose.py\r
\r
R7 covers explicit `lifecycle.py start | stop | status | logs`. In normal\r
chat, report outcomes only — do not ask the user to run lifecycle commands.\r
\r
### First-run account setup\r
\r
Before auto-starting for the very first time, check whether accounts have\r
been configured:\r
\r
    python3 -c "from scripts.init import is_first_run; print(is_first_run())"\r
\r
If `True`, this is the first run and initial cash has not been set yet.\r
**Before proceeding**, show the user the defaults and ask for confirmation:\r
\r
> 即将初始化模拟账户，默认初始资金：\r
> - CNY（人民币）：10,000,000 元\r
> - HKD（港币）：10,000,000 元\r
> - USD（美元）：50,000,000 元\r
>\r
> 是否调整？（直接回复"确认"或给出修改后的金额）\r
\r
Once the user confirms (or provides custom amounts), write accounts.yaml\r
and then proceed with the normal autostart:\r
\r
    python3 -c "\r
    from pathlib import Path; from scripts.init import write_accounts_yaml\r
    write_accounts_yaml(Path('.'), cny=\x3CCNY>, hkd=\x3CHKD>, usd=\x3CUSD>)\r
    "\r
\r
**Important constraint**: initial cash is a one-time setting. After the\r
service starts for the first time, accounts are seeded from accounts.yaml\r
into the local database. Subsequent edits to accounts.yaml have no effect —\r
changing initial cash after first start requires resetting the simulation,\r
which permanently deletes all trade history. Warn the user clearly if they ask\r
to change initial cash after the service has already run. Do not mention\r
`accounts.yaml` or SQLite in the user dialog — use the prompt above only.\r
\r
## Error handling\r
\r
`_http.py` maps trading-assistant error `recovery_hint` (agent-internal —\r
do not expose hint names to the user):\r
\r
  - **fix_input** — surface translated `message`; ask the user to correct\r
  - **retry** — one retry already attempted; propagate if still failing\r
  - **reconcile** — R8: refresh account + events, then retry\r
\r
`DUPLICATE_CLIENT_ORDER_ID` returns the existing order — treat as success.\r
`SERVICE_UNREACHABLE` means autostart already tried; run R7 (doctor /\r
lifecycle) silently, then tell the user the simulator is temporarily\r
unreachable and you are fixing it.\r
\r
## Doctor / diagnose\r
\r
Run before reporting setup issues:\r
\r
    python3 {baseDir}/scripts/doctor.py\r
    python3 {baseDir}/scripts/diagnose.py\r
\r
Report exit code 0/1 and the one-line status if failed — do not paste token\r
or path details from the output.\r
\r
## Cross-ref\r
\r
See `INSTALL.md` for install and `.env` setup. See `references/*.md` for\r
per-endpoint contracts.\r