工作区与上传 API
文件 Job 操作所选工作区,产物路径来自当前 Task metadata。
遵循 HTTP/MCP 协议,通过 axonx help --job NAME 查询 Schema。示例 Task/会话 ID 需替换为实际值。
接口列表
| Job | 用途 |
|---|---|
list_entries | 列出工作区内一个目录的条目。 |
preview_file | 预览工作区内一个受支持格式的文件。 |
delete_entries | 删除工作区内多个文件或目录。 |
list_entries
列出工作区内一个目录的条目。
| 参数 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|
path | string | 否 | {"default":""} |
offset | integer | 否 | {"minimum":0,"default":0} |
{
"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_missing | boolean | 否 | {"default":false} |
max_bytes | integer | 否 | {"minimum":1,"maximum":33554432} |
path | string | 是 | — |
offset | integer | 否 | {"minimum":0,"default":0} |
limit | integer | 否 | {"minimum":1,"maximum":5000,"default":200} |
{
"arguments": {
"path": "tasks/base/base#demo#api-check/metadata.json",
"limit": 20,
"max_bytes": 8192
}
}对尚未产出的文件可设置 allow_missing: true:文件不存在时成功返回 answer: null,默认仍将缺失视为错误。无效路径、权限异常和文件内容损坏保留原有报错或 parse_error 行为。
delete_entries
删除工作区内多个文件或目录。
| 参数 | 类型 | 必填 | 默认/约束 |
|---|---|---|---|
paths | array | 是 | {"minItems":1,"maxItems":200} |
{
"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 通过此接口发送本地文件:
axonx upload --path dist/plugins/ACTUAL_FILENAME.whl --target HOST:1024等价的 multipart 请求为:
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 使用返回的工作区相对路径清理:
axonx discard_file --path tmp/uploads/UUID/file.whl --target HOST:1024完整目录替换
POST /upload?mode=replace 通过相同的二进制或 multipart 上传格式接收 gzip tar 归档。默认 mode=stage 保留普通文件暂存行为。
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,更大的文件返回错误 |
| CSV | columns、行数组、offset、limit、has_more;表头不计入行偏移 |
| JSONL / NDJSON | rows 含 line、content、data、parse_error、逐行 truncated;每页另有独立的 512 KiB 预算,不受 max_bytes 控制,并返回页级 truncated、has_more |
| Parquet | columns、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,将预览作为完整证据前还需检查完整源文件。