AxonX 开发与运行指南
You define the question; the Agent implements it; AxonX manages execution and evidence.
用户定义研究问题,Agent 实现代码并验证想法,AxonX 管理 Task 执行、日志、依赖记录和产物。按以下闭环工作,已有条件满足时直接复用:
定义问题与基线 → 准备执行环境 → 开发插件 → 安装部署 → 运行与检查 → 比较结果并迭代。
本文按开发和运行顺序组织,通过 axonx 命令完成操作。源码路径相对源码仓库根目录,工作区路径属于实际执行机器;示例名称、地址、日期和文件名应替换为当前实验的值。在用户授权范围内操作,不输出凭据,不编造运行结果。
0. 定义研究问题
先从用户要求和现有记录中确定:
- 假设与基线:要验证什么,与哪个实现或参数组比较。
- 实验设置:数据源、股池、信号可用时点、训练/验证/评估窗口、成本与成交假设。
- 判断方式:主要指标、候选选择规则、时间与资源预算。
缺少影响实现或结论的条件时再澄清。因子分析、模型实验、策略回测可以独立开展,不必每次运行完整研究链。固定比较所需的控制变量,在开发窗口筛选候选,用独立确认窗口评估锁定方案;负面结果也可以完成验证。
1. 准备执行环境
区分编辑源码的开发机与运行 Task 的执行机,它们可能是不同机器。
| 当前条件 | 操作 |
|---|---|
| 已有本地或远程服务 | 复用连接、凭据和工作区,先发现能力;无需重新启动服务 |
| 只需本机运行 Task | 安装后端即可使用本地 exec,无须启动服务 |
| 需要新服务或 Studio | 安装后启动 axonx app;Studio 按需安装 |
安装与启动(需要时)
macOS/Linux 使用 Python 3.12+。新建环境并安装后端:
python3 -m venv .venv
source .venv/bin/activate
pip install axonx需要 Studio 时安装带预构建界面的版本:
pip install 'axonx[studio]'启动本地服务:
export AXONX_SERVICE_TOKEN='replace-with-your-service-token'
axonx app --service.host 127.0.0.1保持终端运行,另一终端使用相同环境和 token。已安装 Studio 时访问 http://127.0.0.1:1024/,在设置中填写令牌。仅开发插件不要求 Node.js 或内置 Agent 的模型凭据。
需要参考插件源码时克隆仓库;已有检出目录则复用。Python 安装包不包含这些示例项目:
git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e '.[dev]'默认端口 1024、工作区 .axonx、日志目录 logs、时区 Asia/Shanghai。CLI 加载当前目录及最多五级父目录中最近的 .env,保留已有环境变量。自定义配置示例:
extends: default
workspace_dir: .axonx
log_dir: logs
timezone: Asia/Shanghai
service:
host: 127.0.0.1
port: 1024
token: ${AXONX_SERVICE_TOKEN}
cron: []保存为 app.yaml 后启动:
axonx app --config app.yaml自定义文件只有声明 extends: default 才继承默认配置;映射递归合并,列表/标量替换,支持环境变量插值。相对路径以进程工作目录为基准,配置修改后重启服务。
连接与能力发现
axonx --help
axonx health
axonx list_jobs
axonx help
axonx help --job status
axonx diagnose
axonx get_config
axonx exec
axonx list_task_defs --include-schemas false
axonx get_task_def --task demohealth 查询服务就绪状态,无法确认服务运行时返回退出码 1;list_jobs 返回含输入/输出 Schema 的完整公开 Job 目录。两者直接调用 HTTP 接口。
--help 离线显示 CLI 语法;help 列出服务可用命令,help --job status 查看 status 的详细参数与返回格式。不带参数的 exec 列出当前解释器的 Task,查询命令需要连接服务。list_task_defs/get_task_def 查看服务加载的 Task 及输入/输出 Schema。diagnose 检查版本、Python、插件和资源;get_config 确认工作区和执行环境,其中可能包含敏感配置,不要原样放入报告。
连接远程服务只需开发机安装 CLI,无需在开发机启动服务:
export AXONX_TARGET_TOKEN='replace-with-target-token'
axonx version --target node-b:1024
axonx help --target node-b:1024
axonx diagnose --target node-b:1024
axonx get_task_def --task demo --target node-b:1024显式 --target 使用 AXONX_TARGET_TOKEN,默认本地连接使用 AXONX_SERVICE_TOKEN;--token 可覆盖。地址须带端口,可使用 HTTP(S),不能包含凭据、子路径或查询字符串。执行、查询和文件读取始终使用同一目标。
需要确认执行机资源或 Python 环境时运行,远程机器加相同 target:
axonx list_machines
axonx machine_status
axonx python --code 'import sys; print(sys.executable)' --timeout 30list_machines 检查已配置目标的连接;machine_status 查看资源,资源读数不代表自动分配;python 使用服务解释器运行短时探测,默认 30 秒、上限 300 秒。长期计算写成 Task。
2. 开发或修改插件
先阅读相关插件的 README、pyproject.toml、plugin.yaml、Task 实现与测试,再选择实现方式:
| 需求 | 实现与参考 |
|---|---|
| 已有参数足以验证 | 复用已安装 Task,直接进入运行阶段 |
| 修改现有算法 | 在职责对应的插件中修改,更新参数、测试与说明 |
| 独立算法或可复用扩展 | 新建插件,注册唯一 Task 名;可位于 AxonX 仓库之外 |
| 参考完整研究链 | plugins/qlib_a158/:ETL、分析、训练、预测、组合、回测与父 Task |
| 扩展特征或组合规则 | plugins/qlib_factor/ 扩展 ETL/Train;plugins/qlib_strategy/ 扩展回测 |
最小插件
目录如下,__init__.py 可为空:
example/
pyproject.toml
example_plugin/
__init__.py
plugin.yaml
task.pyexample_plugin/task.py:
from axonx.task.core.base import BaseTask
from axonx.task.models.params import BaseInputParams, BaseOutputParams
class AddInput(BaseInputParams):
x: int
y: int
class AddOutput(BaseOutputParams):
total: int
class AddTask(BaseTask):
"""Add two integers and publish their sum."""
input_cls = AddInput
output_cls = AddOutput
def build_task_steps(self):
yield self.add
def add(self):
self.state["total"] = self.input_params.x + self.input_params.y
def build_output_params(self):
return AddOutput(total=self.state["total"])example_plugin/plugin.yaml:
tasks:
example_add: example_plugin.task:AddTaskexample/pyproject.toml:
[build-system]
requires = ["setuptools>=84.0.0"]
build-backend = "setuptools.build_meta"
[project]
name = "axonx-example"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["axonx>=0.3.0"]
[project.entry-points."axonx.plugins"]
example = "example_plugin"
[tool.setuptools.package-data]
example_plugin = ["plugin.yaml"]分发包名 axonx-example 用于安装管理,入口名 example 标识插件,注册名 example_add 用于执行。manifest 只注册 tasks,运行所需文件须包含在 package data 中;业务依赖写入 dependencies。
Task 与产物约定
- 输入/输出继承对应 Pydantic 模型,未声明的 Task 入参会被拒绝。步骤同步执行,通过
self.state传值,build_output_params()返回output_cls实例。 - 输出文件写入
self.task_dir,跨同名重跑保留的状态写入self.persistent_dir;研究输入路径使用self.resolve_workspace_path()。用report_progress()报告进度,在close()中释放资源;输出在清理后构建,须保留所需状态。 - 执行中用
self.resolve_task(reg_name)获取声明的 Task 类及input_cls;注册解析由执行环境注入,不导入宿主。可选的self.input_budget由子任务继承,执行器在步骤边界检查截止时间。 - 用
upstream_task_ids声明数据依赖,它不会自动执行上游。用self.run_task(...)同步调用子任务,并检查返回的success、child_task_id和类型化output_params。父子调用与输入依赖是两种关系。 - 子任务共享进程与工作区,默认继承父实例名;同一注册名和实例名会复用同一目录,多次调用需使用不同
task_name或先固定产物。
研究基类在 axonx.task.core.research,输入/输出在 axonx.task.models.params,协议在 axonx.task.models.artifacts。标准研究输出的主要必填字段:
| 阶段 | 字段 |
|---|---|
| ETL / Analysis | ETL:rows、date_range;Analysis:rows |
| Train | feature_protocol, model_groups |
| Predict | rows、date_range、protocol |
| Portfolio | portfolios、protocol |
| Backtest | 非空 portfolios、protocol |
先写文件,再用 axonx.task.storage.artifacts.artifact_record(path, task_dir) 注册到输出 artifacts;记录包含 Task 相对路径、大小和 revision。原子写入与输出复制复用 axonx.task.storage.files。verify_artifact() 核验文件,revision 是大小/修改时间标识,并非内容哈希。axonx.task.storage.inputs 的 upstream_artifacts() 直接读取成功上游的产物,metadata 的 input_sources 记录来源执行和文件修订,执行成功前再次校验;业务兼容性仍由插件检查。
复用协议时使用 version=1 和正确的 task_type。训练在一个 Task metadata 中用有序 model_groups 索引模型,每组持有训练和使用区间以及组内 models 成员映射。预测发布模型身份、日期、评分列与输入修订;股票 ETL 分离数据、标签、行情和日历,预测不能含未来标签。股票组合 Task 继承 axonx.task.builtins.stock.portfolio.BaseStockPortfolioTask,实现信号时点的 build_universes() 与 select_universe()。回测继承 axonx.task.builtins.stock.backtest.BaseStockBacktestTask,消费冻结的 Portfolio 产物,沿用成交和估值协议。
在临时工作区运行受影响测试,再做小范围实际运行:
python -m pytest plugins/qlib_factor/tests新增插件使用自己的测试目录;框架修改运行相关框架测试,基础套件为 python -m pytest tests。研究依赖及外部服务需按测试要求准备。
3. 安装与部署插件
先检查 diff,记录源码提交号及未提交改动、插件版本或构建哈希。需要提交源码时按用户要求和项目约定处理;Git 提交不能代替在执行环境安装插件,也不要求先发布到 PyPI。
本地安装
从包含 example/ 的目录执行:
axonx plugin build ./example
axonx plugin install -e ./example
axonx plugin inspect axonx-example
axonx exec --task example_add --task-name check --x 1 --y 2确认退出码为 0、输出 total=3,并检查 base#example_add#check 的 metadata。参考插件先安装 qlib_a158,再按需安装 factor 或 strategy,两者各自依赖基线插件:
axonx plugin install -e ./plugins/qlib_a158
axonx plugin install -e ./plugins/qlib_factor
axonx plugin install -e ./plugins/qlib_strategy
axonx plugin list
axonx plugin build ./plugins/qlib_a158 --output ./dist/plugins不带 target 的 plugin 操作当前 Python 环境。inspect 只读取已安装元数据或已有 wheel;build 构建并校验源码目录,不安装。保留实际 wheel、sha256 和 content_sha256,分别用于定位 wheel、标识文件字节与规范化内容。安装器安装插件依赖但不升级 AxonX 自身,需确认框架版本满足要求;pip 不会自动定位相邻插件源码。
editable 要求执行机已有源码目录,不能与 --output 同用。依赖或入口点变化后重新安装;常驻服务在安装或已加载源码变化后需重启,新 CLI 进程会重新发现插件。环境变更应与运行中的研究协调,已有进程不会固定插件版本。
远程部署
远程 plugin 命令通过服务的通用 cli Job 执行,安装操作作用于目标 Python 环境。--target 不上传本地文件。目标机已有源码/wheel 时可直接安装;已有 AxonX Git 源码仓库时也可采用第 7 节的更新流程。从开发机传输插件则先构建和上传:
axonx plugin build ./example --output ./dist/plugins
axonx upload --path dist/plugins/ACTUAL_FILENAME.whl --target node-b:1024逐条执行并填写实际返回值:构建返回 wheel 文件名与哈希;上传返回 answer.location(目标机绝对路径)和 answer.path(目标工作区相对路径)。将 location 用于安装:
axonx plugin install '/ABSOLUTE/LOCATION_FROM_UPLOAD.whl' \
--target node-b:1024 --client-timeout 600
axonx plugin inspect axonx-example --target node-b:1024确认安装退出码为 0,核对目标插件版本、sha256 和 content_sha256 与本地构建结果一致,再用上传返回的 path 清理暂存:
axonx discard_file --path tmp/uploads/ACTUAL_UPLOAD_PATH.whl --target node-b:1024上传默认限额 512 MiB。连接中断时安装可能继续,先确认远端安装结束再重试或清理。依赖插件也须先安装到目标机;目标机已有源码时可直接使用远程 editable 安装:
axonx plugin install -e /ABSOLUTE/PATH/TO/example --target node-b:1024安装后请求重启,保存返回的 update_id,等待恢复并查询该操作至 succeeded 或 failed,再确认插件和 Task Schema:
axonx restart_service --target node-b:1024
axonx get_update_status --update-id ACTUAL_UPDATE_ID --target node-b:1024
axonx plugin list --target node-b:1024
axonx get_task_def --task example_add --target node-b:1024本地服务采用相同流程,省略 target。安装/重启响应成功不等于新代码已验证;实际运行前先完成刷新。服务重启会终止它拥有的手动 CLI 执行,不能在研究中途随意重启。
Portfolio 与 Backtest
研究链路使用 Predict → Portfolio → Backtest。组合基类是 BasePortfolioTask,股票实现是 BaseStockPortfolioTask。组合输出 portfolios 列表与明文 portfolio_id dict;同一语义使用相同 key,不同生产者可增加字段。组合固定信号资格、排名及策略规则。每个股票组合引用 Predict 输入,所有 N 与策略共用一份完整候选 rankings.parquet。仅新增聚合分数写入 scores.parquet,未改变的分数引用上游列。metadata 保存明文身份、股票池与文件引用。PortfolioReader 校验来源执行及修订并恢复信号,目标及等槽位权重按排名和 top_n 派生;Backtest 不复制信号。Backtest 消费组合上游并执行统一账本、估值与绩效统计。费用和评价参数放在 Backtest。在线与离线共用预测及组合构建逻辑,Compare 读取固定发布的预测、Portfolio 与在线历史,比较身份、排名、目标和账本。
4. 运行 Task 并检查证据
先确认 Task Schema、数据覆盖和所需凭据。行情凭据与 AxonX 服务 token 不同;远程执行使用目标机的数据、路径与环境,本机 export 不会配置远端服务。
axonx exec --task demo --task-name check --x 1 --y 2
axonx status --task-id 'base#demo#check' --detail full
axonx read_task_log --task-id 'base#demo#check' --offset -1 --limit 8192
axonx wait_task --task-id 'base#demo#check' --detail full --client-timeout 600
axonx stream_task --task-id 'base#demo#check' --stream true
axonx get_task_context --task-id 'base#demo#check'
axonx get_task_graph --task-id 'base#demo#check'exec 同步运行,结束后返回业务输出与 Task 退出码;长任务在另一终端或工具调用中观察。远程执行及全部查询加同一个 --target,终端持续显示执行输出。远程断连后执行可能继续,重试前查记录,停止执行使用 kill。
Task 状态与退出码描述程序执行错误。比对差异、待比对数据缺失、协议检查结论以及已处理的不完整/跳过窗口保留在业务输出中,不使已完成的 Task 失败;异常和记录的执行错误才使执行失败。比对视图必须在 Task 成功时继续展示差异。
axonx exec --task demo --task-name remote-check --x 1 --y 2 --target node-b:1024
axonx status --task-id 'base#demo#remote-check' --detail full --target node-b:1024参数使用 --field value,连字符转下划线、点号生成嵌套对象,值支持布尔、null、数字和 JSON。引用含 # 的 ID 与 JSON 数组。--client-timeout 默认 60 秒,是客户端连接超时,不是研究业务截止时间。
本地执行设置优先级为 CLI 显式字段 > 服务 get_config > 默认值;只有服务连接失败可回退,认证或配置错误会失败。--workspace-dir、--log-dir、--timezone、--environment.KEY 等覆盖只影响该命令;服务查询仍观察服务配置的工作区。无服务时直接检查本地 metadata、日志和产物。
执行上传的 Shell 脚本
upload 在 CLI 所在机器读取文件,将字节流发送到所选服务的 POST /upload,再将返回的绝对路径 answer.location 用于 shell 命令:
axonx upload --path queue.sh --target node-b:1024
axonx shell --command 'bash /ABSOLUTE/LOCATION_FROM_UPLOAD' \
--target node-b:1024 --stream trueshell 与 cli 一样,是设置了 cancel_on_disconnect: false 的普通 pipeline Job;普通 pipeline Job 的该选项默认为 true。Shell 源码通过 /bin/bash -c 在服务环境中执行,可选 cwd 指定远程已存在的工作目录,相对路径基于工作区解析。响应等待命令结束,返回 stdout、stderr、exit_code 和截断标志;stdout/stderr 事件流不受响应捕获大小的限制。
脚本在执行机器前台运行。客户端断开只结束观察,远程脚本及其中串行调用的 Task 继续执行;服务停止或重启会终止其进程组。此 Job 不创建单独的执行 ID,研究仍通过现有 Task 状态与日志观察。需要在断开后保留 Shell 输出时,将其重定向到远程文件。上传文件属于会过期清理的暂存文件,需要长期保留时另存到暂存区外。
参考研究链
qlib_a158 主链为 ETL → Train → Predict → Portfolio → Backtest,Analysis 从 ETL 独立分支。安装插件并在执行机配置数据凭据后,按顺序运行;每一步确认成功再启动下游,脚本须遇错停止。已有完整原始历史时跳过下载:
export AXONX_TUSHARE_TOKEN='replace-with-data-token'
axonx exec --task download_tushare_task --task-name data-01 \
--start-date 20140101 --end-date 20240131
axonx exec --task qlib_a158_etl --task-name research-01 \
--start-date 20150101 --end-date 20240131
axonx exec --task qlib_a158_train --task-name research-01 \
--upstream-task-ids '["etl#qlib_a158_etl#research-01"]' \
--train-start 20150101 --train-end 20230101
axonx exec --task qlib_a158_predict --task-name research-01 \
--upstream-task-ids '["train#qlib_a158_train#research-01","etl#qlib_a158_etl#research-01"]' \
--pred-start 20230101 --pred-end 20231231
axonx exec --task qlib_a158_portfolio --task-name research-01 --upstream-task-ids '["predict#qlib_a158_predict#research-01"]' --top-ns '[20,30]'
axonx exec --task qlib_a158_backtest --upstream-task-ids '["<portfolio_task_id>"]' --buy-cost-rate 0.0005 --sell-cost-rate 0.0015下载写入共享 tushare/ 分区,默认回溯 7 天不足以支持多年训练。检查原始历史、滚动特征所需长度和数据权限,缺失行情不能解释为零收益。训练结束日不包含在训练区间,预测不得早于训练结束,预测和选股不能使用未来标签。
也可用一条命令运行完整研究链,由父 Task 管理各阶段:
axonx exec --task qlib_a158_research --task-name pipeline-01 \
--etl.start-date 20150101 --etl.end-date 20240131 \
--train.train-start 20150101 --train.train-end 20230101 \
--predict.pred-end 20231231 --analysis '{}'结果中的 stage_task_ids 指向各阶段,analysis: {} 启用分析。复用既有上游时按前面的分阶段命令执行。qlib_factor 的可选特征需要显式选择,不能因安装扩展就假定训练已采用新特征。
检查运行结果
Task ID 为 task_type#registration#task_name,实例名为 1–32 个字母、数字或连字符,省略时自动生成。started_at 区分同名多次执行;终态为 succeeded 或 failed,执行中为 running。
| 层次 | 要核验的内容 |
|---|---|
| 命令 | 退出码、success、异常、stdout/stderr 及截断标志 |
| Task | 实际 ID、started_at、终态、输入、步骤和子调用;失败时读取日志 |
| 研究证据 | 实际产物、数据覆盖、业务评估状态、样本数和可比的指标 |
status/wait_task 默认摘要,--detail full 返回完整输入输出;get_task_context 提供完整选中记录、路径和输入关系。日志用 next_offset 续读,--started-at TIMESTAMP 可防止读到同名新执行。列表与图可能有索引刷新延迟,单任务状态直接读取 metadata。
固定名字保存在 <workspace>/tasks/<task_type>/<task_id>/;匹配 YYYYMMDDHH 加四位字母数字的名字(包括继承名字)保存在 <workspace>/tmp/tasks/<task_type>/<task_id>/。两者包含 metadata.json、events.jsonl、相对 Task 目录的 log_path(启用文件日志时为 task.log)及 persistent/history.jsonl。每次 Task 结束后,执行器追加一行完整的终态元信息 JSON,同名重跑保留该历史;执行期间复用 persistent/task.lock 文件锁,不创建全局锁目录。从输出 artifacts 取实际文件名,将 Task 目录与产物相对路径组合后预览:
axonx list_entries --path ''
axonx preview_file --path 'tasks/base/base#demo#check/metadata.json' --max-bytes 8192preview_file 使用工作区相对路径,CLI 默认 20 行、8192 字节。检查解析错误与截断标记,表格按 offset/limit 翻页,日志按 next_offset 续读。查询通常返回 {answer, success, metadata},success 只说明查询完成,还需检查 answer 中的 Task 状态和研究结果。
忘记实例名或查找已有实验时,先列出记录:
axonx list_task_statuses --task-type backtest --state succeeded
axonx list_entries --path tasks/backtest5. 比较结果与迭代
先定位问题,再返回相应步骤:
| 情况 | 处理 |
|---|---|
| 连接、凭据或数据问题 | 修正环境或补齐数据,核验已有运行后再试 |
| 插件/Task 不存在、版本或 Schema 不符 | 检查执行机的安装、依赖与服务刷新 |
| 代码异常、输入或产物协议错误 | 保留失败证据,修复代码、验证、重新部署运行 |
| 有效结果不支持假设 | 记录负面结果;有明确新假设且在预算内时再迭代 |
基线、候选和修复后运行使用不同实例名,保留代码/数据版本、参数和失败记录。同名重跑会替换当前目录并保留 persistent/。特征变化通常重跑 ETL 及下游,模型变化可复用兼容 ETL,组合规则变化可复用兼容预测;先核验上游修订、特征和协议。
比较时对齐有效日期、样本、股池、成本和指标定义,区分信号质量与组合收益。用于筛选方案的窗口不能同时作为独立确认;确认后继续调参需重新建立确认设计。不必为了得到正收益或更高指标无限尝试。
交付时简要报告:问题与改动、验证结果、执行目标/工作区、源码或插件版本、Task ID 与 started_at、输入修订、关键产物、基线对比与结论。说明数据质量、交易假设、独立确认情况,以及实际错误和未验证部分。完成标准是有证据地回答研究问题,或明确证据不足及继续所需条件。
6. 停止、清理与重跑
需要中止研究时,停止实际执行后再确认状态;取消日志观察不会停止 Task:
axonx kill --task-id 'base#demo#check' --timeout 5 --force false
axonx status --task-id 'base#demo#check' --detail fullkill 核验进程身份,子任务会解析到根进程所有者。确认任务已停止且不再需要证据后,才清理目录;不再需要示例插件时可卸载:
axonx delete_entries --paths '["tasks/base/base#demo#check"]'
axonx plugin uninstall axonx-example删除目录会移除 persistent/,没有活动任务保护;卸载插件保留历史产物,常驻服务需重启刷新。启动、重跑和删除同一目录须串行协调。需要保留结果时,改用新实例名运行。
7. 其他运行操作(按需)
服务更新
修改配置或安装插件后,使用第 3 节的 restart_service 流程刷新服务。更新 AxonX 框架时,根据安装来源选择 Git 或包索引。
远程服务从 AxonX 源码仓库启动时,可通过 Git 拉取已推送到目标仓库当前分支上游的提交。目标机需配置该上游的访问权限并具备 git/npm,运行中的 AxonX 源码须属于启动仓库。触发更新后,保存返回的 update_id,等待服务恢复,再查询该操作至 succeeded 或 failed:
axonx update_from_git --target node-b:1024
axonx get_update_status --update-id ACTUAL_UPDATE_ID --target node-b:1024远端依次停止服务、执行 git pull --ff-only、构建 Studio、以 editable 方式重新安装 AxonX 和 Studio、校验依赖及导入,再启动服务。它更新当前分支的上游,不切换分支;成功时自动重启,无需再调用 restart_service。请求成功只代表接受操作,须查询更新状态确认完成。
Git 更新不会重新安装研究插件,按插件的实际安装方式处理:
- editable 插件指向本次更新的源码目录时,普通 Python 代码修改会在服务重启后加载;依赖或入口点变化仍需按第 3 节重新
plugin install -e,再重启并验证。 - wheel 安装的插件不会随仓库拉取而更新,需按第 3 节安装新 wheel,再重启并验证。
- 插件源码在独立 Git 仓库时,需单独更新该仓库;
update_from_git只更新运行 AxonX 的启动仓库。
包索引安装的服务可更新已发布的 AxonX 和 Studio,完成后同样自动重启:
axonx update_from_pip --target node-b:1024
axonx get_update_status --update-id ACTUAL_UPDATE_ID --target node-b:1024本地服务使用相同命令并省略 --target。这些操作需要认证和由 axonx app 启动的 Daemon。更新会停止服务拥有的手动 CLI 执行,Daemon 拥有的定时 Task 继续运行;修改源码和依赖前须协调活动研究。失败可能留下部分源码/依赖变更,不会自动回滚。插件实验使用 plugin install,无需每次更新框架。
传输完整目录
使用 axonx.client.files.build_file_archive 构建含必需 directories.json 的 gzip tar 归档,再发送到目标服务:
axonx upload_archive --path files.tar.gz --target node-b:1024接收端完整替换清单内的每个目录,移除归档中未提供的文件,响应列出已替换目录。清理普通单文件上传时,将返回的暂存路径交给 discard_file。
定时运行
将以下内容保存为 scheduled.yaml,再启动服务:
extends: default
timezone: Asia/Shanghai
cron:
- expression: "0 16 * * 1-5"
command:
- axonx exec --task download_tushare_task
- --days-back 7axonx app --config scheduled.yamlcommand 接受一个字符串,或用空格拼成同一条命令的字符串片段列表。长片段使用 YAML >- 块,JSON 参数须保留命令文本内的引号;YAML 锚点可复用完整的带引号参数片段。
计划接受五字段表达式和本地 axonx exec --task NAME,不支持 shell 管道、重定向或远程选项,不补跑错过时点。配置修改后重启;已启动的定时执行可跨服务重启继续,手动执行随服务停止。检查 Task 状态与 logs/cron/entry-N.log,避免固定实例名的计划重叠。
服务内的定时 Job 使用 backend: scheduled;expression 复用 App 时区,arguments 提供定时公共入参。定时调用串行执行,随服务停止。
jobs:
hourly_diagnostics:
backend: scheduled
expression: "0 * * * *"
arguments: {}
enable_serve: false
steps:
- backend: diagnose_step使用内置 Agent
使用外部 Agent 开发时,直接使用宿主的代码工具与上述命令即可。需要 AxonX 内置 Agent 时,服务机配置 CLAUDE_CODE_API_KEY、CLAUDE_CODE_BASE_URL、CLAUDE_CODE_MODEL_NAME,源码开发将 components.agent.default.cwd 设为源码目录,再发起对话:
axonx agent_chat --message 'Inspect existing research tasks and report their actual status.' --stream true --client-timeout 600
axonx list_agent_sessions --limit 20保存返回的 metadata.session_id,将下面的 <SESSION_ID> 换成实际值,按需继续对话、读取历史或管理会话:
axonx agent_chat --session-id '<SESSION_ID>' --message 'Read the logs for the task we just discussed.' --stream true --client-timeout 600
axonx get_agent_session --session-id '<SESSION_ID>' --limit 20
axonx rename_agent_session --session-id '<SESSION_ID>' --title 'Factor validation'
axonx tag_agent_session --session-id '<SESSION_ID>' --tag research
axonx fork_agent_session --session-id '<SESSION_ID>' --title 'Alternative approach'
axonx cancel_agent_turn --session-id '<SESSION_ID>'
axonx delete_agent_session --session-id '<SESSION_ID>'取消轮次与 Task kill 分开处理;运行中的会话不能删除。命令默认返回一次查询结果,需要实时事件时使用 --stream true,供程序读取时再加 --stream-format json。--target、--token、--client-timeout、--stream、--stream-format 控制连接和显示,不是研究 Task 参数。