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 starts from the reviewed CommandRegistry, binds each identity to the exact current Cobra leaf, and then resolves typed constraints, sanitized MCP snapshots, Agent hints, and Skills into one SchemaRegistry. Startup and Schema queries do not call MCP tools/list.
7. The embedded Catalog is a downstream release artifact and never backfills identity or participates in regeneration. Stable flag-to-interface property bindings come from the reviewed, content-addressed v3 manifest in schema_parameter_bindings.json; its exact active tuples, corrections, removals, and mapping exclusions are validated against the final bound SchemaRegistry. CLI required and constraints come from the resolved typed contract, while 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/cmdcore: dispatch-agnostic leaf-command base — flag registration, alias/env/default value resolution, required and cross-flag constraint validation, Risk write confirmation, toolArgs assembly, Runtime Schema projection. Distinct from internal/cobracmd (generic tree helpers): it owns the declarative leaf contract (CommandSpec) that the LeafSpec framework is built on and that the Shortcut adapter projects into.
• 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

Quality Pipeline

Quality enforcement is layered so a pull request receives fast, deterministic admission feedback without pretending that downstream integration has already run.

flowchart TB
  PR["Pull request"] --> CLASSIFY["Fail-closed risk classification"]
  CLASSIFY --> DOCS["Documentation-only<br/>asset/content validation"]
  CLASSIFY --> STANDARD["Standard<br/>affected + reverse-dependent race<br/>scope-matched HEAD/base coverage"]
  CLASSIFY --> HIGH["High-risk / main<br/>full race + native tests"]
  DOCS --> CA["CI"]
  STANDARD --> CA
  HIGH --> CA
  subgraph CA_CHECKS["Nine required contexts"]
    L["Lint"]
    T["Test"]
    C["Coverage"]
    P["Policy"]
    E["Edition"]
    I["Interface Integrity"]
    A["AI Behavior"]
    S["CLI Smoke"]
    M["Mock MCP"]
  end
  CA --> CA_CHECKS
  CA_CHECKS --> MAIN["Protected main"]
  MAIN --> MP["Main Integration — 主干集成<br/>Multi-profile E2E"]
  MAIN --> PLATFORM["Risk-selected / release native platform validation"]
  MP --> RELEASE["Release delivery"]
  PLATFORM --> RELEASE

All nine named contexts are produced for every tier. Domain-specific helpers run when their owned surface is affected; otherwise the corresponding context records an explicit unaffected success. Standard code changes still receive representative Darwin/Windows compilation. High-risk PRs and protected main run the complete race and native test suites, while platform-sensitive diffs also receive native changed-code coverage.

Review orchestration is also base-owned: it requests one eligible peer without executing PR code, re-routes an updated head when needed, and auto-merge completes only after the latest push has peer approval plus the current revision's nine strict contexts. Complete Multi-profile E2E remains downstream of PR admission. See docs/ci-pr-gates.md for the exact classification, context, reviewer, and ruleset contract.