feat(cli): 终端诊断用户体验优化 — 补全文档、友好错误提示、更新加载动画#627
Conversation
…g.md, www/.vitepress/config.mts) - Created bilingual VitePress guide pages covering neocode shell, neocode diag, neocode diag -i, neocode diag auto, and common issues - Registered in both Chinese and English sidebars under "日常使用" / "Daily Use"
- Pre-check: Added checks in defaultDiagCommandRunner, defaultDiagInteractiveCommandRunner, and defaultDiagAutoCommandRunner — when resolveDiagTargetSessionID() returns empty, returns a clear message: "no neocode shell session found; run neocode shell first..." - Post-check: Added wrapDiagGatewayError() in triggerDiagAction() — intercepts the "target role stream is unavailable" gateway error and wraps it with the friendly message - 7 new tests added (shell_diag_commands_test.go)
- Added startUpdateSpinner() — a goroutine-based rotating character animation (- \ | /) writing to stderr - Integrated via defer stop() in defaultUpdateCommandRunner(), wrapping the doUpdate() call
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
| return | ||
| case <-ticker.C: | ||
| frame := updateSpinnerFrames[i%len(updateSpinnerFrames)] | ||
| fmt.Fprintf(os.Stderr, "\r%s Updating...", frame) |
There was a problem hiding this comment.
startUpdateSpinner writes directly to os.Stderr, so the new progress output bypasses Cobra's configured stderr stream and always emits terminal control characters even when stderr is redirected. In practice that means tests/embedded callers cannot capture it via cmd.SetErr(...), and neocode update 2>file will record raw \r- Updating... frames instead of a clean log. Please route this through the command's stderr writer and gate the spinner on a real TTY before enabling it.
|
|
||
| 启动后，你会进入一个由 NeoCode 代理的终端环境。该会话会向 NeoCode Gateway 注册为 shell 角色，从而使后续的诊断命令能够找到目标会话。 | ||
|
|
||
| > **注意**：所有诊断命令（`neocode diag` 及其子命令）都依赖当前已有一个活跃的 `neocode shell` 会话。请先在一个终端窗口启动 `neocode shell`，然后在另一个终端窗口执行诊断命令。 |
There was a problem hiding this comment.
The new guide says users can start neocode shell in one terminal and then run neocode diag in another, but the implementation here still resolves the target only from --session or NEOCODE_SHELL_SESSION (resolveDiagTargetSessionID). A separate terminal will not inherit the proxy shell's env var automatically, so the documented flow fails with no neocode shell session found unless the user passes --session <session-id> (or runs inside the proxied shell). The wording here and the later examples/FAQ should be updated to match the real behavior.
|
|
||
| Once started, you enter a NeoCode-proxied terminal environment. The session registers itself with the NeoCode Gateway as a shell role, allowing subsequent diagnosis commands to locate the target session. | ||
|
|
||
| > **Note**: All diagnosis commands (`neocode diag` and its subcommands) depend on an active `neocode shell` session. Start `neocode shell` in one terminal window first, then run diagnosis commands in another. |
There was a problem hiding this comment.
This guide currently says users can run neocode diag from another terminal after starting neocode shell, but the implementation still resolves the target only from --session or NEOCODE_SHELL_SESSION (resolveDiagTargetSessionID). A different terminal session will not see that env var by default, so the documented flow fails unless the user passes --session <session-id> (or runs inside the proxied shell). Please align this note and the later examples/FAQ with the actual CLI behavior.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
2 participants
概述
针对终端诊断功能的三个体验短板进行统一优化：
neocode update添加加载动画 — 更新过程无任何反馈，用户无法判断是否卡死变更详情
1. 补全双语文档（
www/）www/guide/shell-diag.md（中文）和www/en/guide/shell-diag.md（英文）neocode shell、neocode diag、neocode diag -i、neocode diag auto的全部用法www/.vitepress/config.mts中英文侧边栏同步注册2. 友好错误提示（
internal/cli/shell_diag_commands.go）resolveDiagTargetSessionID()返回空时直接返回友好提示，不再发起 RPC 调用triggerDiagAction()中对网关返回的"target role stream is unavailable"错误进行包装，附加 "请先执行neocode shell" 的引导信息3. 更新加载动画（
internal/cli/update_command.go）startUpdateSpinner()，以 goroutine 方式在 stderr 输出旋转动画（- \ | /），100ms 每帧defaultUpdateCommandRunner()中以defer stop()包裹doUpdate()调用涉及文件
www/guide/shell-diag.mdwww/en/guide/shell-diag.mdwww/.vitepress/config.mtsinternal/cli/shell_diag_commands.gointernal/cli/shell_diag_commands_test.gointernal/cli/update_command.go验证
go test ./internal/cli/...全部通过go test ./internal/updater/...全部通过go build ./internal/cli/编译通过cd www && pnpm dev）确认页面可访问neocode diag应看到友好提示neocode update应看到旋转加载动画Closes #613