AxonX 项目概览
从研究 Prompt 到量化代码,再到可追溯的实验。
AxonX 是什么?
AxonX 是面向 Agent 的量化研究 Harness。 Agent 开发研究插件、执行实验,与研究者共同检查参数、日志、依赖和产物。
用户提出问题,Agent 实现逻辑,AxonX 管理执行与证据。 支持 CLI、HTTP、MCP 和 Studio。参考插件适配 Microsoft Qlib 的 Alpha158 基线,扩展可配置因子与持仓策略。
快速开始 · 插件体系 · 研究案例 · 文档 · Playground 在线试玩
为什么使用 AxonX?
- 使用 Agent 开发: 结合 AxonX Skill、源码工具和实时 Task Schema。
- 保留实验依据: 类型化输入输出、进程身份、日志和带修订的产物引用。
- 通过 Studio 检查: 任务控制、工作区预览、研究图表与策略比较。
最新更新
- 发布 0.3.0: 支持可继承配置、统一任务执行,以及服务重启不中断的定时任务。
- Alpha158 实验: 风险因子与排名保留策略的 Top20 净年化收益,相比适配基线分别提升 +1.36 pp 和 +24.70 pp。见结果与证据边界。
- Studio Playground: 使用模拟数据体验任务和图表。在线试玩。
快速开始
要求 Python 3.12+,支持 macOS 和 Linux。Studio 是可选包,与 AxonX 共用版本号和发布工作流。
1. 安装与启动
从 pip 安装:
pip install 'axonx[studio]'或从源码安装后端与 Studio:
git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e ./axonx_studio -e '.[studio]'
npm --prefix axonx_studio ci
npm --prefix axonx_studio run build源码安装使用 editable 模式。构建 Studio 需要 Node.js 22.13+(22.x)、24.x 或 26+;修改前端后需重新构建。
然后启动服务:
export AXONX_SERVICE_TOKEN='replace-with-your-service-token'
axonx app --service.host 127.0.0.1默认端口 1024、工作区 .axonx、服务/CLI 日志目录 logs/。可选设置见 example.env;CLI 启动时从启动目录或父目录加载最近的 .env,保留已有环境变量。保持此终端运行,在另一终端使用相同 Python 环境与 token。
需要自定义设置时,将以下 YAML 保存为 axonx.local.yaml:
extends: default
workspace_dir: .axonx
service:
host: 127.0.0.1通过 axonx app --config ./axonx.local.yaml 启动。自定义配置仅在声明 extends: default 时继承内置服务、组件和 Job;字典合并,列表和标量替换。已安装插件也可提供命名配置,详见配置参考。
2. 运行 Demo 并打开 Studio
axonx get_task_def --task demo
axonx exec --task demo --task-name quickstart --x 2 --y 3
axonx status --task-id 'base#demo#quickstart' --detail fullexec 等待完成,输出业务结果(result=5)并返回 Task 退出码。Demo 无需行情或模型凭据。访问 http://127.0.0.1:1024/,在 设置 → 本机服务 token 填写令牌。
axonx --help 显示离线用法,axonx help 查询运行中服务的 Job。执行设置按 显式 CLI 参数 → 服务 get_config → 内置默认值 生效。仅在服务连接不可用时回退;认证或服务错误直接报告。Task 专用参数通过 get_task_def 查询。
记录 Task ID 和 metadata started_at。实验使用不同实例名:同名重跑替换当前记录与输出,保留 persistent/。详见任务管理。
3. 使用 Agent 开发
使用参考研究插件时,复用上面的源码仓库;通过 pip 安装的用户可另行克隆仓库。在仓库根目录,将插件安装到执行服务的 Python 环境:
axonx plugin install -e ./plugins/qlib_a158
axonx restart_service研究插件从源码安装,先安装 Alpha158,再按需安装 factor 或 strategy,两个扩展彼此不依赖。源码变化后重启常驻服务;依赖或入口点变化后重新安装。服务重新就绪后再查询定义。
提供源码、文件/命令工具和 AxonX Skill。通过 GitHub CLI 从 main 安装 Skill,Claude Code 将 --agent 改为 claude-code:
gh skill install FlowLLM-AI/AxonX axonx --agent codex --scope user --pin main按上文安装 AxonX 和研究插件,再选择接入方式:
- 外部 Agent: 客户端管理模型凭据。使用 CLI,或通过 Streamable HTTP MCP 连接
http://127.0.0.1:1024/mcp,携带Authorization: Bearer <token>。见 MCP 集成。 - 内置 Agent: 配置以下模型环境,重启服务后打开 Studio → Agent,将其
cwd指向源码。见 Agent 配置。
CLAUDE_CODE_API_KEY=your-model-api-key
CLAUDE_CODE_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_MODEL_NAME=your-model-name向 Agent 提出明确目标,例如:
阅读 AxonX Skill 和 Alpha158 实现,开发独立插件测试残差波动与下行风险。固定数据、训练设置、成本和评估窗口,仅使用信号时点可得信息。测试代码并执行实验,报告 Task ID、RankIC、净收益、回撤与限制,预留独立确认窗口。
开始前准备历史数据与 AXONX_TUSHARE_TOKEN,再按研究流程执行。
从 Qlib Alpha158 到研究插件
主链为 ETL → Train → Predict → Portfolio → Backtest,因子分析可从 ETL 分支。qlib_a158_research 组合各阶段,叶子 Task 可复用兼容的上游产物。
| 插件 | 能力 |
|---|---|
| qlib_a158 | 158 个价量特征、LightGBM、因子分析与 TopN 回测 |
| qlib_factor | 13 个可选特征,训练默认使用 158 个基线特征 |
| qlib_strategy | 最短持有期、排名保留与换仓限制,复用预测 |
其他研究方法通过同一套 Task 与插件契约接入。基线调整了 Qlib 的数据、标签、训练与交易假设,详见与原始 Qlib 的差异。
Alpha158 改进案例
该历史实验增加两个风险特征,再对因子模型的预测应用排名保留策略:
| 配置 | Top20 净年化 | 最大回撤 | 日均双边换手 |
|---|---|---|---|
| Alpha158 基线 | 7.67% | -38.65% | 198.83% |
| 风险因子模型 | 9.03% | -40.69% | 199.35% |
| 排名保留策略 | 32.37% | -24.91% | 40.01% |
训练:[20150101,20230101);评估:20230103–20261008(909 个市场日)。买入/卖出费用:0.05% / 0.15%。策略最短持有 3 日,每日每侧换仓数量上限 20%,首次建仓除外。
证据边界: 尚无独立确认窗口;基础/因子模型的 feature_fraction 不同(0.9/1.0),无法单独归因于新增因子。所有回测均报告 incomplete_market_data,使用同收盘成交代理,且 2026 年不完整。不能据此认定优于原始 Qlib。
CLI 与远程执行
设置目标令牌,执行与观察使用相同地址:
export AXONX_TARGET_TOKEN='replace-with-target-token'
axonx exec --task demo --task-name remote-check --x 2 --y 3 --target node-b:1024
axonx status --task-id 'base#demo#remote-check' --detail full --target node-b:1024替换示例地址。--target 使用 AXONX_TARGET_TOKEN,默认本机调用使用 AXONX_SERVICE_TOKEN。远程路径属于目标机。本地插件部署按 构建 → 上传 → 安装 location → 清理 path → 重启/验证 完成,见插件管理。
Studio 使用后端配置的 targets;AXONX_TARGET 填充内置 remote 配置,本身不会选择 CLI 目标。见远程机器。服务重启会停止服务拥有的手动命令,保留 Daemon 拥有的定时 Task;计划接受本地 axonx exec --task NAME 命令。见服务更新。
文档入口
| 目标 | 指南 |
|---|---|
| 运行研究 | 快速开始 · 研究流程 |
| 使用 Agent | 外部 Agent · 内置 Agent |
| 开发插件 | 开发指南 · 产物契约 |
| 评估结果 | 实验设计 · 策略比较 |
| 运行或扩展 AxonX | CLI · 配置 · 架构 |
参与贡献
欢迎贡献框架、插件、实验与文档。环境与检查要求见贡献指南,问题和提案见 GitHub Issues。