Files
deepseek-harness/.agents/notes/implemented/process/2026-09-14-generated-cli-help-reference.md
T
Tianyi Cui 75935af1d0 feat(cli): generate the CLI help reference and add dsh plugin help
`scripts/gen-cli-help.ts` runs the source `dsh` launcher with temporary
Harness and Agents homes and captures the launcher, `dsh plugin`, and every
shipped profile's text help (profile names come from `PROFILE_TEMPLATES`).
It recursively discovers subcommands from each page's `Commands:` section,
shows identical alias help once with every invocation, and writes
`docs/cli-help.md`, its Chinese page, and their pairing record. The record
resolves links between the two pages as written, so a first run already
matches `verify-translation-pairing`. `verify-cli-help` checks all three
files and runs as the `cli-help` doc-sync leaf, which the static CI lane
also runs on an unbuilt tree.

`dsh plugin` now owns `-h`/`--help` and reads its own options only before
the forwarded pnpm arguments: `dsh plugin --help` prints its help instead of
failing on the missing `--profile`, while everything after the pnpm command
(including `-h`, `--help`, and `--profile`) reaches pnpm verbatim. A
`--profile` placed after the pnpm command is no longer accepted; the
v0.2.1-alpha.1 upgrade guide covers the migration.

Refs #4114
2026-10-05 17:45:17 +08:00

1.5 KiB

Agent Note: Generate the CLI reference from command help

Status: implemented

English | 中文

Problem

Launcher flags, profile options, and nested commands have separate owners. A manually maintained command reference can omit subcommands or retain obsolete defaults.

Decision

The CLI reference captures the supported dsh launcher's help, the plugin forwarder's help, and each shipped profile's help, then recursively discovers the subcommands listed in each page's Commands: section. Shipped profile names come from PROFILE_TEMPLATES. Every page retains its complete help text; identical alias help appears once with all invocation forms.

Generation uses temporary Harness and Agents homes. Help exits before application work starts and requires no server or model. The plugin forwarder exposes its own help before pnpm arguments; flags after the pnpm command remain pnpm input.

The generated bilingual pages retain CLI output in its original language. verify-cli-help compares the complete pages and pairing record and runs with the documentation checks.

Alternatives considered

A second command inventory or help-specific runtime API would duplicate the parser's definitions. Reading actual help keeps the reference tied to the same descriptions, options, defaults, and examples users receive.

Consequences

Command changes update the reference through the same generator. Reviewers can compare complete help without assembling separate command invocations.