oldwinter / oldwinter/all-cli

体验:doctor 与 diagnose 在帮助里无法区分

Open Beginner friendly
#54 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
1
Forks
0
Avg merge
7d 23h
Merged PRs (30d)
24

Description

体验:doctor 与 diagnose 在帮助里无法区分

用户路径
  1. all-cli --helpdoctordiagnose 都在 Primary commands 里(internal/cli/root.gosetSubcommandGroups)。
  2. 看 Short:一个像健康检查,一个像诊断,但都没说 audience / 默认 profile。
  3. 再跑 all-cli doctor --helpall-cli diagnose --help
  4. 顺带打开 all-cli current --help,Long 第二段被字面 tab 缩进打断。
摩擦点
  • internal/cli/agent_commands.gonewDiagnoseCommandnewDoctorCommand 都调用 buildDiagnosticReport。diagnose 默认 profile=agent + printDiagnosticReport;doctor 默认 profile=human + printDoctorReport
  • doctor 原先没有 Long,Short 是 “Run read-only health checks for local CLI tools”;diagnose Short 是 “Generate agent-readable diagnostics from CLI status”。根帮助看不出何时用哪个。
  • internal/cli/current.go 的 Long 在 “skip unrelated” 后有一个 stray tab,帮助文本折行后看起来像坏掉的缩进。

已关闭 issue(#42/#34 空 error、#41 go-install PATH)是另一类问题,不重复。

建议改动
  • Short/Long 写明 profile 和输出对象:doctor = human health table(默认 human);diagnose = agent diagnostics(默认 agent)。
  • 互相 See also。
  • 去掉 current Long 里的 tab。
  • 加帮助文本测试,保证两条 Short 保持不同,且 current Long 不含 tab。

不改 diagnostic schema、telemetry,也不加新工具。

本地 clone 已按此改了一版(未 push / 未开 PR)。

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with internal/cli/agent_commands.go and internal/cli/root.go to compare the doctor and diagnose help definitions and their command grouping, then inspect internal/cli/current.go for the formatting issue. Add help-text coverage for distinct Shorts, profile/output descriptions, cross-references, and the absence of tabs in current's Long; verify the resulting CLI help output.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, documentation, testing
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.