dingtalk-workspace-cli/docs/architecture.md

Architecture

dws is a Go CLI with a versioned, static command surface for DingTalk MCP capabilities. Cobra help serves humans; the embedded Command Catalog serves AI agents.

High-Level Flow

1. cmd is the CLI entrypoint, invoking internal/app to build the root Cobra command tree.
2. internal/app wires static utility commands (auth, audit, schema, completion), product helpers, and versioned plugin descriptors.
3. internal/helpers contains the main command handlers for all product surfaces (dev, chat, calendar, contact, aitable, etc.).
4. internal/executor and internal/transport execute MCP JSON-RPC calls; internal/output formats responses.
5. internal/auth manages login state, PAT tokens, and agent-code detection.
6. Schema generation combines the reviewed command surface, current Cobra flags, strong typed CLI constraints, sanitized MCP snapshots, Agent hints, and Skills at build time. Startup and Schema queries do not call MCP tools/list.
7. The embedded Catalog may backfill canonical identity for real commands, but it cannot replay parameter metadata into the next generation. Stable flag-to-RPC property bindings come from the versioned schema_parameter_bindings.json (316 active bindings: a 311-row historical seed, minus 3 exclusions, plus 8 current inherited-flag additions); CLI required and constraints come from Cobra/typed annotations. MCP required remains interface-only metadata.
8. Agent selection results are fixed in versioned review inputs. Every public tool has explicit use/avoid/example and interface disposition metadata; Skill references that are not current leaves require an explicit alias/group/stale/out-of-surface review instead of fuzzy runtime matching.

Repository Structure

• cmd: CLI entrypoint
• internal/app: root command wiring, static utility commands, and plugin loading
• internal/helpers: product command handlers (dev, chat, calendar, contact, etc.)
• internal/plugin: versioned plugin manifest, hook, skill, and transport descriptor loading
• internal/cli: embedded Agent Command Catalog, static schema query, and catalog contracts
• internal/generator: deterministic Agent metadata and Command Catalog generators
• internal/executor: invocation dispatch and result handling
• internal/transport: MCP HTTP client and request signing
• internal/auth: login, token management, agent-code detection, identity
• internal/audit: user operation audit log (JSONL, hash chain, forwarding)
• internal/errors: structured error model with categories and hints
• internal/keychain: OS keychain integration for credential storage
• internal/security: endpoint allowlist and domain trust
• internal/safety: runtime safety checks (confirm prompts, dry-run guards)
• internal/cobracmd: shared Cobra command builders
• internal/pat: PAT (Personal Access Token) authorization flow
• internal/output: response formatting (json, table, raw, pretty)
• internal/logging: structured logging and argument sanitization
• internal/tui: terminal UI helpers
• internal/recovery: panic recovery and graceful degradation
• pkg/configmeta: environment variable registry and documentation
• pkg/config: configuration constants and paths
• pkg/edition: edition detection (oss vs enterprise)
• pkg/mcptypes: MCP protocol type definitions
• internal/syncdata: generated static endpoint and command-routing data synced from the Wukong baseline
• skills/: bundled agent skills (mono/ and multi/ layouts)
• test/: CLI, integration, contract, unit, and skill E2E tests
• scripts/: install scripts, policy checks, and CI helpers