桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载本篇文章基于 Warp 仓库中的 REMOTE-1374 产品规格 与 技术规格系统讲解 Oz CLIWarp 的云端 Agent 编排平台命令行如何为oz run list与oz run get补齐 JSON 输出能力以及为oz run list新增一整套过滤、排序与分页参数。读完本文你将掌握用oz run list --output-format json | jq ...在 Shell 中脚本化查询 Agent 运行记录runs的完整姿势并理解从 clap 参数解析、客户端过滤结构到服务端 REST 查询参数映射的底层实现链路。一、背景为什么 CLI 需要“跟 REST API 对齐”在本次变更之前oz run list和oz run get只能以漂亮的 ASCII 卡片表格输出适合人眼扫一眼最近运行却无法支撑脚本化工作流两个命令都不响应全局的--output-formatjson标志表格是唯一的输出形态oz run list只暴露了--limit服务端支持的 state、source、creator、environment、时间范围、搜索等过滤条件在 CLI 上全部不可达公共 REST APIGET /api/v1/agent/runs早已支持全部过滤能力被 CLI 能力瓶颈卡住的用户只能转而手工拼curl这违背了 CLI 存在的意义。这一差距由 GitHub 客户报告CSAT-8397明确提出并一直阻塞着脚本化场景。因此本次改造的目标非常明确让oz run list/oz run get在功能上对齐公共 REST API 与 Oz Web 应用使针对 CLI 的脚本编写等价于针对 REST 端点编写。二、设计目标与非目标目标oz run list与oz run get尊重已有的全局--output-format标志取值pretty、text、jsonpretty仍为默认值且行为与之前完全一致CLI 的 JSON 输出就是服务端 JSON 响应本身原样透传解析为serde_json::Value后重新以 pretty-print 形式输出与 REST API / Web 应用保持同步客户端无需维护 schemaoz run list暴露适合终端工作流的过滤/排序参数oz run list --help的文本足够清晰可以独立充当脚本化参考手册。非目标不改动oz run conversation get与oz run get --conversation它们已支持 JSON且不属于本工单不改动oz run get的过滤面oz run get run_id依然只接受单个 ID不新增 pretty 表格列pretty输出功能上保持不变唯一新增行为是--output-format json开始生效本次不在 CLI 侧提供类 jq 的过滤支持——JSON 输出的结构设计就是为了让oz run list --output-format json | jq ...成为预期脚本模式一等公民的 jq 支持是后续工作不改动服务端 APICLI 只是把已有的查询参数暴露出来。三、CLI 命令面全览3.1oz run list既有参数-L, --limit N— 返回的最大运行条数。默认10服务端上限500。3.2oz run list新增过滤参数所有新参数均为可选缺省时保持原有行为。以下表格同时给出了每个 CLI 参数在底层映射的服务端查询参数映射实现见下文 [五、源码级实现解析] 的build_list_agent_runs_urlCLI 参数含义可取值 / 格式映射的 API 参数--state STATE按运行状态过滤可重复多个值之间是“任一匹配”OR 语义queued、pending、claimed、in-progress、succeeded、failed、error、blocked、cancelledstate每个值产生一个state...--source SOURCE按运行来源过滤单值API、CLI、SLACK、LINEAR、SCHEDULED_AGENT、WEB_APP、CLOUD_MODE、GITHUB_ACTION、INTERACTIVEsource--execution-location LOC按执行位置过滤单值local、remoteexecution_location--creator UID按创建者 UID用户或服务账号过滤任意 UID 字符串creator--environment ENV_ID按环境 ID 过滤任意环境 IDenvironment_id--skill SKILL按 skill 过滤如owner/repo:path/to/SKILL.mdskill_spec--schedule SCHEDULE_ID只返回由指定 scheduled agent 创建的运行任意 schedule IDschedule_id--ancestor-run RUN_ID只返回指定运行的后代运行任意 run IDancestor_run_id--name NAME按 Agent 配置名过滤任意名称name--model MODEL_ID按模型 ID 过滤任意模型 IDmodel_id--artifact-type TYPE按产生的产物类型过滤单值plan、pull-request、screenshot、fileartifact_type--created-after RFC3339只包含在给定 RFC 3339 时间戳之后创建的运行RFC 3339 时间戳created_after--created-before RFC3339只包含在给定时间戳之前创建的运行RFC 3339 时间戳created_before--updated-after RFC3339只包含在给定时间戳之后更新的运行RFC 3339 时间戳updated_after-q, --query TEXT对运行标题、prompt、skill spec 做模糊搜索任意文本q3.3oz run list排序与分页参数CLI 参数含义可取值映射的 API 参数--sort-by FIELD排序字段updated-at默认、created-at、title、agentsort_by--sort-order DIR排序方向asc、desc默认sort_order--cursor CURSOR不透明分页游标取自上一次列表响应的page_info.next_cursor任意游标字符串cursor使用--cursor时--sort-by与--sort-order必须与获取该游标时使用的取值一致服务端强制校验不一致返回400。值得注意的设计细节是CLI 故意使用--environment、--skill、--schedule、--ancestor-run、--created-after、--created-before、--updated-after、-q/--query这些终端友好的名字而不是 API 的environment_id、skill_spec、schedule_id、ancestor_run_id等底层再映射回既有 API 查询参数。3.4oz run get无参数变化oz run get run_id继续接受单个 run ID只有输出层发生变化见下文。对应源码可参见 crates/warp_cli/src/task.rs 中仅含task_id、--conversation与扁平化 JSON 配置的TaskGetArgs。四、输出格式行为按--output-format的取值pretty默认不变。渲染与现在相同的卡片式 ASCII 表格。text不变。同一表格去掉 box-drawing 字符。json新增oz run list --output-format json向 stdout 打印一个 pretty-print 的 JSON 对象正是GET /api/v1/agent/runs的响应体即{ runs: [...], page_info: { has_next_page: ..., next_cursor: ... } }。这里特意走/agent/runs路径使响应外层键为runs与 Web 应用及 REST 文档保持一致oz run get run_id --output-format json打印一个 pretty-print 的 JSON 对象正是GET /api/v1/agent/runs/:runId的响应体两种情况下客户端都只发一次请求把响应体解析为serde_json::Value再用serde_json::to_string_pretty重新序列化输出。任何字段都不会被丢弃、改名或重新解释因此未来服务端新增字段会自动出现在 CLI 输出中成功获取时退出码为0出错时非零错误以人类可读形式打印到 stderr与现状一致不会渲染成 JSON。五、实战示例5.1 脚本化获取最近的失败运行oz run list \ --state failed --state error \ --updated-after 2026-04-01T00:00:00Z \ --output-format json \ | jq -r .runs[] | \(.task_id) \(.title)这里--state重复两次即 OR 语义failed 或 error配合--updated-after缩小时间窗口输出交给jq做字段投影——这正是“JSON 与 REST 对齐”设计所期望的脚本模式。5.2 游标分页# 第一页按创建时间排序 oz run list --limit 50 --sort-by created-at --output-format json page1.json # 跟随游标取下一页 CURSOR$(jq -r .page_info.next_cursor page1.json) oz run list --limit 50 --sort-by created-at --cursor $CURSOR --output-format json注意第二条命令的--sort-by created-at必须与第一条一致否则服务端返回400见下文边界情况。5.3 以 JSON 获取单个运行oz run get 01HX9Y... --output-format json | jq .state5.4 既有 pretty 输出保持不变$ oz run list --limit 3 Agent Runs (3): ... (existing table output)不带任何新参数时输出与改动前完全一致旧脚本无需迁移。六、源码级实现解析本节沿着“CLI 参数层 → 客户端过滤层 → 输出层”的调用链给出仓库内对应的实现证据。6.1 CLI 参数层clap 声明与枚举校验oz run list的全部参数定义在 crates/warp_cli/src/task.rs 的ListTasksArgs结构体中TaskCommand::List是其子命令入口。几个关键实现手法枚举型参数使用 clapValueEnum状态、来源、执行位置、产物类型、排序字段、排序方向分别对应RunStateArg、RunSourceArg、ExecutionLocationArg、ArtifactTypeArg、RunSortByArg见 task.rs以及通用的SortOrderArg见 crates/warp_cli/src/sort_order.rs。非法枚举值会在 clap 解析阶段直接报错并列出可接受取值--state是VecRunStateArg可重复空向量表示“不过滤”。这正是重复--state failed --state error产生 OR 语义的根源时间戳参数用value_parser绑定parse_rfc3339见 crates/warp_cli/src/date_time.rs内部调用DateTime::parse_from_rfc3339并统一归一化为DateTimeUtc校验发生在 clap 层而非把非法时间戳推给服务端报错。--output-format是全局参数定义在 crates/warp_cli/src/lib.rs 的GlobalOptions中支持环境变量WARP_OUTPUT_FORMAT覆盖默认pretty取值来自 crates/warp_cli/src/agent.rs 的OutputFormat枚举json、ndjson、pretty、text。6.2 参数解析的测试佐证crates/warp_cli/src/task_tests.rs 用独立的小型TestApp包装ListTasksArgs做纯 clap 解析测试可直接视为“合法参数速查表”all_filter_flags_parse一次性解析全部新参数--limit 42、--state in-progress、--source api、--execution-location remote、三个时间戳、-q oz run、--sort-by created-at --sort-order asc --cursor abcd等并逐字段断言state_flag_is_repeatable验证--state failed --state error解析为[Failed, Error]invalid_state_is_rejected/invalid_sort_by_is_rejected/invalid_execution_location_is_rejected/invalid_artifact_type_is_rejected验证非法枚举值产生InvalidValue错误invalid_created_after_timestamp_is_rejected验证非法时间戳产生ValueValidation错误timestamps_are_converted_to_utc验证2026-04-03T12:30:0002:00会被归一化为 UTC 的10:30。6.3 客户端过滤层TaskListFilter与 URL 构建CLI 参数首先在 app/src/ai/agent_sdk/ambient.rs 的filter_from_args中被机械地翻译成服务端过滤结构TaskListFilterclap 枚举逐一转换为对应的服务端枚举字符串字段原样透传。TaskListFilter定义在 app/src/server/server_api/ai.rs覆盖全部 18 个字段creator_uid、三个时间戳、states、source、execution_location、environment_id、skill_spec、schedule_id、ancestor_run_id、config_name、model_id、artifact_type、search_query、sort_by、sort_order、cursor。随后 build_list_agent_runs_url 把过滤结构拼成请求 URLagent/runs?limit...为基底每个Option字段出现时追加一个keyvaluestates则是每个状态各追加一个state...对所有值经urlencoding::encode百分号编码时间戳用to_rfc3339()序列化。值得展开的两个“命名翻译”--source INTERACTIVE→sourceLOCALCLI 枚举RunSourceArg::Interactive经run_source_from_arg映射到AgentSource::Interactive而AgentSource::as_str实现app/src/ai/ambient_agents/task.rs明确把Interactive序列化为公共 API 使用的LOCAL用于本地交互任务——Agent Mode 与本地 CLI 运行。同理RunSourceArg::Api→AgentSource::AgentWebhook→API枚举值的大小写与拼写服务端枚举ArtifactType的as_query_param返回PLAN、PULL_REQUEST、SCREENSHOT、FILERunSortBy返回updated_at、created_at、title、agentRunSortOrder返回asc、desc见 ai.rs。CLI 侧对枚举值大小写不敏感帮助文本统一用小写。6.4 输出层按OutputFormat分流入口函数list_ambient_agent_tasks与get_ambient_agent_task_statusapp/src/ai/agent_sdk/ambient.rs接收GlobalOptions读取其中的output_format后进入AmbientAgentRunner::list_tasks/get_task_statusJson或被--jq强制 JSON走 raw 接口list_agent_runs_raw/get_agent_run_raw拿到serde_json::Value后以serde_json::to_string_pretty打印到 stdout服务端字段原样透传一个字节不改仅重新排版Pretty/Text走类型化接口list_ambient_agent_tasks/get_ambient_agent_task反序列化为AmbientAgentTask后沿用原有的print_tasks_table卡片渲染器行为与改动前一致。两种输出刻意不混用一次调用只发一次 HTTP 请求pretty/text 走类型化结构体渲染需要的字段JSON 走serde_json::Value保真透传。此外ListTasksArgs与TaskGetArgs还扁平化了 json_filter.rs 的JsonOutput--jq FILTER参数用 jaq 引擎编译执行force_json_output()会在用户指定--jq时自动切换为 JSON 获取路径即便用户同时选择了 pretty 输出。6.5 不变量与边界情况规格文档明确列出的行为契约如下--state可重复、OR 语义与服务端一致--source单值未知值产生 clap 级错误并列出可接受取值--execution-location、--artifact-type、--sort-by、--sort-order均单值由 clap 对照允许集合校验时间戳参数要求 RFC 3339非法时间戳在请求发出前即被 clap 解析错误拒绝--cursor与--sort-by/--sort-order不一致时服务端返回400CLI 原样透出该错误不做多余客户端校验过滤结果为空时JSON 返回空的runs数组page_info块依然存在pretty/text 显示No runs found.权限语义不变服务端本就按认证主体的个人运行 团队运行来限定列表范围CLI 不额外增减作用域pretty/text 渲染继续反序列化到既有AmbientAgentTask结构体客户端不认识的字段在渲染时被忽略但因 JSON 输出直接走serde_json::Value这些字段会完整保留输出体积受--limit上限约束oz run get单个运行的载荷很小不含完整对话转写。七、成功标准与验证方式本次改造的验收标准可归纳为六条oz run list --output-format json打印GET /api/v1/agent/runs的精确 JSON 响应体pretty-print 后oz run get run_id --output-format json打印GET /api/v1/agent/runs/:runId的精确 JSON 响应体pretty-print 后上文列出的每个过滤参数都从 CLI 可达、映射到对应 API 查询参数且枚举型参数在 CLI 层完成校验不带新参数运行oz run list产生与之前相同的 pretty 输出oz run list --help文档化全部过滤、排序与分页参数包括枚举参数的可接受取值服务端错误非法游标、非法时间戳等以非零退出码打印到 stderr与现有行为一致。验证手段分为单元测试与手动验证两层Rust 单元测试CLI 参数解析测试每个新参数解析为预期过滤值、枚举参数拒绝非法输入即 task_tests.rs客户端过滤到 URL 的翻译测试每个字段生成正确的查询参数、重复--state产生多个state...含时间戳的百分号编码逐字节比对输出层测试JSON 输出与服务端原始 JSON 逐字节一致仅排版差异、pretty/text 输出渲染列不变手动验证针对 staging用一批真实运行逐一演练每个过滤参数并把 CLI 输出与 Web 应用对照确认--cursor在每种--sort-by下都能正确翻页确认非法 RFC 3339 与非法游标以非零退出码呈现帮助文本快照oz run list --help与oz run get --help被捕获进测试防止意外回归。八、兼容性与演进本次改动为单 PR、无服务端变更、无 schema 迁移也无需新增 feature flag命令整体已由AmbientAgentsCommandLine控制在已启用的表面内增加参数与让--output-format生效是安全的。未传--output-format的旧脚本输出不变。CLI 列表请求的路径从/api/v1/agent/tasks迁移到/api/v1/agent/runs服务端两路径等价但/runs是与 Web 应用及 REST 文档一致的优先拼写以便后续演进不产生分歧。技术规格中列出的后续工作包括CLI 输出的一等公民 jq 风格--filter、为--output-format text提供单行一条记录的精简渲染器以及将本次成果镜像到oz run conversation get/oz run get --conversation。风险方面规格文档重点提示了三处其一终端友好的 flag 名与 API 参数名的偏差需在--help与文档中显式标注映射其二JSON 输出刻意绕过AmbientAgentTask结构体服务端畸形响应会被原样透出这是保真语义的代价也正是目标所在其三游标与排序条件不匹配时服务端返回400由 CLI 原样透传错误不做客户端侧多余校验。赞分享桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载相关推荐Warp Oz CLI 的 oz run list / oz run get 过滤、排序与 JSON 输出能力从 REST API 到命令行的完整对齐Warp Oz CLI 的 oz run list / oz run get 过滤、排序与 JSON 输出能力从 REST API 到命令行的完整对齐 oz桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp CLI 内置 jq 过滤oz run get / oz run list 的 --jq 标志设计与源码实现Warp CLI 内置 jq 过滤 oz run get / oz run list 的 jq 标志设计与源码实现 导读 本文围绕 specs/REMOTE桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp CLI 内置 jq 过滤为 oz run get / oz run list 打造零依赖的 JSON 处理管线Warp CLI 内置 jq 过滤为 oz run get / oz run list 打造零依赖的 JSON 处理管线 导读 本文讲解 Warp 开源仓库中桌面应用开发者工具人工智能AI 应用AI Agent代码智能体上一篇Vue-Vben-Admin 多标签页功能深度解析useMultipleTabs 源码实现揭秘下一篇Awesome Cheatsheets微服务架构速查服务发现与配置中心创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Warp Oz CLI 的 `oz run list` / `oz run get`：JSON 输出与完整过滤排序实战指南
桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载本篇文章基于 Warp 仓库中的 REMOTE-1374 产品规格 与 技术规格系统讲解 Oz CLIWarp 的云端 Agent 编排平台命令行如何为oz run list与oz run get补齐 JSON 输出能力以及为oz run list新增一整套过滤、排序与分页参数。读完本文你将掌握用oz run list --output-format json | jq ...在 Shell 中脚本化查询 Agent 运行记录runs的完整姿势并理解从 clap 参数解析、客户端过滤结构到服务端 REST 查询参数映射的底层实现链路。一、背景为什么 CLI 需要“跟 REST API 对齐”在本次变更之前oz run list和oz run get只能以漂亮的 ASCII 卡片表格输出适合人眼扫一眼最近运行却无法支撑脚本化工作流两个命令都不响应全局的--output-formatjson标志表格是唯一的输出形态oz run list只暴露了--limit服务端支持的 state、source、creator、environment、时间范围、搜索等过滤条件在 CLI 上全部不可达公共 REST APIGET /api/v1/agent/runs早已支持全部过滤能力被 CLI 能力瓶颈卡住的用户只能转而手工拼curl这违背了 CLI 存在的意义。这一差距由 GitHub 客户报告CSAT-8397明确提出并一直阻塞着脚本化场景。因此本次改造的目标非常明确让oz run list/oz run get在功能上对齐公共 REST API 与 Oz Web 应用使针对 CLI 的脚本编写等价于针对 REST 端点编写。二、设计目标与非目标目标oz run list与oz run get尊重已有的全局--output-format标志取值pretty、text、jsonpretty仍为默认值且行为与之前完全一致CLI 的 JSON 输出就是服务端 JSON 响应本身原样透传解析为serde_json::Value后重新以 pretty-print 形式输出与 REST API / Web 应用保持同步客户端无需维护 schemaoz run list暴露适合终端工作流的过滤/排序参数oz run list --help的文本足够清晰可以独立充当脚本化参考手册。非目标不改动oz run conversation get与oz run get --conversation它们已支持 JSON且不属于本工单不改动oz run get的过滤面oz run get run_id依然只接受单个 ID不新增 pretty 表格列pretty输出功能上保持不变唯一新增行为是--output-format json开始生效本次不在 CLI 侧提供类 jq 的过滤支持——JSON 输出的结构设计就是为了让oz run list --output-format json | jq ...成为预期脚本模式一等公民的 jq 支持是后续工作不改动服务端 APICLI 只是把已有的查询参数暴露出来。三、CLI 命令面全览3.1oz run list既有参数-L, --limit N— 返回的最大运行条数。默认10服务端上限500。3.2oz run list新增过滤参数所有新参数均为可选缺省时保持原有行为。以下表格同时给出了每个 CLI 参数在底层映射的服务端查询参数映射实现见下文 [五、源码级实现解析] 的build_list_agent_runs_urlCLI 参数含义可取值 / 格式映射的 API 参数--state STATE按运行状态过滤可重复多个值之间是“任一匹配”OR 语义queued、pending、claimed、in-progress、succeeded、failed、error、blocked、cancelledstate每个值产生一个state...--source SOURCE按运行来源过滤单值API、CLI、SLACK、LINEAR、SCHEDULED_AGENT、WEB_APP、CLOUD_MODE、GITHUB_ACTION、INTERACTIVEsource--execution-location LOC按执行位置过滤单值local、remoteexecution_location--creator UID按创建者 UID用户或服务账号过滤任意 UID 字符串creator--environment ENV_ID按环境 ID 过滤任意环境 IDenvironment_id--skill SKILL按 skill 过滤如owner/repo:path/to/SKILL.mdskill_spec--schedule SCHEDULE_ID只返回由指定 scheduled agent 创建的运行任意 schedule IDschedule_id--ancestor-run RUN_ID只返回指定运行的后代运行任意 run IDancestor_run_id--name NAME按 Agent 配置名过滤任意名称name--model MODEL_ID按模型 ID 过滤任意模型 IDmodel_id--artifact-type TYPE按产生的产物类型过滤单值plan、pull-request、screenshot、fileartifact_type--created-after RFC3339只包含在给定 RFC 3339 时间戳之后创建的运行RFC 3339 时间戳created_after--created-before RFC3339只包含在给定时间戳之前创建的运行RFC 3339 时间戳created_before--updated-after RFC3339只包含在给定时间戳之后更新的运行RFC 3339 时间戳updated_after-q, --query TEXT对运行标题、prompt、skill spec 做模糊搜索任意文本q3.3oz run list排序与分页参数CLI 参数含义可取值映射的 API 参数--sort-by FIELD排序字段updated-at默认、created-at、title、agentsort_by--sort-order DIR排序方向asc、desc默认sort_order--cursor CURSOR不透明分页游标取自上一次列表响应的page_info.next_cursor任意游标字符串cursor使用--cursor时--sort-by与--sort-order必须与获取该游标时使用的取值一致服务端强制校验不一致返回400。值得注意的设计细节是CLI 故意使用--environment、--skill、--schedule、--ancestor-run、--created-after、--created-before、--updated-after、-q/--query这些终端友好的名字而不是 API 的environment_id、skill_spec、schedule_id、ancestor_run_id等底层再映射回既有 API 查询参数。3.4oz run get无参数变化oz run get run_id继续接受单个 run ID只有输出层发生变化见下文。对应源码可参见 crates/warp_cli/src/task.rs 中仅含task_id、--conversation与扁平化 JSON 配置的TaskGetArgs。四、输出格式行为按--output-format的取值pretty默认不变。渲染与现在相同的卡片式 ASCII 表格。text不变。同一表格去掉 box-drawing 字符。json新增oz run list --output-format json向 stdout 打印一个 pretty-print 的 JSON 对象正是GET /api/v1/agent/runs的响应体即{ runs: [...], page_info: { has_next_page: ..., next_cursor: ... } }。这里特意走/agent/runs路径使响应外层键为runs与 Web 应用及 REST 文档保持一致oz run get run_id --output-format json打印一个 pretty-print 的 JSON 对象正是GET /api/v1/agent/runs/:runId的响应体两种情况下客户端都只发一次请求把响应体解析为serde_json::Value再用serde_json::to_string_pretty重新序列化输出。任何字段都不会被丢弃、改名或重新解释因此未来服务端新增字段会自动出现在 CLI 输出中成功获取时退出码为0出错时非零错误以人类可读形式打印到 stderr与现状一致不会渲染成 JSON。五、实战示例5.1 脚本化获取最近的失败运行oz run list \ --state failed --state error \ --updated-after 2026-04-01T00:00:00Z \ --output-format json \ | jq -r .runs[] | \(.task_id) \(.title)这里--state重复两次即 OR 语义failed 或 error配合--updated-after缩小时间窗口输出交给jq做字段投影——这正是“JSON 与 REST 对齐”设计所期望的脚本模式。5.2 游标分页# 第一页按创建时间排序 oz run list --limit 50 --sort-by created-at --output-format json page1.json # 跟随游标取下一页 CURSOR$(jq -r .page_info.next_cursor page1.json) oz run list --limit 50 --sort-by created-at --cursor $CURSOR --output-format json注意第二条命令的--sort-by created-at必须与第一条一致否则服务端返回400见下文边界情况。5.3 以 JSON 获取单个运行oz run get 01HX9Y... --output-format json | jq .state5.4 既有 pretty 输出保持不变$ oz run list --limit 3 Agent Runs (3): ... (existing table output)不带任何新参数时输出与改动前完全一致旧脚本无需迁移。六、源码级实现解析本节沿着“CLI 参数层 → 客户端过滤层 → 输出层”的调用链给出仓库内对应的实现证据。6.1 CLI 参数层clap 声明与枚举校验oz run list的全部参数定义在 crates/warp_cli/src/task.rs 的ListTasksArgs结构体中TaskCommand::List是其子命令入口。几个关键实现手法枚举型参数使用 clapValueEnum状态、来源、执行位置、产物类型、排序字段、排序方向分别对应RunStateArg、RunSourceArg、ExecutionLocationArg、ArtifactTypeArg、RunSortByArg见 task.rs以及通用的SortOrderArg见 crates/warp_cli/src/sort_order.rs。非法枚举值会在 clap 解析阶段直接报错并列出可接受取值--state是VecRunStateArg可重复空向量表示“不过滤”。这正是重复--state failed --state error产生 OR 语义的根源时间戳参数用value_parser绑定parse_rfc3339见 crates/warp_cli/src/date_time.rs内部调用DateTime::parse_from_rfc3339并统一归一化为DateTimeUtc校验发生在 clap 层而非把非法时间戳推给服务端报错。--output-format是全局参数定义在 crates/warp_cli/src/lib.rs 的GlobalOptions中支持环境变量WARP_OUTPUT_FORMAT覆盖默认pretty取值来自 crates/warp_cli/src/agent.rs 的OutputFormat枚举json、ndjson、pretty、text。6.2 参数解析的测试佐证crates/warp_cli/src/task_tests.rs 用独立的小型TestApp包装ListTasksArgs做纯 clap 解析测试可直接视为“合法参数速查表”all_filter_flags_parse一次性解析全部新参数--limit 42、--state in-progress、--source api、--execution-location remote、三个时间戳、-q oz run、--sort-by created-at --sort-order asc --cursor abcd等并逐字段断言state_flag_is_repeatable验证--state failed --state error解析为[Failed, Error]invalid_state_is_rejected/invalid_sort_by_is_rejected/invalid_execution_location_is_rejected/invalid_artifact_type_is_rejected验证非法枚举值产生InvalidValue错误invalid_created_after_timestamp_is_rejected验证非法时间戳产生ValueValidation错误timestamps_are_converted_to_utc验证2026-04-03T12:30:0002:00会被归一化为 UTC 的10:30。6.3 客户端过滤层TaskListFilter与 URL 构建CLI 参数首先在 app/src/ai/agent_sdk/ambient.rs 的filter_from_args中被机械地翻译成服务端过滤结构TaskListFilterclap 枚举逐一转换为对应的服务端枚举字符串字段原样透传。TaskListFilter定义在 app/src/server/server_api/ai.rs覆盖全部 18 个字段creator_uid、三个时间戳、states、source、execution_location、environment_id、skill_spec、schedule_id、ancestor_run_id、config_name、model_id、artifact_type、search_query、sort_by、sort_order、cursor。随后 build_list_agent_runs_url 把过滤结构拼成请求 URLagent/runs?limit...为基底每个Option字段出现时追加一个keyvaluestates则是每个状态各追加一个state...对所有值经urlencoding::encode百分号编码时间戳用to_rfc3339()序列化。值得展开的两个“命名翻译”--source INTERACTIVE→sourceLOCALCLI 枚举RunSourceArg::Interactive经run_source_from_arg映射到AgentSource::Interactive而AgentSource::as_str实现app/src/ai/ambient_agents/task.rs明确把Interactive序列化为公共 API 使用的LOCAL用于本地交互任务——Agent Mode 与本地 CLI 运行。同理RunSourceArg::Api→AgentSource::AgentWebhook→API枚举值的大小写与拼写服务端枚举ArtifactType的as_query_param返回PLAN、PULL_REQUEST、SCREENSHOT、FILERunSortBy返回updated_at、created_at、title、agentRunSortOrder返回asc、desc见 ai.rs。CLI 侧对枚举值大小写不敏感帮助文本统一用小写。6.4 输出层按OutputFormat分流入口函数list_ambient_agent_tasks与get_ambient_agent_task_statusapp/src/ai/agent_sdk/ambient.rs接收GlobalOptions读取其中的output_format后进入AmbientAgentRunner::list_tasks/get_task_statusJson或被--jq强制 JSON走 raw 接口list_agent_runs_raw/get_agent_run_raw拿到serde_json::Value后以serde_json::to_string_pretty打印到 stdout服务端字段原样透传一个字节不改仅重新排版Pretty/Text走类型化接口list_ambient_agent_tasks/get_ambient_agent_task反序列化为AmbientAgentTask后沿用原有的print_tasks_table卡片渲染器行为与改动前一致。两种输出刻意不混用一次调用只发一次 HTTP 请求pretty/text 走类型化结构体渲染需要的字段JSON 走serde_json::Value保真透传。此外ListTasksArgs与TaskGetArgs还扁平化了 json_filter.rs 的JsonOutput--jq FILTER参数用 jaq 引擎编译执行force_json_output()会在用户指定--jq时自动切换为 JSON 获取路径即便用户同时选择了 pretty 输出。6.5 不变量与边界情况规格文档明确列出的行为契约如下--state可重复、OR 语义与服务端一致--source单值未知值产生 clap 级错误并列出可接受取值--execution-location、--artifact-type、--sort-by、--sort-order均单值由 clap 对照允许集合校验时间戳参数要求 RFC 3339非法时间戳在请求发出前即被 clap 解析错误拒绝--cursor与--sort-by/--sort-order不一致时服务端返回400CLI 原样透出该错误不做多余客户端校验过滤结果为空时JSON 返回空的runs数组page_info块依然存在pretty/text 显示No runs found.权限语义不变服务端本就按认证主体的个人运行 团队运行来限定列表范围CLI 不额外增减作用域pretty/text 渲染继续反序列化到既有AmbientAgentTask结构体客户端不认识的字段在渲染时被忽略但因 JSON 输出直接走serde_json::Value这些字段会完整保留输出体积受--limit上限约束oz run get单个运行的载荷很小不含完整对话转写。七、成功标准与验证方式本次改造的验收标准可归纳为六条oz run list --output-format json打印GET /api/v1/agent/runs的精确 JSON 响应体pretty-print 后oz run get run_id --output-format json打印GET /api/v1/agent/runs/:runId的精确 JSON 响应体pretty-print 后上文列出的每个过滤参数都从 CLI 可达、映射到对应 API 查询参数且枚举型参数在 CLI 层完成校验不带新参数运行oz run list产生与之前相同的 pretty 输出oz run list --help文档化全部过滤、排序与分页参数包括枚举参数的可接受取值服务端错误非法游标、非法时间戳等以非零退出码打印到 stderr与现有行为一致。验证手段分为单元测试与手动验证两层Rust 单元测试CLI 参数解析测试每个新参数解析为预期过滤值、枚举参数拒绝非法输入即 task_tests.rs客户端过滤到 URL 的翻译测试每个字段生成正确的查询参数、重复--state产生多个state...含时间戳的百分号编码逐字节比对输出层测试JSON 输出与服务端原始 JSON 逐字节一致仅排版差异、pretty/text 输出渲染列不变手动验证针对 staging用一批真实运行逐一演练每个过滤参数并把 CLI 输出与 Web 应用对照确认--cursor在每种--sort-by下都能正确翻页确认非法 RFC 3339 与非法游标以非零退出码呈现帮助文本快照oz run list --help与oz run get --help被捕获进测试防止意外回归。八、兼容性与演进本次改动为单 PR、无服务端变更、无 schema 迁移也无需新增 feature flag命令整体已由AmbientAgentsCommandLine控制在已启用的表面内增加参数与让--output-format生效是安全的。未传--output-format的旧脚本输出不变。CLI 列表请求的路径从/api/v1/agent/tasks迁移到/api/v1/agent/runs服务端两路径等价但/runs是与 Web 应用及 REST 文档一致的优先拼写以便后续演进不产生分歧。技术规格中列出的后续工作包括CLI 输出的一等公民 jq 风格--filter、为--output-format text提供单行一条记录的精简渲染器以及将本次成果镜像到oz run conversation get/oz run get --conversation。风险方面规格文档重点提示了三处其一终端友好的 flag 名与 API 参数名的偏差需在--help与文档中显式标注映射其二JSON 输出刻意绕过AmbientAgentTask结构体服务端畸形响应会被原样透出这是保真语义的代价也正是目标所在其三游标与排序条件不匹配时服务端返回400由 CLI 原样透传错误不做客户端侧多余校验。赞分享桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载相关推荐Warp Oz CLI 的 oz run list / oz run get 过滤、排序与 JSON 输出能力从 REST API 到命令行的完整对齐Warp Oz CLI 的 oz run list / oz run get 过滤、排序与 JSON 输出能力从 REST API 到命令行的完整对齐 oz桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp CLI 内置 jq 过滤oz run get / oz run list 的 --jq 标志设计与源码实现Warp CLI 内置 jq 过滤 oz run get / oz run list 的 jq 标志设计与源码实现 导读 本文围绕 specs/REMOTE桌面应用开发者工具人工智能AI 应用AI Agent代码智能体Warp CLI 内置 jq 过滤为 oz run get / oz run list 打造零依赖的 JSON 处理管线Warp CLI 内置 jq 过滤为 oz run get / oz run list 打造零依赖的 JSON 处理管线 导读 本文讲解 Warp 开源仓库中桌面应用开发者工具人工智能AI 应用AI Agent代码智能体上一篇Vue-Vben-Admin 多标签页功能深度解析useMultipleTabs 源码实现揭秘下一篇Awesome Cheatsheets微服务架构速查服务发现与配置中心创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考