shortcut

package
v1.0.54 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package shortcut provides a declarative framework for high-fidelity CLI commands (shortcuts) on top of the DingTalk MCP runtime.

A Shortcut is a curated, thin wrapper over a raw MCP tool call: it declares its flags, validation and execution logic once, and the framework compiles it into a cobra command wired to the shared executor.Runner, output formatting, dry-run and identity handling. This provides a `+command` shortcut layer, but executes through DWS's MCP dispatch instead of a native SDK.

Shortcuts are surfaced as `dws <service> +<command>` (e.g. `dws contact +search-user`). The `+` prefix keeps them visually distinct from the dynamically-discovered MCP leaf commands and from hand-written helper commands.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuiltInCommands 

func BuiltInCommands() []*cobra.Command

BuiltInCommands compiles only distribution-owned shortcuts.

func Commands 

func Commands() []*cobra.Command

Commands compiles all registered shortcuts into a slice of top-level cobra commands, one per service, each carrying its `+command` leaves. The result is merged into the root command tree by the host application.

func InPublicCatalog 

func InPublicCatalog(service, command string) bool

InPublicCatalog reports whether a shortcut belongs to the generated public shortcut surface used by help, listing, and skill generation.

func Register 

func Register(shortcuts ...Shortcut)

Register adds one or more shortcuts to the built-in registry. Call from a service package's init().

Types

type Constraint 

type Constraint struct {
	Kind        ConstraintKind `json:"kind"`
	Flags       []string       `json:"flags"`
	Description string         `json:"description,omitempty"`
}

Constraint declares a shortcut parameter relationship. Known kinds are enforced by the runner; custom constraints are enforced by Validate and must include a concrete Description.

type ConstraintKind 

type ConstraintKind string

ConstraintKind is a machine-readable cross-parameter or custom validation rule published by `dws shortcut list` and rendered in leaf help. 

const (
	// ConstraintAtLeastOne requires one or more of Flags.
	ConstraintAtLeastOne ConstraintKind = "at_least_one"
	// ConstraintExactlyOne requires exactly one of Flags.
	ConstraintExactlyOne ConstraintKind = "exactly_one"
	// ConstraintMutuallyExclusive permits zero or one of Flags.
	ConstraintMutuallyExclusive ConstraintKind = "mutually_exclusive"
	// ConstraintCustom documents validation enforced by Shortcut.Validate.
	ConstraintCustom ConstraintKind = "custom"
)

type Flag 

type Flag struct {
	// Name is the long flag name (kebab-case), e.g. "user-ids".
	Name string `json:"name"`
	// Type is the value type; defaults to FlagString when empty.
	Type FlagType `json:"type"`
	// Default is the default value rendered as a string.
	Default string `json:"default"`
	// Desc is the help text shown in --help.
	Desc string `json:"description"`
	// Required, when true, makes the framework error if the flag is not set.
	Required bool `json:"required"`
	// Enum, when non-empty, restricts the accepted values (string flags only).
	Enum []string `json:"enum"`
	// Hidden hides the flag from --help while keeping it usable.
	Hidden bool `json:"-"`
}

Flag is a declarative CLI flag definition. The runner registers each Flag onto the generated cobra command, applying defaults, and validates Enum/Required before the Execute hook runs.

func AIMessageTagFlag 

func AIMessageTagFlag() Flag

AIMessageTagFlag matches `chat message send --ai-tag`: IM send shortcuts default to tagging delivered messages as AI-sent, while still allowing users to opt out with --ai-tag=false.

type FlagType 

type FlagType string

FlagType is the pflag value type a Flag registers as. 

const (
	FlagString      FlagType = "string"
	FlagBool        FlagType = "bool"
	FlagInt         FlagType = "int"
	FlagStringSlice FlagType = "string_slice"
)

type Risk 

type Risk string

Risk classifies the side effect of running a shortcut. It drives whether a confirmation prompt is required before execution (see internal/safety). 

const (
	// RiskRead is a read-only operation; never prompts.
	RiskRead Risk = "read"
	// RiskWrite mutates state; may prompt unless --yes is set.
	RiskWrite Risk = "write"
	// RiskHighWrite is a destructive/irreversible operation; requires explicit
	// confirmation (or --yes) before execution.
	RiskHighWrite Risk = "high-risk-write"
)

type RuntimeContext 

type RuntimeContext struct {
	// contains filtered or unexported fields
}

RuntimeContext is handed to a Shortcut's Validate and Execute hooks. It wraps the cobra command and exposes typed flag accessors plus a single CallMCP entry point so shortcut authors never touch cobra/executor plumbing directly.

func (*RuntimeContext) AddAIMessageTag 

func (rt *RuntimeContext) AddAIMessageTag(params map[string]any) map[string]any

AddAIMessageTag attaches the clawType parameter expected by IM send APIs when the shortcut exposes --ai-tag and the flag is true. This mirrors the native `chat message send` behavior.

func (*RuntimeContext) AtLeastOne 

func (rt *RuntimeContext) AtLeastOne(flags ...string) error

AtLeastOne returns a validation error if none of the flags is set.

func (*RuntimeContext) Bool 

func (rt *RuntimeContext) Bool(name string) bool

Bool returns the bool value of a flag.

func (*RuntimeContext) CallMCP 

func (rt *RuntimeContext) CallMCP(tool string, params map[string]any) error

CallMCP dispatches a single MCP tool call and prints the result, reusing the shared helper path so the shortcut inherits DWS's error classification (auth/PAT/business), dry-run preview and --format/--jq/--fields output for free. The MCP server id is the shortcut's product (defaults to Service).

Most passthrough shortcuts do all their work in one CallMCP call.

func (*RuntimeContext) CallMCPData 

func (rt *RuntimeContext) CallMCPData(product, tool string, params map[string]any) (map[string]any, error)

CallMCPData dispatches a read-only tool call to an explicit MCP product and returns the PARSED response as data WITHOUT printing. This is the building block for multi-step ("smart") shortcuts: call a tool, read its output, feed it into the next call. Errors carry DWS's auth/PAT/business classification.

The product is explicit (not the shortcut's own) because smart shortcuts routinely cross services — e.g. resolve a name via `contact` then act via `chat`. Reads run even under --dry-run so a preview can still resolve inputs. Write tools that need parsed responses must use CallMCPWriteData instead; as a backstop, obvious write-like tool names are rejected here under --dry-run.

func (*RuntimeContext) CallMCPWriteData 

func (rt *RuntimeContext) CallMCPWriteData(product, tool string, params map[string]any) (map[string]any, error)

CallMCPWriteData dispatches a write tool call and returns its parsed response. Unlike CallMCPData, it refuses to run under --dry-run so smart shortcuts cannot accidentally perform writes while rendering a preview.

func (*RuntimeContext) Changed 

func (rt *RuntimeContext) Changed(name string) bool

Changed reports whether the user explicitly set the flag on the command line.

func (*RuntimeContext) Command 

func (rt *RuntimeContext) Command() *cobra.Command

Command returns the underlying cobra command (escape hatch; prefer the typed accessors below).

func (*RuntimeContext) DryRun 

func (rt *RuntimeContext) DryRun() bool

DryRun reports whether --dry-run is set (inherited from the root command).

func (*RuntimeContext) ExactlyOne 

func (rt *RuntimeContext) ExactlyOne(flags ...string) error

ExactlyOne returns a validation error unless exactly one of the flags is set.

func (*RuntimeContext) Int 

func (rt *RuntimeContext) Int(name string) int

Int returns the int value of a flag.

func (*RuntimeContext) IntFirst 

func (rt *RuntimeContext) IntFirst(primary string, aliases ...string) int

IntFirst returns the int value for a primary flag plus aliases. Explicitly set aliases are considered before the primary's default, matching native helper compatibility flags such as --size for --limit.

func (*RuntimeContext) MutuallyExclusive 

func (rt *RuntimeContext) MutuallyExclusive(flags ...string) error

MutuallyExclusive returns a validation error if more than one of the flags is set. Zero or one set is allowed.

func (*RuntimeContext) Output 

func (rt *RuntimeContext) Output(payload any) error

Output prints a (typically reshaped/projected) payload honouring the root --format/--jq/--fields flags. Multi-step shortcuts use it to emit a clean, composed result instead of the raw MCP response — the output-projection output-formatting capability.

func (*RuntimeContext) RangeInt 

func (rt *RuntimeContext) RangeInt(flag string, min, max int) error

RangeInt validates that an int flag (when set) is within [min, max].

func (*RuntimeContext) RequireAll 

func (rt *RuntimeContext) RequireAll(flags ...string) error

RequireAll returns a validation error if any of the flags is not set. Useful for "these flags come as a group" constraints (e.g. --start requires --end).

func (*RuntimeContext) Str 

func (rt *RuntimeContext) Str(name string) string

Str returns the trimmed string value of a flag, or "" if unset.

func (*RuntimeContext) StrFirst 

func (rt *RuntimeContext) StrFirst(names ...string) string

StrFirst returns the first non-empty string value across a primary flag and its aliases.

func (*RuntimeContext) StrSlice 

func (rt *RuntimeContext) StrSlice(name string) []string

StrSlice returns the string-slice value of a flag.

func (*RuntimeContext) Yes 

func (rt *RuntimeContext) Yes() bool

Yes reports whether --yes is set (skip confirmation prompts).

type Shortcut 

type Shortcut struct {
	// Service is the top-level command group, e.g. "contact". Multiple
	// shortcuts sharing a Service are mounted under the same parent command.
	Service string
	// Command is the leaf name including its "+" prefix, e.g. "+search-user".
	Command string
	// Product is the canonical MCP product id used to build the invocation.
	// Defaults to Service when empty.
	Product string
	// Description is the one-line help shown in --help.
	Description string
	// Intent is a fuller natural-language description of what the command does
	// and WHEN to reach for it. Unlike the terse Description, it is written for
	// human discovery and AI-agent intent matching (e.g. "当你只知道某人姓名、需要
	// 拿到其 userId 以便后续发消息或指派任务时使用"). Surfaced in `--help` (as the
	// long description) and in `dws shortcut list`.
	Intent string
	// Risk classifies the side effect; defaults to RiskRead when empty.
	Risk Risk
	// Flags are the command-specific flags. Global flags are injected separately.
	Flags []Flag
	// Constraints publish and enforce relationships that individual flags cannot
	// express, such as "exactly one of --group and --user". Custom constraints
	// describe checks implemented by Validate.
	Constraints []Constraint
	// Tips are optional usage examples appended to --help.
	Tips []string
	// Hidden hides the command from listings while keeping it invocable.
	Hidden bool
	// UserDefined identifies shortcuts loaded from the user's config
	// directory. Distribution-owned Schema and interface snapshots exclude
	// these runtime extensions even if another root loaded them earlier.
	UserDefined bool

	// Validate optionally checks resolved flag values before execution. Return a
	// non-nil error to abort with a validation message. Runs after built-in
	// Required/Enum checks.
	Validate func(rt *RuntimeContext) error
	// Execute performs the shortcut. It is required. Typically it builds a
	// params map from rt's flags, calls rt.CallMCP, and rt.Output's the result.
	Execute func(rt *RuntimeContext) error
}

Shortcut is the declarative definition of a single high-fidelity command.

The zero-value is not usable; Service, Command and Execute are required. The framework injects the global --format/--dry-run/--jq/--yes flags from the root command, so shortcuts must not redeclare them.

func All 

func All() []Shortcut

All returns the registered shortcuts. Primarily for coverage tests that need each shortcut's declared flags (types/enums/required) to synthesize inputs.

Source Files

View all Source files

Directories

Path Synopsis
Package aitable provides declarative shortcuts for the DingTalk AI 表格 (aitable) service: Base / table / field / record / view / form / dashboard / chart / workflow / advanced-permission / section management.
 Package aitable provides declarative shortcuts for the DingTalk AI 表格 (aitable) service: Base / table / field / record / view / form / dashboard / chart / workflow / advanced-permission / section management.
Package attendance provides declarative shortcuts for the DingTalk attendance (考勤) service: attendance records, check results/records, approvals, shifts, schedules, class/group/rule management, statistics, settings, reports and vacation.
 Package attendance provides declarative shortcuts for the DingTalk attendance (考勤) service: attendance records, check results/records, approvals, shifts, schedules, class/group/rule management, statistics, settings, reports and vacation.
Package builtin aggregates all built-in shortcut service packages via blank imports so their init() registrations run, then re-exports the compiled cobra commands.
 Package builtin aggregates all built-in shortcut service packages via blank imports so their init() registrations run, then re-exports the compiled cobra commands.
Package calendar declares the declarative shortcut (+command) layer for the DingTalk calendar MCP product.
 Package calendar declares the declarative shortcut (+command) layer for the DingTalk calendar MCP product.
Package chat provides declarative shortcuts for the DingTalk chat service (群聊 / 会话 / 消息 / 机器人).
 Package chat provides declarative shortcuts for the DingTalk chat service (群聊 / 会话 / 消息 / 机器人).
Package contact provides declarative shortcuts for the DingTalk contact (通讯录) service: user / department / role / relation queries and the HR roster (花名册) lookups.
 Package contact provides declarative shortcuts for the DingTalk contact (通讯录) service: user / department / role / relation queries and the HR roster (花名册) lookups.
Package devapp declares high-fidelity shortcuts for the DingTalk open-platform developer application ("devapp") MCP service, for the apps command surface.
 Package devapp declares high-fidelity shortcuts for the DingTalk open-platform developer application ("devapp") MCP service, for the apps command surface.
Package ding holds the built-in DING (钉) shortcuts.
 Package ding holds the built-in DING (钉) shortcuts.
Package doc declares the high-fidelity `dws doc +<command>` shortcuts.
 Package doc declares the high-fidelity `dws doc +<command>` shortcuts.
Package drive declares high-fidelity shortcuts for the DingTalk drive (钉盘) service: file/folder listing, metadata, download link, folder creation, upload credentials, search, recycle bin, internet publish and the document space proxy operations (copy/move/rename/permission/recent).
 Package drive declares high-fidelity shortcuts for the DingTalk drive (钉盘) service: file/folder listing, metadata, download link, folder creation, upload credentials, search, recycle bin, internet publish and the document space proxy operations (copy/move/rename/permission/recent).
Package mail provides declarative shortcuts for the DingTalk mail (邮箱) service: mailbox / message / draft / thread / folder / tag / user / attachment / template / contact / auto-reply / rule operations.
 Package mail provides declarative shortcuts for the DingTalk mail (邮箱) service: mailbox / message / draft / thread / folder / tag / user / attachment / template / contact / auto-reply / rule operations.
Package minutes contains declarative shortcuts for DingTalk AI 听记 (minutes).
 Package minutes contains declarative shortcuts for DingTalk AI 听记 (minutes).
Package oa registers declarative shortcuts for the DingTalk OA approval service, wrapping the raw MCP tools exposed by the dws oa helper.
 Package oa registers declarative shortcuts for the DingTalk OA approval service, wrapping the raw MCP tools exposed by the dws oa helper.
Package report declares declarative shortcuts for the DingTalk "报告/日志" (OA 周报应用) MCP tools.
 Package report declares declarative shortcuts for the DingTalk "报告/日志" (OA 周报应用) MCP tools.
Package sheet declares high-fidelity shortcuts for the DingTalk sheet MCP product.
 Package sheet declares high-fidelity shortcuts for the DingTalk sheet MCP product.
Package smart holds genuine multi-step / intelligent shortcuts — commands that orchestrate several MCP calls or resolve names to IDs, so they are NOT a 1:1 wrapper over a single tool.
 Package smart holds genuine multi-step / intelligent shortcuts — commands that orchestrate several MCP calls or resolve names to IDs, so they are NOT a 1:1 wrapper over a single tool.
Package todo declares high-fidelity shortcuts for the DingTalk "todo" (personal todo) MCP service.
 Package todo declares high-fidelity shortcuts for the DingTalk "todo" (personal todo) MCP service.
Package usage records the SHAPE of MCP tool calls (which product/tool, which argument keys, and a redacted sample of ID/enum-like values) so that the shortcut layer can later mine high-frequency patterns and suggest distilling them into custom shortcuts (see docs/shortcut-p2-design.md).
 Package usage records the SHAPE of MCP tool calls (which product/tool, which argument keys, and a redacted sample of ID/enum-like values) so that the shortcut layer can later mine high-frequency patterns and suggest distilling them into custom shortcuts (see docs/shortcut-p2-design.md).
Package userdef loads user-defined shortcuts from ~/.dws/shortcuts/*.yaml and compiles them into the same shortcut.Shortcut model as the built-ins, so a distilled high-frequency operation behaves exactly like a native `+command`.
 Package userdef loads user-defined shortcuts from ~/.dws/shortcuts/*.yaml and compiles them into the same shortcut.Shortcut model as the built-ins, so a distilled high-frequency operation behaves exactly like a native `+command`.
Package wiki declares high-fidelity shortcuts for the DingTalk wiki (knowledge base) service: space management, member management and node management.
 Package wiki declares high-fidelity shortcuts for the DingTalk wiki (knowledge base) service: space management, member management and node management.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.