docs(skills,chat): clarify --title is required for chat message send (#174)

The backend MCP tools `send_direct_message_as_user` and
`send_message_as_user` both require `title` as a required field.
However, the skill documentation and --help Long text described
--title as "optional", causing AI models to omit it and trigger
a vague `business error: success=false`.

Update descriptions in:
- skills/references/products/chat.md
- internal/helpers/chat.go (command Long text)

Closes #173

.github/badges/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 49.8%"><title>coverage: 49.8%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#e05d44"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="835" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">49.8%</text><text x="835" y="140" transform="scale(.1)" fill="#fff" textLength="370">49.8%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 52.8%"><title>coverage: 52.8%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#e05d44"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="835" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">52.8%</text><text x="835" y="140" transform="scale(.1)" fill="#fff" textLength="370">52.8%</text></g></svg>

.gitignore

@@ -16,6 +16,7 @@ dws
 test/cli/testdata/
 tmp/
 test/cli_compat/testdata/
+/internal/compat/testdata/*
 .gitignore
 .worktrees/
 

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and this project follows [Semantic Versioning](https://semver.org/).
 
+## [1.0.16] - 2026-04-24
+
+Discovery service abstraction with schema v3 extensions, open-edition helper-subtree restoration, and a defensive device-flow login reset.
+
+### Added
+
+- **`internal/discovery` service abstraction** (#156) — encapsulates market registry fetch, MCP runtime negotiation (`initialize → tools/list → detail` merge), and multi-level cache fallback. `EnvironmentLoader` now does cache-first startup, with degraded-mode reasons (`unauthenticated` / `market_unreachable` / `runtime_all_failed`) and `UpdatedAt`-based selective re-discovery.
+- **Schema v3 extensions** (#156) — positional parameters with typed coercion, `Example` on `--help`, flag `Default` / `RuntimeDefault` (with `$currentUserId` / `$now` etc.), `BodyWrapper`, `MutuallyExclusive` / `RequireOneOf` flag groups, `OmitWhen`, explicit `Type` override, and detail-schema `default` propagation.
+- **`dws chat message send` destination-flag routing** (#170) — open edition gains a hardcoded helper that dispatches by `--group` (→ `send_message_as_user`) vs `--user` / `--open-dingtalk-id` (→ `send_direct_message_as_user`), mirroring the closed-source overlay so single-chat sends finally work end-to-end.
+
+### Changed
+
+- **`pickCommands` → `cmdutil.MergeHardcodedLeaves`** (#169) — when a top-level product name collides between the dynamic overlay and a helper subtree, helper-only siblings are grafted into the dynamic tree instead of dropped. Restores `dws chat message send-by-bot` / `recall-by-bot` / `send-by-webhook` and `dws chat group members add-bot`, which had silently vanished from the open edition.
+- **`OverridePriority` / `MergeHardcodedLeaves` promoted into `pkg/cmdutil`** (#170) — single source of truth for the merge layer; hardcoded leaves can opt into overriding the dynamic envelope via a strictly higher priority.
+
+### Fixed
+
+- **Device flow defensively resets credentials before login** (#157) — `--device` login now clears stale credential state and re-fetches `clientID` from the MCP server, regardless of what previous login methods (OAuth scan, PAT) left in `app.json`. Fixes the case where a prior OAuth login made `--device` fall back to direct mode and demand `clientSecret`.
+
 ## [1.0.15] - 2026-04-23
 
 Compat layer gains **subcommand merging** under shared parents so multiple server entries can contribute into the same `dws <parent> <branch>` subtree without producing duplicate `--help` rows. Ships with a fresh auto-generated command index doc, a README sync to **159 commands across 13 products**, and a wide-ranging flag-naming cleanup that standardises CLI flags across chat, calendar, drive, minutes, contact, and devdoc commands.
@@ -46,6 +65,10 @@ Compat layer gains **subcommand merging** under shared parents so multiple serve
   - `TestBuildDynamicCommands_ParentMergeRecursive` — recursive merge through nested groups (e.g. `chat.group.members`)
   - `TestBuildDynamicCommands_ParentMergeLeafCollision` — identical leaf paths resolve first-wins without producing duplicates
 
+## [1.0.14] - 2026-04-22
+
+Docs-only re-tag of v1.0.13. The single commit (#153) backfills the v1.0.13 release notes after the binary was already published; no functional or CLI surface change.
+
 ## [1.0.13] - 2026-04-22
 
 IM / Messaging capability expansion: the `chat` (aka `im`) product surface grows from "group + bot messaging" into a full conversational layer — user-identity messaging, message reading & search, personal messages, topic replies, mentions, focused contacts, unread/top/common conversations, org-wide group creation, and first-class bot lifecycle.

internal/app/auth_command_test.go

@@ -26,7 +26,9 @@ import (
 )
 
 func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
-	// Cleanup keychain after test
+	// Isolate keychain storage to a per-test directory so the saved
+	// token can't leak into other test packages running in parallel.
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
 	t.Cleanup(func() {
 		_ = keychain.Remove(keychain.Service, keychain.AccountToken)
 	})

internal/app/auth_refresh_retry.go

@@ -0,0 +1,83 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"context"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/authretry"
+)
+
+// authRetryingKey marks a context that has already attempted one
+// AuthRefreshRequired-driven retry of the current invocation. The runner uses
+// this to refuse a second refresh+retry pass and surface the original cause
+// to the user instead.
+type authRetryingKeyType struct{}
+
+var authRetryingKey = authRetryingKeyType{}
+
+// IsAuthRetrying reports whether the current context is already inside an
+// AuthRefreshRequired retry. Mirrors IsPatRetrying.
+func IsAuthRetrying(ctx context.Context) bool {
+	if ctx == nil {
+		return false
+	}
+	v, _ := ctx.Value(authRetryingKey).(bool)
+	return v
+}
+
+// withAuthRetrying returns a child context flagged as "already retried once"
+// so the runner does not enter an infinite refresh loop if the second attempt
+// also returns AuthRefreshRequired.
+func withAuthRetrying(ctx context.Context) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return context.WithValue(ctx, authRetryingKey, true)
+}
+
+// handleAuthRefreshRequired performs a one-shot ForceRefresh using the active
+// configDir and re-runs the invocation through the supplied runner. It must
+// only be called when the runner has observed an *authretry.AuthRefreshRequired
+// from an edition hook (ClassifyToolResult / OnAuthError).
+//
+// Behaviour rules — all three matter for safety:
+//  1. If the context is already flagged via IsAuthRetrying, this returns
+//     refresh.Cause unchanged. No further refresh attempts, no recursion.
+//  2. If ForceRefresh fails (e.g. refresh_token also expired), this returns
+//     refresh.Cause so the user sees the original auth diagnostic, not an
+//     internal "force refresh failed" message.
+//  3. On successful refresh, this resets the per-process token cache and
+//     re-runs the invocation with withAuthRetrying applied so a second
+//     refresh request from the overlay degrades gracefully to "show the
+//     original error".
+func handleAuthRefreshRequired(
+	ctx context.Context,
+	r executor.Runner,
+	invocation executor.Invocation,
+	refresh *authretry.AuthRefreshRequired,
+) (executor.Result, error) {
+	if refresh == nil {
+		return executor.Result{}, nil
+	}
+	if IsAuthRetrying(ctx) {
+		return executor.Result{}, refresh.Cause
+	}
+	if _, err := ForceRefreshAccessToken(ctx, defaultConfigDir()); err != nil {
+		return executor.Result{}, refresh.Cause
+	}
+	ResetRuntimeTokenCache()
+	return r.Run(withAuthRetrying(ctx), invocation)
+}

internal/app/direct_runtime.go

@@ -80,11 +80,19 @@ func SetDynamicServers(servers []market.ServerDescriptor) {
 					toolEndpoints[toolName] = endpoint
 				}
 			}
-			for toolName := range server.CLI.ToolOverrides {
+			for toolName, override := range server.CLI.ToolOverrides {
 				toolName = strings.TrimSpace(toolName)
-				if toolName != "" {
-					toolEndpoints[toolName] = endpoint
+				if toolName == "" {
+					continue
 				}
+				// Leaves with serverOverride are routed to a different server's
+				// endpoint (e.g. chat's "search_my_robots" → bot). Registering
+				// them here would overwrite the real owner's tool → endpoint
+				// mapping and send the invocation to the wrong MCP URL.
+				if strings.TrimSpace(override.ServerOverride) != "" {
+					continue
+				}
+				toolEndpoints[toolName] = endpoint
 			}
 		}
 	}
@@ -208,11 +216,17 @@ func AppendDynamicServer(server market.ServerDescriptor) {
 				dynamicToolEndpoints[toolName] = endpoint
 			}
 		}
-		for toolName := range server.CLI.ToolOverrides {
+		for toolName, override := range server.CLI.ToolOverrides {
 			toolName = strings.TrimSpace(toolName)
-			if toolName != "" {
-				dynamicToolEndpoints[toolName] = endpoint
+			if toolName == "" {
+				continue
 			}
+			// Leaves with serverOverride are routed to a different server's
+			// endpoint; skip to avoid overwriting the real owner's mapping.
+			if strings.TrimSpace(override.ServerOverride) != "" {
+				continue
+			}
+			dynamicToolEndpoints[toolName] = endpoint
 		}
 	}
 }

internal/app/direct_runtime_override_test.go

@@ -0,0 +1,183 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+)
+
+// Regression for the chat/bot tool routing bug: when the `chat` envelope
+// declares toolOverrides with `serverOverride: "bot"` (e.g. `search_my_robots`,
+// `send_message_by_custom_robot`), those tool names must NOT be registered
+// into `dynamicToolEndpoints` pointing at chat's endpoint. Otherwise the
+// tool-level Priority 1 lookup in `directRuntimeEndpoint` returns chat's URL
+// even when the invocation's CanonicalProduct is "bot", causing the Portal to
+// respond with `PARAM_ERROR - 未找到指定工具` because chat's mcpId has no such
+// tool.
+//
+// Owner (bot envelope) still registers the tool (no serverOverride on the bot
+// side), so product-level and tool-level lookups both resolve correctly.
+
+const (
+	testBotEndpoint  = "https://pre-mcp-gw.dingtalk.com/server/4717d5cbb92ecdebd89c174e4331dc17207208a97622e2004cac49c0fbedc9d1"
+	testChatEndpoint = "https://pre-mcp-gw.dingtalk.com/server/0a1609437385696b77fc4771c3ddaf5656b487f809966c0cc8d4755e7b1d3b74"
+)
+
+// botDescriptor returns a minimal `bot` server descriptor that owns the
+// `search_my_robots` + `send_message_by_custom_robot` tools (no
+// serverOverride — bot is the real owner).
+func botDescriptor() market.ServerDescriptor {
+	return market.ServerDescriptor{
+		Endpoint: testBotEndpoint,
+		CLI: market.CLIOverlay{
+			ID: "bot",
+			ToolOverrides: map[string]market.CLIToolOverride{
+				"search_my_robots":             {CLIName: "search"},
+				"send_message_by_custom_robot": {CLIName: "send-by-webhook"},
+				"add_robot_to_group":           {CLIName: "add-bot"},
+			},
+		},
+	}
+}
+
+// chatDescriptor returns a minimal `chat` server descriptor whose
+// toolOverrides include bot-owned tools via `serverOverride: "bot"`, plus a
+// chat-native tool (`search_groups_by_keyword`) that must remain routed to
+// chat's endpoint.
+func chatDescriptor() market.ServerDescriptor {
+	return market.ServerDescriptor{
+		Endpoint: testChatEndpoint,
+		CLI: market.CLIOverlay{
+			ID:      "chat",
+			Command: "chat",
+			ToolOverrides: map[string]market.CLIToolOverride{
+				"search_groups_by_keyword": {CLIName: "search"},
+				"search_my_robots": {
+					CLIName:        "search",
+					ServerOverride: "bot",
+				},
+				"send_message_by_custom_robot": {
+					CLIName:        "send-by-webhook",
+					ServerOverride: "bot",
+				},
+				"add_robot_to_group": {
+					CLIName:        "add-bot",
+					ServerOverride: "bot",
+				},
+			},
+		},
+	}
+}
+
+// withCleanDynamicRegistry snapshots and restores the package-level dynamic
+// registries so parallel/other tests aren't affected by this case's mutations.
+func withCleanDynamicRegistry(t *testing.T) {
+	t.Helper()
+	dynamicMu.Lock()
+	prev := struct {
+		endpoints     map[string]string
+		products      map[string]bool
+		aliases       map[string]string
+		toolEndpoints map[string]string
+	}{dynamicEndpoints, dynamicProducts, dynamicAliases, dynamicToolEndpoints}
+	dynamicEndpoints = nil
+	dynamicProducts = nil
+	dynamicAliases = nil
+	dynamicToolEndpoints = nil
+	dynamicMu.Unlock()
+	t.Cleanup(func() {
+		dynamicMu.Lock()
+		dynamicEndpoints = prev.endpoints
+		dynamicProducts = prev.products
+		dynamicAliases = prev.aliases
+		dynamicToolEndpoints = prev.toolEndpoints
+		dynamicMu.Unlock()
+	})
+}
+
+func assertEndpoint(t *testing.T, productID, toolName, want string) {
+	t.Helper()
+	got, ok := directRuntimeEndpoint(productID, toolName)
+	if !ok {
+		t.Fatalf("directRuntimeEndpoint(%q, %q) returned ok=false", productID, toolName)
+	}
+	if got != want {
+		t.Fatalf("directRuntimeEndpoint(%q, %q) = %q, want %q", productID, toolName, got, want)
+	}
+}
+
+// TestSetDynamicServers_ServerOverrideDoesNotHijackToolEndpoint verifies that
+// chat's serverOverride entries cannot steal bot-owned tool routes, regardless
+// of registration order.
+func TestSetDynamicServers_ServerOverrideDoesNotHijackToolEndpoint(t *testing.T) {
+	tests := []struct {
+		name    string
+		servers []market.ServerDescriptor
+	}{
+		{
+			name:    "bot first, chat second",
+			servers: []market.ServerDescriptor{botDescriptor(), chatDescriptor()},
+		},
+		{
+			name:    "chat first, bot second",
+			servers: []market.ServerDescriptor{chatDescriptor(), botDescriptor()},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			withCleanDynamicRegistry(t)
+			SetDynamicServers(tc.servers)
+
+			// Bot-owned tools must route to bot's endpoint even though chat
+			// declares toolOverrides for them (with serverOverride="bot").
+			assertEndpoint(t, "bot", "search_my_robots", testBotEndpoint)
+			assertEndpoint(t, "bot", "send_message_by_custom_robot", testBotEndpoint)
+			assertEndpoint(t, "bot", "add_robot_to_group", testBotEndpoint)
+
+			// Chat-native tools must still route to chat.
+			assertEndpoint(t, "chat", "search_groups_by_keyword", testChatEndpoint)
+
+			// Product-level fallback for bot (no tool name) must also return
+			// bot's endpoint.
+			assertEndpoint(t, "bot", "", testBotEndpoint)
+		})
+	}
+}
+
+// TestAppendDynamicServer_ServerOverrideDoesNotHijackToolEndpoint exercises
+// the plugin-injection path (`AppendDynamicServer`) which has the same
+// `toolOverrides` registration loop as `SetDynamicServers`. Chat's
+// serverOverride entries must not overwrite bot's tool → endpoint mapping.
+func TestAppendDynamicServer_ServerOverrideDoesNotHijackToolEndpoint(t *testing.T) {
+	orders := [][]market.ServerDescriptor{
+		{botDescriptor(), chatDescriptor()},
+		{chatDescriptor(), botDescriptor()},
+	}
+
+	for _, servers := range orders {
+		t.Run("", func(t *testing.T) {
+			withCleanDynamicRegistry(t)
+			for _, s := range servers {
+				AppendDynamicServer(s)
+			}
+
+			assertEndpoint(t, "bot", "search_my_robots", testBotEndpoint)
+			assertEndpoint(t, "bot", "send_message_by_custom_robot", testBotEndpoint)
+			assertEndpoint(t, "chat", "search_groups_by_keyword", testChatEndpoint)
+		})
+	}
+}

internal/app/force_refresh.go

@@ -0,0 +1,62 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"strings"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+)
+
+// ForceRefreshAccessToken forces a single refresh_token exchange and returns
+// the new access_token. It is intended for callers that have observed a
+// server-side rejection (HTTP 401 or business code such as
+// TOKEN_VERIFIED_FAILED) on what locally appeared to be a still-valid token.
+//
+// Steps:
+//  1. MarkAccessTokenStale rewrites ExpiresAt to a past instant so
+//     OAuthProvider.GetAccessToken's fast-path will miss.
+//  2. NewOAuthProvider + GetAccessToken triggers lockedRefresh, which uses the
+//     existing dual-layer lock (process + file) to serialize concurrent
+//     refresh attempts across goroutines and processes.
+//  3. ResetRuntimeTokenCache clears the per-process sync.Once cache so the
+//     next resolveAuthToken call re-reads from disk.
+//
+// Existing OAuthProvider.GetAccessToken behaviour is unchanged; this helper
+// is the only entry point that orchestrates "force refresh" semantics.
+func ForceRefreshAccessToken(ctx context.Context, configDir string) (string, error) {
+	if strings.TrimSpace(configDir) == "" {
+		return "", fmt.Errorf("config directory is empty")
+	}
+	if err := authpkg.MarkAccessTokenStale(configDir); err != nil {
+		return "", fmt.Errorf("mark access token stale: %w", err)
+	}
+	disc := slog.New(slog.NewTextHandler(io.Discard, nil))
+	provider := authpkg.NewOAuthProvider(configDir, disc)
+	configureOAuthProviderCompatibility(provider, configDir)
+	tok, err := provider.GetAccessToken(ctx)
+	if err != nil {
+		return "", err
+	}
+	tok = strings.TrimSpace(tok)
+	if tok == "" {
+		return "", fmt.Errorf("force refresh returned empty access token")
+	}
+	ResetRuntimeTokenCache()
+	return tok, nil
+}

internal/app/legacy.go

@@ -32,6 +32,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
@@ -47,12 +48,46 @@ func newLegacyPublicCommands(ctx context.Context, runner executor.Runner) []*cob
 		return mergeTopLevelCommands(commands)
 	}
 
-	var commands []*cobra.Command
-	if dynamicCmds := loadDynamicCommands(ctx, runner); len(dynamicCmds) > 0 {
-		commands = append(commands, dynamicCmds...)
+	dynamicCmds := loadDynamicCommands(ctx, runner)
+	helperCmds := helpers.NewPublicCommands(runner)
+	return mergeTopLevelCommands(pickCommands(dynamicCmds, helperCmds))
+}
+
+// pickCommands returns the union of dynamic and helpers commands. For
+// same-named top-level products, helper-only leaves are grafted into the
+// dynamic tree via cmdutil.MergeHardcodedLeaves so the discovery envelope
+// remains the authority for leaves it declares, while hardcoded helpers can
+// still fill gaps the envelope did not cover (e.g. `chat message send-by-bot`
+// alongside the envelope's `chat message send`).
+//
+// Why this exists: mergeTopLevelCommands below calls cobracmd.MergeCommandTree
+// on same-named top-level commands, which — at leaf conflicts — falls back to
+// "more local flags wins" via ShouldReplaceLeaf. Hardcoded helpers commands
+// typically expose more flags than the corresponding dynamic overlay leaves,
+// so a naive append would silently promote helper leaves over their dynamic
+// counterparts. MergeHardcodedLeaves avoids that by letting dynamic win every
+// leaf conflict, and only adding subtrees the dynamic side lacks.
+func pickCommands(dynamic, helpers []*cobra.Command) []*cobra.Command {
+	dynByName := make(map[string]*cobra.Command, len(dynamic))
+	out := make([]*cobra.Command, 0, len(dynamic)+len(helpers))
+	for _, c := range dynamic {
+		if c == nil {
+			continue
+		}
+		dynByName[c.Name()] = c
+		out = append(out, c)
 	}
-	commands = append(commands, helpers.NewPublicCommands(runner)...)
-	return mergeTopLevelCommands(commands)
+	for _, h := range helpers {
+		if h == nil {
+			continue
+		}
+		if dyn := dynByName[h.Name()]; dyn != nil {
+			cmdutil.MergeHardcodedLeaves(dyn, h)
+			continue
+		}
+		out = append(out, h)
+	}
+	return out
 }
 
 // injectStaticServers converts edition.ServerInfo entries into
@@ -87,9 +122,58 @@ func injectStaticServers(servers []edition.ServerInfo) {
 //
 // Tests may override discoveryBaseURLOverride to redirect to a local server;
 // in that case the registry cache is always bypassed.
+// editionPartition returns the cache partition for the active edition.
+// Each edition gets its own partition to prevent cross-edition data leakage.
+func editionPartition() string {
+	name := edition.Get().Name
+	if name == "" || name == "open" {
+		return config.DefaultPartition
+	}
+	return name + "/default"
+}
+
+// discoveryTraceEnabled reports whether the user asked for discovery-path diagnostics.
+// loadDynamicCommands runs while building the command tree, before PersistentPreRun
+// applies --debug to slog; we also accept argv --debug and DWS_PERF_DEBUG for consistency.
+func discoveryTraceEnabled() bool {
+	if IsPerfDebugEnabled() {
+		return true
+	}
+	for _, a := range os.Args[1:] {
+		if a == "--debug" {
+			return true
+		}
+	}
+	return false
+}
+
+func discoveryTraceServerIDs(servers []market.ServerDescriptor) []string {
+	seen := make(map[string]struct{})
+	for _, s := range servers {
+		id := strings.TrimSpace(s.CLI.Command)
+		if id == "" {
+			id = strings.TrimSpace(s.CLI.ID)
+		}
+		if id == "" {
+			continue
+		}
+		seen[id] = struct{}{}
+	}
+	out := make([]string, 0, len(seen))
+	for id := range seen {
+		out = append(out, id)
+	}
+	sort.Strings(out)
+	const maxIDs = 48
+	if len(out) > maxIDs {
+		out = out[:maxIDs]
+	}
+	return out
+}
+
 func loadDynamicCommands(ctx context.Context, runner executor.Runner) []*cobra.Command {
 	store := cacheStoreFromEnv()
-	partition := config.DefaultPartition
+	partition := editionPartition()
 
 	// Bypass the registry cache when a fixture override is active.
 	// This ensures tests that set DWS_CATALOG_FIXTURE always get fresh
@@ -116,27 +200,55 @@ func loadDynamicCommands(ctx context.Context, runner executor.Runner) []*cobra.C
 		}
 	}
 
+	if len(servers) > 0 && discoveryTraceEnabled() {
+		slog.Info("loadDynamicCommands: skipping sync discovery fetch, using registry cache",
+			"partition", partition,
+			"servers", len(servers),
+			"registry_freshness", string(freshness))
+	}
+
 	// Cache miss or bypassed: fetch from market API synchronously (first run only).
 	if len(servers) == 0 {
-		baseURL := cli.DefaultMarketBaseURL
-		if discoveryBaseURLOverride != "" {
-			baseURL = discoveryBaseURLOverride
+		if discoveryTraceEnabled() {
+			if edURL := strings.TrimSpace(edition.Get().DiscoveryURL); edURL != "" {
+				slog.Info("loadDynamicCommands: sync discovery fetch", "partition", partition, "url", edURL)
+			} else {
+				baseURL := cli.DefaultMarketBaseURL
+				if discoveryBaseURLOverride != "" {
+					baseURL = discoveryBaseURLOverride
+				}
+				slog.Info("loadDynamicCommands: sync market catalog fetch", "partition", partition, "base_url", baseURL)
+			}
 		}
 		fetchStart := time.Now()
-		client := market.NewClient(baseURL, ipv4OnlyHTTPClient())
-		resp, fetchErr := client.FetchServers(ctx, config.DefaultFetchServersLimit)
+
+		resp, fetchErr := fetchRegistryServers(ctx, ipv4OnlyHTTPClient())
+
 		RecordTiming(ctx, "market_fetch", time.Since(fetchStart))
 		if fetchErr != nil {
+			if discoveryTraceEnabled() {
+				slog.Info("loadDynamicCommands: sync discovery fetch failed",
+					"partition", partition,
+					"error", fetchErr.Error())
+			}
 			slog.Debug("loadDynamicCommands: market API fetch failed", "error", fetchErr)
 			// Degrade to stale cache if available (production only).
 			if useCache && cacheErr == nil && len(snapshot.Servers) > 0 {
 				slog.Debug("loadDynamicCommands: degrading to stale registry cache", "servers", len(snapshot.Servers))
 				servers = snapshot.Servers
 			} else {
-				return nil
+				// no-op: fall through to FallbackServers check below
 			}
 		} else {
 			servers = market.NormalizeServers(resp, "market")
+			if discoveryTraceEnabled() {
+				slog.Info("loadDynamicCommands: sync discovery fetch ok",
+					"partition", partition,
+					"response_servers", len(resp.Servers),
+					"metadata_count", resp.Metadata.Count,
+					"normalized_servers", len(servers),
+					"cli_command_ids", discoveryTraceServerIDs(servers))
+			}
 			// Persist fresh data (only in non-test mode).
 			if useCache {
 				saveStart := time.Now()
@@ -148,9 +260,22 @@ func loadDynamicCommands(ctx context.Context, runner executor.Runner) []*cobra.C
 		}
 	}
 
+	// FallbackServers: safety net when Market discovery + cache both fail.
 	if len(servers) == 0 {
+		if fn := edition.Get().FallbackServers; fn != nil {
+			if fb := fn(); len(fb) > 0 {
+				slog.Debug("loadDynamicCommands: using FallbackServers", "count", len(fb))
+				descriptors := fallbackToDescriptors(fb)
+				descriptors = mergeSupplementServers(descriptors)
+				SetDynamicServers(descriptors)
+				return nil
+			}
+		}
 		return nil
 	}
+
+	// Merge edition-specific supplement servers (not in Market).
+	servers = mergeSupplementServers(servers)
 	// Inject dynamic server data for endpoint resolution
 	SetDynamicServers(servers)
 
@@ -172,7 +297,7 @@ func loadCachedDetailsFast(store *cache.Store, servers []market.ServerDescriptor
 	if store == nil {
 		return result
 	}
-	partition := config.DefaultPartition
+	partition := editionPartition()
 	for _, server := range servers {
 		if server.DetailLocator.MCPID <= 0 {
 			continue
@@ -203,7 +328,7 @@ func fetchDetailsByServerID(ctx context.Context, client *market.Client, servers
 	if ctx == nil {
 		ctx = context.Background()
 	}
-	partition := config.DefaultPartition
+	partition := editionPartition()
 	now := time.Now().UTC()
 	if store != nil && store.Now != nil {
 		now = store.Now().UTC()
@@ -333,13 +458,13 @@ func DiscoveryBaseURL() string {
 	return cli.DefaultMarketBaseURL
 }
 
-// ipv4OnlyHTTPClient returns an HTTP client that forces IPv4 connections
-// and uses a short timeout suitable for CLI startup network requests.
-// This avoids IPv6 DNS/connect timeouts on hosts without IPv6 networking.
-func ipv4OnlyHTTPClient() *http.Client {
+// ipv4HTTPClient returns an HTTP client that forces IPv4 connections with
+// the given total request timeout. This avoids IPv6 DNS/connect timeouts on
+// hosts without IPv6 networking.
+func ipv4HTTPClient(timeout time.Duration) *http.Client {
 	dialer := &net.Dialer{Timeout: 3 * time.Second}
 	return &http.Client{
-		Timeout: 5 * time.Second,
+		Timeout: timeout,
 		Transport: &http.Transport{
 			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
 				return dialer.DialContext(ctx, "tcp4", addr)
@@ -348,6 +473,29 @@ func ipv4OnlyHTTPClient() *http.Client {
 	}
 }
 
+// ipv4OnlyHTTPClient returns an IPv4-forcing HTTP client with a short timeout
+// suitable for CLI startup network requests.
+func ipv4OnlyHTTPClient() *http.Client {
+	return ipv4HTTPClient(5 * time.Second)
+}
+
+// fetchRegistryServers performs the server-list HTTP fetch honoring the
+// active edition's DiscoveryURL override. It is the single source of truth
+// for all server-list fetches (startup, async revalidation, explicit
+// `cache refresh`); keeping the edition-URL branch in one place prevents
+// call sites from drifting out of sync.
+func fetchRegistryServers(ctx context.Context, httpClient *http.Client) (market.ListResponse, error) {
+	if editionURL := strings.TrimSpace(edition.Get().DiscoveryURL); editionURL != "" {
+		client := market.NewClient("", httpClient)
+		if fn := edition.Get().DiscoveryHeaders; fn != nil {
+			client.Headers = fn()
+		}
+		return client.FetchServersFromURL(ctx, editionURL)
+	}
+	client := market.NewClient(DiscoveryBaseURL(), httpClient)
+	return client.FetchServers(ctx, config.DefaultFetchServersLimit)
+}
+
 // asyncRevalidateRegistry refreshes the registry cache in the background.
 // Uses a short timeout derived from the parent context and silently ignores
 // errors — the next CLI invocation will pick up the refreshed cache or retry.
@@ -355,9 +503,7 @@ func asyncRevalidateRegistry(parent context.Context, store *cache.Store, partiti
 	ctx, cancel := context.WithTimeout(parent, 30*time.Second)
 	defer cancel()
 
-	baseURL := DiscoveryBaseURL()
-	client := market.NewClient(baseURL, ipv4OnlyHTTPClient())
-	resp, err := client.FetchServers(ctx, config.DefaultFetchServersLimit)
+	resp, err := fetchRegistryServers(ctx, ipv4OnlyHTTPClient())
 	if err != nil {
 		slog.Debug("asyncRevalidateRegistry: fetch failed", "error", err)
 		return
@@ -398,3 +544,50 @@ func mergeTopLevelCommands(commands []*cobra.Command) []*cobra.Command {
 	})
 	return out
 }
+
+// mergeSupplementServers appends edition-specific servers (not in Market)
+// into the discovery result. Existing IDs from Market/cache take precedence.
+func mergeSupplementServers(servers []market.ServerDescriptor) []market.ServerDescriptor {
+	fn := edition.Get().SupplementServers
+	if fn == nil {
+		return servers
+	}
+	existing := make(map[string]bool, len(servers))
+	for _, s := range servers {
+		existing[s.CLI.ID] = true
+		existing[s.Key] = true
+	}
+	for _, sup := range fn() {
+		if !existing[sup.ID] {
+			servers = append(servers, market.ServerDescriptor{
+				Key:         sup.ID,
+				DisplayName: sup.Name,
+				Endpoint:    sup.Endpoint,
+				CLI: market.CLIOverlay{
+					ID:       sup.ID,
+					Command:  sup.ID,
+					Prefixes: sup.Prefixes,
+				},
+			})
+		}
+	}
+	return servers
+}
+
+// fallbackToDescriptors converts edition.ServerInfo into market.ServerDescriptor.
+func fallbackToDescriptors(servers []edition.ServerInfo) []market.ServerDescriptor {
+	descriptors := make([]market.ServerDescriptor, 0, len(servers))
+	for _, s := range servers {
+		descriptors = append(descriptors, market.ServerDescriptor{
+			Key:         s.ID,
+			DisplayName: s.Name,
+			Endpoint:    s.Endpoint,
+			CLI: market.CLIOverlay{
+				ID:       s.ID,
+				Command:  s.ID,
+				Prefixes: s.Prefixes,
+			},
+		})
+	}
+	return descriptors
+}

internal/app/legacy_test.go

@@ -0,0 +1,160 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestPickCommands_DynamicWinsLeafConflicts verifies that when the discovery
+// envelope produces a dynamic leaf and a helper registers the same-named leaf,
+// the dynamic one wins — envelopes remain the runtime authority for behaviour
+// they declare. The helper subtree must not slip in via
+// mergeTopLevelCommands's LocalFlagCount-based arbitration.
+func TestPickCommands_DynamicWinsLeafConflicts(t *testing.T) {
+	dynTask := &cobra.Command{Use: "task", Short: "dynamic-task", Run: func(*cobra.Command, []string) {}}
+	dyn := &cobra.Command{Use: "todo", Short: "dynamic"}
+	dyn.AddCommand(dynTask)
+	dynamic := []*cobra.Command{dyn}
+
+	hlpTask := &cobra.Command{Use: "task", Short: "helper-task", Run: func(*cobra.Command, []string) {}}
+	hlp := &cobra.Command{Use: "todo", Short: "helper"}
+	hlp.AddCommand(hlpTask)
+	helpers := []*cobra.Command{hlp}
+
+	got := pickCommands(dynamic, helpers)
+
+	if len(got) != 1 || got[0] != dyn {
+		t.Fatalf("pickCommands returned %v, want [dyn]", got)
+	}
+	// The dynamic leaf must still be the one we find under the top-level name.
+	var found *cobra.Command
+	for _, c := range got[0].Commands() {
+		if c.Name() == "task" {
+			found = c
+		}
+	}
+	if found != dynTask {
+		t.Fatalf("leaf conflict resolved to helper; want dynamic to win")
+	}
+}
+
+// TestPickCommands_HelperOnlyLeavesAreGrafted verifies that when a helper
+// registers siblings the discovery envelope did NOT declare (e.g.
+// `chat message send-by-bot`, `chat message recall-by-bot` next to the
+// envelope's `chat message send`), those helper-only leaves are grafted into
+// the dynamic subtree instead of being dropped. This is a regression guard:
+// prior to this fix, pickCommands silently dropped the entire helper subtree
+// whenever the top-level product name collided, which disappeared every
+// helper-only leaf the envelope didn't cover.
+func TestPickCommands_HelperOnlyLeavesAreGrafted(t *testing.T) {
+	dynMessage := &cobra.Command{Use: "message"}
+	dynMessage.AddCommand(&cobra.Command{Use: "send", Run: func(*cobra.Command, []string) {}})
+	dyn := &cobra.Command{Use: "chat"}
+	dyn.AddCommand(dynMessage)
+	dynamic := []*cobra.Command{dyn}
+
+	helperOnlyLeaf := &cobra.Command{Use: "send-by-bot", Run: func(*cobra.Command, []string) {}}
+	hlpMessage := &cobra.Command{Use: "message"}
+	hlpMessage.AddCommand(helperOnlyLeaf)
+	hlp := &cobra.Command{Use: "chat"}
+	hlp.AddCommand(hlpMessage)
+	helpers := []*cobra.Command{hlp}
+
+	got := pickCommands(dynamic, helpers)
+
+	if len(got) != 1 || got[0] != dyn {
+		t.Fatalf("pickCommands returned %v, want [dyn]", got)
+	}
+	var grafted *cobra.Command
+	for _, child := range dynMessage.Commands() {
+		if child.Name() == "send-by-bot" {
+			grafted = child
+		}
+	}
+	if grafted == nil {
+		t.Fatalf("helper-only leaf send-by-bot was not grafted into dynamic.chat.message")
+	}
+	if grafted != helperOnlyLeaf {
+		t.Fatalf("grafted leaf identity differs from helper-registered leaf")
+	}
+}
+
+// TestPickCommands_HelpersFillUncoveredProducts verifies that helpers whose
+// names are NOT in the dynamic set are preserved — the dynamic overlay only
+// shadows products it actually covers.
+func TestPickCommands_HelpersFillUncoveredProducts(t *testing.T) {
+	dyn := &cobra.Command{Use: "todo"}
+	dynamic := []*cobra.Command{dyn}
+
+	todoHelper := &cobra.Command{Use: "todo"}
+	attendanceHelper := &cobra.Command{Use: "attendance"}
+	chatHelper := &cobra.Command{Use: "chat"}
+	helpers := []*cobra.Command{todoHelper, attendanceHelper, chatHelper}
+
+	got := pickCommands(dynamic, helpers)
+
+	names := make(map[string]*cobra.Command, len(got))
+	for _, c := range got {
+		names[c.Name()] = c
+	}
+	if names["todo"] != dyn {
+		t.Fatalf("todo = %v, want dynamic", names["todo"])
+	}
+	if names["attendance"] != attendanceHelper {
+		t.Fatalf("attendance not preserved from helpers")
+	}
+	if names["chat"] != chatHelper {
+		t.Fatalf("chat not preserved from helpers")
+	}
+	if len(got) != 3 {
+		t.Fatalf("got %d commands, want 3 (todo+attendance+chat)", len(got))
+	}
+}
+
+// TestPickCommands_EmptyDynamicPreservesHelpers verifies the degenerate case:
+// when discovery returns nothing, helpers are the sole source of truth — the
+// behaviour must be identical to the pre-refactor append-all code path.
+func TestPickCommands_EmptyDynamicPreservesHelpers(t *testing.T) {
+	todoHelper := &cobra.Command{Use: "todo"}
+	chatHelper := &cobra.Command{Use: "chat"}
+	helpers := []*cobra.Command{todoHelper, chatHelper}
+
+	got := pickCommands(nil, helpers)
+
+	if len(got) != 2 {
+		t.Fatalf("got %d commands, want 2", len(got))
+	}
+	if got[0] != todoHelper || got[1] != chatHelper {
+		t.Fatalf("pickCommands changed helpers order or identity")
+	}
+}
+
+// TestPickCommands_NilsAreSkipped guards against nil entries sneaking in from
+// a misbehaving factory.
+func TestPickCommands_NilsAreSkipped(t *testing.T) {
+	dyn := &cobra.Command{Use: "todo"}
+	hlp := &cobra.Command{Use: "chat"}
+
+	got := pickCommands([]*cobra.Command{nil, dyn}, []*cobra.Command{nil, hlp})
+
+	if len(got) != 2 {
+		t.Fatalf("got %d commands, want 2 (nils filtered)", len(got))
+	}
+	if got[0] != dyn || got[1] != hlp {
+		t.Fatalf("unexpected ordering or identity after nil filter")
+	}
+}

internal/app/plugin_stdio_overlay.go

@@ -0,0 +1,206 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"encoding/json"
+	"log/slog"
+	"os"
+	"path/filepath"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cache"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/compat"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/spf13/cobra"
+)
+
+// resolveStdioOverlay resolves the CLIOverlay for a stdio plugin server
+// from its manifest. It supports two forms:
+//
+//  1. inline JSON object in manifest.MCPServers[key].CLI
+//  2. a relative file path (JSON string) pointing to an external overlay
+//     file anchored at the plugin root (e.g. "overlay.json")
+//
+// When no CLI metadata is present, a minimal overlay keyed by the server
+// name is returned so callers can still build an identity descriptor.
+func resolveStdioOverlay(p *plugin.Plugin, sc plugin.StdioServerClient) market.CLIOverlay {
+	serverID := sc.Key
+	overlay := market.CLIOverlay{
+		ID:      serverID,
+		Command: serverID,
+	}
+	srv, ok := p.Manifest.MCPServers[sc.Key]
+	if !ok || len(srv.CLI) == 0 {
+		return overlay
+	}
+
+	cliData := srv.CLI
+	// A JSON string is interpreted as a relative path to an external
+	// overlay file (e.g. "overlay.json") anchored at the plugin root.
+	if len(cliData) > 0 && cliData[0] == '"' {
+		var cliPath string
+		if err := json.Unmarshal(cliData, &cliPath); err == nil && cliPath != "" {
+			absPath := filepath.Join(p.Root, cliPath)
+			if fileData, readErr := os.ReadFile(absPath); readErr == nil {
+				cliData = fileData
+			} else {
+				slog.Warn("plugin: failed to read CLI overlay file",
+					"plugin", p.Manifest.Name, "path", absPath, "error", readErr)
+			}
+		}
+	}
+	if err := json.Unmarshal(cliData, &overlay); err != nil {
+		slog.Warn("plugin: failed to parse CLI overlay for stdio server",
+			"plugin", p.Manifest.Name, "server", sc.Key, "error", err)
+	}
+	if overlay.ID == "" {
+		overlay.ID = serverID
+	}
+	if overlay.Command == "" {
+		overlay.Command = serverID
+	}
+	return overlay
+}
+
+// toolsToDetails converts discovered ToolDescriptors to the DetailTool map
+// shape expected by compat.BuildDynamicCommands (keyed by overlay ID).
+// Returns nil if tools is empty.
+func toolsToDetails(tools []transport.ToolDescriptor, overlayID string) map[string][]market.DetailTool {
+	if len(tools) == 0 {
+		return nil
+	}
+	detailTools := make([]market.DetailTool, 0, len(tools))
+	for _, tool := range tools {
+		schemaJSON := ""
+		if tool.InputSchema != nil {
+			if data, marshalErr := json.Marshal(tool.InputSchema); marshalErr == nil {
+				schemaJSON = string(data)
+			}
+		}
+		detailTools = append(detailTools, market.DetailTool{
+			ToolName:    tool.Name,
+			ToolTitle:   tool.Title,
+			ToolDesc:    tool.Description,
+			IsSensitive: tool.Sensitive,
+			ToolRequest: schemaJSON,
+		})
+	}
+	return map[string][]market.DetailTool{overlayID: detailTools}
+}
+
+// registerStdioServerFromOverlay builds cobra commands for a stdio plugin
+// server using only its manifest + overlay.json — no subprocess required.
+//
+// Returns (cmds, descriptor, true) when the overlay carries toolOverrides,
+// otherwise (nil, zero, false) so the caller can fall back to discovery-first
+// registration (legacy path).
+//
+// When a warm tools cache exists for this server, its DetailTools are passed
+// to BuildDynamicCommands so flag types are enriched from the last successful
+// discovery. Fresh installs (or evicted caches) get overlay-declared flags
+// only; the next startup after a successful refresh picks up the full schema.
+func registerStdioServerFromOverlay(
+	p *plugin.Plugin,
+	sc plugin.StdioServerClient,
+	runner executor.Runner,
+	store *cache.Store,
+) ([]*cobra.Command, market.ServerDescriptor, bool) {
+	overlay := resolveStdioOverlay(p, sc)
+	if len(overlay.ToolOverrides) == 0 {
+		return nil, market.ServerDescriptor{}, false
+	}
+
+	descriptor := market.ServerDescriptor{
+		Key:         sc.Key,
+		DisplayName: p.Manifest.Name + "/" + sc.Key,
+		Description: p.Manifest.Description,
+		Endpoint:    StdioEndpoint(p.Manifest.Name, sc.Key),
+		Source:      "plugin",
+		CLI:         overlay,
+		HasCLIMeta:  true,
+	}
+
+	AppendDynamicServer(descriptor)
+	RegisterStdioClient(p.Manifest.Name+"/"+sc.Key, sc.Client)
+
+	// Warm-cache enrichment: if a prior successful discovery wrote a
+	// non-empty tool list, use its schema to enrich flag types.
+	var detailsByID map[string][]market.DetailTool
+	if store != nil {
+		cacheKey := pluginCacheKey(p.Manifest.Name, sc.Key)
+		if snapshot, _, err := store.LoadTools(config.DefaultPartition, cacheKey); err == nil && len(snapshot.Tools) > 0 {
+			detailsByID = toolsToDetails(snapshot.Tools, overlay.ID)
+		}
+	}
+
+	cmds := compat.BuildDynamicCommands(
+		[]market.ServerDescriptor{descriptor}, runner, detailsByID)
+
+	slog.Debug("plugin: stdio server registered from overlay",
+		"plugin", p.Manifest.Name, "server", sc.Key,
+		"toolOverrides", len(overlay.ToolOverrides),
+		"commands", len(cmds),
+		"enriched", detailsByID != nil)
+
+	return cmds, descriptor, true
+}
+
+// refreshStdioToolsCache performs Initialize + ListTools on a stdio plugin
+// subprocess and persists the result so the next startup can enrich
+// overlay-registered commands with typed flags. It never constructs cobra
+// commands; command registration has already happened synchronously from
+// the overlay before this function runs.
+//
+// On failure (subprocess not ready, RPC timeout, empty tool list) it skips
+// SaveTools entirely so a transient error cannot poison the warm cache
+// with a null-tools snapshot.
+func refreshStdioToolsCache(
+	p *plugin.Plugin,
+	sc plugin.StdioServerClient,
+	store *cache.Store,
+	timeouts pluginColdTimeouts,
+) {
+	if store == nil {
+		return
+	}
+	tools := discoverStdioTools(p, sc, timeouts)
+	if len(tools) == 0 {
+		slog.Debug("plugin: stdio cache refresh skipped (no tools)",
+			"plugin", p.Manifest.Name, "server", sc.Key)
+		return
+	}
+	cacheKey := pluginCacheKey(p.Manifest.Name, sc.Key)
+	if err := store.SaveTools(config.DefaultPartition, cacheKey, cache.ToolsSnapshot{
+		ServerKey: cacheKey,
+		Tools:     tools,
+	}); err != nil {
+		slog.Warn("plugin: failed to persist stdio tools cache",
+			"plugin", p.Manifest.Name, "server", sc.Key, "error", err)
+		return
+	}
+	slog.Debug("plugin: stdio tools cache refreshed",
+		"plugin", p.Manifest.Name, "server", sc.Key, "tools", len(tools))
+}
+
+// hasOverlayToolOverrides reports whether a stdio plugin server carries
+// enough CLI metadata to be registered via the overlay-first path. Used by
+// loadPlugins to split entries into overlay-first vs. legacy discovery-first
+// buckets without doing the overlay parse twice.
+func hasOverlayToolOverrides(p *plugin.Plugin, sc plugin.StdioServerClient) bool {
+	return len(resolveStdioOverlay(p, sc).ToolOverrides) > 0
+}

internal/app/plugin_stdio_overlay_test.go

@@ -0,0 +1,398 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cache"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/spf13/cobra"
+)
+
+// withCleanStdioRegistry snapshots and restores the package-level stdio
+// client registry so tests that call RegisterStdioClient don't leak state
+// across cases.
+func withCleanStdioRegistry(t *testing.T) {
+	t.Helper()
+	stdioMu.Lock()
+	prev := stdioClients
+	stdioClients = make(map[string]*transport.StdioClient)
+	stdioMu.Unlock()
+	t.Cleanup(func() {
+		stdioMu.Lock()
+		stdioClients = prev
+		stdioMu.Unlock()
+	})
+}
+
+// newOverlayFixture constructs a plugin + stdio entry carrying an inline
+// CLIOverlay with the given tool-override map. The stdio client is created
+// but never started, since the overlay-first path does not require the
+// subprocess to be running for command registration.
+func newOverlayFixture(t *testing.T, pluginName, serverKey string, overlay market.CLIOverlay) (*plugin.Plugin, plugin.StdioServerClient) {
+	t.Helper()
+	raw, err := json.Marshal(overlay)
+	if err != nil {
+		t.Fatalf("marshal overlay: %v", err)
+	}
+	p := &plugin.Plugin{
+		Manifest: plugin.Manifest{
+			Name:        pluginName,
+			Version:     "1.0.0",
+			Description: pluginName + " plugin",
+			MCPServers: map[string]*plugin.MCPServer{
+				serverKey: {
+					Type:    "stdio",
+					Command: "/usr/bin/true", // never executed by overlay-first path
+					CLI:     raw,
+				},
+			},
+		},
+		Root: t.TempDir(),
+	}
+	sc := plugin.StdioServerClient{
+		Key:    serverKey,
+		Client: transport.NewStdioClient("/usr/bin/true", nil, nil),
+	}
+	return p, sc
+}
+
+// TestRegisterStdioServerFromOverlay_NoDiscoveryStillBuildsCommands verifies
+// the core promise of the overlay-first path: when overlay.json ships
+// ToolOverrides, commands appear immediately — no subprocess probe.
+func TestRegisterStdioServerFromOverlay_NoDiscoveryStillBuildsCommands(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	withCleanStdioRegistry(t)
+
+	overlay := market.CLIOverlay{
+		ID:      "conference-local",
+		Command: "conference-local",
+		Groups: map[string]market.CLIGroupDef{
+			"meeting": {Description: "会议控制"},
+			"member":  {Description: "成员管理"},
+		},
+		ToolOverrides: map[string]market.CLIToolOverride{
+			"create_meeting": {CLIName: "create", Group: "meeting", Description: "Create a meeting"},
+			"end_meeting":    {CLIName: "end", Group: "meeting", Description: "End a meeting"},
+			"mute_member":    {CLIName: "mute", Group: "member", Description: "Mute a member"},
+		},
+	}
+	p, sc := newOverlayFixture(t, "conference-local", "conference-local", overlay)
+
+	store := cache.NewStore(t.TempDir())
+	cmds, desc, ok := registerStdioServerFromOverlay(p, sc, executor.EchoRunner{}, store)
+	if !ok {
+		t.Fatal("registerStdioServerFromOverlay returned ok=false, want true")
+	}
+	if len(cmds) == 0 {
+		t.Fatal("registerStdioServerFromOverlay returned 0 commands, want >=1")
+	}
+
+	var root *struct{ name, path string }
+	_ = root
+	found := false
+	for _, c := range cmds {
+		if c.Name() == "conference-local" {
+			found = true
+			// Groups must be attached as sub-commands.
+			groups := map[string]bool{}
+			for _, sub := range c.Commands() {
+				groups[sub.Name()] = true
+			}
+			if !groups["meeting"] {
+				t.Errorf("missing 'meeting' group sub-command, children = %v", groups)
+			}
+			if !groups["member"] {
+				t.Errorf("missing 'member' group sub-command, children = %v", groups)
+			}
+		}
+	}
+	if !found {
+		names := []string{}
+		for _, c := range cmds {
+			names = append(names, c.Name())
+		}
+		t.Fatalf("missing top-level 'conference-local' command, got %v", names)
+	}
+
+	// AppendDynamicServer registration: product ID should land in
+	// DirectRuntimeProductIDs so hideNonDirectRuntimeCommands keeps it
+	// visible even under a restrictive VisibleProducts hook.
+	if !DirectRuntimeProductIDs()["conference-local"] {
+		t.Error("DirectRuntimeProductIDs missing 'conference-local'")
+	}
+
+	// RegisterStdioClient side-effect: the runtime must be able to look up
+	// the StdioClient when the endpoint is invoked later.
+	if _, ok := LookupStdioClient("conference-local/conference-local"); !ok {
+		t.Error("LookupStdioClient missing conference-local/conference-local")
+	}
+
+	if desc.Endpoint != StdioEndpoint("conference-local", "conference-local") {
+		t.Errorf("descriptor.Endpoint = %q, want %q", desc.Endpoint, StdioEndpoint("conference-local", "conference-local"))
+	}
+}
+
+// TestRegisterStdioServerFromOverlay_WarmCacheEnrichesFlags pre-populates the
+// tools cache with a schema-bearing DetailTool and asserts the resulting
+// leaf command picks up the typed flag derived from InputSchema.
+func TestRegisterStdioServerFromOverlay_WarmCacheEnrichesFlags(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	withCleanStdioRegistry(t)
+
+	overlay := market.CLIOverlay{
+		ID:      "cache-plugin",
+		Command: "cache-plugin",
+		ToolOverrides: map[string]market.CLIToolOverride{
+			"echo": {CLIName: "echo", Description: "Echo input"},
+		},
+	}
+	p, sc := newOverlayFixture(t, "cache-plugin", "cache-plugin", overlay)
+
+	store := cache.NewStore(t.TempDir())
+	cacheKey := pluginCacheKey(p.Manifest.Name, sc.Key)
+	if err := store.SaveTools(config.DefaultPartition, cacheKey, cache.ToolsSnapshot{
+		SavedAt:   time.Now().UTC(),
+		ServerKey: cacheKey,
+		Tools: []transport.ToolDescriptor{
+			{
+				Name:        "echo",
+				Description: "Echo the input",
+				InputSchema: map[string]any{
+					"type": "object",
+					"properties": map[string]any{
+						"message": map[string]any{"type": "string"},
+					},
+					"required": []any{"message"},
+				},
+			},
+		},
+	}); err != nil {
+		t.Fatalf("SaveTools: %v", err)
+	}
+
+	cmds, _, ok := registerStdioServerFromOverlay(p, sc, executor.EchoRunner{}, store)
+	if !ok || len(cmds) == 0 {
+		t.Fatalf("overlay registration failed: ok=%v cmds=%d", ok, len(cmds))
+	}
+
+	var echoLeaf *leafMatch
+	for _, top := range cmds {
+		if top.Name() != "cache-plugin" {
+			continue
+		}
+		for _, sub := range top.Commands() {
+			if sub.Name() == "echo" {
+				echoLeaf = &leafMatch{name: sub.Name(), hasFlag: sub.Flags().Lookup("message") != nil}
+			}
+		}
+	}
+	if echoLeaf == nil {
+		t.Fatal("missing 'echo' leaf command under 'cache-plugin'")
+	}
+	if !echoLeaf.hasFlag {
+		t.Error("warm-cache enrichment did not wire --message flag from InputSchema")
+	}
+}
+
+type leafMatch struct {
+	name    string
+	hasFlag bool
+}
+
+// TestRegisterStdioServerFromOverlay_OverlayWithoutOverridesReturnsFalse
+// asserts the fallback contract: when overlay.json is missing toolOverrides,
+// the overlay-first path declines so the caller can route the entry through
+// the legacy discovery-first registerStdioServer.
+func TestRegisterStdioServerFromOverlay_OverlayWithoutOverridesReturnsFalse(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	withCleanStdioRegistry(t)
+
+	// Overlay with no ToolOverrides (simulates a plugin that relies entirely
+	// on runtime discovery for its tool list).
+	overlay := market.CLIOverlay{
+		ID:      "legacy-plugin",
+		Command: "legacy-plugin",
+	}
+	p, sc := newOverlayFixture(t, "legacy-plugin", "legacy-plugin", overlay)
+
+	store := cache.NewStore(t.TempDir())
+	cmds, _, ok := registerStdioServerFromOverlay(p, sc, executor.EchoRunner{}, store)
+	if ok {
+		t.Errorf("registerStdioServerFromOverlay ok=true for empty toolOverrides; want false")
+	}
+	if cmds != nil {
+		t.Errorf("cmds = %v, want nil", cmds)
+	}
+	if DirectRuntimeProductIDs()["legacy-plugin"] {
+		t.Error("legacy-plugin must NOT be appended to dynamic registry in fallback case")
+	}
+	if _, found := LookupStdioClient("legacy-plugin/legacy-plugin"); found {
+		t.Error("stdio client must NOT be registered in fallback case")
+	}
+}
+
+// TestRefreshStdioToolsCache_FailurePreservesCache guards against the
+// "negative cache poisoning" bug: if discovery fails (subprocess not ready,
+// timeout, empty tool list), the existing warm cache must remain intact so
+// the next startup still enriches flags from the last good snapshot.
+func TestRefreshStdioToolsCache_FailurePreservesCache(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	withCleanStdioRegistry(t)
+
+	p, sc := newOverlayFixture(t, "refresh-plugin", "refresh-plugin", market.CLIOverlay{
+		ID:      "refresh-plugin",
+		Command: "refresh-plugin",
+	})
+
+	store := cache.NewStore(t.TempDir())
+	cacheKey := pluginCacheKey(p.Manifest.Name, sc.Key)
+	goodSnapshot := cache.ToolsSnapshot{
+		SavedAt:   time.Now().UTC(),
+		ServerKey: cacheKey,
+		Tools: []transport.ToolDescriptor{
+			{
+				Name:        "ping",
+				Description: "Health check",
+				InputSchema: map[string]any{"type": "object"},
+			},
+		},
+	}
+	if err := store.SaveTools(config.DefaultPartition, cacheKey, goodSnapshot); err != nil {
+		t.Fatalf("seed SaveTools: %v", err)
+	}
+
+	// /usr/bin/true exits immediately, so Initialize + ListTools will fail
+	// (no MCP handshake). discoverStdioTools returns nil → refresh must be
+	// a no-op and must NOT overwrite the good cache with a null snapshot.
+	refreshStdioToolsCache(p, sc, store, pluginColdTimeouts{stdio: 200 * time.Millisecond})
+
+	got, _, err := store.LoadTools(config.DefaultPartition, cacheKey)
+	if err != nil {
+		t.Fatalf("LoadTools after failed refresh: %v", err)
+	}
+	if len(got.Tools) != 1 || got.Tools[0].Name != "ping" {
+		t.Errorf("warm cache was overwritten by failed refresh: %+v", got.Tools)
+	}
+}
+
+// TestLoadPlugins_OverlayFirstVisibleBeforeDiscovery is an integration-style
+// test for the loadPlugins split decision: stdio plugins whose overlay ships
+// ToolOverrides must have their commands visible on the root immediately,
+// WITHOUT waiting on any discovery handshake. It drives the same sequence
+// loadPlugins uses (registerStdioServerFromOverlay → root.AddCommand →
+// hideNonDirectRuntimeCommands) and asserts the plugin command survives the
+// visibility filter even when no discovery has run.
+func TestLoadPlugins_OverlayFirstVisibleBeforeDiscovery(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	withCleanStdioRegistry(t)
+
+	// Simulate a wukong-like edition that declares a static VisibleProducts
+	// whitelist NOT containing our plugin. This is the exact scenario where
+	// the original bug surfaced.
+	overrideVisibleProducts(t, []string{"calendar", "doc"})
+
+	overlay := market.CLIOverlay{
+		ID:      "conference-local",
+		Command: "conference-local",
+		ToolOverrides: map[string]market.CLIToolOverride{
+			"create_meeting": {CLIName: "create", Description: "Create a meeting"},
+		},
+	}
+	p, sc := newOverlayFixture(t, "conference-local", "conference-local", overlay)
+
+	// No discovery runs — no cache seeded. This mirrors a cold-start where
+	// the subprocess is unavailable (or just slow) yet the user expects
+	// `dws --help` to still list the plugin.
+	store := cache.NewStore(t.TempDir())
+	cmds, _, ok := registerStdioServerFromOverlay(p, sc, executor.EchoRunner{}, store)
+	if !ok {
+		t.Fatal("registerStdioServerFromOverlay returned ok=false")
+	}
+
+	root := &cobra.Command{Use: "dws"}
+	// Also add a sibling command that is NOT a registered product so we can
+	// prove the visibility filter still hides non-product commands.
+	bogus := &cobra.Command{Use: "bogus-not-a-product"}
+	root.AddCommand(bogus)
+	for _, c := range cmds {
+		root.AddCommand(c)
+	}
+
+	hideNonDirectRuntimeCommands(root)
+
+	var pluginCmd *cobra.Command
+	for _, c := range root.Commands() {
+		if c.Name() == "conference-local" {
+			pluginCmd = c
+		}
+	}
+	if pluginCmd == nil {
+		t.Fatal("conference-local missing from root after overlay-first registration")
+	}
+	if pluginCmd.Hidden {
+		t.Error("conference-local must stay visible (Hidden=false) after hideNonDirectRuntimeCommands")
+	}
+	if !bogus.Hidden {
+		t.Error("bogus-not-a-product must be hidden by the visibility filter")
+	}
+
+	services := visibleMCPRootCommands(root)
+	if !containsCommand(services, "conference-local") {
+		t.Errorf("visibleMCPRootCommands missing conference-local: %v", commandNames(services))
+	}
+}
+
+// TestHasOverlayToolOverrides exercises the split-decision helper used by
+// loadPlugins to route stdio entries to overlay-first vs. legacy buckets.
+func TestHasOverlayToolOverrides(t *testing.T) {
+	cases := []struct {
+		name    string
+		overlay market.CLIOverlay
+		want    bool
+	}{
+		{
+			name:    "empty overlay",
+			overlay: market.CLIOverlay{ID: "x", Command: "x"},
+			want:    false,
+		},
+		{
+			name: "overlay with overrides",
+			overlay: market.CLIOverlay{
+				ID:      "x",
+				Command: "x",
+				ToolOverrides: map[string]market.CLIToolOverride{
+					"foo": {CLIName: "foo"},
+				},
+			},
+			want: true,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			p, sc := newOverlayFixture(t, "x", "x", tc.overlay)
+			got := hasOverlayToolOverrides(p, sc)
+			if got != tc.want {
+				t.Errorf("hasOverlayToolOverrides = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}

internal/app/root.go

@@ -420,20 +420,25 @@ func newCacheCommand() *cobra.Command {
 			if err != nil {
 				return apperrors.NewInternal("failed to read cache refresh flags")
 			}
-			baseURL := DiscoveryBaseURL()
 
 			store := cacheStoreFromEnv()
 			transportClient := transport.NewClient(nil)
 			transportClient.AuthToken = resolveRuntimeAuthToken(cmd.Context(), "")
+			// Market client here is only a fallback for Detail API calls inside
+			// DiscoverAllRuntime; the primary server-list fetch below goes
+			// through fetchRegistryServers so edition DiscoveryURL wins.
 			service := discovery.NewService(
-				market.NewClient(baseURL, nil),
+				market.NewClient(DiscoveryBaseURL(), nil),
 				transportClient,
 				store,
 			)
-			servers, err := service.DiscoverServers(cmd.Context())
+
+			resp, err := fetchRegistryServers(cmd.Context(), ipv4HTTPClient(config.HTTPTimeout))
 			if err != nil {
-				return err
+				return apperrors.NewDiscovery(fmt.Sprintf("cache refresh: fetch server list failed: %v", err))
 			}
+			servers := market.NormalizeServers(resp, "live_market")
+			_ = store.SaveRegistry(service.CachePartition(), cache.RegistrySnapshot{Servers: servers})
 
 			selected := selectServersForProduct(servers, product)
 			if strings.TrimSpace(product) != "" && len(selected) == 0 {
@@ -650,16 +655,7 @@ func newMCPCommand(ctx context.Context, loader cli.CatalogLoader, runner executo
 // Public utility commands (auth, cache, completion, version) are always kept
 // visible; explicitly hidden commands stay hidden.
 func hideNonDirectRuntimeCommands(root *cobra.Command) {
-	var allowedProducts map[string]bool
-	if fn := edition.Get().VisibleProducts; fn != nil {
-		products := fn()
-		allowedProducts = make(map[string]bool, len(products))
-		for _, p := range products {
-			allowedProducts[p] = true
-		}
-	} else {
-		allowedProducts = DirectRuntimeProductIDs()
-	}
+	allowedProducts := resolveVisibleProducts()
 	staticCommands := map[string]bool{
 		"auth":       true,
 		"cache":      true,
@@ -1157,11 +1153,31 @@ func loadPlugins(engine *pipeline.Engine, runner executor.Runner) []*cobra.Comma
 	sharedStore := cacheStoreFromEnv()
 	coldTimeouts := resolvePluginColdTimeouts()
 
-	// Fan out HTTP and stdio discovery in parallel. Each goroutine resolves
-	// its cache hit locally (no network) or runs a bounded cold-path probe.
-	// Wall-clock cost ≈ max(individual plugin latencies), not the sum.
+	// Phase A: stdio overlay-first registration (synchronous, no I/O).
+	// Plugins whose overlay.json declares ToolOverrides register their full
+	// command tree up-front from manifest metadata alone — no subprocess
+	// handshake required. This fixes the "discovery fails → no commands
+	// ever appear" lock-out and keeps `dws --help` reliable even when the
+	// underlying MCP server is temporarily unavailable.
+	var legacyStdioEntries []stdioEntry
+	for _, e := range stdioEntries {
+		cmds, _, ok := registerStdioServerFromOverlay(e.plugin, e.sc, runner, sharedStore)
+		if !ok {
+			legacyStdioEntries = append(legacyStdioEntries, e)
+			continue
+		}
+		pluginCmds = append(pluginCmds, cmds...)
+	}
+
+	// Phase B: fan out discovery in parallel.
+	//   - HTTP plugins: same behaviour as before (discovery-first).
+	//   - stdio overlay-first plugins: async cache refresh only; their
+	//     commands are already registered. Failures are non-fatal and do
+	//     NOT poison the warm-cache with a null-tools snapshot.
+	//   - stdio legacy plugins (overlay without toolOverrides): preserve
+	//     the old discovery-first path for backwards compatibility.
 	httpResults := make([][]*cobra.Command, len(httpServers))
-	stdioResults := make([][]*cobra.Command, len(stdioEntries))
+	legacyStdioResults := make([][]*cobra.Command, len(legacyStdioEntries))
 	var wg sync.WaitGroup
 	for i, ps := range httpServers {
 		wg.Add(1)
@@ -1170,18 +1186,30 @@ func loadPlugins(engine *pipeline.Engine, runner executor.Runner) []*cobra.Comma
 			httpResults[idx] = registerHTTPServer(ps.plugin, ps.srv, tc, runner, sharedStore, coldTimeouts)
 		}(i, ps)
 	}
-	for i, e := range stdioEntries {
+	// overlay-first stdio: async refresh (no command building here).
+	for _, e := range stdioEntries {
+		if !hasOverlayToolOverrides(e.plugin, e.sc) {
+			continue
+		}
+		wg.Add(1)
+		go func(e stdioEntry) {
+			defer wg.Done()
+			refreshStdioToolsCache(e.plugin, e.sc, sharedStore, coldTimeouts)
+		}(e)
+	}
+	// legacy stdio: discovery-first (commands depend on tool list).
+	for i, e := range legacyStdioEntries {
 		wg.Add(1)
 		go func(idx int, e stdioEntry) {
 			defer wg.Done()
-			stdioResults[idx] = registerStdioServer(e.plugin, e.sc, runner, sharedStore, coldTimeouts)
+			legacyStdioResults[idx] = registerStdioServer(e.plugin, e.sc, runner, sharedStore, coldTimeouts)
 		}(i, e)
 	}
 	wg.Wait()
 	for _, cmds := range httpResults {
 		pluginCmds = append(pluginCmds, cmds...)
 	}
-	for _, cmds := range stdioResults {
+	for _, cmds := range legacyStdioResults {
 		pluginCmds = append(pluginCmds, cmds...)
 	}
 
@@ -1467,6 +1495,11 @@ func discoverStdioTools(p *plugin.Plugin, sc plugin.StdioServerClient, timeouts
 // buildStdioCommands constructs Cobra commands from a tool list and
 // registers the runtime dispatch state (StdioClient + dynamic server).
 // Returns nil for an empty tool list.
+//
+// This is the legacy discovery-first path, used only for stdio plugins whose
+// overlay.json does NOT carry toolOverrides. Plugins that ship toolOverrides
+// register commands up-front via registerStdioServerFromOverlay, bypassing
+// this function entirely (see plugin_stdio_overlay.go).
 func buildStdioCommands(p *plugin.Plugin, sc plugin.StdioServerClient, tools []transport.ToolDescriptor, runner executor.Runner) []*cobra.Command {
 	if len(tools) == 0 {
 		slog.Debug("plugin: stdio server has no tools",
@@ -1474,44 +1507,14 @@ func buildStdioCommands(p *plugin.Plugin, sc plugin.StdioServerClient, tools []t
 		return nil
 	}
 
-	// Build CLIOverlay: use manifest CLI metadata if present, else auto-generate.
-	serverID := sc.Key
-	overlay := market.CLIOverlay{
-		ID:      serverID,
-		Command: serverID,
-	}
-	if srv, ok := p.Manifest.MCPServers[sc.Key]; ok && len(srv.CLI) > 0 {
-		cliData := srv.CLI
-		// If cli is a JSON string, treat it as a relative file path to an overlay file.
-		if len(cliData) > 0 && cliData[0] == '"' {
-			var cliPath string
-			if err := json.Unmarshal(cliData, &cliPath); err == nil && cliPath != "" {
-				absPath := filepath.Join(p.Root, cliPath)
-				if fileData, readErr := os.ReadFile(absPath); readErr == nil {
-					cliData = fileData
-				} else {
-					slog.Warn("plugin: failed to read CLI overlay file",
-						"plugin", p.Manifest.Name, "path", absPath, "error", readErr)
-				}
-			}
-		}
-		if err := json.Unmarshal(cliData, &overlay); err != nil {
-			slog.Warn("plugin: failed to parse CLI overlay for stdio server",
-				"plugin", p.Manifest.Name, "server", sc.Key, "error", err)
-		}
-		if overlay.ID == "" {
-			overlay.ID = serverID
-		}
-		if overlay.Command == "" {
-			overlay.Command = serverID
-		}
-	}
+	overlay := resolveStdioOverlay(p, sc)
 
-	// Auto-generate ToolOverrides from discovered tools when not provided.
+	// Auto-generate ToolOverrides from discovered tools when not provided
+	// by the manifest/overlay (legacy discovery-first path).
 	if len(overlay.ToolOverrides) == 0 {
 		overlay.ToolOverrides = make(map[string]market.CLIToolOverride)
 		if len(overlay.Prefixes) == 0 {
-			overlay.Prefixes = []string{serverID}
+			overlay.Prefixes = []string{overlay.ID}
 		}
 		for _, tool := range tools {
 			overlay.ToolOverrides[tool.Name] = market.CLIToolOverride{
@@ -1520,43 +1523,20 @@ func buildStdioCommands(p *plugin.Plugin, sc plugin.StdioServerClient, tools []t
 		}
 	}
 
-	// Construct virtual endpoint and server descriptor.
-	endpoint := StdioEndpoint(p.Manifest.Name, sc.Key)
-
 	descriptor := market.ServerDescriptor{
 		Key:         sc.Key,
 		DisplayName: p.Manifest.Name + "/" + sc.Key,
 		Description: p.Manifest.Description,
-		Endpoint:    endpoint,
+		Endpoint:    StdioEndpoint(p.Manifest.Name, sc.Key),
 		Source:      "plugin",
 		CLI:         overlay,
 		HasCLIMeta:  true,
 	}
 
 	AppendDynamicServer(descriptor)
-	// Register with pluginName/serverKey format for cleanup by plugin name
-	RegisterStdioClient(p.Manifest.Name+"/"+serverID, sc.Client)
-
-	// Convert tool descriptors to DetailTool entries for flag generation.
-	detailsByID := make(map[string][]market.DetailTool)
-	var detailTools []market.DetailTool
-	for _, tool := range tools {
-		schemaJSON := ""
-		if tool.InputSchema != nil {
-			if data, marshalErr := json.Marshal(tool.InputSchema); marshalErr == nil {
-				schemaJSON = string(data)
-			}
-		}
-		detailTools = append(detailTools, market.DetailTool{
-			ToolName:    tool.Name,
-			ToolTitle:   tool.Title,
-			ToolDesc:    tool.Description,
-			IsSensitive: tool.Sensitive,
-			ToolRequest: schemaJSON,
-		})
-	}
-	detailsByID[serverID] = detailTools
+	RegisterStdioClient(p.Manifest.Name+"/"+sc.Key, sc.Client)
 
+	detailsByID := toolsToDetails(tools, overlay.ID)
 	cmds := compat.BuildDynamicCommands(
 		[]market.ServerDescriptor{descriptor}, runner, detailsByID)
 

internal/app/root_cache_refresh_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
 func TestCacheRefreshClearsExistingCachesAndSkipsCLISkippedServers(t *testing.T) {
@@ -106,6 +107,98 @@ func TestCacheRefreshClearsExistingCachesAndSkipsCLISkippedServers(t *testing.T)
 	}
 }
 
+// TestCacheRefreshHonorsEditionDiscoveryURL asserts the `dws cache refresh`
+// command routes its server-list fetch through edition.Hooks.DiscoveryURL /
+// DiscoveryHeaders when they are set, instead of the default Market endpoint.
+// Kept deliberately generic (no edition-specific strings) — concrete values
+// belong to the overlay repo that installs the hooks, not to this open core.
+func TestCacheRefreshHonorsEditionDiscoveryURL(t *testing.T) {
+	cacheDir := t.TempDir()
+	t.Setenv(cli.CacheDirEnv, cacheDir)
+
+	var (
+		editionHits atomic.Int32
+		marketHits  atomic.Int32
+		gotHeaders  atomic.Value // map[string]string
+	)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/cli/edition/apis":
+			editionHits.Add(1)
+			snapshot := map[string]string{
+				"x-test-edition": r.Header.Get("x-test-edition"),
+				"x-test-client":  r.Header.Get("x-test-client"),
+			}
+			gotHeaders.Store(snapshot)
+			_ = json.NewEncoder(w).Encode(market.ListResponse{
+				Metadata: market.ListMetadata{Count: 1},
+				Servers: []market.ServerEnvelope{
+					{
+						Server: market.RegistryServer{
+							Name:    "Edition Service",
+							Remotes: []market.RegistryRemote{{Type: "streamable-http", URL: "https://example.invalid/mcp"}},
+						},
+						Meta: market.EnvelopeMeta{
+							Registry: market.RegistryMetadata{Status: "active"},
+							CLI:      market.CLIOverlay{ID: "edition-service", Command: "edition-service"},
+						},
+					},
+				},
+			})
+		case "/cli/discovery/apis":
+			marketHits.Add(1)
+			http.Error(w, "market endpoint must not be called when edition DiscoveryURL is set", http.StatusNotFound)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+
+	edition.Override(&edition.Hooks{
+		Name:         "testing",
+		DiscoveryURL: srv.URL + "/cli/edition/apis",
+		DiscoveryHeaders: func() map[string]string {
+			return map[string]string{
+				"x-test-edition": "custom",
+				"x-test-client":  "cli-refresh",
+			}
+		},
+	})
+	t.Cleanup(func() { edition.Override(&edition.Hooks{}) })
+
+	SetDiscoveryBaseURL(srv.URL)
+	t.Cleanup(func() { SetDiscoveryBaseURL("") })
+
+	cmd := newCacheCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"refresh"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	if got := editionHits.Load(); got != 1 {
+		t.Fatalf("edition DiscoveryURL hits = %d, want 1", got)
+	}
+	if got := marketHits.Load(); got != 0 {
+		t.Fatalf("market endpoint hits = %d, want 0 (edition DiscoveryURL must take precedence)", got)
+	}
+
+	headers, _ := gotHeaders.Load().(map[string]string)
+	if headers == nil {
+		t.Fatal("captured request headers = nil, want edition DiscoveryHeaders to be applied")
+	}
+	if headers["x-test-edition"] != "custom" {
+		t.Fatalf("x-test-edition header = %q, want %q", headers["x-test-edition"], "custom")
+	}
+	if headers["x-test-client"] != "cli-refresh" {
+		t.Fatalf("x-test-client header = %q, want %q", headers["x-test-client"], "cli-refresh")
+	}
+}
+
 func saveCLIIDDetail(t *testing.T, store *cache.Store, partition, cliID string) {
 	t.Helper()
 

internal/app/root_help.go

@@ -84,21 +84,30 @@ func renderRootHelp(root *cobra.Command) {
 	_, _ = fmt.Fprintln(w, `Use "dws <service> --help" for more information about a discovered MCP service or "dws <command> --help" for utility commands.`)
 }
 
+// resolveVisibleProducts returns the set of top-level product IDs that should
+// be treated as visible. It unions the edition's VisibleProducts hook (when
+// set) with DirectRuntimeProductIDs(), so dynamically-registered products —
+// including plugins loaded via AppendDynamicServer — are never silently hidden
+// by a static VisibleProducts list.
+func resolveVisibleProducts() map[string]bool {
+	allowed := map[string]bool{}
+	if fn := edition.Get().VisibleProducts; fn != nil {
+		for _, p := range fn() {
+			allowed[p] = true
+		}
+	}
+	for id := range DirectRuntimeProductIDs() {
+		allowed[id] = true
+	}
+	return allowed
+}
+
 func visibleMCPRootCommands(root *cobra.Command) []*cobra.Command {
 	if root == nil {
 		return nil
 	}
 
-	var allowed map[string]bool
-	if fn := edition.Get().VisibleProducts; fn != nil {
-		products := fn()
-		allowed = make(map[string]bool, len(products))
-		for _, p := range products {
-			allowed[p] = true
-		}
-	} else {
-		allowed = DirectRuntimeProductIDs()
-	}
+	allowed := resolveVisibleProducts()
 	if len(allowed) == 0 {
 		return nil
 	}
@@ -121,13 +130,7 @@ func visibleUtilityRootCommands(root *cobra.Command) []*cobra.Command {
 		return nil
 	}
 
-	productCommands := DirectRuntimeProductIDs()
-	if fn := edition.Get().VisibleProducts; fn != nil {
-		productCommands = make(map[string]bool, len(fn()))
-		for _, product := range fn() {
-			productCommands[product] = true
-		}
-	}
+	productCommands := resolveVisibleProducts()
 
 	commands := make([]*cobra.Command, 0)
 	for _, cmd := range root.Commands() {

internal/app/runner.go

@@ -168,10 +168,10 @@ func (r *runtimeRunner) Run(ctx context.Context, invocation executor.Invocation)
 
 	product, ok := catalog.FindProduct(invocation.CanonicalProduct)
 	if !ok || strings.TrimSpace(product.Endpoint) == "" {
-		return r.fallback.Run(ctx, invocation)
+		return r.handleCatalogMiss(ctx, invocation, "product missing from discovery catalog and no supplement/env override")
 	}
 	if _, ok := product.FindTool(invocation.Tool); !ok {
-		return r.fallback.Run(ctx, invocation)
+		return r.handleCatalogMiss(ctx, invocation, fmt.Sprintf("tool %q not declared by product %q in discovery catalog", invocation.Tool, invocation.CanonicalProduct))
 	}
 	if r.globalFlags != nil && r.globalFlags.DryRun {
 		invocation.DryRun = true
@@ -184,6 +184,37 @@ func (r *runtimeRunner) Run(ctx context.Context, invocation executor.Invocation)
 	return r.executeInvocation(ctx, endpoint, invocation)
 }
 
+// handleCatalogMiss decides what to do when discovery catalog does not cover the
+// requested product / tool and no `directRuntimeEndpoint` match fired earlier.
+//
+// Previously every catalog miss silently fell through to EchoRunner, which
+// returns an empty `executor.Result{Response: nil}`. The helper-invocation
+// adapter then converted that into `&edition.ToolResult{}`, whose `Content`
+// marshals to `null`, surfacing as `{"Content": null}` at the CLI. Users had no
+// signal that endpoint resolution failed — see the fix-wukong-discovery-missing-servers plan (Phase 3) for the full trace.
+//
+// New contract:
+//   - Dry-run (invocation.DryRun or globalFlags.DryRun): keep EchoRunner so
+//     `--dry-run` still prints the planned payload without real execution.
+//   - Otherwise: return an explicit apperrors.NewAPI("endpoint_not_resolved")
+//     with the offending product/tool attached. This fails fast to stderr and
+//     makes missing envelopes / supplement gaps immediately visible.
+func (r *runtimeRunner) handleCatalogMiss(ctx context.Context, invocation executor.Invocation, detail string) (executor.Result, error) {
+	dryRun := invocation.DryRun || (r.globalFlags != nil && r.globalFlags.DryRun)
+	if dryRun {
+		invocation.DryRun = true
+		return r.fallback.Run(ctx, invocation)
+	}
+	return executor.Result{}, apperrors.NewAPI(
+		fmt.Sprintf("endpoint not resolved for product %q (tool %q): %s", invocation.CanonicalProduct, invocation.Tool, detail),
+		apperrors.WithOperation("discovery.resolve"),
+		apperrors.WithReason("endpoint_not_resolved"),
+		apperrors.WithServerKey(invocation.CanonicalProduct),
+		apperrors.WithHint("产品 envelope 可能未下发到 discovery，或已经被 serverDeps fail-fast 丢弃；可执行 'dws cache refresh' 强制重新 discovery，仍失败请向 Portal 确认 envelope 状态。"),
+		apperrors.WithActions("dws cache refresh"),
+	)
+}
+
 func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string, invocation executor.Invocation) (result executor.Result, retErr error) {
 	// Route stdio:// endpoints to the local StdioClient — no HTTP, no auth.
 	if IsStdioEndpoint(endpoint) {

internal/app/runner_test.go

@@ -26,6 +26,7 @@ import (
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	mockmcp "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/test/mock_mcp"
 )
@@ -33,6 +34,13 @@ import (
 func setupRuntimeCommandTest(t *testing.T) {
 	t.Helper()
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	// Isolate keychain storage so concurrent test packages can't leak a
+	// real auth token into runtime tests via the shared on-disk keychain
+	// location. We deliberately do NOT reset the process-wide token
+	// cache here: getCachedRuntimeToken uses sync.Once and is read by
+	// detached preload goroutines spawned per Run(); replacing the Once
+	// races with those still-running goroutines.
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
 
 	discoverySrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		_ = json.NewEncoder(w).Encode(contactDiscoveryResponse())
@@ -336,7 +344,17 @@ func TestRuntimeRunnerRejectsUnauthenticatedRequest(t *testing.T) {
 	}
 }
 
-func TestRuntimeRunnerFallsBackForUnavailableProduct(t *testing.T) {
+// TestRuntimeRunnerErrorsForUnavailableProduct pins down the post-fix
+// (fix-wukong-discovery-missing-servers Phase 3) behaviour: when the catalog
+// does not carry the requested product (here `contact` against a
+// doc-only fixture), `runtimeRunner.Run` must surface an explicit
+// `endpoint_not_resolved` error instead of silently echoing an empty result
+// back to the user — the latter is what historically produced `{"Content":
+// null}` output on `dws doc list`.
+//
+// Dry-run / compat semantics continue to route through EchoRunner and are
+// covered by other tests in this file (TestRuntime*Dry*, TestCompat*).
+func TestRuntimeRunnerErrorsForUnavailableProduct(t *testing.T) {
 	setupRuntimeCommandTest(t)
 	server := mockmcp.DefaultServer()
 	defer server.Close()
@@ -349,33 +367,16 @@ func TestRuntimeRunnerFallsBackForUnavailableProduct(t *testing.T) {
 	cmd.SetErr(&out)
 	cmd.SetArgs([]string{"-f", "json", "contact", "user", "get-self"})
 
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v", err)
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatalf("Execute() error = nil, want endpoint_not_resolved error\noutput:\n%s", out.String())
 	}
-
-	var payload struct {
-		Invocation struct {
-			Implemented      bool   `json:"implemented"`
-			CanonicalProduct string `json:"canonical_product"`
-			Tool             string `json:"tool"`
-		} `json:"invocation"`
-		Response map[string]any `json:"response"`
+	msg := err.Error()
+	if !strings.Contains(msg, "endpoint not resolved") {
+		t.Fatalf("error message = %q, want it to contain \"endpoint not resolved\"", msg)
 	}
-	if err := json.Unmarshal(out.Bytes(), &payload); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v\noutput:\n%s", err, out.String())
-	}
-
-	if payload.Invocation.Implemented {
-		t.Fatalf("implemented = true, want false for fallback")
-	}
-	if payload.Invocation.CanonicalProduct != "contact" {
-		t.Fatalf("canonical_product = %q, want contact", payload.Invocation.CanonicalProduct)
-	}
-	if payload.Invocation.Tool != "get_current_user_profile" {
-		t.Fatalf("tool = %q, want get_current_user_profile", payload.Invocation.Tool)
-	}
-	if payload.Response != nil {
-		t.Fatalf("response = %#v, want nil for echo fallback", payload.Response)
+	if !strings.Contains(msg, "contact") {
+		t.Fatalf("error message = %q, want it to mention product \"contact\"", msg)
 	}
 }
 

internal/app/testmain_test.go

@@ -0,0 +1,50 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"os"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+)
+
+// TestMain isolates the on-disk keychain storage to a process-wide
+// temporary directory for the entire internal/app test binary.
+//
+// Background: getCachedRuntimeToken caches the auth token via sync.Once
+// for the process lifetime. Whichever test triggers it first locks in the
+// cached value. Several tests in this package (e.g. TestSkillInstallInvalidTarget)
+// call SaveTokenData and then exec a CLI command that triggers Once.Do; if
+// keychain storage points at the developer's real ~/Library/Application
+// Support/dws-cli (or ~/.local/share/dws-cli on Linux), a real token can be
+// written there and cached process-wide, breaking later tests that assume
+// "no auth" — most notably TestRuntimeRunnerRejectsUnauthenticatedRequest.
+//
+// Setting keychain.StorageDirEnv here forces every keychain read/write in
+// this binary into a per-process tempdir, eliminating that contamination
+// without touching production code.
+func TestMain(m *testing.M) {
+	tmpDir, err := os.MkdirTemp("", "dws-app-test-keychain-")
+	if err != nil {
+		panic("create test keychain tempdir: " + err.Error())
+	}
+	if err := os.Setenv(keychain.StorageDirEnv, tmpDir); err != nil {
+		_ = os.RemoveAll(tmpDir)
+		panic("set " + keychain.StorageDirEnv + ": " + err.Error())
+	}
+	code := m.Run()
+	_ = os.RemoveAll(tmpDir)
+	os.Exit(code)
+}

internal/app/tool_caller_adapter.go

@@ -16,6 +16,7 @@ package app
 import (
 	"context"
 	"encoding/json"
+	"log/slog"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -56,6 +57,19 @@ func (a *toolCallerAdapter) DryRun() bool {
 func convertResult(r executor.Result) *edition.ToolResult {
 	resp := r.Response
 	if resp == nil {
+		// After the fix-wukong-discovery-missing-servers Phase 3 change,
+		// runtimeRunner.Run returns an explicit error for catalog misses
+		// instead of an empty Response, so this branch should only be
+		// reachable for unit tests / unexpected runners. Log a warning so
+		// any future regression (silent `{"Content": null}` on the CLI)
+		// leaves a trace in the file logger / stderr.
+		slog.Warn(
+			"tool_caller_adapter: empty runner response — upstream should surface an error instead",
+			"product", r.Invocation.CanonicalProduct,
+			"tool", r.Invocation.Tool,
+			"kind", r.Invocation.Kind,
+			"dry_run", r.Invocation.DryRun,
+		)
 		return &edition.ToolResult{}
 	}
 

internal/app/visibility_test.go

@@ -0,0 +1,125 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+// overrideVisibleProducts temporarily installs an edition hook exposing the
+// given static product list and restores the previous hooks on cleanup.
+func overrideVisibleProducts(t *testing.T, products []string) {
+	t.Helper()
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		VisibleProducts: func() []string { return products },
+	})
+	t.Cleanup(func() { edition.Override(prev) })
+}
+
+// registerPluginProduct simulates a plugin's `AppendDynamicServer` call so
+// the product ID ends up in DirectRuntimeProductIDs() without triggering
+// network discovery.
+func registerPluginProduct(t *testing.T, id, endpoint string) {
+	t.Helper()
+	AppendDynamicServer(market.ServerDescriptor{
+		Endpoint: endpoint,
+		CLI: market.CLIOverlay{
+			ID:      id,
+			Command: id,
+		},
+	})
+}
+
+// TestHideNonDirectRuntimeCommands_PluginVisibleDespiteStaticVisibleProducts
+// is a regression for the dws-wukong plugin-visibility bug: when an edition
+// installs a static VisibleProducts hook (Wukong returns 40 hardcoded product
+// IDs) and a plugin registers a new product via AppendDynamicServer
+// (e.g. `conference-local`), the plugin command must stay visible because the
+// dynamic registry takes precedence over the hook's static whitelist.
+func TestHideNonDirectRuntimeCommands_PluginVisibleDespiteStaticVisibleProducts(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	overrideVisibleProducts(t, []string{"calendar"})
+	registerPluginProduct(t, "conference-local", "stdio://plugin/conference-local")
+
+	root := &cobra.Command{Use: "dws"}
+	calendarCmd := &cobra.Command{Use: "calendar"}
+	pluginCmd := &cobra.Command{Use: "conference-local"}
+	bogusCmd := &cobra.Command{Use: "bogus-not-a-product"}
+	root.AddCommand(calendarCmd, pluginCmd, bogusCmd)
+
+	hideNonDirectRuntimeCommands(root)
+
+	if calendarCmd.Hidden {
+		t.Errorf("calendar (static VisibleProducts) must stay visible, got Hidden=true")
+	}
+	if pluginCmd.Hidden {
+		t.Errorf("conference-local (plugin-registered) must stay visible, got Hidden=true")
+	}
+	if !bogusCmd.Hidden {
+		t.Errorf("bogus-not-a-product must be hidden, got Hidden=false")
+	}
+}
+
+// TestVisibleMCPRootCommands_IncludesPluginProducts asserts that the help
+// renderer surfaces plugin products in the "Discovered MCP Services" section
+// and does not misclassify them as utility commands.
+func TestVisibleMCPRootCommands_IncludesPluginProducts(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	overrideVisibleProducts(t, []string{"calendar"})
+	registerPluginProduct(t, "conference-local", "stdio://plugin/conference-local")
+
+	root := &cobra.Command{Use: "dws"}
+	calendarCmd := &cobra.Command{Use: "calendar"}
+	pluginCmd := &cobra.Command{Use: "conference-local"}
+	authCmd := &cobra.Command{Use: "auth"}
+	root.AddCommand(calendarCmd, pluginCmd, authCmd)
+
+	services := visibleMCPRootCommands(root)
+	if !containsCommand(services, "conference-local") {
+		t.Errorf("visibleMCPRootCommands missing plugin command: %v", commandNames(services))
+	}
+	if !containsCommand(services, "calendar") {
+		t.Errorf("visibleMCPRootCommands missing static product: %v", commandNames(services))
+	}
+
+	utilities := visibleUtilityRootCommands(root)
+	if containsCommand(utilities, "conference-local") {
+		t.Errorf("visibleUtilityRootCommands must not include plugin command, got %v", commandNames(utilities))
+	}
+	if !containsCommand(utilities, "auth") {
+		t.Errorf("visibleUtilityRootCommands must include genuine utility command, got %v", commandNames(utilities))
+	}
+}
+
+func containsCommand(cmds []*cobra.Command, name string) bool {
+	for _, c := range cmds {
+		if c.Name() == name {
+			return true
+		}
+	}
+	return false
+}
+
+func commandNames(cmds []*cobra.Command) []string {
+	names := make([]string, 0, len(cmds))
+	for _, c := range cmds {
+		names = append(names, c.Name())
+	}
+	return names
+}

internal/auth/credential_reset_test.go

@@ -0,0 +1,319 @@
+package auth
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+// resetAppConfigCache clears cached app config so tests get a fresh load.
+func resetAppConfigCache() {
+	cachedAppConfigMu.Lock()
+	cachedAppConfig = nil
+	cachedAppConfigMu.Unlock()
+	cachedAppConfigOnce = sync.Once{}
+
+	cachedResolvedMu.Lock()
+	cachedResolvedValid = false
+	cachedResolvedID = ""
+	cachedResolvedSecret = ""
+	cachedResolvedMu.Unlock()
+}
+
+// ─── Issue #155: Defensive credential reset ────────────────────────────
+//
+// These tests verify that both DeviceFlowProvider and OAuthProvider always
+// reset credential state and re-fetch clientID from MCP, regardless of what
+// previous login methods left in app.json or runtime state.
+
+func TestIssue155V2_OAuthLoginNoSource_ThenDeviceLogin_ResetsAndFetches(t *testing.T) {
+	// Scenario: OAuth login saved app.json WITHOUT Source field (the original bug).
+	// Device flow should ignore the stale clientID, reset state, and re-fetch from MCP.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientID("")
+	SetClientSecret("")
+	resetClientIDFromMCP()
+	resetAppConfigCache()
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	// Simulate OAuth login: saved app.json with clientId but NO Source field
+	oauthAppJSON := `{"clientId":"ding-oauth-stale","clientSecret":"","createdAt":"2026-04-24T00:00:00+08:00"}`
+	if err := os.WriteFile(filepath.Join(dir, appConfigFile), []byte(oauthAppJSON), 0o600); err != nil {
+		t.Fatalf("WriteFile error: %v", err)
+	}
+
+	// Verify precondition: ClientID() loads stale value from app.json
+	resetAppConfigCache()
+	gotID := ClientID()
+	if gotID != "ding-oauth-stale" {
+		t.Fatalf("precondition: ClientID() = %q, want 'ding-oauth-stale'", gotID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("precondition: IsClientIDFromMCP() should be false for app.json without Source")
+	}
+
+	// Now create a DeviceFlowProvider — it should pick up the stale clientID
+	provider := NewDeviceFlowProvider(dir, nil)
+	if provider.clientID != "ding-oauth-stale" {
+		t.Fatalf("provider.clientID = %q, want 'ding-oauth-stale' (from app.json)", provider.clientID)
+	}
+
+	// Key assertion: after prepareCredentials(), the provider should have
+	// cleared the stale clientID and be ready for MCP fetch.
+	// We can't call Login() directly (needs real MCP server), but we can
+	// verify the reset logic by calling the new method directly.
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false")
+	}
+}
+
+func TestIssue155V2_LegacyAppJson_ThenDeviceLogin_ResetsAndFetches(t *testing.T) {
+	// Scenario: Legacy app.json (no Source field at all) exists from an old CLI version.
+	// Device flow should reset and re-fetch.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientID("")
+	SetClientSecret("")
+	resetClientIDFromMCP()
+	resetAppConfigCache()
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	// Write legacy app.json
+	legacyJSON := `{"clientId":"ding-legacy-old","clientSecret":"","createdAt":"2026-01-01T00:00:00+08:00"}`
+	if err := os.WriteFile(filepath.Join(dir, appConfigFile), []byte(legacyJSON), 0o600); err != nil {
+		t.Fatalf("WriteFile error: %v", err)
+	}
+
+	resetAppConfigCache()
+	provider := NewDeviceFlowProvider(dir, nil)
+
+	// Verify stale clientID was loaded
+	if provider.clientID != "ding-legacy-old" {
+		t.Fatalf("provider.clientID = %q, want 'ding-legacy-old'", provider.clientID)
+	}
+
+	// Reset should clear it
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+}
+
+func TestIssue155V2_DirectAppJson_ThenDeviceLogin_ResetsAndFetches(t *testing.T) {
+	// Scenario: User previously logged in with --client-id + --client-secret (direct mode).
+	// app.json has a different clientId. Device flow should reset and re-fetch from MCP.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientID("")
+	SetClientSecret("")
+	resetClientIDFromMCP()
+	resetAppConfigCache()
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	// Simulate direct-mode app.json with clientSecret stored
+	if err := SaveAppConfig(dir, &AppConfig{
+		ClientID:     "ding-direct-custom",
+		ClientSecret: PlainSecret("some-secret"),
+	}); err != nil {
+		t.Fatalf("SaveAppConfig error: %v", err)
+	}
+
+	resetAppConfigCache()
+	provider := NewDeviceFlowProvider(dir, nil)
+
+	// Verify the direct clientID was loaded
+	if provider.clientID != "ding-direct-custom" {
+		t.Fatalf("provider.clientID = %q, want 'ding-direct-custom'", provider.clientID)
+	}
+
+	// Reset should clear it
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false")
+	}
+}
+
+func TestIssue155V2_MCPFlagAlreadySet_ThenDeviceLogin_StillResets(t *testing.T) {
+	// Scenario: MCP flag is already set from a previous device login in same process.
+	// Device flow should still reset and re-fetch to ensure freshness.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	// Simulate: MCP flag is already set from previous login
+	SetClientIDFromMCP("ding-old-mcp")
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	provider := NewDeviceFlowProvider(dir, nil)
+	if provider.clientID != "ding-old-mcp" {
+		t.Fatalf("provider.clientID = %q, want 'ding-old-mcp'", provider.clientID)
+	}
+
+	// Reset should clear both clientID and MCP flag
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false after reset")
+	}
+}
+
+func TestIssue155V2_NoAppJson_DeviceLogin_StillWorks(t *testing.T) {
+	// Scenario: No app.json exists (first time login). Device flow should work normally.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientID("")
+	SetClientSecret("")
+	resetClientIDFromMCP()
+	resetAppConfigCache()
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	provider := NewDeviceFlowProvider(dir, nil)
+
+	// clientID should already be empty
+	if provider.clientID != "" {
+		t.Fatalf("provider.clientID = %q, want empty (no app.json)", provider.clientID)
+	}
+
+	// Reset should be a no-op but not crash
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false")
+	}
+}
+
+// ─── OAuthProvider defensive reset (--force login) ─────────────────────
+
+func TestIssue155V2_OAuthForceLogin_ResetsStaleCredentials(t *testing.T) {
+	// Scenario: Previous login saved app.json with MCP-fetched clientID but
+	// no Source marker. OAuth --force login should reset and re-fetch.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientID("")
+	SetClientSecret("")
+	resetClientIDFromMCP()
+	resetAppConfigCache()
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	// Simulate previous login: app.json with clientId but no Source
+	staleJSON := `{"clientId":"ding-stale-oauth","clientSecret":"","createdAt":"2026-04-24T00:00:00+08:00"}`
+	if err := os.WriteFile(filepath.Join(dir, appConfigFile), []byte(staleJSON), 0o600); err != nil {
+		t.Fatalf("WriteFile error: %v", err)
+	}
+
+	resetAppConfigCache()
+	provider := NewOAuthProvider(dir, nil)
+
+	// Verify stale clientID was loaded
+	if provider.clientID != "ding-stale-oauth" {
+		t.Fatalf("provider.clientID = %q, want 'ding-stale-oauth'", provider.clientID)
+	}
+
+	// Reset should clear it
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false")
+	}
+}
+
+func TestIssue155V2_OAuthForceLogin_MCPFlagSet_StillResets(t *testing.T) {
+	// Scenario: MCP flag is already set. OAuth --force login should still reset.
+
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	t.Setenv("DWS_CLIENT_ID", "")
+	t.Setenv("DWS_CLIENT_SECRET", "")
+
+	SetClientIDFromMCP("ding-old-mcp-oauth")
+	t.Cleanup(func() {
+		SetClientID("")
+		SetClientSecret("")
+		resetClientIDFromMCP()
+		resetAppConfigCache()
+	})
+
+	provider := NewOAuthProvider(dir, nil)
+
+	provider.resetCredentialState()
+
+	if provider.clientID != "" {
+		t.Fatalf("after resetCredentialState: provider.clientID = %q, want empty", provider.clientID)
+	}
+	if IsClientIDFromMCP() {
+		t.Fatal("after resetCredentialState: IsClientIDFromMCP() should be false after reset")
+	}
+}

internal/auth/device_flow.go

@@ -127,22 +127,38 @@ type serviceResult struct {
 	ErrorMsg  string          `json:"errorMsg"`
 }
 
+// resetCredentialState clears any stale credential state inherited from
+// previous login methods (OAuth, PAT, etc.) so that device flow always
+// starts fresh by fetching clientID from MCP.
+//
+// This is a defensive measure: no matter what a prior login wrote to
+// app.json or runtime globals, device flow will re-fetch from MCP and
+// set the correct clientIDFromMCP flag, ensuring exchangeCode() uses
+// the MCP proxy path (which doesn't require clientSecret).
+func (p *DeviceFlowProvider) resetCredentialState() {
+	p.clientID = ""
+	clientMu.Lock()
+	clientIDFromMCP = false
+	clientMu.Unlock()
+}
+
 func (p *DeviceFlowProvider) Login(ctx context.Context) (*TokenData, error) {
-	// Ensure we have a valid client ID (fetch from MCP if not available)
-	if p.clientID == "" {
-		if p.logger != nil {
-			p.logger.Debug("client ID not configured, fetching from MCP server")
-		}
-		mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
-		if mcpErr != nil {
-			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
-		}
-		p.clientID = mcpClientID
-		// Mark that clientID is from MCP
-		SetClientIDFromMCP(mcpClientID)
-		if p.logger != nil {
-			p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
-		}
+	// Defensive reset: clear any stale credential state from previous login
+	// methods (OAuth scan, PAT, etc.) so we always re-fetch from MCP.
+	// This ensures --device login works regardless of what app.json contains.
+	p.resetCredentialState()
+
+	if p.logger != nil {
+		p.logger.Debug("fetching client ID from MCP server (device flow always re-fetches)")
+	}
+	mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
+	if mcpErr != nil {
+		return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
+	}
+	p.clientID = mcpClientID
+	SetClientIDFromMCP(mcpClientID)
+	if p.logger != nil {
+		p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
 	}
 
 	const maxAttempts = 3

internal/auth/force_refresh.go

@@ -0,0 +1,41 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package auth
+
+import "time"
+
+// MarkAccessTokenStale loads the persisted TokenData, sets ExpiresAt to a past
+// instant (preserving access_token and refresh_token), and writes it back. The
+// next OAuthProvider.GetAccessToken call will see IsAccessTokenValid() == false
+// and proceed to lockedRefresh, exchanging the refresh_token for a fresh
+// access_token.
+//
+// Use this only when the server has rejected the current access_token but the
+// local expiry has not yet elapsed (zombie token scenario). It does not delete
+// any token material and is safe to call concurrently — actual refresh is
+// serialized by lockedRefresh's dual-layer locking.
+//
+// Returns the original load error when there is no usable token on disk; a
+// nil error when there is no access_token to invalidate (no-op).
+func MarkAccessTokenStale(configDir string) error {
+	data, err := LoadTokenData(configDir)
+	if err != nil {
+		return err
+	}
+	if data == nil || data.AccessToken == "" {
+		return nil
+	}
+	data.ExpiresAt = time.Now().Add(-1 * time.Minute)
+	return SaveTokenData(configDir, data)
+}

internal/auth/oauth_provider.go

@@ -55,6 +55,16 @@ func NewOAuthProvider(configDir string, logger *slog.Logger) *OAuthProvider {
 	}
 }
 
+// resetCredentialState clears any stale credential state inherited from
+// previous login methods so that OAuth flow always starts fresh by
+// fetching clientID from MCP.
+func (p *OAuthProvider) resetCredentialState() {
+	p.clientID = ""
+	clientMu.Lock()
+	clientIDFromMCP = false
+	clientMu.Unlock()
+}
+
 func (p *OAuthProvider) output() io.Writer {
 	if p != nil && p.Output != nil {
 		return p.Output
@@ -94,21 +104,22 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 	}
 
 	// Fall through: full browser OAuth flow.
-	// Ensure we have a valid client ID (fetch from MCP if not available)
-	if p.clientID == "" {
-		if p.logger != nil {
-			p.logger.Debug("client ID not configured, fetching from MCP server")
-		}
-		mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
-		if mcpErr != nil {
-			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
-		}
-		p.clientID = mcpClientID
-		// Mark that clientID is from MCP, so we use MCP OAuth endpoints
-		SetClientIDFromMCP(mcpClientID)
-		if p.logger != nil {
-			p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
-		}
+	// Defensive reset: clear any stale credential state from previous login
+	// methods so we always re-fetch clientID from MCP. This ensures
+	// --force login works regardless of what app.json contains.
+	p.resetCredentialState()
+
+	if p.logger != nil {
+		p.logger.Debug("fetching client ID from MCP server (OAuth flow always re-fetches)")
+	}
+	mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
+	if mcpErr != nil {
+		return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
+	}
+	p.clientID = mcpClientID
+	SetClientIDFromMCP(mcpClientID)
+	if p.logger != nil {
+		p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
 	}
 
 	// Find a free port for the callback server.

internal/auth/testmain_test.go

@@ -0,0 +1,40 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package auth
+
+import (
+	"os"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+)
+
+// TestMain isolates the on-disk keychain storage to a process-wide
+// temporary directory for the entire internal/auth test binary so that
+// SaveTokenData/DeleteTokenData calls in these tests can never write to
+// the developer's real keychain location, preventing cross-package leaks
+// when go test runs packages in parallel.
+func TestMain(m *testing.M) {
+	tmpDir, err := os.MkdirTemp("", "dws-auth-test-keychain-")
+	if err != nil {
+		panic("create test keychain tempdir: " + err.Error())
+	}
+	if err := os.Setenv(keychain.StorageDirEnv, tmpDir); err != nil {
+		_ = os.RemoveAll(tmpDir)
+		panic("set " + keychain.StorageDirEnv + ": " + err.Error())
+	}
+	code := m.Run()
+	_ = os.RemoveAll(tmpDir)
+	os.Exit(code)
+}

internal/auth/token_test.go

@@ -20,9 +20,12 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 )
 
-// cleanupKeychain removes test data from keychain after test completes.
+// cleanupKeychain isolates keychain state to a per-test temporary directory
+// so that concurrent test packages (notably internal/app) don't read tokens
+// written by these tests, and removes test data on completion.
 func cleanupKeychain(t *testing.T) {
 	t.Helper()
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
 	t.Cleanup(func() {
 		_ = keychain.Remove(keychain.Service, keychain.AccountToken)
 	})

internal/cli/loader.go

@@ -250,6 +250,13 @@ func (l EnvironmentLoader) Load(ctx context.Context) (ir.Catalog, error) {
 		return ir.Catalog{}, newCatalogDegraded(DegradedMarketUnreachable, 0)
 	}
 
+	// Surface Portal-side merge warnings (dropped envelopes, dangling serverDeps,
+	// dangling toolOverrides.*.serverOverride) to stderr so configuration drift
+	// is visible at the first `dws cache refresh` / cold start after Portal
+	// publishes a broken envelope. Non-fatal: discovery continues with the
+	// accepted subset. See plan fix-wukong-discovery-missing-servers Phase 4.3.
+	logDiscoveryWarnings(response.Metadata.Warnings)
+
 	servers := market.NormalizeServers(response, "live_market")
 	_ = store.SaveRegistry(partition, cache.RegistrySnapshot{Servers: servers})
 
@@ -354,3 +361,19 @@ func (l EnvironmentLoader) lookup(key string) (string, bool) {
 	}
 	return value, true
 }
+
+// logDiscoveryWarnings prints Portal-side merge warnings via slog (stderr).
+// No-op when the response carries an empty / nil Warnings slice — which is the
+// common case for older Portal builds that don't populate the field.
+func logDiscoveryWarnings(warnings []market.ListWarning) {
+	if len(warnings) == 0 {
+		return
+	}
+	for _, w := range warnings {
+		slog.Warn("discovery: merge warning from Portal",
+			"product", w.ProductID,
+			"reason", w.Reason,
+			"detail", w.Detail,
+		)
+	}
+}

internal/cobracmd/priority.go

@@ -14,37 +14,18 @@
 package cobracmd
 
 import (
-	"strconv"
-	"strings"
-
 	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 )
 
-const overridePriorityAnnotation = "dws.override-priority"
-
-// SetOverridePriority sets the override priority annotation on cmd.
+// SetOverridePriority delegates to cmdutil.SetOverridePriority so internal and
+// external call sites share one annotation key.
 func SetOverridePriority(cmd *cobra.Command, priority int) {
-	if cmd == nil {
-		return
-	}
-	if cmd.Annotations == nil {
-		cmd.Annotations = map[string]string{}
-	}
-	cmd.Annotations[overridePriorityAnnotation] = strconv.Itoa(priority)
+	cmdutil.SetOverridePriority(cmd, priority)
 }
 
-// OverridePriority returns the override priority annotation value, or 0.
+// OverridePriority delegates to cmdutil.OverridePriority.
 func OverridePriority(cmd *cobra.Command) int {
-	if cmd == nil || cmd.Annotations == nil {
-		return 0
-	}
-	raw := strings.TrimSpace(cmd.Annotations[overridePriorityAnnotation])
-	if raw == "" {
-		return 0
-	}
-	value, err := strconv.Atoi(raw)
-	if err != nil {
-		return 0
-	}
-	return value
+	return cmdutil.OverridePriority(cmd)
 }

internal/compat/dynamic_commands.go

@@ -14,18 +14,35 @@
 package compat
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"log/slog"
 	"os"
 	"sort"
 	"strings"
+	"time"
 	"unicode"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
 
+// runtimeDefaultWhitelist is the closed set of placeholders v3 supports for
+// CLIFlagOverride.RuntimeDefault. Placeholders outside this set emit a
+// warning at command-build time and are ignored at invocation time. See
+// discovery-schema-v3 §2.3.
+var runtimeDefaultWhitelist = map[string]bool{
+	"$currentUserId": true,
+	"$unionId":       true,
+	"$corpId":        true,
+	"$now":           true,
+	"$today":         true,
+}
+
 // BuildDynamicCommands generates cobra commands from servers.json CLIOverlay metadata.
 // Each server with non-skip CLIOverlay gets a top-level command with groups and
 // tool overrides translated into subcommands with proper flag bindings and transforms.
@@ -47,10 +64,6 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 		if cli.Skip {
 			continue
 		}
-		if len(cli.ToolOverrides) == 0 {
-			continue
-		}
-
 		// §1.1: cli.command → top-level command name
 		cmdName := strings.TrimSpace(cli.Command)
 		if cmdName == "" {
@@ -60,11 +73,35 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 			continue
 		}
 
+		// §v3.2.6: CLIOverlay.RedirectTo turns the entire top-level product
+		// into a stub that prints "Please use: dws <target>".
+		if target := strings.TrimSpace(cli.RedirectTo); target != "" {
+			stub := buildOverlayRedirect(cmdName, cli.Description, target)
+			if cli.Hidden {
+				stub.Hidden = true
+			}
+			// Mark envelope provenance so overlay registrants can tell this
+			// redirect stub apart from a helper fallback carrying the same
+			// name; see cmdutil.SourceAnnotation.
+			cmdutil.MarkEnvelopeSource(stub)
+			built = append(built, builtCmd{cmd: stub, parent: strings.TrimSpace(cli.Parent)})
+			continue
+		}
+
+		if len(cli.ToolOverrides) == 0 {
+			continue
+		}
+
 		rootCmd := NewGroupCommand(cmdName, cli.Description)
 		// §1.5: cli.hidden → entire service hidden
 		if cli.Hidden {
 			rootCmd.Hidden = true
 		}
+		// Mark envelope provenance so edition overlays can distinguish this
+		// dynamic root from a same-named helper fallback when deciding
+		// whether to merge hardcoded leaves or evict and replace. See
+		// cmdutil.SourceAnnotation and the wukong overlay's RegisterProducts.
+		cmdutil.MarkEnvelopeSource(rootCmd)
 
 		// Build detail index for this server: toolName → DetailTool
 		detailIndex := buildDetailIndex(detailsByID[strings.TrimSpace(cli.ID)])
@@ -93,6 +130,13 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 				cliName = deriveCommandName(toolName, cli.Prefixes)
 			}
 
+			// §P2.redirect: redirectTo turns this entry into a stub.
+			if target := strings.TrimSpace(override.RedirectTo); target != "" {
+				redirect := buildRedirectCommand(cliName, override.Description, target)
+				attachToGroup(rootCmd, override.Group, groupCmds, redirect)
+				continue
+			}
+
 			bindings, normalizer := buildOverrideBindings(override)
 
 			// Resolve Short/Long from Detail API toolTitle/toolDesc;
@@ -111,12 +155,25 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 				}
 			}
 
+			// ServerOverride routes this leaf's tool invocation to a different
+			// product's MCP server; fall back to the enclosing overlay's ID.
+			canonicalProduct := strings.TrimSpace(override.ServerOverride)
+			if canonicalProduct == "" {
+				canonicalProduct = strings.TrimSpace(cli.ID)
+			}
+
 			route := Route{
 				Use:   cliName,
 				Short: short,
 				Long:  long,
+				// Preserve left-side indentation: cobra's Examples template
+				// renders {{.Example}} verbatim, and hardcoded helper commands
+				// rely on a 2-space prefix to look indented under "Examples:".
+				// Only trim trailing whitespace/newlines so envelope JSON can
+				// safely carry a closing "\n" without doubling the blank line.
+				Example: strings.TrimRight(override.Example, " \t\r\n"),
 				Target: Target{
-					CanonicalProduct: strings.TrimSpace(cli.ID),
+					CanonicalProduct: canonicalProduct,
 					Tool:             toolName,
 				},
 				Bindings:   bindings,
@@ -128,6 +185,9 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 				route.Normalizer = chainSensitiveNormalizer(normalizer)
 			}
 
+			// §v3.2.5: outputFormat.rename/drop/columns post-processing.
+			route.OutputTransform = buildOutputTransform(override.OutputFormat)
+
 			cmd := NewDirectCommand(route, runner)
 
 			// Enrich flags with typed parameters from Detail API toolRequest JSON Schema.
@@ -135,13 +195,25 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 				buildFlagsFromDetailSchema(cmd, dt.ToolRequest, override.Flags)
 			}
 
+			// §P2.flagconstraints: must run AFTER schema enrichment because the
+			// target flags may be registered lazily by buildFlagsFromDetailSchema.
+			applyFlagConstraints(cmd, override)
+
 			// §1.4: Add to the right parent group
-			groupName := strings.TrimSpace(override.Group)
-			if groupName != "" {
-				parent := resolveNestedGroup(rootCmd, groupName, groupCmds)
-				parent.AddCommand(cmd)
-			} else {
-				rootCmd.AddCommand(cmd)
+			attachToGroup(rootCmd, override.Group, groupCmds, cmd)
+		}
+
+		// §P2.hints: attach hint stub commands registered on the overlay.
+		if len(cli.Hints) > 0 {
+			hintNames := make([]string, 0, len(cli.Hints))
+			for name := range cli.Hints {
+				hintNames = append(hintNames, name)
+			}
+			sort.Strings(hintNames)
+			for _, name := range hintNames {
+				def := cli.Hints[name]
+				hint := buildHintCommand(name, def)
+				attachToGroup(rootCmd, def.Group, groupCmds, hint)
 			}
 		}
 
@@ -238,6 +310,15 @@ func buildFlagsFromDetailSchema(cmd *cobra.Command, schemaJSON string, flagOverr
 	for _, key := range keys {
 		prop := schema.Properties[key]
 
+		// Skip properties that are bound as positional arguments; they are
+		// collected from cobra args rather than flags. For dual-mode positional
+		// bindings (envelope: positional + alias/aliases), ApplyBindings has
+		// already registered the alias flags, so we should not re-register
+		// them here from the MCP detail schema.
+		if ov, ok := flagOverrides[key]; ok && ov.Positional {
+			continue
+		}
+
 		// Determine flag name: prefer alias from CLIFlagOverride, else kebab-case.
 		flagName := toKebabCase(key)
 		if ov, ok := flagOverrides[key]; ok && strings.TrimSpace(ov.Alias) != "" {
@@ -452,21 +533,46 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 		envVar    string
 	}
 	var envDefaults []envDefaultEntry
-	type hiddenDefaultEntry struct {
+	// defaultInjectEntry captures envelope flag.default values that must be
+	// injected into the MCP body when the user omits the flag. v3.2 widened
+	// this from hidden-only to all flags so that visible flags carrying a
+	// default (e.g. oa list-forms cursor=0 / pageSize=100) match the
+	// hardcoded helper command behavior of `mustGetFlag(cobra default) →
+	// body`. The kind drives typed coercion at injection time so a
+	// `type: int` envelope default reaches MCP as `int(0)`, not string `"0"`.
+	type defaultInjectEntry struct {
 		paramName    string
 		defaultValue string
+		kind         ValueKind
 	}
-	var hiddenDefaults []hiddenDefaultEntry
+	var defaultInjects []defaultInjectEntry
+	type runtimeDefaultEntry struct {
+		paramName   string
+		placeholder string
+	}
+	var runtimeDefaults []runtimeDefaultEntry
+	type omitEntry struct {
+		paramName string
+		mode      string // "empty" (default) | "zero" | "never"
+	}
+	omits := make(map[string]omitEntry, len(paramNames))
 
 	for _, paramName := range paramNames {
 		flagOverride := override.Flags[paramName]
 
-		// §2.2: flag name from alias, fallback to kebab-case of param name
-		flagName := strings.TrimSpace(flagOverride.Alias)
-		if flagName == "" {
+		// §2.2: flag name from alias, fallback to kebab-case of param name.
+		// For pure positional bindings (no alias declared) we deliberately
+		// leave FlagName empty so ApplyBindings / NewDirectCommand can
+		// distinguish "envelope wants flag-or-positional dual entry" from
+		// "envelope only wants positional". Auto-deriving a flag name here
+		// would otherwise leak a redundant `--<paramName>` flag and confuse
+		// the dual-mode detection.
+		explicitAlias := strings.TrimSpace(flagOverride.Alias)
+		flagName := explicitAlias
+		if flagName == "" && !flagOverride.Positional {
 			flagName = compatFlagName(paramName)
 		}
-		if flagName == "" {
+		if flagName == "" && !flagOverride.Positional {
 			flagName = paramName
 		}
 
@@ -475,23 +581,68 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 			continue
 		}
 
-		binding := FlagBinding{
-			FlagName: flagName,
-			Property: paramName,
-			Kind:     ValueString,
-			Usage:    paramName,
+		// §2.2 (aliases): deduplicate additional hidden aliases against the
+		// primary name + reserved names. Preserves envelope declaration order
+		// so CLI precedence (primary > Alias > Aliases[0..n]) is deterministic.
+		var extraAliases []string
+		if len(flagOverride.Aliases) > 0 {
+			seen := map[string]bool{"json": true, "params": true}
+			if flagName != "" {
+				seen[flagName] = true
+			}
+			extraAliases = make([]string, 0, len(flagOverride.Aliases))
+			for _, a := range flagOverride.Aliases {
+				a = strings.TrimSpace(a)
+				if a == "" || seen[a] {
+					continue
+				}
+				seen[a] = true
+				extraAliases = append(extraAliases, a)
+			}
 		}
 
-		// §2.5: hidden flag with default
-		if flagOverride.Hidden {
-			// Hidden flags are still added but marked hidden.
-			// They are auto-populated with their default value via the normalizer.
-			if flagOverride.Default != "" {
-				hiddenDefaults = append(hiddenDefaults, hiddenDefaultEntry{
-					paramName:    paramName,
-					defaultValue: flagOverride.Default,
-				})
-			}
+		// Usage defaults to paramName but an explicit Description on the
+		// overlay wins (it also beats the Detail API's toolDesc during flag
+		// enrichment because buildFlagsFromDetailSchema preserves overlay usage).
+		usage := paramName
+		if desc := strings.TrimSpace(flagOverride.Description); desc != "" {
+			usage = desc
+		}
+
+		binding := FlagBinding{
+			FlagName: flagName,
+			Aliases:  extraAliases,
+			Short:    strings.TrimSpace(flagOverride.Shorthand),
+			Property: paramName,
+			Kind:     kindFromTypeName(flagOverride.Type),
+			Usage:    usage,
+			// §P1: Required is preserved for positional bindings too. For
+			// pure positional, cobra arity (MinimumNArgs) enforces presence
+			// at parse time. For dual-mode positional (positional + alias),
+			// validateRequiredPositionalBindings closes the loop in RunE
+			// after both flag and positional injection, so MarkFlagRequired
+			// is intentionally avoided.
+			Required: flagOverride.Required,
+			// §2.4: Default drives both cobra's --help "(default ...)"
+			// rendering and (since v3.2) MCP body injection when the user
+			// omits the flag. CollectBindings still gates writes by
+			// user-changed flags, so user-provided values always win; the
+			// normalizer's defaultInjects loop only fills missing keys.
+			Default:         flagOverride.Default,
+			Positional:      flagOverride.Positional,
+			PositionalIndex: flagOverride.PositionalIndex,
+		}
+
+		// §v3.2: any non-empty default — hidden or visible — gets injected
+		// when the user omits the flag. Earlier versions gated this on
+		// flagOverride.Hidden which left visible flags with `"default": "0"`
+		// (e.g. oa list-forms cursor) silently absent from the MCP body.
+		if flagOverride.Default != "" {
+			defaultInjects = append(defaultInjects, defaultInjectEntry{
+				paramName:    paramName,
+				defaultValue: flagOverride.Default,
+				kind:         binding.Kind,
+			})
 		}
 
 		bindings = append(bindings, binding)
@@ -509,10 +660,23 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 				envVar:    flagOverride.EnvDefault,
 			})
 		}
+		if rd := strings.TrimSpace(flagOverride.RuntimeDefault); rd != "" {
+			if !runtimeDefaultWhitelist[rd] {
+				fmt.Fprintf(os.Stderr, "[discovery] runtimeDefault: unknown placeholder %q on %s; ignoring\n", rd, paramName)
+			} else {
+				runtimeDefaults = append(runtimeDefaults, runtimeDefaultEntry{
+					paramName:   paramName,
+					placeholder: rd,
+				})
+			}
+		}
+		if mode := strings.TrimSpace(flagOverride.OmitWhen); mode != "" && mode != "empty" {
+			omits[paramName] = omitEntry{paramName: paramName, mode: mode}
+		}
 	}
 
 	// Check if we need a normalizer: transforms, env defaults, hidden defaults,
-	// or dotted property paths that need nesting.
+	// runtime defaults, omit-when overrides, dotted property paths, or body wrapper.
 	needsDottedNesting := false
 	for _, b := range bindings {
 		if strings.Contains(b.Property, ".") {
@@ -520,16 +684,32 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 			break
 		}
 	}
-	if len(transforms) == 0 && len(envDefaults) == 0 && len(hiddenDefaults) == 0 && !needsDottedNesting {
+	bodyWrapper := strings.TrimSpace(override.BodyWrapper)
+	if len(transforms) == 0 && len(envDefaults) == 0 && len(defaultInjects) == 0 && len(runtimeDefaults) == 0 && len(omits) == 0 && !needsDottedNesting && bodyWrapper == "" {
 		return bindings, nil
 	}
 
-	// Build a normalizer that applies hidden defaults + env defaults + transforms + nesting
+	// Build a normalizer that applies default injections + env defaults + runtime defaults
+	// + transforms + omitWhen + nesting + body wrap.
 	normalizer := func(cmd *cobra.Command, params map[string]any) error {
-		// §2.5: Apply hidden flag defaults for parameters not explicitly set
-		for _, hd := range hiddenDefaults {
-			if _, exists := params[hd.paramName]; !exists {
-				params[hd.paramName] = hd.defaultValue
+		// §v3.2: Apply envelope flag.default for parameters not explicitly set.
+		// Coerce by Kind so number-typed schemas don't reject string defaults.
+		for _, di := range defaultInjects {
+			if _, exists := params[di.paramName]; exists {
+				continue
+			}
+			defStr, defInt, defFloat, defBool, defSlice := parseFlagDefault(di.kind, di.defaultValue)
+			switch di.kind {
+			case ValueInt:
+				params[di.paramName] = defInt
+			case ValueFloat:
+				params[di.paramName] = defFloat
+			case ValueBool:
+				params[di.paramName] = defBool
+			case ValueStringSlice, ValueIntSlice, ValueFloatSlice, ValueBoolSlice:
+				params[di.paramName] = defSlice
+			default: // ValueString, ValueJSON, and any unknown kind
+				params[di.paramName] = defStr
 			}
 		}
 
@@ -542,6 +722,26 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 			}
 		}
 
+		// §v3.2.3: Apply runtime defaults (lowest priority, last default fill).
+		if len(runtimeDefaults) > 0 {
+			resolvers := runtimeDefaultResolvers()
+			for _, rd := range runtimeDefaults {
+				if _, exists := params[rd.paramName]; exists {
+					continue
+				}
+				resolver, ok := resolvers[rd.placeholder]
+				if !ok {
+					// Whitelisted but no provider registered (common on
+					// open-source core). Emit a single warning and move on.
+					fmt.Fprintf(os.Stderr, "[discovery] runtimeDefault: no resolver registered for %s; skipping %s\n", rd.placeholder, rd.paramName)
+					continue
+				}
+				if val, ok := resolver(cmd.Context()); ok && val != "" {
+					params[rd.paramName] = val
+				}
+			}
+		}
+
 		// §3: Apply transforms
 		for _, t := range transforms {
 			val, exists := params[t.paramName]
@@ -561,15 +761,155 @@ func buildOverrideBindings(override market.CLIToolOverride) ([]FlagBinding, Norm
 			params[t.paramName] = transformed
 		}
 
+		// §v3.2.2: Apply omitWhen — drop keys whose value meets the omit
+		// condition for the declared mode. Default mode "empty" is already
+		// handled implicitly by CollectBindings (empty string / empty slice
+		// never enters params), so we only deal with "zero" and "never".
+		for _, o := range omits {
+			applyOmitWhen(params, o.paramName, o.mode)
+		}
+
 		// Nest dotted property paths: "Body.query" → params["Body"]["query"]
 		nestDottedPaths(params)
 
+		// §P2.bodyWrapper: wrap user-facing params under a single named key.
+		// Internal control keys (prefixed with '_' e.g. _blocked, _yes) stay
+		// at the top level so downstream confirmation logic keeps working.
+		if bodyWrapper != "" {
+			wrapParamsIntoBody(params, bodyWrapper)
+		}
+
 		return nil
 	}
 
 	return bindings, normalizer
 }
 
+// wrapParamsIntoBody moves every non-internal key from params into a new
+// map stored under params[wrapper]. Internal keys (leading underscore) are
+// preserved at the top level so the dispatcher / --yes logic still sees
+// them. If params already contains params[wrapper] it is merged in first.
+func wrapParamsIntoBody(params map[string]any, wrapper string) {
+	if wrapper == "" {
+		return
+	}
+	body := map[string]any{}
+	if existing, ok := params[wrapper].(map[string]any); ok {
+		for k, v := range existing {
+			body[k] = v
+		}
+		delete(params, wrapper)
+	}
+	for key, value := range params {
+		if strings.HasPrefix(key, "_") {
+			continue
+		}
+		body[key] = value
+		delete(params, key)
+	}
+	params[wrapper] = body
+}
+
+// attachToGroup places cmd under the right parent based on the dotted group
+// path. Empty group means attach directly to the overlay root.
+func attachToGroup(root *cobra.Command, groupPath string, groupCmds map[string]*cobra.Command, cmd *cobra.Command) {
+	gp := strings.TrimSpace(groupPath)
+	if gp == "" {
+		root.AddCommand(cmd)
+		return
+	}
+	parent := resolveNestedGroup(root, gp, groupCmds)
+	parent.AddCommand(cmd)
+}
+
+// buildRedirectCommand returns a stub leaf that prints "use: <target>" and
+// performs no tool invocation. Accepts unknown flags/args so users hitting
+// the old path get the redirect message instead of a parse error.
+func buildRedirectCommand(name, description, target string) *cobra.Command {
+	short := strings.TrimSpace(description)
+	if short == "" {
+		short = fmt.Sprintf("moved → %s", target)
+	}
+	cmd := &cobra.Command{
+		Use:                name,
+		Short:              short,
+		Long:               fmt.Sprintf("This command has moved. Please use: %s", target),
+		DisableFlagParsing: true,
+		DisableAutoGenTag:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			fmt.Fprintf(cmd.OutOrStdout(), "This command has moved. Please use: %s\n", target)
+			return nil
+		},
+	}
+	return cmd
+}
+
+// buildHintCommand returns a stub sub-command that prints a redirect hint
+// to the canonical command path declared by the overlay's hintCommands entry.
+func buildHintCommand(name string, def market.CLIHintDef) *cobra.Command {
+	target := strings.TrimSpace(def.Target)
+	short := strings.TrimSpace(def.Description)
+	if short == "" {
+		if target != "" {
+			short = fmt.Sprintf("hint: use %s", target)
+		} else {
+			short = "hint: see --help for the canonical command"
+		}
+	}
+	cmd := &cobra.Command{
+		Use:                name,
+		Short:              short,
+		Long:               short,
+		DisableFlagParsing: true,
+		DisableAutoGenTag:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if target != "" {
+				fmt.Fprintf(cmd.OutOrStdout(), "Please use: %s\n", target)
+			} else {
+				_ = cmd.Help()
+			}
+			return nil
+		},
+	}
+	return cmd
+}
+
+// applyFlagConstraints wires mutuallyExclusive / requireOneOf declarations
+// onto the cobra command. Unknown flag names are logged and skipped so a
+// stale/malformed overlay never blocks the entire command tree from building.
+func applyFlagConstraints(cmd *cobra.Command, override market.CLIToolOverride) {
+	validate := func(names []string) []string {
+		valid := make([]string, 0, len(names))
+		for _, n := range names {
+			n = strings.TrimSpace(n)
+			if n == "" {
+				continue
+			}
+			if cmd.Flags().Lookup(n) == nil {
+				fmt.Fprintf(os.Stderr, "[discovery] flag constraint references unknown flag --%s on %q; skipping\n", n, cmd.Name())
+				return nil
+			}
+			valid = append(valid, n)
+		}
+		return valid
+	}
+
+	for _, group := range override.MutuallyExclusive {
+		names := validate(group)
+		if len(names) < 2 {
+			continue
+		}
+		cmd.MarkFlagsMutuallyExclusive(names...)
+	}
+	for _, group := range override.RequireOneOf {
+		names := validate(group)
+		if len(names) < 1 {
+			continue
+		}
+		cmd.MarkFlagsOneRequired(names...)
+	}
+}
+
 // chainSensitiveNormalizer wraps a normalizer with --yes confirmation for sensitive operations (§5.1).
 func chainSensitiveNormalizer(inner Normalizer) Normalizer {
 	return func(cmd *cobra.Command, params map[string]any) error {
@@ -618,6 +958,101 @@ func sortedToolNames(m map[string]market.CLIToolOverride) []string {
 	return keys
 }
 
+// kindFromTypeName maps the v3 CLIFlagOverride.Type declaration to the
+// internal FlagBinding.Kind enum. Empty / unknown → ValueString (which keeps
+// the v2 behaviour where every overlay flag was a plain string).
+func kindFromTypeName(typeName string) ValueKind {
+	switch strings.TrimSpace(strings.ToLower(typeName)) {
+	case "int", "integer", "number":
+		return ValueInt
+	case "bool", "boolean":
+		return ValueBool
+	case "stringslice", "string_slice", "[]string":
+		return ValueStringSlice
+	case "string", "":
+		return ValueString
+	default:
+		fmt.Fprintf(os.Stderr, "[discovery] flag type %q not recognised; defaulting to string\n", typeName)
+		return ValueString
+	}
+}
+
+// runtimeDefaultResolvers returns the edition-provided resolver map plus
+// built-in fallbacks for $now / $today (which are trivially local). Overlays
+// are expected to register the user-identity placeholders; $now / $today are
+// always available.
+func runtimeDefaultResolvers() map[string]edition.RuntimeDefaultFn {
+	resolvers := make(map[string]edition.RuntimeDefaultFn, len(runtimeDefaultWhitelist))
+	resolvers["$now"] = func(ctx context.Context) (string, bool) {
+		return fmt.Sprintf("%d", time.Now().UnixMilli()), true
+	}
+	resolvers["$today"] = func(ctx context.Context) (string, bool) {
+		loc, err := time.LoadLocation("Asia/Shanghai")
+		if err != nil {
+			loc = time.FixedZone("CST", 8*3600)
+		}
+		return time.Now().In(loc).Format("2006-01-02"), true
+	}
+	if hooks := edition.Get(); hooks != nil && hooks.RuntimeDefaults != nil {
+		for id, fn := range hooks.RuntimeDefaults() {
+			if fn != nil {
+				resolvers[id] = fn
+			}
+		}
+	}
+	return resolvers
+}
+
+// applyOmitWhen drops a key from params when its value meets the omit
+// condition for the declared mode. "empty" (the default) is handled by
+// CollectBindings upstream, so this function only processes "zero" and
+// "never" — "never" is a marker that keeps the zero value explicit, so we
+// do nothing for it.
+func applyOmitWhen(params map[string]any, key, mode string) {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case "never":
+		return
+	case "zero":
+		val, exists := params[key]
+		if !exists {
+			return
+		}
+		if isZeroValue(val) {
+			delete(params, key)
+		}
+	default:
+		// "empty" is the default, no-op.
+	}
+	// Emit a trace for anyone debugging envelope behaviour; kept at Debug so
+	// it never leaks into the default CLI output.
+	slog.Debug("applyOmitWhen", "key", key, "mode", mode)
+}
+
+func isZeroValue(v any) bool {
+	switch val := v.(type) {
+	case nil:
+		return true
+	case string:
+		return strings.TrimSpace(val) == ""
+	case bool:
+		return !val
+	case int:
+		return val == 0
+	case int64:
+		return val == 0
+	case float64:
+		return val == 0
+	case []any:
+		return len(val) == 0
+	case []string:
+		return len(val) == 0
+	case map[string]any:
+		return len(val) == 0
+	default:
+		return false
+	}
+}
+
 // nestDottedPaths converts flat dotted keys in params into nested maps.
 // Example: params["Body.query"] = "test" → params["Body"] = map{"query": "test"}
 // If multiple dotted keys share a prefix, they are merged into the same nested map.

internal/compat/hint_redirect.go

@@ -0,0 +1,55 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package compat
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// buildOverlayRedirect builds a top-level product command whose only behaviour
+// is printing "Please use: dws <target>" and returning nil. All args/flags are
+// accepted and ignored so users running the old command path get the redirect
+// message instead of a parse error.
+//
+// See discovery-schema-v3 §2.6 (CLIOverlay.RedirectTo).
+func buildOverlayRedirect(name, description, target string) *cobra.Command {
+	target = strings.TrimSpace(target)
+	short := strings.TrimSpace(description)
+	if short == "" {
+		if target != "" {
+			short = fmt.Sprintf("moved → %s", target)
+		} else {
+			short = "command relocated; see --help for the canonical path"
+		}
+	}
+	cmd := &cobra.Command{
+		Use:                name,
+		Short:              short,
+		Long:               fmt.Sprintf("This command has moved. Please use: dws %s", target),
+		DisableFlagParsing: true,
+		DisableAutoGenTag:  true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if target == "" {
+				_ = cmd.Help()
+				return nil
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Please use: dws %s\n", target)
+			return nil
+		},
+	}
+	return cmd
+}

internal/compat/output_format.go

@@ -0,0 +1,107 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package compat
+
+import (
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+)
+
+// buildOutputTransform compiles a CLIOutputFormat into a payload-shaping
+// function applied to executor.Result.Response before the formatter runs.
+// See discovery-schema-v3 §2.5.
+//
+// Apply order (deterministic): drop → rename → columns.
+// Columns filter only takes effect under --format=table (the formatter
+// consults it via the "_columns" marker key this function injects).
+// Returns nil when the spec is empty so callers can skip wiring.
+func buildOutputTransform(spec market.CLIOutputFormat) func(map[string]any) map[string]any {
+	if len(spec.Drop) == 0 && len(spec.Rename) == 0 && len(spec.Columns) == 0 {
+		return nil
+	}
+	dropped := append([]string(nil), spec.Drop...)
+	renamed := make(map[string]string, len(spec.Rename))
+	for k, v := range spec.Rename {
+		renamed[k] = v
+	}
+	columns := append([]string(nil), spec.Columns...)
+
+	return func(resp map[string]any) map[string]any {
+		if resp == nil {
+			return resp
+		}
+		applyDrop(resp, dropped)
+		applyRename(resp, renamed)
+		if len(columns) > 0 {
+			resp["_columns"] = append([]string(nil), columns...)
+		}
+		return resp
+	}
+}
+
+// applyDrop removes the named keys at the top level and one level of nested
+// object. Missing keys are silently ignored. Keys with "." are treated as a
+// two-part path (parent.child).
+func applyDrop(m map[string]any, keys []string) {
+	for _, key := range keys {
+		if key == "" {
+			continue
+		}
+		delete(m, key)
+	}
+	for _, v := range m {
+		if inner, ok := v.(map[string]any); ok {
+			for _, key := range keys {
+				if key == "" {
+					continue
+				}
+				delete(inner, key)
+			}
+		}
+	}
+}
+
+// applyRename moves fields from src key to dst key at top level and one level
+// of nested object. Collisions overwrite silently. Missing src keys are
+// no-ops.
+func applyRename(m map[string]any, mapping map[string]string) {
+	if len(mapping) == 0 {
+		return
+	}
+	// First pass: top level.
+	for src, dst := range mapping {
+		if src == "" || dst == "" || src == dst {
+			continue
+		}
+		if v, ok := m[src]; ok {
+			m[dst] = v
+			delete(m, src)
+		}
+	}
+	// Second pass: one level nested.
+	for _, v := range m {
+		inner, ok := v.(map[string]any)
+		if !ok {
+			continue
+		}
+		for src, dst := range mapping {
+			if src == "" || dst == "" || src == dst {
+				continue
+			}
+			if val, ok := inner[src]; ok {
+				inner[dst] = val
+				delete(inner, src)
+			}
+		}
+	}
+}

internal/compat/registry.go

@@ -56,11 +56,27 @@ type Target struct {
 type FlagBinding struct {
 	FlagName string
 	Alias    string
+	// Aliases are additional hidden flag names that map to the same MCP
+	// parameter. Any of them being set satisfies Required, and the value
+	// is resolved via firstChangedFlag(FlagName, Alias, Aliases...).
+	// Mirrors cmdutil.ValidateRequiredFlagWithAliases / FlagOrFallback.
+	Aliases  []string
 	Short    string
 	Property string
 	Kind     ValueKind
 	Usage    string
 	Required bool
+	// Default is the cobra-level flag default value as a string. Parsed
+	// into the Kind-appropriate primitive at registration time. Empty
+	// string keeps the existing zero-value default. This only affects
+	// what cobra renders in --help (the "(default ...)" suffix); it does
+	// NOT inject the value into MCP params on its own — CollectBindings
+	// still gates writes by user-changed flags via firstChangedFlag.
+	Default string
+	// Positional binds this parameter to a positional CLI argument rather
+	// than a --flag. PositionalIndex is the 0-based slot.
+	Positional      bool
+	PositionalIndex int
 }
 
 type Normalizer func(cmd *cobra.Command, params map[string]any) error
@@ -75,6 +91,10 @@ type Route struct {
 	Target     Target
 	Bindings   []FlagBinding
 	Normalizer Normalizer
+	// OutputTransform, when non-nil, post-processes the MCP response payload
+	// (rename / drop / columns) before the formatter emits it. Wired up from
+	// CLIToolOverride.OutputFormat. See discovery-schema-v3 §2.5.
+	OutputTransform func(map[string]any) map[string]any
 }
 
 type CommandFactory func(runner executor.Runner) *cobra.Command
@@ -109,14 +129,87 @@ func NewFallbackCommands(runner executor.Runner) []*cobra.Command {
 var NewGroupCommand = cobracmd.NewGroupCommand
 
 func NewDirectCommand(route Route, runner executor.Runner) *cobra.Command {
+	// Compute positional arity. Two counts:
+	//   - totalMax: the highest PositionalIndex+1 across all positional bindings
+	//     (caps how many trailing args cobra accepts).
+	//   - strictMin: the highest PositionalIndex+1 among "pure" positional
+	//     bindings (no flag aliases). Backward-compat: any pure positional
+	//     binding implies required arity at parse time, regardless of Required.
+	//
+	// Dual-mode positional bindings (positional + envelope-declared flag
+	// aliases, e.g. `{positional:true, alias:"query", aliases:["keyword"]}`)
+	// are counted into totalMax but excluded from strictMin so a flag-only
+	// invocation parses; their required-presence is enforced by
+	// validateRequiredPositionalBindings inside RunE.
+	//
+	// For positional bindings, buildOverrideBindings populates FlagName /
+	// Aliases only when the envelope explicitly declared them, so the
+	// dual-mode detection here is unambiguous.
+	strictMin := 0
+	totalMax := 0
+	for _, b := range route.Bindings {
+		if !b.Positional {
+			continue
+		}
+		if b.PositionalIndex+1 > totalMax {
+			totalMax = b.PositionalIndex + 1
+		}
+		hasFlagAlias := strings.TrimSpace(b.Alias) != "" || strings.TrimSpace(b.FlagName) != "" || len(b.Aliases) > 0
+		if !hasFlagAlias && b.PositionalIndex+1 > strictMin {
+			strictMin = b.PositionalIndex + 1
+		}
+	}
+	var argsValidator cobra.PositionalArgs = cobra.NoArgs
+	switch {
+	case totalMax == 0:
+		argsValidator = cobra.NoArgs
+	case strictMin > 0 && strictMin == totalMax:
+		argsValidator = cobra.MinimumNArgs(strictMin)
+	case strictMin > 0:
+		argsValidator = cobra.RangeArgs(strictMin, totalMax)
+	default:
+		argsValidator = cobra.MaximumNArgs(totalMax)
+	}
+
+	// Extend Use with [<placeholder>] tokens for positional bindings so
+	// `--help` renders `cmd [arg1] [arg2] [flags]`, matching hardcoded
+	// helper commands' style (e.g. devdoc article search [keyword]).
+	use := route.Use
+	if totalMax > 0 {
+		ordered := make([]FlagBinding, 0, totalMax)
+		for _, b := range route.Bindings {
+			if b.Positional {
+				ordered = append(ordered, b)
+			}
+		}
+		sort.SliceStable(ordered, func(i, j int) bool {
+			return ordered[i].PositionalIndex < ordered[j].PositionalIndex
+		})
+		var sb strings.Builder
+		sb.WriteString(use)
+		for _, b := range ordered {
+			name := strings.TrimSpace(b.Property)
+			if name == "" {
+				name = strings.TrimSpace(b.FlagName)
+			}
+			if name == "" {
+				continue
+			}
+			sb.WriteString(" [")
+			sb.WriteString(name)
+			sb.WriteString("]")
+		}
+		use = sb.String()
+	}
+
 	cmd := &cobra.Command{
-		Use:               route.Use,
+		Use:               use,
 		Aliases:           append([]string(nil), route.Aliases...),
 		Short:             route.Short,
 		Long:              route.Long,
 		Example:           route.Example,
 		Hidden:            route.Hidden,
-		Args:              cobra.NoArgs,
+		Args:              argsValidator,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsonPayload, err := cmd.Flags().GetString("json")
@@ -141,10 +234,27 @@ func NewDirectCommand(route Route, runner executor.Runner) *cobra.Command {
 				params[key] = value
 			}
 
+			// Inject positional args into params according to each binding's
+			// PositionalIndex. Pure positional bindings are not registered as
+			// flags; dual-mode positional bindings (positional + alias) only
+			// fall through to positional injection when their flag aliases
+			// were not used (collectPositionalBindings skips when params
+			// already contains the property).
+			if err := collectPositionalBindings(args, route.Bindings, params); err != nil {
+				return err
+			}
+
 			// Collect schema-derived flags (from buildFlagsFromDetailSchema)
 			// that are not covered by explicit bindings.
 			collectSchemaFlags(cmd, route.Bindings, params)
 
+			// Required-presence check for positional bindings — must run after
+			// both flag (CollectBindings) and positional (collectPositionalBindings)
+			// have had a chance to populate params.
+			if err := validateRequiredPositionalBindings(cmd, route.Bindings, params); err != nil {
+				return err
+			}
+
 			if route.Normalizer != nil {
 				if err := route.Normalizer(cmd, params); err != nil {
 					return err
@@ -180,6 +290,9 @@ func NewDirectCommand(route Route, runner executor.Runner) *cobra.Command {
 			if err != nil {
 				return err
 			}
+			if route.OutputTransform != nil && result.Response != nil {
+				result.Response = route.OutputTransform(result.Response)
+			}
 			return output.WriteCommandPayload(cmd, result, output.FormatJSON)
 		},
 	}
@@ -196,8 +309,64 @@ func NewCuratedCommand(route Route, runner executor.Runner) *cobra.Command {
 	return cmd
 }
 
+// parseFlagDefault converts a string-form envelope default into the typed
+// primitives used by pflag's *P helpers. Unparseable values silently fall
+// back to the type's zero value so a malformed envelope downgrades to
+// "no default in --help" rather than a panic at startup. The slice form
+// splits on commas and trims whitespace, mirroring pflag.StringSlice
+// behavior; empty/whitespace-only segments are dropped.
+func parseFlagDefault(kind ValueKind, raw string) (defStr string, defInt int, defFloat float64, defBool bool, defSlice []string) {
+	trimmed := strings.TrimSpace(raw)
+	switch kind {
+	case ValueString, ValueJSON:
+		// Preserve raw (not trimmed) so explicitly-padded defaults survive.
+		defStr = raw
+	case ValueInt:
+		if trimmed != "" {
+			if v, err := strconv.Atoi(trimmed); err == nil {
+				defInt = v
+			}
+		}
+	case ValueFloat:
+		if trimmed != "" {
+			if v, err := strconv.ParseFloat(trimmed, 64); err == nil {
+				defFloat = v
+			}
+		}
+	case ValueBool:
+		if trimmed != "" {
+			if v, err := strconv.ParseBool(trimmed); err == nil {
+				defBool = v
+			}
+		}
+	case ValueStringSlice, ValueIntSlice, ValueFloatSlice, ValueBoolSlice:
+		if trimmed != "" {
+			for _, p := range strings.Split(trimmed, ",") {
+				if t := strings.TrimSpace(p); t != "" {
+					defSlice = append(defSlice, t)
+				}
+			}
+		}
+	}
+	return
+}
+
 func ApplyBindings(cmd *cobra.Command, bindings []FlagBinding) {
 	for _, binding := range bindings {
+		// Positional bindings are collected from cobra args rather than flags.
+		// Exception: dual-mode bindings (positional + envelope-declared flag
+		// aliases) also register the aliases so users can pass either
+		// `cmd VALUE` or `cmd --primary VALUE`. Required-presence is enforced
+		// later by validateRequiredPositionalBindings instead of MarkFlagRequired.
+		if binding.Positional {
+			primary := strings.TrimSpace(binding.FlagName)
+			alias := strings.TrimSpace(binding.Alias)
+			if primary == "" && alias == "" && len(binding.Aliases) == 0 {
+				continue
+			}
+			registerPositionalAliasFlags(cmd, binding)
+			continue
+		}
 		primary := strings.TrimSpace(binding.FlagName)
 		if primary == "" {
 			continue
@@ -206,43 +375,77 @@ func ApplyBindings(cmd *cobra.Command, bindings []FlagBinding) {
 		if alias == primary {
 			alias = ""
 		}
+		// Dedupe extra aliases against primary + single alias and each other.
+		var extras []string
+		if len(binding.Aliases) > 0 {
+			seen := map[string]bool{primary: true, "json": true, "params": true}
+			if alias != "" {
+				seen[alias] = true
+			}
+			extras = make([]string, 0, len(binding.Aliases))
+			for _, a := range binding.Aliases {
+				a = strings.TrimSpace(a)
+				if a == "" || seen[a] {
+					continue
+				}
+				seen[a] = true
+				extras = append(extras, a)
+			}
+		}
+
+		// Parse binding.Default once per binding into Kind-typed values used
+		// by both the primary and hidden-alias registrations below. Hidden
+		// aliases share the same default so users typing the legacy alias
+		// see consistent --help text and zero-value behavior.
+		defStr, defInt, defFloat, defBool, defSlice := parseFlagDefault(binding.Kind, binding.Default)
+
+		registerHidden := func(name string, suffix string) {
+			if name == "" {
+				return
+			}
+			switch binding.Kind {
+			case ValueString:
+				cmd.Flags().String(name, defStr, binding.Usage+suffix)
+			case ValueInt:
+				cmd.Flags().Int(name, defInt, binding.Usage+suffix)
+			case ValueFloat:
+				cmd.Flags().Float64(name, defFloat, binding.Usage+suffix)
+			case ValueBool:
+				cmd.Flags().Bool(name, defBool, binding.Usage+suffix)
+			case ValueStringSlice, ValueIntSlice, ValueFloatSlice, ValueBoolSlice:
+				cmd.Flags().StringSlice(name, defSlice, binding.Usage+suffix)
+			case ValueJSON:
+				cmd.Flags().String(name, defStr, binding.Usage+suffix)
+			}
+			_ = cmd.Flags().MarkHidden(name)
+		}
 
 		switch binding.Kind {
 		case ValueString:
-			cmd.Flags().StringP(primary, binding.Short, "", binding.Usage)
-			if alias != "" {
-				cmd.Flags().String(alias, "", binding.Usage+" (alias)")
-				_ = cmd.Flags().MarkHidden(alias)
-			}
+			cmd.Flags().StringP(primary, binding.Short, defStr, binding.Usage)
 		case ValueInt:
-			cmd.Flags().IntP(primary, binding.Short, 0, binding.Usage)
-			if alias != "" {
-				cmd.Flags().Int(alias, 0, binding.Usage+" (alias)")
-				_ = cmd.Flags().MarkHidden(alias)
-			}
+			cmd.Flags().IntP(primary, binding.Short, defInt, binding.Usage)
 		case ValueFloat:
-			cmd.Flags().Float64P(primary, binding.Short, 0, binding.Usage)
-			if alias != "" {
-				cmd.Flags().Float64(alias, 0, binding.Usage+" (alias)")
-				_ = cmd.Flags().MarkHidden(alias)
-			}
+			cmd.Flags().Float64P(primary, binding.Short, defFloat, binding.Usage)
 		case ValueBool:
-			cmd.Flags().BoolP(primary, binding.Short, false, binding.Usage)
-			if alias != "" {
-				cmd.Flags().Bool(alias, false, binding.Usage+" (alias)")
-				_ = cmd.Flags().MarkHidden(alias)
-			}
+			cmd.Flags().BoolP(primary, binding.Short, defBool, binding.Usage)
 		case ValueStringSlice, ValueIntSlice, ValueFloatSlice, ValueBoolSlice:
-			cmd.Flags().StringSliceP(primary, binding.Short, nil, binding.Usage)
-			if alias != "" {
-				cmd.Flags().StringSlice(alias, nil, binding.Usage+" (alias)")
-				_ = cmd.Flags().MarkHidden(alias)
-			}
+			cmd.Flags().StringSliceP(primary, binding.Short, defSlice, binding.Usage)
 		case ValueJSON:
-			cmd.Flags().StringP(primary, binding.Short, "", binding.Usage+" (JSON)")
-			if alias != "" {
-				cmd.Flags().String(alias, "", binding.Usage+" (alias, JSON)")
-				_ = cmd.Flags().MarkHidden(alias)
+			cmd.Flags().StringP(primary, binding.Short, defStr, binding.Usage+" (JSON)")
+		}
+		registerHidden(alias, " (alias)")
+		for _, extra := range extras {
+			registerHidden(extra, " (alias)")
+		}
+		if binding.Required {
+			// When no hidden aliases exist, lean on cobra's native required
+			// validation for the best UX (colored error, shown in --help).
+			// When aliases exist, CollectBindings does its own "any-of-these
+			// is set" check so users who type the hidden alias do not hit
+			// cobra yelling about the primary being missing.
+			if alias == "" && len(extras) == 0 {
+				_ = cmd.MarkFlagRequired(primary)
 			}
 		}
 	}
@@ -252,6 +455,165 @@ func ApplyBindings(cmd *cobra.Command, bindings []FlagBinding) {
 	_ = cmd.Flags().MarkHidden("params")
 }
 
+// registerPositionalAliasFlags registers the visible primary flag and any
+// hidden aliases for a "dual-mode" positional binding (envelope:
+// `{positional:true, alias:"X", aliases:["Y"]}`). Required-presence is
+// intentionally deferred to validateRequiredPositionalBindings — cobra's
+// MarkFlagRequired would yell even when the user supplied the value as a
+// positional arg.
+func registerPositionalAliasFlags(cmd *cobra.Command, binding FlagBinding) {
+	primary := strings.TrimSpace(binding.FlagName)
+	alias := strings.TrimSpace(binding.Alias)
+	if alias == primary {
+		alias = ""
+	}
+
+	// Dedupe extras against primary + alias and reserved internal names.
+	seen := map[string]bool{"json": true, "params": true}
+	if primary != "" {
+		seen[primary] = true
+	}
+	if alias != "" {
+		seen[alias] = true
+	}
+	extras := make([]string, 0, len(binding.Aliases))
+	for _, a := range binding.Aliases {
+		a = strings.TrimSpace(a)
+		if a == "" || seen[a] {
+			continue
+		}
+		seen[a] = true
+		extras = append(extras, a)
+	}
+
+	defStr, defInt, defFloat, defBool, defSlice := parseFlagDefault(binding.Kind, binding.Default)
+
+	register := func(name string, withShort bool, hidden bool, usageSuffix string) {
+		if name == "" {
+			return
+		}
+		short := ""
+		if withShort {
+			short = binding.Short
+		}
+		usage := binding.Usage + usageSuffix
+		switch binding.Kind {
+		case ValueString:
+			cmd.Flags().StringP(name, short, defStr, usage)
+		case ValueInt:
+			cmd.Flags().IntP(name, short, defInt, usage)
+		case ValueFloat:
+			cmd.Flags().Float64P(name, short, defFloat, usage)
+		case ValueBool:
+			cmd.Flags().BoolP(name, short, defBool, usage)
+		case ValueStringSlice, ValueIntSlice, ValueFloatSlice, ValueBoolSlice:
+			cmd.Flags().StringSliceP(name, short, defSlice, usage)
+		case ValueJSON:
+			cmd.Flags().StringP(name, short, defStr, usage+" (JSON)")
+		default:
+			cmd.Flags().StringP(name, short, defStr, usage)
+		}
+		if hidden {
+			_ = cmd.Flags().MarkHidden(name)
+		}
+	}
+
+	register(primary, true, false, "")
+	register(alias, false, true, " (alias)")
+	for _, e := range extras {
+		register(e, false, true, " (alias)")
+	}
+}
+
+// collectPositionalBindings pulls positional args according to the bindings
+// and injects them into params[property]. Missing slots are skipped (cobra
+// arity validation already ran before RunE).
+func collectPositionalBindings(args []string, bindings []FlagBinding, params map[string]any) error {
+	for _, binding := range bindings {
+		if !binding.Positional {
+			continue
+		}
+		property := strings.TrimSpace(binding.Property)
+		if property == "" {
+			continue
+		}
+		// Dual-mode positional: if the user already provided the value via a
+		// flag alias (CollectBindings wrote it), honor flag > positional.
+		if _, ok := params[property]; ok {
+			continue
+		}
+		if binding.PositionalIndex < 0 || binding.PositionalIndex >= len(args) {
+			continue
+		}
+		raw := args[binding.PositionalIndex]
+		switch binding.Kind {
+		case ValueInt:
+			v, err := strconv.Atoi(strings.TrimSpace(raw))
+			if err != nil {
+				return apperrors.NewValidation(fmt.Sprintf("positional argument %d (%s) must be int", binding.PositionalIndex, property))
+			}
+			params[property] = v
+		case ValueFloat:
+			v, err := strconv.ParseFloat(strings.TrimSpace(raw), 64)
+			if err != nil {
+				return apperrors.NewValidation(fmt.Sprintf("positional argument %d (%s) must be float", binding.PositionalIndex, property))
+			}
+			params[property] = v
+		case ValueBool:
+			v, err := strconv.ParseBool(strings.TrimSpace(raw))
+			if err != nil {
+				return apperrors.NewValidation(fmt.Sprintf("positional argument %d (%s) must be bool", binding.PositionalIndex, property))
+			}
+			params[property] = v
+		default:
+			params[property] = raw
+		}
+	}
+	return nil
+}
+
+// validateRequiredPositionalBindings enforces required-presence for positional
+// bindings whose original envelope spec set required=true. The arity validator
+// for dual-mode positionals is intentionally relaxed (MaximumNArgs / RangeArgs
+// excluding the dual slot) so a flag-only invocation is permitted; this check
+// closes the loop by rejecting the case where neither the positional arg nor
+// any flag alias was supplied.
+func validateRequiredPositionalBindings(cmd *cobra.Command, bindings []FlagBinding, params map[string]any) error {
+	for _, binding := range bindings {
+		if !binding.Positional || !binding.Required {
+			continue
+		}
+		property := strings.TrimSpace(binding.Property)
+		if property == "" {
+			continue
+		}
+		if v, ok := params[property]; ok {
+			if s, isStr := v.(string); !isStr || strings.TrimSpace(s) != "" {
+				continue
+			}
+		}
+		// Compose candidate flag names so the error message points users at
+		// the first writable label even for flag-only invocations.
+		primary := strings.TrimSpace(binding.FlagName)
+		alias := strings.TrimSpace(binding.Alias)
+		if _, changed := firstChangedFlag(cmd, append([]string{primary, alias}, binding.Aliases...)...); changed {
+			continue
+		}
+		display := primary
+		if display == "" {
+			display = alias
+		}
+		if display == "" && len(binding.Aliases) > 0 {
+			display = binding.Aliases[0]
+		}
+		if display == "" {
+			return apperrors.NewValidation(fmt.Sprintf("positional argument <%s> is required", property))
+		}
+		return apperrors.NewValidation(fmt.Sprintf("--%s (or positional <%s>) is required", display, property))
+	}
+	return nil
+}
+
 // collectSchemaFlags picks up flags created by buildFlagsFromDetailSchema that
 // have no explicit FlagBinding. This bridges the gap for plugin-defined tools
 // whose parameters come from the MCP inputSchema rather than CLIToolOverride.Flags.
@@ -265,6 +627,11 @@ func collectSchemaFlags(cmd *cobra.Command, bindings []FlagBinding, params map[s
 		if a := strings.TrimSpace(b.Alias); a != "" {
 			bound[a] = true
 		}
+		for _, extra := range b.Aliases {
+			if e := strings.TrimSpace(extra); e != "" {
+				bound[e] = true
+			}
+		}
 	}
 
 	// Reserved/internal flags that should never be forwarded as tool params.
@@ -316,36 +683,78 @@ func toOriginalParamName(flagName string) string {
 	return strings.ReplaceAll(flagName, "-", "_")
 }
 
+// firstChangedFlag returns the first name (in order) whose cobra flag has
+// been set by the user. Whitespace-only or empty entries are skipped.
+// Mirrors wukong cmdutil.FlagOrFallback precedence: primary > alias >
+// extraAliases in declaration order.
+func firstChangedFlag(cmd *cobra.Command, names ...string) (name string, changed bool) {
+	for _, n := range names {
+		n = strings.TrimSpace(n)
+		if n == "" {
+			continue
+		}
+		if cobracmd.FlagChanged(cmd, n) {
+			return n, true
+		}
+	}
+	return "", false
+}
+
 func CollectBindings(cmd *cobra.Command, bindings []FlagBinding, existing map[string]any) (map[string]any, error) {
 	if existing == nil {
 		existing = map[string]any{}
 	}
 	params := make(map[string]any)
 	for _, binding := range bindings {
+		if binding.Positional {
+			// Pure positional (no flag aliases) is handled by
+			// collectPositionalBindings. Dual-mode positional bindings
+			// (envelope: positional + alias/aliases) fall through so any
+			// user-supplied flag value wins over the positional arg.
+			primary := strings.TrimSpace(binding.FlagName)
+			alias := strings.TrimSpace(binding.Alias)
+			if primary == "" && alias == "" && len(binding.Aliases) == 0 {
+				continue
+			}
+		}
 		primaryName := strings.TrimSpace(binding.FlagName)
 		if primaryName == "" {
 			continue
 		}
 		aliasName := strings.TrimSpace(binding.Alias)
-		primaryChanged := cobracmd.FlagChanged(cmd, primaryName)
-		aliasChanged := aliasName != "" && cobracmd.FlagChanged(cmd, aliasName)
 
-		flagName := primaryName
-		if aliasChanged {
-			flagName = aliasName
+		// Candidate flag names in precedence order: primary, single alias,
+		// then extra aliases. Whichever is set first wins; mirrors the
+		// semantics of cmdutil.FlagOrFallback.
+		candidates := make([]string, 0, 2+len(binding.Aliases))
+		candidates = append(candidates, primaryName)
+		if aliasName != "" && aliasName != primaryName {
+			candidates = append(candidates, aliasName)
+		}
+		for _, extra := range binding.Aliases {
+			e := strings.TrimSpace(extra)
+			if e == "" || e == primaryName || e == aliasName {
+				continue
+			}
+			candidates = append(candidates, e)
+		}
+
+		flagName, anyChanged := firstChangedFlag(cmd, candidates...)
+		if !anyChanged {
+			flagName = primaryName
 		}
 
 		flag := cmd.Flags().Lookup(flagName)
 		if flag == nil {
 			continue
 		}
-		if binding.Required && !primaryChanged && !aliasChanged {
+		if binding.Required && !anyChanged && !binding.Positional {
 			if _, ok := existing[binding.Property]; ok {
 				continue
 			}
 			return nil, apperrors.NewValidation(fmt.Sprintf("--%s is required", primaryName))
 		}
-		if !primaryChanged && !aliasChanged {
+		if !anyChanged {
 			continue
 		}
 

internal/compat/registry_test.go

@@ -21,6 +21,71 @@ import (
 	"github.com/spf13/cobra"
 )
 
+func TestApplyBindings_PositionalWithFlagAliases(t *testing.T) {
+	t.Parallel()
+
+	// envelope shape: { keyword: { alias: "query", aliases: ["keyword"], positional: true } }
+	bindings := []FlagBinding{
+		{
+			FlagName:        "query",
+			Aliases:         []string{"keyword"},
+			Property:        "keyword",
+			Kind:            ValueString,
+			Usage:           "搜索关键词",
+			Required:        true,
+			Positional:      true,
+			PositionalIndex: 0,
+		},
+	}
+
+	cmd := &cobra.Command{Use: "search"}
+	ApplyBindings(cmd, bindings)
+
+	primary := cmd.Flags().Lookup("query")
+	if primary == nil {
+		t.Fatal("--query flag should be registered for dual-mode positional")
+	}
+	if primary.Hidden {
+		t.Fatal("--query flag should be visible")
+	}
+	hidden := cmd.Flags().Lookup("keyword")
+	if hidden == nil {
+		t.Fatal("--keyword alias flag should be registered")
+	}
+	if !hidden.Hidden {
+		t.Fatal("--keyword alias flag should be hidden")
+	}
+
+	// --query should NOT be marked required at cobra level — that would
+	// break flag-only invocation when arity is relaxed.
+	if _, ok := primary.Annotations[cobra.BashCompOneRequiredFlag]; ok {
+		t.Fatal("--query should not be MarkFlagRequired (validation happens in RunE)")
+	}
+}
+
+func TestApplyBindings_PurePositionalSkipsFlagRegistration(t *testing.T) {
+	t.Parallel()
+
+	// Pure positional (no Alias / no Aliases) → no flag should be registered;
+	// arity validator (set in NewDirectCommand) handles required-presence.
+	bindings := []FlagBinding{
+		{
+			Property:        "text",
+			Kind:            ValueString,
+			Required:        true,
+			Positional:      true,
+			PositionalIndex: 0,
+		},
+	}
+
+	cmd := &cobra.Command{Use: "send"}
+	ApplyBindings(cmd, bindings)
+
+	if f := cmd.Flags().Lookup("text"); f != nil {
+		t.Fatalf("pure positional should not register a flag, got %+v", f)
+	}
+}
+
 func TestCollectBindingsParsesTypedValuesAndAcceptsAliasFlags(t *testing.T) {
 	t.Parallel()
 

internal/compat/v3_helpers_test.go

@@ -0,0 +1,171 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+package compat
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+// TestKindFromTypeName covers the schema v3 explicit Type field → ValueKind map.
+func TestKindFromTypeName(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   string
+		want ValueKind
+	}{
+		{"", ValueString},
+		{"string", ValueString},
+		{"STRING", ValueString},
+		{"int", ValueInt},
+		{"integer", ValueInt},
+		{"number", ValueInt},
+		{"bool", ValueBool},
+		{"boolean", ValueBool},
+		{"stringSlice", ValueStringSlice},
+		{"string_slice", ValueStringSlice},
+		{"[]string", ValueStringSlice},
+		{"weird-unknown-type", ValueString},
+	}
+	for _, tc := range cases {
+		if got := kindFromTypeName(tc.in); got != tc.want {
+			t.Errorf("kindFromTypeName(%q) = %v, want %v", tc.in, got, tc.want)
+		}
+	}
+}
+
+// TestApplyOmitWhen verifies all three modes plus zero-detection.
+func TestApplyOmitWhen(t *testing.T) {
+	t.Parallel()
+
+	t.Run("mode_zero_drops_zero_values", func(t *testing.T) {
+		params := map[string]any{
+			"a": 0,
+			"b": "",
+			"c": false,
+			"d": []any{},
+			"e": map[string]any{},
+			"f": "non-empty",
+			"g": 42,
+		}
+		for k := range params {
+			applyOmitWhen(params, k, "zero")
+		}
+		for _, k := range []string{"a", "b", "c", "d", "e"} {
+			if _, ok := params[k]; ok {
+				t.Errorf("expected key %q to be dropped by omitWhen=zero", k)
+			}
+		}
+		for _, k := range []string{"f", "g"} {
+			if _, ok := params[k]; !ok {
+				t.Errorf("expected key %q to be preserved", k)
+			}
+		}
+	})
+
+	t.Run("mode_never_preserves_zero_values", func(t *testing.T) {
+		params := map[string]any{"explicitFalse": false, "explicitZero": 0}
+		applyOmitWhen(params, "explicitFalse", "never")
+		applyOmitWhen(params, "explicitZero", "never")
+		if len(params) != 2 {
+			t.Errorf("expected both keys preserved under 'never', got %v", params)
+		}
+	})
+
+	t.Run("mode_empty_is_noop", func(t *testing.T) {
+		params := map[string]any{"a": ""}
+		applyOmitWhen(params, "a", "empty")
+		if _, ok := params["a"]; !ok {
+			t.Errorf("empty mode should not drop keys here (upstream CollectBindings does)")
+		}
+	})
+
+	t.Run("missing_key_safe", func(t *testing.T) {
+		params := map[string]any{}
+		applyOmitWhen(params, "nope", "zero")
+		if len(params) != 0 {
+			t.Errorf("expected no-op on missing key, got %v", params)
+		}
+	})
+}
+
+// TestIsZeroValue covers every branch of the helper.
+func TestIsZeroValue(t *testing.T) {
+	t.Parallel()
+	zeros := []any{
+		nil,
+		"",
+		"   ",
+		false,
+		0,
+		int64(0),
+		float64(0),
+		[]any{},
+		[]string{},
+		map[string]any{},
+	}
+	for i, z := range zeros {
+		if !isZeroValue(z) {
+			t.Errorf("case %d: expected zero value for %#v", i, z)
+		}
+	}
+	nonZeros := []any{"x", true, 1, int64(1), float64(1.5), []any{1}, []string{"a"}, map[string]any{"k": 1}}
+	for i, nz := range nonZeros {
+		if isZeroValue(nz) {
+			t.Errorf("case %d: expected non-zero for %#v", i, nz)
+		}
+	}
+}
+
+// TestRuntimeDefaultResolvers_BuiltIns asserts $now and $today always resolve.
+func TestRuntimeDefaultResolvers_BuiltIns(t *testing.T) {
+	// NOTE: not t.Parallel — edition.Get() global state is shared.
+	resolvers := runtimeDefaultResolvers()
+	now := resolvers["$now"]
+	if now == nil {
+		t.Fatal("$now resolver missing")
+	}
+	if v, ok := now(context.Background()); !ok || v == "" {
+		t.Errorf("$now returned empty value: %q ok=%v", v, ok)
+	}
+	today := resolvers["$today"]
+	if today == nil {
+		t.Fatal("$today resolver missing")
+	}
+	if v, ok := today(context.Background()); !ok || !strings.Contains(v, "-") {
+		t.Errorf("$today returned unexpected value: %q ok=%v", v, ok)
+	}
+}
+
+// TestRuntimeDefaultResolvers_OverlayMerge covers the edition overlay hook.
+func TestRuntimeDefaultResolvers_OverlayMerge(t *testing.T) {
+	prev := edition.Get()
+	defer edition.Override(prev)
+
+	edition.Override(&edition.Hooks{
+		RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+			return map[string]edition.RuntimeDefaultFn{
+				"$currentUserId": func(ctx context.Context) (string, bool) {
+					return "test-user-001", true
+				},
+			}
+		},
+	})
+
+	resolvers := runtimeDefaultResolvers()
+	fn := resolvers["$currentUserId"]
+	if fn == nil {
+		t.Fatal("$currentUserId missing after overlay install")
+	}
+	if v, ok := fn(context.Background()); !ok || v != "test-user-001" {
+		t.Errorf("$currentUserId=%q ok=%v", v, ok)
+	}
+}

internal/helpers/chat.go

@@ -60,6 +60,7 @@ func (chatHandler) Command(runner executor.Runner) *cobra.Command {
 		},
 	}
 	message.AddCommand(
+		newChatMessageSendCommand(runner),
 		newChatMessageSendByBotCommand(runner),
 		newChatMessageRecallByBotCommand(runner),
 		newChatMessageSendByWebhookCommand(runner),
@@ -81,6 +82,123 @@ func (chatHandler) Command(runner executor.Runner) *cobra.Command {
 	return root
 }
 
+func newChatMessageSendCommand(runner executor.Runner) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "send",
+		Short: "以当前用户身份发送消息 (--group 群聊 / --user 或 --open-dingtalk-id 单聊)",
+		Long: `以当前用户身份发送群消息或单聊消息。
+
+--group 指定群聊 openConversationId 发群消息；--user 指定 userId 发单聊；
+--open-dingtalk-id 指定 openDingTalkId 发单聊 (适用于无法获取 userId 的场景)。
+三者只能选其一，不能同时指定。
+
+消息内容通过 --text 传入，也可作为位置参数；支持 Markdown。必须提供 --title 作为消息标题。`,
+		Example: `  dws chat message send --group <openconversation_id> --text "hello"
+  dws chat message send --user <userId> --text "请查收"
+  dws chat message send --open-dingtalk-id <openDingTalkId> --title "提醒" --text "请确认"
+  dws chat message send --group <openconversation_id> "hello"`,
+		Args:              cobra.MaximumNArgs(1),
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			params, tool, err := buildChatMessageSendInvocation(cmd, args)
+			if err != nil {
+				return err
+			}
+			invocation := executor.NewHelperInvocation(
+				cobracmd.LegacyCommandPath(cmd),
+				"chat",
+				tool,
+				params,
+			)
+			invocation.DryRun = commandDryRun(cmd)
+			result, err := runner.Run(cmd.Context(), invocation)
+			if err != nil {
+				return err
+			}
+			return writeCommandPayload(cmd, result)
+		},
+	}
+	preferLegacyLeaf(cmd)
+
+	cmd.Flags().String("group", "", "群会话 openConversationId (群聊三选一)")
+	cmd.Flags().String("user", "", "接收人 userId (单聊三选一)")
+	cmd.Flags().String("open-dingtalk-id", "", "接收人 openDingTalkId (单聊三选一)")
+	cmd.Flags().String("text", "", "消息内容，支持 Markdown (也可作位置参数)")
+	cmd.Flags().String("title", "", "消息标题 (可选)")
+	return cmd
+}
+
+func buildChatMessageSendInvocation(cmd *cobra.Command, args []string) (map[string]any, string, error) {
+	guard := cli.NewStdinGuard()
+
+	group, err := cmd.Flags().GetString("group")
+	if err != nil {
+		return nil, "", apperrors.NewInternal("failed to read --group")
+	}
+	user, err := cmd.Flags().GetString("user")
+	if err != nil {
+		return nil, "", apperrors.NewInternal("failed to read --user")
+	}
+	openID, err := cmd.Flags().GetString("open-dingtalk-id")
+	if err != nil {
+		return nil, "", apperrors.NewInternal("failed to read --open-dingtalk-id")
+	}
+	title, err := resolveStringFlag(cmd, "title", guard, false)
+	if err != nil {
+		return nil, "", err
+	}
+	// --text is the primary content flag: receives stdin pipe and positional
+	// fallback when empty.
+	text, err := resolveStringFlag(cmd, "text", guard, true)
+	if err != nil {
+		return nil, "", err
+	}
+	if strings.TrimSpace(text) == "" && len(args) > 0 {
+		text = args[0]
+	}
+
+	hasGroup := strings.TrimSpace(group) != ""
+	hasUser := strings.TrimSpace(user) != ""
+	hasOpenID := strings.TrimSpace(openID) != ""
+	specified := 0
+	if hasGroup {
+		specified++
+	}
+	if hasUser {
+		specified++
+	}
+	if hasOpenID {
+		specified++
+	}
+	switch specified {
+	case 0:
+		return nil, "", apperrors.NewValidation("one of --group, --user, or --open-dingtalk-id is required")
+	case 1:
+	default:
+		return nil, "", apperrors.NewValidation("--group, --user, and --open-dingtalk-id are mutually exclusive")
+	}
+	if strings.TrimSpace(text) == "" {
+		return nil, "", apperrors.NewValidation("--text (or positional argument) is required")
+	}
+
+	params := map[string]any{"text": text}
+	if strings.TrimSpace(title) != "" {
+		params["title"] = title
+	}
+
+	switch {
+	case hasGroup:
+		params["openConversation_id"] = group
+		return params, "send_message_as_user", nil
+	case hasUser:
+		params["receiverUserId"] = user
+		return params, "send_direct_message_as_user", nil
+	default:
+		params["receiverOpenDingTalkId"] = openID
+		return params, "send_direct_message_as_user", nil
+	}
+}
+
 func newChatMessageSendByBotCommand(runner executor.Runner) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "send-by-bot",

internal/helpers/chat_test.go

@@ -3,6 +3,7 @@ package helpers
 import (
 	"bytes"
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
@@ -48,6 +49,108 @@ func TestChatMessageSendByBotIgnoresLegacyRealBuildModeEnv(t *testing.T) {
 	}
 }
 
+func TestChatMessageSendRoutesByDestination(t *testing.T) {
+	cases := []struct {
+		name      string
+		args      []string
+		wantTool  string
+		wantKey   string
+		wantValue string
+	}{
+		{
+			name:      "group",
+			args:      []string{"--group", "cid-xyz", "--text", "hello"},
+			wantTool:  "send_message_as_user",
+			wantKey:   "openConversation_id",
+			wantValue: "cid-xyz",
+		},
+		{
+			name:      "user-direct",
+			args:      []string{"--user", "034766", "--text", "hi"},
+			wantTool:  "send_direct_message_as_user",
+			wantKey:   "receiverUserId",
+			wantValue: "034766",
+		},
+		{
+			name:      "open-dingtalk-id-direct",
+			args:      []string{"--open-dingtalk-id", "OP123", "--text", "hi"},
+			wantTool:  "send_direct_message_as_user",
+			wantKey:   "receiverOpenDingTalkId",
+			wantValue: "OP123",
+		},
+		{
+			name:      "positional-text",
+			args:      []string{"--group", "cid-xyz", "hello from positional"},
+			wantTool:  "send_message_as_user",
+			wantKey:   "text",
+			wantValue: "hello from positional",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			runner := &captureRunner{}
+			cmd := newChatMessageSendCommand(runner)
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetErr(&out)
+			cmd.SetArgs(tc.args)
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v\noutput:\n%s", err, out.String())
+			}
+			if got := runner.last.Tool; got != tc.wantTool {
+				t.Fatalf("Tool = %q, want %q", got, tc.wantTool)
+			}
+			if got := runner.last.CanonicalProduct; got != "chat" {
+				t.Fatalf("CanonicalProduct = %q, want chat", got)
+			}
+			if got, ok := runner.last.Params[tc.wantKey]; !ok || got != tc.wantValue {
+				t.Fatalf("Params[%q] = %#v, want %q", tc.wantKey, got, tc.wantValue)
+			}
+		})
+	}
+}
+
+func TestChatMessageSendRejectsInvalidDestination(t *testing.T) {
+	cases := []struct {
+		name    string
+		args    []string
+		wantErr string
+	}{
+		{
+			name:    "no-destination",
+			args:    []string{"--text", "hi"},
+			wantErr: "one of --group, --user, or --open-dingtalk-id is required",
+		},
+		{
+			name:    "group-and-user",
+			args:    []string{"--group", "cid-x", "--user", "034766", "--text", "hi"},
+			wantErr: "--group, --user, and --open-dingtalk-id are mutually exclusive",
+		},
+		{
+			name:    "empty-text",
+			args:    []string{"--group", "cid-x"},
+			wantErr: "--text (or positional argument) is required",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			runner := &captureRunner{}
+			cmd := newChatMessageSendCommand(runner)
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetErr(&out)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			if err == nil {
+				t.Fatalf("expected error, got nil; output: %s", out.String())
+			}
+			if got := err.Error(); !strings.Contains(got, tc.wantErr) {
+				t.Fatalf("error = %q, want to contain %q", got, tc.wantErr)
+			}
+		})
+	}
+}
+
 func TestChatMessageSendByBotRoutesToBotProduct(t *testing.T) {
 	cases := []struct {
 		name     string

internal/keychain/keychain.go

@@ -23,6 +23,13 @@ const (
 
 	// AccountToken is the account key for storing auth token data.
 	AccountToken = "auth-token"
+
+	// StorageDirEnv overrides the on-disk keychain storage root on
+	// platforms that use file-backed storage (macOS, Linux). It is
+	// intended for tests that need to isolate keychain state from the
+	// real user environment and from sibling test packages running in
+	// parallel. When empty, the platform default applies.
+	StorageDirEnv = "DWS_KEYCHAIN_DIR"
 )
 
 // KeychainAccess abstracts keychain Get/Set/Remove for dependency injection.

internal/keychain/keychain_darwin.go

@@ -40,7 +40,12 @@ const (
 
 // StorageDir returns the storage directory for a given service name on macOS.
 // Uses ~/Library/Application Support/<service> following Apple conventions.
+// When the DWS_KEYCHAIN_DIR environment variable is set (used by tests for
+// isolation), the storage root is taken from that env var instead.
 func StorageDir(service string) string {
+	if override := os.Getenv(StorageDirEnv); override != "" {
+		return filepath.Join(override, service)
+	}
 	home, err := os.UserHomeDir()
 	if err != nil || home == "" {
 		return filepath.Join(".dws", "keychain", service)

internal/keychain/keychain_linux.go

@@ -34,8 +34,13 @@ const (
 )
 
 // StorageDir returns the storage directory for a given service name.
-// Follows XDG Base Directory Specification: ~/.local/share/<service>
+// Follows XDG Base Directory Specification: ~/.local/share/<service>.
+// When the DWS_KEYCHAIN_DIR environment variable is set (used by tests for
+// isolation), the storage root is taken from that env var instead.
 func StorageDir(service string) string {
+	if override := os.Getenv(StorageDirEnv); override != "" {
+		return filepath.Join(override, service)
+	}
 	home, err := os.UserHomeDir()
 	if err != nil || home == "" {
 		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)

internal/market/registry.go

@@ -38,6 +38,7 @@ const (
 type Client struct {
 	BaseURL    string
 	HTTPClient *http.Client
+	Headers    map[string]string
 }
 
 type ListResponse struct {
@@ -48,6 +49,26 @@ type ListResponse struct {
 type ListMetadata struct {
 	Count      int    `json:"count"`
 	NextCursor string `json:"nextCursor"`
+	// Warnings is populated by the Portal merge service when envelopes are
+	// dropped (e.g. missing serverDeps, status != active) or when a dangling
+	// serverDeps / toolOverrides.*.serverOverride reference is detected.
+	// Old Portals without the field simply leave this nil. CLI side should
+	// treat any non-empty slice as non-fatal informational output: print to
+	// stderr so cache refreshes expose Portal drift to the user, but do not
+	// fail the discovery load.
+	//
+	// See plan fix-wukong-discovery-missing-servers Phase 4.2/4.3.
+	Warnings []ListWarning `json:"warnings,omitempty"`
+}
+
+// ListWarning describes one envelope that was filtered out of the merged
+// response or flagged for dangling references. Fields mirror the JSON emitted
+// by WukongDiscoveryRegistry.buildWarning on the Portal side; unknown reason
+// codes are passed through verbatim for forward compatibility.
+type ListWarning struct {
+	ProductID string `json:"productId"`
+	Reason    string `json:"reason"`
+	Detail    string `json:"detail"`
 }
 
 type ServerEnvelope struct {
@@ -97,6 +118,37 @@ type CLIOverlay struct {
 	Tools         []CLITool                  `json:"tools"`
 	Groups        map[string]CLIGroupDef     `json:"groups,omitempty"`
 	ToolOverrides map[string]CLIToolOverride `json:"toolOverrides,omitempty"`
+	// ServerDeps declares other product IDs that this overlay depends on at
+	// runtime (e.g. chat depends on bot for cross-server tool routing).
+	// Consumed by the portal merge service for fail-fast validation; CLI side
+	// currently only stores the value for tooling/introspection.
+	ServerDeps []string `json:"serverDeps,omitempty"`
+	// Hints registers stub sub-commands under the overlay root that only
+	// print a redirect message pointing to the canonical command path. Used
+	// for deprecated command aliases and "did-you-mean" style hints.
+	// Key is the sub-command name; value describes the target path.
+	Hints map[string]CLIHintDef `json:"hintCommands,omitempty"`
+	// RedirectTo, when non-empty, turns the entire top-level product into a
+	// stub that prints "Please use: dws <target>" and performs no work. Used
+	// for deprecated top-level products migrated to new paths (e.g.
+	// `bot → chat bot`, `message → chat message`). See schema v3 §2.6.
+	RedirectTo string `json:"redirectTo,omitempty"`
+}
+
+// CLIHintDef declares a stub sub-command that prints a redirect message.
+// The command takes no bindings and calls no tool; its sole purpose is to
+// help users migrate from an old command path to the new one.
+type CLIHintDef struct {
+	// Target is the canonical command path shown in the redirect message
+	// (e.g. "dws chat message list").
+	Target string `json:"target"`
+	// Description overrides the Short/Long help text for the hint command.
+	// Empty falls back to a generic "use: <target>" string.
+	Description string `json:"description,omitempty"`
+	// Group optionally nests the hint under a named sub-group (same syntax
+	// as CLIToolOverride.Group with dot-separated paths). Empty means the
+	// hint is attached directly to the overlay root.
+	Group string `json:"group,omitempty"`
 }
 
 // CLIGroupDef defines a sub-command group within a CLI module.
@@ -104,25 +156,111 @@ type CLIGroupDef struct {
 	Description string `json:"description"`
 }
 
+// CLIOutputFormat declares structured post-processing applied to the MCP tool
+// response before the formatter prints it. See schema v3 §2.5.
+//
+// Apply order: Drop → Rename → Columns. All three are optional.
+type CLIOutputFormat struct {
+	// Rename moves fields from src key to dst key at top level and one level
+	// of nested objects. Missing src keys are silently ignored.
+	Rename map[string]string `json:"rename,omitempty"`
+	// Drop removes these keys from the response (top level + one level deep).
+	Drop []string `json:"drop,omitempty"`
+	// Columns controls column order and subset for --format=table. Ignored in
+	// JSON output mode.
+	Columns []string `json:"columns,omitempty"`
+}
+
 // CLIToolOverride maps an MCP tool to a CLI command with flag aliases and transforms.
 type CLIToolOverride struct {
-	CLIName      string                     `json:"cliName"`
-	Description  string                     `json:"description,omitempty"`
-	Group        string                     `json:"group,omitempty"`
-	IsSensitive  bool                       `json:"isSensitive,omitempty"`
-	Hidden       bool                       `json:"hidden,omitempty"`
-	Flags        map[string]CLIFlagOverride `json:"flags,omitempty"`
-	OutputFormat map[string]any             `json:"outputFormat,omitempty"`
+	CLIName     string `json:"cliName"`
+	Description string `json:"description,omitempty"`
+	// Example, when non-empty, is wired to cobra.Command.Example to render
+	// the "Examples:" section in --help. Mirrors hardcoded helper commands'
+	// Example field (e.g. wukong/products/oa.go list-forms). Empty value
+	// produces no Examples section. Multi-line strings keep "\n" literally.
+	Example     string                     `json:"example,omitempty"`
+	Group       string                     `json:"group,omitempty"`
+	IsSensitive bool                       `json:"isSensitive,omitempty"`
+	Hidden      bool                       `json:"hidden,omitempty"`
+	Flags       map[string]CLIFlagOverride `json:"flags,omitempty"`
+	// OutputFormat declares structured response post-processing. v3 typed form
+	// supersedes v2's untyped map[string]any, but parsing stays lenient so v2
+	// envelopes continue to deserialize (unknown keys are ignored).
+	OutputFormat CLIOutputFormat `json:"outputFormat,omitempty"`
+	// ServerOverride routes this leaf command's tool invocation to a different
+	// product's MCP server (e.g. `chat bot ...` leaves live under the `chat`
+	// command tree but call the `bot` endpoint). Empty means use the enclosing
+	// overlay's server.
+	ServerOverride string `json:"serverOverride,omitempty"`
+	// BodyWrapper, when non-empty, wraps the collected params map under this
+	// single key before the invocation is dispatched. Useful when the upstream
+	// tool expects a typed DTO wrapper (e.g. `PersonalTodoCreateVO`). Only
+	// user-provided params are wrapped; internal control keys starting with
+	// '_' (e.g. `_blocked`, `_yes`) are preserved at the top level.
+	BodyWrapper string `json:"bodyWrapper,omitempty"`
+	// MutuallyExclusive groups flag aliases that must not be set together.
+	// Each inner slice becomes one cobra.MarkFlagsMutuallyExclusive call.
+	// Example: [["group","user","open-dingtalk-id"]] for `chat message list`.
+	MutuallyExclusive [][]string `json:"mutuallyExclusive,omitempty"`
+	// RequireOneOf groups flag aliases where at least one must be set. Each
+	// inner slice becomes one cobra.MarkFlagsOneRequired call. Typically
+	// paired with MutuallyExclusive to enforce "exactly one of".
+	RequireOneOf [][]string `json:"requireOneOf,omitempty"`
+	// RedirectTo, when non-empty, turns this entry into a stub command that
+	// prints the redirect target instead of invoking a tool. All other
+	// fields (Flags / BodyWrapper / IsSensitive / ServerOverride) are
+	// ignored. Use for deprecated leaf commands that moved to a new path.
+	RedirectTo string `json:"redirectTo,omitempty"`
 }
 
 // CLIFlagOverride describes how to map an MCP parameter to a CLI flag.
 type CLIFlagOverride struct {
-	Alias         string         `json:"alias"`
+	Alias string `json:"alias"`
+	// Aliases registers additional hidden CLI flag names for the same MCP
+	// parameter. Use to preserve legacy flag names when migrating from
+	// hardcoded commands (mirrors cmdutil.ValidateRequiredFlagWithAliases /
+	// cmdutil.FlagOrFallback). All entries are registered as hidden flags
+	// (not shown in --help); values are deduped against the primary flag
+	// name and Alias, and reserved names ("json", "params") are skipped.
+	// When any alias is set by the user, the binding's Required check is
+	// satisfied and the value is written to params[Property].
+	Aliases       []string       `json:"aliases,omitempty"`
 	Transform     string         `json:"transform,omitempty"`
 	TransformArgs map[string]any `json:"transformArgs,omitempty"`
 	EnvDefault    string         `json:"envDefault,omitempty"`
 	Hidden        bool           `json:"hidden,omitempty"`
 	Default       string         `json:"default,omitempty"`
+	// Shorthand registers a single-char flag alias (cobra StringP etc.).
+	Shorthand string `json:"shorthand,omitempty"`
+	// Required marks this flag as mandatory via cobra.MarkFlagRequired.
+	// Ignored when Positional is true (positional args have their own arity rules).
+	Required bool `json:"required,omitempty"`
+	// Description overrides the usage string displayed in --help; takes
+	// priority over the Detail API's toolDesc when non-empty.
+	Description string `json:"description,omitempty"`
+	// Positional, when true, binds this parameter to a positional CLI argument
+	// instead of a --flag. PositionalIndex (0-based) selects which arg slot.
+	Positional      bool `json:"positional,omitempty"`
+	PositionalIndex int  `json:"positionalIndex,omitempty"`
+	// Type explicitly declares the flag's type: "string" (default) / "int" /
+	// "bool" / "stringSlice". When set, overrides the type inferred from MCP
+	// tools/list inputSchema. See schema v3 §2.1.
+	Type string `json:"type,omitempty"`
+	// OmitWhen declares empty-value handling when building the invocation body:
+	//
+	//   "empty" (default): empty string / zero-length slice-or-map → omit
+	//   "zero":            + zero numbers / false booleans → omit
+	//   "never":           always send, even at zero value (explicit-zero semantics)
+	//
+	// See schema v3 §2.2.
+	OmitWhen string `json:"omitWhen,omitempty"`
+	// RuntimeDefault, when non-empty, injects a runtime-resolved value if the
+	// user omits the flag. Allowed placeholders: "$currentUserId" / "$unionId"
+	// / "$corpId" / "$now" / "$today". Unknown placeholders → warning + skip.
+	// Resolution comes from edition.Hooks.RuntimeDefaults; open-source core
+	// only recognises the placeholder set. See schema v3 §2.3.
+	RuntimeDefault string `json:"runtimeDefault,omitempty"`
 }
 
 type CLITool struct {
@@ -256,6 +394,9 @@ func (c *Client) FetchServersFromURL(ctx context.Context, fullURL string) (ListR
 	if err != nil {
 		return ListResponse{}, apperrors.NewDiscovery("failed to create servers request")
 	}
+	for k, v := range c.Headers {
+		req.Header.Set(k, v)
+	}
 	resp, err := c.HTTPClient.Do(req)
 	if err != nil {
 		return ListResponse{}, apperrors.NewDiscovery(fmt.Sprintf("servers request failed: %v", err))
@@ -289,6 +430,9 @@ func (c *Client) fetchServersPage(ctx context.Context, limit int, cursor string)
 	if err != nil {
 		return ListResponse{}, apperrors.NewDiscovery("failed to create market servers request")
 	}
+	for k, v := range c.Headers {
+		req.Header.Set(k, v)
+	}
 	resp, err := c.HTTPClient.Do(req)
 	if err != nil {
 		return ListResponse{}, apperrors.NewDiscovery(fmt.Sprintf("market servers request failed: %v", err))

pkg/authretry/authretry.go

@@ -0,0 +1,74 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package authretry exposes the AuthRefreshRequired marker error used by
+// edition overlays (in separate Go modules) to signal "the current access
+// token was rejected by the server; please run a force-refresh and retry".
+//
+// The package has no dependencies beyond the standard library so it can be
+// imported by both the runner (internal/app) and external overlays without
+// creating import cycles with packages such as pkg/runtimetoken.
+package authretry
+
+import (
+	stderrors "errors"
+)
+
+// AuthRefreshRequired is a marker error returned by overlays (typically from
+// the edition's ClassifyToolResult or OnAuthError hook) to ask the runner to
+// perform a one-shot ForceRefresh of the access token and retry the current
+// invocation.
+//
+// Open-source code paths never produce this type, so the runner's retry
+// branch is a no-op for editions that don't opt in.
+type AuthRefreshRequired struct {
+	// Cause is the underlying user-facing error. The runner returns Cause
+	// (not the wrapper) when refresh fails or the retry budget is exhausted,
+	// so end users always see the original diagnostic instead of an internal
+	// "auth refresh required" message.
+	Cause error
+}
+
+// Error returns the underlying cause's message, or a generic fallback when
+// Cause is nil.
+func (e *AuthRefreshRequired) Error() string {
+	if e == nil || e.Cause == nil {
+		return "authentication refresh required"
+	}
+	return e.Cause.Error()
+}
+
+// Unwrap exposes the underlying cause to errors.Is / errors.As.
+func (e *AuthRefreshRequired) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// As walks the error chain and returns the first *AuthRefreshRequired it
+// finds, along with true. Returns nil, false otherwise.
+//
+// Use this instead of a plain errors.As when callers care about acting on
+// the marker (force-refresh + retry) rather than just identifying the
+// underlying error class.
+func As(err error) (*AuthRefreshRequired, bool) {
+	if err == nil {
+		return nil, false
+	}
+	var target *AuthRefreshRequired
+	if stderrors.As(err, &target) {
+		return target, true
+	}
+	return nil, false
+}

pkg/cmdutil/leaf_merge.go

@@ -0,0 +1,115 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmdutil
+
+import (
+	"log/slog"
+
+	"github.com/spf13/cobra"
+)
+
+// MergeHardcodedLeaves grafts leaves from hardcodedRoot onto dynamicRoot when
+// the same-named path does not already exist. Groups recurse. On leaf
+// conflicts the dynamic side wins by default, because the discovery envelope
+// is the runtime authority — hardcoded commands are retained only as a
+// leaf-level fallback for behaviour the envelope explicitly does not
+// declare. See _docs/discovery-overlay-authority.md.
+//
+// Explicit opt-in override: a hardcoded leaf may promote itself over a
+// same-named dynamic leaf by carrying a strictly higher OverridePriority
+// (see SetOverridePriority / OverridePriority). This exists for the narrow
+// case where the envelope exposes one dispatch path but the hardcoded leaf
+// needs richer flag-based routing (e.g. `chat message send` fanning out to
+// multiple MCP tools depending on --group vs --user), which the envelope
+// cannot currently express. Helpers without the annotation still lose to
+// the envelope, so the default authority contract is preserved.
+//
+// PRECONDITION: dynamicRoot must be envelope-sourced (carry the
+// SourceAnnotation=SourceEnvelope marker set by BuildDynamicCommands via
+// MarkEnvelopeSource). Callers that might otherwise pass a helper-fallback
+// root with the same name are responsible for evicting it upstream —
+// otherwise the "envelope is authority" rule silently promotes helper leaves
+// over same-named hardcoded leaves and the overlay loses its ability to
+// override routing. The wukong overlay's RegisterProducts gates this call on
+// IsEnvelopeSourced(dynamicRoot); new callers must do the same.
+//
+// Conflict resolution table:
+//
+//	dynamic  hardcoded                          →  action
+//	-------  ---------------------------------  -----------------------------
+//	absent   anything                              graft hardcoded subtree
+//	leaf     leaf (hc priority ≤ dyn)              dynamic wins (no-op)
+//	leaf     leaf (hc priority > dyn)              hardcoded replaces dynamic
+//	group    group                                 recurse
+//	leaf     group                                 dynamic wins, warn
+//	group    leaf                                  dynamic wins, warn
+//
+// MergeHardcodedLeaves mutates dynamicRoot in place and returns it so callers
+// can chain. hardcodedRoot is treated as a donor: grafted children are
+// detached from it so their cobra parent pointer points at the new parent.
+func MergeHardcodedLeaves(dynamicRoot, hardcodedRoot *cobra.Command) *cobra.Command {
+	if dynamicRoot == nil || hardcodedRoot == nil {
+		return dynamicRoot
+	}
+	// Snapshot children before mutating hardcodedRoot — RemoveCommand during
+	// iteration over hardcodedRoot.Commands() is unsafe because cobra returns
+	// a slice backed by an internal field that is re-sliced on removal.
+	children := append([]*cobra.Command(nil), hardcodedRoot.Commands()...)
+	for _, hc := range children {
+		dyn := findChildByName(dynamicRoot, hc.Name())
+		switch {
+		case dyn == nil:
+			hardcodedRoot.RemoveCommand(hc)
+			dynamicRoot.AddCommand(hc)
+		case IsLeafCmd(hc) && IsLeafCmd(dyn):
+			if OverridePriority(hc) > OverridePriority(dyn) {
+				hardcodedRoot.RemoveCommand(hc)
+				dynamicRoot.RemoveCommand(dyn)
+				dynamicRoot.AddCommand(hc)
+			}
+			// else: envelope is authority; hardcoded leaf is ignored.
+		case !IsLeafCmd(hc) && !IsLeafCmd(dyn):
+			MergeHardcodedLeaves(dyn, hc)
+		default:
+			slog.Warn("overlay: shape mismatch, keeping dynamic",
+				"name", hc.Name(),
+				"dynamicIsLeaf", IsLeafCmd(dyn),
+				"hardcodedIsLeaf", IsLeafCmd(hc))
+		}
+	}
+	return dynamicRoot
+}
+
+// IsLeafCmd reports whether a command has no subcommands. Leaves carry a RunE
+// and are invocation targets; groups merely organise subcommands.
+func IsLeafCmd(cmd *cobra.Command) bool {
+	if cmd == nil {
+		return false
+	}
+	return !cmd.HasSubCommands()
+}
+
+// findChildByName scans parent's direct children for a matching Name(). A
+// local helper so pkg/cmdutil stays independent of internal/cobracmd.
+func findChildByName(parent *cobra.Command, name string) *cobra.Command {
+	if parent == nil {
+		return nil
+	}
+	for _, child := range parent.Commands() {
+		if child.Name() == name {
+			return child
+		}
+	}
+	return nil
+}

pkg/cmdutil/leaf_merge_test.go

@@ -0,0 +1,198 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmdutil
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// newGroup returns a group command with the given children attached.
+func newGroup(name string, children ...*cobra.Command) *cobra.Command {
+	cmd := &cobra.Command{Use: name}
+	cmd.AddCommand(children...)
+	return cmd
+}
+
+// newLeaf returns a leaf command tagged via Short so tests can verify which
+// variant (dynamic or hardcoded) wins without introducing a priority system.
+func newLeaf(name, tag string) *cobra.Command {
+	return &cobra.Command{Use: name, Short: tag}
+}
+
+func TestMergeHardcodedLeaves_NilInputs(t *testing.T) {
+	t.Parallel()
+	if got := MergeHardcodedLeaves(nil, nil); got != nil {
+		t.Fatalf("expected nil, got %v", got)
+	}
+	dyn := newGroup("root")
+	if got := MergeHardcodedLeaves(dyn, nil); got != dyn {
+		t.Fatal("expected dyn to be returned unchanged")
+	}
+	hc := newGroup("root")
+	if got := MergeHardcodedLeaves(nil, hc); got != nil {
+		t.Fatal("expected nil when dynamicRoot is nil")
+	}
+}
+
+func TestMergeHardcodedLeaves_GraftsUnknownLeaf(t *testing.T) {
+	t.Parallel()
+	dyn := newGroup("root", newLeaf("kept", "dynamic"))
+	hc := newGroup("root", newLeaf("extra", "hardcoded"))
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	got := findChildByName(dyn, "extra")
+	if got == nil {
+		t.Fatal("expected extra leaf to be grafted onto dyn")
+	}
+	if got.Short != "hardcoded" {
+		t.Fatalf("extra.Short = %q, want %q", got.Short, "hardcoded")
+	}
+	if findChildByName(hc, "extra") != nil {
+		t.Fatal("expected extra to be detached from hardcodedRoot")
+	}
+	if got.Parent() != dyn {
+		t.Fatalf("grafted leaf parent = %v, want %v", got.Parent(), dyn)
+	}
+}
+
+func TestMergeHardcodedLeaves_DynamicLeafWins(t *testing.T) {
+	t.Parallel()
+	dyn := newGroup("root", newLeaf("shared", "dynamic"))
+	hc := newGroup("root", newLeaf("shared", "hardcoded"))
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	got := findChildByName(dyn, "shared")
+	if got == nil {
+		t.Fatal("expected shared leaf to remain on dyn")
+	}
+	if got.Short != "dynamic" {
+		t.Fatalf("shared.Short = %q, want %q (dynamic must win)", got.Short, "dynamic")
+	}
+	if findChildByName(hc, "shared") == nil {
+		t.Fatal("expected hardcoded.shared to remain on hardcodedRoot (not grafted)")
+	}
+}
+
+func TestMergeHardcodedLeaves_HigherPriorityHardcodedOverridesDynamic(t *testing.T) {
+	t.Parallel()
+	dynLeaf := newLeaf("shared", "dynamic")
+	dyn := newGroup("root", dynLeaf)
+	hcLeaf := newLeaf("shared", "hardcoded")
+	SetOverridePriority(hcLeaf, 100)
+	hc := newGroup("root", hcLeaf)
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	got := findChildByName(dyn, "shared")
+	if got == nil {
+		t.Fatal("expected shared leaf on dyn after merge")
+	}
+	if got != hcLeaf {
+		t.Fatalf("expected hardcoded leaf to replace dynamic; got Short=%q", got.Short)
+	}
+	if findChildByName(hc, "shared") != nil {
+		t.Fatal("expected hardcoded.shared to be moved off hardcodedRoot after replacement")
+	}
+}
+
+func TestMergeHardcodedLeaves_EqualPriorityKeepsDynamic(t *testing.T) {
+	t.Parallel()
+	dynLeaf := newLeaf("shared", "dynamic")
+	SetOverridePriority(dynLeaf, 100)
+	dyn := newGroup("root", dynLeaf)
+	hcLeaf := newLeaf("shared", "hardcoded")
+	SetOverridePriority(hcLeaf, 100)
+	hc := newGroup("root", hcLeaf)
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	got := findChildByName(dyn, "shared")
+	if got != dynLeaf {
+		t.Fatalf("equal priorities must keep dynamic; got Short=%q", got.Short)
+	}
+}
+
+func TestMergeHardcodedLeaves_RecurseGroups(t *testing.T) {
+	t.Parallel()
+	dyn := newGroup("root",
+		newGroup("space",
+			newLeaf("list", "dynamic"),
+		),
+	)
+	hc := newGroup("root",
+		newGroup("space",
+			newLeaf("list", "hardcoded"),   // dynamic wins
+			newLeaf("create", "hardcoded"), // grafted
+		),
+		newLeaf("ping", "hardcoded"), // grafted top-level
+	)
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	space := findChildByName(dyn, "space")
+	if space == nil {
+		t.Fatal("expected space group on dyn")
+	}
+	if l := findChildByName(space, "list"); l == nil || l.Short != "dynamic" {
+		t.Fatalf("space.list should remain dynamic, got %+v", l)
+	}
+	if c := findChildByName(space, "create"); c == nil || c.Short != "hardcoded" {
+		t.Fatalf("space.create should be grafted from hardcoded, got %+v", c)
+	}
+	if p := findChildByName(dyn, "ping"); p == nil || p.Short != "hardcoded" {
+		t.Fatalf("ping should be grafted from hardcoded, got %+v", p)
+	}
+}
+
+func TestMergeHardcodedLeaves_ShapeMismatch_KeepsDynamic(t *testing.T) {
+	t.Parallel()
+	// Dynamic declares `cmd` as a group; hardcoded declares `cmd` as a leaf.
+	// Shape mismatch — dynamic wins, warning logged, hardcoded leaf discarded.
+	dyn := newGroup("root",
+		newGroup("cmd", newLeaf("sub", "dynamic")),
+	)
+	hc := newGroup("root", newLeaf("cmd", "hardcoded"))
+
+	MergeHardcodedLeaves(dyn, hc)
+
+	cmd := findChildByName(dyn, "cmd")
+	if cmd == nil {
+		t.Fatal("expected cmd to remain on dyn")
+	}
+	if IsLeafCmd(cmd) {
+		t.Fatal("expected dynamic cmd to remain a group")
+	}
+	if findChildByName(cmd, "sub") == nil {
+		t.Fatal("expected cmd.sub to remain")
+	}
+}
+
+func TestIsLeafCmd(t *testing.T) {
+	t.Parallel()
+	leaf := newLeaf("x", "")
+	group := newGroup("x", newLeaf("child", ""))
+	if !IsLeafCmd(leaf) {
+		t.Fatal("expected leaf to be a leaf")
+	}
+	if IsLeafCmd(group) {
+		t.Fatal("expected group to not be a leaf")
+	}
+	if IsLeafCmd(nil) {
+		t.Fatal("expected nil to not be a leaf")
+	}
+}

pkg/cmdutil/override_priority.go

@@ -0,0 +1,57 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmdutil
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// OverridePriorityAnnotation is the cobra.Command.Annotations key used to
+// declare a command's merge-time override priority. Higher values win when
+// same-named leaves collide during merge. Exported so overlays and helpers
+// can reference the same key as the core merge logic without spelling drift.
+const OverridePriorityAnnotation = "dws.override-priority"
+
+// SetOverridePriority stamps the override priority annotation on cmd. A
+// positive value asks the merge layer to promote this command over a
+// same-named leaf with a lower (or unset) priority.
+func SetOverridePriority(cmd *cobra.Command, priority int) {
+	if cmd == nil {
+		return
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[OverridePriorityAnnotation] = strconv.Itoa(priority)
+}
+
+// OverridePriority returns the override priority annotation value on cmd,
+// or 0 if the annotation is absent or malformed.
+func OverridePriority(cmd *cobra.Command) int {
+	if cmd == nil || cmd.Annotations == nil {
+		return 0
+	}
+	raw := strings.TrimSpace(cmd.Annotations[OverridePriorityAnnotation])
+	if raw == "" {
+		return 0
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		return 0
+	}
+	return value
+}

pkg/cmdutil/provenance.go

@@ -0,0 +1,54 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmdutil
+
+import "github.com/spf13/cobra"
+
+// SourceAnnotation is the cobra.Command.Annotations key used to record where
+// a top-level command came from. Edition overlays (e.g. wukong) read this
+// annotation to distinguish envelope-authored dynamic commands from
+// helper-fallback commands that merely happen to share a name. Keeping the
+// key and value literals in one place prevents spelling drift between the
+// core (which sets the annotation) and overlays (which read it).
+const SourceAnnotation = "dws.source"
+
+// SourceEnvelope marks a command as authored by the discovery envelope and
+// therefore authoritative at runtime. Only commands built from a
+// market.ServerDescriptor / CLIOverlay should carry this value. Helper
+// fallbacks and other sources must leave the annotation unset.
+const SourceEnvelope = "envelope"
+
+// MarkEnvelopeSource stamps the envelope provenance annotation on cmd.
+// Safe to call on commands that may not have an Annotations map yet.
+// Callers in core code are the only ones that should invoke this — overlays
+// read the annotation but must not fabricate envelope provenance.
+func MarkEnvelopeSource(cmd *cobra.Command) {
+	if cmd == nil {
+		return
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[SourceAnnotation] = SourceEnvelope
+}
+
+// IsEnvelopeSourced reports whether cmd carries the envelope provenance
+// annotation. Commands without the annotation are treated as non-authoritative
+// (helper fallbacks, overlay-injected stubs, etc.).
+func IsEnvelopeSourced(cmd *cobra.Command) bool {
+	if cmd == nil || cmd.Annotations == nil {
+		return false
+	}
+	return cmd.Annotations[SourceAnnotation] == SourceEnvelope
+}

pkg/edition/edition.go

@@ -55,6 +55,12 @@ type ToolCaller interface {
 	DryRun() bool
 }
 
+// RuntimeDefaultFn resolves a single runtimeDefault placeholder (e.g.
+// "$currentUserId") to a concrete string value. Called lazily at RunE time.
+// Returning (_, false) is equivalent to "not registered" and falls through
+// to the next-lower default source.
+type RuntimeDefaultFn func(ctx context.Context) (string, bool)
+
 // Hooks groups all edition-specific behavioural overrides. Zero values
 // fall back to open-source defaults so the struct is safe to use as-is.
 type Hooks struct {
@@ -88,17 +94,54 @@ type Hooks struct {
 	// ClassifyToolResult inspects raw MCP tool-call content and returns a typed
 	// error (e.g. PATError, CLIError) when the response contains a known
 	// gateway-auth or PAT-permission failure. nil → no special handling.
-	ClassifyToolResult func(content map[string]any) error
+	// ClassifyToolResult func(content map[string]any) error
 
 	// --- product & endpoint ---
 	StaticServers         func() []ServerInfo                          // non-nil → skip Market discovery
 	VisibleProducts       func() []string                              // non-nil → override help visibility
 	RegisterExtraCommands func(root *cobra.Command, caller ToolCaller) // register overlay-only commands
 
+	// --- discovery ---
+
+	// DiscoveryURL overrides the Market API endpoint for server list.
+	// Non-empty → loadDynamicCommands uses FetchServersFromURL(DiscoveryURL)
+	// instead of the default Market base URL. Provides edition-level isolation.
+	DiscoveryURL string
+
+	// DiscoveryHeaders returns HTTP headers injected into discovery requests.
+	// Used to authenticate edition-specific endpoints.
+	DiscoveryHeaders func() map[string]string
+
+	// SupplementServers returns edition-specific MCP servers NOT registered
+	// in any Market registry. Always merged into the endpoint map alongside
+	// Market/cache results, regardless of discovery success or failure.
+	SupplementServers func() []ServerInfo
+
+	// FallbackServers returns the full server list as a safety net when
+	// Market discovery + cache both fail. Results are NOT cached so the
+	// next startup still attempts live discovery.
+	FallbackServers func() []ServerInfo
+
 	// AfterPersistentPreRun runs at the end of the root PersistentPreRunE after
 	// global setup (OAuth flag overrides, log level, output sink). Overlays use
 	// this for clients that bypass the MCP runner (e.g. A2A gateway).
 	AfterPersistentPreRun func(cmd *cobra.Command, args []string) error
+
+	// ClassifyToolResult is called before the framework's default business-error
+	// detection on MCP tool results. If it returns a non-nil error, that error
+	// is used instead of the generic CategoryAPI business error. Editions use
+	// this to return custom error types with specific exit codes (e.g. PAT
+	// authorization errors with exit code 4).
+	ClassifyToolResult func(content map[string]any) error
+
+	// --- schema v3: runtime defaults ---
+
+	// RuntimeDefaults returns resolvers for runtimeDefault placeholders (e.g.
+	// "$currentUserId" → fn). Placeholders not in the map fall through to a
+	// "not registered" warning. Open-source core returns an empty map;
+	// overlays populate the whitelist ($currentUserId / $unionId / $corpId /
+	// $now / $today). See schema v3 §2.3.
+	RuntimeDefaults func() map[string]RuntimeDefaultFn
 }
 
 var (

pkg/editiontest/contract.go

@@ -17,6 +17,7 @@
 package editiontest
 
 import (
+	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -85,4 +86,47 @@ func RunContractTests(t *testing.T, h *edition.Hooks) {
 			t.Error("VisibleProducts() must return at least one product when set")
 		}
 	})
+
+	t.Run("SupplementServers_valid_when_set", func(t *testing.T) {
+		if h.SupplementServers == nil {
+			return
+		}
+		servers := h.SupplementServers()
+		if len(servers) == 0 {
+			t.Error("SupplementServers() must return at least one server when set")
+		}
+		for i, s := range servers {
+			if s.ID == "" || s.Endpoint == "" {
+				t.Errorf("SupplementServers()[%d]: ID and Endpoint must be non-empty", i)
+			}
+		}
+	})
+
+	t.Run("FallbackServers_superset_of_supplement", func(t *testing.T) {
+		if h.FallbackServers == nil || h.SupplementServers == nil {
+			return
+		}
+		fallback := h.FallbackServers()
+		if len(fallback) == 0 {
+			t.Error("FallbackServers() must return at least one server when set")
+		}
+		fbIDs := make(map[string]bool, len(fallback))
+		for _, s := range fallback {
+			fbIDs[s.ID] = true
+		}
+		for _, s := range h.SupplementServers() {
+			if !fbIDs[s.ID] {
+				t.Errorf("SupplementServers ID %q not found in FallbackServers", s.ID)
+			}
+		}
+	})
+
+	t.Run("DiscoveryURL_valid_when_set", func(t *testing.T) {
+		if h.DiscoveryURL == "" {
+			return
+		}
+		if !strings.HasPrefix(h.DiscoveryURL, "https://") {
+			t.Errorf("DiscoveryURL must start with https://, got %q", h.DiscoveryURL)
+		}
+	})
 }

skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dws
-description: 管理钉钉产品能力(AI表格/日历/通讯录/群聊与机器人/待办/审批/考勤/日志/DING消息/开放平台文档/钉钉文档/钉钉云盘/AI听记等)。当用户需要操作表格数据、管理日程会议、查询通讯录、管理群聊、机器人发消息、创建待办、提交审批、查看考勤、提交日报周报（钉钉日志模版）、读写钉钉文档、上传下载云盘文件、查询听记纪要时使用。
+description: 管理钉钉产品能力(AI表格/日历/通讯录/群聊与机器人/待办/审批/考勤/日志/DING消息/开放平台文档/钉钉文档/钉钉云盘/AI听记/邮箱等)。当用户需要操作表格数据、管理日程会议、查询通讯录、管理群聊、机器人发消息、创建待办、提交审批、查看考勤、提交日报周报（钉钉日志模版）、读写钉钉文档、上传下载云盘文件、查询听记纪要、收发邮件时使用。
 cli_version: ">=1.0.15"
 ---
 
@@ -36,6 +36,7 @@ cli_version: ">=1.0.15"
 | `minutes`         | AI听记：听记列表/摘要/关键词/转写/待办/思维导图/发言人/热词/上传                | [minutes.md](./references/products/minutes.md)                 |
 | `oa`              | OA审批：待办/我发起的/表单模板/详情/审批流水/同意/拒绝/撤销                   | [oa.md](./references/products/oa.md)                           |
 | `report`          | 日志：按模版创建/收件箱/已发送/模版查看/详情/已读统计                         | [report.md](./references/products/report.md)                   |
+| `mail`            | 邮箱：邮箱地址查询/邮件搜索(KQL)/邮件详情/发送邮件                        | [mail.md](./references/products/mail.md)                       |
 | `todo`            | 待办：创建(含优先级/截止时间/循环)/查询/修改/标记完成/删除                   | [todo.md](./references/products/todo.md)                       |
 
 ## 意图判断决策树
@@ -50,6 +51,7 @@ cli_version: ">=1.0.15"
 用户提到"钉钉文档/云文档/知识库/读写文档/块级编辑/文档评论/文档复制移动" → `doc`
 用户提到"云盘/文件存储/文件上传下载/文件夹" → `drive`
 用户提到"听记/AI听记/会议纪要/转写/摘要/思维导图/发言人/热词" → `minutes`
+用户提到"邮箱/邮件/发邮件/收邮件/搜邮件/查邮件" → `mail`
 用户提到"审批/请假/报销/出差/加班/同意/拒绝/撤销审批" → `oa`
 用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → `report`
 用户提到"待办/TODO/任务提醒/循环待办" → `todo`

skills/references/products/chat.md

@@ -181,7 +181,7 @@ Flags:
 
 ## message send — 以当前用户身份发消息
 
---group 指定群聊 ID 发群消息；--user 指定用户 userId 发单聊；--open-dingtalk-id 指定用户 openDingTalkId 发单聊。三者只能选其一，不能同时指定。消息内容为位置参数（恰好 1 个），支持 Markdown。可选 --title 作为消息标题。
+--group 指定群聊 ID 发群消息；--user 指定用户 userId 发单聊；--open-dingtalk-id 指定用户 openDingTalkId 发单聊。三者只能选其一，不能同时指定。消息内容为位置参数（恰好 1 个），支持 Markdown。必须提供 --title 作为消息标题。
 --群聊时可选 --at-all @所有人，或 --at-users 指定成员（仅群聊时生效）。
 --发送图片消息：指定 --media-id（通过 dt_media_upload 工具上传获得），自动设置 msgType=image，此时不需要传文本内容。
 
@@ -203,7 +203,7 @@ Flags:
       --group string             群聊 openconversation_id（群聊时必填）
       --user string              接收人 userId（单聊时与 --open-dingtalk-id 二选一）
       --open-dingtalk-id string  接收人 openDingTalkId（单聊时与 --user 二选一，适用于三方应用等无法获取 userId 的场景）
-      --title string             消息标题（可选，默认「消息」）
+      --title string             消息标题（必填）
       --at-all                   @所有人（仅群聊时生效，可选，默认 false）
       --at-users string          @指定成员的 userId 列表，逗号分隔（仅群聊时生效，可选）
       --media-id string          图片 mediaId（通过 dt_media_upload 工具上传获得，需从返回链接中去除 _宽_高.格式 后缀并加上 @ 前缀），指定后发送图片消息，不需要传文本内容
@@ -601,10 +601,10 @@ dws chat message list-unread-conversations --count 20 --format json
 dws chat message send --group <openconversation_id> --title "周报提醒" "请大家本周五前提交周报" --format json
 
 # 4. 以个人身份单聊（通过 userId）
-dws chat message send --user <userId> "你好" --format json
+dws chat message send --user <userId> --title "问候" "你好" --format json
 
 # 4b. 以个人身份单聊（通过 openDingTalkId，三方应用等无法获取 userId 时使用）
-dws chat message send --open-dingtalk-id <openDingTalkId> "你好" --format json
+dws chat message send --open-dingtalk-id <openDingTalkId> --title "问候" "你好" --format json
 
 # 5. 机器人发群消息（Markdown）
 dws chat message send-by-bot --robot-code <robot-code> \

skills/references/products/mail.md

@@ -0,0 +1,160 @@
+# 邮箱 (mail) 命令参考
+
+## 命令总览
+
+### 查询可用邮箱地址
+```
+Usage:
+  dws mail mailbox list [flags]
+Example:
+  dws mail mailbox list
+```
+
+**返回字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `mailboxes` | `List[]` | 邮箱列表，每条包含邮箱地址、账号类型、所属企业 |
+
+### 搜索邮件 (KQL 语法)
+```
+Usage:
+  dws mail message search [flags]
+Example:
+  dws mail message search --email user@company.com --query "subject:\"周报\"" --size 20
+  dws mail message search --email user@company.com --query "from:alice AND date>2025-06-01T00:00:00Z" --size 10
+Flags:
+      --cursor string   邮件的起始偏移标识, 其值取自响应中的nextCursor字段。""表示从头开始
+      --email string    搜索目标邮箱地址 (必填)
+      --query string    KQL 查询表达式 (必填), 其中 date 格式需遵循 ISO8601 规范
+      --size string     每页返回数量(最大限制 100, 默认 20) (必填)，别名: --limit, --page-size
+```
+
+KQL 查询字段: date, size, tag, folderId, isRead, hasAttachments, subject, attachname, body, from, to
+常用文件夹 ID: 1=已发送, 2=收件箱, 3=垃圾邮件, 5=草稿, 6=已删除
+
+### KQL 查询字段说明
+
+| 字段 | 类型 | 说明 | 正确示例 | 错误示例 |
+|------|------|------|----------|----------|
+| `date` | ISO8601 日期时间 | 邮件日期，支持 `>` `<` `>=` `<=` 比较运算符 | `date>2025-06-01T00:00:00Z` | `date>2025-06-01`（缺少时间部分） |
+| `size` | 整数（字节数） | 邮件大小，支持 `>` `<` `>=` `<=` 比较运算符 | `size>1024` | `size>"1024"`（值不需要引号） |
+| `tag` | 字符串 | 邮件标签 | `tag:important` | `tag:""` |
+| `folderId` | 整数 | 文件夹 ID（1=已发送, 2=收件箱, 3=垃圾邮件, 5=草稿, 6=已删除） | `folderId:2` | `folderId:"收件箱"`（必须用数字 ID） |
+| `isRead` | 布尔 `true`/`false` | 是否已读 | `isRead:false` | `isRead:0`、`isRead:"false"`（不支持数字或字符串形式） |
+| `hasAttachments` | 布尔 `true`/`false` | 是否有附件 | `hasAttachments:true` | `hasAttachments:yes` |
+| `subject` | 字符串 | 邮件主题，含空格须加双引号 | `subject:周报`、`subject:"项目 进展"` | `subject:项目 进展`（含空格未加引号） |
+| `attachname` | 字符串 | 附件文件名，含空格须加双引号 | `attachname:report.pdf`、`attachname:"月度 报告.xlsx"` | `attachname:月度 报告.xlsx`（含空格未加引号） |
+| `body` | 字符串 | 邮件正文内容，含空格须加双引号 | `body:会议纪要`、`body:"Q1 总结"` | `body:Q1 总结`（含空格未加引号） |
+| `from` | 字符串（邮件地址或名称） | 发件人，支持：纯邮件地址、纯名称（含空格须加双引号）、`"名称<邮件地址>"` 格式 | `from:alice@company.com`、`from:"张 三"`、`from:"alice<a@b.com>"` | `from:张 三`（含空格未加引号） |
+| `to` | 字符串（邮件地址或名称） | 收件人，支持：纯邮件地址、纯名称（含空格须加双引号）、`"名称<邮件地址>"` 格式 | `to:bob@company.com`、`to:"李 四"`、`to:"alice<a@b.com>"` | `to:李 四`（含空格未加引号） |
+
+**组合查询说明：**
+- 支持 `AND` / `OR` / `NOT` 逻辑运算符（大写）
+- 括号用于分组：`(from:alice OR from:bob) AND folderId:2`
+- 排除特定文件夹：`(NOT folderId:3) AND (NOT folderId:6)`
+
+### message search 返回值说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `messages` | `List[]` | 邮件列表，每条包含邮件 ID 及元信息（不含正文） |
+| `total` | `int32` | 符合条件的总邮件数 |
+| `nextCursor` | `string` | 下一页游标，传入 `--cursor` 翻页；值为 `$` 表示已到达列表尾部 |
+
+**翻页示例：**
+```bash
+# 第一页
+dws mail message search --email user@company.com --query "folderId:2" --size 20 --format json
+# 取返回中的 nextCursor，传入下一次请求（nextCursor="$" 时停止）
+dws mail message search --email user@company.com --query "folderId:2" --size 20 --cursor <nextCursor> --format json
+```
+
+### 查看邮件完整内容
+```
+Usage:
+  dws mail message get [flags]
+Example:
+  dws mail message get --email user@company.com --id <messageId>
+Flags:
+      --email string   邮件所属邮箱地址 (必填)
+      --id string      邮件 ID (必填)
+```
+
+**返回字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `message` | `object` | 邮件完整信息，包含主题、发件人、收件人、正文、附件等 |
+
+### 发送邮件
+```
+Usage:
+  dws mail message send [flags]
+Example:
+  dws mail message send --from user@company.com --to colleague@company.com \
+    --subject "周报" --body "本周完成任务A和任务B"
+Flags:
+      --body string      邮件正文，支持 Markdown 格式 (必填)
+      --cc string        抄送人列表
+      --from string      发件人邮箱 (必填)，别名: --sender
+      --subject string   邮件标题 (必填)
+      --to string        收件人列表 (必填)
+```
+
+## 通用错误说明
+
+以下错误适用于所有 mail 命令。
+
+| 错误标识 | 含义 | 处理建议 |
+|----------|------|----------|
+| `domain.notFound` | 该用户的邮箱不是由钉钉邮箱托管，无法完成操作 | 确认邮箱是否已开通钉钉企业邮箱服务 |
+
+## 意图判断
+
+用户说"我的邮箱/邮箱地址" → `mailbox list`
+用户说"找邮件/搜邮件/查邮件" → `message search`
+用户说"看邮件/打开邮件/邮件内容" → 先 `message search` 获取 messageId，再 `message get`
+用户说"发邮件/写邮件" → 先 `mailbox list` 获取发件地址，再 `message send`
+用户说"给(某人名字)发邮件" → 先 `aisearch person` 获取 userId，再 `contact user get` 获取收件人邮箱，再 `message send`
+
+
+## 严格禁止 (NEVER DO)
+- 明确禁止猜测、假设、推断发件人和收件人邮箱
+- 无法获取邮箱时，强引导ask_human，由用户确认，不要通过假设或其他方式继续执行
+
+## 核心工作流
+
+```bash
+# 1. 查看可用邮箱 — 提取邮箱地址
+dws mail mailbox list --format json
+
+# 2. 搜索邮件 — 提取 messageId
+dws mail message search --email user@company.com \
+  --query "subject:\"周报\" AND date>2025-06-01T00:00:00Z" --size 10 --format json
+
+# 3. 查看邮件详情
+dws mail message get --email user@company.com --id <messageId> --format json
+
+# 4. 发送邮件
+dws mail message send --from user@company.com --to colleague@company.com \
+  --subject "周报" --body "本周完成…" --format json
+```
+
+## 上下文传递表
+
+| 操作 | 从返回中提取 | 用于 |
+|------|-------------|------|
+| `mailbox list` | 邮箱地址 | message search/get/send 的 --email/--from |
+| `message search` | `messageId` | message get 的 --id |
+| `aisearch person` → `contact user get` | 用户邮箱 (orgAuthEmail) | message send 的 --to/--cc (跨产品) |
+
+## 注意事项
+
+- `mailbox list` 返回用户所有邮箱（含个人和企业），每条记录包含邮箱地址、账号类型、所属企业。选择邮箱时优先匹配用户当前所在企业的企业邮箱；若有多个可选，向用户确认后再操作
+- `message search` 返回邮件 ID 和元信息（不含正文），需 `message get` 获取完整内容
+- KQL 查询支持 AND/OR/NOT 组合，字段值含空格时需用双引号
+- `--cc` 抄送人支持多人，逗号分隔
+- 收件人邮箱获取：用户只知道同事名字时，先通过 `dws aisearch person --keyword "名字" --dimension name` 获取 userId，再 `dws contact user get --ids <userId>` 从返回中提取 orgAuthEmail 字段
+
+

test/unit/open_source_policy_test.go

@@ -35,6 +35,8 @@ func TestOpenSourceTreeOmitsEmbeddedHostMarkers(t *testing.T) {
 		"REWIND_" + "MESSAGE_ID",
 		"MergeWukong" + "MCPHeaders",
 		"buildMode ==" + " \"real\"",
+		"wukong/" + "discovery",
+		"dingi8fo" + "prfi3jynjjlu",
 	}
 
 	var matches []string