feat(compat): surface dynamic-command flag aliases in --help#418
Open
jackjin1997 wants to merge 1 commit into
Open
feat(compat): surface dynamic-command flag aliases in --help#418jackjin1997 wants to merge 1 commit into
jackjin1997 wants to merge 1 commit into
Conversation
Envelope overlays can declare flag aliases (alias + aliases), which the dynamic command builder registers as hidden cobra flags. They work at runtime but never appear in --help, so users and agents inspecting `--help` cannot self-discover them and must read the source JSON. After schema enrichment, annotate each visible primary flag whose envelope override declares aliases with a " [别名: --x, --y]" suffix. Aliases stay hidden; the hint is deduped against the primary and reserved names (json, params) and is idempotent. Running post-enrichment avoids clobbering the detail-schema usage-fill (which keys off usage == paramName). Closes DingTalk-Real-AI#371
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What changed? Dynamic commands built from envelope overlays now show their declared flag aliases in
--help. After schema enrichment, each visible primary flag whose override declaresaliasesgets a[别名: --x, --y]suffix on its usage text.Before:
After:
Why? Envelope
alias+aliasesare registered as hidden cobra flags (perCLIFlagOverride.Aliasesdocs). They work at runtime but never appear in--help, so users — and especially AI agents probing capability via--help— cannot self-discover them and must read the source JSON. This was the secondary ask split out of [suggest] dws sheet find: 加 --query 兼容别名 (wukong 主名 / 跨版本一致性) #280.Closes #371
Verification
make buildmake lint—go vetpasses;staticchecknot installed in my local env (CI covers it)go test ./internal/compat/(incl. newTestAliasUsageHint,TestBuildDynamicCommands_AliasesShownInHelp; existing..._MultipleAliases_Dedupstill green)make policy./scripts/policy/check-generated-drift.sh./scripts/policy/check-command-surface.sh --strictNotes
buildFlagsFromDetailSchema, not insideApplyBindings. The detail-schema enrichment fills a flag's usage only whenusage == paramName; baking the alias hint earlier would change that string and could suppress the description fill. Running last keeps the final usage text intact and just appends the hint.json,params) and is idempotent (guarded by the[别名:marker). Alias flags themselves stay hidden — only the hint surfaces them.别名is hardcoded Chinese to match the issue spec and the surrounding overlay copy (which is itself Chinese); happy to wrap it ini18n.Tif you prefer.