ths login

请选择 [1]：2
手机号（可见输入）：13800000000
未授权（138****0000）
输入授权 Key 继续，直接回车退出：XXXX-XXXX-XXXX
向 138****0000 发送一次短信验证码？输入 y 确认，回车取消 [y/N]：y
短信验证码（隐藏输入）：
交易密码（隐藏输入；直接回车跳过该券商）：
券商 broker_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa：已认证，连接驻留daemon

ths daemon query --broker-account 00001234567890 --kind positions --live

{
  "version": 2,      // 本机通信协议版本
  "id": 47,          // 本次请求的随机编号，排查时原样提供
  "ok": true,        // 只表示本机请求处理成功，不表示成交；交易要看 data.status
  "data": {},        // 结果；失败时为 null
  "error": null      // 失败时为 {"code": ..., "message": ...}
}

ths daemon query --broker-account "$BROKER_ACCOUNT" --kind balance --live

{
  "version": 2,
  "id": 47,
  "ok": true,                                         // false 是失败，不等于余额为零
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "kind": "balance",
    "result": {
      "available_funds": 1092.18,                     // 可用资金
      "total_assets": "2092.1800",                    // 总资产，保留券商原文小数位；没返回时为 null
      "market_value": "1000.00"                       // 股票总市值；没返回时为 null
      // 两处可用资金不一致时另有 "warning": "资金返回值存在差异，请核对券商客户端。"
    }
  },
  "error": null
}

ths daemon query --broker-account "$BROKER_ACCOUNT" --kind positions --live

{
  "version": 2,
  "id": 48,
  "ok": true,
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "kind": "positions",
    "result": {
      "row_count": 1,                     // 持仓条数；0 加空数组＝确实没有持仓
      "positions": [
        {
          "code": "000001",               // 证券代码，保留前导零
          "name": "合成股票",
          "quantity": 1000,               // 持仓数量，按券商原样，不换算成"手"
          "available": 800,               // 可卖数量
          "cost_price": "10.1200",        // 成本价，字符串，保留券商原文小数位
          "current_price": 10.4,          // 现价
          "market_value": 10400.125,      // 市值
          "profit_loss": -12.375,         // 浮动盈亏
          "profit_loss_percent": "-0.1188" // 盈亏比例，已是百分数（-0.1188 表示 -0.1188%），不要再乘 100
        }
      ]
    }
  },
  "error": null
}

ths daemon query --broker-account "$BROKER_ACCOUNT" --kind orders --live

{
  "version": 2,
  "id": 49,
  "ok": true,
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "kind": "orders",
    "result": {
      "row_count": 1,
      "orders": [
        {
          "code": "000001",
          "name": "合成股票",
          "order_id": "12345",            // 委托编号，撤单时用
          "order_date": "20261019",
          "side": "买入",                 // 券商原文
          "price": "10.1200",             // 委托价
          "quantity": 100,                // 委托数量
          "filled_quantity": 0,           // 已成交数量
          "average_fill_price": 0.0,      // 成交价
          "status": "已报",               // 委托状态，券商原文
          "reason": null,                 // 券商说明原文（如废单原因）
          "cancelled_quantity": 0,        // 已撤数量
          "market": "1"
        }
      ]
    },
    // 同一批委托按状态分组的副本，不要和 orders 重复累加，统计以 orders 为准。
    // 分组：unfilled 未成交；partially_filled 部分成交；cancellation_pending 撤单中；cancelled 已撤；
    // partially_cancelled 部撤；partially_filled_then_cancelled 部成后撤；filled 已成交；waste 废单；rejected 已拒绝；unknown 未识别
    "groups": {
      "unfilled": [
        { "code": "000001", "name": "合成股票", "order_id": "12345", "order_date": "20261019", "side": "买入",
          "price": "10.1200", "quantity": 100, "filled_quantity": 0, "average_fill_price": 0.0,
          "status": "已报", "reason": null, "cancelled_quantity": 0, "market": "1" }
      ]
    }
  },
  "error": null
}

ths daemon query --broker-account "$BROKER_ACCOUNT" --kind orders --cache

{
  "source": "cache",                       // 缓存，不是实时数据
  "upstream_requests": 0,                  // 没有联网
  "cache": {
    "source": "explicit_query",            // explicit_query 手动查过；post_acceptance_refresh 下单受理后自动刷新
    "cached_at": "2026-10-19T02:00:00Z",   // 缓存时间（UTC）
    "age_ms": 1250.0,                      // 距今毫秒数；可能已过时
    "connection_ready": true
  }
}

{
  "version": 2,
  "id": 3089527198357359987,
  "ok": false,                              // 失败；不等于余额为零或没有持仓
  "data": null,
  "error": {
    "code": "broker_account_not_found",
    "message": "Broker account is not in the selected current daemon roster"
  }
}

ths daemon buy --broker-account "$BROKER_ACCOUNT" --code 000001 --price 10.12 --qty 100

{
  "mode": "dry_run",                         // 演练
  "transaction_sent": false,                 // 没有发送交易
  "upstream_requests": 0,                    // 没有联网
  "validation": "local_only",
  "account_id": "11111111111111111111111111111111",
  "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "broker_account": "00001234567890",
  "preview": {                               // 程序理解的下单内容，请核对
    "operation": "buy",
    "exchange": "shenzhen",                  // 按代码识别：shenzhen／shanghai／beijing
    "market": "1",
    "code": "000001",
    "price": "10.12",
    "quantity": 100
  }
}

# ⚠️ 真实买入
ths daemon buy --broker-account "$BROKER_ACCOUNT" --code "$CODE" --price "$PRICE" --qty "$QTY" --live

{
  "version": 2,
  "id": 63,
  "ok": true,                                // 被拒时也是 true，一定看 data.status
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "preview": { "operation": "buy", "exchange": "shenzhen", "market": "1", "code": "000001", "price": "10.12", "quantity": 100 },
    "status": "accepted",                    // 交易结果：accepted／rejected／confirmation_required／unknown，含义见 2.6 的表
    "order_id": "12345",                     // 委托编号；可能为 null，不代表失败
    "order_cache_refresh": {"status": "updated"},   // 受理后自动查一次委托；order_not_found／failed 不影响已受理
    "message": "请求已受理，不代表成交或最终委托有效；请查询委托状态。",
    "notice_confirmation_attempted": false,  // true＝券商弹出风险告知、按授权自动确认过一次，原文在 risk_notice
    "automatic_retries": 0                   // 始终 0：从不自动重发
    // 被拒时另有 server_message（券商原文）和 error_codes（数字码），示例见 2.6
  },
  "error": null
}

ths daemon sell --broker-account "$BROKER_ACCOUNT" --code 000001 --price 10.12 --qty 100   # 演练

# ⚠️ 真实卖出
ths daemon sell --broker-account "$BROKER_ACCOUNT" --code "$CODE" --price "$PRICE" --qty "$QTY" --live

{
  "version": 2,
  "id": 64,
  "ok": true,                                // 被拒也是 true
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "preview": { "operation": "sell", "exchange": "shenzhen", "market": "1", "code": "000001", "price": "10.12", "quantity": 100 },
    "status": "rejected",                    // 券商拒绝；不会自动重发
    "order_id": null,
    "server_message": "（券商返回的原文）",   // 不翻译不删减
    "error_codes": [-150906135],             // 原文里的数字码，原顺序
    "notice_confirmation_attempted": false,
    "automatic_retries": 0
  },
  "error": null
}

ths daemon cancel --broker-account "$BROKER_ACCOUNT" --order-id 12345   # 演练

{
  "mode": "dry_run",
  "transaction_sent": false,                 // 没有发送撤单
  "upstream_requests": 0,
  "validation": "local_only",                // 只检查编号格式（1–15 位数字），不查委托是否存在
  "account_id": "11111111111111111111111111111111",
  "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "broker_account": "00001234567890",
  "preview": { "operation": "cancel", "order_id": "12345" }
}

ths daemon query --broker-account "$BROKER_ACCOUNT" --kind orders --live      # 先查委托
# ⚠️ 真实撤单
ths daemon cancel --broker-account "$BROKER_ACCOUNT" --order-id "$ORDER_ID" --live

{
  "version": 2,
  "id": 65,
  "ok": true,
  "data": {
    "account_id": "11111111111111111111111111111111",
    "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "preview": {
      "operation": "cancel", "exchange": null, "market": "1", "code": "000001",
      "price": "10.1200", "quantity": 100,
      "order_id": "12345",                   // 要撤的委托
      "order_date": "20261019"               // 委托日期，来自之前查到的委托
    },
    "status": "accepted",                    // 撤单请求已受理，不代表已撤成；取值和退出码同 2.6
    "order_id": "12345",                     // 回显原委托编号
    "message": "请求已受理，不代表成交或最终委托有效；请查询委托状态。",
    "notice_confirmation_attempted": false,
    "automatic_retries": 0
    // 被拒时另有 server_message（券商原文，如"不在允许撤单时间"）和 error_codes
  },
  "error": null
}

ths license status          # 只看本机；加 --live 向服务器刷新

{
  "device": {"enrolled": true, "device_id": "dev_0123abcd"},
  "accounts": [
    {
      "login_name": "138****0000",            // 已打码
      "status": "active",                     // active 有效；unlicensed 未授权；expired 到期；disabled 停用
      "expires_at": "2026-11-17T03:40:55Z",   // 授权到期（UTC）
      "ticket": {"exp": "2026-10-18T03:40:56Z", "offline_release": true}   // 可离线登录的截止时间；现在能否离线登录
    }
  ],
  "source": "local"                           // local 本机；license_server 已联网刷新
}

ths license redeem

{
  "redeemed": true,
  "login_name": "138****0000",
  "account": {"status": "active", "expires_at": "2026-11-17T03:40:56Z"},   // 兑换后的状态和到期时间
  "redemption": {"duration": "1m", "before_expires_at": null, "after_expires_at": "2026-11-17T03:40:56Z"}   // 本次加的时长（1m＝1 个月）
}

ths login                 # 菜单
ths login sms             # 短信登录（推荐）
ths login pwd             # 密码登录
ths login sms --new-pwd   # 券商交易密码改了，逐家重新输入

{
  "account_id": "11111111111111111111111111111111",   // 后台会话编号；daemon 重启后会变
  "account": "13800000000",
  "results": [                                        // 每家券商一条，逐家看是否成功
    {
      "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "response": {
        "version": 2,
        "id": 101,
        "ok": true,                                   // 这家券商是否登录成功
        "data": {
          "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "broker_name": "合成证券",
          "branch_name": "合成营业部",
          "broker_account": "00001234567890",         // 完整资金账号，查询交易用它选券商
          "state": "ready",                           // ready 可用，其他值见 4.3
          "authenticated": true,
          "credentials_stored": true,
          "reused": false                             // true＝连接本来就在，直接复用
        },
        "error": null                                 // 失败时原因在这里，券商原文在 error.server_message
      }
    }
  ],
  "automatic_retries": 0,
  "reopened": false,                                  // true＝因未启用券商自动断开并重新打开过该账号
  "authenticated": true,                              // 同花顺部分已登录；券商看 results
  "method": "sms",                                    // sms 或 pwd
  "ths_session": "authenticated",                     // reused 复用已有登录；authenticated 本次重新登录
  "license": {
    "source": "server",                               // server 已联网核对；offline_ticket 离线放行
    "status": "active",
    "expires_at": "2026-11-17T03:40:55Z"              // 授权到期（UTC）
  }
}

{
  "authenticated": false,
  "stage": "license",                 // 停在哪一步：license 授权、sms 短信、password-auth 密码、broker 券商等
  "code": "license_key_rejected",     // 失败代码
  "message": "授权 Key 兑换失败：授权 Key 无效（key_invalid）",
  "server_message": "授权 Key 无效",   // 服务端原文；本机或网络问题时为 null
  "error_codes": []                   // 服务端数字码，原顺序
}

ths daemon start

{
  "started": true,                 // false＝已在运行（already_running 为 true）
  "already_running": false,
  "status": { },                   // 与 daemon status 的 data 相同，见 4.3
  "synchronization": "empty"       // ready 全部恢复；partial 部分；failed 失败；empty 无可恢复；pending 超时仍在后台恢复
}

ths daemon status

{
  "version": 2,
  "id": 50,
  "ok": true,
  "data": {
    "account_count": 1,                  // 后台持有的账号数；0 可能是还没登录或还在恢复
    "accounts": [
      {
        "account_id": "11111111111111111111111111111111",   // 可用于 daemon close --account-id
        "account": "13800000000",
        "ths_state": "ready",
        "brokers": [
          {
            "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",   // 本次会话的券商编号；重启后会变
            "broker_name": "合成证券",
            "broker_account": "00001234567890",
            // ready 可用；credentials_required 缺交易密码；failed_no_retry 上次失败不自动重试；disconnected 已断开
            "state": "ready",
            "authenticated": true,       // 本机最后一次观察的结果，不是实时探测
            "credentials_stored": true
            // 正在处理请求时另有 "busy": true
          }
        ]
      }
    ],
    "restoration": {
      "state": "complete",               // 启动恢复：empty 无记录；restoring 进行中；complete 完成（仍要逐家看）；failed 失败
      "pending_accounts": 0,
      "results": []
    },
    "schedule": {
      "mode": "manual",                  // 运行模式，见 4.7
      "exchange_date": "2026-10-19",
      "phase": "trading",                // trading 交易时段；non_trading_day 非交易日 等
      "trading_day": true,
      "open": "09:00",
      "close": "15:05"                   // 收盘自动退出时间（北京时间）
    },
    "upload": {                          // 操作记录上传（见第 3 章）
      "state": "active",                 // active 正常；stopped 已停止；unavailable 本机未配置
      "pending": 0,                      // 本机排队待传的条数
      "dropped": 0,                      // 队列满被丢弃的条数
      "rejected": 0,                     // 服务器拒收的条数
      "skipped": 0,                      // 跳过的条数（如券商还没在授权服务器登记，重新 ths login 一次即可）
      "last_success_at": "2026-10-19T01:30:05Z",   // 最近一次上传成功（UTC）
      "last_error": null                 // 最近一次错误原因，正常为 null
    },
    "pid": 84976,
    "protocol_version": 2
  },
  "error": null
}

ths daemon close                              # 按提示输入同花顺账号
ths daemon close --account-id "$ACCOUNT_ID"   # 用 daemon status 里的 account_id

{
  "version": 2,
  "id": 51,
  "ok": true,
  "data": {
    "closed": true,                                   // false＝这个账号本来就没打开
    "account_id": "11111111111111111111111111111111"
  },
  "error": null
}

ths daemon stop

{
  "version": 2,
  "id": 53,
  "ok": true,
  "data": {"stopping": true},      // 断开全部连接并退出；登录信息和恢复清单保留
  "error": null
}

ths daemon mode           # 查看
ths daemon mode auto      # 开机自启 + 交易日开盘自动登录
ths daemon mode manual    # 默认：用到时才启动，不自动登录

{
  "mode": "manual",                // 下次启动使用的模式
  "source": "inferred",            // configured 设置过；inferred 推断
  "service_installed": false,      // 是否装了开机自启服务
  "daemon_running": true,
  "running_mode": "manual",        // 运行中后台的模式
  "applies_after_restart": false   // true＝需 ths daemon stop 后再启动才生效
}

ths update --check   # 只检查，不安装
ths update           # 有新版就下载、校验并替换

{
  "current": "0.1.0",          // 当前版本
  "latest": "0.1.1",           // 下载站最新版本
  "update_available": true
}

python3 -m pip install ~/.local/share/ths/python
python3 -m pip install "$HOME/.local/share/ths/python[file-store]"   # 没有钥匙串的机器（如无桌面 Linux）

import getpass
from ths_client import ThsClient, CliError, DaemonError

client = ThsClient()      # 或 ThsClient(executable="/绝对路径/ths")
result = client.login_with_sms(
    "13800000000",
    confirm_sms=lambda info: input(f"向 {info['mobile']} 发一次验证码？输入 y：") == "y",
    verification_code=lambda: input("短信验证码："),
    broker_password=lambda broker: getpass.getpass(
        f"{broker['broker_name']} {broker['broker_account']} 交易密码（回车跳过）：") or None,
    license_key=lambda info: input(f"授权状态 {info['status']}，输入授权 Key（回车退出）：") or None,
)
for item in result["results"]:
    print(item["broker_id"], item["response"]["ok"])

broker_account = "00001234567890"     # 原样，保留前导零
client.daemon_status()                                         # 4.3 的 data；后台没运行时抛 DaemonError
client.query("balance",   broker_account=broker_account)       # 2.1 的 data
client.query("positions", broker_account=broker_account)       # 2.2 的 data
client.query("orders",    broker_account=broker_account)       # 2.3 的 data
client.query("orders",    broker_account=broker_account, cache=True)   # 只读缓存

{
  "account_id": "11111111111111111111111111111111",
  "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "kind": "balance",
  "result": {"available_funds": 1092.18, "total_assets": "2092.1800", "market_value": "1000.00"}
}

try:
    client.query("positions", broker_account=broker_account)
except DaemonError as error:
    print(error.code, error.message)    # 程序分类和说明，同 2.4
    print(error.server_message)         # 券商原文；没有时为 None
    print(error.server_codes)           # 数字码，原顺序

prepared = client.daemon.prepare_trade(
    side="buy", code="000001", price="10.12", quantity=100,
    broker_account="00001234567890",
)

def confirm(preview):
    print(preview)
    return input("确认真实下单？输入 YES：") == "YES"

# ⚠️ 真实下单
result = client.daemon.execute_trade(prepared, confirm=confirm)
print(result["status"], result["order_id"])

{
  "account_id": "11111111111111111111111111111111",
  "broker_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "broker_name": "合成证券",
  "broker_account": "00001234567890",
  "preview_id": "cccccccccccccccccccccccccccccccc",   // 一次性，只能执行一次；再准备会替换旧的
  "preview": {"operation": "buy", "exchange": "shenzhen", "market": "1", "code": "000001", "price": "10.12", "quantity": 100},
  "transaction_sent": false                          // 还没下单
}

client.query("orders", broker_account="00001234567890")
prepared = client.daemon.prepare_cancel(order_id="12345", broker_account="00001234567890")
# ⚠️ 真实撤单
result = client.daemon.execute_trade(prepared, confirm=confirm)

client.daemon.close("13800000000")   # {"closed": True, "account_id": "..."}
client.daemon.shutdown()             # {"stopping": True}

ths daemon stop
ths daemon mode manual                # 切过 auto 的，先卸载开机自启服务
rm ~/.local/bin/ths
python3 -m pip uninstall ths-client   # 用过 Python 包时