Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

feat(cli): add a compact command map for agent discovery (#41226)

samzong1299d99b2d70
diff --git a/cli/README.md b/cli/README.md
index bde55e4bfe9..b9de444b980 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -48,11 +48,13 @@ Background docs: `difyctl help account`, `difyctl help external`, `difyctl help
Run `difyctl --help` for the full list of commands.
Run `difyctl <cmd> --help` for per-command reference.
-For agents (and scripting), start with `difyctl help agent` — the cross-command operating guide (output, discovery, auth, exit codes, errors, HITL, retry). Every help surface is also machine-readable: `difyctl help -o json` dumps the whole command tree plus the global contract (exit codes, output formats, error envelope, HITL protocol), and `difyctl <cmd> --help -o json` returns one command's descriptor.
+Use `difyctl help -o json --compact` to read the complete command map, then inspect the selected command with `difyctl help <path> -o json` before running it — that per-command descriptor is the only surface that carries args and flags.
+
+For agents (and scripting), start with `difyctl help agent` — the cross-command operating guide (output, discovery, auth, exit codes, errors, HITL, retry). Every help surface is also machine-readable: `difyctl help -o json` dumps the whole command tree plus the global contract (exit codes, output formats, error envelope, HITL protocol), and `difyctl help <path> -o json` returns one command's descriptor.
## Agent skill
-`difyctl skills install` installs a single, pure-delegation `SKILL.md` into your local agents so they auto-load it. The skill does not freeze the command set — it points the agent at `difyctl help -o json` for the live surface, so it never drifts from your binary. It is embedded in the binary (version-stamped) rather than checked in.
+`difyctl skills install` installs a single, pure-delegation `SKILL.md` into your local agents so they auto-load it. The skill does not freeze the command set — it directs the agent through the live compact sitemap and per-command help, so it never drifts from your binary. It is embedded in the binary (version-stamped) rather than checked in.
- `difyctl skills install` — dry-run: detect installed agents (Claude Code, Codex, opencode, Cursor, pi) and print where the skill would land. Writes nothing.
- `difyctl skills install --yes` — write to every detected agent, printing each path. `--agent claude-code[,cursor]` restricts to a subset; `<dir>` forces one explicit directory (handy when your agent isn't detected).
diff --git a/cli/src/framework/help.test.ts b/cli/src/framework/help.test.ts
index a85510173d5..3fef2a830f1 100644
--- a/cli/src/framework/help.test.ts
+++ b/cli/src/framework/help.test.ts
@@ -205,4 +205,31 @@ describe('formatTopLevelHelp', () => {
expect(obj.commands.every((c: { effect?: string }) => typeof c.effect === 'string')).toBe(true)
expect(obj.topics.map((t: { name: string }) => t.name)).toContain('account')
})
+
+ it('emits only command, description, and effect when compact', () => {
+ const tree: CommandTree = {
+ get: {
+ subcommands: {
+ app: {
+ command: makeCmd({
+ description: 'apps',
+ effect: 'read',
+ flags: { output: Flags.string({ description: 'format' }) },
+ }),
+ subcommands: {},
+ },
+ },
+ },
+ }
+ const obj = JSON.parse(formatTopLevelHelp(tree, 'json', { compact: true })) as {
+ commands: Array<Record<string, unknown>>
+ bin?: unknown
+ contract?: unknown
+ }
+ expect(obj).toEqual({
+ commands: [{ command: 'get app', description: 'apps', effect: 'read' }],
+ })
+ expect(obj.bin).toBeUndefined()
+ expect(obj.contract).toBeUndefined()
+ })
})
diff --git a/cli/src/framework/help.ts b/cli/src/framework/help.ts
index 2098f8c828c..e8fea63c522 100644
--- a/cli/src/framework/help.ts
+++ b/cli/src/framework/help.ts
@@ -35,7 +35,7 @@ export type CommandDescriptor = {
agentGuide: string | null
}
-function isStructured(format: string): boolean {
+export function isStructured(format: string): boolean {
return format === 'json' || format === 'yaml'
}
@@ -71,13 +71,22 @@ function agentGuideOf(ctor: CommandConstructor): string {
return new C().agentGuide()
}
-export function describeCommand(ctor: CommandConstructor, path: string): CommandDescriptor {
- const guide = agentGuideOf(ctor)
-
+function summarizeCommand(
+ ctor: CommandConstructor,
+ path: string,
+): Pick<CommandDescriptor, 'command' | 'description' | 'effect'> {
return {
command: path,
description: ctor.description ?? null,
effect: ctor.effect ?? 'read',
+ }
+}
+
+export function describeCommand(ctor: CommandConstructor, path: string): CommandDescriptor {
+ const guide = agentGuideOf(ctor)
+
+ return {
+ ...summarizeCommand(ctor, path),
args: Object.entries(ctor.args ?? {}).map(([name, def]) => ({
name,
required: def.required ?? false,
@@ -230,13 +239,28 @@ function formatTopLevelHelpText(tree: CommandTree): string {
`GUIDES\n${renderTopicRows()}`,
`LEARN MORE\n` +
` Use \`${BIN} <command> --help\` for details on a command.\n` +
- ` New here? Run \`${BIN} help account\`. Agents: \`${BIN} help agent\` or \`${BIN} --help -o json\`.`,
+ ` New here? Run \`${BIN} help account\`. Agents: \`${BIN} help agent\` or \`${BIN} help -o json --compact\`.`,
]
return `${sections.join('\n\n')}\n`
}
-export function formatTopLevelHelp(tree: CommandTree, format: string): string {
+export function formatTopLevelHelp(
+ tree: CommandTree,
+ format: string,
+ options: { compact?: boolean } = {},
+): string {
+ if (options.compact && isStructured(format)) {
+ return serialize(
+ {
+ commands: collectCommands(tree).map(({ command, path }) =>
+ summarizeCommand(command, path.join(' ')),
+ ),
+ },
+ format,
+ )
+ }
+
if (isStructured(format)) {
return serialize(
{
diff --git a/cli/src/framework/run.test.ts b/cli/src/framework/run.test.ts
index 31f0a013117..9ce0df7f45e 100644
--- a/cli/src/framework/run.test.ts
+++ b/cli/src/framework/run.test.ts
@@ -486,6 +486,39 @@ describe('run() help routing', () => {
expect(result.exit).toBeUndefined()
})
+ it('routes `--compact` to the site map instead of the full tree', async () => {
+ const result = await captureRun(tree, ['help', '-o', 'json', '--compact'])
+ const obj = JSON.parse(result.stdout) as { bin?: unknown; contract?: unknown }
+ expect(result.exit).toBeUndefined()
+ expect(obj.bin).toBeUndefined()
+ expect(obj.contract).toBeUndefined()
+ })
+
+ it('accepts every boolean spelling of `--compact`', async () => {
+ const canonical = await captureRun(tree, ['help', '-o', 'json', '--compact'])
+ for (const flag of ['--compact=true', '--compact=1']) {
+ const result = await captureRun(tree, ['help', '-o', 'json', flag])
+ expect(result.stdout, flag).toBe(canonical.stdout)
+ }
+ })
+
+ it('rejects `--compact` without a structured format', async () => {
+ const result = await captureRun(tree, ['help', '--compact'])
+ expect(result.exit).toBe(ExitCode.Usage)
+ expect(result.stderr).toContain('--compact requires -o json or -o yaml')
+ })
+
+ it('rejects `--compact` on per-command help', async () => {
+ const result = await captureRun(tree, ['help', 'get', 'app', '-o', 'json', '--compact'])
+ expect(result.exit).toBe(ExitCode.Usage)
+ expect(JSON.parse(result.stderr)).toEqual({
+ error: {
+ code: 'usage_invalid_flag',
+ message: '--compact is only valid on top-level help',
+ },
+ })
+ })
+
it('emits a JSON descriptor for `help <cmd> -o json`', async () => {
const result = await captureRun(tree, ['help', 'get', 'app', '-o', 'json'])
const obj = JSON.parse(result.stdout)
diff --git a/cli/src/framework/run.ts b/cli/src/framework/run.ts
index 1d1affe08a9..5c567940c12 100644
--- a/cli/src/framework/run.ts
+++ b/cli/src/framework/run.ts
@@ -1,14 +1,29 @@
import type { CommandTree } from './registry'
-import { BaseError, unknownError } from '@/errors/base'
+import { BaseError, newError, unknownError } from '@/errors/base'
+import { ErrorCode } from '@/errors/codes'
import { formatErrorForCli } from '@/errors/format'
import { findTopic } from '@/help/topics'
-import { formatCommandList, formatHelp, formatTopic, formatTopLevelHelp } from './help'
+import { hasBooleanFlag } from './flags'
+import {
+ formatCommandList,
+ formatHelp,
+ formatTopic,
+ formatTopLevelHelp,
+ isStructured,
+} from './help'
import { stringifyOutput } from './output'
import { collectCommands, findSuggestions, resolveCommand } from './registry'
+function exitWithUsageError(message: string, format: string): void {
+ const error = newError(ErrorCode.UsageInvalidFlag, message)
+ process.stderr.write(`${formatErrorForCli(error, { format, isErrTTY: process.stderr.isTTY })}\n`)
+ process.exit(error.exit())
+}
+
export async function run(tree: CommandTree, argv: string[]): Promise<void> {
if (argv.length === 0 || argv[0] === 'help' || argv.includes('--help') || argv.includes('-h')) {
const format = sniffOutputFormat(argv)
+ const compact = hasBooleanFlag(argv, 'compact')
// The command/topic path is the leading positional run; stop at the first
// flag so output flags like `-o json` never leak into resolution.
const helpArgv: string[] = []
@@ -19,12 +34,22 @@ export async function run(tree: CommandTree, argv: string[]): Promise<void> {
helpArgv.push(a)
}
+ if (compact && helpArgv.length > 0) {
+ exitWithUsageError('--compact is only valid on top-level help', format)
+ return
+ }
+
+ if (compact && !isStructured(format)) {
+ exitWithUsageError('--compact requires -o json or -o yaml', format)
+ return
+ }
+
if (helpArgv.length > 0) {
const resolved = resolveCommand(tree, helpArgv)
if (resolved) {
const out = formatHelp(resolved.command, resolved.path.join(' '), format)
- process.stdout.write(isStructuredFormat(format) ? out : `${out}\n`)
+ process.stdout.write(isStructured(format) ? out : `${out}\n`)
return
}
@@ -67,7 +92,7 @@ export async function run(tree: CommandTree, argv: string[]): Promise<void> {
process.exit(1)
}
- process.stdout.write(formatTopLevelHelp(tree, format))
+ process.stdout.write(formatTopLevelHelp(tree, format, { compact }))
return
}
@@ -125,7 +150,3 @@ export function sniffOutputFormat(argv: readonly string[]): string {
}
return ''
}
-
-function isStructuredFormat(format: string): boolean {
- return format === 'json' || format === 'yaml'
-}
diff --git a/cli/src/help/contract.ts b/cli/src/help/contract.ts
index 646f6386483..407beed6638 100644
--- a/cli/src/help/contract.ts
+++ b/cli/src/help/contract.ts
@@ -49,14 +49,19 @@ export const CONTRACT: Contract = {
},
}
-// Single source for the top-level GLOBAL FLAGS section: flags that work across
-// commands. `-o` is parsed globally (see sniffOutputFormat); its accepted values
-// come straight from CONTRACT.outputFormats so the two can never drift.
+// Single source for the top-level GLOBAL FLAGS section: flags the framework
+// parses before any command sees argv. `-o` is parsed globally (see
+// sniffOutputFormat); its accepted values come straight from
+// CONTRACT.outputFormats so the two can never drift.
export const GLOBAL_FLAG_HELP: ReadonlyArray<{ label: string; description: string }> = [
{
label: '-o, --output <format>',
description: `Output format: ${CONTRACT.outputFormats.join('|')}`,
},
+ {
+ label: '--compact',
+ description: 'Command map with only command/description/effect (top-level help, json|yaml)',
+ },
{ label: '-v, --verbose', description: 'Enable verbose logging' },
{
label: '--http-retry <n>',
diff --git a/cli/src/help/skill-template.ts b/cli/src/help/skill-template.ts
index 581d6392e13..6315b10c9fc 100644
--- a/cli/src/help/skill-template.ts
+++ b/cli/src/help/skill-template.ts
@@ -1,15 +1,3 @@
-// The difyctl agent skill, in full — one hand-authored, pure-delegation file.
-//
-// It inlines NO command list, NO flag list, and ships no reference files. The
-// command surface is discovered at runtime via `difyctl help -o json`, so this
-// template has nothing to derive from the binary and nothing that can drift
-// from it. `{{VERSION}}` is the only substitution; it is filled at emit time by
-// renderSkill() in ./skill.
-//
-// RED LINE: keep this pure delegation. The moment a command or flag listing is
-// added here, the embedded static copy can fall out of sync with the command
-// surface — at which point it must instead be generated from the command model
-// with a snapshot test (see SKILL-SPEC.md §10, decision D2).
export const SKILL_TEMPLATE = `---
name: difyctl
description: Drive the difyctl CLI to manage Dify apps, workspaces, members and runs. Use when the task involves difyctl or operating a Dify instance from the command line.
@@ -20,10 +8,25 @@ description: Drive the difyctl CLI to manage Dify apps, workspaces, members and
difyctl is self-describing — do not guess commands.
## Discover the command surface
-Run \`difyctl help -o json\` for the version-current map: every command
-(args, flags, examples, \`effect\`) plus the global \`contract\` (exit codes,
-output formats, error envelope, HITL protocol). Treat that JSON as the
-source of truth; this file only bootstraps you into it.
+1. Read the complete compact sitemap:
+ \`difyctl help -o json --compact\`
+ Each entry contains only \`command\`, \`description\`, and \`effect\`.
+2. Decide whether the request maps to one command, needs clarification, or is
+ unsupported.
+3. When one command is selected, inspect it:
+ \`difyctl help <path> -o json\`
+ Expand a multi-token path as separate shell arguments; never quote the
+ entire returned path.
+ That JSON is the source of truth for args, flags, examples, \`effect\`,
+ and \`agentGuide\`. Never skip it — the sitemap carries no args or flags,
+ so any flag you name without this step is a guess.
+
+When the task depends on global exit codes, error envelopes, HITL, or retry
+semantics, read \`difyctl help agent\`.
+
+Do not read the full command tree. Report unsupported only after checking the
+compact sitemap. Clarify only when more than one command could satisfy the
+request.
## The one non-obvious thing: HITL pauses are not failures
A run can pause for human input. It exits with **code 0** and emits a
@@ -31,8 +34,8 @@ A run can pause for human input. It exits with **code 0** and emits a
Resume as the payload instructs (see \`difyctl resume app --help\`).
## Before any write/destructive action
-Check the command's \`effect\` (\`read\` / \`write\` / \`destructive\`) in
-\`difyctl help -o json\` before running it.
+Treat the inspected command's \`effect\` as the confirmation gate before
+running it. Never execute a write/destructive command without confirmation.
---
difyctl skill v{{VERSION}} — if \`difyctl version\` differs, re-run
diff --git a/cli/src/help/skill.test.ts b/cli/src/help/skill.test.ts
index 8cae781427c..a6edf40cf71 100644
--- a/cli/src/help/skill.test.ts
+++ b/cli/src/help/skill.test.ts
@@ -5,8 +5,6 @@ import { versionInfo } from '@/version/info'
import { renderSkill } from './skill'
import { SKILL_TEMPLATE } from './skill-template'
-// Self-references the skill is allowed to name — operational pointers, not a
-// command listing. Everything else must be discovered via `help -o json`.
const SELF_REFERENCES = new Set(['resume app', 'skills install', 'version'])
describe('renderSkill', () => {
@@ -25,8 +23,14 @@ describe('renderSkill', () => {
expect(renderSkill({ version: versionInfo.version })).not.toContain('{{')
})
- it('points at the machine-readable surface instead of inlining it', () => {
- expect(renderSkill({ version: versionInfo.version })).toContain('difyctl help -o json')
+ it('uses the compact sitemap before per-command help', () => {
+ const skill = renderSkill({ version: versionInfo.version })
+ expect(skill).toContain('difyctl help -o json --compact')
+ expect(skill).toContain('difyctl help <path> -o json')
+ expect(skill).toContain('difyctl help agent')
+ expect(skill.indexOf('difyctl help -o json --compact')).toBeLessThan(
+ skill.indexOf('difyctl help <path> -o json'),
+ )
})
it('enumerates no command from the tree (zero drift surface)', () => {
@@ -54,6 +58,8 @@ describe('renderSkill', () => {
it('inlines no command-specific flags (only the --help pointer)', () => {
const skill = renderSkill({ version: versionInfo.version })
const longFlags = skill.match(/--[a-z][\w-]+/g) ?? []
- for (const flag of longFlags) expect(flag, `unexpected flag in skill: ${flag}`).toBe('--help')
+ const allowed = new Set(['--help', '--compact'])
+ for (const flag of longFlags)
+ expect(allowed.has(flag), `unexpected flag in skill: ${flag}`).toBe(true)
})
})
diff --git a/cli/src/help/skill.ts b/cli/src/help/skill.ts
index be35d392dec..5f31c1d72f1 100644
--- a/cli/src/help/skill.ts
+++ b/cli/src/help/skill.ts
@@ -4,11 +4,6 @@ export type RenderSkillOptions = {
readonly version: string
}
-// Renders the difyctl SKILL.md by substituting only the version stamp into the
-// hand-authored, pure-delegation template. There is no command-tree walk: the
-// skill points agents at `difyctl help -o json` for the live command surface
-// rather than enumerating it, so there is nothing to derive and nothing to
-// drift. The single file is what `skills install` writes / prints.
export function renderSkill(opts: RenderSkillOptions): string {
return SKILL_TEMPLATE.replaceAll('{{VERSION}}', opts.version)
}
diff --git a/cli/src/help/topics.test.ts b/cli/src/help/topics.test.ts
index 14ad27f742a..a3dc4af54fc 100644
--- a/cli/src/help/topics.test.ts
+++ b/cli/src/help/topics.test.ts
@@ -40,10 +40,12 @@ describe('account topic', () => {
describe('agent topic', () => {
it('covers output, exit codes, auth, errors and HITL', () => {
const out = render('agent')
- expect(out).toContain('-o json')
expect(out).toContain('EXIT CODES')
expect(out).toContain('DIFY_TOKEN')
- expect(out).toContain('difyctl help -o json')
+ expect(out).toContain('difyctl help <path> -o json')
+ expect(out).toContain('difyctl help -o json --compact')
+ expect(out).toMatch(/difyctl help -o json\s+full command tree/)
+ expect(out).toContain('difyctl get app -o json')
expect(out).toContain('HUMAN-IN-THE-LOOP')
})
})
diff --git a/cli/src/help/topics.ts b/cli/src/help/topics.ts
index 3944e309be4..59e75d34e0e 100644
--- a/cli/src/help/topics.ts
+++ b/cli/src/help/topics.ts
@@ -87,9 +87,11 @@ APP vs STUDIO-APP
noun supports.
DISCOVERY
- difyctl help -o json full command tree + this contract, machine-readable
- difyctl get app -o json list apps (ids + modes)
- difyctl describe app <id> one app's mode and input schema
+ difyctl help -o json --compact complete command map for discovery
+ difyctl help <path> -o json inspect the selected command; the only source of flags
+ difyctl help -o json full command tree + contract for troubleshooting
+ difyctl get app -o json list apps (ids + modes)
+ difyctl describe app <id> one app's mode and input schema
AUTH
Interactive: difyctl auth login (browser device flow)
diff --git a/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts b/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts
index b9e972336c7..8e6b9a82c8f 100644
--- a/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts
+++ b/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts
@@ -3,7 +3,7 @@
*
* Scenario: an AI agent has loaded difyctl SKILL.md and drives difyctl to:
* 1. Bootstrap - read SKILL.md via `skills install --stdout`
- * 2. Discover - `help -o json` for full command surface + contract
+ * 2. Discover - compact sitemap, then per-command help
* 3. Auth check - no token → exit 4 + JSON error envelope
* 4. Discover apps - `get app -o json`
* 5. Describe app - `describe app <id> -o json`
@@ -14,7 +14,7 @@
* 10. Pipeline safety - no ANSI/spinner, stdout/stderr separation
*
* PRD: §3 Agent-Driven, §5 Agent onboarding, Req 1.3/2.1/2.3/3.1-3.3
- * Agent Skills PRD: §4/§5.2 SKILL.md → help -o json discovery pattern
+ * Agent Skills PRD: §4/§5.2 SKILL.md → live command discovery
*
* Groups 1-3, 9: no auth required (local mode compatible)
* Groups 4-8, 10: require DIFY_E2E_TOKEN / staging — wrapped with optionalIt
@@ -45,14 +45,18 @@ const itWithWorkflow = optionalIt(Boolean(E.token) && Boolean(E.workflowAppId))
const itWithHitl = optionalIt(Boolean(E.token) && Boolean(E.hitlAppId))
// ---------------------------------------------------------------------------
-// 1 + 2. Skill bootstrap → help -o json discovery
+// 1 + 2. Skill bootstrap → compact sitemap → per-command help
// ---------------------------------------------------------------------------
describe('E2E / agent skill — bootstrap + discovery (no auth)', () => {
- it('[P0] SKILL.md contains `difyctl help -o json` as the discovery entry point', async () => {
+ it('[P0] SKILL.md directs agents through compact sitemap and per-command help', async () => {
const r = await run(['skills', 'install', '--stdout'])
expect(r.exitCode).toBe(0)
- expect(r.stdout).toContain('difyctl help -o json')
+ expect(r.stdout).toContain('difyctl help -o json --compact')
+ expect(r.stdout).toContain('difyctl help <path> -o json')
+ expect(r.stdout.indexOf('difyctl help -o json --compact')).toBeLessThan(
+ r.stdout.indexOf('difyctl help <path> -o json'),
+ )
})
it('[P0] SKILL.md enumerates no commands from the tree (zero drift surface)', async () => {
@@ -102,6 +106,25 @@ describe('E2E / agent skill — bootstrap + discovery (no auth)', () => {
)
})
+ it('[P0] `help -o json --compact` emits only command, description, and effect', async () => {
+ const r = await run(['help', '-o', 'json', '--compact'])
+ expect(r.exitCode).toBe(0)
+ assertPipeFriendlyJson(r)
+ const map = JSON.parse(r.stdout) as {
+ commands: Array<Record<string, unknown>>
+ bin?: unknown
+ contract?: unknown
+ }
+ expect(map.bin).toBeUndefined()
+ expect(map.contract).toBeUndefined()
+ expect(map.commands.length).toBeGreaterThan(0)
+ for (const command of map.commands) {
+ expect(Object.keys(command)).toEqual(['command', 'description', 'effect'])
+ expect(typeof command.command).toBe('string')
+ expect(typeof command.effect).toBe('string')
+ }
+ })
+
it('[P0] every command in help -o json has args, flags, examples arrays', async () => {
const { commands } = JSON.parse((await run(['help', '-o', 'json'])).stdout) as {
commands: Array<{ command: string; args: unknown; flags: unknown; examples: unknown }>