Skip to content

工作区与上传 API ​

文件 Job 操作所选工作区,产物路径来自当前 Task metadata。

遵循 HTTP/MCP 协议,通过 axonx help --job NAME 查询 Schema。示例 Task/会话 ID 需替换为实际值。

接口列表 ​

Job用途
list_entries列出工作区内一个目录的条目。
preview_file预览工作区内一个受支持格式的文件。
delete_entries删除工作区内多个文件或目录。

list_entries ​

列出工作区内一个目录的条目。

参数类型必填默认/约束
pathstring否{"default":""}
offsetinteger否{"minimum":0,"default":0}
json
{
  "arguments": {
    "path": ""
  }
}

answer 包含 path、绝对 workspace_root、entries 和 truncated。目录优先,其后按忽略大小写的名称及原始名称排序;从 offset 起最多返回 5000 项。截断时以 offset + entries.length 继续。条目包含 name、相对 path、kind、preview_kind、supported、size、modified_at;可列出符号链接,但不能沿其访问。

preview_file ​

预览工作区内一个受支持格式的文件。

参数类型必填默认/约束
allow_missingboolean否{"default":false}
max_bytesinteger否{"minimum":1,"maximum":33554432}
pathstring是—
offsetinteger否{"minimum":0,"default":0}
limitinteger否{"minimum":1,"maximum":5000,"default":200}
json
{
  "arguments": {
    "path": "tasks/base/base#demo#api-check/metadata.json",
    "limit": 20,
    "max_bytes": 8192
  }
}

对尚未产出的文件可设置 allow_missing: true:文件不存在时成功返回 answer: null,默认仍将缺失视为错误。无效路径、权限异常和文件内容损坏保留原有报错或 parse_error 行为。

delete_entries ​

删除工作区内多个文件或目录。

参数类型必填默认/约束
pathsarray是{"minItems":1,"maxItems":200}
json
{
  "arguments": {
    "paths": ["tasks/base/base#demo#api-check"]
  }
}

删除工作区相对路径。这是通用文件操作,不保护活动 Task 进程,删除目录前应确认已停止并与执行串行协调。

文件上传与清理 ​

POST /upload 接受带 x-file-name 的二进制请求体,或 multipart file 和可选 directory;x-file-directory 优先于 multipart 目录。目标限制在工作区 tmp,使用 UUID 目录避免冲突。默认传输预算 512 MiB,multipart 额外允许 64 KiB 封装。

CLI 通过此接口发送本地文件:

bash
axonx upload --path dist/plugins/ACTUAL_FILENAME.whl --target HOST:1024

等价的 multipart 请求为:

bash
curl --fail-with-body 'http://HOST:1024/upload' \
  -H "Authorization: Bearer $AXONX_TARGET_TOKEN" \
  -F 'file=@dist/plugins/ACTUAL_FILENAME.whl'

JobResponse.answer 为 StagedFile:{ "path": "tmp/uploads/UUID/file.whl", "location": "/absolute/workspace/tmp/uploads/UUID/file.whl", "size": 123 }。目标机原生插件安装使用 location,DELETE /upload?path=... 使用 path。上传和清理使用同一服务 token。上传不安装或执行文件,插件安装也不自动消费/删除上传文件,应在 finally 中清理。过期文件在后续上传时机会性清理(默认保留七天),不是安装后的即时清理。

CLI 使用返回的工作区相对路径清理:

bash
axonx discard_file --path tmp/uploads/UUID/file.whl --target HOST:1024

完整目录替换 ​

POST /upload?mode=replace 通过相同的二进制或 multipart 上传格式接收 gzip tar 归档。默认 mode=stage 保留普通文件暂存行为。

bash
axonx upload_archive --path ./files.tar.gz --target HOST:1024

归档以 directories.json 开始,内容为不重叠的工作区相对目标目录 JSON 数组,随后包含这些路径下的全部普通文件。例如 ["reports/daily"] 表示完整替换 reports/daily/,允许声明空目录。符号链接、路径越界、重复成员、重叠根目录,以及覆盖上传或文件接收暂存区的目标均被拒绝。

请求大小和包含扩展头、填充在内的完整展开 tar 流都必须满足 transfer_budget_bytes。接收端先暂存解包,再替换指定目录;安装失败时回滚。被替换目录中未再提供的旧文件会移除,清单外目录保留。文件按原始字节接收,不执行、不解释。并发读取可能遇到目录替换过程,多目录批次不提供读取事务。

返回已替换的目录列表,例如 ["reports/daily"]。完成或回滚成功后清理上传归档和操作暂存;回滚本身失败时,原始目录保留在报错指出的暂存备份路径中,供恢复使用。Python 调用方可用 axonx.client.files.build_file_archive 构建归档,通过 HttpClient.upload_archive 发送。

预览响应类型 ​

所有预览都包含 kind 与字节 size,限制按格式区分:

格式响应字段与限制
文本content、truncated;默认前 512 KiB,可用 max_bytes 覆盖
Markdown正文 content、解析后的 frontmatter、frontmatter_error、truncated;字节预算同文本
JSON / YAML解析的 data,或带 parse_error 的原文 content;不传 max_bytes 时最多解析 32 MiB,更大的文件返回错误
CSVcolumns、行数组、offset、limit、has_more;表头不计入行偏移
JSONL / NDJSONrows 含 line、content、data、parse_error、逐行 truncated;每页另有独立的 512 KiB 预算,不受 max_bytes 控制,并返回页级 truncated、has_more
Parquetcolumns、column_schema、行数组、row_count、row_group_count、offset、limit、has_more
不支持的格式kind="unsupported"、size,不预览内容

行格式默认每页 200 行,最多 5000 行。max_bytes 仅作用于文本、Markdown、JSON 和 YAML,上限为 32 MiB。截断的 JSON/YAML 返回带标记的原文前缀和解析错误,不返回解析对象。CLI 额外设置默认 20 行和 8192 字节;普通 HTTP/MCP Job 使用上述服务端默认值。行分页依据 has_more,将预览作为完整证据前还需检查完整源文件。

源码:默认 Job 契约 · Job 协议

Agent-native quant research.