order-lifecycle-safety
Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 32
- Forks
- 6
01 前言 Front Matter
- name
- order-lifecycle-safety
- description
- Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.
02 资源文件 2
- 参考文档references/broker-caveats.md1.2 KB
- 参考文档references/states.md494 B
03 SKILL.md 正文
Order Lifecycle Safety
Pure markdown. No dependencies, no code to install. These are the rules an order path must own itself; do not assume an external approval gate exists.
1. Unique client_order_id on every order
- Every order carries a
client_order_idgenerated by your code, once, before the first send. - It must be unique per intended order and stable across retries of that same order.
- Persist it (audit log) before sending, so a crash cannot lose it.
- Respect broker length/charset limits: see
references/broker-caveats.md.
2. Same terms vs different terms (REPLAY / ID_REUSED)
| Repeat of an existing id | Correct behaviour | Label |
|---|---|---|
| Same id, same terms | Return the first result; do not create a second order | REPLAY |
| Same id, different terms | Refuse; never mutate or resubmit under that id | ID_REUSED |
Implement this in your own layer (compare a hash of symbol, side, qty, type, price, TIF). Do not rely on the broker to do it; broker behaviour varies (see caveats).
3. Unknown outcome: reconcile before retry
A timeout, 5xx, dropped connection, or crash after send means the outcome is unknown, not failed.
- Mark the order
UNKNOWNin the audit log. - Look the order up by client id (or list recent orders and match).
- Found → adopt its status. Not found after the broker's lookup is known consistent → only then may you resend with the same client id.
- Lookup itself fails → stay
UNKNOWN, alert a human. Never blind-retry.
4. Audit before forward
- Decide (allow/refuse).
- Write the decision, with the client id and terms, to an append-only audit log before forwarding.
- Forward to the broker.
- If forwarding raises or times out, append
UNKNOWN(notFAILED) and go to section 3. - Redact credentials from log lines.
If the audit write fails, do not forward: fail closed.
5. Environment-proof preflight
Never infer paper vs live from config, env var names, base URLs, or account-number shape. Config can be wrong or edited.
- Before the first order of a session, read the environment back from the broker.
- Prefer a call that states the environment/capabilities of the session (a session-capabilities call) over a bare auth-status call, which usually proves only that credentials work, not which environment they belong to.
- Compare the broker's answer to the environment the operator intended. Match → proceed. Mismatch, missing field, or any ambiguity → refuse.
- Re-run after any credential or endpoint change.
- Whether a given broker exposes such a call is per-broker; see
references/broker-caveats.md. If none does, treat the environment as unproven and require a human to confirm in a terminal the agent cannot reach.
Checklist
- [ ] client id generated and persisted before send
- [ ] REPLAY / ID_REUSED handled locally
- [ ] audit entry written before forward; forward failure recorded as UNKNOWN
- [ ] no retry without lookup by client id
- [ ] environment read back from broker, ambiguity refuses
See references/ for tables.
04 同仓库更多 Skills
order-lifecycle-safety
Idempotency, reconcile-before-retry, audit-before-forward and environment-proof preflight rules for any code or agent that places broker orders. Use when building or reviewing an order path, handling a timeout or unknown order outcome, adding client_order_id, deciding whether a retry is safe, or confirming paper vs live before sending an order.
write-a-skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
wireframe-sketch
A hand-drawn wireframe exploration — graph-paper background, marker / pencil tone, multiple tab labels for variants, sticky-note annotations, scribbled chart placeholders, hatched fills. Reads like a designer's whiteboard before any pixels are committed. Use when the brief asks for "wireframe", "sketch wireframe", "hand-drawn", "lo-fi", "whiteboard", "草稿", or "手绘原型".
weekly-update
Single-file horizontal-swipe slide deck for a weekly team update — shipped, in flight, blocked, metrics, asks. 6–8 slides. Use when the brief mentions "weekly update", "team update slides", "weekly status", "周报演示".
webull-openapi
Trade stocks, options, futures, crypto, and event contracts on Webull. Query real-time and historical market data. Manage accounts and positions. Supports US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with configurable risk controls.
web-prototype
General-purpose desktop web prototype. Single self-contained HTML file built by copying the seed `assets/template.html` and pasting section layouts from `references/layouts.md`. Default for any landing / marketing / docs / SaaS page when no more specific skill matches.