Skip to content

fix(cli): preserve structured API error context#2803

Open
qin-ctx wants to merge 1 commit into
mainfrom
fix/cli-structured-api-errors
Open

fix(cli): preserve structured API error context#2803
qin-ctx wants to merge 1 commit into
mainfrom
fix/cli-structured-api-errors

Conversation

@qin-ctx

@qin-ctx qin-ctx commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

Description

改进 ov_cli 对 OpenViking API、请求、响应、超时和服务健康错误的分类与展示,保留后端返回的结构化错误 code、HTTP status 和 details,并让中文错误提示与恢复动作更准确。

Related Issue

暂无关联 issue。

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

  • 为 CLI 错误模型增加结构化 API 错误字段,以及独立的 Timeout、Request、Response、ServerUnhealthy 错误类型。
  • 统一 HTTP 请求、响应体读取和 API envelope 解析路径,避免把超时、响应解析失败、权限失败等误报为普通网络错误。
  • 更新 config/status/error/help UI 的中英文提示、建议动作和测试覆盖,补充 set-tags 帮助入口。

Before / After examples:

  • API 返回 PROCESSING_ERROR
    • Before: 只展示普通 API 错误文本,code/details 容易丢失,verbose 信息不足。
    • After: 普通输出显示 PROCESSING_ERROR: Parse error: boom,verbose 保留 HTTP status、code 和 details。
  • 请求超时
    • Before: 容易被归为连接错误,提示用户检查服务器 URL 或网络。
    • After: 显示 Request Timeout,提示 OpenViking 未在当前超时时间内响应。
  • /health 返回 {"healthy": false}
    • Before: ov config wizard 可能落到泛化提示,让用户检查 API key / URL。
    • After: 明确提示服务器可连接但健康状态异常。
  • /health 返回 200 但响应体不是合法 JSON
    • Before: ov config validate 可能显示 Auth accepted、Health healthy。
    • After: 显示 Server reachable,但 Auth / Health 均为 not checked,并说明 CLI 无法理解响应内容。
  • 发送请求阶段失败或未知验证失败
    • Before: 兜底分类可能误显示 accepted / healthy。
    • After: 兜底状态统一显示 not checked,避免把未知失败渲染成通过。

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

cargo test -p ov_cli -- --test-threads=1

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Screenshots (if applicable)

ov config validate against a server whose /health returns HTTP 200 with an invalid JSON body:

Before After
TODO: upload config-validate-before.dark.png here TODO: upload config-validate-after.dark.png here

Before incorrectly renders the unknown validation failure as 认证 已通过 and 健康状态 健康. After renders the same case as 认证 未检查 and 健康状态 未检查.

Light theme captures are also available if preferred:

  • config-validate-before.light.png
  • config-validate-after.light.png

Additional Notes

不适用。

@qin-ctx qin-ctx force-pushed the fix/cli-structured-api-errors branch 4 times, most recently from 485a8f3 to 5eaa608 Compare June 24, 2026 07:33
@qin-ctx qin-ctx force-pushed the fix/cli-structured-api-errors branch from 5eaa608 to bc412d6 Compare June 24, 2026 07:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

2 participants