平台 CLI 命令参考

2026-10-30补充：provider list、research-skill list/preview/run/show/events/files/cancel及notification list/config/state/read-all复用平台接口；本地无需Web的十类研究、按角色后端覆盖和原生Skill导出见Agent后端与原生Skills。通知状态仍按client_id区分，读取/关闭不消除风险来源。

2026-10-25追加：backtest run及pipeline run支持--execution-costs JSON，也可在--file请求中填写同名对象。支持方案、最低佣金、分方向税费及成交约束，费率使用内部小数。实际示例与快照位置见交易成本指南。Qlib及前向模拟不接受通用费用覆盖。

更新于 2026-10-22，A/B/C 已实现。CLI 通过 REST 复用网页的业务服务，涵盖 29 个命令组、168 个普通 REST 操作和 2 个 SSE 端点。先读命令行上手和协议原理。正式设计保留在项目 doc/platform/cli_interface_design.md，实测记录保留在 docs/audit/cli_validation_2026-10-20.md、docs/audit/platform_fix_2026-10-21/README.md。

入口与常用命令

在项目根目录使用 Python 3.10+ 执行 python egs/entrypoints/cli.py，也支持 python -m src.cli。下表用 aiquant 简写同一入口；安装本项目后可使用该别名，从源码运行无需安装。先启动现有后端；CLI 默认连接 http://127.0.0.1:8000，可用 --base-url 覆盖。所有示例在 Windows PowerShell 和 Linux shell 中均为单行命令。

目标	调用形式
查看完整帮助	aiquant --help
查看回测参数帮助	aiquant backtest run --help
查看当前服务能力	aiquant system capabilities --format json
检查服务	aiquant system health
显式连接测试服务	aiquant --base-url http://127.0.0.1:8879 system info
前台启动服务	aiquant system serve --host 127.0.0.1 --port 8000
查证券名称和代码	aiquant security search --query 沪深300 --market CN
读取日 K	aiquant stock show 510300 --sections kline --kline-count 240 --market CN
ETF 池	aiquant etf universe list
ETF 当前快照	aiquant etf snapshot cn_core --require-real
因子监控	aiquant factor monitor --universe 510300,510500,159915
查看已导入策略	aiquant strategy list --all --max-items 100
查看预制策略	aiquant strategy examples list
导入 ETF 策略	aiquant strategy examples import --example egs/examples/strategy_examples/etf_momentum_rotation_strategy.py --name ETF轮动研究
启用策略	aiquant strategy enable 12
读取方案列表	aiquant strategy params profiles 12
预览参数	aiquant strategy params resolve 12 --parameter-profile etf_momentum.yaml:baseline --params-file egs/config/cli/params/etf.yaml
从 YAML 运行回测	aiquant backtest run --file egs/config/cli/requests/etf_backtest.yaml --format json
单次覆盖选股数	aiquant backtest run --file egs/config/cli/requests/etf_backtest.yaml --set params.top_n=2
查看绩效和净值	aiquant backtest metrics 42；aiquant backtest curve 42 --format json
查看运行快照	aiquant backtest snapshot 42 --format json
比较多个任务	aiquant backtest compare --ids 41,42
导出交易	aiquant backtest export 42 --kind trades --output data/reports/backtest/42-trades.csv
ETF 多 Agent 复核	aiquant agent review --backtest-id 42 --workflow etf_review --objective 核查ETF换手和成本 --model-id 3
保存复核报告	aiquant agent show RUN_ID --format json --output data/reports/research_team/review.json
创建模拟账户	aiquant paper create --name ETF模拟研究 --strategy-id 12 --initial-capital 1000000
查看模拟账户	aiquant paper show 7；aiquant paper positions 7
模拟下单	aiquant paper order 7 --symbol 510300 --side buy --order-type market --quantity 100
查看实盘配置验证	aiquant live validation 3
Qlib 环境诊断	aiquant qlib status --format json
Qlib Workflow	aiquant qlib run --server-workflow egs/qlib_workflows/alpha158_lgb.yaml --provider-uri data/qlib
知识库文档上传	aiquant kb document upload --file doc/strategies/etf_strategy_design.md --category-id 2
知识检索	aiquant kb search --keyword ETF轮动
知识问答	aiquant kb ask --question ETF轮动的回测限制是什么
定时任务	aiquant job list；aiquant job trigger 5；aiquant job history 5
模型配置诊断	aiquant model list；aiquant model test 3
普通模型问答	aiquant model chat --model-id 3 --question-file egs/config/cli/prompts/question.txt
工作台真实后台消息	aiquant ai ask --session-id 8 --backend codex --message-file egs/config/cli/prompts/question.txt --format jsonl
环境变量状态	aiquant env check --name OPENAI_API_KEY，只返回状态，不输出密钥

表中的资源 ID 和运行标识需要替换为实际创建结果。egs/config/cli/requests/etf_backtest.yaml、params/etf.yaml、prompts/question.txt 已提供；回测样例的 strategy_id 也需替换。Qlib 的 workflow/provider 路径属于服务端，示例不附带原生训练数据或 workflow 文件。

第一次跑通策略与回测

先在一个终端执行 python start.py --host 127.0.0.1 --port 8000，在另一个终端从项目根目录执行下面命令。前两步可直接执行；后续 12、42 只是占位 ID，必须先读取实际返回值再替换，不要把整组命令不加修改连续执行。

python egs/entrypoints/cli.py system health --format json
python egs/entrypoints/cli.py strategy examples import --example egs/examples/strategy_examples/etf_momentum_rotation_strategy.py --name ETF首次验证 --format json
python egs/entrypoints/cli.py strategy enable 12
python egs/entrypoints/cli.py strategy params resolve 12 --parameter-profile etf_momentum.yaml:baseline --format json
python egs/entrypoints/cli.py backtest run --file egs/config/cli/requests/etf_backtest.yaml --set strategy_id=12 --dry-run --format json
python egs/entrypoints/cli.py backtest run --file egs/config/cli/requests/etf_backtest.yaml --set strategy_id=12 --format json
python egs/entrypoints/cli.py backtest metrics 42 --format json
python egs/entrypoints/cli.py backtest snapshot 42 --format json
python egs/entrypoints/cli.py backtest curve 42 --format json
python egs/entrypoints/cli.py backtest trades 42 --format json

运行前核对请求 YAML 的日期与可得行情；真实行情无区间内数据会明确失败。完成后对照曲线日期、成交、费用、持仓及来源，不能把零成交、HTTP 200 或 mock 回测当作真实策略表现。需要强制来源检查时，可在支持来源证据的运行或指标接口加 --require-real；曲线等不含来源证据的结果也会被该选项拒绝。

创建对象	后续命令使用的返回字段
策略导入	data.strategy_id
创建回测	data.task_id
AI 会话	data.id
模拟账户	data.account_id
多 Agent 复核	data.run_id，字符串运行标识

更多页面操作与限制见 策略调参、ETF 研究和 AI 工作台。

配置与发现

策略工坊新增 pipeline 命令族：components、templates、preview、create、list、show、update、publish、versions、enabled、run、runs、result、export、events、cancel、accounts、account、monitor、risk-reset。运行示例见策略工坊。pipeline run 等待真实终态，--format jsonl 或 --stream 显示实际事件；JSON配合 --output 只保存一次最终结果。参数请求使用 --file，不是CLI连接用的 --config。

可以将 egs/config/platform/cli.example.yaml 复制为项目内的 egs/config/platform/cli.yaml，分别保存多个 context；不提供配置时读取样例默认值。优先级为命令行、ALL_IN_ONE_CLI_* 环境、context 和样例配置。代理凭证通过 context 的 authorization_env 引用 .env，不写在 YAML 中。

使用 aiquant api operations --format json 查看完整契约；aiquant api describe "backtest run" 查看一个命令；业务参数以该命令的 --help 为准。模型地址用 --model-base-url，JSON 配置对象用 --request-config，避免与客户端的 --base-url、--config 混淆。

通用调用示例为 aiquant api call --method GET --path /backtests/42，请求字段通过 --file 或 --set 提供；它和语义命令共用确认、禁用及业务失败规则。历史 CLI 策略生成模拟器、券商事件注入和人工标错操作已明确禁用。

请求文件与参数

回测请求 YAML 使用现有 API 字段，至少包含 strategy_id、symbols、start_date、end_date。常用可选字段为 engine、initial_capital、commission_rate、order_type、price_adjustment、lot_size、max_position_count、max_position_weight、slippage_rate、parameter_profile 和 params。

--file 是整个请求，--params-file 只表示策略参数，--parameter-profile 是服务端已登记的方案 ID。完整方案 YAML 不能直接塞进 params。修改学习率使用 --set params.model_params.learning_rate=0.03，不会覆盖同级其他模型设置；列表替换整个列表。

CLI 本地覆盖顺序为 --file → --params-file → --set → 显式业务字段选项；服务端再解析命名方案与已保存默认值。--config 控制客户端连接，--request-config 才是业务 JSON 配置对象；二者均不修改后端行情模式。

默认值由服务端解析，CLI 不复制或猜测数据库默认值。发送前可以用 --dry-run 查看请求；该选项不执行后端参数验证、回测或工具调用。

完整请求和参数文件可使用 --file -、--params-file - 从标准输入读取；同一命令只允许一个参数消费标准输入。日期写成带引号的字符串，零和 false 会保留。尚未实现的日期/排序筛选会报错，避免静默忽略。kb search 只返回受 page-size 限制的检索结果，不支持自动翻页。

脚本与长任务

脚本使用 JSON 获取固定 code、message、data、meta 字段，通过进程退出码判断命令是否成功。原始 HTTP 200 不代表成功；执行结果 blocked 或 failed 会非零退出。读取一份失败任务记录本身仍可成功，任务状态保留在 data 中。

当前回测、Qlib、多 Agent 主要为同步接口：命令会等待最终响应，不提供虚假的后台任务 ID。超时或 Ctrl+C 后服务端可能继续执行，不能盲目重复提交。JSONL 只输出真实收到的状态和消息，未产生 token 时不会输出假进度。

退出码	含义
0	请求成功；模拟来源仍会标明
2	输入、配置或精确确认不满足
3	HTTP、连接、断流或协议错误
4	超时，执行结果可能未知
5	业务失败或执行 failed
6	能力缺失、blocked 或被禁用
7	require-real 或 fail-on-verdict 条件不满足
130	用户中断，服务端可能继续执行

--all --max-items 1000 遍历支持分页的接口，按 ID 去重，结果 meta 会标注截断及非一致性快照。--output 只允许写入本项目；已有文件需要 --overwrite。CSV 目前只导出 trades，嵌套结果用 JSON；公式样式字符串添加单引号，避免电子表格执行公式。

AI 会话、附件与事件

先执行 aiquant ai session create --title ETF研究，取得 data.id，然后使用 aiquant ai ask --session-id 8 --backend codex --message-file egs/config/cli/prompts/question.txt --attachment doc/strategies/etf_strategy_design.md --format jsonl。附件可重复指定；文件先经 multipart 上传，后端只接受返回的附件标识。图片会传给实际支持图片的后台。

aiquant ai session show 8 读取持久消息；aiquant ai session list 查看会话。后台的模型参数为 --model-name，模型 API 配置 ID 为 --model-id，思考强度为 --reasoning-effort。Codex 的状态、消息和动作来源于本地真实进程；GenericAgent 当前仅提供已完成阶段和最终消息，不承诺逐 token。多 Agent 复核同样可以加 --format jsonl。

mock 服务默认不启动真实 Codex；如需显式验收，在启动服务的环境中设置 ALL_IN_ONE_ENABLE_REAL_CLI=true。真实模型缺失、Trae/WorkBuddy 未接协议、Qlib 环境不完整均如实失败。断流先查会话/报告，不重发原消息。

数据来源和操作边界

图形工坊对应的查询为 pipeline nodes <运行ID> --after 0、pipeline layout show <方案ID>。保存布局使用 pipeline layout save <方案ID> --file <请求文件>，文件包含 definition_digest、layout 与 revision；修订号从show读取。保存坐标不发布计算版本，nodes只读取近期节点预览，完整事件使用 pipeline events。

--require-real 用于拒绝模拟数据/模型；它不会把 US 模拟行情自动升级成真实行情。ETF 的缺失规模、成交额或官方基准数据仍保持缺失，CLI 不改写策略能力。

删除、重置和覆盖需要确认精确对象，非交互调用通过 --yes --confirm-id 对象标识 明确确认；普通查询不需要确认。实盘启动和恢复还需开启允许交易操作的上下文，并通过服务端验证；停止和暂停直接执行。

model chat 是普通模型问答，ai ask 才使用 AI 工作台后台与会话。旧策略生成模拟器不能当作真实 Codex 后台，Trae/WorkBuddy 在没有真实协议时继续报告不可用。

配置凭证来自项目 .env，密钥不放在普通请求文件、命令行参数或日志中。服务端返回的文件路径不代表客户端已下载文件，导出要通过明确 output 生成客户端产物。