a-share-paper-trading

A 股模拟盘

独立的模拟盘技能。交易服务、CLI、账户、撮合与行情适配都在本目录内，不依赖其他技能脚本。

何时使用

• 启动或检查模拟盘服务
• 创建／重置账户
• 限价买卖、市价买卖、撤单
• 查询账户、持仓、订单、成交
• 验证涨跌停、T+1、收盘过期
• 运行简单回测

启动

SKILL_DIR="<本skill绝对路径>"
python3 "$SKILL_DIR/scripts/paper_trading_service.py" --host 127.0.0.1 --port 18765

默认监听 http://127.0.0.1:18765，默认数据库不再存放于技能目录，而是存放在用户级数据目录：

• macOS：~/Library/Application Support/a-share-paper-trading/paper_trading.db
• Linux：${XDG_DATA_HOME:-~/.local/share}/a-share-paper-trading/paper_trading.db

如果本机该端口已有模拟盘进程在运行，不要再启动第二个实例：这会报错 Address already in use，且多个进程可能争用同一个 SQLite 数据库文件。启动前可先检查端口是否正在监听，例如：

lsof -iTCP:18765 -sTCP:LISTEN

或者向 http://127.0.0.1:18765/accounts 发送 GET（CLI 默认 --base-url 与此一致）。已有服务时直接使用 paper_trade_cli.py 即可。

更推荐使用控制脚本让服务常驻运行：

python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" start
python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" status
python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" stop

在 macOS 上，如需持续自启动，可安装 launchd：

python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" install-launchd

服务会：

• 在交易时段定时撮合挂单
• 在非交易时段停止撮合
• 收盘后让当日未成交的订单过期
• 定时写入账户净值快照

可用启动参数：

• --host
• --port
• --db-path
• --match-interval
• --valuation-interval
• --idle-valuation-interval

默认端口与 CLI 基址已改为 18765，以避免与常见本地开发服务冲突。

CLI

python3 "$SKILL_DIR/scripts/paper_trade_cli.py" create-account alpha --cash 500000
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" list-accounts
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" show-default-account
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" set-default-account alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" reset-account alpha --cash 300000
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" add-cash alpha 50000 --note 入金
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" deduct-cash alpha 10000 --note 出金
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" buy alpha 600519 100 --market
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" sell alpha 600519 100 --price 1450
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" orders alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" positions alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" show-account alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" trades alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" cancel <order_id>
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" process-orders
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" run-snapshots
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" backtest 600519 --strategy sma_cross --start 2025-01-01 --end 2026-03-31 --cash 200000

支持的 CLI 子命令：

• create-account
• show-default-account
• set-default-account
• reset-account
• list-accounts
• show-account
• positions
• orders
• trades
• buy
• sell
• cancel
• add-cash
• deduct-cash
• process-orders
• run-snapshots
• backtest

エージェント执行规则（账户路由）

• 首次创建模拟账户前，必须先向用户确认初始资金金额。
• 如果系统中存在多个账户，而用户未指定账户，则先询问“本次操作使用哪个账户”，再继续。
• 如果只有一个账户且该账户已存在，则默认直接使用该账户。
• 如果存在默认账户（可通过 show-default-account 查询），且用户未指定账户，则优先使用默认账户。
• 需要切换默认账户时，使用 set-default-account。

首次初始化资金规则（默认 100w）

• 用户首次要进行交易但尚未初始化账户资金时，先询问确认，不要直接执行。
• 建议默认初始资金为 1000000（100w），提问模板建议为：
  • “当前尚未初始化模拟账户，默认按 100w 启动，是否确认？如需修改，请直接给出金额。”
• 仅在用户明确确认后，才创建默认账户。
• 如果用户给出其他金额，则按用户指定金额创建账户并继续后续操作。

CLI 参数约束（エージェント必读）

• buy/sell：
  • 限价单必须带 --price。
  • 市价单使用 --market，不应再传入 --price。
• orders --status 可用值：open / filled / cancelled / expired / rejected。
• add-cash / deduct-cash 的 amount 必须为正数，单位为人民币元。
• 默认优先使用 --json 输出，以便后续进行结构化解析与决策。

执行前检查（下单前固定三步）

1. 先确认账户路由：show-default-account 或 list-accounts。
2. 再确认资金：show-account <account_id>。
3. 下单前确认持仓与未完成订单：positions <account_id> 与 orders <account_id> --status open。

资金调整规则（增减可用资金）

• 入金使用 add-cash <account_id> <amount>，出金使用 deduct-cash <account_id> <amount>。
• 入金／出金金额必须为正数。
• 出金只能减少可用资金，不得动用冻结资金；可用资金不足时应先告知用户再调整。

常见错误与处理动作

• Address already in use：不要重复启动服务，直接使用现有服务地址。
• default account not set：启动首次初始化询问流程，确认金额后创建默认账户。
• insufficient available cash：提示当前可用资金，建议入金或降低下单数量／价格。
• insufficient sellable qty：提示可卖数量，并说明可能受 T+1 影响或持仓不足。
• order is not open：先查询订单状态（可能已成交／已撤单／已过期），再决定下一步。
• market orders are only accepted during trading hours：改用限价单或等待交易时段。

规则摘要

• 仅支持 A 股做多
• 买入数量必须是 100 股的整数倍
• 卖出遵守 T+1
• 限价单价格必须符合 0.01 元的最小报价单位
• 板块涨跌幅兜底规则：
  • 主板普通股 10%
  • 创业板／科创板 20%
  • 主板 ST 5%
• 限价单价格不能超出当日涨跌停范围
• 触及涨停价时默认无法买入（包括一字涨停）
• 触及跌停价时默认无法卖出（包括一字跌停）
• 市价单仅在连续竞价时段接受
• 集合竞价与午休时段不进行自动撮合
• 行情时间戳不是当日时，视为陈旧行情，不执行市价成交
• 费用模型包含最低佣金、卖出印花税、沪市过户费
• 当日订单在收盘后过期

结构

• scripts/paper_trading_service.py：启动 HTTP 服务
• scripts/paper_trade_cli.py：CLI
• scripts/paper_trading_ctl.py：启停、状态、launchd 安装
• scripts/paper_trading_runtime.py：运行时默认目录、端口、路径
• scripts/paper_trading/：账户、撮合、估值、数据适配

服务接口

默认暴露以下 HTTP 路由：

• GET /accounts
• GET /accounts/default
• POST /accounts
• POST /accounts/default
• GET /accounts/{account_id}
• POST /accounts/{account_id}/reset
• POST /accounts/{account_id}/cash-adjust
• GET /accounts/{account_id}/positions
• GET /accounts/{account_id}/orders
• GET /accounts/{account_id}/trades
• POST /orders
• POST /orders/{order_id}/cancel
• POST /orders/process
• POST /snapshots/run
• POST /backtest
• GET /health

参考

• GitHub 项目地址：https://github.com/shouldnotappearcalm/a-share-skill