chore(skills): drop dead SAFETY_PREAMBLE_INJECT marker

No injection code ever existed in this repository, so the marker was
inert in all 22 multi SKILL.md files. Remove it and correct the skill
authoring docs to describe safety rules as plain prose.

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/workflows/release.yml

@@ -1735,7 +1735,7 @@ jobs:
     if: ${{ !cancelled() && vars.ENABLE_GITEE_UPLOAD_FALLBACK == 'true' && needs.release-contract.result == 'success' && needs.release.result == 'success' && needs.publish-channels.result == 'success' }}
     needs: [release-contract, release, publish-channels]
     runs-on: ubuntu-latest
-    timeout-minutes: 120
+    timeout-minutes: 360
     permissions:
       contents: read
     env:
@@ -1752,12 +1752,14 @@ jobs:
 
       - name: Check out trusted release tooling
         uses: actions/checkout@v4
+        timeout-minutes: 5
         with:
           ref: ${{ github.sha }}
           path: tmp/trusted-release-tooling
           persist-credentials: false
 
       - name: Fetch and verify sealed release tag
+        timeout-minutes: 5
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -1776,7 +1778,7 @@ jobs:
           path: dist
 
       - name: Mirror release to Gitee (China)
-        timeout-minutes: 100
+        timeout-minutes: 318
         run: ./scripts/release/sync-to-gitee.sh
         env:
           VERSION: ${{ needs.release-contract.outputs.release_version }}
@@ -2180,13 +2182,14 @@ jobs:
     needs: dispatch-contract
     if: ${{ !cancelled() && needs.dispatch-contract.result == 'success' && (needs.dispatch-contract.outputs.mode == 'repair_gitee' || needs.dispatch-contract.outputs.mode == 'repair_oss') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.repository == 'DingTalk-Real-AI/dingtalk-workspace-cli' }}
     runs-on: ubuntu-latest
-    timeout-minutes: 120
+    timeout-minutes: 360
     permissions:
       actions: read
       contents: read
     steps:
       - name: Check out trusted release tooling
         uses: actions/checkout@v4
+        timeout-minutes: 5
         with:
           ref: ${{ github.sha }}
           path: tooling
@@ -2194,6 +2197,7 @@ jobs:
           fetch-depth: 0
 
       - name: Validate repair version
+        timeout-minutes: 2
         working-directory: tooling
         env:
           VERSION: ${{ inputs.repair_gitee_version || inputs.repair_oss_version }}
@@ -2208,6 +2212,7 @@ jobs:
       - name: Verify immutable release authority
         id: authority
         uses: actions/github-script@v7
+        timeout-minutes: 5
         env:
           VERSION: ${{ inputs.repair_gitee_version || inputs.repair_oss_version }}
         with:
@@ -2330,12 +2335,14 @@ jobs:
 
       - name: Check out sealed release source
         uses: actions/checkout@v4
+        timeout-minutes: 5
         with:
           ref: ${{ steps.authority.outputs.commit_sha }}
           path: release-source
           persist-credentials: false
 
       - name: Fetch and verify sealed release tag
+        timeout-minutes: 5
         working-directory: tooling
         env:
           VERSION: ${{ inputs.repair_gitee_version || inputs.repair_oss_version }}
@@ -2352,6 +2359,7 @@ jobs:
             "$VERSION" "$RELEASE_COMMIT" "$RELEASE_TAG_OBJECT"
 
       - name: Require successful Release workflow delivery
+        timeout-minutes: 5
         working-directory: tooling
         env:
           VERSION: ${{ inputs.repair_gitee_version || inputs.repair_oss_version }}
@@ -2368,6 +2376,7 @@ jobs:
             --channel-repair "$target" "$VERSION" "$RELEASE_COMMIT"
 
       - name: Download and verify immutable GitHub Release assets
+        timeout-minutes: 10
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VERSION: ${{ inputs.repair_gitee_version || inputs.repair_oss_version }}
@@ -2385,7 +2394,7 @@ jobs:
 
       - name: Mirror release to Gitee (China)
         if: ${{ needs.dispatch-contract.outputs.mode == 'repair_gitee' }}
-        timeout-minutes: 100
+        timeout-minutes: 318
         working-directory: tooling
         run: |
           "$GITHUB_WORKSPACE/tooling/scripts/release/sync-to-gitee.sh"

AGENTS.md

@@ -1,357 +1,51 @@
 # Repository Agent Guide
 
-This file applies to the entire repository. Keep changes scoped, preserve
-unrelated work, and use `gofmt` for every modified Go file.
+This file applies to the entire repository. Keep it as a routing page: load
+the detailed guide for the surface you are changing instead of treating this
+file as a repository wiki.
 
-## Build and test
+## Always
 
-- Build: `go build ./cmd`
-- Full test suite: `DWS_PACKAGE_VERSION=0.0.0-test go test ./...`
-- Generate Schema assets: `go generate ./internal/cli`
-- Check generated drift: `./scripts/policy/check-generated-drift.sh`
-- Check the Schema contract: `./scripts/policy/check-schema-catalog.sh`
+- Preserve unrelated and pre-existing work; inspect `git status` before edits.
+- Make the smallest coherent change and update its tests and user-facing docs.
+- Use `gofmt` for every modified Go file.
+- Treat repository code, tests, scripts, and versioned docs as the source of
+  truth. Do not depend on generated Wiki or CodeWiki content.
+- Do not hand-edit generated Schema Catalog or Agent metadata. Change their
+  reviewed inputs or generators, then regenerate.
 
-Generated Schema JSON is committed. Change its source inputs and generators,
-then regenerate; do not hand-edit generated Catalog or Agent metadata files.
-`internal/cli/schema_command_registry.json` is different: it is a reviewed
-`CommandRegistry` source, not a generated snapshot. It is the single reviewed
-source of stable canonical identity,
-primary paths, aliases, and navigation. Edit it only when reviewed exposure,
-identity, primary path, or aliases change; parameter, Skill, and metadata-only
-changes must not rewrite it mechanically.
+## Read by task
 
-## Agent Schema contract
+| Change surface | Required guide |
+|---|---|
+| Any implementation or review | [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/coding-agent-guide.md`](docs/coding-agent-guide.md) |
+| Writing a task for a coding agent | [`docs/coding-agent-task-template.md`](docs/coding-agent-task-template.md) |
+| Overall architecture or package layering | [`docs/architecture.md`](docs/architecture.md) |
+| Product command handler behavior | [`internal/helpers/AGENTS.md`](internal/helpers/AGENTS.md) |
+| Helpers package/file layout or megafile splits | [`docs/helpers-structure-guide.md`](docs/helpers-structure-guide.md) |
+| Bundled skill authoring (`skills/`) | [`skills/AGENTS.md`](skills/AGENTS.md) and [`docs/skill-authoring-guide.md`](docs/skill-authoring-guide.md) |
+| CLI paths, flags, Schema, Agent metadata, or generated Catalog | [`docs/schema-contributor-guide.md`](docs/schema-contributor-guide.md) |
+| CI, release, packaging, or repository automation | [`docs/automation.md`](docs/automation.md) |
+| Agent identification headers or host integration | [`docs/agent-code.md`](docs/agent-code.md) |
 
-The Schema data flow is one way:
+Read the closest code and tests for the affected package as well. Nested
+`AGENTS.md` files take precedence for their subtrees.
 
-```text
-1. app.NewRootCommand()
-   └─ builds the real Cobra command tree and flags
+## Common checks
 
-2. schema_command_registry.json
-   + schema_hints/metadata/<product>.json tool parameters (+ cli_path)
-   └─ forms EffectiveCommandRegistry
-      └─ binds exactly to real Cobra leaves and aliases
-
-3. Parameter resolution
-   Cobra flags
-   + schema_parameter_bindings.json
-   + metadata tool parameters
-   └─ produces ParameterSpec and constraints
-
-4. Agent and interface semantics
-   schema_hints/selection/<product>.json   (selection prose)
-   + schema_hints/metadata/<product>.json  (safety/interface/runtime_gate)
-   + pinned MCP metadata
-   └─ resolves Agent metadata by source precedence
-      Markdown is evidence only; it is not concatenated into final prose
-
-5. One typed hub
-   BoundCommandRegistry
-   + ParameterSpec
-   + Agent metadata
-   + Interface metadata
-   └─ resolves every command exactly once into ToolSpec
-      └─ aggregates SchemaRegistry + SchemaIndex
-
-6. One-way publication
-   SchemaRegistry
-   └─ internal/cli/schema_catalog.json
-      └─ dws schema list/product/group/leaf/--all
-```
-
-Parameter overlays from metadata are merged into `EffectiveCommandRegistry`
-*before* Cobra binding; after that point there is no second identity source and
-no identity precedence winner. The binder must reject a missing/non-runnable
-Cobra path, an alias collision, and any native identity annotation that
-disagrees with the effective registry. A missing native identity annotation is
-allowed because annotations are implementation-side assertions, not identity
-fallbacks.
-
-The assembler resolves every bound command exactly once into one `ToolSpec`.
-Build-time gates and the snapshot serializer consume that source-resolved typed
-registry/index. Runtime projections and delivery gates consume the typed
-registry/index returned by the production snapshot loader. Neither path may
-reopen annotations, merge source records, or use a previous Catalog or other
-generated JSON as a source. `schema_catalog.json` is output-only in the
-generation graph. The production loader decoding the embedded published
-snapshot is a delivery boundary, not source resolution; it must never create or
-repair a Cobra command, flag, registry entry, or later Catalog generation.
-
-This split is architecturally isomorphic to Lark's typed metadata registry,
-navigation catalog, and schema renderer. DWS intentionally preserves its
-existing flat JSON wire contract for compatibility; do not treat architectural
-alignment as permission to make an unversioned wire-format change.
-
-The reviewed `CommandRegistry` is the sole source of stable command identity
-and navigation. The executable Cobra tree remains the source of truth for
-whether a CLI path exists, is runnable, and which flags it accepts. Schema
-coverage is bidirectional:
-
-1. Every final `SchemaRegistry` tool, including its serialized Catalog
-   projection, must resolve to an executable Cobra command.
-2. Every public runnable Cobra leaf must either resolve to Schema or appear as
-   an exact, reviewed exclusion with a non-empty reason in
-   `internal/cli/schema_command_exclusions.json`.
-
-Do not use prefix or wildcard exclusions: they can silently hide future
-commands. Remove an exclusion when its command enters Schema; stale, invalid,
-or duplicate exclusions must fail generation and CI.
-
-When adding or changing an Agent-visible command, review all relevant inputs:
-
-- `internal/cli/schema_command_registry.json` for the reviewed
-  `CommandRegistry`: canonical identity, primary CLI path, aliases, and stable
-  navigation. It is the identity source and is not a generated artifact.
-- `internal/cli/schema_command_registry.schema.json` is its closed,
-  machine-readable editing contract. Preserve the local `$schema` reference;
-  unknown fields, invalid visibility values, stale paths, and collisions fail
-  Go validation and policy.
-- `internal/cli/schema_hints/metadata/<product>.json` for safety, interface,
-  `runtime_gate`, and optional parameter overlays (`parameters` / `cli_path`).
-- `internal/cli/schema_hints/selection/<product>.json` for reviewed Agent
-  selection prose (`agent_summary`, `use_when`, `avoid_when`, `examples`).
-- `internal/cli/schema_hints/index.json` only maps product IDs to those files.
-- Native Runtime Schema identity annotations, when present, as consistency
-  assertions against `EffectiveCommandRegistry`. They must agree exactly and
-  must never materialize, infer, or override registry identity.
-- Flag-to-interface property mappings and required/default semantics.
-- Generated files under `internal/cli/schema_agent_metadata/` and
-  `internal/cli/schema_catalog.json` after running generation.
-
-Run the reverse-completeness tests whenever the Cobra tree changes. A command
-that works through `dws <path>` but cannot be found through the matching
-`dws schema` lookup is a contract failure unless it has a reviewed exact
-exclusion.
-
-Metadata parameter overlays must reference an exact public runnable Cobra leaf
-and real flags. They may override Schema description, interface-property/type
-mapping, `required`, and `required_when`; they must not create commands or
-flags, define an interface, or advertise an unknown RPC. Every authored entry
-requires `reviewed: true` and a non-empty review reason.
-
-For Agent-authored metadata or selection edits:
-
-1. Confirm the exact command and flag names in the current Cobra tree.
-2. Edit only the owning block (`metadata/` or `selection/`); do not mix fields.
-3. Add the smallest possible entry; do not copy generated Catalog fields into
-   the input.
-4. Describe user-visible semantics in `review_reason` and parameter
-   descriptions.
-5. Run generation, drift, Schema policy, and the focused CLI tests before
-   proposing the change.
-
-## Agent curation workflow (Schema hints)
-
-Use this workflow when refreshing Agent selection prose and confirmation
-alignment. Prefer **agent-authored review** over bulk merge scripts that dump
-`selection-review.json` or Skill Markdown into Catalog fields.
-
-Human-authored inputs are split into two blocks:
-
-| Block | Path | Owns |
-|---|---|---|
-| **metadata** | `internal/cli/schema_hints/metadata/<product>.json` | `effect` / `risk` / `confirmation` / `idempotency` / `interface_*` / `runtime_gate` / optional `parameters` |
-| **selection** | `internal/cli/schema_hints/selection/<product>.json` | `agent_summary` / `use_when` / `avoid_when` / `examples` (+ product routing) |
-
-`index.json` only maps product IDs to those files. Do not mix selection fields
-into metadata files or metadata fields into selection files.
-
-### Goals
-
-1. **Selection prose** is decision-oriented (Feishu/Lark style): trigger intent,
-   sibling-command routing, and outcome shape — not a restatement of the
-   summary. Delivered Catalog provenance is `reviewed_explicit` from
-   `selection/`.
-2. **Safety** follows Runtime: `confirmation=user_required` iff the tool's
-   metadata `runtime_gate != none` (for example `confirm_delete`, `typed_yes`,
-   `confirm_dangerous`).
-3. **Parameter overrides** (former Manual `commands`) live on metadata tools as
-   `parameters` (+ `cli_path`) and are applied into EffectiveCommandRegistry.
-
-### Authoring
-
-For every curated tool:
-
-1. Edit `metadata/<product>.json` for safety/interface/gates/parameters.
-2. Edit `selection/<product>.json` for selection prose (`reviewed: true`,
-   `review_reason`, `source_refs`).
-3. Run `make generate-schema`. Do not hand-edit generated
-   `schema_agent_metadata/` or `schema_catalog.json`.
-
-### Pull live MCP descriptions (personal token)
-
-Pinned `internal/cli/schema_mcp_metadata.json` is a sanitized baseline. Prefer
-live Schema from a logged-in personal session:
+Choose checks from the matrix in `docs/coding-agent-guide.md`; do not claim a
+check that was not run.
 
 ```bash
-dws auth status                 # token_valid should be true
-dws cache refresh               # refresh discovery / tools cache
-dws schema <mcp-canonical> -f json
-# or CLI path: dws schema --cli-path "drive copy" -f json
+make coding-agent-harness
+make build
+make format-check
+make test
+make policy
+git diff --check
 ```
 
-Resolve MCP identity via `interface_ref` when CLI canonical ≠ MCP path
-(example: CLI `drive.copy_document` → live `doc.copy_document`). On pull
-failure, fall back to Skill + Cobra Help + pinned MCP, and record evidence
-(for example `live-dws-schema:<path>#FAILED`). Never print or commit tokens.
-
-Precedence when sources disagree: **Runtime/Cobra > live MCP > pinned MCP >
-Skill (evidence only)**.
-
-### Parallel product agents
-
-Split work by product groups. Each agent must:
-
-- Read Skill, Cobra/`--help`, Runtime confirmation sites, and live `dws schema`
-  for its tools.
-- Hand-write selection + metadata; forbid wholesale JSON merges from review
-  dumps.
-- Edit only its `metadata/<product>.json` and `selection/<product>.json`.
-- **Never** `git checkout` unrelated product files to “clean scope”.
-
-### Regenerate and gates
-
-```bash
-make generate-schema
-./scripts/policy/check-runtime-confirmation-truth.sh
-go test ./internal/app -run '^TestSheetFinalSchemaConfirmationMatchesRuntimeGuards$' -count=1
-```
-
-Example rules (fail generation otherwise):
-
-- At most two examples per tool; no `--yes` in stored examples.
-- Examples must match live Cobra argv (path, flags, required groups).
-- No shell comments in examples.
-
-After generation, spot-check Catalog: selection provenance is
-`reviewed_explicit` from `selection/`, and `user_required` count equals
-metadata `runtime_gate != none`.
-
-`make generate-schema` is a full deterministic snapshot rebuild, not an
-incremental patch over the previous Catalog. It rereads every reviewed input,
-removes stale generated product metadata, and rewrites the exact metadata and
-Catalog projections. Incremental work happens only when an Agent or human
-edits selected `metadata/` or `selection/` entries; the next publication still
-recomputes all outputs. Generated files must never be read back as merge input,
-and byte guards fail generation if it changes the hint inputs or CommandRegistry.
-
-Selection prose may choose a more or less restrictive recommendation. It cannot
-create a Cobra command or flag, change parameter facts, invent an
-RPC/interface, alter safety metadata, or bypass command completeness. Examples
-must use an executable primary/alias path and flags accepted by the live Cobra
-command; never add `--yes` to stored examples.
-
-Every example is always checked against its real `BoundCommand`: exact path,
-accepted flags, Cobra required flags/positionals, and the effective
-`require_one_of`, `require_together`, and `mutually_exclusive` constraints must
-all pass before execution eligibility is considered. A missing required value,
-constraint failure, runtime error, or MCP resolution error is a contract bug;
-none is a valid reason to skip an example.
-
-Example execution defaults to contract validation only. Runtime execution is
-opt-in: an example enters `dry_run` only when its final `ToolSpec` publishes an
-explicit reviewed dry-run capability. The test never injects `--yes`, and
-`risk`/`confirmation` values do not manufacture preview support. A narrow
-runtime precondition that cannot be derived from the typed contract may use an
-exact zero-based `example_dispositions` entry with `mode=contract_only`,
-`reviewed=true`, one of the schema-enumerated reason codes, and a concrete
-non-empty reason. Such a disposition may only narrow an explicit dry-run
-capability; it cannot turn an ordinary contract-only example into a skip.
-Duplicate, missing, and out-of-range indexes fail validation. Never catch a
-dry-run failure and dynamically downgrade it to `contract_only`.
-
-Normal Go tests run the exhaustive contract gate. Run
-`make test-schema-agent-examples` to additionally execute the eligible subset
-through the real Cobra `--dry-run` path with isolated HOME and blocked proxies.
-The test reports stable `total`, `contract`, `dry_run`, `contract_only`,
-`reviewed_manual`, and per-reason counts; changing those counts requires a
-review of the corresponding typed dry-run capability or manual disposition.
-This target is also part of `make policy`.
-
-Treat every tool `use_when` entry as a reviewed positive selection scenario
-whose expected result is that tool's canonical path, and every `avoid_when`
-entry as a reviewed negative scenario that must not choose that tool. The
-deterministic gate derives a typed evaluation fixture from these same fields;
-it requires exact tool coverage, a real runnable `BoundCommandRegistry`
-primary command, at least one positive and negative assertion per tool, and no
-literal contradictory expectations. It does not claim that string matching
-proves natural-language understanding.
-
-Semantic selection is an explicit opt-in live-model check. Run the smoke set
-(one positive and one negative scenario per product) with
-`DWS_AGENT_SELECTION_LIVE=1 ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... go test ./internal/app -run TestManualAgentSelectionArkLive -count=1`.
-Add `DWS_AGENT_SELECTION_FULL=1` to evaluate every committed tool scenario, or
-set `DWS_AGENT_SELECTION_CASES` to comma-separated fixture case IDs. Normal CI
-never calls a model; its blockers remain the reproducible fixture, binding,
-example, provenance, and final-delivery facts.
-
-The live evaluator sends only case IDs/scenarios plus one same-product
-candidate table; expected/forbidden assertions stay local and must never be
-included in the model prompt. Built-in Ark HTTPS bases are allowlisted. A
-different HTTPS provider requires its exact base in
-`DWS_AGENT_SELECTION_ALLOWED_BASE_URLS`; plaintext HTTP is accepted only for a
-loopback test server so API credentials are never sent to an arbitrary clear
-text endpoint.
-
-## Safety metadata
-
-Parameter and safety resolution is mostly source-precedence based and
-value-neutral: do not choose a winner because one value looks stricter. A
-higher-priority reviewed metadata/explicit source may intentionally raise or
-lower description, mapping, `effect`, `risk`, `confirmation`, or `idempotency`.
-Preserve all candidates and the selected source in provenance, and fail
-same-precedence conflicts rather than silently merging them.
-
-`required` is the exception. Cobra `MarkFlagRequired` is a hard floor: the
-final Agent projection must keep `required=true` and cannot be lowered by
-manual/hint overlays. Overlays may still raise an optional flag to required.
-`cli_required` continues to mirror the executable Cobra marker.
-
-For command text, reviewed `ToolSchemaHint` wins first, then command-specific
-Cobra Help, then MCP metadata. Generic RPC prose may remain an unselected
-provenance candidate (and parameter-level `interface_description`); it must not
-overwrite a specialized leaf's title or description.
-
-For every delivered `ToolSpec` and `ParameterSpec` field, the provenance
-winner value must exactly equal the delivered value. Checking only source,
-count, presence, or hash is not a sufficient final-delivery invariant.
-
-The same resolved `ToolSpec` must drive every projection. The full leaf payload
-must equal the corresponding tool in `schema --all` and the full Catalog tool.
-Overview/product/group summaries and Catalog summaries must equal
-`ToolSpec.ToSummaryPayload()`. An alias lookup may change only the view fields
-`cli_path` and `is_alias`; it must not re-resolve or mutate the command
-contract.
-
-This build-time rule is distinct from runtime drift handling. If shipped Help
-and leaf Schema disagree, pass only flags accepted by Cobra. For conflicting
-safety information, do not silently take the less restrictive behavior: use
-the safer interpretation or stop and report the contract drift.
-
-Do not infer one safety field from another. In particular, `effect=destructive`
-or `risk=high` does not mechanically rewrite `confirmation`; the final
-precedence winner for each field is authoritative. When
-`confirmation=user_required`, obtain confirmation before adding `--yes`.
-Keep CLI confirmation behavior and Schema metadata consistent, and add a
-semantic regression test through the final embedded loader/query delivery
-path; a generator unit test or JSON count alone is insufficient.
-
-## Current Schema boundaries
-
-- `schema list` remains a progressive overview. `schema --all` is the stable
-  full-export contract: every final `SchemaIndex` tool must contain its
-  complete leaf parameters, constraints, and safety semantics, including an empty
-  `parameters` object for commands without flags. Keep it suitable for the #602
-  compatibility baseline and fail rather than silently emitting a partial
-  export.
-- `schema --all` is not normal command discovery. Use overview -> product/group
-  -> leaf for routine Agent work. `--compact` is supported for context-saving
-  projections, but a compact full export is not a complete compatibility
-  baseline.
-- `dws <path> --help` defines whether Cobra exposes a path and which flags the
-  executable accepts. A leaf Schema defines Agent selection, parameter mapping
-  and constraints, and safety/confirmation semantics. A conflict is contract
-  drift, not permission to guess.
-- Schema and Help describe commands; neither returns DingTalk business data.
-  After discovery, execute the real read/search/list command to obtain data.
+For Schema work, the minimum generation entry point is `make generate-schema`.
+For CLI path or flag changes, also run
+`./scripts/policy/check-command-surface.sh --strict`. Report failures,
+environment limits, and unrun checks explicitly in the handoff.

CHANGELOG.md

@@ -6,6 +6,40 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+## [1.0.54] - 2026-07-21
+
+This release promotes the validated `v1.0.54-beta.2` baseline to stable. It restores the default transport envelope for personal event output with opt-in flattening, plus Schema CLI path and plugin overlay compatibility fixes.
+
+### Changed
+
+- **Personal event output compatibility** (#743) — `event consume` once again preserves the transport envelope by default for `ndjson`/`json`/`pretty`, while retaining the existing `compact` processor. New Agent workflows opt into the event-specific top-level DTO with `--flatten`, which is mutually exclusive with `-f raw` and `--debug-raw-events`; `event schema --flatten` describes that DTO, while the default schema describes `type/event_type/data/headers` and points to `.data | fromjson`.
+
+### Fixed
+
+- **Schema CLI path compatibility** (#738) — user-facing Schema lookups once again accept space-, dot-, and slash-separated CLI paths without weakening strict canonical identity resolution.
+- **Plugin CLI overlays** (#701) — installed plugins register their manifest-authored command trees again for HTTP and stdio servers, and a plugin may now replace a hidden compatibility fallback (for example `conference`) instead of being skipped as a distribution conflict.
+
+## [1.0.54-beta.2] - 2026-07-21
+
+This beta revalidates the same `v1.0.54-beta.1` source through the cloud release path with a sealed `OSS-Mirror: deferred` policy, because the manually tagged `v1.0.54-beta.1` push run failed on the unavailable OSS mirror channel after GitHub and npm delivery.
+
+### Changed
+
+- **Release delivery only** — no source changes since `v1.0.54-beta.1`; see that section for the user-visible changes under validation (#743, #738, #701).
+
+## [1.0.54-beta.1] - 2026-07-21
+
+This beta validates the restored default transport envelope for personal event output with opt-in flattening, plus Schema CLI path and plugin overlay compatibility fixes, on top of the validated `v1.0.53-beta.7` baseline.
+
+### Changed
+
+- **Personal event output compatibility** (#743) — `event consume` once again preserves the transport envelope by default for `ndjson`/`json`/`pretty`, while retaining the existing `compact` processor. New Agent workflows opt into the event-specific top-level DTO with `--flatten`, which is mutually exclusive with `-f raw` and `--debug-raw-events`; `event schema --flatten` describes that DTO, while the default schema describes `type/event_type/data/headers` and points to `.data | fromjson`.
+
+### Fixed
+
+- **Schema CLI path compatibility** (#738) — user-facing Schema lookups once again accept space-, dot-, and slash-separated CLI paths without weakening strict canonical identity resolution.
+- **Plugin CLI overlays** (#701) — installed plugins register their manifest-authored command trees again for HTTP and stdio servers, and a plugin may now replace a hidden compatibility fallback (for example `conference`) instead of being skipped as a distribution conflict.
+
 ## [1.0.53] - 2026-07-21
 
 This release promotes the validated `v1.0.53-beta.7` baseline to stable. It adds enterprise onboarding, declarative shortcuts, Sheet/Aitable writes, multi-account profiles, and broader personal IM events, while hardening authentication and the guarded release path.

CONTRIBUTING.md

@@ -10,9 +10,13 @@ under the project [Apache License 2.0](./LICENSE).
 ## Before You Start
 
 1. Read `README.md`.
-2. Read the relevant docs under `docs/`.
-3. Inspect the code and tests for the area you will change.
-4. Decide the smallest safe change that satisfies the request.
+2. Normalize the task and select checks with
+   [`docs/coding-agent-guide.md`](./docs/coding-agent-guide.md).
+3. Read the relevant docs under `docs/`. CLI/Schema/Agent metadata work must
+   also follow
+   [`docs/schema-contributor-guide.md`](./docs/schema-contributor-guide.md).
+4. Inspect the code and tests for the area you will change.
+5. Decide the smallest safe change that satisfies the request.
 
 Maintainers and automation authors should also read
 `docs/automation.md` for repo-local release and agent workflow

Formula/dingtalk-workspace-cli-beta.rb

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
   desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.53-beta.4"
+  version "1.0.54-beta.2"
   license "Apache-2.0"
   keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"
 
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-darwin-arm64.tar.gz"
-      sha256 "32a442d5b42dfed8512a695a7cef513722db6912f3c3168954cfaefb68e0b075"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54-beta.2/dws-darwin-arm64.tar.gz"
+      sha256 "46b57bed1f6e9f7ba007d8a86a6f5eb280fdeb557fc9bb5946f14f9b1f8f0c9f"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-darwin-amd64.tar.gz"
-      sha256 "00c694677b9ce2e1a711535740681defe0a5f83d6b72140f305483501628faf8"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54-beta.2/dws-darwin-amd64.tar.gz"
+      sha256 "1b7fd08e64b1c86bbcee217604ffe07e0e8f1b3b5c4de518534386972bcf0f9b"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-linux-arm64.tar.gz"
-      sha256 "98516620e861e516cf846cf418f1a0ad5c5eb9a8681bd066b1fd29f4847aca6a"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54-beta.2/dws-linux-arm64.tar.gz"
+      sha256 "108d3861ef606519f9934530d29654eab55a73607d1ee6775461f98ef5a6acd4"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-linux-amd64.tar.gz"
-      sha256 "266df80e8a989971789a157dd134685a7c9eda01dd1d082719ec9e09d5a07bf0"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54-beta.2/dws-linux-amd64.tar.gz"
+      sha256 "6cb96ee09419bbbcc1eb336218ac2aa1d9ca0ed5cbd5a80c79bc20e1e1f03ff7"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-skills.zip"
-    sha256 "6770511ab9b04b4d97da1858069ff694830ba91d47c1e8564fd85856f95b016e"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54-beta.2/dws-skills.zip"
+    sha256 "572b93f04a10268d185ad1f8e70e0d412949ae056be8494a9949387076fd14bc"
   end
 
   def install

Formula/dingtalk-workspace-cli.rb

@@ -1,32 +1,33 @@
 class DingtalkWorkspaceCli < Formula
   desc "Automate DingTalk workspace tasks from the terminal"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.52"
+  version "1.0.54"
   license "Apache-2.0"
 
+
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-darwin-arm64.tar.gz"
-      sha256 "4f6b4d064a76bcefac42feb5f356253fe43f9499b8cec9d2cdf202e7d3b9b60c"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-darwin-arm64.tar.gz"
+      sha256 "8ae0e52cf973f6fb3df61c67a41fd11e2df417a0c815762b6060cbcb5e600c08"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-darwin-amd64.tar.gz"
-      sha256 "abc87128f4b98d0a01ea99235449031971db8fa4ce94167403e3b736c4b81e9a"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-darwin-amd64.tar.gz"
+      sha256 "11b711b9d70dea62304bf5f8206c56b4e7ea91148dafe97fb7c0f844a2a61da3"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-linux-arm64.tar.gz"
-      sha256 "0d357ef0535f99f2f63b5ecbfdee9c32448be2a2c24f3096c03126b3b7570bc5"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-linux-arm64.tar.gz"
+      sha256 "9c7ecb4c8cd55644b2faa73f6ce7843c0279b23793e23deb5061692ea71a0cf1"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-linux-amd64.tar.gz"
-      sha256 "b7dfd9a4b3489211359261747ed0cb9c8c261434bb762ad3f76df33bdbabd5cb"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-linux-amd64.tar.gz"
+      sha256 "8a0bc245747fc3facf98c8103c06da46852a30bff31ac93b0aa874e8c7e46db7"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-skills.zip"
-    sha256 "0fa3c8dec500c1659e6480d6772ae901b2d12d24322dd5d7283f016024290c21"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-skills.zip"
+    sha256 "7450fd0115c75bfe6820c7099f348973d9353cca9d8d647c9cddcd70978a7ec0"
   end
 
   def install
@@ -52,6 +53,7 @@ class DingtalkWorkspaceCli < Formula
     <<~EOS
       Agent Skills are bundled in #{pkgshare}/skills/dws.
       Run `dws skill setup` to install them into your Agent directories.
+
     EOS
   end
 

Makefile

@@ -8,7 +8,7 @@ POLICY_GOTMPDIR ?= $(DWS_POLICY_TMPDIR)/go
 POLICY_ENV = DWS_POLICY_TMPDIR="$(DWS_POLICY_TMPDIR)" GOTMPDIR="$(POLICY_GOTMPDIR)"
 GO_SOURCE_LIST = git ls-files -z --cached --others --exclude-standard -- '*.go'
 
-.PHONY: all help build rebuild test test-plan lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema generate-schema-agent-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan lint format-check fmt policy coding-agent-harness coding-agent-task edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema generate-schema-agent-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
 
 all: setup-hooks fmt lint build test rebuild
 
@@ -21,6 +21,8 @@ help:
 	@printf "  make format-check  - Check all repository Go source files with gofmt\n"
 	@printf "  make fmt           - Format all repository Go source files\n"
 	@printf "  make policy        - Check the built dws plus open-source and Schema policies\n"
+	@printf "  make coding-agent-harness - Validate coding-agent task intake, routing, and self-check contracts\n"
+	@printf "  make coding-agent-task TASK=<file> - Validate a filled coding-agent task contract\n"
 	@printf "  make interface-integrity - Check historical commands and help contracts still work\n"
 	@printf "  make authoritative-interface-integrity BASE_REF=<ref> - Check the Git-owned PR merge-base\n"
 	@printf "  make coverage-gate BASE_REF=<ref> - Enforce overall non-regression and 100%% changed-code coverage\n"
@@ -86,6 +88,13 @@ policy:
 	@$(POLICY_ENV) ./scripts/policy/check-schema-binary.sh
 	@$(POLICY_ENV) $(MAKE) test-schema-agent-examples
 
+coding-agent-harness:
+	@./scripts/policy/check-coding-agent-harness.sh
+
+coding-agent-task:
+	@test -n "$(TASK)" || { printf '%s\n' 'TASK is required, e.g. make coding-agent-task TASK=task.md' >&2; exit 2; }
+	@./scripts/policy/check-coding-agent-harness.sh -task "$(TASK)"
+
 edition-test:
 	$(GO) test -v -count=1 ./pkg/editiontest/...
 

README.md

@@ -476,6 +476,8 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
 
 `dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog currently covers messages that mention the current user, one-to-one messages with a specified user, and messages in a specified group.
 
+The default `ndjson`, `json`, and `pretty` output preserves the transport envelope (`type`, `event_type`, string `data`, and `headers`) for existing scripts; `compact` retains its existing processor. Add `--flatten` to emit the stable top-level business fields used by Agent workflows. `--format` controls JSON serialization; `--flatten` controls the data structure and cannot be combined with `-f raw` or `--debug-raw-events`.
+
 > **Prerequisite**: run `dws auth login`. Personal identity is resolved from the OAuth token and cannot be supplied through command-line identity flags.
 
 For an event-focused installation, use the official convenience installer:
@@ -487,19 +489,19 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 ```bash
 # Inspect the public personal event catalog and schema
 dws event list
-dws event schema user_im_message_receive_o2o
+dws event schema user_im_message_receive_o2o --flatten
 
 # Listen for messages that mention the current user
-dws event consume user_im_message_receive_at -f ndjson
+dws event consume user_im_message_receive_at --flatten -f ndjson
 
 # Listen for one-to-one messages with a specified user
-dws event consume user_im_message_receive_o2o --user <userId> -f ndjson
+dws event consume user_im_message_receive_o2o --user <userId> --flatten -f ndjson
 
 # Listen by openDingtalkId (external contact, bot, or cross-organization identity)
-dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> -f ndjson
+dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> --flatten -f ndjson
 
 # Listen for messages in a specified group
-dws event consume user_im_message_receive_group --group <openConversationId> -f ndjson
+dws event consume user_im_message_receive_group --group <openConversationId> --flatten -f ndjson
 
 # Inspect local consumers and cancel a subscription
 dws event status

README_zh.md

@@ -470,6 +470,8 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 
 `dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录包括：当前用户被 @ 的消息、与指定用户的单聊消息、指定群的消息。
 
+默认 `ndjson`、`json`、`pretty` 输出保留兼容 transport envelope（`type`、`event_type`、字符串 `data`、`headers`），`compact` 继续沿用原 processor。Agent 或新脚本显式加 `--flatten` 后，输出稳定的顶层业务字段。`--format` 控制 JSON 序列化，`--flatten` 控制数据结构，且不能与 `-f raw` 或 `--debug-raw-events` 同时使用。
+
 > **前置条件**：先运行 `dws auth login`。个人身份从 OAuth token 解析，不允许通过命令行伪造。
 
 只需要 event 能力时，可以使用官方便捷安装脚本：
@@ -481,19 +483,19 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 ```bash
 # 查看公开个人事件目录和 schema
 dws event list
-dws event schema user_im_message_receive_o2o
+dws event schema user_im_message_receive_o2o --flatten
 
 # 监听当前用户被 @ 的消息
-dws event consume user_im_message_receive_at -f ndjson
+dws event consume user_im_message_receive_at --flatten -f ndjson
 
 # 监听与指定用户的单聊消息
-dws event consume user_im_message_receive_o2o --user <userId> -f ndjson
+dws event consume user_im_message_receive_o2o --user <userId> --flatten -f ndjson
 
 # 使用 openDingtalkId 监听外部联系人、机器人或跨组织身份
-dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> -f ndjson
+dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> --flatten -f ndjson
 
 # 监听指定群的消息
-dws event consume user_im_message_receive_group --group <openConversationId> -f ndjson
+dws event consume user_im_message_receive_group --group <openConversationId> --flatten -f ndjson
 
 # 查看本地 consume，并取消指定订阅
 dws event status

docs/architecture.md

@@ -2,6 +2,29 @@
 
 `dws` is a Go CLI with a versioned, static command surface for DingTalk MCP capabilities. Cobra help serves humans; the embedded Command Catalog serves AI agents.
 
+## Change Rules
+
+Prescriptive layering for new code. Keep descriptions here concise; scoped
+guides own the details.
+
+1. Dependencies point inward: `cmd` → `internal/app` → `internal/helpers` →
+   shared layers (`executor`, `transport`, `output`, `errors`, `safety`,
+   `cobracmd`). Shared layers never import `helpers` or `app`.
+2. New product commands go to `internal/helpers` following
+   [`helpers-structure-guide.md`](helpers-structure-guide.md); do not add
+   product logic to `internal/app`, `internal/cli`, or transport.
+3. New shared behavior joins the existing shared package that owns the
+   contract; do not create a new shared package for a single caller.
+4. Schema/Agent metadata changes start from reviewed inputs in `internal/cli`
+   per [`schema-contributor-guide.md`](schema-contributor-guide.md); never
+   hand-edit generated Catalog output.
+5. Bundled skill content under `skills/` follows
+   [`skill-authoring-guide.md`](skill-authoring-guide.md); skills are embedded
+   via `skills/embed.go` and ship with the binary.
+6. A new top-level package (under `internal/` or `pkg/`) requires a stated
+   boundary reason in its PR and an update to the Repository Structure list
+   below.
+
 ## High-Level Flow
 
 1. `cmd` is the CLI entrypoint, invoking `internal/app` to build the root Cobra command tree.

docs/coding-agent-guide.md

@@ -0,0 +1,112 @@
+# Coding Agent Workflow
+
+This is the task intake and self-check contract for coding agents working in
+this repository. It is intentionally independent of external Wiki systems:
+the checked-out repository is the execution context and evidence source.
+
+## 1. Normalize the task input
+
+Start from the copyable
+[`coding-agent-task-template.md`](coding-agent-task-template.md). Keep one
+primary outcome per task. Fill unknown fields from the issue, nearby code,
+tests, and versioned docs; state any assumption that can affect behavior.
+
+For a saved, filled template, run `make coding-agent-task TASK=path/to/task.md`.
+The local checker rejects missing required fields, unsupported task kinds, and
+unresolved placeholders before implementation begins.
+
+Do not invent acceptance criteria that expand the requested behavior. Stop for
+user input only when the unresolved choice would change externally visible
+behavior, compatibility, destructive scope, credentials, or external state.
+
+## 2. Establish the baseline
+
+1. Run `git status --short` and identify pre-existing changes.
+2. Read the applicable guides linked from the root `AGENTS.md`.
+3. Locate the implementation and its closest tests with `rg`/`rg --files`.
+4. Reproduce the bug or capture the current contract before changing it.
+5. Pick the smallest owning layer; avoid duplicating policy in a caller when a
+   shared typed layer already owns it.
+
+Never clean, overwrite, stage, or reformat unrelated user changes. If a
+required file is already modified, inspect the overlap and preserve both
+intents or stop with the exact conflict.
+
+## 3. Implement from authoritative inputs
+
+- Go behavior belongs in the package that owns the contract, with focused
+  tests beside it.
+- Product handlers under `internal/helpers` follow
+  [`helpers-structure-guide.md`](helpers-structure-guide.md): thin
+  `{product}.go` wiring plus `{product}_{resource}.go` files; do not enlarge
+  megafiles such as `chat.go`.
+- Public CLI paths and flags must match the live Cobra tree and compatibility
+  policies.
+- Schema and Agent-facing changes start from reviewed source inputs; generated
+  outputs are publication artifacts.
+- Documentation describes behavior that exists in the same change.
+- Secrets, tokens, local identities, and private endpoints must not enter code,
+  fixtures, logs, or handoff output.
+
+For generated files, run the repository generator and inspect the resulting
+diff. A large or unrelated generated diff is a signal to stop and find the
+wrong input or nondeterminism, not something to accept automatically.
+
+## 4. Select validation by change surface
+
+Run the narrow check while iterating, then the applicable admission checks
+before handoff. `make help` is the authoritative target list.
+
+| Changed surface | Focused check | Admission checks |
+|---|---|---|
+| Documentation only | inspect links/examples | `git diff --check` |
+| Go implementation | `go test ./path/to/package` | `make format-check`, `make test` |
+| CLI paths or flags | focused command/help tests | `make build`, `./scripts/policy/check-command-surface.sh --strict`, `make interface-integrity` |
+| Schema registry, hints, or generators | focused generator/app tests | `make generate-schema`, `./scripts/policy/check-generated-drift.sh`, `./scripts/policy/check-schema-catalog.sh`, `make test-schema-agent-examples` |
+| Skill command examples | inspect referenced `dws` help | `make skill-command-integrity` |
+| CI or test sharding | run the affected script/test | `make test-plan`, `make lint`, and the CI workflow's pinned actionlint command when workflows change |
+| Packaging or installers | focused release-script tests | `make package`, `./scripts/release/verify-package-managers.sh` |
+| Authentication, transport, or OS-specific code | focused tests, including failure paths | `make test`; run relevant platform checks or disclose the unavailable platform |
+
+`make policy` is the combined policy gate and is appropriate for command,
+Schema, generated-asset, or broad cross-cutting changes. Platform credentials
+and live services are not prerequisites for ordinary unit tests; never turn a
+missing credential into permission to skip deterministic checks.
+
+The guide contract itself is executable. Run `make coding-agent-harness` after
+changing `AGENTS.md`, this guide, the Schema contributor guide, helpers
+structure guide, or their routed commands and paths. This remains a local,
+opt-in agent aid and is not wired into CI.
+
+## Design references
+
+This repository adapts two patterns without copying their product-specific
+rules:
+
+- [Lark CLI's contributor guide](https://github.com/larksuite/cli/blob/5efaf65aec59c33899475bb90e6bff1bc3b5b65c/AGENTS.md): one primary goal, machine-consumable errors/output, and validation selected by behavior surface.
+- [WeCom CLI's root routing guide](https://github.com/WecomTeam/wecom-cli/blob/9eb7898b959861af879495e211e37431fa908f19/AGENTS.md) and [human helper template](https://github.com/WecomTeam/wecom-cli/blob/9eb7898b959861af879495e211e37431fa908f19/src/helpers/HUMANS.md): a thin root guide, scoped implementation guidance, and a copyable request format.
+
+## 5. Pre-handoff self-check
+
+Confirm every applicable item:
+
+- The diff implements the stated goal and no unrelated cleanup.
+- Pre-existing changes are still present and were not attributed to this task.
+- New behavior has a regression test; removed behavior has an explicit reason.
+- Public command paths, flags, output, exit behavior, and compatibility remain
+  intentional.
+- Destructive or mutating operations retain the required confirmation path.
+- Generated files came from their reviewed inputs and generation is clean.
+- Docs and examples use commands accepted by current help/Schema.
+- Errors preserve actionable context without leaking secrets.
+- `git diff --check` passes and the final diff has been read.
+- Every reported check is labeled passed, failed, or not run with a reason.
+
+Use this compact handoff shape:
+
+```text
+Outcome: what is now true
+Files: intentional files changed
+Validation: exact commands and results
+Limits: unrun checks, environment constraints, follow-ups
+```

docs/coding-agent-task-template.md

@@ -0,0 +1,35 @@
+# Coding Agent Task Template
+
+Copy this block into an issue or coding-agent request. One task should have one
+primary outcome; split unrelated outcomes instead of hiding them in acceptance
+criteria.
+
+```text
+Task kind: bug | feature | refactor | docs | policy | release
+Goal (one primary outcome):
+Current behavior and evidence:
+Acceptance criteria:
+In scope (packages/files/surfaces):
+Out of scope:
+Compatibility constraints:
+Interface impact (commands/flags/output/errors/exit codes/Schema):
+Safety or data-mutation constraints:
+Expected validation:
+Known environment limitations:
+```
+
+For a command or remote-interface task, add the smallest concrete invocation
+and contract evidence available:
+
+```text
+CLI path and example argv:
+Current --help or Schema excerpt:
+Remote method and request/response shape, if relevant:
+Expected stdout/stderr and exit behavior:
+Mutation preview/confirmation behavior:
+```
+
+Do not paste credentials, tokens, private endpoints, or production business
+data. Use redacted fixtures and say which evidence is unavailable. Save the
+filled block and run `make coding-agent-task TASK=path/to/task.md` to validate
+it before implementation.

docs/helpers-structure-guide.md

@@ -0,0 +1,214 @@
+# Helpers Package Structure Guide
+
+This is the coding-structure contract for product commands under
+`internal/helpers/`. Business teams and coding agents must follow it when
+adding or moving CLI leaves. Behavioral contracts (stdout, errors, confirmation,
+Schema) stay in [`internal/helpers/AGENTS.md`](../internal/helpers/AGENTS.md);
+this document only owns file layout and split rules.
+
+Reference implementations already in-tree:
+
+| Pattern | Use as |
+|---|---|
+| [`sheet.go`](../internal/helpers/sheet.go) + `sheet_*.go` | Preferred product layout: thin root wiring, resource files |
+| [`chat_media_upload.go`](../internal/helpers/chat_media_upload.go) | Incremental extract from a megafile without behavior change |
+| `connect_*.go` | Concern-based split inside the same `helpers` package |
+
+Anti-pattern to stop growing: single megafiles such as `chat.go` / `aitable.go`
+(thousands of lines). New work must not enlarge them.
+
+## 1. Package boundary
+
+Keep product handlers in the flat package `helpers`:
+
+```text
+internal/helpers/                 # package helpers (default)
+  register_products.go            # public product registration table
+  {product}.go                    # product root: new{Product}Command()
+  {product}_{resource}.go         # one resource / cohesive concern
+  {product}_{resource}_test.go    # focused tests beside the file
+  helpers.go / interfaces.go …    # cross-product shared machinery
+```
+
+Do **not** create `internal/helpers/{product}/` subpackages by default. The flat
+package exists so leaves can share unexported helpers (`callMCPToolOnServer`,
+flag validators, confirmation wrappers, transport adapters) without exporting a
+public API surface. Split into a subpackage only when the concern is a real
+library boundary with its own tests and almost no need for helpers-private
+symbols—and get an explicit review for that exception.
+
+Repository layers outside helpers stay unchanged:
+
+| Layer | Owns |
+|---|---|
+| `internal/app` | Root/static wiring, plugin load |
+| `internal/helpers` | Product Cobra trees and handler behavior |
+| `internal/cobracmd` | Shared Cobra construction primitives |
+| `internal/executor`, `internal/transport` | Invocation and transport |
+| `internal/output`, `internal/errors`, `internal/safety` | Projection, failures, confirmation |
+| `internal/cli` | Schema identity / Agent metadata |
+
+Ordinary product leaves belong in helpers. Do not push product business mapping
+into app, transport, or Schema generators.
+
+## 2. File roles inside a product
+
+### 2.1 Product root — `{product}.go`
+
+Owns exactly one entry constructor, registered from `register_products.go`:
+
+```go
+func newChatCommand() *cobra.Command { /* wire subgroups only */ }
+```
+
+The root file should:
+
+1. Define the product `cobra.Command` (`Use` / `Short` / `Long` / aliases).
+2. Call resource factories and `AddCommand` them.
+3. Register product-level aliases or hint stubs when needed.
+4. Avoid large inline `RunE` bodies for leaves.
+
+Target size: wiring-only, roughly under **400 lines** (see `sheet.go` ≈ 270).
+If the root grows past that because leaves are inlined, extract a resource file.
+
+### 2.2 Resource / concern file — `{product}_{resource}.go`
+
+Split on the **CLI path segment or cohesive concern**, not on “one function per
+file”:
+
+| CLI path | File |
+|---|---|
+| `dws chat group …` | `chat_group.go` |
+| `dws chat message …` | `chat_message.go` |
+| `dws chat media …` | `chat_media_upload.go` (or `chat_media.go`) |
+| `dws sheet filter-view …` | `sheet_filter_view.go` |
+| `dws sheet dimension …` | `sheet_dimension.go` |
+
+Each file exposes one or more unexported factories, for example:
+
+```go
+func newChatGroupCmd() *cobra.Command { … }
+func newChatMessageCmd() *cobra.Command { … }
+func newWorkbookCmds() []*cobra.Command { … }
+```
+
+The product root only wires those factories. Prefer keeping a leaf’s flags,
+`RunE`, and nearby request-mapping helpers in the same resource file until a
+helper is reused by multiple resources.
+
+Soft size guide per resource file:
+
+| Lines | Action |
+|---|---|
+| < 600 | Normal |
+| 600–1000 | Prefer splitting the next cohesive subgroup before adding more |
+| > 1000 | Required split before landing substantial new leaves |
+
+“One command per file” is **not** required. Tiny sibling leaves that share
+flags and mapping belong together. Split when the file holds multiple unrelated
+resources or becomes hard to review.
+
+### 2.3 Shared product helpers — `{product}_{concern}.go`
+
+Use a concern suffix when code is shared across resources and is not itself a
+command tree:
+
+- `sheet_validate.go` — shared validation
+- `chat_args.go` / similar — grant/arg builders used by several leaves
+- `connect_command.go` — slash-command parsing used by the daemon
+
+Do not park unrelated products’ utilities in these files. Cross-product
+machinery belongs in non-prefixed shared files (`helpers.go`, `interfaces.go`,
+output/error helpers), never copied per product.
+
+### 2.4 Tests
+
+- Name tests after the file or scenario: `chat_message_search_test.go`,
+  `sheet_filter_view_test.go`.
+- Prefer exercising public product construction (`newChatCommand().Find(…)`)
+  for command-surface regressions.
+- Pure helpers may be unit-tested directly in the same package.
+- A mechanical file split without behavior change should keep existing tests
+  green with no assertion edits; if tests must change, the split leaked a
+  behavior or visibility change and needs review.
+
+## 3. Registration and naming
+
+1. Public products enter the CLI only through the table in
+   `register_products.go` (`new{Product}Command` factories). Do not invent a
+   second registration path for ordinary product leaves.
+2. Constructor names stay unexported (`new…`) unless a deliberate test helper
+   requires otherwise.
+3. File names are lowercase snake_case. Match the CLI resource token when
+   practical (`filter-view` → `filter_view`).
+4. Do not hand-edit generated sync markers in `register_products.go` outside
+   the product-registration workflow that owns that file.
+
+## 4. How to add a new command (business-team checklist)
+
+1. Confirm the owning product and CLI path with `dws <product> --help`.
+2. Open `{product}.go` only to wire `AddCommand`; put the leaf in
+   `{product}_{resource}.go`.
+3. If the product is still a megafile (`chat.go`, `aitable.go`, …) and your
+   resource file does not exist yet, **create the resource file and move only
+   the subgroup you need** (or add the new leaf there and wire it from the
+   root). Do not append another large leaf into the megafile.
+4. Keep stdout / stderr / error / confirmation contracts from
+   `internal/helpers/AGENTS.md`.
+5. If path, flags, safety, or Agent selection change, follow
+   [`schema-contributor-guide.md`](schema-contributor-guide.md).
+6. Add or extend the closest test; run
+   `go test ./internal/helpers -count=1` (or a tighter `-run`) plus the checks
+   selected by [`coding-agent-guide.md`](coding-agent-guide.md).
+
+## 5. Migrating an existing megafile
+
+Mechanical splits are welcome and preferred over “big-bang” rewrites.
+
+Rules for a split PR:
+
+1. **Behavior-neutral**: same command paths, flags, help text, request mapping,
+   confirmation, and output.
+2. **Stable entrypoint**: keep `new{Product}Command()` as the registration
+   symbol; only its body becomes wiring.
+3. **Move by resource**: extract one CLI subgroup per commit/PR when possible
+   (`group`, `message`, `category`, …).
+4. **No drive-by cleanups** in the same PR (renames, flag redesign, Schema
+   edits) unless the task explicitly includes them.
+5. **Stop growing the megafile**: after the first extract, new leaves for that
+   resource go to the new file only.
+
+Suggested first-wave split for `chat` (illustrative, not mandatory order):
+
+| Extract to | Contents |
+|---|---|
+| `chat.go` | `newChatCommand()` wiring only |
+| `chat_permission.go` | `chmod`, `data-auth` |
+| `chat_group.go` | `group` tree |
+| `chat_message.go` | `message` tree |
+| `chat_category.go` | `category` tree |
+| `chat_bot.go` | `bot` tree |
+| `chat_conversation.go` | top-level conversation ops (`set-top`, mute, red-point, …) |
+| existing `chat_media_upload.go` | keep; optionally rename to `chat_media.go` only in a dedicated rename PR |
+
+Apply the same pattern to `aitable`, `attendance`, `mail`, and `doc` when those
+products take new work.
+
+## 6. What this guide does not change
+
+- Wire format, MCP method names, or Schema identity rules.
+- The choice to keep `package helpers` flat.
+- Runtime confirmation / dry-run policy (still owned by safety + Schema metadata).
+- Permission to skip tests because a change was “only a move”—moves still need
+  the product’s focused tests green.
+
+## 7. Harness check
+
+After editing this guide or its links from `AGENTS.md` /
+`internal/helpers/AGENTS.md`, run:
+
+```bash
+make coding-agent-harness
+```
+
+This check is a local, opt-in agent aid; it is not part of `make policy` or CI.

docs/schema-contributor-guide.md

@@ -0,0 +1,150 @@
+# Schema and Agent Contract Contributor Guide
+
+Read this guide when changing public CLI commands, Schema identity or
+parameters, Agent selection/safety metadata, or generated Schema assets.
+
+## Ownership and data flow
+
+The publication graph is one way:
+
+```text
+Cobra command tree
+  + reviewed CommandRegistry identity/navigation
+  + reviewed metadata parameter overlays
+  -> EffectiveCommandRegistry and executable binding
+  + parameter bindings
+  + reviewed selection and safety/interface metadata
+  + pinned MCP metadata
+  -> one resolved ToolSpec registry/index
+  -> generated Agent metadata and embedded Schema Catalog
+  -> dws schema projections and runtime metadata lookup
+```
+
+The owning sources are:
+
+| Concern | Authoritative input |
+|---|---|
+| Executable paths and accepted flags | Cobra tree built by `app.NewRootCommand()` |
+| Stable canonical identity, primary path, aliases, navigation | `internal/cli/schema_command_registry.json` |
+| Registry editing contract | `internal/cli/schema_command_registry.schema.json` |
+| Safety, interface, runtime gates, parameter overlays | `internal/cli/schema_hints/metadata/<product>.json` |
+| Agent selection prose and examples | `internal/cli/schema_hints/selection/<product>.json` |
+| Product-to-hint-file routing | `internal/cli/schema_hints/index.json` |
+| Flag/property bindings | `internal/cli/schema_parameter_bindings.json` |
+| Sanitized interface fallback | `internal/cli/schema_mcp_metadata.json` |
+| Exact reviewed omissions from Schema | `internal/cli/schema_command_exclusions.json` |
+
+Generated files under `internal/cli/schema_agent_metadata/` and
+`internal/cli/schema_catalog.json` are output only. Runtime loading is a delivery
+boundary: it must not create or repair commands, flags, registry entries, or
+generation inputs.
+
+## Invariants
+
+1. Every delivered tool resolves to a public runnable Cobra leaf.
+2. Every public runnable Cobra leaf resolves to Schema or has one exact,
+   reviewed exclusion with a non-empty reason. Wildcard/prefix exclusions are
+   forbidden.
+3. The reviewed CommandRegistry is the only stable identity/navigation source.
+   Native annotations, when present, are consistency assertions and must agree.
+4. Metadata overlays may describe or constrain real flags; they cannot create
+   commands, flags, interfaces, or unknown RPCs.
+5. Cobra-required flags are a hard floor. An overlay may make an optional flag
+   required but cannot make a Cobra-required flag optional.
+6. Each tool is resolved once into one typed `ToolSpec`; all Catalog, `schema
+   --all`, leaf, summary, safety, and runtime projections derive from it.
+7. Provenance winner values must equal delivered values. Same-precedence
+   conflicts fail instead of being merged silently.
+8. `confirmation=user_required` requires user confirmation before `--yes`.
+   Do not infer confirmation mechanically from risk/effect; keep runtime gates
+   and published metadata consistent.
+9. Stored examples use real primary/alias paths and accepted flags, satisfy all
+   required/constraint rules, contain no shell comments, and never add `--yes`.
+10. `schema --all` remains the complete compatibility export. Routine discovery
+    should use overview, product/group, then leaf queries.
+
+When Help and shipped Schema disagree, treat it as contract drift. Cobra still
+defines executable flags; use the safer interpretation for confirmation or
+stop rather than guessing.
+
+Parameter and safety resolution is source-precedence based and otherwise
+value-neutral: a value must not win merely because it looks stricter. Preserve
+all candidates and the selected source, and fail same-precedence conflicts.
+Command text resolves from reviewed tool hints, then command-specific Cobra
+help, then MCP metadata; generic RPC prose must not replace a specialized
+leaf's description. An alias lookup may change only view fields such as
+`cli_path` and `is_alias`, never the resolved command contract.
+
+## Editing workflow
+
+1. Confirm the live path and flags in the Cobra tree and current `--help`.
+2. Change only the owning reviewed block. Do not copy generated Catalog fields
+   into inputs or mix selection fields into metadata files.
+3. Keep registry edits limited to intentional identity/navigation changes.
+4. For selection prose, write decision-oriented routing: when to choose the
+   command, when a sibling is better, and the result shape. Do not restate help.
+5. For parameter overlays, use an exact runnable leaf and real flags; set
+   `reviewed: true` with a concrete review reason.
+6. Regenerate the complete snapshot; publication is deterministic even when
+   only one product input changed.
+7. Inspect authored and generated diffs separately, then run the gates below.
+
+Pinned MCP metadata is a sanitized fallback. When a task requires refreshing
+it and a personal session is available, inspect live metadata with `dws auth
+status`, `dws cache refresh`, and `dws schema <canonical> -f json`. Never print
+or commit tokens. Evidence precedence is Runtime/Cobra, live MCP, pinned MCP,
+then Skill prose as evidence only.
+
+## Required checks
+
+```bash
+make generate-schema
+./scripts/policy/check-runtime-confirmation-truth.sh
+./scripts/policy/check-generated-drift.sh
+./scripts/policy/check-schema-catalog.sh
+./scripts/policy/check-command-surface.sh --strict
+make test-schema-agent-examples
+```
+
+Also run focused tests for the changed binder, generator, command, or runtime
+consumer. Run reverse-completeness tests whenever the Cobra tree changes.
+
+Agent examples are contract-checked by default. Eligible reviewed dry-run
+examples are additionally exercised by `make test-schema-agent-examples` with
+isolated state; a runtime failure must not be converted into an ad hoc skip.
+Live-model selection evaluation is optional and never a normal CI dependency.
+
+An example enters runtime dry-run only when its final typed contract publishes
+an explicit reviewed dry-run capability. Risk or confirmation metadata does
+not manufacture preview support, and the harness never injects `--yes`. A
+narrow precondition that cannot be derived from the contract may use an exact,
+reviewed `example_dispositions` entry to narrow dry-run to contract-only; it
+must not become a general skip or a fallback applied after execution fails.
+
+Every `use_when` entry is a positive selection fixture and every `avoid_when`
+entry is a negative fixture for that tool. The deterministic gate checks
+coverage and contradictions; it does not claim to prove natural-language
+understanding. When explicitly requested, the optional live-model smoke test
+can be run with:
+
+```bash
+DWS_AGENT_SELECTION_LIVE=1 \
+ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... \
+go test ./internal/app -run TestManualAgentSelectionArkLive -count=1
+```
+
+Use `DWS_AGENT_SELECTION_FULL=1` for the full fixture or
+`DWS_AGENT_SELECTION_CASES=<comma-separated-ids>` for selected cases. A custom
+HTTPS provider must be explicitly allowlisted; plaintext is accepted only for
+a loopback test server so credentials are not sent over arbitrary clear text.
+
+## Runtime boundaries
+
+- `schema list` is a progressive overview; `schema --all` is the complete,
+  non-compact compatibility baseline with full parameters, constraints, and
+  safety semantics.
+- `--compact` saves discovery context but is not a full compatibility export.
+- `dws <path> --help` decides whether a path and its flags are executable. Leaf
+  Schema owns Agent selection, mapping, constraints, and safety semantics.
+- Help and Schema describe commands; they do not return DingTalk business
+  data. Execute the real read/list/search command after discovery.

docs/skill-authoring-guide.md

@@ -0,0 +1,75 @@
+# Skill Authoring Guide
+
+Contract for the bundled agent skills under `skills/`. Skills are embedded via
+`skills/embed.go` and installed by `dws skill setup`, so every edit ships with
+the binary. Keep skill prose concise: long command references belong in
+`references/`, not in `SKILL.md`.
+
+## Layout
+
+| Path | Role |
+|---|---|
+| `skills/mono/` | Single bundled skill (stable mode) with shared `references/` and `scripts/` |
+| `skills/multi/dingtalk-<product>/` | One skill per product (experimental mode) |
+| `skills/multi/dws-shared/` | Shared prerequisite: auth, global flags, routing, safety |
+| `skills/embed.go` | Embeds `mono` + `multi`; do not add new roots |
+
+A product skill directory contains:
+
+```text
+dingtalk-<product>/
+  SKILL.md          # frontmatter + concise routing/usage prose
+  references/       # long command references, playbooks
+  scripts/          # executable recipes (python), kept minimal
+```
+
+## SKILL.md contract
+
+Frontmatter:
+
+```yaml
+---
+name: dingtalk-<product>
+description: <触发场景>. Use when … Distinct from <相邻skill>(…). 命令前缀：dws <product>。
+cli_version: ">=<minimum dws version>"
+metadata:
+  category: product
+  stability: experimental
+  requires:
+    bins:
+      - dws
+---
+```
+
+Body rules:
+
+- State the safety rules directly in concise prose; there is no injected
+  preamble mechanism in this repository.
+- State the `dws-shared` prerequisite for multi skills.
+- Route by intent: shortcuts table first when one covers the scenario, then
+  scripts/recipes, then atomic commands with `dws schema` / `--help`.
+- Every referenced `dws` command must exist in the current binary; verify with
+  `dws <cmd> --help` and keep prose version-agnostic ("以当前 dws 二进制为准").
+- Mutating commands must point at the leaf Schema `confirmation` contract; do
+  not invent confirmation rules in prose.
+
+## Dual-write rule
+
+Skill behavior described in prose must match the CLI it references. When a
+command, flag, or confirmation contract changes, update the affected `SKILL.md`
+/ `references/` in the same change; when skill routing changes, check whether
+Schema selection hints (`internal/cli/schema_hints/`) need a reviewed update
+per [`schema-contributor-guide.md`](schema-contributor-guide.md).
+
+## Validation
+
+| Change | Check |
+|---|---|
+| Any skill edit | `make skill-command-integrity` |
+| Referenced CLI surface changed | `./scripts/policy/check-command-surface.sh --strict` |
+| Schema hints touched | `make generate-schema` + schema gates |
+| Recipe scripts | run the script's own smoke path or `test/skill_e2e` when applicable |
+
+`make skill-command-integrity` builds `scripts/policy/skill-command-check` and
+verifies every `dws` command referenced by skills resolves against the current
+binary. Run it before handoff; do not claim a command exists without it.

internal/app/auth_registry.go

@@ -49,6 +49,15 @@ func RegisterPluginAuth(productID string, auth *PluginAuth) {
 	pluginAuthRegistry[productID] = auth
 }
 
+// ClearPluginAuth removes credentials for a plugin product. Registration uses
+// this before applying an accepted descriptor so a descriptor without custom
+// auth cannot inherit stale credentials from an earlier root construction.
+func ClearPluginAuth(productID string) {
+	pluginAuthMu.Lock()
+	defer pluginAuthMu.Unlock()
+	delete(pluginAuthRegistry, productID)
+}
+
 // LookupPluginAuth returns the authentication credentials registered
 // for the given product ID, or nil if none exists.
 func LookupPluginAuth(productID string) (*PluginAuth, bool) {

internal/app/coverage_edges_test.go

@@ -1469,10 +1469,10 @@ func TestCrossPlatformCoveragePersonalEventPureCoverage(t *testing.T) {
 	if !ok {
 		t.Fatal("mention definition missing")
 	}
-	if err := renderPersonalSchema(io.Discard, def, ""); err != nil {
+	if err := renderPersonalSchema(io.Discard, def, "", false); err != nil {
 		t.Fatal(err)
 	}
-	if err := renderPersonalSchema(io.Discard, def, "yaml"); err == nil {
+	if err := renderPersonalSchema(io.Discard, def, "yaml", true); err == nil {
 		t.Fatal("unsupported schema format succeeded")
 	}
 	for _, key := range []string{"", "unknown", personal.EventMention, personal.EventFromUser} {

internal/app/event_command.go

@@ -112,6 +112,7 @@ func newEventConsumeCommand() *cobra.Command {
 		dryRun       bool
 		foreground   bool
 		asIdentity   string
+		flatten      bool
 		personalOpts personalConsumeOptions
 		streamOpts   eventStreamTicketOptions
 	)
@@ -127,7 +128,11 @@ func newEventConsumeCommand() *cobra.Command {
   json            每事件多行美化 JSON（必须配 --max-events 或 --duration）
   pretty          同 json，未来加颜色
   raw             仅 SDK 原始 payload，无外层封装
-  compact         扁平化 + 解析嵌套 + 抽取语义字段（Agent 友好）
+  compact         单行紧凑 JSON；不传 --flatten 时沿用原 compact processor
+
+数据结构：
+  ndjson/json/pretty 默认保持 transport envelope（type/event_type/data/headers）
+  --flatten          结构化格式输出稳定的顶层业务字段，适合 Agent / 脚本直接消费
 
 默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加
 --profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用
@@ -144,6 +149,7 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 			}
 			if as == "user" {
 				personalOpts.EventKey = firstArg(args)
+				personalOpts.Flatten = flatten
 				personalOpts.Common = commonConsumeOptions{
 					EventTypes: eventTypes,
 					Filter:     filter,
@@ -167,6 +173,7 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 				return fmt.Errorf("event consume: --debug-raw-events is only supported with --as user")
 			}
 			if err := rejectChangedFlags(c, "user",
+				"flatten",
 				"subscribe-id",
 				"rule",
 				"name",
@@ -280,6 +287,8 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 		"提示 bus 客户端期望 compact 渲染（语义透传，bus 仍按原 payload 投递）")
 	f.StringVarP(&formatRaw, "format", "f", "ndjson",
 		"输出格式 (ndjson/json/pretty/raw/compact)；事件流默认 ndjson")
+	f.BoolVar(&flatten, "flatten", false,
+		"将个人事件 transport envelope 投影为稳定的顶层业务字段")
 	f.StringVar(&outputDir, "output-dir", "",
 		"每事件写一个文件到该目录 ({type}_{id}_{ts}.json)；与 stdout 互斥")
 	f.StringArrayVar(&routesRaw, "route", nil,

internal/app/event_personal_command.go

@@ -61,6 +61,7 @@ type commonConsumeOptions struct {
 type personalConsumeOptions struct {
 	Common           commonConsumeOptions
 	EventKey         string
+	Flatten          bool
 	DebugRawEvents   bool
 	SubscribeID      string
 	Rule             string
@@ -140,6 +141,7 @@ var (
 func newEventSchemaCommand() *cobra.Command {
 	var asIdentity string
 	var formatRaw string
+	var flatten bool
 	cmd := &cobra.Command{
 		Use:               "schema <event_key>",
 		Short:             "显示事件 schema",
@@ -157,11 +159,12 @@ func newEventSchemaCommand() *cobra.Command {
 			if !def.Public {
 				return personal.PublicAvailabilityError(args[0])
 			}
-			return renderPersonalSchema(c.OutOrStdout(), def, formatRaw)
+			return renderPersonalSchema(c.OutOrStdout(), def, formatRaw, flatten)
 		},
 	}
 	cmd.Flags().StringVar(&asIdentity, "as", "user", "事件身份: user")
 	cmd.Flags().StringVarP(&formatRaw, "format", "f", "json", "输出格式: json")
+	cmd.Flags().BoolVar(&flatten, "flatten", false, "显示 --flatten 消费模式对应的顶层业务字段 schema")
 	hideEventInternalFlags(cmd, "as")
 	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
 		Name:        "event_key",
@@ -189,7 +192,7 @@ func runPersonalEventList(c *cobra.Command, opts personalListOptions) error {
 	return tw.Flush()
 }
 
-func renderPersonalSchema(w io.Writer, def personal.Definition, format string) error {
+func renderPersonalSchema(w io.Writer, def personal.Definition, format string, flatten bool) error {
 	format = strings.ToLower(strings.TrimSpace(format))
 	if format == "" {
 		format = "json"
@@ -199,7 +202,7 @@ func renderPersonalSchema(w io.Writer, def personal.Definition, format string) e
 	}
 	enc := json.NewEncoder(w)
 	enc.SetIndent("", "  ")
-	return enc.Encode(personal.BuildSchemaDocument(def))
+	return enc.Encode(personal.BuildSchemaDocumentForMode(def, flatten))
 }
 
 func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) error {
@@ -207,6 +210,19 @@ func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) erro
 	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
 		return err
 	}
+	rawFormat := ""
+	if f := c.Flags().Lookup("format"); f != nil && f.Changed {
+		rawFormat = opts.Common.FormatRaw
+	}
+	normalised, fellback := consume.NormalizeFormat(rawFormat)
+	if fellback && !opts.Common.Quiet {
+		fmt.Fprintf(c.ErrOrStderr(), "WARN: --format %q has no meaning for event stream; using ndjson\n", rawFormat)
+	}
+	if err := validatePersonalEventOutputMode(opts.Flatten, opts.DebugRawEvents, normalised); err != nil {
+		return fmt.Errorf("event consume --as user: %w", err)
+	}
+	projector := personalEventProjector(opts.DebugRawEvents, opts.Flatten)
+
 	configDir := defaultConfigDir()
 	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
 	if err != nil {
@@ -221,16 +237,6 @@ func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) erro
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
-	rawFormat := ""
-	if f := c.Flags().Lookup("format"); f != nil && f.Changed {
-		rawFormat = opts.Common.FormatRaw
-	}
-	normalised, fellback := consume.NormalizeFormat(rawFormat)
-	if fellback && !opts.Common.Quiet {
-		fmt.Fprintf(c.ErrOrStderr(), "WARN: --format %q has no meaning for event stream; using ndjson\n", rawFormat)
-	}
-	projector := personalEventProjector(opts.DebugRawEvents)
-
 	if opts.Common.DryRun {
 		if strings.TrimSpace(opts.SubscribeID) == "" {
 			if err := validatePersonalSubscriptionOptions(opts); err != nil {
@@ -247,6 +253,7 @@ func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) erro
 			Duration:       opts.Common.Duration,
 			EventKey:       opts.EventKey,
 			Format:         normalised,
+			Flatten:        opts.Flatten,
 			OutputDir:      opts.Common.OutputDir,
 			Routes:         routes,
 			Projector:      projector,
@@ -303,6 +310,7 @@ func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) erro
 		Duration:         opts.Common.Duration,
 		EventKey:         eventKey,
 		Format:           normalised,
+		Flatten:          opts.Flatten,
 		OutputDir:        opts.Common.OutputDir,
 		Routes:           routes,
 		Projector:        projector,
@@ -366,11 +374,27 @@ func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) erro
 	return err
 }
 
-func personalEventProjector(debugRawEvents bool) consume.Projector {
+func personalEventProjector(debugRawEvents, flatten bool) consume.Projector {
 	if debugRawEvents {
 		return func(ev transport.Event) (any, error) { return ev, nil }
 	}
-	return personal.ProjectOutput
+	if flatten {
+		return personal.ProjectOutput
+	}
+	return nil
+}
+
+func validatePersonalEventOutputMode(flatten, debugRawEvents bool, format consume.Format) error {
+	if !flatten {
+		return nil
+	}
+	if debugRawEvents {
+		return fmt.Errorf("--flatten and --debug-raw-events are mutually exclusive")
+	}
+	if format == consume.FormatRaw {
+		return fmt.Errorf("--flatten and --format raw are mutually exclusive")
+	}
+	return nil
 }
 
 func applyPersonalConsumeFilters(cfg *consume.Config, opts personalConsumeOptions, subscribeID, eventKey string) {

internal/app/event_personal_debug_test.go

@@ -20,6 +20,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/spf13/cobra"
 )
 
 func TestApplyPersonalConsumeFiltersDebugRawEvents(t *testing.T) {
@@ -52,11 +53,14 @@ func TestApplyPersonalConsumeFiltersDefault(t *testing.T) {
 	}
 }
 
-func TestPersonalEventProjectorUsesRawEnvelopeForDebug(t *testing.T) {
-	if personalEventProjector(false) == nil {
-		t.Fatal("normal personal consume projector = nil")
+func TestPersonalEventProjectorSelectsExplicitModes(t *testing.T) {
+	if personalEventProjector(false, false) != nil {
+		t.Fatal("default personal consume should preserve transport envelope")
 	}
-	projector := personalEventProjector(true)
+	if personalEventProjector(false, true) == nil {
+		t.Fatal("flatten personal consume projector = nil")
+	}
+	projector := personalEventProjector(true, false)
 	if projector == nil {
 		t.Fatal("debug raw personal consume projector = nil")
 	}
@@ -74,6 +78,69 @@ func TestPersonalEventProjectorUsesRawEnvelopeForDebug(t *testing.T) {
 	}
 }
 
+func TestEventConsumeFlattenRejectsRawModesBeforeIdentityResolution(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "raw format",
+			args: []string{personal.EventMention, "--flatten", "--format", "raw"},
+			want: "--flatten and --format raw are mutually exclusive",
+		},
+		{
+			name: "raw debug",
+			args: []string{personal.EventMention, "--flatten", "--debug-raw-events"},
+			want: "--flatten and --debug-raw-events are mutually exclusive",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+			cmd := newEventConsumeCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("Execute() error = %v, want %q", err, tc.want)
+			}
+			if strings.Contains(err.Error(), "login") || strings.Contains(err.Error(), "token") {
+				t.Fatalf("output-mode validation ran after identity resolution: %v", err)
+			}
+		})
+	}
+}
+
+func TestValidatePersonalEventOutputModeAllowsFlattenStructuredFormats(t *testing.T) {
+	for _, format := range []consume.Format{consume.FormatNDJSON, consume.FormatJSON, consume.FormatPretty, consume.FormatCompact} {
+		if err := validatePersonalEventOutputMode(true, false, format); err != nil {
+			t.Fatalf("validatePersonalEventOutputMode(true, false, %q) error = %v", format, err)
+		}
+	}
+}
+
+func TestEventConsumeFlattenFlagIsForwarded(t *testing.T) {
+	oldRun := eventRunPersonalConsume
+	t.Cleanup(func() { eventRunPersonalConsume = oldRun })
+
+	var got personalConsumeOptions
+	eventRunPersonalConsume = func(_ *cobra.Command, opts personalConsumeOptions) error {
+		got = opts
+		return nil
+	}
+	cmd := newEventConsumeCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{personal.EventMention, "--flatten", "--format", "compact"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if !got.Flatten || got.Common.FormatRaw != "compact" {
+		t.Fatalf("forwarded options = %#v", got)
+	}
+}
+
 func TestEventConsumeDebugRawEventsRequiresUserMode(t *testing.T) {
 	cmd := newEventConsumeCommand()
 	cmd.SilenceUsage = true

internal/app/event_personal_output_test.go

@@ -188,7 +188,44 @@ func TestPersonalEventSchemaHidesSchemaIDs(t *testing.T) {
 	}
 }
 
-func TestPersonalEventSchemaUsesSingleJSONSchema(t *testing.T) {
+func TestPersonalEventSchemaDefaultsToTransportEnvelope(t *testing.T) {
+	cmd := newEventSchemaCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetArgs([]string{personal.EventSingleChat})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(out.Bytes(), &doc); err != nil {
+		t.Fatalf("schema output is not JSON: %v\n%s", err, out.String())
+	}
+	if doc["jq_root_path"] != ".data | fromjson" {
+		t.Fatalf("jq_root_path = %#v, want .data | fromjson", doc["jq_root_path"])
+	}
+	schema, ok := doc["schema"].(map[string]any)
+	if !ok {
+		t.Fatalf("schema = %#v, want object", doc["schema"])
+	}
+	props, ok := schema["properties"].(map[string]any)
+	if !ok {
+		t.Fatalf("schema.properties = %#v, want object", schema["properties"])
+	}
+	for _, field := range []string{"type", "seq", "event_type", "data", "headers", "subscribe_id"} {
+		if _, ok := props[field]; !ok {
+			t.Fatalf("default envelope schema missing %q: %#v", field, props)
+		}
+	}
+	for _, field := range []string{"content", "sender", "conversation_id", "timestamp"} {
+		if _, ok := props[field]; ok {
+			t.Fatalf("default envelope schema unexpectedly contains flat field %q", field)
+		}
+	}
+}
+
+func TestPersonalEventFlattenedSchemaUsesSingleJSONSchema(t *testing.T) {
 	for _, eventKey := range []string{
 		personal.EventMention,
 		personal.EventSingleChat,
@@ -200,7 +237,7 @@ func TestPersonalEventSchemaUsesSingleJSONSchema(t *testing.T) {
 			cmd.SilenceErrors = true
 			var out bytes.Buffer
 			cmd.SetOut(&out)
-			cmd.SetArgs([]string{eventKey})
+			cmd.SetArgs([]string{eventKey, "--flatten"})
 			if err := cmd.Execute(); err != nil {
 				t.Fatalf("Execute() error = %v", err)
 			}
@@ -316,7 +353,7 @@ func TestPersonalActionEventSchemaMatchesFlatOutput(t *testing.T) {
 				cmd.SilenceErrors = true
 				var out bytes.Buffer
 				cmd.SetOut(&out)
-				cmd.SetArgs([]string{eventKey})
+				cmd.SetArgs([]string{eventKey, "--flatten"})
 				if err := cmd.Execute(); err != nil {
 					t.Fatal(err)
 				}
@@ -367,6 +404,9 @@ func TestEventSchemaDefaultsToUser(t *testing.T) {
 	if doc["event_key"] != personal.EventSingleChat {
 		t.Fatalf("event_key = %#v, want %s", doc["event_key"], personal.EventSingleChat)
 	}
+	if doc["jq_root_path"] != ".data | fromjson" {
+		t.Fatalf("jq_root_path = %#v, want default envelope path", doc["jq_root_path"])
+	}
 }
 
 func TestPersonalEventFromUserIsPubliclyAvailable(t *testing.T) {
@@ -469,6 +509,9 @@ func TestEventConsumeCobraSchemaIncludesOpenDingTalkID(t *testing.T) {
 	if _, ok := params["odid"]; ok {
 		t.Fatalf("schema parameters unexpectedly include odid alias: %#v", params)
 	}
+	if _, ok := params["flatten"]; !ok {
+		t.Fatalf("schema parameters missing flatten: %#v", params)
+	}
 	for _, name := range []string{"user", "open-dingtalk-id", "group"} {
 		param, ok := params[name].(map[string]any)
 		if !ok {

internal/app/legacy.go

@@ -27,21 +27,27 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller) []*cobra.Command {
+func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller, loadUserShortcuts bool) []*cobra.Command {
 	injectStaticServers()
 	helpers.InitDeps(caller)
 	commands := helpers.NewPublicCommands(runner)
 	// Load user-defined shortcuts (~/.dws/shortcuts/*.yaml) BEFORE compiling the
 	// command tree, so distilled high-frequency operations mount alongside the
 	// built-ins. Conflicts with built-ins are skipped inside Load.
-	if _, err := userdef.Load(); err != nil {
-		slog.Warn("shortcut: failed to load user-defined shortcuts", "error", err)
+	if loadUserShortcuts {
+		if _, err := userdef.Load(); err != nil {
+			slog.Warn("shortcut: failed to load user-defined shortcuts", "error", err)
+		}
 	}
 	// Built-in + user shortcuts (`dws <service> +<command>`) share the same
 	// command tree; mergeTopLevelCommands folds each shortcut's service parent
 	// into the matching helper command so the `+leaf` sits alongside existing
 	// subcommands.
-	commands = append(commands, builtin.Commands()...)
+	if loadUserShortcuts {
+		commands = append(commands, builtin.Commands()...)
+	} else {
+		commands = append(commands, builtin.BaseCommands()...)
+	}
 	return mergeTopLevelCommands(commands)
 }
 

internal/app/plugin_commands_coverage_test.go

@@ -0,0 +1,675 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+type pluginFailRunner struct{}
+
+func (pluginFailRunner) Run(context.Context, executor.Invocation) (executor.Result, error) {
+	return executor.Result{}, errors.New("runner failed")
+}
+
+type pluginWrongFlagValue struct{}
+
+func (pluginWrongFlagValue) String() string   { return "" }
+func (pluginWrongFlagValue) Set(string) error { return nil }
+func (pluginWrongFlagValue) Type() string     { return "wrong" }
+
+func TestPluginCompilerRejectsInvalidDuplicateAndEmptyDefinitions(t *testing.T) {
+	invalidRoot := conferencePluginDescriptor()
+	invalidRoot.CLI.Command = "Invalid Root"
+	if commands := buildPluginCommands([]mcptypes.ServerDescriptor{invalidRoot}, executor.EchoRunner{}, nil); len(commands) != 0 {
+		t.Fatalf("invalid root produced commands %#v", commands)
+	}
+
+	descriptor := conferencePluginDescriptor()
+	descriptor.CLI.Groups = map[string]mcptypes.CLIGroupDef{
+		"empty": {Description: "removed when no leaf survives"},
+	}
+	descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"":        {CLIName: "blank-tool"},
+		"hidden":  {CLIName: "hidden", Hidden: true},
+		"invalid": {CLIName: "Invalid Leaf"},
+		"first":   {CLIName: "same"},
+		"second":  {CLIName: "same"},
+	}
+	commands := buildPluginCommands([]mcptypes.ServerDescriptor{descriptor}, executor.EchoRunner{}, nil)
+	if len(commands) != 1 {
+		t.Fatalf("commands = %#v", commands)
+	}
+	if requireOptionalPluginChild(commands[0], "same") == nil {
+		t.Fatal("valid leaf was not retained")
+	}
+	if requireOptionalPluginChild(commands[0], "empty") != nil {
+		t.Fatal("empty group was not pruned")
+	}
+
+	empty := conferencePluginDescriptor()
+	empty.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"hidden": {CLIName: "hidden", Hidden: true},
+	}
+	if commands := buildPluginCommands([]mcptypes.ServerDescriptor{empty}, executor.EchoRunner{}, nil); len(commands) != 0 {
+		t.Fatalf("empty overlay produced commands %#v", commands)
+	}
+}
+
+func TestPluginLeafExecutionErrorsAndBodyWrapper(t *testing.T) {
+	base := conferencePluginDescriptor()
+	base.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"wrapped": {
+			CLIName:     "wrapped",
+			BodyWrapper: "body",
+			Flags: map[string]mcptypes.CLIFlagOverride{
+				"value": {Required: true},
+			},
+		},
+	}
+	runner := &pluginCaptureRunner{}
+	root := pluginTestRoot(buildPluginCommands([]mcptypes.ServerDescriptor{base}, runner, nil)...)
+	root.SetArgs([]string{"conference", "wrapped", "--value", "ok", "--params", `{"body":{"old":1},"_meta":"kept"}`})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("wrapped command: %v", err)
+	}
+	want := map[string]any{
+		"_meta": "kept",
+		"body":  map[string]any{"old": float64(1), "value": "ok"},
+	}
+	if !reflect.DeepEqual(runner.invocations[0].Params, want) {
+		t.Fatalf("wrapped params = %#v, want %#v", runner.invocations[0].Params, want)
+	}
+
+	for _, testCase := range []struct {
+		name   string
+		runner executor.Runner
+		args   []string
+	}{
+		{name: "invalid json", runner: executor.EchoRunner{}, args: []string{"conference", "wrapped", "--json", "["}},
+		{name: "missing required", runner: executor.EchoRunner{}, args: []string{"conference", "wrapped"}},
+		{name: "missing runner", runner: nil, args: []string{"conference", "wrapped", "--value", "ok"}},
+		{name: "runner error", runner: pluginFailRunner{}, args: []string{"conference", "wrapped", "--value", "ok"}},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			commandRoot := pluginTestRoot(buildPluginCommands([]mcptypes.ServerDescriptor{base}, testCase.runner, nil)...)
+			commandRoot.SetArgs(testCase.args)
+			if err := commandRoot.Execute(); err == nil {
+				t.Fatal("expected command error")
+			}
+		})
+	}
+
+	for _, flagName := range []string{"json", "params"} {
+		t.Run("unreadable "+flagName, func(t *testing.T) {
+			commands := buildPluginCommands([]mcptypes.ServerDescriptor{base}, executor.EchoRunner{}, nil)
+			leaf := requirePluginChild(t, commands[0], "wrapped")
+			leaf.Flags().Lookup(flagName).Value = pluginWrongFlagValue{}
+			commandRoot := pluginTestRoot(commands...)
+			commandRoot.SetArgs([]string{"conference", "wrapped", "--value", "ok"})
+			if err := commandRoot.Execute(); err == nil {
+				t.Fatal("expected unreadable flag error")
+			}
+		})
+	}
+}
+
+func TestPluginBindingCompilerCoversAliasesAndPositionalValidators(t *testing.T) {
+	reservations := pluginFlagReservations{
+		names:      map[string]bool{"reserved": true},
+		shorthands: map[string]bool{},
+	}
+	bindings, _, _, ok := registerPluginBindings("alias", mcptypes.CLIToolOverride{
+		Flags: map[string]mcptypes.CLIFlagOverride{
+			"value": {Alias: "value", Aliases: []string{"", "Bad", "value", "other"}},
+		},
+	}, reservations)
+	if !ok || !reflect.DeepEqual(bindings[0].names, []string{"value", "other"}) {
+		t.Fatalf("alias bindings = (%#v, %v)", bindings, ok)
+	}
+	if _, _, _, ok := registerPluginBindings("conflict", mcptypes.CLIToolOverride{
+		Flags: map[string]mcptypes.CLIFlagOverride{"value": {Alias: "reserved"}},
+	}, reservations); ok {
+		t.Fatal("reserved flag was accepted")
+	}
+	if _, _, _, ok := registerPluginBindings("negative", mcptypes.CLIToolOverride{
+		Flags: map[string]mcptypes.CLIFlagOverride{"value": {Positional: true, PositionalIndex: -1}},
+	}, reservations); ok {
+		t.Fatal("negative positional index was accepted")
+	}
+	if _, _, _, ok := registerPluginBindings("duplicate", mcptypes.CLIToolOverride{
+		Flags: map[string]mcptypes.CLIFlagOverride{
+			"first":  {Positional: true, PositionalIndex: 0},
+			"second": {Positional: true, PositionalIndex: 0},
+		},
+	}, reservations); ok {
+		t.Fatal("duplicate positional index was accepted")
+	}
+	if _, _, _, ok := registerPluginBindings("gap", mcptypes.CLIToolOverride{
+		Flags: map[string]mcptypes.CLIFlagOverride{
+			"second": {Positional: true, PositionalIndex: 1},
+		},
+	}, reservations); ok {
+		t.Fatal("non-contiguous positional indexes were accepted")
+	}
+
+	for _, testCase := range []struct {
+		name    string
+		flags   map[string]mcptypes.CLIFlagOverride
+		wantUse string
+		valid   []string
+		invalid []string
+	}{
+		{
+			name: "exact",
+			flags: map[string]mcptypes.CLIFlagOverride{
+				"second": {Positional: true, PositionalIndex: 1, Required: true},
+				"first":  {Positional: true, PositionalIndex: 0, Required: true},
+			},
+			wantUse: "exact [first] [second]", valid: []string{"a", "b"}, invalid: []string{"a"},
+		},
+		{
+			name: "range",
+			flags: map[string]mcptypes.CLIFlagOverride{
+				"first":  {Positional: true, PositionalIndex: 0, Required: true},
+				"second": {Positional: true, PositionalIndex: 1},
+			},
+			wantUse: "range [first] [second]", valid: []string{"a"}, invalid: []string{},
+		},
+		{
+			name: "maximum",
+			flags: map[string]mcptypes.CLIFlagOverride{
+				"first":  {Positional: true, PositionalIndex: 0},
+				"second": {Positional: true, PositionalIndex: 1},
+			},
+			wantUse: "maximum [first] [second]", valid: []string{}, invalid: []string{"a", "b", "c"},
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			_, use, validator, ok := registerPluginBindings(testCase.name, mcptypes.CLIToolOverride{Flags: testCase.flags}, reservations)
+			if !ok || use != testCase.wantUse {
+				t.Fatalf("binding contract = (%q, %v)", use, ok)
+			}
+			cmd := &cobra.Command{Use: testCase.name}
+			if err := validator(cmd, testCase.valid); err != nil {
+				t.Fatalf("valid args: %v", err)
+			}
+			if err := validator(cmd, testCase.invalid); err == nil {
+				t.Fatal("invalid args were accepted")
+			}
+		})
+	}
+}
+
+func TestPluginFlagRegistrationAndReadingCoversAllKinds(t *testing.T) {
+	cmd := &cobra.Command{Use: "leaf"}
+	override := mcptypes.CLIToolOverride{Flags: map[string]mcptypes.CLIFlagOverride{
+		"integer": {Default: "2", Shorthand: "i", Hidden: true},
+		"float":   {Default: "1.5"},
+		"boolean": {Default: "true"},
+		"slice":   {Default: "one, ,two"},
+		"json":    {Default: `{"old":true}`},
+		"string":  {Default: "text"},
+	}}
+	bindings := []pluginFlagBinding{
+		{property: "integer", names: []string{"integer", "integer-alias"}, kind: pluginFlagInt},
+		{property: "float", names: []string{"float"}, kind: pluginFlagFloat},
+		{property: "boolean", names: []string{"boolean"}, kind: pluginFlagBool},
+		{property: "slice", names: []string{"slice"}, kind: pluginFlagStringSlice},
+		{property: "json", names: []string{"json-value"}, kind: pluginFlagJSON},
+		{property: "string", names: []string{"string"}, kind: pluginFlagString},
+	}
+	registerPluginFlags(cmd, bindings, override, pluginFlagReservations{shorthands: map[string]bool{}})
+	for name, raw := range map[string]string{
+		"integer": "3", "float": "2.5", "boolean": "false",
+		"slice": "three,four", "json-value": `{"ok":true}`, "string": "changed",
+	} {
+		if err := cmd.Flags().Set(name, raw); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	wants := map[string]any{
+		"integer": 3,
+		"float":   2.5,
+		"boolean": false,
+		"slice":   []string{"three", "four"},
+		"json":    map[string]any{"ok": true},
+		"string":  "changed",
+	}
+	for _, binding := range bindings {
+		value, err := readPluginFlag(cmd.Flags(), binding.names[0], binding.kind)
+		if err != nil || !reflect.DeepEqual(value, wants[binding.property]) {
+			t.Fatalf("read %s = (%#v, %v), want %#v", binding.property, value, err, wants[binding.property])
+		}
+	}
+	if !cmd.Flags().Lookup("integer").Hidden || !cmd.Flags().Lookup("integer-alias").Hidden {
+		t.Fatal("hidden primary or alias flag was exposed")
+	}
+	if err := cmd.Flags().Set("json-value", "{"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readPluginFlag(cmd.Flags(), "json-value", pluginFlagJSON); err == nil {
+		t.Fatal("invalid JSON flag was accepted")
+	}
+	cmd.Flags().Lookup("json-value").Value = pluginWrongFlagValue{}
+	if _, err := readPluginFlag(cmd.Flags(), "json-value", pluginFlagJSON); err == nil {
+		t.Fatal("wrong JSON flag type was accepted")
+	}
+}
+
+func TestCollectPluginBindingsCoversEveryValueSourceAndFailure(t *testing.T) {
+	t.Run("sources", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "leaf"}
+		registerPluginFlag(cmd.Flags(), "flag", "", "", pluginFlagString, "")
+		if err := cmd.Flags().Set("flag", "from-flag"); err != nil {
+			t.Fatal(err)
+		}
+		t.Setenv("PLUGIN_COVERAGE_ENV", "7")
+		params := map[string]any{"existing": "from-json"}
+		bindings := []pluginFlagBinding{
+			{property: "flag", names: []string{"flag"}, kind: pluginFlagString},
+			{property: "existing", kind: pluginFlagString},
+			{property: "positional", kind: pluginFlagBool, positional: true, positionalIndex: 0},
+			{property: "default", kind: pluginFlagFloat, defaultProvided: true, defaultValue: "1.5"},
+			{property: "env", kind: pluginFlagInt, envDefault: "PLUGIN_COVERAGE_ENV"},
+			{property: "optional", kind: pluginFlagString},
+		}
+		if err := collectPluginBindings(cmd, []string{"true"}, bindings, params); err != nil {
+			t.Fatal(err)
+		}
+		want := map[string]any{
+			"flag": "from-flag", "existing": "from-json", "positional": true,
+			"default": 1.5, "env": 7,
+		}
+		if !reflect.DeepEqual(params, want) {
+			t.Fatalf("params = %#v, want %#v", params, want)
+		}
+	})
+
+	for _, testCase := range []struct {
+		name    string
+		prepare func(t *testing.T, cmd *cobra.Command)
+		args    []string
+		binding pluginFlagBinding
+		params  map[string]any
+	}{
+		{
+			name: "wrong flag type",
+			prepare: func(t *testing.T, cmd *cobra.Command) {
+				cmd.Flags().String("value", "", "")
+				if err := cmd.Flags().Set("value", "x"); err != nil {
+					t.Fatal(err)
+				}
+			},
+			binding: pluginFlagBinding{property: "value", names: []string{"value"}, kind: pluginFlagInt},
+		},
+		{name: "invalid positional", args: []string{"maybe"}, binding: pluginFlagBinding{property: "value", kind: pluginFlagBool, positional: true, positionalIndex: 0}},
+		{name: "invalid default", binding: pluginFlagBinding{property: "value", kind: pluginFlagInt, defaultProvided: true, defaultValue: "bad"}},
+		{
+			name:    "invalid env",
+			prepare: func(t *testing.T, _ *cobra.Command) { t.Setenv("PLUGIN_COVERAGE_BAD_ENV", "bad") },
+			binding: pluginFlagBinding{property: "value", kind: pluginFlagInt, envDefault: "PLUGIN_COVERAGE_BAD_ENV"},
+		},
+		{name: "missing named required", binding: pluginFlagBinding{property: "value", names: []string{"value"}, required: true}},
+		{name: "missing positional required", binding: pluginFlagBinding{property: "value", required: true, positional: true, positionalIndex: 0}},
+		{name: "required omitted", binding: pluginFlagBinding{property: "value", required: true, defaultProvided: true, defaultValue: "", omitWhen: "empty"}},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "leaf"}
+			if testCase.prepare != nil {
+				testCase.prepare(t, cmd)
+			}
+			if err := collectPluginBindings(cmd, testCase.args, []pluginFlagBinding{testCase.binding}, testCase.params); err == nil {
+				t.Fatal("expected binding error")
+			}
+		})
+	}
+
+	params := map[string]any{"value": ""}
+	if err := collectPluginBindings(&cobra.Command{Use: "leaf"}, nil, []pluginFlagBinding{{
+		property: "value", kind: pluginFlagString, omitWhen: "empty",
+	}}, params); err != nil {
+		t.Fatal(err)
+	}
+	if _, exists := params["value"]; exists {
+		t.Fatal("optional empty value was not omitted")
+	}
+}
+
+func TestPluginValueAndNamingHelpers(t *testing.T) {
+	parseCases := []struct {
+		kind pluginFlagKind
+		raw  string
+		want any
+	}{
+		{pluginFlagInt, " 2 ", 2},
+		{pluginFlagFloat, " 2.5 ", 2.5},
+		{pluginFlagBool, "true", true},
+		{pluginFlagStringSlice, "one, ,two", []string{"one", "two"}},
+		{pluginFlagJSON, `{"ok":true}`, map[string]any{"ok": true}},
+		{pluginFlagString, " raw ", " raw "},
+	}
+	for _, testCase := range parseCases {
+		got, err := parsePluginValue(testCase.raw, testCase.kind)
+		if err != nil || !reflect.DeepEqual(got, testCase.want) {
+			t.Fatalf("parse %q = (%#v, %v), want %#v", testCase.raw, got, err, testCase.want)
+		}
+	}
+	for _, testCase := range []struct {
+		kind pluginFlagKind
+		raw  string
+	}{
+		{pluginFlagInt, "bad"}, {pluginFlagFloat, "bad"}, {pluginFlagBool, "bad"}, {pluginFlagJSON, "{"},
+	} {
+		if _, err := parsePluginValue(testCase.raw, testCase.kind); err == nil {
+			t.Fatalf("invalid %q was accepted", testCase.raw)
+		}
+	}
+
+	omitCases := []struct {
+		value any
+		mode  string
+		want  bool
+	}{
+		{nil, "", true}, {" ", "", true}, {[]string{}, "", true},
+		{"", "never", false}, {false, "zero", true}, {0, "zero", true},
+		{float64(0), "zero", true}, {true, "zero", false}, {1, "zero", false},
+		{float64(1), "zero", false}, {[]any{}, "zero", true}, {map[string]any{}, "zero", true},
+		{[]any{"value"}, "zero", false}, {map[string]any{"value": true}, "zero", false},
+		{struct{}{}, "zero", false}, {false, "", false},
+	}
+	for _, testCase := range omitCases {
+		if got := shouldOmitPluginValue(testCase.value, testCase.mode); got != testCase.want {
+			t.Fatalf("omit (%#v, %q) = %v, want %v", testCase.value, testCase.mode, got, testCase.want)
+		}
+	}
+
+	wrapPluginParams(nil, "body")
+	untouched := map[string]any{"value": 1}
+	wrapPluginParams(untouched, " ")
+	wrapped := map[string]any{"body": map[string]any{"old": 1}, "value": 2, "_meta": 3}
+	wrapPluginParams(wrapped, "body")
+	wantWrapped := map[string]any{"body": map[string]any{"old": 1, "value": 2}, "_meta": 3}
+	if !reflect.DeepEqual(wrapped, wantWrapped) {
+		t.Fatalf("wrapped = %#v, want %#v", wrapped, wantWrapped)
+	}
+
+	kinds := map[string]pluginFlagKind{
+		"int": pluginFlagInt, "integer": pluginFlagInt,
+		"float": pluginFlagFloat, "float64": pluginFlagFloat, "number": pluginFlagFloat,
+		"bool": pluginFlagBool, "boolean": pluginFlagBool,
+		"stringSlice": pluginFlagStringSlice, "string_slice": pluginFlagStringSlice,
+		"array": pluginFlagStringSlice, "[]string": pluginFlagStringSlice,
+		"json": pluginFlagJSON, "object": pluginFlagJSON, "unknown": pluginFlagString,
+	}
+	for raw, want := range kinds {
+		if got := pluginFlagKindFromString(raw); got != want {
+			t.Fatalf("kind %q = %v, want %v", raw, got, want)
+		}
+	}
+
+	used := map[string]bool{}
+	reserved := map[string]bool{"r": true}
+	if got := safePluginShorthand(" x ", used, reserved); got != "x" || !used["x"] {
+		t.Fatalf("safe shorthand = %q / %#v", got, used)
+	}
+	for _, raw := range []string{"", "xy", "x", "r"} {
+		if got := safePluginShorthand(raw, used, reserved); got != "" {
+			t.Fatalf("unsafe shorthand %q = %q", raw, got)
+		}
+	}
+
+	baseReservations := pluginReservedFlags(nil)
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().StringP("custom", "c", "", "")
+	rootReservations := pluginReservedFlags(root)
+	if !baseReservations.names["yes"] || !rootReservations.names["custom"] || !rootReservations.shorthands["c"] {
+		t.Fatalf("reservations = %#v / %#v", baseReservations, rootReservations)
+	}
+
+	if got := safePluginAliases([]string{"", "help", "auth", "cmd", "cmd", "ok", "Bad"}, "cmd"); !reflect.DeepEqual(got, []string{"ok"}) {
+		t.Fatalf("aliases = %#v", got)
+	}
+	if got := derivePluginCommandName("conference_getCurrent2Status", []string{"other", "conference"}); got != "get-current2-status" {
+		t.Fatalf("derived name = %q", got)
+	}
+	if got := pluginKebabName(" HTTP2.Foo_bar baz@ "); got != "http2-foo-bar-baz@" {
+		t.Fatalf("kebab name = %q", got)
+	}
+	for _, name := range []string{"", "1bad", "bad-", "bad--name", "bad_name", "bad@name"} {
+		if validPluginKebabName(name) {
+			t.Fatalf("invalid kebab name %q was accepted", name)
+		}
+	}
+	if !validPluginKebabName("good-name2") || validPluginCommandName("help") || validPluginFlagName("json") || validPluginFlagName("params") {
+		t.Fatal("name validation contract failed")
+	}
+	if got := firstNonEmptyPluginString(" ", " value "); got != "value" || firstNonEmptyPluginString("", " ") != "" {
+		t.Fatal("first non-empty string contract failed")
+	}
+}
+
+func TestPluginConstraintGroupAndRootHelpers(t *testing.T) {
+	cmd := &cobra.Command{Use: "leaf"}
+	for _, name := range []string{"a", "b", "c"} {
+		cmd.Flags().String(name, "", "")
+	}
+	applyPluginFlagConstraints(cmd, mcptypes.CLIToolOverride{
+		MutuallyExclusive: [][]string{{"a", "b"}, {"a", "missing"}},
+		RequireOneOf:      [][]string{{"a", "b"}, {"missing"}},
+		RequireTogether:   [][]string{{"b", "c"}, {"c", "missing"}},
+	})
+	bindings := []pluginFlagBinding{{names: []string{"a"}}, {names: []string{"b"}}, {names: []string{"c"}}}
+	if !validPluginFlagConstraints(bindings, mcptypes.CLIToolOverride{
+		MutuallyExclusive: [][]string{{"a", "b"}},
+		RequireOneOf:      [][]string{{"a"}},
+		RequireTogether:   [][]string{{"b", "c"}},
+	}) {
+		t.Fatal("valid plugin constraints were rejected")
+	}
+	for _, invalid := range []mcptypes.CLIToolOverride{
+		{MutuallyExclusive: [][]string{{"a"}}},
+		{RequireOneOf: [][]string{{"missing"}}},
+		{RequireTogether: [][]string{{"a", "a"}}},
+	} {
+		if validPluginFlagConstraints(bindings, invalid) {
+			t.Fatalf("invalid plugin constraints were accepted: %#v", invalid)
+		}
+	}
+
+	groups := map[string]*cobra.Command{}
+	root := &cobra.Command{Use: "root"}
+	group := ensurePluginGroup(root, "parent.child", "child description", groups)
+	if group.Name() != "child" || group.Short != "child description" || !cmdutil.IsPluginSourced(group) {
+		t.Fatalf("group = %#v", group)
+	}
+	if again := ensurePluginGroup(root, "parent.child", "ignored", groups); again != group {
+		t.Fatal("existing group was not reused")
+	}
+	for _, invalid := range []string{"safe.bad_name", "_bad", ".parent", "parent."} {
+		if got := ensurePluginGroup(root, invalid, "invalid", groups); got != nil {
+			t.Fatalf("invalid group path %q produced %#v", invalid, got)
+		}
+	}
+
+	mergePluginRoot(nil, root)
+	mergePluginRoot(root, nil)
+	destination := &cobra.Command{Use: "plugin", Aliases: []string{"one"}}
+	source := &cobra.Command{Use: "plugin", Aliases: []string{"one", "two"}}
+	source.AddCommand(&cobra.Command{Use: "leaf"})
+	mergePluginRoot(destination, source)
+	if !reflect.DeepEqual(destination.Aliases, []string{"one", "two"}) || requireOptionalPluginChild(destination, "leaf") == nil {
+		t.Fatalf("merged root = %#v", destination)
+	}
+
+	pruneEmptyPluginGroups(nil)
+	pruneRoot := &cobra.Command{Use: "root"}
+	empty := cobracmd.NewGroupCommand("empty", "empty")
+	nonEmpty := cobracmd.NewGroupCommand("non-empty", "non-empty")
+	nonEmpty.AddCommand(&cobra.Command{Use: "leaf"})
+	pruneRoot.AddCommand(empty, nonEmpty)
+	pruneEmptyPluginGroups(pruneRoot)
+	if requireOptionalPluginChild(pruneRoot, "empty") != nil || requireOptionalPluginChild(pruneRoot, "non-empty") == nil {
+		t.Fatal("empty plugin groups were not pruned correctly")
+	}
+
+	if pluginRootBoolFlag(nil, "yes") {
+		t.Fatal("nil command reported a root flag")
+	}
+	noFlag := &cobra.Command{Use: "root"}
+	if pluginRootBoolFlag(noFlag, "yes") {
+		t.Fatal("missing flag reported true")
+	}
+	wrongType := &cobra.Command{Use: "root"}
+	wrongType.PersistentFlags().String("yes", "true", "")
+	if pluginRootBoolFlag(wrongType, "yes") {
+		t.Fatal("wrong flag type reported true")
+	}
+	boolRoot := &cobra.Command{Use: "root"}
+	boolRoot.PersistentFlags().Bool("yes", false, "")
+	if err := boolRoot.PersistentFlags().Set("yes", "true"); err != nil {
+		t.Fatal(err)
+	}
+	if !pluginRootBoolFlag(boolRoot, "yes") {
+		t.Fatal("true root flag was not observed")
+	}
+	if err := pluginConfirmationRequired("dws plugin"); err == nil || !strings.Contains(err.Error(), "sensitive") {
+		t.Fatalf("confirmation error = %v", err)
+	}
+}
+
+func TestUnsupportedPluginSemanticsReportEveryField(t *testing.T) {
+	overlays := []struct {
+		value mcptypes.CLIOverlay
+		want  string
+	}{
+		{mcptypes.CLIOverlay{Parent: "root"}, "parent"},
+		{mcptypes.CLIOverlay{Group: "group"}, "group"},
+		{mcptypes.CLIOverlay{ServerDeps: []string{"other"}}, "serverDeps"},
+		{mcptypes.CLIOverlay{Hints: map[string]json.RawMessage{"x": json.RawMessage(`{}`)}}, "hintCommands"},
+		{mcptypes.CLIOverlay{RedirectTo: "other"}, "redirectTo"},
+		{mcptypes.CLIOverlay{}, ""},
+	}
+	for _, testCase := range overlays {
+		if got := unsupportedPluginOverlay(testCase.value); got != testCase.want {
+			t.Fatalf("unsupported overlay = %q, want %q", got, testCase.want)
+		}
+	}
+
+	tools := []struct {
+		value mcptypes.CLIToolOverride
+		want  string
+	}{
+		{mcptypes.CLIToolOverride{CLIAliases: []string{"x"}}, "cliAliases"},
+		{mcptypes.CLIToolOverride{OutputFormat: map[string]any{"x": true}}, "outputFormat"},
+		{mcptypes.CLIToolOverride{ServerOverride: "other"}, "serverOverride"},
+		{mcptypes.CLIToolOverride{RedirectTo: "x"}, "redirectTo"},
+		{mcptypes.CLIToolOverride{Pipeline: []json.RawMessage{json.RawMessage(`{}`)}}, "pipeline"},
+		{mcptypes.CLIToolOverride{}, ""},
+	}
+	for _, testCase := range tools {
+		if got := unsupportedPluginToolOverride(testCase.value); got != testCase.want {
+			t.Fatalf("unsupported tool = %q, want %q", got, testCase.want)
+		}
+	}
+
+	flags := []struct {
+		value mcptypes.CLIFlagOverride
+		want  string
+	}{
+		{mcptypes.CLIFlagOverride{MapsTo: "x"}, "mapsTo"},
+		{mcptypes.CLIFlagOverride{Transform: "x"}, "transform"},
+		{mcptypes.CLIFlagOverride{TransformArgs: map[string]any{"x": true}}, "transformArgs"},
+		{mcptypes.CLIFlagOverride{RuntimeDefault: "x"}, "runtimeDefault"},
+		{mcptypes.CLIFlagOverride{PipelineLocal: true}, "pipelineLocal"},
+		{mcptypes.CLIFlagOverride{Type: "mystery"}, "type"},
+		{mcptypes.CLIFlagOverride{OmitWhen: "sometimes"}, "omitWhen"},
+		{mcptypes.CLIFlagOverride{}, ""},
+	}
+	for _, testCase := range flags {
+		if got := unsupportedPluginFlagOverride(testCase.value); got != testCase.want {
+			t.Fatalf("unsupported flag = %q, want %q", got, testCase.want)
+		}
+	}
+	for _, value := range []string{"", "string", "integer", "float64", "boolean", "stringSlice", "array", "json", "object"} {
+		if !supportedPluginFlagType(value) {
+			t.Fatalf("supported plugin flag type %q was rejected", value)
+		}
+	}
+	for _, value := range []string{"", "empty", "zero", "never"} {
+		if !supportedPluginOmitMode(value) {
+			t.Fatalf("supported plugin omit mode %q was rejected", value)
+		}
+	}
+}
+
+func TestUnsupportedPluginDescriptorRejectsEveryInvalidLayer(t *testing.T) {
+	testCases := []struct {
+		name   string
+		mutate func(*mcptypes.ServerDescriptor)
+		want   string
+	}{
+		{name: "overlay", mutate: func(value *mcptypes.ServerDescriptor) { value.CLI.Parent = "root" }, want: "parent"},
+		{name: "no tools", mutate: func(value *mcptypes.ServerDescriptor) { value.CLI.ToolOverrides = nil }, want: ""},
+		{name: "root", mutate: func(value *mcptypes.ServerDescriptor) { value.CLI.Command = "Bad" }, want: "command"},
+		{name: "declared group", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.Groups = map[string]mcptypes.CLIGroupDef{"bad_name": {}}
+		}, want: "groups"},
+		{name: "blank tool", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"": {}}
+		}, want: "tool"},
+		{name: "tool semantics", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {ServerOverride: "drive"}}
+		}, want: "serverOverride"},
+		{name: "hidden tool", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {Hidden: true, ServerOverride: "drive"}}
+		}, want: ""},
+		{name: "derived leaf", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"conference_derived_tool": {}}
+		}, want: ""},
+		{name: "leaf", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {CLIName: "Bad"}}
+		}, want: "cliName"},
+		{name: "leaf group", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {CLIName: "leaf", Group: "bad_name"}}
+		}, want: "group"},
+		{name: "flags", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {
+				CLIName: "leaf",
+				Flags:   map[string]mcptypes.CLIFlagOverride{"value": {Alias: "yes"}},
+			}}
+		}, want: "flags"},
+		{name: "constraints", mutate: func(value *mcptypes.ServerDescriptor) {
+			value.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{"tool": {
+				CLIName:         "leaf",
+				Flags:           map[string]mcptypes.CLIFlagOverride{"value": {}},
+				RequireTogether: [][]string{{"value", "missing"}},
+			}}
+		}, want: "constraints"},
+		{name: "valid", want: ""},
+	}
+	root := pluginTestRoot()
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			descriptor := conferencePluginDescriptor()
+			if testCase.mutate != nil {
+				testCase.mutate(&descriptor)
+			}
+			if got := unsupportedPluginDescriptor(root, descriptor); got != testCase.want {
+				t.Fatalf("unsupported descriptor = %q, want %q", got, testCase.want)
+			}
+		})
+	}
+}

internal/app/plugin_commands_test.go

@@ -0,0 +1,809 @@
+// 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"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+type pluginCaptureRunner struct {
+	invocations []executor.Invocation
+}
+
+func (r *pluginCaptureRunner) Run(_ context.Context, invocation executor.Invocation) (executor.Result, error) {
+	r.invocations = append(r.invocations, invocation)
+	return executor.Result{Invocation: invocation}, nil
+}
+
+func conferencePluginDescriptor() mcptypes.ServerDescriptor {
+	return mcptypes.ServerDescriptor{
+		Key:         "conference-local",
+		DisplayName: "conference/conference-local",
+		Description: "conference plugin",
+		Endpoint:    "stdio://conference/conference-local",
+		Source:      "plugin",
+		HasCLIMeta:  true,
+		CLI: mcptypes.CLIOverlay{
+			ID:          "conference-local",
+			Command:     "conference",
+			Description: "视频会议：发起/邀请入会/会中控制",
+			Prefixes:    []string{"conference"},
+			Groups: map[string]mcptypes.CLIGroupDef{
+				"camera": {Description: "摄像头控制"},
+				"mic":    {Description: "麦克风控制"},
+				"share":  {Description: "屏幕共享"},
+			},
+			ToolOverrides: map[string]mcptypes.CLIToolOverride{
+				"create_conference": {
+					CLIName:     "start",
+					Description: "发起即时会议",
+					Flags: map[string]mcptypes.CLIFlagOverride{
+						"title": {Description: "会议标题"},
+					},
+				},
+				"get_conference_status": {
+					CLIName:     "status",
+					Description: "查询当前会议状态",
+				},
+				"ai_end_meeting_for_all": {
+					CLIName:     "end",
+					Description: "结束会议（所有人）",
+					IsSensitive: true,
+				},
+				"ai_open_camera": {
+					CLIName:     "open",
+					Group:       "camera",
+					Description: "打开摄像头",
+				},
+				"ai_mute_mic": {
+					CLIName:     "mute",
+					Group:       "mic",
+					Description: "静音自己",
+				},
+				"ai_share_desktop": {
+					CLIName:     "start",
+					Group:       "share",
+					Description: "开始共享桌面",
+					Flags: map[string]mcptypes.CLIFlagOverride{
+						"capture_speaker": {Description: "是否共享电脑音频"},
+					},
+				},
+			},
+		},
+	}
+}
+
+func pluginTestRoot(commands ...*cobra.Command) *cobra.Command {
+	root := &cobra.Command{
+		Use:           "dws",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+	}
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.PersistentFlags().Bool("yes", false, "")
+	root.PersistentFlags().StringP("format", "f", "json", "")
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.AddCommand(commands...)
+	return root
+}
+
+func requirePluginChild(t *testing.T, parent *cobra.Command, names ...string) *cobra.Command {
+	t.Helper()
+	current := parent
+	for _, name := range names {
+		var next *cobra.Command
+		for _, child := range current.Commands() {
+			if child.Name() == name {
+				next = child
+				break
+			}
+		}
+		if next == nil {
+			t.Fatalf("missing plugin command %q below %q", name, current.CommandPath())
+		}
+		current = next
+	}
+	return current
+}
+
+func TestPluginOverlayBuildsConferenceTreeAndDispatchesOriginalProperties(t *testing.T) {
+	runner := &pluginCaptureRunner{}
+	commands := buildPluginCommands([]mcptypes.ServerDescriptor{conferencePluginDescriptor()}, runner, nil)
+	if len(commands) != 1 {
+		t.Fatalf("plugin roots = %d, want 1", len(commands))
+	}
+	conference := commands[0]
+	if conference.Name() != "conference" || conference.Short != "视频会议：发起/邀请入会/会中控制" {
+		t.Fatalf("conference root = %q / %q", conference.Name(), conference.Short)
+	}
+	if !cmdutil.IsPluginSourced(conference) {
+		t.Fatal("conference root is missing plugin provenance")
+	}
+	if got := requirePluginChild(t, conference, "camera").Short; got != "摄像头控制" {
+		t.Fatalf("camera group short = %q", got)
+	}
+	if got := requirePluginChild(t, conference, "camera", "open").Short; got != "打开摄像头" {
+		t.Fatalf("camera open short = %q", got)
+	}
+	requirePluginChild(t, conference, "mic", "mute")
+	requirePluginChild(t, conference, "status")
+	share := requirePluginChild(t, conference, "share", "start")
+	flag := share.Flags().Lookup("capture-speaker")
+	if flag == nil || flag.Usage != "是否共享电脑音频" {
+		t.Fatalf("capture-speaker flag = %#v", flag)
+	}
+
+	root := pluginTestRoot(commands...)
+	root.SetArgs([]string{
+		"conference", "start",
+		"--json", `{"from_json":"kept","title":"json"}`,
+		"--params", `{"from_params":2,"title":"params"}`,
+		"--title", "验证会议",
+		"--dry-run",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("conference start: %v", err)
+	}
+	if len(runner.invocations) != 1 {
+		t.Fatalf("runner calls = %d, want 1", len(runner.invocations))
+	}
+	invocation := runner.invocations[0]
+	if invocation.Kind != "compat_invocation" ||
+		invocation.CanonicalProduct != "conference-local" ||
+		invocation.Tool != "create_conference" ||
+		!invocation.DryRun {
+		t.Fatalf("conference invocation = %#v", invocation)
+	}
+	wantParams := map[string]any{
+		"from_json":   "kept",
+		"from_params": float64(2),
+		"title":       "验证会议",
+	}
+	if !reflect.DeepEqual(invocation.Params, wantParams) {
+		t.Fatalf("conference params = %#v, want %#v", invocation.Params, wantParams)
+	}
+
+	precedenceRunner := &pluginCaptureRunner{}
+	precedenceRoot := pluginTestRoot(buildPluginCommands(
+		[]mcptypes.ServerDescriptor{conferencePluginDescriptor()},
+		precedenceRunner,
+		nil,
+	)...)
+	precedenceRoot.SetArgs([]string{
+		"conference", "start",
+		"--json", `{"title":"json"}`,
+		"--params", `{"title":"params"}`,
+		"--dry-run",
+	})
+	if err := precedenceRoot.Execute(); err != nil {
+		t.Fatalf("conference payload precedence: %v", err)
+	}
+	if got := precedenceRunner.invocations[0].Params["title"]; got != "params" {
+		t.Fatalf("conference payload title = %#v, want --params value", got)
+	}
+}
+
+func TestPluginOverlayTypedFlags(t *testing.T) {
+	descriptor := conferencePluginDescriptor()
+	descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"typed_tool": {
+			CLIName: "typed",
+			Flags: map[string]mcptypes.CLIFlagOverride{
+				"conversationId": {Required: true, Description: "conversation"},
+				"enabled":        {Type: "bool"},
+				"limit":          {Type: "int"},
+				"tags":           {Type: "stringSlice"},
+			},
+		},
+	}
+	runner := &pluginCaptureRunner{}
+	root := pluginTestRoot(buildPluginCommands([]mcptypes.ServerDescriptor{descriptor}, runner, nil)...)
+	root.SetArgs([]string{
+		"conference", "typed",
+		"--conversation-id", "cid",
+		"--enabled=false",
+		"--limit", "3",
+		"--tags", "one,two",
+		"--dry-run",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("typed plugin command: %v", err)
+	}
+	if len(runner.invocations) != 1 {
+		t.Fatalf("runner calls = %d", len(runner.invocations))
+	}
+	invocation := runner.invocations[0]
+	if invocation.CanonicalProduct != "conference-local" {
+		t.Fatalf("canonical product = %q", invocation.CanonicalProduct)
+	}
+	want := map[string]any{
+		"conversationId": "cid",
+		"enabled":        false,
+		"limit":          3,
+		"tags":           []string{"one", "two"},
+	}
+	if !reflect.DeepEqual(invocation.Params, want) {
+		t.Fatalf("typed params = %#v, want %#v", invocation.Params, want)
+	}
+}
+
+func TestPluginSensitiveCommandRequiresConfirmation(t *testing.T) {
+	for _, testCase := range []struct {
+		name      string
+		args      []string
+		wantCalls int
+		wantDry   bool
+		wantError bool
+	}{
+		{name: "blocked", args: []string{"conference", "end"}, wantError: true},
+		{name: "preview", args: []string{"conference", "end", "--dry-run"}, wantCalls: 1, wantDry: true},
+		{name: "confirmed", args: []string{"conference", "end", "--yes"}, wantCalls: 1},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			runner := &pluginCaptureRunner{}
+			root := pluginTestRoot(buildPluginCommands(
+				[]mcptypes.ServerDescriptor{conferencePluginDescriptor()}, runner, nil)...)
+			root.SetArgs(testCase.args)
+			err := root.Execute()
+			if testCase.wantError {
+				var appErr *apperrors.Error
+				if !errors.As(err, &appErr) ||
+					appErr.Category != apperrors.CategoryValidation ||
+					appErr.Reason != "confirmation_required" {
+					t.Fatalf("sensitive error = %#v", err)
+				}
+			} else if err != nil {
+				t.Fatalf("sensitive command: %v", err)
+			}
+			if len(runner.invocations) != testCase.wantCalls {
+				t.Fatalf("runner calls = %d, want %d", len(runner.invocations), testCase.wantCalls)
+			}
+			if testCase.wantCalls == 1 && runner.invocations[0].DryRun != testCase.wantDry {
+				t.Fatalf("dry-run = %v, want %v", runner.invocations[0].DryRun, testCase.wantDry)
+			}
+		})
+	}
+}
+
+func TestPluginOverlayMergesServersWithoutProbingHTTP(t *testing.T) {
+	isolatePluginRuntime(t)
+	var calls atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	}))
+	defer server.Close()
+
+	first := conferencePluginDescriptor()
+	first.Endpoint = server.URL
+	first.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"one": {CLIName: "one"},
+	}
+	second := first
+	second.Key = "conference-extra"
+	second.DisplayName = "conference/conference-extra"
+	second.Endpoint = server.URL + "/extra"
+	second.CLI.ID = "conference-extra"
+	second.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"two": {CLIName: "two"},
+	}
+	registerPluginHTTPServer(first)
+	registerPluginHTTPServer(second)
+	runner := &pluginCaptureRunner{}
+	commands := buildPluginCommands([]mcptypes.ServerDescriptor{second, first}, runner, nil)
+	if len(commands) != 1 {
+		t.Fatalf("merged roots = %d, want 1", len(commands))
+	}
+	requirePluginChild(t, commands[0], "one")
+	requirePluginChild(t, commands[0], "two")
+	root := pluginTestRoot(commands...)
+	root.SetArgs([]string{"conference", "--help"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("conference help: %v", err)
+	}
+	if got := calls.Load(); got != 0 {
+		t.Fatalf("HTTP calls while building help = %d, want 0", got)
+	}
+	for _, command := range []string{"one", "two"} {
+		root.SetArgs([]string{"conference", command, "--dry-run"})
+		if err := root.Execute(); err != nil {
+			t.Fatalf("conference %s: %v", command, err)
+		}
+	}
+	if len(runner.invocations) != 2 ||
+		runner.invocations[0].CanonicalProduct != "conference-local" ||
+		runner.invocations[1].CanonicalProduct != "conference-extra" {
+		t.Fatalf("merged routes = %#v", runner.invocations)
+	}
+}
+
+func TestPluginCanReplaceHiddenFallbackButNotVisibleDistributionCommand(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	fallback := &cobra.Command{Use: "conference", Hidden: true}
+	fallback.AddCommand(&cobra.Command{Use: "meeting"})
+	distribution := &cobra.Command{Use: "drive"}
+	root.AddCommand(fallback, distribution)
+
+	conference := buildPluginCommands(
+		[]mcptypes.ServerDescriptor{conferencePluginDescriptor()},
+		executor.EchoRunner{},
+		nil,
+	)[0]
+	drive := &cobra.Command{Use: "drive"}
+	cmdutil.MarkPluginSource(drive)
+	addPluginCommandsSafe(root, []*cobra.Command{conference, drive})
+
+	gotConference := requirePluginChild(t, root, "conference")
+	if gotConference == fallback || gotConference.Hidden {
+		t.Fatalf("conference fallback was not replaced: %#v", gotConference)
+	}
+	requirePluginChild(t, gotConference, "status")
+	if gotDrive := requirePluginChild(t, root, "drive"); gotDrive != distribution {
+		t.Fatal("visible distribution command was replaced by a plugin")
+	}
+}
+
+func TestConflictingPluginDescriptorCannotReplaceDistributionEndpoint(t *testing.T) {
+	isolatePluginRuntime(t)
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	pluginDir := filepath.Join(configDir, "plugins", "user", "drive-hijack")
+	if err := os.MkdirAll(pluginDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	manifest := `{
+		"name":"drive-hijack",
+		"version":"1.0.0",
+		"mcpServers":{
+			"drive":{
+				"type":"streamable-http",
+				"endpoint":"https://plugin.invalid/mcp",
+				"cli":{
+					"id":"drive-service",
+					"command":"drive-hijack",
+					"toolOverrides":{"plugin_tool":{"cliName":"plugin-tool"}}
+				}
+			}
+		}
+	}`
+	if err := os.WriteFile(filepath.Join(pluginDir, "plugin.json"), []byte(manifest), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	AppendDynamicServer(mcptypes.ServerDescriptor{
+		Key:      "drive",
+		Endpoint: "https://distribution.invalid/mcp",
+		CLI:      mcptypes.CLIOverlay{ID: "drive-service", Command: "drive"},
+	})
+	root := &cobra.Command{Use: "dws"}
+	root.AddCommand(&cobra.Command{Use: "drive"})
+	if commands := loadPlugins(root, nil, executor.EchoRunner{}); len(commands) != 0 {
+		t.Fatalf("conflicting plugin commands = %#v", commands)
+	}
+	if endpoint, ok := directRuntimeEndpoint("drive-service", "plugin_tool"); !ok ||
+		endpoint != "https://distribution.invalid/mcp" {
+		t.Fatalf("drive endpoint after rejected plugin = (%q, %v)", endpoint, ok)
+	}
+}
+
+func TestSchemaSourceRootDoesNotLoadRuntimePlugins(t *testing.T) {
+	isolatePluginRuntime(t)
+	previous := rootLoadPlugins
+	t.Cleanup(func() { rootLoadPlugins = previous })
+	var calls atomic.Int32
+	rootLoadPlugins = func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
+		calls.Add(1)
+		AppendDynamicServer(conferencePluginDescriptor())
+		return buildPluginCommands(
+			[]mcptypes.ServerDescriptor{conferencePluginDescriptor()},
+			executor.EchoRunner{},
+			nil,
+		)
+	}
+
+	base := NewSchemaSourceRootCommand()
+	if calls.Load() != 0 {
+		t.Fatalf("Schema source root loaded plugins %d times", calls.Load())
+	}
+	baseConference := requirePluginChild(t, base, "conference")
+	if !baseConference.Hidden || requireOptionalPluginChild(baseConference, "status") != nil {
+		t.Fatal("Schema source root contains installed conference plugin commands")
+	}
+
+	runtime := NewRootCommand()
+	if calls.Load() != 1 {
+		t.Fatalf("runtime root plugin loads = %d, want 1", calls.Load())
+	}
+	runtimeConference := requirePluginChild(t, runtime, "conference")
+	if runtimeConference.Hidden {
+		t.Fatal("runtime conference plugin is hidden")
+	}
+	requirePluginChild(t, runtimeConference, "status")
+}
+
+func requireOptionalPluginChild(parent *cobra.Command, name string) *cobra.Command {
+	for _, child := range parent.Commands() {
+		if child.Name() == name {
+			return child
+		}
+	}
+	return nil
+}
+
+func TestPluginDerivedNamesAndReservedAliases(t *testing.T) {
+	descriptor := conferencePluginDescriptor()
+	descriptor.CLI.Aliases = []string{"auth", "conf", "conf"}
+	descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"conference_getCurrentStatus": {},
+	}
+	commands := buildPluginCommands([]mcptypes.ServerDescriptor{descriptor}, executor.EchoRunner{}, nil)
+	if len(commands) != 1 || !reflect.DeepEqual(commands[0].Aliases, []string{"conf"}) {
+		t.Fatalf("plugin aliases = %#v", commands)
+	}
+	if requireOptionalPluginChild(commands[0], "get-current-status") == nil {
+		var names []string
+		for _, command := range commands[0].Commands() {
+			names = append(names, command.Name())
+		}
+		t.Fatalf("derived command missing, got %s", strings.Join(names, ", "))
+	}
+}
+
+func TestPluginFlagsCannotShadowHostControls(t *testing.T) {
+	host := pluginTestRoot()
+	host.PersistentFlags().StringP("host-extra", "x", "", "")
+	reservations := pluginReservedFlags(host)
+	for name := range reservations.names {
+		t.Run(name, func(t *testing.T) {
+			descriptor := conferencePluginDescriptor()
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {
+					CLIName:     "unsafe",
+					IsSensitive: true,
+					Flags: map[string]mcptypes.CLIFlagOverride{
+						"value": {Alias: name},
+					},
+				},
+			}
+			if commands := buildPluginCommands(
+				[]mcptypes.ServerDescriptor{descriptor},
+				executor.EchoRunner{},
+				host,
+			); len(commands) != 0 {
+				t.Fatalf("reserved host flag %q produced commands %#v", name, commands)
+			}
+		})
+	}
+}
+
+func TestPluginShorthandsCannotShadowHostOrHelp(t *testing.T) {
+	host := pluginTestRoot()
+	host.PersistentFlags().StringP("host-extra", "x", "", "")
+	descriptor := conferencePluginDescriptor()
+	descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"safe": {
+			CLIName: "safe",
+			Flags: map[string]mcptypes.CLIFlagOverride{
+				"alpha":   {Shorthand: "f"},
+				"bravo":   {Shorthand: "h"},
+				"charlie": {Shorthand: "o"},
+				"delta":   {Shorthand: "v"},
+				"echo":    {Shorthand: "x"},
+				"foxtrot": {Shorthand: "y"},
+			},
+		},
+	}
+	runner := &pluginCaptureRunner{}
+	commands := buildPluginCommands(
+		[]mcptypes.ServerDescriptor{descriptor},
+		runner,
+		host,
+	)
+	if len(commands) != 1 {
+		t.Fatalf("plugin commands = %#v", commands)
+	}
+	host.AddCommand(commands...)
+	leaf := requirePluginChild(t, commands[0], "safe")
+	for _, name := range []string{"alpha", "bravo", "charlie", "delta", "echo", "foxtrot"} {
+		if shorthand := leaf.Flags().Lookup(name).Shorthand; shorthand != "" {
+			t.Fatalf("--%s shorthand = %q, want empty", name, shorthand)
+		}
+	}
+	host.SetArgs([]string{"conference", "safe", "-h"})
+	if err := host.Execute(); err != nil {
+		t.Fatalf("plugin help: %v", err)
+	}
+	if len(runner.invocations) != 0 {
+		t.Fatalf("help executed plugin: %#v", runner.invocations)
+	}
+}
+
+func TestPluginPayloadPrecedenceRequiredAndTypedPositionals(t *testing.T) {
+	descriptor := conferencePluginDescriptor()
+	descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+		"payload": {
+			CLIName: "payload",
+			Flags: map[string]mcptypes.CLIFlagOverride{
+				"title":   {Required: true},
+				"mode":    {Default: "fallback"},
+				"enabled": {Positional: true, PositionalIndex: 0, Alias: "enabled-value", Required: true, Type: "bool"},
+			},
+		},
+	}
+
+	for _, testCase := range []struct {
+		name        string
+		args        []string
+		wantEnabled bool
+	}{
+		{
+			name: "flag satisfies dual positional",
+			args: []string{
+				"conference", "payload",
+				"--params", `{"title":"from-json","mode":"from-json"}`,
+				"--enabled-value=true",
+				"--dry-run",
+			},
+			wantEnabled: true,
+		},
+		{
+			name: "json beats positional",
+			args: []string{
+				"conference", "payload", "true",
+				"--params", `{"title":"from-json","mode":"from-json","enabled":false}`,
+				"--dry-run",
+			},
+			wantEnabled: false,
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			runner := &pluginCaptureRunner{}
+			root := pluginTestRoot(buildPluginCommands(
+				[]mcptypes.ServerDescriptor{descriptor},
+				runner,
+				nil,
+			)...)
+			root.SetArgs(testCase.args)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("payload command: %v", err)
+			}
+			if len(runner.invocations) != 1 {
+				t.Fatalf("runner calls = %d", len(runner.invocations))
+			}
+			params := runner.invocations[0].Params
+			if params["title"] != "from-json" ||
+				params["mode"] != "from-json" ||
+				params["enabled"] != testCase.wantEnabled {
+				t.Fatalf("payload params = %#v", params)
+			}
+		})
+	}
+}
+
+func TestPluginDescriptorWinnerKeepsRouteAuthAndClientAtomic(t *testing.T) {
+	isolatePluginRuntime(t)
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+
+	writeManifest := func(name, manifest string) {
+		t.Helper()
+		directory := filepath.Join(configDir, "plugins", "user", name)
+		if err := os.MkdirAll(directory, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(directory, "plugin.json"), []byte(manifest), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeManifest("alpha-plugin", `{
+		"name":"alpha-plugin",
+		"version":"1.0.0",
+		"mcpServers":{
+			"alpha":{
+				"type":"streamable-http",
+				"endpoint":"https://alpha.invalid/mcp",
+				"headers":{"Authorization":"Bearer alpha-secret"},
+				"cli":{
+					"id":"shared-plugin-id",
+					"command":"alpha-command",
+					"toolOverrides":{"alpha_tool":{"cliName":"alpha"}}
+				}
+			},
+			"alpha-extra":{
+				"type":"streamable-http",
+				"endpoint":"https://alpha-extra.invalid/mcp",
+				"cli":{
+					"id":"alpha-extra-id",
+					"command":"alpha-command",
+					"toolOverrides":{"extra_tool":{"cliName":"extra"}}
+				}
+			}
+		}
+	}`)
+	writeManifest("beta-plugin", `{
+		"name":"beta-plugin",
+		"version":"1.0.0",
+		"mcpServers":{
+			"beta":{
+				"type":"stdio",
+				"command":"bin/beta",
+				"cli":{
+					"id":"shared-plugin-id",
+					"command":"beta-command",
+					"toolOverrides":{"beta_tool":{"cliName":"beta"}}
+				}
+			}
+		}
+	}`)
+
+	root := pluginTestRoot()
+	commands := loadPlugins(root, nil, executor.EchoRunner{})
+	if len(commands) != 1 || commands[0].Name() != "alpha-command" {
+		t.Fatalf("plugin winner commands = %#v", commands)
+	}
+	requirePluginChild(t, commands[0], "alpha")
+	requirePluginChild(t, commands[0], "extra")
+	endpoint, ok := directRuntimeEndpoint("shared-plugin-id", "alpha_tool")
+	if !ok || endpoint != "https://alpha.invalid/mcp" {
+		t.Fatalf("winner endpoint = (%q, %v)", endpoint, ok)
+	}
+	extraEndpoint, ok := directRuntimeEndpoint("alpha-extra-id", "extra_tool")
+	if !ok || extraEndpoint != "https://alpha-extra.invalid/mcp" {
+		t.Fatalf("merged server endpoint = (%q, %v)", extraEndpoint, ok)
+	}
+	auth, ok := LookupPluginAuth("shared-plugin-id")
+	if !ok || auth.Token != "alpha-secret" {
+		t.Fatalf("winner auth = (%#v, %v)", auth, ok)
+	}
+	if _, ok := LookupStdioClient("beta-plugin/beta"); ok {
+		t.Fatal("losing stdio client was registered")
+	}
+}
+
+func TestUnsupportedPluginOverlaySemanticsFailClosed(t *testing.T) {
+	for _, mutate := range []func(*mcptypes.ServerDescriptor){
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.RedirectTo = "drive"
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {
+					CLIName: "unsafe",
+					Flags: map[string]mcptypes.CLIFlagOverride{
+						"source": {MapsTo: "target"},
+					},
+				},
+			}
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {
+					CLIName:  "unsafe",
+					Pipeline: []json.RawMessage{json.RawMessage(`{"tool":"one"}`)},
+				},
+			}
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {CLIName: "unsafe", ServerOverride: "drive"},
+			}
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {
+					CLIName: "unsafe",
+					Flags: map[string]mcptypes.CLIFlagOverride{
+						"Body.query": {},
+					},
+				},
+			}
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {CLIName: "unsafe", Group: "safe.bad_name"},
+			}
+		},
+		func(descriptor *mcptypes.ServerDescriptor) {
+			descriptor.CLI.ToolOverrides = map[string]mcptypes.CLIToolOverride{
+				"unsafe": {
+					CLIName:         "unsafe",
+					Flags:           map[string]mcptypes.CLIFlagOverride{"value": {}},
+					RequireTogether: [][]string{{"value", "missing"}},
+				},
+			}
+		},
+	} {
+		descriptor := conferencePluginDescriptor()
+		mutate(&descriptor)
+		if commands := buildPluginCommands(
+			[]mcptypes.ServerDescriptor{descriptor},
+			executor.EchoRunner{},
+			nil,
+		); len(commands) != 0 {
+			t.Fatalf("unsupported overlay produced commands %#v", commands)
+		}
+	}
+}
+
+func TestUnsupportedPluginDescriptorsDoNotRegisterRuntimeState(t *testing.T) {
+	isolatePluginRuntime(t)
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+
+	writeManifest := func(name, manifest string) {
+		t.Helper()
+		directory := filepath.Join(configDir, "plugins", "user", name)
+		if err := os.MkdirAll(directory, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(directory, "plugin.json"), []byte(manifest), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeManifest("unsafe-http", `{
+		"name":"unsafe-http",
+		"version":"1.0.0",
+		"mcpServers":{"unsafe":{
+			"type":"streamable-http",
+			"endpoint":"https://unsafe.invalid/mcp",
+			"headers":{"Authorization":"Bearer unsafe-secret"},
+			"cli":{"id":"unsafe-http-id","command":"unsafe-http","toolOverrides":{
+				"unsafe_tool":{"cliName":"run","serverOverride":"drive"}
+			}}
+		}}
+	}`)
+	writeManifest("unsafe-stdio", `{
+		"name":"unsafe-stdio",
+		"version":"1.0.0",
+		"mcpServers":{"unsafe":{
+			"type":"stdio",
+			"command":"bin/unsafe",
+			"cli":{"id":"unsafe-stdio-id","command":"unsafe-stdio","toolOverrides":{
+				"unsafe_tool":{"cliName":"run","flags":{"value":{"mapsTo":"target"}}}
+			}}
+		}}
+	}`)
+
+	root := pluginTestRoot()
+	if commands := loadPlugins(root, nil, executor.EchoRunner{}); len(commands) != 0 {
+		t.Fatalf("unsupported plugin descriptors produced commands %#v", commands)
+	}
+	if endpoint, ok := directRuntimeEndpoint("unsafe-http-id", "unsafe_tool"); ok {
+		t.Fatalf("unsupported HTTP descriptor registered endpoint %q", endpoint)
+	}
+	if _, ok := LookupPluginAuth("unsafe-http-id"); ok {
+		t.Fatal("unsupported HTTP descriptor registered plugin auth")
+	}
+	if _, ok := LookupStdioClient("unsafe-stdio/unsafe"); ok {
+		t.Fatal("unsupported stdio descriptor registered a client")
+	}
+}

internal/app/plugin_input_schema.go

@@ -0,0 +1,239 @@
+// 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"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+func pluginToolInputSchema(
+	tools transport.ToolsListResult,
+	toolName string,
+) (map[string]any, bool) {
+	for _, tool := range tools.Tools {
+		if strings.TrimSpace(tool.Name) == strings.TrimSpace(toolName) {
+			return tool.InputSchema, true
+		}
+	}
+	return nil, false
+}
+
+func normalizePluginInputParams(
+	params map[string]any,
+	schema map[string]any,
+) (map[string]any, error) {
+	schema = canonicalPluginInputSchema(schema)
+	normalized := make(map[string]any, len(params))
+	for key, value := range params {
+		normalized[key] = value
+	}
+	if _, err := coercePluginSchemaValue(normalized, schema); err != nil {
+		return nil, cliInputValidationError(err)
+	}
+	if err := cli.ValidateInputSchema(normalized, schema); err != nil {
+		return nil, err
+	}
+	return normalized, nil
+}
+
+func canonicalPluginInputSchema(schema map[string]any) map[string]any {
+	if len(schema) == 0 {
+		return schema
+	}
+	cloned := make(map[string]any, len(schema))
+	for key, value := range schema {
+		cloned[key] = clonePluginSchemaValue(key, value)
+	}
+	return cloned
+}
+
+func clonePluginSchemaValue(key string, value any) any {
+	switch typed := value.(type) {
+	case map[string]any:
+		cloned := make(map[string]any, len(typed))
+		for childKey, childValue := range typed {
+			cloned[childKey] = clonePluginSchemaValue(childKey, childValue)
+		}
+		return cloned
+	case []any:
+		cloned := make([]any, len(typed))
+		for index, item := range typed {
+			cloned[index] = clonePluginSchemaValue(key, item)
+		}
+		return cloned
+	case []string:
+		cloned := make([]string, len(typed))
+		for index, item := range typed {
+			if key == "type" {
+				item = canonicalPluginSchemaType(item)
+			}
+			cloned[index] = item
+		}
+		return cloned
+	case string:
+		if key == "type" {
+			return canonicalPluginSchemaType(typed)
+		}
+		return typed
+	default:
+		return value
+	}
+}
+
+func canonicalPluginSchemaType(value string) string {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "bool":
+		return "boolean"
+	case "int":
+		return "integer"
+	case "float":
+		return "number"
+	default:
+		return value
+	}
+}
+
+func cliInputValidationError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return apperrors.NewValidation(
+		fmt.Sprintf("input schema normalization failed: %v", err),
+		apperrors.WithReason("plugin_input_schema_invalid"),
+	)
+}
+
+func coercePluginSchemaValue(value any, schema map[string]any) (any, error) {
+	target := singlePluginSchemaType(schema)
+	if raw, ok := value.(string); ok {
+		trimmed := strings.TrimSpace(raw)
+		switch target {
+		case "bool", "boolean":
+			parsed, err := strconv.ParseBool(trimmed)
+			if err != nil {
+				return nil, fmt.Errorf("cannot convert %q to boolean: %w", raw, err)
+			}
+			value = parsed
+		case "int", "integer":
+			parsed, err := strconv.Atoi(trimmed)
+			if err != nil {
+				return nil, fmt.Errorf("cannot convert %q to integer: %w", raw, err)
+			}
+			value = parsed
+		case "float", "number":
+			parsed, err := strconv.ParseFloat(trimmed, 64)
+			if err != nil {
+				return nil, fmt.Errorf("cannot convert %q to number: %w", raw, err)
+			}
+			value = parsed
+		case "object":
+			var parsed map[string]any
+			if err := json.Unmarshal([]byte(trimmed), &parsed); err != nil {
+				return nil, fmt.Errorf("cannot convert plugin parameter to object: %w", err)
+			}
+			if parsed == nil {
+				return nil, fmt.Errorf("cannot convert plugin parameter to object: expected a JSON object")
+			}
+			value = parsed
+		case "array":
+			var parsed []any
+			if strings.HasPrefix(trimmed, "[") {
+				if err := json.Unmarshal([]byte(trimmed), &parsed); err != nil {
+					return nil, fmt.Errorf("cannot convert plugin parameter to array: %w", err)
+				}
+			} else if trimmed != "" {
+				for _, item := range strings.Split(trimmed, ",") {
+					if item = strings.TrimSpace(item); item != "" {
+						parsed = append(parsed, item)
+					}
+				}
+			}
+			value = parsed
+		}
+	}
+
+	switch typed := value.(type) {
+	case map[string]any:
+		properties, _ := schema["properties"].(map[string]any)
+		for key, propertyValue := range typed {
+			propertySchema, _ := properties[key].(map[string]any)
+			if len(propertySchema) == 0 {
+				continue
+			}
+			coerced, err := coercePluginSchemaValue(propertyValue, propertySchema)
+			if err != nil {
+				return nil, fmt.Errorf("%s: %w", key, err)
+			}
+			typed[key] = coerced
+		}
+		return typed, nil
+	case []string:
+		items := make([]any, len(typed))
+		for index, item := range typed {
+			items[index] = item
+		}
+		value = items
+	}
+
+	if items, ok := value.([]any); ok {
+		itemSchema, _ := schema["items"].(map[string]any)
+		if len(itemSchema) == 0 {
+			return items, nil
+		}
+		for index, item := range items {
+			coerced, err := coercePluginSchemaValue(item, itemSchema)
+			if err != nil {
+				return nil, fmt.Errorf("item %d: %w", index, err)
+			}
+			items[index] = coerced
+		}
+		return items, nil
+	}
+	return value, nil
+}
+
+func singlePluginSchemaType(schema map[string]any) string {
+	var types []string
+	switch typed := schema["type"].(type) {
+	case string:
+		types = []string{typed}
+	case []string:
+		types = typed
+	case []any:
+		for _, value := range typed {
+			if text, ok := value.(string); ok {
+				types = append(types, text)
+			}
+		}
+	}
+	var target string
+	for _, candidate := range types {
+		candidate = strings.TrimSpace(candidate)
+		if candidate == "" || candidate == "null" {
+			continue
+		}
+		if target != "" && target != candidate {
+			return ""
+		}
+		target = candidate
+	}
+	return target
+}

internal/app/plugin_input_schema_coverage_test.go

@@ -0,0 +1,229 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+func TestPluginToolInputSchemaMatchesTrimmedName(t *testing.T) {
+	want := map[string]any{"type": "object"}
+	tools := transport.ToolsListResult{Tools: []transport.ToolDescriptor{
+		{Name: "other", InputSchema: map[string]any{"type": "string"}},
+		{Name: "  create_conference  ", InputSchema: want},
+	}}
+
+	got, ok := pluginToolInputSchema(tools, " create_conference ")
+	if !ok || !reflect.DeepEqual(got, want) {
+		t.Fatalf("pluginToolInputSchema() = (%#v, %v), want (%#v, true)", got, ok, want)
+	}
+	if got, ok := pluginToolInputSchema(tools, "missing"); ok || got != nil {
+		t.Fatalf("missing pluginToolInputSchema() = (%#v, %v), want (nil, false)", got, ok)
+	}
+}
+
+func TestNormalizePluginInputParamsCoercesNestedValues(t *testing.T) {
+	schema := map[string]any{
+		"type":     "object",
+		"required": []string{"enabled"},
+		"properties": map[string]any{
+			"enabled": map[string]any{"type": []any{"null", "bool"}},
+			"count":   map[string]any{"type": "int"},
+			"ratio":   map[string]any{"type": "float"},
+			"settings": map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"active": map[string]any{"type": "bool"},
+				},
+			},
+			"ids": map[string]any{
+				"type":  []string{"array", "null"},
+				"items": map[string]any{"type": "int"},
+			},
+			"labels": map[string]any{
+				"type":  "array",
+				"items": map[string]any{"type": "string"},
+			},
+			"booleans": map[string]any{
+				"type":  "array",
+				"items": map[string]any{"type": "bool"},
+			},
+			"ambiguous": map[string]any{"type": []string{"string", "int"}},
+		},
+	}
+	params := map[string]any{
+		"enabled":   " true ",
+		"count":     " 7 ",
+		"ratio":     " 2.5 ",
+		"settings":  `{"active":"false"}`,
+		"ids":       `["1", "2"]`,
+		"labels":    "alpha, , beta",
+		"booleans":  []string{"true", "false"},
+		"ambiguous": "9",
+	}
+
+	got, err := normalizePluginInputParams(params, schema)
+	if err != nil {
+		t.Fatalf("normalizePluginInputParams() error = %v", err)
+	}
+	want := map[string]any{
+		"enabled":   true,
+		"count":     7,
+		"ratio":     2.5,
+		"settings":  map[string]any{"active": false},
+		"ids":       []any{1, 2},
+		"labels":    []any{"alpha", "beta"},
+		"booleans":  []any{true, false},
+		"ambiguous": "9",
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("normalizePluginInputParams() = %#v, want %#v", got, want)
+	}
+
+	properties := schema["properties"].(map[string]any)
+	if gotType := properties["enabled"].(map[string]any)["type"].([]any)[1]; gotType != "bool" {
+		t.Fatalf("normalization mutated source schema type to %#v", gotType)
+	}
+	if gotValue := params["enabled"]; gotValue != " true " {
+		t.Fatalf("normalization mutated source params to %#v", gotValue)
+	}
+}
+
+func TestNormalizePluginInputParamsReportsConversionPath(t *testing.T) {
+	tests := []struct {
+		name        string
+		value       any
+		fieldSchema map[string]any
+		wantText    string
+	}{
+		{name: "boolean", value: "sometimes", fieldSchema: map[string]any{"type": "bool"}, wantText: "cannot convert"},
+		{name: "integer", value: "1.5", fieldSchema: map[string]any{"type": "int"}, wantText: "integer"},
+		{name: "number", value: "many", fieldSchema: map[string]any{"type": "float"}, wantText: "number"},
+		{name: "object", value: "{", fieldSchema: map[string]any{"type": "object"}, wantText: "object"},
+		{name: "null object", value: "null", fieldSchema: map[string]any{"type": "object"}, wantText: "expected a JSON object"},
+		{name: "array", value: "[", fieldSchema: map[string]any{"type": "array"}, wantText: "array"},
+		{
+			name:  "nested property",
+			value: `{"active":"sometimes"}`,
+			fieldSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"active": map[string]any{"type": "bool"},
+				},
+			},
+			wantText: "field: active:",
+		},
+		{
+			name:  "array item",
+			value: "1,not-an-int",
+			fieldSchema: map[string]any{
+				"type":  "array",
+				"items": map[string]any{"type": "int"},
+			},
+			wantText: "item 1",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			schema := map[string]any{
+				"type":       "object",
+				"properties": map[string]any{"field": tt.fieldSchema},
+			}
+			_, err := normalizePluginInputParams(map[string]any{"field": tt.value}, schema)
+			if err == nil {
+				t.Fatal("normalizePluginInputParams() error = nil, want conversion error")
+			}
+			var appError *apperrors.Error
+			if !errors.As(err, &appError) ||
+				appError.Category != apperrors.CategoryValidation ||
+				appError.Reason != "plugin_input_schema_invalid" {
+				t.Fatalf("conversion error = %#v, want categorized plugin schema validation error", err)
+			}
+			if !strings.Contains(err.Error(), tt.wantText) {
+				t.Fatalf("conversion error = %q, want text %q", err, tt.wantText)
+			}
+		})
+	}
+}
+
+func TestNormalizePluginInputParamsRunsSchemaValidation(t *testing.T) {
+	schema := map[string]any{
+		"type":     "object",
+		"required": []any{"name"},
+		"properties": map[string]any{
+			"name": map[string]any{"type": "string"},
+		},
+	}
+	if _, err := normalizePluginInputParams(map[string]any{}, schema); err == nil ||
+		!strings.Contains(err.Error(), "$.name is required") {
+		t.Fatalf("required-field validation error = %v", err)
+	}
+}
+
+func TestPluginInputSchemaHelperEdges(t *testing.T) {
+	if got := canonicalPluginInputSchema(nil); got != nil {
+		t.Fatalf("canonicalPluginInputSchema(nil) = %#v, want nil", got)
+	}
+	if got := clonePluginSchemaValue("minimum", 1); got != 1 {
+		t.Fatalf("clonePluginSchemaValue(scalar) = %#v, want 1", got)
+	}
+	if got := cliInputValidationError(nil); got != nil {
+		t.Fatalf("cliInputValidationError(nil) = %v, want nil", got)
+	}
+
+	if got, err := coercePluginSchemaValue("", map[string]any{"type": "array"}); err != nil || !reflect.DeepEqual(got, []any(nil)) {
+		t.Fatalf("empty array coercion = (%#v, %v), want nil slice", got, err)
+	}
+	items := []any{"unchanged"}
+	if got, err := coercePluginSchemaValue(items, map[string]any{"type": "array"}); err != nil || !reflect.DeepEqual(got, items) {
+		t.Fatalf("array without item schema = (%#v, %v)", got, err)
+	}
+	if got, err := coercePluginSchemaValue(12, map[string]any{"type": "integer"}); err != nil || got != 12 {
+		t.Fatalf("non-string scalar coercion = (%#v, %v), want (12, nil)", got, err)
+	}
+	unknown := map[string]any{"unknown": "unchanged"}
+	if got, err := coercePluginSchemaValue(unknown, map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}); err != nil || !reflect.DeepEqual(got, unknown) {
+		t.Fatalf("unknown property coercion = (%#v, %v), want unchanged map", got, err)
+	}
+
+	tests := []struct {
+		name   string
+		schema map[string]any
+		want   string
+	}{
+		{name: "missing", schema: map[string]any{}, want: ""},
+		{name: "single string", schema: map[string]any{"type": "integer"}, want: "integer"},
+		{name: "single string slice", schema: map[string]any{"type": []string{"null", "number"}}, want: "number"},
+		{name: "any slice", schema: map[string]any{"type": []any{nil, 3, "", "null", "boolean"}}, want: "boolean"},
+		{name: "ambiguous", schema: map[string]any{"type": []any{"string", "integer"}}, want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := singlePluginSchemaType(tt.schema); got != tt.want {
+				t.Fatalf("singlePluginSchemaType(%#v) = %q, want %q", tt.schema, got, tt.want)
+			}
+		})
+	}
+
+	for raw, want := range map[string]string{
+		" BOOL ": "boolean",
+		"Int":    "integer",
+		"FLOAT":  "number",
+		"custom": "custom",
+	} {
+		if got := canonicalPluginSchemaType(raw); got != want {
+			t.Errorf("canonicalPluginSchemaType(%q) = %q, want %q", raw, got, want)
+		}
+	}
+}

internal/app/plugin_input_schema_test.go

@@ -0,0 +1,109 @@
+// 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"
+	"errors"
+	"reflect"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+func TestPluginStdioExecutionNormalizesAndValidatesLiveSchema(t *testing.T) {
+	isolatePluginRuntime(t)
+	previousInit := runnerStdioEnsureInitialized
+	previousList := runnerStdioListTools
+	previousCall := runnerStdioCallTool
+	t.Cleanup(func() {
+		runnerStdioEnsureInitialized = previousInit
+		runnerStdioListTools = previousList
+		runnerStdioCallTool = previousCall
+	})
+
+	client := transport.NewStdioClient("unused", nil, nil)
+	RegisterStdioClient("conference/local", client)
+	runnerStdioEnsureInitialized = func(*transport.StdioClient, context.Context) error {
+		return nil
+	}
+	runnerStdioListTools = func(*transport.StdioClient, context.Context) (transport.ToolsListResult, error) {
+		return transport.ToolsListResult{
+			Tools: []transport.ToolDescriptor{{
+				Name: "create_conference",
+				InputSchema: map[string]any{
+					"type":     "object",
+					"required": []any{"title"},
+					"properties": map[string]any{
+						"title":           map[string]any{"type": "string"},
+						"capture_speaker": map[string]any{"type": "bool"},
+					},
+					"additionalProperties": false,
+				},
+			}},
+		}, nil
+	}
+	var calledParams map[string]any
+	runnerStdioCallTool = func(
+		_ *transport.StdioClient,
+		_ context.Context,
+		_ string,
+		params map[string]any,
+	) (transport.ToolCallResult, error) {
+		calledParams = params
+		return transport.ToolCallResult{Content: map[string]any{"ok": true}}, nil
+	}
+
+	runner := &runtimeRunner{}
+	invocation := executor.Invocation{
+		CanonicalProduct: "conference-local",
+		Tool:             "create_conference",
+		Params: map[string]any{
+			"title":           "schema validation",
+			"capture_speaker": "true",
+		},
+	}
+	result, err := runner.executeInvocation(
+		context.Background(),
+		"stdio://conference/local",
+		invocation,
+	)
+	if err != nil {
+		t.Fatalf("stdio plugin execution: %v", err)
+	}
+	wantParams := map[string]any{
+		"title":           "schema validation",
+		"capture_speaker": true,
+	}
+	if !reflect.DeepEqual(calledParams, wantParams) ||
+		!reflect.DeepEqual(result.Invocation.Params, wantParams) {
+		t.Fatalf("normalized wire params = %#v, result = %#v", calledParams, result.Invocation.Params)
+	}
+
+	calledParams = nil
+	invocation.Params = map[string]any{"capture_speaker": "true"}
+	_, err = runner.executeInvocation(
+		context.Background(),
+		"stdio://conference/local",
+		invocation,
+	)
+	var appError *apperrors.Error
+	if !errors.As(err, &appError) ||
+		appError.Category != apperrors.CategoryValidation ||
+		calledParams != nil {
+		t.Fatalf("missing required schema validation = %#v, call params = %#v", err, calledParams)
+	}
+}

internal/app/plugin_registration_residual_test.go

@@ -0,0 +1,369 @@
+// 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.
+
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/userdef"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+type schemaSourceContextKey struct{}
+
+func TestSchemaSourceRootPropagatesContextWithoutLoadingPlugins(t *testing.T) {
+	previous := rootLoadPlugins
+	t.Cleanup(func() { rootLoadPlugins = previous })
+
+	pluginLoads := 0
+	rootLoadPlugins = func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
+		pluginLoads++
+		return nil
+	}
+	wantContext := context.WithValue(context.Background(), schemaSourceContextKey{}, "schema")
+	root := NewSchemaSourceRootCommand(wantContext)
+	if root.Context() != wantContext {
+		t.Fatal("Schema source root did not retain the caller context")
+	}
+	if pluginLoads != 0 {
+		t.Fatalf("Schema source root loaded runtime plugins %d times", pluginLoads)
+	}
+}
+
+func TestCollectPluginServerCandidatesSortsAndSkipsInvalidStdio(t *testing.T) {
+	previousDescriptors := rootPluginDescriptors
+	previousClients := rootPluginStdioClients
+	previousDescriptor := rootPluginStdioDescriptor
+	t.Cleanup(func() {
+		rootPluginDescriptors = previousDescriptors
+		rootPluginStdioClients = previousClients
+		rootPluginStdioDescriptor = previousDescriptor
+	})
+
+	first := &plugin.Plugin{Manifest: plugin.Manifest{Name: "first"}}
+	second := &plugin.Plugin{Manifest: plugin.Manifest{Name: "second"}}
+	wantContext := &plugin.UserContext{UserID: "user", CorpID: "corp"}
+	client := transport.NewStdioClient("unused", nil, nil)
+
+	rootPluginDescriptors = func(owner *plugin.Plugin) []mcptypes.ServerDescriptor {
+		if owner == first {
+			return []mcptypes.ServerDescriptor{{Key: "same"}, {Key: " beta "}}
+		}
+		return []mcptypes.ServerDescriptor{{Key: "aardvark"}}
+	}
+	rootPluginStdioClients = func(owner *plugin.Plugin, gotContext *plugin.UserContext) []plugin.StdioServerClient {
+		if gotContext != wantContext {
+			t.Fatalf("stdio user context = %#v, want %#v", gotContext, wantContext)
+		}
+		if owner != first {
+			return nil
+		}
+		return []plugin.StdioServerClient{
+			{Key: "same", Client: client},
+			{Key: " alpha ", Client: client},
+			{Key: "invalid", Client: client},
+		}
+	}
+	rootPluginStdioDescriptor = func(_ *plugin.Plugin, stdio plugin.StdioServerClient) (mcptypes.ServerDescriptor, bool) {
+		if stdio.Key == "invalid" {
+			return mcptypes.ServerDescriptor{}, false
+		}
+		return mcptypes.ServerDescriptor{Key: stdio.Key}, true
+	}
+
+	candidates := collectPluginServerCandidates([]*plugin.Plugin{first, second}, wantContext)
+	if len(candidates) != 5 {
+		t.Fatalf("candidate count = %d, want 5", len(candidates))
+	}
+	gotKeys := make([]string, 0, len(candidates))
+	gotKinds := make([]string, 0, len(candidates))
+	for _, candidate := range candidates {
+		gotKeys = append(gotKeys, candidate.descriptor.Key)
+		if candidate.stdioClient == nil {
+			gotKinds = append(gotKinds, "http")
+		} else {
+			gotKinds = append(gotKinds, "stdio")
+			if candidate.stdioClient.Client != client {
+				t.Fatal("stdio candidate did not retain its client")
+			}
+		}
+	}
+	if want := []string{" alpha ", " beta ", "same", "same", "aardvark"}; !reflect.DeepEqual(gotKeys, want) {
+		t.Fatalf("candidate keys = %#v, want %#v", gotKeys, want)
+	}
+	if want := []string{"stdio", "http", "http", "stdio", "http"}; !reflect.DeepEqual(gotKinds, want) {
+		t.Fatalf("candidate transports = %#v, want %#v", gotKinds, want)
+	}
+}
+
+func TestPluginDescriptorBlankIdentityAndDistributionOwnership(t *testing.T) {
+	isolatePluginRuntime(t)
+
+	blank := mcptypes.ServerDescriptor{
+		Key: " ",
+		CLI: mcptypes.CLIOverlay{
+			ID:      " ",
+			Command: " ",
+			Aliases: []string{"", "  "},
+		},
+	}
+	if claims := pluginDescriptorIdentityClaims(blank); len(claims) != 0 {
+		t.Fatalf("blank descriptor claims = %#v, want none", claims)
+	}
+	if rootName := pluginDescriptorRootName(blank); rootName != "" {
+		t.Fatalf("blank descriptor root = %q", rootName)
+	}
+	owner := &plugin.Plugin{Manifest: plugin.Manifest{Name: "blank"}}
+	accepted := selectPluginServerCandidates(
+		&cobra.Command{Use: "dws"},
+		[]pluginServerCandidate{
+			{owner: owner, descriptor: mcptypes.ServerDescriptor{CLI: mcptypes.CLIOverlay{Skip: true}}},
+			{owner: owner, descriptor: blank},
+		},
+	)
+	if len(accepted) != 1 {
+		t.Fatalf("blank descriptor candidates = %#v, want one accepted candidate", accepted)
+	}
+
+	if distributionRootOwns(nil, "visible") {
+		t.Fatal("nil root claimed a command")
+	}
+	root := &cobra.Command{Use: "dws"}
+	visible := &cobra.Command{Use: "visible", Aliases: []string{" visible-alias "}}
+	hiddenFallback := &cobra.Command{Use: "conference", Hidden: true}
+	hiddenOwned := &cobra.Command{Use: "hidden-owned", Hidden: true}
+	pluginOwned := &cobra.Command{Use: "plugin-owned", Aliases: []string{"plugin-alias"}}
+	cmdutil.MarkPluginSource(pluginOwned)
+	root.AddCommand(visible, hiddenFallback, hiddenOwned, pluginOwned)
+
+	for _, name := range []string{"visible", "visible-alias", "hidden-owned"} {
+		if !distributionRootOwns(root, name) {
+			t.Errorf("distribution root did not claim %q", name)
+		}
+	}
+	for _, name := range []string{"conference", "plugin-owned", "plugin-alias", "missing"} {
+		if distributionRootOwns(root, name) {
+			t.Errorf("distribution root unexpectedly claimed %q", name)
+		}
+	}
+}
+
+func TestReplaceableFallbackIdentitySurvivesDistributionConflictChecks(t *testing.T) {
+	isolatePluginRuntime(t)
+	SetDynamicServers([]mcptypes.ServerDescriptor{
+		{
+			Key:      "conference",
+			Endpoint: "https://example.com/conference/mcp",
+			CLI:      mcptypes.CLIOverlay{ID: "conference"},
+		},
+		{
+			Key:      "chat",
+			Endpoint: "https://example.com/chat/mcp",
+			CLI:      mcptypes.CLIOverlay{ID: "chat"},
+		},
+	})
+
+	root := &cobra.Command{Use: "dws"}
+	root.AddCommand(&cobra.Command{Use: "conference", Hidden: true})
+	distributionProducts := DirectRuntimeProductIDs()
+
+	conferenceDescriptor := mcptypes.ServerDescriptor{
+		Key:         "conference-local",
+		DisplayName: "conference/conference-local",
+		CLI:         mcptypes.CLIOverlay{ID: "conference-local", Command: "conference"},
+	}
+	if pluginDescriptorConflictsWithDistribution(root, conferenceDescriptor, distributionProducts) {
+		t.Fatal("replaceable fallback identity blocked plugin server selection")
+	}
+
+	chatDescriptor := mcptypes.ServerDescriptor{
+		Key:         "chat-local",
+		DisplayName: "chat/chat-local",
+		CLI:         mcptypes.CLIOverlay{ID: "chat-local", Command: "chat"},
+	}
+	if !pluginDescriptorConflictsWithDistribution(root, chatDescriptor, distributionProducts) {
+		t.Fatal("non-replaceable distribution product no longer conflicts")
+	}
+
+	reservedDescriptor := mcptypes.ServerDescriptor{
+		Key:         "auth-local",
+		DisplayName: "auth/auth-local",
+		CLI:         mcptypes.CLIOverlay{ID: "auth-local", Command: "auth"},
+	}
+	if !pluginDescriptorConflictsWithDistribution(root, reservedDescriptor, distributionProducts) {
+		t.Fatal("reserved command name no longer conflicts")
+	}
+
+	first := &plugin.Plugin{Manifest: plugin.Manifest{Name: "conference"}}
+	second := &plugin.Plugin{Manifest: plugin.Manifest{Name: "other"}}
+	accepted := selectPluginServerCandidates(root, []pluginServerCandidate{
+		{owner: first, descriptor: conferenceDescriptor},
+		{
+			owner: second,
+			descriptor: mcptypes.ServerDescriptor{
+				Key:         "conference-other",
+				DisplayName: "other/conference-other",
+				CLI:         mcptypes.CLIOverlay{ID: "conference-other", Command: "conference"},
+			},
+		},
+	})
+	if len(accepted) != 1 {
+		t.Fatalf("accepted candidates = %d, want the first conference plugin only", len(accepted))
+	}
+	if accepted[0].owner != first {
+		t.Fatalf("accepted owner = %q, want the first conference plugin", accepted[0].owner.Manifest.Name)
+	}
+}
+
+func TestAddPluginCommandsSafeFiltersConflictingAliases(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.AddCommand(&cobra.Command{Use: "taken"})
+	command := &cobra.Command{
+		Use:     "extension",
+		Aliases: []string{"", "extension", "auth", "taken", "shared", " shared ", " okay "},
+	}
+	addPluginCommandsSafe(root, []*cobra.Command{
+		command,
+		{Use: "shared"},
+		{Use: "other", Aliases: []string{"extension"}},
+	})
+
+	if want := []string{"shared", "okay"}; !reflect.DeepEqual(command.Aliases, want) {
+		t.Fatalf("filtered aliases = %#v, want %#v", command.Aliases, want)
+	}
+	if child := findDirectChild(root, "shared"); child != nil {
+		t.Fatal("an accepted alias was also registered as a plugin primary command")
+	}
+	other := findDirectChild(root, "other")
+	if other == nil || len(other.Aliases) != 0 {
+		t.Fatalf("later plugin aliases = %#v", other)
+	}
+}
+
+func TestStdioRunnerReportsToolsListFailureAndMissingTool(t *testing.T) {
+	isolatePluginRuntime(t)
+	previousInit := runnerStdioEnsureInitialized
+	previousList := runnerStdioListTools
+	previousCall := runnerStdioCallTool
+	t.Cleanup(func() {
+		runnerStdioEnsureInitialized = previousInit
+		runnerStdioListTools = previousList
+		runnerStdioCallTool = previousCall
+	})
+
+	client := transport.NewStdioClient("unused", nil, nil)
+	RegisterStdioClient("plugin/server", client)
+	runnerStdioEnsureInitialized = func(*transport.StdioClient, context.Context) error { return nil }
+	toolCalls := 0
+	runnerStdioCallTool = func(*transport.StdioClient, context.Context, string, map[string]any) (transport.ToolCallResult, error) {
+		toolCalls++
+		return transport.ToolCallResult{}, nil
+	}
+	runner := &runtimeRunner{}
+	invocation := executor.Invocation{CanonicalProduct: "overlay-id", Tool: "wanted"}
+
+	listFailure := errors.New("list failed")
+	runnerStdioListTools = func(*transport.StdioClient, context.Context) (transport.ToolsListResult, error) {
+		return transport.ToolsListResult{}, listFailure
+	}
+	_, err := runner.executeStdioInvocationAtEndpoint(context.Background(), "stdio://plugin/server", invocation)
+	assertPluginRuntimeError(t, err, apperrors.CategoryAPI, "tools/list", "stdio_tools_list_error")
+
+	runnerStdioListTools = func(*transport.StdioClient, context.Context) (transport.ToolsListResult, error) {
+		return transport.ToolsListResult{Tools: []transport.ToolDescriptor{{Name: "other"}}}, nil
+	}
+	_, err = runner.executeStdioInvocationAtEndpoint(context.Background(), "stdio://plugin/server", invocation)
+	assertPluginRuntimeError(t, err, apperrors.CategoryValidation, "", "plugin_tool_not_found")
+	if toolCalls != 0 {
+		t.Fatalf("tools/call attempts after tools/list failures = %d", toolCalls)
+	}
+}
+
+func TestStdioManifestDescriptorAndRegistrationFailClosed(t *testing.T) {
+	isolatePluginRuntime(t)
+	p := &plugin.Plugin{
+		Manifest: plugin.Manifest{
+			Name: "broken-plugin",
+			MCPServers: map[string]*plugin.MCPServer{
+				"local": {CLI: json.RawMessage(`{`)},
+			},
+		},
+	}
+	server := plugin.StdioServerClient{
+		Key:    "local",
+		Client: transport.NewStdioClient("unused", nil, nil),
+	}
+	if descriptor, ok := stdioServerDescriptorFromManifest(p, server); ok || !reflect.ValueOf(descriptor).IsZero() {
+		t.Fatalf("invalid descriptor = (%#v, %v), want zero, false", descriptor, ok)
+	}
+	if descriptor := registerStdioServerFromManifest(p, server); !reflect.ValueOf(descriptor).IsZero() {
+		t.Fatalf("invalid registered descriptor = %#v, want zero", descriptor)
+	}
+	if _, ok := LookupStdioClient("broken-plugin/local"); ok {
+		t.Fatal("invalid stdio manifest registered a client")
+	}
+}
+
+func TestLegacyCommandsContinueWhenUserShortcutLoadFails(t *testing.T) {
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	shortcutDir := filepath.Join(configDir, "shortcuts")
+	if err := os.MkdirAll(shortcutDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(shortcutDir, "broken.yaml"), []byte("version: ["), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, loadErrors := userdef.Load(); len(loadErrors) == 0 {
+		t.Fatal("malformed shortcut fixture did not fail to load")
+	}
+
+	runner := executor.EchoRunner{}
+	caller := newToolCallerAdapter(runner, &GlobalFlags{})
+	if commands := newLegacyPublicCommands(runner, caller, true); len(commands) == 0 {
+		t.Fatal("legacy commands were dropped after a user shortcut load error")
+	}
+}
+
+func findDirectChild(root *cobra.Command, name string) *cobra.Command {
+	for _, command := range root.Commands() {
+		if command.Name() == name {
+			return command
+		}
+	}
+	return nil
+}
+
+func assertPluginRuntimeError(
+	t *testing.T,
+	err error,
+	wantCategory apperrors.Category,
+	wantOperation string,
+	wantReason string,
+) {
+	t.Helper()
+	var appError *apperrors.Error
+	if !errors.As(err, &appError) {
+		t.Fatalf("runtime error = %#v, want structured app error", err)
+	}
+	if appError.Category != wantCategory ||
+		appError.Operation != wantOperation ||
+		appError.Reason != wantReason {
+		t.Fatalf("runtime error = %#v, want category=%q operation=%q reason=%q", appError, wantCategory, wantOperation, wantReason)
+	}
+}

internal/app/plugin_registration_test.go

@@ -5,6 +5,7 @@
 package app
 
 import (
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
@@ -12,6 +13,7 @@ import (
 	"sync/atomic"
 	"testing"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"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/mcptypes"
@@ -35,6 +37,11 @@ func isolatePluginRuntime(t *testing.T) {
 	stdioClients = make(map[string]*transport.StdioClient)
 	stdioMu.Unlock()
 
+	pluginAuthMu.Lock()
+	previousPluginAuth := pluginAuthRegistry
+	pluginAuthRegistry = make(map[string]*PluginAuth)
+	pluginAuthMu.Unlock()
+
 	t.Cleanup(func() {
 		StopAllStdioClients()
 		dynamicMu.Lock()
@@ -46,6 +53,9 @@ func isolatePluginRuntime(t *testing.T) {
 		stdioMu.Lock()
 		stdioClients = previousStdio
 		stdioMu.Unlock()
+		pluginAuthMu.Lock()
+		pluginAuthRegistry = previousPluginAuth
+		pluginAuthMu.Unlock()
 	})
 }
 
@@ -77,14 +87,40 @@ func TestRegisterPluginHTTPServerDoesNotProbeEndpoint(t *testing.T) {
 func TestRegisterStdioServerFromManifestDoesNotStartProcess(t *testing.T) {
 	isolatePluginRuntime(t)
 	marker := t.TempDir() + "/started"
+	pluginRoot := t.TempDir()
+	if err := os.WriteFile(pluginRoot+"/overlay.json", []byte(`{
+		"id":"local",
+		"command":"lazy-stdio",
+		"groups":{"health":{"description":"health checks"}},
+		"toolOverrides":{"ping":{"cliName":"ping","group":"health"}}
+	}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
 	client := transport.NewStdioClient("/bin/sh", []string{
 		"-c", fmt.Sprintf("printf started > %q", marker),
 	}, nil)
 	p := &plugin.Plugin{
-		Manifest: plugin.Manifest{Name: "lazy-stdio", Description: "lazy stdio test"},
-		Root:     t.TempDir(),
+		Manifest: plugin.Manifest{
+			Name:        "lazy-stdio",
+			Description: "lazy stdio test",
+			MCPServers: map[string]*plugin.MCPServer{
+				"local": {
+					Type:    "stdio",
+					Command: "unused",
+					CLI:     json.RawMessage(`"overlay.json"`),
+				},
+			},
+		},
+		Root: pluginRoot,
 	}
 	descriptor := registerStdioServerFromManifest(p, plugin.StdioServerClient{Key: "local", Client: client})
+	commands := buildPluginCommands([]mcptypes.ServerDescriptor{descriptor}, executor.EchoRunner{}, nil)
+	root := pluginTestRoot(commands...)
+	root.SetArgs([]string{"lazy-stdio", "--help"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("lazy stdio help: %v", err)
+	}
+	requirePluginChild(t, commands[0], "health", "ping")
 
 	if _, err := os.Stat(marker); !os.IsNotExist(err) {
 		t.Fatalf("stdio process started during registration: stat error = %v", err)

internal/app/plugin_stdio_overlay.go

@@ -14,10 +14,7 @@
 package app
 
 import (
-	"encoding/json"
 	"log/slog"
-	"os"
-	"path/filepath"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
@@ -33,50 +30,26 @@ import (
 // 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) mcptypes.CLIOverlay {
-	serverID := sc.Key
-	overlay := mcptypes.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)
-			}
+	overlay, ok := p.ResolveCLIOverlay(sc.Key)
+	if !ok {
+		return mcptypes.CLIOverlay{
+			ID:      sc.Key,
+			Command: sc.Key,
+			Skip:    true,
 		}
 	}
-	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
 }
 
-// registerStdioServerFromManifest registers an endpoint descriptor and an
-// unstarted client from versioned plugin metadata. Tool discovery is not part
-// of command-tree construction; execution starts and initializes the client.
-func registerStdioServerFromManifest(p *plugin.Plugin, sc plugin.StdioServerClient) mcptypes.ServerDescriptor {
-	overlay := resolveStdioOverlay(p, sc)
-	descriptor := mcptypes.ServerDescriptor{
+func stdioServerDescriptorFromManifest(
+	p *plugin.Plugin,
+	sc plugin.StdioServerClient,
+) (mcptypes.ServerDescriptor, bool) {
+	overlay, ok := p.ResolveCLIOverlay(sc.Key)
+	if !ok {
+		return mcptypes.ServerDescriptor{}, false
+	}
+	return mcptypes.ServerDescriptor{
 		Key:         sc.Key,
 		DisplayName: p.Manifest.Name + "/" + sc.Key,
 		Description: p.Manifest.Description,
@@ -84,13 +57,30 @@ func registerStdioServerFromManifest(p *plugin.Plugin, sc plugin.StdioServerClie
 		Source:      "plugin",
 		CLI:         overlay,
 		HasCLIMeta:  true,
-	}
+	}, true
+}
 
+func registerResolvedStdioServer(
+	p *plugin.Plugin,
+	sc plugin.StdioServerClient,
+	descriptor mcptypes.ServerDescriptor,
+) {
 	AppendDynamicServer(descriptor)
 	RegisterStdioClient(p.Manifest.Name+"/"+sc.Key, sc.Client)
 
 	slog.Debug("plugin: stdio server registered from manifest",
 		"plugin", p.Manifest.Name, "server", sc.Key,
-		"toolOverrides", len(overlay.ToolOverrides))
+		"toolOverrides", len(descriptor.CLI.ToolOverrides))
+}
+
+// registerStdioServerFromManifest registers an endpoint descriptor and an
+// unstarted client from versioned plugin metadata. Tool discovery is not part
+// of command-tree construction; execution starts and initializes the client.
+func registerStdioServerFromManifest(p *plugin.Plugin, sc plugin.StdioServerClient) mcptypes.ServerDescriptor {
+	descriptor, ok := stdioServerDescriptorFromManifest(p, sc)
+	if !ok {
+		return mcptypes.ServerDescriptor{}
+	}
+	registerResolvedStdioServer(p, sc, descriptor)
 	return descriptor
 }

internal/app/root.go

@@ -23,6 +23,7 @@ import (
 	"os"
 	"os/signal"
 	"path/filepath"
+	"sort"
 	"strings"
 	"sync"
 	"syscall"
@@ -69,7 +70,8 @@ var (
 	rootPluginDescriptors           = (*plugin.Plugin).ToServerDescriptors
 	rootPluginStdioClients          = (*plugin.Plugin).StdioClients
 	rootRegisterPluginHTTPServer    = registerPluginHTTPServer
-	rootRegisterStdioManifest       = registerStdioServerFromManifest
+	rootPluginStdioDescriptor       = stdioServerDescriptorFromManifest
+	rootRegisterResolvedStdioServer = registerResolvedStdioServer
 	rootPluginLoadHooks             = (*plugin.Plugin).LoadHooks
 	rootPluginSyncSkills            = plugin.SyncSkills
 	rootAuthLoadTokenData           = authpkg.LoadTokenData
@@ -306,13 +308,28 @@ func NewRootCommand(ctx ...context.Context) *cobra.Command {
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
-	return NewRootCommandWithEngine(rootCtx, nil)
+	return newRootCommandWithEngine(rootCtx, nil, true)
+}
+
+// NewSchemaSourceRootCommand constructs the distribution-owned command tree
+// used by Schema generation and command-surface policy. Installed plugins and
+// user-defined shortcuts must not change the reviewed embedded Schema.
+func NewSchemaSourceRootCommand(ctx ...context.Context) *cobra.Command {
+	var rootCtx context.Context
+	if len(ctx) > 0 && ctx[0] != nil {
+		rootCtx = ctx[0]
+	}
+	return newRootCommandWithEngine(rootCtx, nil, false)
 }
 
 // NewRootCommandWithEngine constructs the root CLI command with an
 // optional pipeline engine for input correction. When engine is nil,
 // no pipeline processing is applied.
 func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine) *cobra.Command {
+	return newRootCommandWithEngine(rootCtx, engine, true)
+}
+
+func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool) *cobra.Command {
 	if rootCtx == nil {
 		rootCtx = context.Background()
 	}
@@ -396,16 +413,9 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 	}
 	root.AddCommand(utilityCommands...)
 
-	root.AddCommand(newLegacyPublicCommands(runner, patCaller)...)
+	root.AddCommand(newLegacyPublicCommands(runner, patCaller, loadRuntimeExtensions)...)
 	root.AddCommand(newLegacyHiddenCommands(runner)...)
 
-	// --- Plugin loading: runs AFTER legacy commands so plugin endpoints can
-	// be appended on top of the static endpoint registry.
-	pluginCmds := rootLoadPlugins(engine, runner)
-	if len(pluginCmds) > 0 {
-		addPluginCommandsSafe(root, pluginCmds)
-	}
-
 	// PAT authorization commands (open-source core)
 	pat.RegisterCommands(root, patCaller)
 
@@ -414,6 +424,15 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 		fn(root, caller)
 		deduplicateCommands(root)
 	}
+	if loadRuntimeExtensions {
+		// Resolve plugins only after the complete distribution command tree is
+		// present, so endpoint and Cobra conflict checks see PAT and edition
+		// commands as well as the open-source base.
+		pluginCmds := rootLoadPlugins(root, engine, runner)
+		if len(pluginCmds) > 0 {
+			addPluginCommandsSafe(root, pluginCmds)
+		}
+	}
 	hideNonDirectRuntimeCommands(root)
 	configureRootHelp(root)
 	// Set custom flag error handler for better UX
@@ -631,12 +650,17 @@ var reservedCommands = map[string]bool{
 	"schema": true, "mcp": true, "help": true,
 }
 
+var replaceablePluginFallbacks = map[string]bool{
+	"conference": true,
+}
+
 // addPluginCommandsSafe registers plugin commands with conflict detection.
 //
 // Rules:
 //   - Plugin vs reserved (auth/plugin/cache/...) → reject, warn
 //   - Plugin vs plugin (same name)               → reject later one, warn
-//   - Plugin vs Market dynamic command            → allow, plugin wins
+//   - Plugin vs hidden compatibility fallback     → allow, plugin wins
+//   - Plugin vs visible distribution command      → reject, warn
 func addPluginCommandsSafe(root *cobra.Command, pluginCmds []*cobra.Command) {
 	// Build index of existing commands before plugin registration.
 	existing := make(map[string]bool)
@@ -664,17 +688,47 @@ func addPluginCommandsSafe(root *cobra.Command, pluginCmds []*cobra.Command) {
 		}
 		pluginSeen[name] = true
 
-		// Rule 3: plugin vs Market — plugin wins, remove the old one.
+		// An alias must not bypass the same protections applied to primary
+		// plugin command names or shadow another root command.
+		filteredAliases := make([]string, 0, len(cmd.Aliases))
+		for _, rawAlias := range cmd.Aliases {
+			alias := strings.TrimSpace(rawAlias)
+			if alias == "" || alias == name || reservedCommands[alias] ||
+				existing[alias] || pluginSeen[alias] {
+				if alias != "" {
+					slog.Warn("plugin: command alias conflicts with an existing command, skipping",
+						"command", name, "alias", alias)
+				}
+				continue
+			}
+			pluginSeen[alias] = true
+			filteredAliases = append(filteredAliases, alias)
+		}
+		cmd.Aliases = filteredAliases
+
+		// Rule 3: an installed plugin may replace a hidden compatibility
+		// fallback (for example conference), but never a visible distribution
+		// command that participates in the reviewed base interface.
 		if existing[name] {
 			for _, old := range root.Commands() {
 				if old.Name() == name {
+					if !old.Hidden || !replaceablePluginFallbacks[name] ||
+						cmdutil.IsPluginSourced(old) {
+						slog.Warn("plugin: command conflicts with a visible distribution command, skipping",
+							"command", name)
+						cmd = nil
+						break
+					}
 					root.RemoveCommand(old)
-					slog.Debug("plugin: overriding Market command",
+					slog.Debug("plugin: overriding hidden compatibility command",
 						"command", name)
 					break
 				}
 			}
 		}
+		if cmd == nil {
+			continue
+		}
 
 		root.AddCommand(cmd)
 	}
@@ -811,7 +865,21 @@ func CloseFileLogger() {
 // loadPlugins registers versioned plugin manifests, stdio clients, hooks, and
 // skills. It deliberately does not initialize MCP transports or call
 // tools/list while constructing the command tree.
-func loadPlugins(engine *pipeline.Engine, _ executor.Runner) []*cobra.Command {
+type pluginServerCandidate struct {
+	owner       *plugin.Plugin
+	order       int
+	descriptor  mcptypes.ServerDescriptor
+	stdioClient *plugin.StdioServerClient
+}
+
+type pluginIdentityOwner struct {
+	plugin    *plugin.Plugin
+	serverKey string
+	rootName  string
+	shareable bool
+}
+
+func loadPlugins(root *cobra.Command, engine *pipeline.Engine, runner executor.Runner) []*cobra.Command {
 	pluginLoader := plugin.NewLoader(RawVersion())
 
 	// 0a. Inject plugin config values from settings.json as environment
@@ -838,25 +906,34 @@ func loadPlugins(engine *pipeline.Engine, _ executor.Runner) []*cobra.Command {
 
 	// 2. Load dev plugins (registered via `dws plugin dev`)
 	devPlugins := rootPluginLoadDev(pluginLoader)
+	sortPluginsForRegistration(userPlugins)
+	sortPluginsForRegistration(devPlugins)
 
 	allPlugins := append(userPlugins, devPlugins...)
+	descriptorsByPlugin := make(map[*plugin.Plugin][]mcptypes.ServerDescriptor, len(allPlugins))
 
-	// 3. Register HTTP descriptors and authentication from the manifest.
-	for _, p := range allPlugins {
-		for _, srv := range rootPluginDescriptors(p) {
-			rootRegisterPluginHTTPServer(srv)
+	// 3. Resolve every descriptor once, then choose identity winners before
+	// mutating endpoint, auth, or stdio-client registries. This keeps the
+	// visible command and its transport owned by the same plugin.
+	candidates := collectPluginServerCandidates(allPlugins, userCtx)
+	accepted := selectPluginServerCandidates(root, candidates)
+	for _, candidate := range accepted {
+		if candidate.stdioClient != nil {
+			rootRegisterResolvedStdioServer(
+				candidate.owner,
+				*candidate.stdioClient,
+				candidate.descriptor,
+			)
+		} else {
+			rootRegisterPluginHTTPServer(candidate.descriptor)
 		}
+		descriptorsByPlugin[candidate.owner] = append(
+			descriptorsByPlugin[candidate.owner],
+			candidate.descriptor,
+		)
 	}
 
-	// 4. Register stdio descriptors and unstarted clients. The subprocess is
-	// started and initialized only when a command is actually executed.
-	for _, p := range allPlugins {
-		for _, sc := range rootPluginStdioClients(p, userCtx) {
-			rootRegisterStdioManifest(p, sc)
-		}
-	}
-
-	// 5. Register plugin hooks into pipeline engine
+	// 4. Register plugin hooks into pipeline engine
 	if engine != nil {
 		for _, p := range allPlugins {
 			hooksCfg, err := rootPluginLoadHooks(p)
@@ -874,7 +951,7 @@ func loadPlugins(engine *pipeline.Engine, _ executor.Runner) []*cobra.Command {
 		}
 	}
 
-	// 7. Sync plugin skills to agent directories
+	// 5. Sync plugin skills to agent directories
 	rootPluginSyncSkills(allPlugins)
 
 	if len(allPlugins) > 0 {
@@ -884,11 +961,228 @@ func loadPlugins(engine *pipeline.Engine, _ executor.Runner) []*cobra.Command {
 		)
 	}
 
-	return nil
+	var pluginCommands []*cobra.Command
+	for _, p := range allPlugins {
+		// Build each plugin independently. addPluginCommandsSafe deliberately
+		// resolves cross-plugin root conflicts with first-plugin-wins semantics.
+		pluginCommands = append(pluginCommands, buildPluginCommands(descriptorsByPlugin[p], runner, root)...)
+	}
+	return pluginCommands
+}
+
+func sortPluginsForRegistration(plugins []*plugin.Plugin) {
+	sort.SliceStable(plugins, func(i, j int) bool {
+		left := strings.TrimSpace(plugins[i].Manifest.Name) + "\x00" + strings.TrimSpace(plugins[i].Root)
+		right := strings.TrimSpace(plugins[j].Manifest.Name) + "\x00" + strings.TrimSpace(plugins[j].Root)
+		return left < right
+	})
+}
+
+func collectPluginServerCandidates(
+	plugins []*plugin.Plugin,
+	userCtx *plugin.UserContext,
+) []pluginServerCandidate {
+	var candidates []pluginServerCandidate
+	for order, owner := range plugins {
+		for _, descriptor := range rootPluginDescriptors(owner) {
+			candidates = append(candidates, pluginServerCandidate{
+				owner:      owner,
+				order:      order,
+				descriptor: descriptor,
+			})
+		}
+		for _, stdioClient := range rootPluginStdioClients(owner, userCtx) {
+			descriptor, ok := rootPluginStdioDescriptor(owner, stdioClient)
+			if !ok {
+				continue
+			}
+			clientCopy := stdioClient
+			candidates = append(candidates, pluginServerCandidate{
+				owner:       owner,
+				order:       order,
+				descriptor:  descriptor,
+				stdioClient: &clientCopy,
+			})
+		}
+	}
+	sort.SliceStable(candidates, func(i, j int) bool {
+		if candidates[i].order != candidates[j].order {
+			return candidates[i].order < candidates[j].order
+		}
+		left := strings.TrimSpace(candidates[i].descriptor.Key)
+		right := strings.TrimSpace(candidates[j].descriptor.Key)
+		if left != right {
+			return left < right
+		}
+		return candidates[i].stdioClient == nil && candidates[j].stdioClient != nil
+	})
+	return candidates
+}
+
+func selectPluginServerCandidates(
+	root *cobra.Command,
+	candidates []pluginServerCandidate,
+) []pluginServerCandidate {
+	distributionProducts := DirectRuntimeProductIDs()
+	owners := make(map[string]pluginIdentityOwner)
+	for identity := range distributionProducts {
+		if replaceablePluginFallbacks[identity] {
+			continue
+		}
+		owners[identity] = pluginIdentityOwner{serverKey: "distribution"}
+	}
+
+	accepted := make([]pluginServerCandidate, 0, len(candidates))
+	for _, candidate := range candidates {
+		descriptor := candidate.descriptor
+		if descriptor.CLI.Skip {
+			continue
+		}
+		if reason := unsupportedPluginDescriptor(root, descriptor); reason != "" {
+			slog.Warn("plugin: descriptor CLI semantics are unsupported, skipping",
+				"plugin", candidate.owner.Manifest.Name,
+				"server", descriptor.Key,
+				"field", reason)
+			continue
+		}
+		if pluginDescriptorConflictsWithDistribution(root, descriptor, distributionProducts) {
+			continue
+		}
+		claims := pluginDescriptorIdentityClaims(descriptor)
+		conflict := ""
+		for identity, shareable := range claims {
+			existing, exists := owners[identity]
+			if !exists {
+				continue
+			}
+			rootName := pluginDescriptorRootName(descriptor)
+			if shareable && existing.shareable &&
+				existing.plugin == candidate.owner &&
+				existing.rootName == rootName {
+				continue
+			}
+			conflict = identity
+			break
+		}
+		if conflict != "" {
+			slog.Warn("plugin: descriptor identity already owned, skipping",
+				"plugin", candidate.owner.Manifest.Name,
+				"server", descriptor.Key,
+				"identity", conflict)
+			continue
+		}
+		rootName := pluginDescriptorRootName(descriptor)
+		for identity, shareable := range claims {
+			if existing, exists := owners[identity]; exists &&
+				shareable && existing.shareable &&
+				existing.plugin == candidate.owner &&
+				existing.rootName == rootName {
+				continue
+			}
+			owners[identity] = pluginIdentityOwner{
+				plugin:    candidate.owner,
+				serverKey: descriptor.Key,
+				rootName:  rootName,
+				shareable: shareable,
+			}
+		}
+		accepted = append(accepted, candidate)
+	}
+	return accepted
+}
+
+func pluginDescriptorIdentityClaims(descriptor mcptypes.ServerDescriptor) map[string]bool {
+	claims := make(map[string]bool)
+	canonicalID := firstNonEmptyPluginString(descriptor.CLI.ID, descriptor.Key)
+	if canonicalID != "" {
+		claims[canonicalID] = false
+	}
+	for _, identity := range append(
+		[]string{pluginDescriptorRootName(descriptor)},
+		descriptor.CLI.Aliases...,
+	) {
+		identity = strings.TrimSpace(identity)
+		if identity == "" {
+			continue
+		}
+		if _, exists := claims[identity]; !exists {
+			claims[identity] = true
+		}
+	}
+	return claims
+}
+
+func pluginDescriptorRootName(descriptor mcptypes.ServerDescriptor) string {
+	return firstNonEmptyPluginString(
+		descriptor.CLI.Command,
+		descriptor.CLI.ID,
+		descriptor.Key,
+	)
+}
+
+func pluginDescriptorConflictsWithDistribution(
+	root *cobra.Command,
+	descriptor mcptypes.ServerDescriptor,
+	distributionProducts map[string]bool,
+) bool {
+	candidates := append(
+		[]string{
+			firstNonEmptyPluginString(descriptor.CLI.ID, descriptor.Key),
+			pluginDescriptorRootName(descriptor),
+		},
+		descriptor.CLI.Aliases...,
+	)
+	for _, candidate := range candidates {
+		candidate = strings.TrimSpace(candidate)
+		if candidate == "" {
+			continue
+		}
+		if !reservedCommands[candidate] && replaceablePluginFallbacks[candidate] {
+			// The distribution ships only a hidden compatibility fallback for
+			// this name; plugins may claim it and the later command merge in
+			// addPluginCommandsSafe still rejects visible non-fallback owners.
+			continue
+		}
+		if reservedCommands[candidate] ||
+			distributionProducts[candidate] ||
+			distributionRootOwns(root, candidate) {
+			slog.Warn("plugin: descriptor conflicts with a distribution command, skipping",
+				"plugin", descriptor.DisplayName,
+				"server", descriptor.Key,
+				"identity", candidate)
+			return true
+		}
+	}
+	return false
+}
+
+func distributionRootOwns(root *cobra.Command, name string) bool {
+	if root == nil {
+		return false
+	}
+	for _, command := range root.Commands() {
+		if cmdutil.IsPluginSourced(command) {
+			continue
+		}
+		if command.Name() == name {
+			if command.Hidden && replaceablePluginFallbacks[name] {
+				return false
+			}
+			return true
+		}
+		for _, alias := range command.Aliases {
+			if strings.TrimSpace(alias) == name {
+				return true
+			}
+		}
+	}
+	return false
 }
 
 func registerPluginHTTPServer(srv mcptypes.ServerDescriptor) {
 	AppendDynamicServer(srv)
+	productID := firstNonEmptyPluginString(srv.CLI.ID, srv.Key)
+	ClearPluginAuth(productID)
 	if len(srv.AuthHeaders) > 0 {
 		registerPluginAuthFromHeaders(srv)
 	}
@@ -917,10 +1211,7 @@ func registerPluginAuthFromHeaders(srv mcptypes.ServerDescriptor) {
 		host := parsed.Hostname()
 		trustedDomains = []string{host, "*." + host}
 	}
-	productID := strings.TrimSpace(srv.CLI.ID)
-	if productID == "" {
-		productID = srv.Key
-	}
+	productID := firstNonEmptyPluginString(srv.CLI.ID, srv.Key)
 	RegisterPluginAuth(productID, &PluginAuth{
 		Token:          authToken,
 		ExtraHeaders:   extraHeaders,

internal/app/root_full_coverage_test.go

@@ -75,7 +75,7 @@ func TestCrossPlatformCoverageRootConstructionHooksAndVersionCoverage(t *testing
 		version, buildTime, gitCommit = oldVersion, oldBuild, oldCommit
 	})
 
-	rootLoadPlugins = func(*pipeline.Engine, executor.Runner) []*cobra.Command {
+	rootLoadPlugins = func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
 		return []*cobra.Command{{Use: "plugin-added", Run: func(*cobra.Command, []string) {}}}
 	}
 	preRunCalled := false
@@ -236,7 +236,8 @@ func TestCrossPlatformCoverageRootLoadPluginsRemainingCoverage(t *testing.T) {
 	oldDescriptors := rootPluginDescriptors
 	oldStdioClients := rootPluginStdioClients
 	oldHTTP := rootRegisterPluginHTTPServer
-	oldStdio := rootRegisterStdioManifest
+	oldStdioDescriptor := rootPluginStdioDescriptor
+	oldStdioRegister := rootRegisterResolvedStdioServer
 	oldHooks := rootPluginLoadHooks
 	oldSync := rootPluginSyncSkills
 	oldToken := rootAuthLoadTokenData
@@ -247,7 +248,8 @@ func TestCrossPlatformCoverageRootLoadPluginsRemainingCoverage(t *testing.T) {
 		rootPluginDescriptors = oldDescriptors
 		rootPluginStdioClients = oldStdioClients
 		rootRegisterPluginHTTPServer = oldHTTP
-		rootRegisterStdioManifest = oldStdio
+		rootPluginStdioDescriptor = oldStdioDescriptor
+		rootRegisterResolvedStdioServer = oldStdioRegister
 		rootPluginLoadHooks = oldHooks
 		rootPluginSyncSkills = oldSync
 		rootAuthLoadTokenData = oldToken
@@ -264,9 +266,17 @@ func TestCrossPlatformCoverageRootLoadPluginsRemainingCoverage(t *testing.T) {
 	}
 	rootPluginDescriptors = func(p *plugin.Plugin) []mcptypes.ServerDescriptor {
 		if p == p1 {
-			return []mcptypes.ServerDescriptor{{Key: "http", Endpoint: "https://example.test"}}
+			return []mcptypes.ServerDescriptor{{
+				Key: "http", Endpoint: "https://example.test",
+				CLI: mcptypes.CLIOverlay{
+					ID: "http", Command: "one-http",
+					ToolOverrides: map[string]mcptypes.CLIToolOverride{
+						"ping": {CLIName: "ping"},
+					},
+				},
+			}}
 		}
-		return []mcptypes.ServerDescriptor{{Key: "no-cli", Endpoint: "https://example.test"}}
+		return []mcptypes.ServerDescriptor{{Key: p.Manifest.Name + "-no-cli", Endpoint: "https://example.test"}}
 	}
 	client := transport.NewStdioClient("ignored", nil, nil)
 	rootPluginStdioClients = func(p *plugin.Plugin, uc *plugin.UserContext) []plugin.StdioServerClient {
@@ -278,9 +288,23 @@ func TestCrossPlatformCoverageRootLoadPluginsRemainingCoverage(t *testing.T) {
 	httpCount := 0
 	stdioCount := 0
 	rootRegisterPluginHTTPServer = func(mcptypes.ServerDescriptor) { httpCount++ }
-	rootRegisterStdioManifest = func(*plugin.Plugin, plugin.StdioServerClient) mcptypes.ServerDescriptor {
+	rootPluginStdioDescriptor = func(*plugin.Plugin, plugin.StdioServerClient) (mcptypes.ServerDescriptor, bool) {
+		return mcptypes.ServerDescriptor{
+			Key: "local",
+			CLI: mcptypes.CLIOverlay{
+				ID: "local", Command: "one-stdio",
+				ToolOverrides: map[string]mcptypes.CLIToolOverride{
+					"pong": {CLIName: "pong"},
+				},
+			},
+		}, true
+	}
+	rootRegisterResolvedStdioServer = func(
+		*plugin.Plugin,
+		plugin.StdioServerClient,
+		mcptypes.ServerDescriptor,
+	) {
 		stdioCount++
-		return mcptypes.ServerDescriptor{}
 	}
 	rootPluginLoadHooks = func(p *plugin.Plugin) (*plugin.HooksConfig, error) {
 		switch p {
@@ -294,7 +318,8 @@ func TestCrossPlatformCoverageRootLoadPluginsRemainingCoverage(t *testing.T) {
 	}
 	synced := false
 	rootPluginSyncSkills = func([]*plugin.Plugin) { synced = true }
-	if got := loadPlugins(pipeline.NewEngine(), runnerCoverageFallback{}); got != nil {
+	got := loadPlugins(nil, pipeline.NewEngine(), runnerCoverageFallback{})
+	if len(got) != 2 || got[0].Name() != "one-http" || got[1].Name() != "one-stdio" {
 		t.Fatalf("loaded plugin commands = %#v", got)
 	}
 	if httpCount != 3 || stdioCount != 1 || !synced {

internal/app/runner.go

@@ -168,6 +168,7 @@ var (
 	runnerPreflightDocDownload          = (*runtimeRunner).preflightDocDownload
 	runnerCallTool                      = (*transport.Client).CallTool
 	runnerStdioEnsureInitialized        = (*transport.StdioClient).EnsureInitialized
+	runnerStdioListTools                = (*transport.StdioClient).ListTools
 	runnerStdioCallTool                 = (*transport.StdioClient).CallTool
 	runnerHandlePatAuthCheck            func(context.Context, *runtimeRunner, executor.Invocation, *apperrors.PATError, string, io.Writer) (executor.Result, error)
 	runnerRetryWithPatAuthRetry         func(context.Context, executor.Runner, executor.Invocation, *PatScopeError, string, io.Writer) (executor.Result, error)
@@ -485,7 +486,7 @@ func (r *runtimeRunner) handleCatalogMiss(ctx context.Context, invocation execut
 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) {
-		return r.executeStdioInvocation(ctx, invocation)
+		return r.executeStdioInvocationAtEndpoint(ctx, endpoint, invocation)
 	}
 
 	// Constructing the Cobra tree is also used for help, schema, and command
@@ -766,6 +767,14 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 // subprocess instead of the HTTP transport. This is used for plugin stdio
 // servers whose endpoints use the stdio:// scheme.
 func (r *runtimeRunner) executeStdioInvocation(ctx context.Context, invocation executor.Invocation) (executor.Result, error) {
+	return r.executeStdioInvocationAtEndpoint(ctx, "", invocation)
+}
+
+func (r *runtimeRunner) executeStdioInvocationAtEndpoint(
+	ctx context.Context,
+	endpoint string,
+	invocation executor.Invocation,
+) (executor.Result, error) {
 	if invocation.DryRun {
 		return executor.Result{
 			Invocation: invocation,
@@ -778,10 +787,14 @@ func (r *runtimeRunner) executeStdioInvocation(ctx context.Context, invocation e
 		}, nil
 	}
 
-	client, ok := LookupStdioClient(invocation.CanonicalProduct)
+	lookupKey := strings.Trim(strings.TrimPrefix(strings.TrimSpace(endpoint), stdioEndpointScheme), "/")
+	if lookupKey == "" {
+		lookupKey = invocation.CanonicalProduct
+	}
+	client, ok := LookupStdioClient(lookupKey)
 	if !ok {
 		return executor.Result{}, apperrors.NewInternal(
-			fmt.Sprintf("stdio client not found for %q", invocation.CanonicalProduct))
+			fmt.Sprintf("stdio client not found for %q", lookupKey))
 	}
 
 	callCtx := ctx
@@ -798,6 +811,27 @@ func (r *runtimeRunner) executeStdioInvocation(ctx context.Context, invocation e
 		)
 	}
 
+	tools, err := runnerStdioListTools(client, callCtx)
+	if err != nil {
+		return executor.Result{}, apperrors.NewAPI(
+			fmt.Sprintf("stdio tools/list failed: %v", err),
+			apperrors.WithOperation("tools/list"),
+			apperrors.WithReason("stdio_tools_list_error"),
+		)
+	}
+	schema, ok := pluginToolInputSchema(tools, invocation.Tool)
+	if !ok {
+		return executor.Result{}, apperrors.NewValidation(
+			fmt.Sprintf("plugin tool %q is not declared by tools/list", invocation.Tool),
+			apperrors.WithReason("plugin_tool_not_found"),
+		)
+	}
+	normalizedParams, err := normalizePluginInputParams(invocation.Params, schema)
+	if err != nil {
+		return executor.Result{}, err
+	}
+	invocation.Params = normalizedParams
+
 	callResult, err := runnerStdioCallTool(client, callCtx, invocation.Tool, invocation.Params)
 	if err != nil {
 		return executor.Result{}, apperrors.NewAPI(

internal/app/runner_full_coverage_test.go

@@ -290,10 +290,12 @@ func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) {
 
 func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *testing.T) {
 	oldStdioInit := runnerStdioEnsureInitialized
+	oldStdioList := runnerStdioListTools
 	oldStdioCall := runnerStdioCallTool
 	oldEdition := edition.Get()
 	t.Cleanup(func() {
 		runnerStdioEnsureInitialized = oldStdioInit
+		runnerStdioListTools = oldStdioList
 		runnerStdioCallTool = oldStdioCall
 		edition.Override(oldEdition)
 		StopAllStdioClients()
@@ -309,6 +311,14 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test
 		t.Fatalf("stdio initialize error = %v", err)
 	}
 	runnerStdioEnsureInitialized = func(*transport.StdioClient, context.Context) error { return nil }
+	runnerStdioListTools = func(*transport.StdioClient, context.Context) (transport.ToolsListResult, error) {
+		return transport.ToolsListResult{
+			Tools: []transport.ToolDescriptor{{
+				Name:        "tool",
+				InputSchema: map[string]any{"type": "object"},
+			}},
+		}, nil
+	}
 	runnerStdioCallTool = func(*transport.StdioClient, context.Context, string, map[string]any) (transport.ToolCallResult, error) {
 		return transport.ToolCallResult{}, wantErr
 	}
@@ -327,6 +337,16 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test
 	if got, err := r.executeStdioInvocation(context.Background(), inv); err != nil || !got.Invocation.Implemented {
 		t.Fatalf("stdio success = %#v, %v", got, err)
 	}
+	RegisterStdioClient("plugin/server-key", client)
+	overlayIDInvocation := inv
+	overlayIDInvocation.CanonicalProduct = "overlay-id"
+	if got, err := r.executeInvocation(
+		context.Background(),
+		"stdio://plugin/server-key",
+		overlayIDInvocation,
+	); err != nil || !got.Invocation.Implemented {
+		t.Fatalf("stdio endpoint-key lookup = %#v, %v", got, err)
+	}
 
 	r.globalFlags.Token = " explicit "
 	if got, err := r.resolveAuthToken(context.Background()); err != nil || got != "explicit" {

internal/app/schema_completeness_test.go

@@ -14,7 +14,7 @@ func TestRuntimeSchemaCompletenessCoversPublicCommandTree(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	root := NewRootCommand()
+	root := NewSchemaSourceRootCommand()
 	if err := cli.ValidateEmbeddedRuntimeSchemaCompleteness(root); err != nil {
 		t.Fatal(err)
 	}

internal/cli/AGENTS.md

@@ -0,0 +1,42 @@
+# Schema Runtime and Publication Agent Guide
+
+This file applies to `internal/cli/`. Read
+[`docs/schema-contributor-guide.md`](../../docs/schema-contributor-guide.md)
+before editing.
+
+## Owning inputs
+
+| Change | Edit |
+|---|---|
+| Canonical identity, primary path, aliases, navigation | `schema_command_registry.json` |
+| Parameter/property mapping | `schema_parameter_bindings.json` or reviewed metadata overlay |
+| Safety, interface, runtime gate | `schema_hints/metadata/<product>.json` |
+| Agent selection and examples | `schema_hints/selection/<product>.json` |
+| Exact reviewed omission | `schema_command_exclusions.json` |
+| Runtime query/projection behavior | Go implementation and focused tests in this package |
+
+The executable Cobra tree outside this package owns whether a command exists
+and which flags it accepts. Do not create a command or flag in Schema inputs.
+
+## Generated boundary
+
+- `schema_catalog.json` and `schema_agent_metadata/` are generated outputs.
+- Never hand-edit, merge from, or use a previous generated output as an input.
+- Change the owning reviewed input or generator, run `make generate-schema`,
+  and inspect authored and generated diffs separately.
+- A broad unrelated generated diff is a failure signal, not acceptable churn.
+
+## Self-check
+
+- Every public runnable Cobra leaf is bound or has one exact reviewed
+  exclusion; every delivered tool binds back to a runnable leaf.
+- Registry identity and native annotations agree; aliases do not mutate the
+  resolved contract.
+- Parameters reference real flags and retain Cobra-required floors.
+- Selection examples use executable paths/flags and never include `--yes`.
+- Runtime confirmation gates and published safety metadata agree.
+- Full, compact, summary, alias, and Catalog projections derive from the same
+  typed `ToolSpec` and preserve provenance winners.
+
+Run the focused package/generator tests and the complete command list in
+`docs/schema-contributor-guide.md`, beginning with `make generate-schema`.

internal/cli/canonical.go

@@ -304,3 +304,14 @@ func splitSchemaPathTokens(raw string) []string {
 	}
 	return out
 }
+
+// normalizeSchemaQueryCLIPath accepts the historical query spellings while
+// keeping authored Registry CLI paths strict and space-separated. Canonical
+// identity lookup still runs before this compatibility normalization.
+func normalizeSchemaQueryCLIPath(path string) string {
+	parts := splitSchemaPathTokens(strings.TrimSpace(path))
+	if len(parts) > 0 && parts[0] == "dws" {
+		parts = parts[1:]
+	}
+	return strings.Join(parts, " ")
+}

internal/cli/schema_agent_metadata/event.json

@@ -2,7 +2,7 @@
   "product_id": "event",
   "tools": {
     "event consume": {
-      "agent_summary": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+      "agent_summary": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
       "agent_summary_source": "dws-agent-selection/event",
       "availability": "available",
       "avoid_when": [
@@ -13,19 +13,19 @@
       "effect": "write",
       "effect_source": "agent-hint",
       "examples": [
-        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-        "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+        "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
       ],
       "field_provenance": {
         "agent_summary": {
-          "value": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+          "value": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
           "source": "internal/cli/schema_hints/selection/event.json",
           "precedence": "reviewed_explicit",
           "resolution": "highest_precedence",
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
-              "value": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+              "value": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
               "source": "internal/cli/schema_hints/selection/event.json",
               "precedence": "reviewed_explicit",
               "selected": true,
@@ -105,8 +105,8 @@
         },
         "examples": {
           "value": [
-            "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-            "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+            "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+            "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
           ],
           "source": "internal/cli/schema_hints/selection/event.json",
           "precedence": "reviewed_explicit",
@@ -115,8 +115,8 @@
           "candidates": [
             {
               "value": [
-                "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-                "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+                "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+                "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
               ],
               "source": "internal/cli/schema_hints/selection/event.json",
               "precedence": "reviewed_explicit",
@@ -538,7 +538,7 @@
       ]
     },
     "event schema": {
-      "agent_summary": "查询指定个人事件码的 payload 字段结构",
+      "agent_summary": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
       "agent_summary_source": "dws-agent-selection/event",
       "availability": "available",
       "avoid_when": [
@@ -549,18 +549,18 @@
       "effect": "read",
       "effect_source": "agent-hint",
       "examples": [
-        "dws event schema user_im_message_receive_at --format json"
+        "dws event schema user_im_message_receive_at --flatten --format json"
       ],
       "field_provenance": {
         "agent_summary": {
-          "value": "查询指定个人事件码的 payload 字段结构",
+          "value": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
           "source": "internal/cli/schema_hints/selection/event.json",
           "precedence": "reviewed_explicit",
           "resolution": "highest_precedence",
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
-              "value": "查询指定个人事件码的 payload 字段结构",
+              "value": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
               "source": "internal/cli/schema_hints/selection/event.json",
               "precedence": "reviewed_explicit",
               "selected": true,
@@ -640,7 +640,7 @@
         },
         "examples": {
           "value": [
-            "dws event schema user_im_message_receive_at --format json"
+            "dws event schema user_im_message_receive_at --flatten --format json"
           ],
           "source": "internal/cli/schema_hints/selection/event.json",
           "precedence": "reviewed_explicit",
@@ -649,7 +649,7 @@
           "candidates": [
             {
               "value": [
-                "dws event schema user_im_message_receive_at --format json"
+                "dws event schema user_im_message_receive_at --flatten --format json"
               ],
               "source": "internal/cli/schema_hints/selection/event.json",
               "precedence": "reviewed_explicit",

internal/cli/schema_agent_metadata/index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "source_hash": "sha256:de587cba5051dd4c2715353012d8d9f2a7c5208a0c6dee4ea703cfc97b7351f0",
+  "source_hash": "sha256:5df496973c41b3b4f7ae8c856ff0e9e99bcabd4455419b7d41bb23c44df6f1af",
   "surface_hash": "sha256:7ef588f38052f0104e027c8daff5fefd68698781f2c87715461183d4058288ed",
   "coverage": {
     "surface_products": 22,

internal/cli/schema_agent_metadata_audit.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "source_hash": "sha256:de587cba5051dd4c2715353012d8d9f2a7c5208a0c6dee4ea703cfc97b7351f0",
+  "source_hash": "sha256:5df496973c41b3b4f7ae8c856ff0e9e99bcabd4455419b7d41bb23c44df6f1af",
   "surface_hash": "sha256:7ef588f38052f0104e027c8daff5fefd68698781f2c87715461183d4058288ed",
   "source_files": 150,
   "hint_files": 46,

internal/cli/schema_catalog.go

@@ -290,7 +290,7 @@ func schemaPayloadFromLoadedCatalog(loaded loadedSchemaCatalog, args []string) (
 		return payload, nil
 	}
 	raw := strings.TrimSpace(args[0])
-	if tool, ok := loaded.Index.Resolve(raw); ok {
+	if tool, ok := loaded.Index.ResolveQuery(raw); ok {
 		return schemaToolForResolvedPath(tool, raw).ToPayload()
 	}
 	tokens := splitSchemaPathTokens(raw)

internal/cli/schema_catalog.json

@@ -1,12 +1,12 @@
 {
   "version": 1,
-  "source_hash": "sha256:522d4b43cf13f07430a407319a772cd11e9b1f268f8d98b4d68bdb385e4e585b",
+  "source_hash": "sha256:14398788381c822f208e8cae059d98cd60da6625023869c74015735650d67e6f",
   "surface_hash": "sha256:7ef588f38052f0104e027c8daff5fefd68698781f2c87715461183d4058288ed",
   "catalog": {
     "agent_metadata": {
       "products_with_metadata": 22,
       "source": "embedded-skill-metadata",
-      "source_hash": "sha256:de587cba5051dd4c2715353012d8d9f2a7c5208a0c6dee4ea703cfc97b7351f0",
+      "source_hash": "sha256:5df496973c41b3b4f7ae8c856ff0e9e99bcabd4455419b7d41bb23c44df6f1af",
       "surface_hash": "sha256:7ef588f38052f0104e027c8daff5fefd68698781f2c87715461183d4058288ed",
       "surface_products": 22,
       "surface_tools": 572,
@@ -12178,7 +12178,7 @@
         "tools": [
           {
             "agent_metadata_source": "embedded-skill-metadata",
-            "agent_summary": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+            "agent_summary": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
             "agent_summary_source": "dws-agent-selection/event",
             "availability": "available",
             "avoid_when": [
@@ -12189,7 +12189,7 @@
             "cli_name": "consume",
             "cli_path": "event consume",
             "confirmation": "not_required",
-            "description": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         扁平化 + 解析嵌套 + 抽取语义字段（Agent 友好）\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。",
+            "description": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         单行紧凑 JSON；不传 --flatten 时沿用原 compact processor\n\n数据结构：\n  ndjson/json/pretty 默认保持 transport envelope（type/event_type/data/headers）\n  --flatten          结构化格式输出稳定的顶层业务字段，适合 Agent / 脚本直接消费\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。",
             "effect": "write",
             "idempotency": "non_idempotent",
             "interface_mode": "composite",
@@ -12234,7 +12234,7 @@
           },
           {
             "agent_metadata_source": "embedded-skill-metadata",
-            "agent_summary": "查询指定个人事件码的 payload 字段结构",
+            "agent_summary": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
             "agent_summary_source": "dws-agent-selection/event",
             "availability": "available",
             "avoid_when": [
@@ -290130,7 +290130,7 @@
         "skills/mono/SKILL.md",
         "skills/mono/references/products/event.md"
       ],
-      "agent_summary": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+      "agent_summary": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
       "agent_summary_source": "dws-agent-selection/event",
       "availability": "available",
       "avoid_when": [
@@ -290149,13 +290149,13 @@
           ]
         ]
       },
-      "description": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         扁平化 + 解析嵌套 + 抽取语义字段（Agent 友好）\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。",
+      "description": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         单行紧凑 JSON；不传 --flatten 时沿用原 compact processor\n\n数据结构：\n  ndjson/json/pretty 默认保持 transport envelope（type/event_type/data/headers）\n  --flatten          结构化格式输出稳定的顶层业务字段，适合 Agent / 脚本直接消费\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。",
       "display": "事件订阅 (DingTalk Stream 长连接)",
       "effect": "write",
       "effect_source": "agent-hint",
       "examples": [
-        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-        "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+        "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
       ],
       "field_provenance": {
         "agent_summary": {
@@ -290165,14 +290165,14 @@
               "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
               "selected": true,
               "source": "internal/cli/schema_hints/selection/event.json",
-              "value": "订阅并持续消费指定个人事件，输出 NDJSON 事件流"
+              "value": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON"
             }
           ],
           "precedence": "reviewed_explicit",
           "resolution": "highest_precedence",
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "source": "internal/cli/schema_hints/selection/event.json",
-          "value": "订阅并持续消费指定个人事件，输出 NDJSON 事件流"
+          "value": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON"
         },
         "availability": {
           "candidates": [
@@ -290250,13 +290250,13 @@
               "precedence": "cobra_help",
               "selected": true,
               "source": "cobra_help",
-              "value": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         扁平化 + 解析嵌套 + 抽取语义字段（Agent 友好）\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。"
+              "value": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         单行紧凑 JSON；不传 --flatten 时沿用原 compact processor\n\n数据结构：\n  ndjson/json/pretty 默认保持 transport envelope（type/event_type/data/headers）\n  --flatten          结构化格式输出稳定的顶层业务字段，适合 Agent / 脚本直接消费\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。"
             }
           ],
           "precedence": "cobra_help",
           "resolution": "highest_precedence",
           "source": "cobra_help",
-          "value": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         扁平化 + 解析嵌套 + 抽取语义字段（Agent 友好）\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。"
+          "value": "订阅 DingTalk 个人事件并将每条事件以 NDJSON 输出到 stdout。\n\n输出格式（事件流默认 ndjson；显式 -f json/pretty/raw 可覆盖；-f table/csv 对\n事件流无意义会 fallback 到 ndjson）：\n  ndjson  (默认)  一行一对象，适合 jq / 管道处理\n  json            每事件多行美化 JSON（必须配 --max-events 或 --duration）\n  pretty          同 json，未来加颜色\n  raw             仅 SDK 原始 payload，无外层封装\n  compact         单行紧凑 JSON；不传 --flatten 时沿用原 compact processor\n\n数据结构：\n  ndjson/json/pretty 默认保持 transport envelope（type/event_type/data/headers）\n  --flatten          结构化格式输出稳定的顶层业务字段，适合 Agent / 脚本直接消费\n\n默认使用当前 OAuth 登录态自动创建/复用个人订阅并建立个人长连接；非默认组织加\n--profile。连上后 stderr 打就绪行 [event] ready，等它出现再读 stdout；停机用\nSIGTERM、关 stdin，或先用 dws event stop \u003csubscribe_id\u003e --dry-run 预览、确认后加\n--yes，绝不要 kill -9。\n--event-types/--filter 只影响本地 bus → consume 这一段投递；普通个人事件消费\n通常不需要设置。"
         },
         "effect": {
           "candidates": [
@@ -290282,8 +290282,8 @@
               "selected": true,
               "source": "internal/cli/schema_hints/selection/event.json",
               "value": [
-                "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-                "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+                "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+                "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
               ]
             }
           ],
@@ -290292,8 +290292,8 @@
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "source": "internal/cli/schema_hints/selection/event.json",
           "value": [
-            "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-            "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+            "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+            "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
           ]
         },
         "idempotency": {
@@ -290444,7 +290444,7 @@
       "interface_reason": "Reviewed composite workflow: the command creates or reuses a remote personal-event subscription and coordinates the local event bus and Stream consumer; no single pinned RPC represents the workflow.",
       "is_alias": false,
       "name": "consume",
-      "parameter_count": 27,
+      "parameter_count": 28,
       "parameters": {
         "compact": {
           "description": "提示 bus 客户端期望 compact 渲染（语义透传，bus 仍按原 payload 投递）",
@@ -291124,6 +291124,90 @@
           "required": false,
           "type": "string"
         },
+        "flatten": {
+          "description": "将个人事件 transport envelope 投影为稳定的顶层业务字段",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "将个人事件 transport envelope 投影为稳定的顶层业务字段"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "将个人事件 transport envelope 投影为稳定的顶层业务字段"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "inference",
+                  "selected": true,
+                  "source": "flag_name_inference",
+                  "value": "flatten"
+                }
+              ],
+              "precedence": "inference",
+              "resolution": "highest_precedence",
+              "source": "flag_name_inference",
+              "value": "flatten"
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "default",
+                  "selected": true,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "default",
+              "resolution": "fallback",
+              "source": "default",
+              "value": false
+            },
+            "required_when": {
+              "candidates": [
+                {
+                  "precedence": "default",
+                  "selected": true,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "default",
+              "resolution": "highest_precedence",
+              "source": "default",
+              "value": ""
+            },
+            "type": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_flag_type",
+                  "value": "boolean"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "boolean"
+            }
+          },
+          "property": "flatten",
+          "required": false,
+          "type": "boolean"
+        },
         "force": {
           "description": "仅 --foreground 模式生效：跳过单实例锁 (慎用：会让云事件被随机切分)",
           "field_provenance": {
@@ -293464,7 +293548,7 @@
         "skills/mono/SKILL.md",
         "skills/mono/references/products/event.md"
       ],
-      "agent_summary": "查询指定个人事件码的 payload 字段结构",
+      "agent_summary": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
       "agent_summary_source": "dws-agent-selection/event",
       "availability": "available",
       "avoid_when": [
@@ -293480,7 +293564,7 @@
       "effect": "read",
       "effect_source": "agent-hint",
       "examples": [
-        "dws event schema user_im_message_receive_at --format json"
+        "dws event schema user_im_message_receive_at --flatten --format json"
       ],
       "field_provenance": {
         "agent_summary": {
@@ -293490,14 +293574,14 @@
               "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
               "selected": true,
               "source": "internal/cli/schema_hints/selection/event.json",
-              "value": "查询指定个人事件码的 payload 字段结构"
+              "value": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式"
             }
           ],
           "precedence": "reviewed_explicit",
           "resolution": "highest_precedence",
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "source": "internal/cli/schema_hints/selection/event.json",
-          "value": "查询指定个人事件码的 payload 字段结构"
+          "value": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式"
         },
         "availability": {
           "candidates": [
@@ -293607,7 +293691,7 @@
               "selected": true,
               "source": "internal/cli/schema_hints/selection/event.json",
               "value": [
-                "dws event schema user_im_message_receive_at --format json"
+                "dws event schema user_im_message_receive_at --flatten --format json"
               ]
             }
           ],
@@ -293616,7 +293700,7 @@
           "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "source": "internal/cli/schema_hints/selection/event.json",
           "value": [
-            "dws event schema user_im_message_receive_at --format json"
+            "dws event schema user_im_message_receive_at --flatten --format json"
           ]
         },
         "idempotency": {
@@ -293763,8 +293847,92 @@
       "interface_reason": "命令读取 CLI 内置的个人事件 payload 定义，不绑定 pinned MCP RPC",
       "is_alias": false,
       "name": "schema",
-      "parameter_count": 1,
+      "parameter_count": 2,
       "parameters": {
+        "flatten": {
+          "description": "显示 --flatten 消费模式对应的顶层业务字段 schema",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "显示 --flatten 消费模式对应的顶层业务字段 schema"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "显示 --flatten 消费模式对应的顶层业务字段 schema"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "inference",
+                  "selected": true,
+                  "source": "flag_name_inference",
+                  "value": "flatten"
+                }
+              ],
+              "precedence": "inference",
+              "resolution": "highest_precedence",
+              "source": "flag_name_inference",
+              "value": "flatten"
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "default",
+                  "selected": true,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "default",
+              "resolution": "fallback",
+              "source": "default",
+              "value": false
+            },
+            "required_when": {
+              "candidates": [
+                {
+                  "precedence": "default",
+                  "selected": true,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "default",
+              "resolution": "highest_precedence",
+              "source": "default",
+              "value": ""
+            },
+            "type": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_flag_type",
+                  "value": "boolean"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "boolean"
+            }
+          },
+          "property": "flatten",
+          "required": false,
+          "type": "boolean"
+        },
         "format": {
           "default": "json",
           "description": "输出格式: json",

internal/cli/schema_catalog_coverage_more_test.go

@@ -194,6 +194,23 @@ func TestCrossPlatformCoverageSchemaCatalogLookupAndConversionEdges(t *testing.T
 	}
 }
 
+func TestEmbeddedSchemaLookupAcceptsCompatibleCLIPathSeparators(t *testing.T) {
+	loaded := embeddedSchemaCatalog()
+	for _, path := range []string{
+		"dev app list",
+		"dev.app.list",
+		"dev/app/list",
+	} {
+		payload, err := schemaPayloadFromLoadedCatalog(loaded, []string{path})
+		if err != nil {
+			t.Fatalf("schemaPayloadFromLoadedCatalog(%q) error = %v", path, err)
+		}
+		if got := schemaString(payload["canonical_path"]); got != "dev.list_dev_app" {
+			t.Fatalf("schemaPayloadFromLoadedCatalog(%q) canonical_path = %q, want %q", path, got, "dev.list_dev_app")
+		}
+	}
+}
+
 type catalogHookSnapshot struct {
 	parameterBindings func(BoundCommandRegistry, SchemaRegistry) error
 	dryRun            func(SchemaRegistry) error

internal/cli/schema_contract_model.go

@@ -617,6 +617,22 @@ func (i SchemaIndex) Resolve(path string) (ToolSpec, bool) {
 	return i.registry.Products[location.product].Tools[location.tool], true
 }
 
+// ResolveQuery adds compatibility for dotted and slash-separated CLI paths at
+// the user-facing query boundary. Resolve remains strict because Registry
+// validation uses it to detect missing canonical identities without falling
+// through to a similarly spelled CLI path.
+func (i SchemaIndex) ResolveQuery(path string) (ToolSpec, bool) {
+	if tool, ok := i.Resolve(path); ok {
+		return tool, true
+	}
+	canonical, ok := i.byCLIPath[normalizeSchemaQueryCLIPath(path)]
+	if !ok {
+		return ToolSpec{}, false
+	}
+	location := i.byCanonical[canonical]
+	return i.registry.Products[location.product].Tools[location.tool], true
+}
+
 // CanonicalPaths returns the complete tool identity set in stable order.
 func (i SchemaIndex) CanonicalPaths() []string {
 	paths := make([]string, 0, len(i.byCanonical))

internal/cli/schema_contract_model_test.go

@@ -514,6 +514,19 @@ func TestSchemaRegistryIndexResolvesCanonicalCLIAndAlias(t *testing.T) {
 			t.Fatalf("Resolve(%q) = %#v, %v", path, resolved.Identity, ok)
 		}
 	}
+	for _, path := range []string{
+		"calendar.attendee.delete",
+		"calendar/attendee/delete",
+		"dws.calendar.attendee.delete",
+	} {
+		resolved, ok := index.ResolveQuery(path)
+		if !ok || resolved.Identity.CanonicalPath != "calendar.attendee_delete" {
+			t.Fatalf("ResolveQuery(%q) = %#v, %v", path, resolved.Identity, ok)
+		}
+	}
+	if _, ok := index.ResolveQuery("calendar.attendee.unknown"); ok {
+		t.Fatal("unknown dotted CLI path unexpectedly resolved")
+	}
 	if got := index.CanonicalPaths(); !reflect.DeepEqual(got, []string{"calendar.attendee_delete"}) {
 		t.Fatalf("CanonicalPaths() = %#v", got)
 	}

internal/cli/schema_delivery_invariants_test.go

@@ -154,6 +154,35 @@ func TestSelectionExplicitEmptyListSurvivesFinalDelivery(t *testing.T) {
 	}
 }
 
+func TestCompatibleSchemaAliasSeparatorsSurviveFinalDelivery(t *testing.T) {
+	snapshot := schemaDeliveryTestSnapshot(schemaDeliveryTestTool{
+		Canonical: "sample.run",
+		CLIPath:   "sample category run",
+		Aliases:   []string{"sample legacy execute"},
+	})
+	encoded, err := json.Marshal(snapshot)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := decodeSchemaCatalogSnapshot(encoded)
+	if err != nil {
+		t.Fatalf("decodeSchemaCatalogSnapshot(): %v", err)
+	}
+	canonical, err := schemaPayloadFromLoadedCatalog(loaded, []string{"sample.run"})
+	if err != nil {
+		t.Fatalf("canonical query: %v", err)
+	}
+	for _, path := range []string{"sample legacy execute", "sample.legacy.execute", "sample/legacy/execute"} {
+		alias, aliasErr := schemaPayloadFromLoadedCatalog(loaded, []string{path})
+		if aliasErr != nil {
+			t.Fatalf("alias query %q: %v", path, aliasErr)
+		}
+		if problem := schemaAliasViewProblem(canonical, alias, "sample legacy execute"); problem != "" {
+			t.Fatalf("alias projection for %q: %s", path, problem)
+		}
+	}
+}
+
 func TestValidateSchemaDeliveryInvariantsAllowsOnlyEnvelopeHashes(t *testing.T) {
 	snapshot := schemaDeliveryTestSnapshot(schemaDeliveryTestTool{Canonical: "sample.run", CLIPath: "sample run"})
 	snapshot.SurfaceHash = "sha256:reviewed-command-registry"

internal/cli/schema_full_pipeline_external_test.go

@@ -16,7 +16,7 @@ import (
 // Go's normal per-package coverage accounting attributes the exercised Schema
 // assembly code to internal/cli.
 func TestCrossPlatformCoverageProductionSchemaSourcePipeline(t *testing.T) {
-	root := app.NewRootCommand()
+	root := app.NewSchemaSourceRootCommand()
 	resolved, err := cli.ResolveSchemaBuild(root)
 	if err != nil {
 		t.Fatalf("ResolveSchemaBuild() error = %v", err)
@@ -33,17 +33,17 @@ func TestCrossPlatformCoverageProductionSchemaSourcePipeline(t *testing.T) {
 	if len(snapshot.Tools) == 0 {
 		t.Fatal("production Schema snapshot contains no tools")
 	}
-	registry, err := cli.AssembleSchemaRegistry(app.NewRootCommand())
+	registry, err := cli.AssembleSchemaRegistry(app.NewSchemaSourceRootCommand())
 	if err != nil {
 		t.Fatalf("AssembleSchemaRegistry() error = %v", err)
 	}
 	if len(registry.Products) == 0 {
 		t.Fatal("assembled production Schema registry contains no products")
 	}
-	if err := cli.ValidateEmbeddedRuntimeSchemaCompleteness(app.NewRootCommand()); err != nil {
+	if err := cli.ValidateEmbeddedRuntimeSchemaCompleteness(app.NewSchemaSourceRootCommand()); err != nil {
 		t.Fatalf("ValidateEmbeddedRuntimeSchemaCompleteness() error = %v", err)
 	}
-	root = app.NewRootCommand()
+	root = app.NewSchemaSourceRootCommand()
 	if _, err := cli.ApplyEmbeddedManualSchemaHints(root); err != nil {
 		t.Fatal(err)
 	}

internal/cli/schema_hints/index.json

@@ -634,6 +634,11 @@
       "target": "event consume",
       "reason": "已审查的带 event_key 和输出参数的 Skill 引用，固定映射到当前公开 event consume leaf"
     },
+    "event consume user_im_message_receive_at": {
+      "status": "alias",
+      "target": "event consume",
+      "reason": "已审查的带 event_key 参数的 Skill 引用，固定映射到当前公开 event consume leaf"
+    },
     "event consume user_im_message_receive_group": {
       "status": "alias",
       "target": "event consume",

internal/cli/schema_hints/reference-review.json

@@ -585,6 +585,11 @@
       "target": "event consume",
       "reason": "已审查的带 event_key 和输出参数的 Skill 引用，固定映射到当前公开 event consume leaf"
     },
+    "event consume user_im_message_receive_at": {
+      "status": "alias",
+      "target": "event consume",
+      "reason": "已审查的带 event_key 参数的 Skill 引用，固定映射到当前公开 event consume leaf"
+    },
     "event consume user_im_message_receive_group": {
       "status": "alias",
       "target": "event consume",

internal/cli/schema_hints/selection/event.json

@@ -9,7 +9,7 @@
   },
   "tools": {
     "event.consume": {
-      "agent_summary": "订阅并持续消费指定个人事件，输出 NDJSON 事件流",
+      "agent_summary": "订阅并持续消费指定个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
       "use_when": [
         "需要实时监听 @我、指定单聊、指定群或指定发送人的后续消息事件",
         "需要监听指定单聊或群聊中的消息已读、撤回或表情回应事件",
@@ -20,8 +20,8 @@
         "只看事件目录/字段时用 event list / event schema"
       ],
       "examples": [
-        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --max-events 1 --format ndjson",
-        "dws event consume user_im_message_reaction_group --group cid-example --max-events 1 --format ndjson"
+        "dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+        "dws event consume user_im_message_reaction_group --group cid-example --flatten --max-events 1 --format ndjson"
       ],
       "reviewed": true,
       "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
@@ -57,7 +57,7 @@
       ]
     },
     "event.schema": {
-      "agent_summary": "查询指定个人事件码的 payload 字段结构",
+      "agent_summary": "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
       "use_when": [
         "已知任一公开个人消息 event_key，消费前需要理解扁平输出字段"
       ],
@@ -66,7 +66,7 @@
         "要实际收事件时用 event consume"
       ],
       "examples": [
-        "dws event schema user_im_message_receive_at --format json"
+        "dws event schema user_im_message_receive_at --flatten --format json"
       ],
       "reviewed": true,
       "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",

internal/cli/schema_runtime_registry.go

@@ -284,7 +284,7 @@ func runtimeSchemaPayloadFromRegistry(registry SchemaRegistry, args []string) (m
 	}
 
 	raw := strings.TrimSpace(args[0])
-	if tool, ok := index.Resolve(raw); ok {
+	if tool, ok := index.ResolveQuery(raw); ok {
 		tool = schemaToolForResolvedPath(tool, raw)
 		return renderRegistryToolPayload(tool)
 	}
@@ -338,7 +338,7 @@ func runtimeSchemaAllPayloadFromRegistry(registry SchemaRegistry) (map[string]an
 }
 
 func schemaToolForResolvedPath(tool ToolSpec, raw string) ToolSpec {
-	normalized := normalizeSchemaCLIPath(raw)
+	normalized := normalizeSchemaQueryCLIPath(raw)
 	if normalized == "" || normalized == tool.Identity.CLIPath || normalized == tool.Identity.PrimaryCLIPath {
 		return tool
 	}

internal/event/consume/run.go

@@ -90,6 +90,10 @@ type Config struct {
 	// NormalizeFormat; an empty Format here defaults to NDJSON inside
 	// BuildPipeline.
 	Format Format
+	// Flatten records whether the caller explicitly selected a structured
+	// business projection. Projector remains the executable behavior; this
+	// field is surfaced in dry-run output so users can verify the final mode.
+	Flatten bool
 	// OutputDir, if non-empty, switches the fallback sink from stdout to
 	// "file per event" under this directory.
 	OutputDir string

internal/event/consume/validate.go

@@ -132,6 +132,7 @@ func PrintDryRun(w io.Writer, cfg Config) {
 		fmt.Fprintf(w, "  filter           : %s\n", cfg.Filter)
 	}
 	fmt.Fprintf(w, "  format           : %s\n", cfg.Format)
+	fmt.Fprintf(w, "  flatten          : %v\n", cfg.Flatten)
 	if cfg.OutputDir != "" {
 		fmt.Fprintf(w, "  output_dir       : %s\n", cfg.OutputDir)
 	}

internal/event/consume/validate_test.go

@@ -137,6 +137,7 @@ func TestPrintDryRun_RendersAllSetFields(t *testing.T) {
 	c.EventTypes = []string{"im.*", "approval.*"}
 	c.Filter = "^im\\."
 	c.Format = FormatCompact
+	c.Flatten = true
 	c.OutputDir = "/tmp/events"
 	c.Routes, _ = ParseRoutes([]string{`^im\.=dir:/tmp/im/`})
 	c.MaxEvents = 5
@@ -151,7 +152,7 @@ func TestPrintDryRun_RendersAllSetFields(t *testing.T) {
 	wants := []string{
 		"client_id", "workdir", "ipc_endpoint", "im.*,approval.*",
 		"^im\\.", "compact", "/tmp/events", "route[0]", "max_events       : 5",
-		"duration", "true",
+		"duration", "flatten          : true", "true",
 	}
 	for _, w := range wants {
 		if !strings.Contains(out, w) {

internal/event/personal/output.go

@@ -394,6 +394,39 @@ func outputSchema(eventKey string) map[string]any {
 	}
 }
 
+func transportEnvelopeSchema(eventKey string) map[string]any {
+	eventType := reflect.TypeOf(transport.Event{})
+	properties := make(map[string]any, eventType.NumField())
+	for i := 0; i < eventType.NumField(); i++ {
+		field := eventType.Field(i)
+		name := strings.Split(field.Tag.Get("json"), ",")[0]
+		property := map[string]any{"type": schemaType(field.Type)}
+		switch name {
+		case "type":
+			property["description"] = "transport frame 类型"
+			property["enum"] = []string{string(transport.FrameTypeEvent)}
+		case "event_type":
+			property["description"] = "事件类型"
+			property["enum"] = []string{eventKey}
+		case "data":
+			property["description"] = "服务端业务 payload JSON 字符串"
+			property["content_media_type"] = "application/json"
+		case "headers":
+			property["description"] = "Stream transport headers"
+			property["additionalProperties"] = map[string]any{"type": "string"}
+		case "event_id":
+			property["description"] = "transport 事件 ID"
+		case "subscribe_id":
+			property["description"] = "个人事件订阅 ID"
+		}
+		properties[name] = property
+	}
+	return map[string]any{
+		"type":       "object",
+		"properties": properties,
+	}
+}
+
 func outputTypeForEvent(eventKey string) reflect.Type {
 	switch {
 	case isMessageReceiveEvent(eventKey):

internal/event/personal/registry.go

@@ -258,8 +258,18 @@ func Catalog(category string, enabledOnly, includePending bool) []Definition {
 }
 
 func BuildSchemaDocument(def Definition) SchemaDocument {
+	return BuildSchemaDocumentForMode(def, false)
+}
+
+func BuildSchemaDocumentForMode(def Definition, flatten bool) SchemaDocument {
 	requiredParams := make([]string, 0, len(def.RequiredParams))
 	requiredParams = append(requiredParams, def.RequiredParams...)
+	jqRootPath := ".data | fromjson"
+	schema := transportEnvelopeSchema(def.EventKey)
+	if flatten {
+		jqRootPath = "."
+		schema = outputSchema(def.EventKey)
+	}
 	return SchemaDocument{
 		EventKey:       def.EventKey,
 		DisplayName:    def.DisplayName,
@@ -268,8 +278,8 @@ func BuildSchemaDocument(def Definition) SchemaDocument {
 		RuleType:       def.RuleType,
 		RequiredParams: requiredParams,
 		Constraints:    cloneParameterConstraints(def.Constraints),
-		JQRootPath:     ".",
-		Schema:         outputSchema(def.EventKey),
+		JQRootPath:     jqRootPath,
+		Schema:         schema,
 	}
 }
 

internal/event/personal/registry_test.go

@@ -95,7 +95,7 @@ func TestDefinitionJSONHidesInternalSchemaIDs(t *testing.T) {
 	}
 }
 
-func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
+func TestSchemaDocumentsDefaultToTransportEnvelope(t *testing.T) {
 	for _, eventKey := range []string{EventMention, EventSingleChat, EventInChat, EventFromUser} {
 		t.Run(eventKey, func(t *testing.T) {
 			def, ok := Lookup(eventKey)
@@ -117,16 +117,16 @@ func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
 				"required_params",
 				"jq_root_path",
 				"schema",
+				"type",
+				"seq",
 				"event_id",
-				"timestamp",
+				"event_born_time",
+				"event_type",
 				"subscribe_id",
-				"content",
-				"sender",
-				"sender_open_dingtalk_id",
-				"conversation_id",
-				"message_id",
-				"create_time",
-				"event_time",
+				"source_id",
+				"data",
+				"headers",
+				"received_at_unix_ms",
 			} {
 				if !strings.Contains(out, want) {
 					t.Fatalf("schema for %s missing %q: %s", eventKey, want, out)
@@ -144,7 +144,6 @@ func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
 				"payload_schema",
 				"output_schema",
 				"data_json_path",
-				"headers",
 				"audit",
 				"tenant",
 				"subject",
@@ -152,13 +151,18 @@ func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
 				"msgIdMetaq",
 				"at_users",
 				"sender_user_id",
+				"sender_open_dingtalk_id",
+				"conversation_id",
+				"message_id",
+				"create_time",
+				"event_time",
 			} {
 				if strings.Contains(out, leaked) {
 					t.Fatalf("schema for %s leaked %q: %s", eventKey, leaked, out)
 				}
 			}
-			if doc.JQRootPath != "." {
-				t.Fatalf("jq_root_path = %q, want .", doc.JQRootPath)
+			if doc.JQRootPath != ".data | fromjson" {
+				t.Fatalf("jq_root_path = %q, want .data | fromjson", doc.JQRootPath)
 			}
 			if doc.RequiredParams == nil {
 				t.Fatalf("required_params = nil, want empty slice")
@@ -167,6 +171,38 @@ func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
 			if !ok {
 				t.Fatalf("schema.properties = %#v, want object", doc.Schema["properties"])
 			}
+			wantProperties := []string{
+				"type", "seq", "event_id", "event_born_time", "event_corp_id",
+				"event_type", "event_unified_app_id", "event_scope", "subscribe_id",
+				"source_id", "rule_type", "data", "headers", "received_at_unix_ms",
+			}
+			if len(props) != len(wantProperties) {
+				t.Fatalf("schema.properties = %#v, want exactly %d transport fields", props, len(wantProperties))
+			}
+			for _, name := range wantProperties {
+				if _, ok := props[name].(map[string]any); !ok {
+					t.Fatalf("schema.properties.%s = %#v, want object", name, props[name])
+				}
+			}
+		})
+	}
+}
+
+func TestFlattenedSchemaDocumentsUseMessageDTO(t *testing.T) {
+	for _, eventKey := range []string{EventMention, EventSingleChat, EventInChat, EventFromUser} {
+		t.Run(eventKey, func(t *testing.T) {
+			def, ok := Lookup(eventKey)
+			if !ok {
+				t.Fatalf("Lookup(%q) failed", eventKey)
+			}
+			doc := BuildSchemaDocumentForMode(def, true)
+			if doc.JQRootPath != "." {
+				t.Fatalf("jq_root_path = %q, want .", doc.JQRootPath)
+			}
+			props, ok := doc.Schema["properties"].(map[string]any)
+			if !ok {
+				t.Fatalf("schema.properties = %#v, want object", doc.Schema["properties"])
+			}
 			wantProperties := []string{
 				"type", "event_id", "timestamp", "subscribe_id", "message_id",
 				"conversation_id", "sender", "sender_open_dingtalk_id", "content",
@@ -180,6 +216,11 @@ func TestSchemaDocumentsUseSingleJSONSchema(t *testing.T) {
 					t.Fatalf("schema.properties.%s = %#v, want object", name, props[name])
 				}
 			}
+			for _, transportField := range []string{"data", "headers", "seq", "event_type"} {
+				if _, ok := props[transportField]; ok {
+					t.Fatalf("flattened schema exposed transport field %q", transportField)
+				}
+			}
 		})
 	}
 }
@@ -286,7 +327,7 @@ func TestActionSchemaDocumentsMatchOutputDTOs(t *testing.T) {
 				if !ok {
 					t.Fatalf("Lookup(%q) failed", eventKey)
 				}
-				doc := BuildSchemaDocument(def)
+				doc := BuildSchemaDocumentForMode(def, true)
 				if doc.JQRootPath != "." {
 					t.Fatalf("jq_root_path = %q, want .", doc.JQRootPath)
 				}

internal/executor/invocation.go

@@ -116,11 +116,14 @@ func NewWorkflowInvocation(legacyPath, workflowName string, steps []Invocation)
 func MergePayloads(jsonPayload, paramsPayload string, overrides map[string]any) (map[string]any, error) {
 	merged := make(map[string]any)
 
-	for label, payload := range map[string]string{
-		"--json":   jsonPayload,
-		"--params": paramsPayload,
+	for _, payload := range []struct {
+		label string
+		raw   string
+	}{
+		{label: "--json", raw: jsonPayload},
+		{label: "--params", raw: paramsPayload},
 	} {
-		value, err := parseJSONObject(label, payload)
+		value, err := parseJSONObject(payload.label, payload.raw)
 		if err != nil {
 			return nil, err
 		}

internal/executor/invocation_test.go

@@ -52,6 +52,10 @@ func TestCrossPlatformCoverageMergePayloadsAndToolCallRequest(t *testing.T) {
 	if empty, err := MergePayloads(" ", "", nil); err != nil || len(empty) != 0 {
 		t.Fatalf("empty MergePayloads() = %#v, %v", empty, err)
 	}
+	merged, err = MergePayloads(`{"same":"json"}`, `{"same":"params"}`, nil)
+	if err != nil || merged["same"] != "params" {
+		t.Fatalf("MergePayloads() precedence = %#v, %v; want --params to win", merged, err)
+	}
 	for _, input := range []string{`{`, `[]`, `null`} {
 		if _, err := MergePayloads(input, "", nil); err == nil {
 			t.Errorf("MergePayloads(%q) error = nil", input)

internal/generator/agentmetadata/production_pipeline_external_test.go

@@ -18,7 +18,7 @@ func TestCrossPlatformCoverageGenerateProductionAgentMetadataPipeline(t *testing
 	if err != nil {
 		t.Fatal(err)
 	}
-	root := app.NewRootCommand()
+	root := app.NewSchemaSourceRootCommand()
 	if _, err := cli.ApplyEmbeddedManualSchemaHints(root); err != nil {
 		t.Fatal(err)
 	}

internal/generator/cmd_schema_agent_metadata/main.go

@@ -46,7 +46,7 @@ var (
 	writeMetadataFileBytes = os.WriteFile
 	writeMetadataJSON      = writeJSON
 
-	newMetadataRoot              = app.NewRootCommand
+	newMetadataRoot              = app.NewSchemaSourceRootCommand
 	buildEffectiveMetadata       = cli.BuildEffectiveCommandRegistry
 	bindEffectiveMetadata        = cli.BindEffectiveCommandRegistry
 	loadSelectionMetadataHints   = cli.LoadAgentHintsFromSelectionForValidation

internal/generator/cmd_schema_catalog/main.go

@@ -48,7 +48,7 @@ func main() {
 		fail(err)
 	}
 
-	root := app.NewRootCommand()
+	root := app.NewSchemaSourceRootCommand()
 	if err := generateSchemaCatalog(root, resolvedSurfacePath, outputPath); err != nil {
 		fail(err)
 	}

internal/generator/cmd_schema_catalog/main_test.go

@@ -131,7 +131,7 @@ func TestCrossPlatformCoverageGenerateSchemaCatalogFailureEdges(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageGenerateSchemaCatalogResolvesBuildExactlyOnce(t *testing.T) {
-	root := app.NewRootCommand()
+	root := app.NewSchemaSourceRootCommand()
 	resolveCalls := 0
 	resolvedRegistryHash := ""
 	resolver := func(candidate *cobra.Command) (cli.ResolvedSchemaBuild, error) {

internal/generator/cmd_schema_registry_smoke/main.go

@@ -17,7 +17,7 @@ import (
 )
 
 var (
-	newSmokeRoot                = app.NewRootCommand
+	newSmokeRoot                = app.NewSchemaSourceRootCommand
 	buildEffectiveSmokeRegistry = cli.BuildEffectiveCommandRegistry
 	bindEffectiveSmokeRegistry  = cli.BindEffectiveCommandRegistry
 	buildSmokeRegistryData      = buildSmokeRegistry

internal/helpers/AGENTS.md

@@ -0,0 +1,72 @@
+# Product Command Handler Agent Guide
+
+This file applies to `internal/helpers/`. Read the root `AGENTS.md`,
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md), and
+[`docs/coding-agent-guide.md`](../../docs/coding-agent-guide.md) first.
+For package/file layout, read
+[`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md)
+before adding or moving product leaves.
+
+## Scope and routing
+
+`internal/helpers` owns product command construction and handler behavior. Find
+the owning product file and its closest tests before editing.
+
+| Concern | Owning surface |
+|---|---|
+| Root/static command wiring or plugin loading | `internal/app` |
+| Product command flags and handler behavior | `internal/helpers` |
+| Helpers file layout / megafile splits | [`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md) |
+| Shared Cobra construction | `internal/cobracmd` |
+| Invocation and transport | `internal/executor`, `internal/transport` |
+| Structured failures and recovery hints | `internal/errors`, `internal/recovery` |
+| Output encoding and projections | `internal/output` |
+| Confirmation and dry-run guards | `internal/safety` and command runtime gates |
+| Agent identity/Schema/parameters | `internal/cli` and [`docs/schema-contributor-guide.md`](../../docs/schema-contributor-guide.md) |
+
+Do not modify `internal/app` or shared layers merely to register an ordinary
+product leaf when the existing helper construction already owns it. Cross the
+package boundary only when the task changes that shared contract.
+
+## File layout (hard rules)
+
+- Stay in flat `package helpers`; do not add `helpers/{product}` subpackages by
+  default.
+- Product root `{product}.go` owns `new{Product}Command()` and wires subgroups.
+- Put leaves in `{product}_{resource}.go` by CLI resource (see `sheet_*.go`).
+- Do not grow megafiles such as `chat.go` or `aitable.go`; extract or add the
+  resource file instead.
+- Mechanical splits must be behavior-neutral and keep registration symbols
+  stable. Details and size guides:
+  [`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md).
+
+## Command contract
+
+- Confirm the current path and flags with `dws <path> --help` and the Cobra
+  construction before changing behavior.
+- Keep stdout machine-readable business data. Send progress, warnings, and
+  diagnostics through the established stderr/logging paths.
+- Preserve structured error category, stable exit behavior, cause, trace ID,
+  and an actionable recovery hint. Do not replace a typed lower-layer failure
+  with an unclassified message.
+- Treat paths, JSON payloads, filenames, and remote content as untrusted input;
+  use existing validation and sanitization helpers.
+- Mutating or destructive commands must keep their preview/confirmation
+  behavior aligned with runtime safety and published Schema metadata.
+- If flags, identity, parameters, selection, or safety metadata change, follow
+  the scoped `internal/cli/AGENTS.md` and regenerate from reviewed inputs.
+
+## Verification matrix
+
+| Change | Required focused evidence |
+|---|---|
+| Handler bug or behavior | package regression test including the failure path |
+| Flags or request mapping | Cobra/help test plus dry-run request assertion when the command supports preview |
+| Output or error behavior | structured payload, stderr/stdout, and exit-code assertions |
+| Mutating behavior | preview/confirmation test; live execution only with explicit authorization and disposable data |
+| Shared helper refactor | affected product tests plus `go test ./internal/helpers/...` |
+| Public command surface | Schema/command gates from `internal/cli/AGENTS.md` |
+
+Before handoff, run the narrow package tests, `make format-check`, and the
+admission checks selected by `docs/coding-agent-guide.md`. Do not claim a live
+round-trip when only dry-run or mocked transport was exercised.

internal/plugin/converter.go

@@ -14,7 +14,9 @@
 package plugin
 
 import (
+	"bytes"
 	"encoding/json"
+	"io"
 	"log/slog"
 	"os"
 	"path/filepath"
@@ -24,6 +26,8 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
 )
 
+const maxPluginCLIOverlayBytes = 4 << 20
+
 // UserContext holds the minimal user identity fields injected into
 // stdio plugin subprocesses via environment variables.
 type UserContext struct {
@@ -111,23 +115,9 @@ func (p *Plugin) ToServerDescriptors() []mcptypes.ServerDescriptor {
 			continue
 		}
 
-		overlay := mcptypes.CLIOverlay{}
-		if len(srv.CLI) > 0 {
-			if err := json.Unmarshal(srv.CLI, &overlay); err != nil {
-				slog.Warn("plugin: failed to parse CLIOverlay",
-					"plugin", p.Manifest.Name,
-					"server", key,
-					"error", err,
-				)
-			}
-		}
-
-		// Ensure the overlay has an ID — fall back to server key.
-		if overlay.ID == "" {
-			overlay.ID = key
-		}
-		if overlay.Command == "" {
-			overlay.Command = key
+		overlay, ok := p.ResolveCLIOverlay(key)
+		if !ok {
+			continue
 		}
 
 		source := "plugin"
@@ -154,3 +144,73 @@ func (p *Plugin) ToServerDescriptors() []mcptypes.ServerDescriptor {
 	}
 	return descriptors
 }
+
+// ResolveCLIOverlay resolves inline or external manifest CLI metadata exactly
+// once. External files are opened relative to the plugin root with os.Root so
+// absolute paths, parent traversal, and escaping symlinks fail closed.
+func (p *Plugin) ResolveCLIOverlay(serverKey string) (mcptypes.CLIOverlay, bool) {
+	overlay := mcptypes.CLIOverlay{
+		ID:      serverKey,
+		Command: serverKey,
+	}
+	server, ok := p.Manifest.MCPServers[serverKey]
+	if !ok || len(server.CLI) == 0 {
+		return overlay, true
+	}
+
+	data := []byte(strings.TrimSpace(string(server.CLI)))
+	if len(data) == 0 {
+		return overlay, true
+	}
+	if data[0] == '"' {
+		var relativePath string
+		if err := json.Unmarshal(data, &relativePath); err != nil ||
+			strings.TrimSpace(relativePath) == "" {
+			slog.Warn("plugin: invalid external CLI overlay path",
+				"plugin", p.Manifest.Name, "server", serverKey, "error", err)
+			return mcptypes.CLIOverlay{}, false
+		}
+		root, err := os.OpenRoot(p.Root)
+		if err != nil {
+			slog.Warn("plugin: failed to open plugin root",
+				"plugin", p.Manifest.Name, "server", serverKey, "error", err)
+			return mcptypes.CLIOverlay{}, false
+		}
+		defer root.Close()
+		file, err := root.Open(relativePath)
+		if err != nil {
+			slog.Warn("plugin: failed to open CLI overlay file",
+				"plugin", p.Manifest.Name, "server", serverKey,
+				"path", relativePath, "error", err)
+			return mcptypes.CLIOverlay{}, false
+		}
+		defer file.Close()
+		data, err = io.ReadAll(io.LimitReader(file, maxPluginCLIOverlayBytes+1))
+		if err != nil || len(data) > maxPluginCLIOverlayBytes {
+			slog.Warn("plugin: failed to read CLI overlay file",
+				"plugin", p.Manifest.Name, "server", serverKey,
+				"path", relativePath, "error", err)
+			return mcptypes.CLIOverlay{}, false
+		}
+	}
+
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&overlay); err != nil {
+		slog.Warn("plugin: failed to parse CLI overlay",
+			"plugin", p.Manifest.Name, "server", serverKey, "error", err)
+		return mcptypes.CLIOverlay{}, false
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		slog.Warn("plugin: CLI overlay contains trailing JSON",
+			"plugin", p.Manifest.Name, "server", serverKey, "error", err)
+		return mcptypes.CLIOverlay{}, false
+	}
+	if strings.TrimSpace(overlay.ID) == "" {
+		overlay.ID = serverKey
+	}
+	if strings.TrimSpace(overlay.Command) == "" {
+		overlay.Command = serverKey
+	}
+	return overlay, true
+}

internal/plugin/converter_coverage_test.go

@@ -0,0 +1,143 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package plugin
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestResolveCLIOverlayDefaultsAndInlineErrors(t *testing.T) {
+	plugin := &Plugin{
+		Root: t.TempDir(),
+		Manifest: Manifest{MCPServers: map[string]*MCPServer{
+			"empty":      {CLI: nil},
+			"whitespace": {CLI: json.RawMessage("   \n\t")},
+			"fallback":   {CLI: json.RawMessage(`{"id":" ","command":""}`)},
+			"malformed":  {CLI: json.RawMessage(`{`)},
+			"unknown":    {CLI: json.RawMessage(`{"id":"plugin","unknownField":true}`)},
+			"unknownFlag": {CLI: json.RawMessage(`{
+				"toolOverrides":{"tool":{"flags":{"value":{"unknownFlagField":true}}}}
+			}`)},
+			"trailing": {CLI: json.RawMessage(`{} {}`)},
+			"legacyTools": {CLI: json.RawMessage(`{
+				"tools":[{
+					"name":"tool","cliName":"leaf","title":"Title","description":"Description",
+					"isSensitive":true,"category":"read","hidden":true,
+					"flags":{"value":{"alias":"value-alias","shorthand":"v"}}
+				}]
+			}`)},
+		}},
+	}
+
+	for _, serverKey := range []string{"missing", "empty", "whitespace", "fallback"} {
+		t.Run(serverKey, func(t *testing.T) {
+			overlay, ok := plugin.ResolveCLIOverlay(serverKey)
+			if !ok || overlay.ID != serverKey || overlay.Command != serverKey {
+				t.Fatalf("ResolveCLIOverlay(%q) = (%#v, %v), want default overlay", serverKey, overlay, ok)
+			}
+		})
+	}
+	legacy, ok := plugin.ResolveCLIOverlay("legacyTools")
+	if !ok || len(legacy.Tools) != 1 || legacy.Tools[0].CLIName != "leaf" ||
+		legacy.Tools[0].Flags["value"].Alias != "value-alias" {
+		t.Fatalf("ResolveCLIOverlay(legacyTools) = (%#v, %v), want historical tool metadata", legacy, ok)
+	}
+	if overlay, ok := plugin.ResolveCLIOverlay("malformed"); ok {
+		t.Fatalf("ResolveCLIOverlay(malformed) = (%#v, true), want failure", overlay)
+	}
+	for _, serverKey := range []string{"unknown", "unknownFlag", "trailing"} {
+		if overlay, ok := plugin.ResolveCLIOverlay(serverKey); ok {
+			t.Fatalf("ResolveCLIOverlay(%s) = (%#v, true), want strict failure", serverKey, overlay)
+		}
+	}
+}
+
+func TestResolveCLIOverlayRejectsInvalidExternalFiles(t *testing.T) {
+	root := t.TempDir()
+	plugin := &Plugin{
+		Root: root,
+		Manifest: Manifest{MCPServers: map[string]*MCPServer{
+			"external": {},
+		}},
+	}
+	server := plugin.Manifest.MCPServers["external"]
+
+	t.Run("malformed path JSON", func(t *testing.T) {
+		server.CLI = json.RawMessage(`"unterminated`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want malformed path failure", overlay)
+		}
+	})
+
+	t.Run("blank path", func(t *testing.T) {
+		server.CLI = json.RawMessage(`"  "`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want blank path failure", overlay)
+		}
+	})
+
+	t.Run("missing root", func(t *testing.T) {
+		plugin.Root = filepath.Join(root, "does-not-exist")
+		server.CLI = json.RawMessage(`"overlay.json"`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want missing root failure", overlay)
+		}
+		plugin.Root = root
+	})
+
+	t.Run("missing file", func(t *testing.T) {
+		server.CLI = json.RawMessage(`"missing.json"`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want missing file failure", overlay)
+		}
+	})
+
+	t.Run("read error", func(t *testing.T) {
+		if err := os.Mkdir(filepath.Join(root, "overlay-dir"), 0o700); err != nil {
+			t.Fatal(err)
+		}
+		server.CLI = json.RawMessage(`"overlay-dir"`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want directory read failure", overlay)
+		}
+	})
+
+	t.Run("oversized file", func(t *testing.T) {
+		path := filepath.Join(root, "oversized.json")
+		if err := os.WriteFile(path, bytes.Repeat([]byte(" "), maxPluginCLIOverlayBytes+1), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		server.CLI = json.RawMessage(`"oversized.json"`)
+		if overlay, ok := plugin.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("ResolveCLIOverlay() = (%#v, true), want oversized file failure", overlay)
+		}
+	})
+}
+
+func TestResolveCLIOverlayExternalFileAppliesFallbackIdentity(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "overlay.json"), []byte(`{
+		"id":"",
+		"command":" ",
+		"aliases":["conference"]
+	}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	plugin := &Plugin{
+		Root: root,
+		Manifest: Manifest{MCPServers: map[string]*MCPServer{
+			"server-key": {CLI: json.RawMessage(`"overlay.json"`)},
+		}},
+	}
+
+	overlay, ok := plugin.ResolveCLIOverlay("server-key")
+	if !ok || overlay.ID != "server-key" || overlay.Command != "server-key" ||
+		len(overlay.Aliases) != 1 || overlay.Aliases[0] != "conference" {
+		t.Fatalf("ResolveCLIOverlay() = (%#v, %v), want fallback identity with file metadata", overlay, ok)
+	}
+}

internal/plugin/coverage_edges_test.go

@@ -131,22 +131,19 @@ func TestCrossPlatformCoveragePluginConverterEdges(t *testing.T) {
 		t.Fatalf("StdioClients(user) length = %d", len(got))
 	}
 	descriptors := p.ToServerDescriptors()
-	if len(descriptors) != 2 {
+	if len(descriptors) != 1 {
 		t.Fatalf("descriptors length = %d", len(descriptors))
 	}
-	seenDefault := false
 	seenOverlay := false
 	for _, d := range descriptors {
 		switch d.Key {
-		case "http-default":
-			seenDefault = d.CLI.ID == "http-default" && d.CLI.Command == "http-default" && d.HasCLIMeta
 		case "http-overlay":
 			seenOverlay = d.CLI.ID == "custom" && d.CLI.Command == "run" &&
 				d.AuthHeaders["Authorization"] == "Bearer secret"
 		}
 	}
-	if !seenDefault || !seenOverlay {
-		t.Fatalf("descriptor defaults/overlay not covered: %#v", descriptors)
+	if !seenOverlay {
+		t.Fatalf("valid descriptor overlay not covered: %#v", descriptors)
 	}
 	dataDir := filepath.Join(filepath.Dir(filepath.Dir(root)), "data")
 	if got := expandPluginVars("$"+"{DWS_PLUGIN_ROOT}|$"+"{DWS_PLUGIN_DATA}|$"+"{PLUGIN_TOKEN}", root); got != root+"|"+dataDir+"|secret" {
@@ -300,6 +297,7 @@ func TestCrossPlatformCoverageManifestEdges(t *testing.T) {
 func TestCrossPlatformCoverageLoaderDiscoveryLifecycle(t *testing.T) {
 	oldHome := pluginUserHomeDir
 	t.Cleanup(func() { pluginUserHomeDir = oldHome })
+	t.Setenv("DWS_CONFIG_DIR", "")
 	home := t.TempDir()
 	pluginUserHomeDir = func() (string, error) { return home, nil }
 	defaultLoader := NewLoader("1.2.3")
@@ -310,6 +308,12 @@ func TestCrossPlatformCoverageLoaderDiscoveryLifecycle(t *testing.T) {
 	if got := NewLoader("dev").PluginsDir; got != filepath.Join(".dws", "plugins") {
 		t.Fatalf("NewLoader error path = %q", got)
 	}
+	customConfig := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", customConfig)
+	if got := NewLoader("dev").PluginsDir; got != filepath.Join(customConfig, "plugins") {
+		t.Fatalf("NewLoader custom config path = %q", got)
+	}
+	t.Setenv("DWS_CONFIG_DIR", "")
 
 	root := t.TempDir()
 	l := &Loader{PluginsDir: root, CLIVersion: "1.0.0"}

internal/plugin/loader.go

@@ -56,9 +56,13 @@ var (
 
 // NewLoader creates a Loader with default paths.
 func NewLoader(cliVersion string) *Loader {
-	home, _ := pluginUserHomeDir()
+	configDir := strings.TrimSpace(os.Getenv("DWS_CONFIG_DIR"))
+	if configDir == "" {
+		home, _ := pluginUserHomeDir()
+		configDir = filepath.Join(home, ".dws")
+	}
 	return &Loader{
-		PluginsDir: filepath.Join(home, ".dws", "plugins"),
+		PluginsDir: filepath.Join(configDir, "plugins"),
 		CLIVersion: cliVersion,
 	}
 }

internal/plugin/plugin_test.go

@@ -74,6 +74,56 @@ func TestParseManifest(t *testing.T) {
 	}
 }
 
+func TestResolveCLIOverlayExternalFileIsRootContained(t *testing.T) {
+	root := t.TempDir()
+	overlayPath := filepath.Join(root, "overlay.json")
+	if err := os.WriteFile(overlayPath, []byte(`{
+		"id":"external-id",
+		"command":"external-command",
+		"toolOverrides":{"ping":{"cliName":"ping"}}
+	}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	loaded := &Plugin{
+		Root: root,
+		Manifest: Manifest{
+			Name: "external-plugin",
+			MCPServers: map[string]*MCPServer{
+				"external": {
+					Type:     "streamable-http",
+					Endpoint: "https://example.invalid/mcp",
+					CLI:      json.RawMessage(`"overlay.json"`),
+				},
+			},
+		},
+	}
+	overlay, ok := loaded.ResolveCLIOverlay("external")
+	if !ok || overlay.ID != "external-id" || overlay.Command != "external-command" {
+		t.Fatalf("external overlay = (%#v, %v)", overlay, ok)
+	}
+	descriptors := loaded.ToServerDescriptors()
+	if len(descriptors) != 1 || descriptors[0].CLI.ID != "external-id" {
+		t.Fatalf("external HTTP descriptors = %#v", descriptors)
+	}
+
+	outside := filepath.Join(t.TempDir(), "outside-overlay.json")
+	if err := os.WriteFile(outside, []byte(`{"id":"escaped"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	loaded.Manifest.MCPServers["external"].CLI = json.RawMessage(`"../outside-overlay.json"`)
+	if overlay, ok := loaded.ResolveCLIOverlay("external"); ok {
+		t.Fatalf("parent traversal resolved overlay %#v", overlay)
+	}
+
+	link := filepath.Join(root, "escaped-link.json")
+	if err := os.Symlink(outside, link); err == nil {
+		loaded.Manifest.MCPServers["external"].CLI = json.RawMessage(`"escaped-link.json"`)
+		if overlay, ok := loaded.ResolveCLIOverlay("external"); ok {
+			t.Fatalf("escaping symlink resolved overlay %#v", overlay)
+		}
+	}
+}
+
 func TestManifestValidate(t *testing.T) {
 	tests := []struct {
 		name       string
@@ -219,8 +269,23 @@ func TestLoadAllSuppressesOptionalPluginValidationWarnings(t *testing.T) {
 
 func TestPluginToServerDescriptors(t *testing.T) {
 	cliOverlay, _ := json.Marshal(map[string]any{
-		"id":      "conference",
-		"command": "conference",
+		"id":          "conference",
+		"command":     "conference",
+		"description": "video conference",
+		"groups": map[string]any{
+			"camera": map[string]any{"description": "camera control"},
+		},
+		"toolOverrides": map[string]any{
+			"open_camera": map[string]any{
+				"cliName":     "open",
+				"group":       "camera",
+				"description": "open camera",
+				"isSensitive": true,
+				"flags": map[string]any{
+					"device_id": map[string]any{"description": "camera device"},
+				},
+			},
+		},
 	})
 
 	p := &Plugin{
@@ -262,6 +327,16 @@ func TestPluginToServerDescriptors(t *testing.T) {
 	if d.CLI.ID != "conference" {
 		t.Errorf("cli.id = %q, want conference", d.CLI.ID)
 	}
+	override := d.CLI.ToolOverrides["open_camera"]
+	if d.CLI.Description != "video conference" ||
+		d.CLI.Groups["camera"].Description != "camera control" ||
+		override.CLIName != "open" ||
+		override.Group != "camera" ||
+		override.Description != "open camera" ||
+		!override.IsSensitive ||
+		override.Flags["device_id"].Description != "camera device" {
+		t.Fatalf("CLI overlay command metadata was not preserved: %#v", d.CLI)
+	}
 }
 
 func TestPluginToServerDescriptorsWithHeaders(t *testing.T) {

internal/shortcut/builtin/base_commands_test.go

@@ -0,0 +1,33 @@
+// 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.
+
+package builtin_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/builtin"
+)
+
+func TestBaseCommandsExposeSortedDistributionShortcuts(t *testing.T) {
+	commands := builtin.BaseCommands()
+	if len(commands) == 0 {
+		t.Fatal("BaseCommands returned no distribution shortcuts")
+	}
+	for index, command := range commands {
+		if index > 0 && commands[index-1].Name() > command.Name() {
+			t.Fatalf("BaseCommands are not sorted: %q before %q", commands[index-1].Name(), command.Name())
+		}
+		children := command.Commands()
+		if len(children) == 0 {
+			t.Fatalf("base shortcut service %q has no commands", command.Name())
+		}
+		for _, child := range children {
+			if !strings.HasPrefix(child.Name(), "+") {
+				t.Fatalf("base shortcut %q under %q is not mounted as a +command", child.Name(), command.Name())
+			}
+		}
+	}
+}

internal/shortcut/builtin/builtin.go

@@ -50,3 +50,9 @@ import (
 func Commands() []*cobra.Command {
 	return shortcut.Commands()
 }
+
+// BaseCommands returns only distribution-owned shortcuts for Schema and
+// interface generation.
+func BaseCommands() []*cobra.Command {
+	return shortcut.BuiltInCommands()
+}

internal/shortcut/register.go

@@ -41,6 +41,17 @@ func Commands() []*cobra.Command {
 	return build(allShortcuts)
 }
 
+// BuiltInCommands compiles only distribution-owned shortcuts.
+func BuiltInCommands() []*cobra.Command {
+	builtins := make([]Shortcut, 0, len(allShortcuts))
+	for _, registered := range allShortcuts {
+		if !registered.UserDefined {
+			builtins = append(builtins, registered)
+		}
+	}
+	return build(builtins)
+}
+
 // All returns the registered shortcuts. Primarily for coverage tests that need
 // each shortcut's declared flags (types/enums/required) to synthesize inputs.
 func All() []Shortcut {

internal/shortcut/shortcut_test.go

@@ -266,6 +266,26 @@ func TestCrossPlatformCoverageBuildGroupsByService(t *testing.T) {
 	}
 }
 
+func TestBuiltInCommandsExcludeUserDefinedShortcuts(t *testing.T) {
+	previous := append([]Shortcut(nil), allShortcuts...)
+	t.Cleanup(func() { allShortcuts = previous })
+	allShortcuts = nil
+	Register(
+		Shortcut{Service: "calendar", Command: "+builtin", Execute: noop},
+		Shortcut{Service: "calendar", Command: "+user", UserDefined: true, Execute: noop},
+	)
+
+	all := Commands()
+	if len(all) != 1 || len(all[0].Commands()) != 2 {
+		t.Fatalf("all shortcut commands = %#v", all)
+	}
+	builtins := BuiltInCommands()
+	if len(builtins) != 1 || len(builtins[0].Commands()) != 1 ||
+		builtins[0].Commands()[0].Name() != "+builtin" {
+		t.Fatalf("built-in shortcut commands = %#v", builtins)
+	}
+}
+
 func noop(_ *RuntimeContext) error { return nil }
 
 func TestCrossPlatformCoverageCallMCPWriteDataRejectsDryRun(t *testing.T) {

internal/shortcut/types.go

@@ -127,6 +127,10 @@ type Shortcut struct {
 	Tips []string
 	// Hidden hides the command from listings while keeping it invocable.
 	Hidden bool
+	// UserDefined identifies shortcuts loaded from the user's config
+	// directory. Distribution-owned Schema and interface snapshots exclude
+	// these runtime extensions even if another root loaded them earlier.
+	UserDefined bool
 
 	// Validate optionally checks resolved flag values before execution. Return a
 	// non-nil error to abort with a validation message. Runs after built-in

internal/shortcut/userdef/loader.go

@@ -196,6 +196,7 @@ func Compile(s Spec) shortcut.Shortcut {
 		Intent:      intent,
 		Risk:        risk,
 		Flags:       flags,
+		UserDefined: true,
 		Execute: func(rt *shortcut.RuntimeContext) error {
 			params := map[string]any{}
 			for key, tmpl := range bind {

internal/shortcut/userdef/loader_test.go

@@ -69,6 +69,9 @@ func TestCrossPlatformCoverageCompileFlagsAndDefaults(t *testing.T) {
 	if sc.Service != "chat" || sc.Command != "+notify-team" {
 		t.Fatalf("bad identity: %+v", sc)
 	}
+	if !sc.UserDefined {
+		t.Fatal("compiled user shortcut is missing user-defined provenance")
+	}
 	if sc.Risk != shortcut.RiskRead {
 		t.Errorf("risk default = %q, want read", sc.Risk)
 	}

pkg/cmdutil/provenance.go

@@ -23,15 +23,28 @@ const SourceAnnotation = "dws.source"
 // SourceEnvelope marks a command as authored by the runtime discovery envelope.
 const SourceEnvelope = "envelope"
 
+// SourcePlugin marks a command as an installed plugin extension. Plugin
+// commands are part of the runtime CLI surface, not the embedded base Schema.
+const SourcePlugin = "plugin"
+
 // MarkEnvelopeSource stamps cmd with runtime discovery provenance.
 func MarkEnvelopeSource(cmd *cobra.Command) {
+	markSource(cmd, SourceEnvelope)
+}
+
+// MarkPluginSource stamps cmd with installed-plugin provenance.
+func MarkPluginSource(cmd *cobra.Command) {
+	markSource(cmd, SourcePlugin)
+}
+
+func markSource(cmd *cobra.Command, source string) {
 	if cmd == nil {
 		return
 	}
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	cmd.Annotations[SourceAnnotation] = SourceEnvelope
+	cmd.Annotations[SourceAnnotation] = source
 }
 
 // IsEnvelopeSourced reports whether cmd was authored by the runtime discovery
@@ -40,6 +53,11 @@ func IsEnvelopeSourced(cmd *cobra.Command) bool {
 	return cmd != nil && cmd.Annotations[SourceAnnotation] == SourceEnvelope
 }
 
+// IsPluginSourced reports whether cmd came from an installed plugin.
+func IsPluginSourced(cmd *cobra.Command) bool {
+	return cmd != nil && cmd.Annotations[SourceAnnotation] == SourcePlugin
+}
+
 // KindAnnotation is the annotation key for marking command kinds.
 const KindAnnotation = "dws.kind"
 

pkg/cmdutil/provenance_test.go

@@ -43,3 +43,19 @@ func TestMarkEnvelopeSourceNilDoesNotPanic(t *testing.T) {
 	t.Parallel()
 	MarkEnvelopeSource(nil)
 }
+
+func TestPluginSourceProvenance(t *testing.T) {
+	t.Parallel()
+	if IsPluginSourced(nil) {
+		t.Fatal("nil command should not be plugin sourced")
+	}
+	cmd := &cobra.Command{Use: "conference"}
+	MarkPluginSource(cmd)
+	if !IsPluginSourced(cmd) || IsEnvelopeSourced(cmd) {
+		t.Fatalf("plugin source annotation = %#v", cmd.Annotations)
+	}
+	if got := cmd.Annotations[SourceAnnotation]; got != SourcePlugin {
+		t.Fatalf("SourceAnnotation = %q, want %q", got, SourcePlugin)
+	}
+	MarkPluginSource(nil)
+}

pkg/mcptypes/types.go

@@ -1,6 +1,10 @@
 package mcptypes
 
-import "encoding/json"
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+)
 
 type ServerDescriptor struct {
 	Key         string
@@ -16,19 +20,110 @@ type ServerDescriptor struct {
 type CLIOverlay struct {
 	ID            string                     `json:"id"`
 	Command       string                     `json:"command"`
+	Parent        string                     `json:"parent,omitempty"`
+	Description   string                     `json:"description,omitempty"`
 	Aliases       []string                   `json:"aliases"`
 	Prefixes      []string                   `json:"prefixes"`
+	Group         string                     `json:"group,omitempty"`
 	Skip          bool                       `json:"skip"`
+	Hidden        bool                       `json:"hidden,omitempty"`
 	Tools         []CLITool                  `json:"tools"`
+	Groups        map[string]CLIGroupDef     `json:"groups,omitempty"`
 	ToolOverrides map[string]CLIToolOverride `json:"toolOverrides,omitempty"`
+	ServerDeps    []string                   `json:"serverDeps,omitempty"`
+	Hints         map[string]json.RawMessage `json:"hintCommands,omitempty"`
+	RedirectTo    string                     `json:"redirectTo,omitempty"`
+}
+
+type CLIGroupDef struct {
+	Description string `json:"description,omitempty"`
 }
 
 type CLITool struct {
-	Name string `json:"name"`
+	Name        string                 `json:"name"`
+	CLIName     string                 `json:"cliName,omitempty"`
+	Title       string                 `json:"title,omitempty"`
+	Description string                 `json:"description,omitempty"`
+	IsSensitive bool                   `json:"isSensitive,omitempty"`
+	Category    string                 `json:"category,omitempty"`
+	Hidden      bool                   `json:"hidden,omitempty"`
+	Flags       map[string]CLIFlagHint `json:"flags,omitempty"`
+}
+
+type CLIFlagHint struct {
+	Shorthand string `json:"shorthand,omitempty"`
+	Alias     string `json:"alias,omitempty"`
 }
 
 type CLIToolOverride struct {
-	ServerOverride string `json:"serverOverride,omitempty"`
+	CLIName           string                     `json:"cliName,omitempty"`
+	CLIAliases        []string                   `json:"cliAliases,omitempty"`
+	Description       string                     `json:"description,omitempty"`
+	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      map[string]any             `json:"outputFormat,omitempty"`
+	ServerOverride    string                     `json:"serverOverride,omitempty"`
+	BodyWrapper       string                     `json:"bodyWrapper,omitempty"`
+	MutuallyExclusive [][]string                 `json:"mutuallyExclusive,omitempty"`
+	RequireOneOf      [][]string                 `json:"requireOneOf,omitempty"`
+	RequireTogether   [][]string                 `json:"requireTogether,omitempty"`
+	RejectPositional  bool                       `json:"rejectPositional,omitempty"`
+	RedirectTo        string                     `json:"redirectTo,omitempty"`
+	Pipeline          []json.RawMessage          `json:"pipeline,omitempty"`
+}
+
+type CLIFlagOverride struct {
+	Alias           string         `json:"alias,omitempty"`
+	Aliases         []string       `json:"aliases,omitempty"`
+	MapsTo          string         `json:"mapsTo,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       string         `json:"shorthand,omitempty"`
+	Required        bool           `json:"required,omitempty"`
+	Description     string         `json:"description,omitempty"`
+	Positional      bool           `json:"positional,omitempty"`
+	PositionalIndex int            `json:"positionalIndex,omitempty"`
+	Type            string         `json:"type,omitempty"`
+	OmitWhen        string         `json:"omitWhen,omitempty"`
+	RuntimeDefault  string         `json:"runtimeDefault,omitempty"`
+	PipelineLocal   bool           `json:"pipelineLocal,omitempty"`
+}
+
+func (override *CLIFlagOverride) UnmarshalJSON(data []byte) error {
+	type alias CLIFlagOverride
+	aux := struct {
+		Default json.RawMessage `json:"default,omitempty"`
+		*alias
+	}{alias: (*alias)(override)}
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&aux); err != nil {
+		return err
+	}
+	override.Default = coercePluginScalar(aux.Default)
+	return nil
+}
+
+func coercePluginScalar(raw json.RawMessage) string {
+	value := strings.TrimSpace(string(raw))
+	if value == "" || value == "null" ||
+		strings.HasPrefix(value, "{") || strings.HasPrefix(value, "[") {
+		return ""
+	}
+	if strings.HasPrefix(value, `"`) {
+		var decoded string
+		if json.Unmarshal(raw, &decoded) == nil {
+			return decoded
+		}
+		return ""
+	}
+	return value
 }
 
 func OverlayFromJSON(data json.RawMessage) CLIOverlay {

pkg/mcptypes/types_coverage_test.go

@@ -0,0 +1,70 @@
+package mcptypes
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestCLIFlagOverrideUnmarshalJSONCoercesScalarDefaults(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{name: "missing", raw: `{}`, want: ""},
+		{name: "null", raw: `{"default":null}`, want: ""},
+		{name: "object", raw: `{"default":{"nested":true}}`, want: ""},
+		{name: "array", raw: `{"default":[1,2]}`, want: ""},
+		{name: "string", raw: `{"default":"hello"}`, want: "hello"},
+		{name: "escaped string", raw: `{"default":"line\nvalue"}`, want: "line\nvalue"},
+		{name: "boolean", raw: `{"default":true}`, want: "true"},
+		{name: "integer", raw: `{"default":42}`, want: "42"},
+		{name: "number", raw: `{"default":-1.25}`, want: "-1.25"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var got CLIFlagOverride
+			if err := json.Unmarshal([]byte(tt.raw), &got); err != nil {
+				t.Fatalf("json.Unmarshal() error = %v", err)
+			}
+			if got.Default != tt.want {
+				t.Fatalf("Default = %q, want %q", got.Default, tt.want)
+			}
+		})
+	}
+
+	var got CLIFlagOverride
+	if err := json.Unmarshal([]byte(`{"alias":`), &got); err == nil {
+		t.Fatal("json.Unmarshal() error = nil, want malformed JSON error")
+	}
+	if err := got.UnmarshalJSON([]byte(`{"alias":`)); err == nil {
+		t.Fatal("CLIFlagOverride.UnmarshalJSON() error = nil, want malformed JSON error")
+	}
+	if err := json.Unmarshal([]byte(`{"unknownFlagField":true}`), &got); err == nil {
+		t.Fatal("CLIFlagOverride.UnmarshalJSON() accepted an unknown field")
+	}
+	if got := coercePluginScalar(json.RawMessage(`"unterminated`)); got != "" {
+		t.Fatalf("coercePluginScalar(invalid string) = %q, want empty", got)
+	}
+}
+
+func TestOverlayFromJSONHandlesEmptyValidAndMalformedInput(t *testing.T) {
+	if got := OverlayFromJSON(nil); got.ID != "" || got.Command != "" {
+		t.Fatalf("OverlayFromJSON(nil) = %#v, want zero overlay", got)
+	}
+
+	valid := json.RawMessage(`{
+		"id":"conference",
+		"command":"meeting",
+		"toolOverrides":{"create":{"flags":{"count":{"default":3}}}}
+	}`)
+	got := OverlayFromJSON(valid)
+	if got.ID != "conference" || got.Command != "meeting" ||
+		got.ToolOverrides["create"].Flags["count"].Default != "3" {
+		t.Fatalf("OverlayFromJSON(valid) = %#v", got)
+	}
+
+	if got := OverlayFromJSON(json.RawMessage(`{`)); got.ID != "" || got.Command != "" {
+		t.Fatalf("OverlayFromJSON(malformed) = %#v, want zero overlay", got)
+	}
+}

scripts/policy/check-coding-agent-harness.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+
+cd "$ROOT"
+exec go run ./scripts/policy/coding-agent-harness -root "$ROOT" "$@"

scripts/policy/coding-agent-harness/main.go

@@ -0,0 +1,460 @@
+package main
+
+import (
+	"bufio"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+var guideLineLimits = map[string]int{
+	"AGENTS.md":                  80,
+	"internal/cli/AGENTS.md":     80,
+	"internal/helpers/AGENTS.md": 100,
+	"skills/AGENTS.md":           80,
+}
+
+var markdownLinkPattern = regexp.MustCompile(`\[[^]]+\]\(([^)]+)\)`)
+
+type fileContract struct {
+	path     string
+	required []string
+}
+
+type taskField struct {
+	label        string
+	allowNone    bool
+	allowedValue map[string]bool
+}
+
+var taskFields = []taskField{
+	{label: "Task kind", allowedValue: map[string]bool{"bug": true, "feature": true, "refactor": true, "docs": true, "policy": true, "release": true}},
+	{label: "Goal (one primary outcome)"},
+	{label: "Current behavior and evidence"},
+	{label: "Acceptance criteria"},
+	{label: "In scope (packages/files/surfaces)"},
+	{label: "Out of scope", allowNone: true},
+	{label: "Compatibility constraints", allowNone: true},
+	{label: "Interface impact (commands/flags/output/errors/exit codes/Schema)", allowNone: true},
+	{label: "Safety or data-mutation constraints", allowNone: true},
+	{label: "Expected validation"},
+	{label: "Known environment limitations", allowNone: true},
+}
+
+var guideContracts = []fileContract{
+	{
+		path: "AGENTS.md",
+		required: []string{
+			"docs/coding-agent-guide.md",
+			"docs/coding-agent-task-template.md",
+			"docs/schema-contributor-guide.md",
+			"docs/helpers-structure-guide.md",
+			"docs/architecture.md",
+			"docs/skill-authoring-guide.md",
+			"skills/AGENTS.md",
+			"internal/helpers/AGENTS.md",
+			"docs/automation.md",
+			"docs/agent-code.md",
+			"Do not depend on generated Wiki or CodeWiki content.",
+		},
+	},
+	{
+		path: "CONTRIBUTING.md",
+		required: []string{
+			"docs/coding-agent-guide.md",
+			"docs/schema-contributor-guide.md",
+		},
+	},
+	{
+		path: "docs/coding-agent-guide.md",
+		required: []string{
+			"## 1. Normalize the task input",
+			"coding-agent-task-template.md",
+			"make coding-agent-task TASK=",
+			"primary outcome per task",
+			"helpers-structure-guide.md",
+			"not wired into CI",
+			"github.com/larksuite/cli/blob/",
+			"github.com/WecomTeam/wecom-cli/blob/",
+			"## 2. Establish the baseline",
+			"## 3. Implement from authoritative inputs",
+			"## 4. Select validation by change surface",
+			"Documentation only",
+			"Go implementation",
+			"CLI paths or flags",
+			"Schema registry, hints, or generators",
+			"CI or test sharding",
+			"Packaging or installers",
+			"Authentication, transport, or OS-specific code",
+			"## 5. Pre-handoff self-check",
+			"Outcome: what is now true",
+			"Validation: exact commands and results",
+		},
+	},
+	{
+		path: "docs/architecture.md",
+		required: []string{
+			"## Change Rules",
+			"helpers-structure-guide.md",
+			"skill-authoring-guide.md",
+			"schema-contributor-guide.md",
+			"## Repository Structure",
+			"internal/helpers",
+			"skills/",
+		},
+	},
+	{
+		path: "docs/skill-authoring-guide.md",
+		required: []string{
+			"skills/mono/",
+			"skills/multi/dingtalk-<product>/",
+			"dws-shared",
+			"Dual-write rule",
+			"make skill-command-integrity",
+			"schema-contributor-guide.md",
+		},
+	},
+	{
+		path: "skills/AGENTS.md",
+		required: []string{
+			"../docs/coding-agent-guide.md",
+			"../docs/skill-authoring-guide.md",
+			"../docs/schema-contributor-guide.md",
+			"make skill-command-integrity",
+			"Dual-write",
+		},
+	},
+	{
+		path: "docs/helpers-structure-guide.md",
+		required: []string{
+			"package helpers",
+			"{product}.go",
+			"{product}_{resource}.go",
+			"sheet.go",
+			"register_products.go",
+			"Anti-pattern to stop growing",
+			"Mechanical splits",
+			"make coding-agent-harness",
+			"not part of `make policy` or CI",
+		},
+	},
+	{
+		path: "docs/coding-agent-task-template.md",
+		required: []string{
+			"Goal (one primary outcome):",
+			"Current behavior and evidence:",
+			"Acceptance criteria:",
+			"In scope (packages/files/surfaces):",
+			"Out of scope:",
+			"Compatibility constraints:",
+			"Interface impact (commands/flags/output/errors/exit codes/Schema):",
+			"Safety or data-mutation constraints:",
+			"Expected validation:",
+			"Known environment limitations:",
+			"Expected stdout/stderr and exit behavior:",
+			"Mutation preview/confirmation behavior:",
+		},
+	},
+	{
+		path: "docs/schema-contributor-guide.md",
+		required: []string{
+			"internal/cli/schema_command_registry.json",
+			"internal/cli/schema_command_registry.schema.json",
+			"internal/cli/schema_hints/metadata/<product>.json",
+			"internal/cli/schema_hints/selection/<product>.json",
+			"internal/cli/schema_parameter_bindings.json",
+			"internal/cli/schema_mcp_metadata.json",
+			"internal/cli/schema_command_exclusions.json",
+			"internal/cli/schema_catalog.json",
+			"make generate-schema",
+			"make test-schema-agent-examples",
+		},
+	},
+	{
+		path: "internal/helpers/AGENTS.md",
+		required: []string{
+			"../../CONTRIBUTING.md",
+			"../../docs/coding-agent-guide.md",
+			"../../docs/schema-contributor-guide.md",
+			"../../docs/helpers-structure-guide.md",
+			"File layout (hard rules)",
+			"Do not grow megafiles",
+			"Keep stdout machine-readable business data.",
+			"structured error category",
+			"preview/confirmation",
+			"Do not claim a live",
+		},
+	},
+	{
+		path: "internal/cli/AGENTS.md",
+		required: []string{
+			"../../docs/schema-contributor-guide.md",
+			"schema_command_registry.json",
+			"schema_parameter_bindings.json",
+			"schema_hints/metadata/<product>.json",
+			"schema_hints/selection/<product>.json",
+			"schema_command_exclusions.json",
+			"schema_catalog.json",
+			"make generate-schema",
+		},
+	},
+}
+
+var requiredPaths = []string{
+	"docs/automation.md",
+	"docs/agent-code.md",
+	"scripts/policy/check-runtime-confirmation-truth.sh",
+	"scripts/policy/check-coding-agent-harness.sh",
+	"scripts/policy/check-generated-drift.sh",
+	"scripts/policy/check-schema-catalog.sh",
+	"scripts/policy/check-command-surface.sh",
+	"scripts/release/verify-package-managers.sh",
+}
+
+var requiredMakeTargets = []string{
+	"build",
+	"coding-agent-harness",
+	"coding-agent-task",
+	"format-check",
+	"test",
+	"policy",
+	"interface-integrity",
+	"skill-command-integrity",
+	"test-schema-agent-examples",
+	"generate-schema",
+	"package",
+}
+
+func main() {
+	root := flag.String("root", ".", "repository root")
+	task := flag.String("task", "", "optional filled coding-agent task file to validate")
+	flag.Parse()
+	if flag.NArg() != 0 {
+		fmt.Fprintln(os.Stderr, "coding agent harness: unexpected positional arguments")
+		os.Exit(2)
+	}
+
+	problems := validate(*root)
+	if strings.TrimSpace(*task) != "" {
+		taskPath := *task
+		if !filepath.IsAbs(taskPath) {
+			taskPath = filepath.Join(*root, taskPath)
+		}
+		problems = append(problems, validateTask(taskPath)...)
+		sort.Slice(problems, func(i, j int) bool { return problems[i].Error() < problems[j].Error() })
+	}
+	if len(problems) != 0 {
+		fmt.Fprintln(os.Stderr, "coding agent harness: failed")
+		for _, problem := range problems {
+			fmt.Fprintf(os.Stderr, "- %v\n", problem)
+		}
+		os.Exit(1)
+	}
+	fmt.Println("coding agent harness: ok")
+}
+
+func validateTask(path string) []error {
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return []error{fmt.Errorf("read task contract %s: %w", path, err)}
+	}
+
+	values := make(map[string][]string)
+	occurrences := make(map[string]int)
+	current := ""
+	scanner := bufio.NewScanner(strings.NewReader(string(content)))
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		matched := false
+		for _, field := range taskFields {
+			prefix := field.label + ":"
+			if strings.HasPrefix(line, prefix) {
+				current = field.label
+				occurrences[current]++
+				inline := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+				if inline != "" {
+					values[current] = append(values[current], inline)
+				}
+				matched = true
+				break
+			}
+		}
+		if matched || current == "" || line == "" || strings.HasPrefix(line, "```") {
+			continue
+		}
+		values[current] = append(values[current], line)
+	}
+	if err := scanner.Err(); err != nil {
+		return []error{fmt.Errorf("scan task contract %s: %w", path, err)}
+	}
+
+	var problems []error
+	for _, field := range taskFields {
+		if occurrences[field.label] > 1 {
+			problems = append(problems, fmt.Errorf("task contract field %q appears %d times; each field must be unique", field.label, occurrences[field.label]))
+		}
+		value := strings.TrimSpace(strings.Join(values[field.label], "\n"))
+		if value == "" {
+			problems = append(problems, fmt.Errorf("task contract is missing a value for %q", field.label))
+			continue
+		}
+		normalized := strings.ToLower(value)
+		if len(field.allowedValue) != 0 && !field.allowedValue[normalized] {
+			problems = append(problems, fmt.Errorf("task contract field %q has unsupported value %q", field.label, value))
+		}
+		if isPlaceholderTaskValue(normalized) {
+			problems = append(problems, fmt.Errorf("task contract field %q still contains placeholder value %q", field.label, value))
+		}
+		if !field.allowNone && (normalized == "none" || normalized == "n/a" || normalized == "not applicable") {
+			problems = append(problems, fmt.Errorf("task contract field %q requires concrete evidence", field.label))
+		}
+	}
+	sort.Slice(problems, func(i, j int) bool { return problems[i].Error() < problems[j].Error() })
+	return problems
+}
+
+func isPlaceholderTaskValue(value string) bool {
+	for _, line := range strings.Split(value, "\n") {
+		trimmed := strings.TrimSpace(line)
+		trimmed = strings.TrimLeft(trimmed, "-*0123456789.) ")
+		switch trimmed {
+		case "todo", "tbd", "unknown", "fill me", "to be decided":
+			return true
+		}
+		if strings.HasPrefix(trimmed, "todo:") || strings.HasPrefix(trimmed, "tbd:") || strings.Contains(trimmed, "<fill") || strings.Contains(trimmed, "<todo") {
+			return true
+		}
+	}
+	return false
+}
+
+func validate(root string) []error {
+	absRoot, err := filepath.Abs(root)
+	if err != nil {
+		return []error{fmt.Errorf("resolve root: %w", err)}
+	}
+
+	var problems []error
+	for _, contract := range guideContracts {
+		content, readErr := os.ReadFile(filepath.Join(absRoot, filepath.FromSlash(contract.path)))
+		if readErr != nil {
+			problems = append(problems, fmt.Errorf("read %s: %w", contract.path, readErr))
+			continue
+		}
+		text := string(content)
+		for _, required := range contract.required {
+			if !strings.Contains(text, required) {
+				problems = append(problems, fmt.Errorf("%s is missing required contract text %q", contract.path, required))
+			}
+		}
+		problems = append(problems, validateLocalLinks(absRoot, contract.path, text)...)
+	}
+
+	for path, limit := range guideLineLimits {
+		if lineCount, countErr := countLines(filepath.Join(absRoot, filepath.FromSlash(path))); countErr != nil {
+			problems = append(problems, fmt.Errorf("count %s lines: %w", path, countErr))
+		} else if lineCount > limit {
+			problems = append(problems, fmt.Errorf("%s has %d lines; scoped guide limit is %d", path, lineCount, limit))
+		}
+	}
+
+	for _, path := range requiredPaths {
+		info, statErr := os.Stat(filepath.Join(absRoot, filepath.FromSlash(path)))
+		if statErr != nil {
+			problems = append(problems, fmt.Errorf("required referenced path %s: %w", path, statErr))
+		} else if strings.HasSuffix(path, ".sh") && info.Mode().Perm()&0o111 == 0 {
+			problems = append(problems, fmt.Errorf("required referenced script %s is not executable", path))
+		}
+	}
+
+	makeTargets, makeErr := loadMakeTargets(filepath.Join(absRoot, "Makefile"))
+	if makeErr != nil {
+		problems = append(problems, makeErr)
+	} else {
+		for _, target := range requiredMakeTargets {
+			if !makeTargets[target] {
+				problems = append(problems, fmt.Errorf("makefile is missing referenced target %q", target))
+			}
+		}
+	}
+
+	sort.Slice(problems, func(i, j int) bool { return problems[i].Error() < problems[j].Error() })
+	return problems
+}
+
+func validateLocalLinks(root, document, content string) []error {
+	var problems []error
+	documentDir := filepath.Join(root, filepath.Dir(filepath.FromSlash(document)))
+	for _, match := range markdownLinkPattern.FindAllStringSubmatch(content, -1) {
+		target := strings.TrimSpace(match[1])
+		if target == "" || strings.HasPrefix(target, "#") || strings.HasPrefix(target, "http://") || strings.HasPrefix(target, "https://") || strings.HasPrefix(target, "mailto:") {
+			continue
+		}
+		if cut, _, ok := strings.Cut(target, "#"); ok {
+			target = cut
+		}
+		if target == "" {
+			continue
+		}
+		if filepath.IsAbs(target) {
+			problems = append(problems, fmt.Errorf("%s contains absolute local link %q", document, match[1]))
+			continue
+		}
+		resolved := filepath.Clean(filepath.Join(documentDir, filepath.FromSlash(target)))
+		rel, err := filepath.Rel(root, resolved)
+		if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			problems = append(problems, fmt.Errorf("%s link %q escapes repository root", document, match[1]))
+			continue
+		}
+		if _, err := os.Stat(resolved); err != nil {
+			problems = append(problems, fmt.Errorf("%s has broken local link %q: %w", document, match[1], err))
+		}
+	}
+	return problems
+}
+
+func countLines(path string) (int, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return 0, err
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	count := 0
+	for scanner.Scan() {
+		count++
+	}
+	return count, scanner.Err()
+}
+
+func loadMakeTargets(path string) (map[string]bool, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("read Makefile targets: %w", err)
+	}
+	defer file.Close()
+
+	targets := make(map[string]bool)
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" || line[0] == '\t' || strings.HasPrefix(strings.TrimSpace(line), "#") {
+			continue
+		}
+		name, _, ok := strings.Cut(line, ":")
+		if !ok || strings.ContainsAny(name, "= ") || strings.HasPrefix(name, ".") {
+			continue
+		}
+		targets[name] = true
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, errors.New("scan Makefile targets: " + err.Error())
+	}
+	return targets, nil
+}

scripts/policy/coding-agent-harness/main_test.go

@@ -0,0 +1,250 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRepositoryCodingAgentHarness(t *testing.T) {
+	root, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatalf("resolve repository root: %v", err)
+	}
+	if problems := validate(root); len(problems) != 0 {
+		t.Fatalf("repository harness problems:\n%s", formatProblems(problems))
+	}
+}
+
+func TestCodingAgentHarnessFixturePasses(t *testing.T) {
+	root := newHarnessFixture(t)
+	if problems := validate(root); len(problems) != 0 {
+		t.Fatalf("valid fixture problems:\n%s", formatProblems(problems))
+	}
+}
+
+func TestCodingAgentTaskContractPasses(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "task.md")
+	writeTaskFixture(t, path, validTaskContract)
+	if problems := validateTask(path); len(problems) != 0 {
+		t.Fatalf("valid task problems:\n%s", formatProblems(problems))
+	}
+}
+
+func TestCodingAgentTaskContractFailsClosed(t *testing.T) {
+	tests := []struct {
+		name        string
+		content     string
+		wantProblem string
+	}{
+		{
+			name:        "missing goal",
+			content:     strings.Replace(validTaskContract, "Goal (one primary outcome): Fix retry handling\n", "", 1),
+			wantProblem: `missing a value for "Goal (one primary outcome)"`,
+		},
+		{
+			name:        "blank acceptance criteria",
+			content:     strings.Replace(validTaskContract, "Acceptance criteria:\n- The retry succeeds once and then stops.\n", "Acceptance criteria:\n", 1),
+			wantProblem: `missing a value for "Acceptance criteria"`,
+		},
+		{
+			name:        "unsupported task kind",
+			content:     strings.Replace(validTaskContract, "Task kind: bug", "Task kind: experiment", 1),
+			wantProblem: `unsupported value "experiment"`,
+		},
+		{
+			name:        "placeholder acceptance bullet",
+			content:     strings.Replace(validTaskContract, "- The retry succeeds once and then stops.", "- TBD: decide expected retry result", 1),
+			wantProblem: "still contains placeholder value",
+		},
+		{
+			name:        "duplicate goal",
+			content:     strings.Replace(validTaskContract, "Goal (one primary outcome): Fix retry handling", "Goal (one primary outcome): Fix retry handling\nGoal (one primary outcome): Refactor transport", 1),
+			wantProblem: `field "Goal (one primary outcome)" appears 2 times`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "task.md")
+			writeTaskFixture(t, path, test.content)
+			problems := formatProblems(validateTask(path))
+			if !strings.Contains(problems, test.wantProblem) {
+				t.Fatalf("problems:\n%s\nwant substring %q", problems, test.wantProblem)
+			}
+		})
+	}
+}
+
+func TestCodingAgentHarnessFailsClosed(t *testing.T) {
+	tests := []struct {
+		name        string
+		mutate      func(t *testing.T, root string)
+		wantProblem string
+	}{
+		{
+			name: "root guide is no longer thin",
+			mutate: func(t *testing.T, root string) {
+				path := filepath.Join(root, "AGENTS.md")
+				file, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0)
+				if err != nil {
+					t.Fatal(err)
+				}
+				defer file.Close()
+				for i := 0; i < guideLineLimits["AGENTS.md"]; i++ {
+					if _, err := file.WriteString("extra line\n"); err != nil {
+						t.Fatal(err)
+					}
+				}
+			},
+			wantProblem: "scoped guide limit",
+		},
+		{
+			name: "task input field is removed",
+			mutate: func(t *testing.T, root string) {
+				replaceFixtureText(t, root, "docs/coding-agent-task-template.md", "Acceptance criteria:", "")
+			},
+			wantProblem: `docs/coding-agent-task-template.md is missing required contract text "Acceptance criteria:"`,
+		},
+		{
+			name: "route link is broken",
+			mutate: func(t *testing.T, root string) {
+				replaceFixtureText(t, root, "AGENTS.md", "[automation](docs/automation.md)", "[automation](docs/missing.md)")
+			},
+			wantProblem: "broken local link",
+		},
+		{
+			name: "referenced script is absent",
+			mutate: func(t *testing.T, root string) {
+				if err := os.Remove(filepath.Join(root, "scripts/policy/check-schema-catalog.sh")); err != nil {
+					t.Fatal(err)
+				}
+			},
+			wantProblem: "required referenced path scripts/policy/check-schema-catalog.sh",
+		},
+		{
+			name: "make target is absent",
+			mutate: func(t *testing.T, root string) {
+				replaceFixtureText(t, root, "Makefile", "package:\n", "removed-package:\n")
+			},
+			wantProblem: `makefile is missing referenced target "package"`,
+		},
+		{
+			name: "harness script is not executable",
+			mutate: func(t *testing.T, root string) {
+				path := filepath.Join(root, "scripts/policy/check-coding-agent-harness.sh")
+				if err := os.Chmod(path, 0o644); err != nil {
+					t.Fatal(err)
+				}
+			},
+			wantProblem: "required referenced script scripts/policy/check-coding-agent-harness.sh is not executable",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root := newHarnessFixture(t)
+			test.mutate(t, root)
+			problems := formatProblems(validate(root))
+			if !strings.Contains(problems, test.wantProblem) {
+				t.Fatalf("problems:\n%s\nwant substring %q", problems, test.wantProblem)
+			}
+		})
+	}
+}
+
+func newHarnessFixture(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+
+	for _, contract := range guideContracts {
+		var content strings.Builder
+		content.WriteString("# Fixture\n\n")
+		for _, required := range contract.required {
+			content.WriteString(required)
+			content.WriteByte('\n')
+		}
+		if contract.path == "AGENTS.md" {
+			content.WriteString("[coding](docs/coding-agent-guide.md)\n")
+			content.WriteString("[schema](docs/schema-contributor-guide.md)\n")
+			content.WriteString("[automation](docs/automation.md)\n")
+			content.WriteString("[agent code](docs/agent-code.md)\n")
+		}
+		writeFixtureFile(t, root, contract.path, content.String())
+	}
+
+	for _, path := range requiredPaths {
+		writeFixtureFileMode(t, root, path, "fixture\n", 0o755)
+	}
+	var makefile strings.Builder
+	for _, target := range requiredMakeTargets {
+		makefile.WriteString(target)
+		makefile.WriteString(":\n\t@true\n")
+	}
+	writeFixtureFile(t, root, "Makefile", makefile.String())
+	return root
+}
+
+func writeFixtureFile(t *testing.T, root, path, content string) {
+	t.Helper()
+	writeFixtureFileMode(t, root, path, content, 0o644)
+}
+
+func writeFixtureFileMode(t *testing.T, root, path, content string, mode os.FileMode) {
+	t.Helper()
+	full := filepath.Join(root, filepath.FromSlash(path))
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		t.Fatalf("create fixture directory: %v", err)
+	}
+	if err := os.WriteFile(full, []byte(content), mode); err != nil {
+		t.Fatalf("write fixture %s: %v", path, err)
+	}
+}
+
+func replaceFixtureText(t *testing.T, root, path, old, replacement string) {
+	t.Helper()
+	full := filepath.Join(root, filepath.FromSlash(path))
+	content, err := os.ReadFile(full)
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", path, err)
+	}
+	updated := strings.Replace(string(content), old, replacement, 1)
+	if updated == string(content) {
+		t.Fatalf("fixture %s does not contain %q", path, old)
+	}
+	if err := os.WriteFile(full, []byte(updated), 0o644); err != nil {
+		t.Fatalf("update fixture %s: %v", path, err)
+	}
+}
+
+func formatProblems(problems []error) string {
+	var lines []string
+	for _, problem := range problems {
+		lines = append(lines, problem.Error())
+	}
+	return strings.Join(lines, "\n")
+}
+
+func writeTaskFixture(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write task fixture: %v", err)
+	}
+}
+
+const validTaskContract = `# Task
+
+Task kind: bug
+Goal (one primary outcome): Fix retry handling
+Current behavior and evidence: The focused test reproduces two retries.
+Acceptance criteria:
+- The retry succeeds once and then stops.
+In scope (packages/files/surfaces): internal/transport
+Out of scope: Authentication behavior
+Compatibility constraints: Preserve existing flags and output
+Interface impact (commands/flags/output/errors/exit codes/Schema): None
+Safety or data-mutation constraints: No external writes
+Expected validation: Focused unit test and make test
+Known environment limitations: Live service unavailable
+`

scripts/policy/coding-agent-harness/testdata/valid-task.md

@@ -0,0 +1,15 @@
+# Retry Handling Task
+
+Task kind: bug
+Goal (one primary outcome): Fix transient retry handling
+Current behavior and evidence: A focused transport test reproduces two retries after a successful response.
+Acceptance criteria:
+- The retry loop stops after the first successful response.
+- The existing output and exit behavior remain unchanged.
+In scope (packages/files/surfaces): internal/transport retry implementation and tests
+Out of scope: Authentication and endpoint discovery
+Compatibility constraints: Preserve existing flags, JSON output, and exit codes
+Interface impact (commands/flags/output/errors/exit codes/Schema): None
+Safety or data-mutation constraints: No live service calls or external writes
+Expected validation: Focused transport tests, race test, formatting, and full Go test suite
+Known environment limitations: Live DingTalk service is intentionally not used

scripts/release/reconcile-gitee-assets.sh

@@ -8,16 +8,32 @@ GITEE_API="${GITEE_API:-https://gitee.com/api/v5}"
 GITEE_CURL_CONNECT_TIMEOUT="${GITEE_CURL_CONNECT_TIMEOUT:-15}"
 GITEE_CURL_MAX_TIME="${GITEE_CURL_MAX_TIME:-120}"
 GITEE_LIST_MAX_TIME="${GITEE_LIST_MAX_TIME:-20}"
+# Attachment-list reads are safe to retry and are used both before an upload
+# and to detect a committed upload whose HTTP response was lost. Keep retrying
+# long enough to bridge a short Gitee TLS/API outage without ever blindly
+# replaying the upload itself.
+GITEE_LIST_RETRIES="${GITEE_LIST_RETRIES:-24}"
+GITEE_LIST_RETRY_DELAY="${GITEE_LIST_RETRY_DELAY:-20}"
+GITEE_LIST_RETRY_WINDOW_SECONDS="${GITEE_LIST_RETRY_WINDOW_SECONDS:-420}"
 GITEE_VERIFY_MAX_TIME="${GITEE_VERIFY_MAX_TIME:-60}"
 GITEE_MUTATION_MAX_TIME="${GITEE_MUTATION_MAX_TIME:-20}"
-GITEE_UPLOAD_MAX_TIME="${GITEE_UPLOAD_MAX_TIME:-120}"
+# Gitee does not return a response until an attachment upload is committed.
+# From GitHub-hosted runners, a near-10 MiB DWS binary can legitimately take
+# more than five minutes, so keep the transfer deadline above that observed
+# floor while the per-asset and overall deadlines retain hard upper bounds.
+GITEE_UPLOAD_MAX_TIME="${GITEE_UPLOAD_MAX_TIME:-1200}"
+# The per-asset deadline guarantees one complete slow upload plus one complete
+# attachment-list recovery on each side of that upload. The second upload
+# attempt is allowed only for zero-byte failures before HTTP begins; a first
+# attempt that consumes the full transfer deadline intentionally exhausts the
+# retry budget instead of holding a runner for another full slow upload.
 GITEE_UPLOAD_RETRIES="${GITEE_UPLOAD_RETRIES:-2}"
 GITEE_UPLOAD_RETRY_DELAY="${GITEE_UPLOAD_RETRY_DELAY:-5}"
 GITEE_EXISTING_VERIFY_ATTEMPTS="${GITEE_EXISTING_VERIFY_ATTEMPTS:-1}"
 GITEE_POST_UPLOAD_VERIFY_ATTEMPTS="${GITEE_POST_UPLOAD_VERIFY_ATTEMPTS:-2}"
 GITEE_VERIFY_RETRY_DELAY="${GITEE_VERIFY_RETRY_DELAY:-5}"
-GITEE_ASSET_TIMEOUT_SECONDS="${GITEE_ASSET_TIMEOUT_SECONDS:-600}"
-GITEE_OVERALL_TIMEOUT_SECONDS="${GITEE_OVERALL_TIMEOUT_SECONDS:-4920}"
+GITEE_ASSET_TIMEOUT_SECONDS="${GITEE_ASSET_TIMEOUT_SECONDS:-2220}"
+GITEE_OVERALL_TIMEOUT_SECONDS="${GITEE_OVERALL_TIMEOUT_SECONDS:-18300}"
 
 err() {
   printf 'error: %s\n' "$*" >&2
@@ -43,6 +59,8 @@ for setting in \
   GITEE_CURL_CONNECT_TIMEOUT \
   GITEE_CURL_MAX_TIME \
   GITEE_LIST_MAX_TIME \
+  GITEE_LIST_RETRIES \
+  GITEE_LIST_RETRY_WINDOW_SECONDS \
   GITEE_VERIFY_MAX_TIME \
   GITEE_MUTATION_MAX_TIME \
   GITEE_UPLOAD_MAX_TIME \
@@ -54,6 +72,7 @@ for setting in \
   require_positive_integer "$setting" "${!setting}"
 done
 for setting in \
+  GITEE_LIST_RETRY_DELAY \
   GITEE_UPLOAD_RETRY_DELAY \
   GITEE_VERIFY_RETRY_DELAY; do
   require_nonnegative_integer "$setting" "${!setting}"
@@ -139,21 +158,81 @@ api_get() {
     --max-time "$max_time" "$@"
 }
 
-list_assets() {
-  api_get "$GITEE_LIST_MAX_TIME" \
+list_assets_once() {
+  local max_time="$1" payload
+  payload="$(api_get "$max_time" \
     -H "Authorization: token ${GITEE_TOKEN}" \
-    "${base}/releases/${release_id}/attach_files" \
-    | python3 -c 'import json,sys
+    "${base}/releases/${release_id}/attach_files")" || return 1
+  printf '%s\n' "$payload" | python3 -c 'import json,sys
 data=json.load(sys.stdin)
-rows=data if isinstance(data,list) else data.get("attach_files",[])
+if isinstance(data,list):
+    rows=data
+elif isinstance(data,dict) and "attach_files" in data:
+    rows=data["attach_files"]
+else:
+    raise ValueError("attachment list response must be a list or contain attach_files")
 if not isinstance(rows,list):
     raise ValueError("attach_files must be a list")
 for asset in rows:
+    if not isinstance(asset,dict):
+        raise ValueError("each attachment must be an object")
     name=asset.get("name","")
     asset_id=asset.get("id","")
     url=asset.get("browser_download_url","")
-    if name and asset_id != "":
-        print("%s\t%s\t%s" % (name, asset_id, url))'
+    valid_id=(isinstance(asset_id,int) and not isinstance(asset_id,bool) and asset_id > 0) or (isinstance(asset_id,str) and asset_id.isdigit() and int(asset_id) > 0)
+    if not isinstance(name,str) or not name or not valid_id or not isinstance(url,str) or not url:
+        raise ValueError("attachment identity and download URL are required")
+    print("%s\t%s\t%s" % (name, asset_id, url))'
+}
+
+list_assets() {
+  local attempt=1 candidate now retry_deadline remaining max_time delay
+  now="$(now_seconds)"
+  retry_deadline=$(( now + GITEE_LIST_RETRY_WINDOW_SECONDS ))
+  if [ "$retry_deadline" -gt "$active_deadline" ]; then
+    retry_deadline="$active_deadline"
+  fi
+  while [ "$attempt" -le "$GITEE_LIST_RETRIES" ]; do
+    now="$(now_seconds)"
+    remaining=$(( retry_deadline - now ))
+    [ "$remaining" -gt 0 ] || break
+    max_time="$GITEE_LIST_MAX_TIME"
+    if [ "$max_time" -gt "$remaining" ]; then
+      max_time="$remaining"
+    fi
+    # Publish one complete parse atomically. A malformed response can make the
+    # parser emit valid leading rows before it fails; leaking those rows into a
+    # later successful retry would manufacture duplicates and could delete a
+    # correct attachment.
+    if candidate="$(list_assets_once "$max_time")"; then
+      now="$(now_seconds)"
+      if [ "$now" -lt "$retry_deadline" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+      break
+    fi
+    if [ "$attempt" -ge "$GITEE_LIST_RETRIES" ]; then
+      break
+    fi
+    attempt=$((attempt + 1))
+    now="$(now_seconds)"
+    remaining=$(( retry_deadline - now ))
+    [ "$remaining" -gt 0 ] || break
+    delay="$GITEE_LIST_RETRY_DELAY"
+    if [ "$delay" -gt 0 ]; then
+      # Do not turn a configured backoff into a burst of zero-delay requests
+      # during the final wall-clock second. Explicit delay=0 remains available
+      # to fast unit tests and tightly controlled callers.
+      [ "$remaining" -gt 1 ] || break
+      if [ "$delay" -ge "$remaining" ]; then
+        delay=$(( remaining - 1 ))
+      fi
+    fi
+    echo "   ⚠ Gitee attachment list attempt $((attempt - 1))/${GITEE_LIST_RETRIES} failed; retrying in ${delay}s" >&2
+    sleep_within_deadline "$delay" || return 1
+  done
+  return 1
 }
 
 sha256_of() {
@@ -234,20 +313,42 @@ delete_named_assets() {
 }
 
 gitee_attach() {
-  local file="$1" name attempt response status max_time
+  local file="$1" name attempt response status max_time transfer_log metrics http_code size_upload safe_to_retry
   name="$(basename "$file")"
   attempt=1
   while [ "$attempt" -le "$GITEE_UPLOAD_RETRIES" ]; do
     status=0
     max_time="$(bounded_max_time "$GITEE_UPLOAD_MAX_TIME")" || return 1
-    if response="$(curl -fsS --connect-timeout "$GITEE_CURL_CONNECT_TIMEOUT" \
+    transfer_log="$(mktemp)" || return 1
+    if metrics="$(curl -fsS --connect-timeout "$GITEE_CURL_CONNECT_TIMEOUT" \
       --max-time "$max_time" \
       -X POST "${base}/releases/${release_id}/attach_files" \
-      -H "Authorization: token ${GITEE_TOKEN}" -F "file=@${file}" 2>&1)"; then
+      -H "Authorization: token ${GITEE_TOKEN}" \
+      -H "Expect:" \
+      -F "file=@${file}" \
+      -o /dev/null \
+      -w '%{http_code}\t%{size_upload}' \
+      2>"$transfer_log")"; then
       status=0
     else
       status=$?
     fi
+    response="$(<"$transfer_log")"
+    rm -f "$transfer_log"
+    http_code="${metrics%%$'\t'*}"
+    if [ "$metrics" = "$http_code" ]; then
+      size_upload=""
+    else
+      size_upload="${metrics#*$'\t'}"
+    fi
+    safe_to_retry=0
+    if [ "$status" -ne 0 ] && [ "$http_code" = "000" ] && \
+      awk -v value="$size_upload" 'BEGIN { exit !((value + 0) == 0 && value ~ /^[0-9]+([.][0-9]+)?$/) }'; then
+      # A request that never reached HTTP and uploaded zero bytes cannot have
+      # committed an attachment. TLS/DNS/connect failures are therefore the
+      # only transport failures safe to replay automatically.
+      safe_to_retry=1
+    fi
 
     # Gitee can commit an upload but let the HTTP response time out. Probe the
     # release before retrying so a lost response does not create duplicates.
@@ -259,6 +360,10 @@ gitee_attach() {
     fi
 
     echo "   ⚠ upload attempt ${attempt}/${GITEE_UPLOAD_RETRIES} failed for ${name}: $(printf '%s' "$response" | head -c 240)" >&2
+    if [ "$safe_to_retry" -ne 1 ]; then
+      echo "   ⚠ ${name} upload outcome is ambiguous (HTTP ${http_code:-unknown}, uploaded ${size_upload:-unknown} bytes); refusing to replay POST" >&2
+      return 1
+    fi
     attempt=$((attempt + 1))
     if [ "$attempt" -le "$GITEE_UPLOAD_RETRIES" ]; then
       # Remove any partial, stale, or duplicate attachment before the one

scripts/release/sync-to-gitee.sh

@@ -31,11 +31,13 @@ DIST_DIR="${DIST_DIR:-dist}"
 GITEE_API="${GITEE_API:-https://gitee.com/api/v5}"
 GITEE_CURL_CONNECT_TIMEOUT="${GITEE_CURL_CONNECT_TIMEOUT:-15}"
 GITEE_CURL_MAX_TIME="${GITEE_CURL_MAX_TIME:-120}"
-GITEE_SYNC_TIMEOUT_SECONDS="${GITEE_SYNC_TIMEOUT_SECONDS:-5700}"
+GITEE_SYNC_TIMEOUT_SECONDS="${GITEE_SYNC_TIMEOUT_SECONDS:-18840}"
 GITEE_TAG_TIMEOUT_SECONDS="${GITEE_TAG_TIMEOUT_SECONDS:-300}"
 GITEE_RELEASE_LOOKUP_MAX_TIME="${GITEE_RELEASE_LOOKUP_MAX_TIME:-60}"
+GITEE_RELEASE_LOOKUP_RETRIES="${GITEE_RELEASE_LOOKUP_RETRIES:-2}"
+GITEE_RELEASE_LOOKUP_RETRY_DELAY="${GITEE_RELEASE_LOOKUP_RETRY_DELAY:-2}"
 GITEE_RELEASE_CREATE_MAX_TIME="${GITEE_RELEASE_CREATE_MAX_TIME:-60}"
-GITEE_RECONCILE_TIMEOUT_SECONDS="${GITEE_RECONCILE_TIMEOUT_SECONDS:-4920}"
+GITEE_RECONCILE_TIMEOUT_SECONDS="${GITEE_RECONCILE_TIMEOUT_SECONDS:-18300}"
 GITEE_CHILD_DEADLINE_RESERVE_SECONDS="${GITEE_CHILD_DEADLINE_RESERVE_SECONDS:-5}"
 
 err() {
@@ -51,17 +53,28 @@ require_positive_integer() {
   [ "$value" -gt 0 ] || err "${name} must be greater than zero"
 }
 
+require_nonnegative_integer() {
+  local name="$1" value="$2"
+  case "$value" in
+    ''|*[!0-9]*) err "${name} must be a non-negative integer: ${value}" ;;
+  esac
+}
+
 for setting in \
   GITEE_CURL_CONNECT_TIMEOUT \
   GITEE_CURL_MAX_TIME \
   GITEE_SYNC_TIMEOUT_SECONDS \
   GITEE_TAG_TIMEOUT_SECONDS \
   GITEE_RELEASE_LOOKUP_MAX_TIME \
+  GITEE_RELEASE_LOOKUP_RETRIES \
   GITEE_RELEASE_CREATE_MAX_TIME \
   GITEE_RECONCILE_TIMEOUT_SECONDS \
   GITEE_CHILD_DEADLINE_RESERVE_SECONDS; do
   require_positive_integer "$setting" "${!setting}"
 done
+require_nonnegative_integer \
+  GITEE_RELEASE_LOOKUP_RETRY_DELAY \
+  "$GITEE_RELEASE_LOOKUP_RETRY_DELAY"
 
 missing=""
 [ -z "${GITEE_TOKEN:-}" ] && missing="$missing GITEE_TOKEN"
@@ -117,14 +130,6 @@ GITEE_TAG_TIMEOUT_SECONDS="$GITEE_TAG_TIMEOUT_SECONDS" \
 deadline_remaining >/dev/null || err "overall Gitee sync deadline exhausted during tag synchronization"
 target_commit="$(git rev-parse --verify "${VERSION}^{commit}")"
 
-api_get() {
-  local configured_max_time="$1" max_time
-  shift
-  max_time="$(bounded_max_time "$configured_max_time")" || return 1
-  curl -fsSL --connect-timeout "$GITEE_CURL_CONNECT_TIMEOUT" \
-    --max-time "$max_time" "$@"
-}
-
 release_id_from_json() {
   python3 -c 'import json, sys
 data = json.load(sys.stdin)
@@ -136,12 +141,41 @@ elif isinstance(value, str) and value.isdigit() and int(value) > 0:
 }
 
 # ── Resolve or create the Gitee release for this tag ──────────────────────────
-rel_json="$(api_get "$GITEE_RELEASE_LOOKUP_MAX_TIME" \
+# A transient lookup failure must not be mistaken for a missing release: doing
+# so can race a duplicate create and hides the actual Gitee availability issue.
+release_lookup_body="$(mktemp)"
+trap 'rm -f "$release_lookup_body"' EXIT HUP INT TERM
+lookup_max_time="$(bounded_max_time "$GITEE_RELEASE_LOOKUP_MAX_TIME")" \
+  || err "overall Gitee sync deadline exhausted before release lookup"
+if ! release_status="$(curl -sS --connect-timeout "$GITEE_CURL_CONNECT_TIMEOUT" \
+  --max-time "$lookup_max_time" \
+  --retry "$GITEE_RELEASE_LOOKUP_RETRIES" \
+  --retry-all-errors \
+  --retry-delay "$GITEE_RELEASE_LOOKUP_RETRY_DELAY" \
+  --retry-max-time "$lookup_max_time" \
+  -o "$release_lookup_body" \
+  -w '%{http_code}' \
   -H "Authorization: token ${GITEE_TOKEN}" \
-  "${base}/releases/tags/${VERSION}" 2>/dev/null || true)"
-release_id="$(printf '%s' "$rel_json" | release_id_from_json || true)"
+  "${base}/releases/tags/${VERSION}")"; then
+  deadline_remaining >/dev/null \
+    || err "overall Gitee sync deadline exhausted during release lookup"
+  err "could not query Gitee release ${VERSION} after bounded retries"
+fi
+rel_json="$(<"$release_lookup_body")"
+case "$release_status" in
+  200)
+    release_id="$(printf '%s' "$rel_json" | release_id_from_json || true)"
+    [ -n "$release_id" ] || err "Gitee release lookup returned HTTP 200 without a valid release id"
+    ;;
+  404)
+    release_id=""
+    ;;
+  *)
+    err "Gitee release lookup returned HTTP ${release_status} for ${VERSION}"
+    ;;
+esac
 
-if [ -z "$release_id" ]; then
+if [ "$release_status" = "404" ]; then
   deadline_remaining >/dev/null || err "overall Gitee sync deadline exhausted during release lookup"
   echo "   No Gitee release for ${VERSION} yet — creating it."
   create_max_time="$(bounded_max_time "$GITEE_RELEASE_CREATE_MAX_TIME")" \

skills/AGENTS.md

@@ -0,0 +1,23 @@
+# Bundled Skills Agent Guide
+
+This file applies to `skills/`. Read the root `AGENTS.md` and
+[`docs/coding-agent-guide.md`](../docs/coding-agent-guide.md) first. The full
+authoring contract lives in
+[`docs/skill-authoring-guide.md`](../docs/skill-authoring-guide.md); this file
+is the scoped summary.
+
+## Hard rules
+
+- `skills/mono` is the stable single-skill layout; `skills/multi/dingtalk-*`
+  are per-product experimental skills; `dws-shared` is the prerequisite.
+- Keep `SKILL.md` concise: frontmatter (`name`, `description` with triggers +
+  `Distinct from` + 命令前缀, `cli_version`), routing prose, and pointers.
+  Long references go to `references/`, recipes to `scripts/`.
+- Write safety rules as concise prose; no injected-preamble mechanism exists
+  in this repository.
+- Every referenced `dws` command must exist in the current binary; run
+  `make skill-command-integrity` before handoff.
+- Dual-write: CLI behavior changes update skill prose in the same change;
+  skill routing changes check Schema selection hints per
+  [`docs/schema-contributor-guide.md`](../docs/schema-contributor-guide.md).
+- Do not add new embed roots; `skills/embed.go` embeds `mono` + `multi` only.

skills/mono/SKILL.md

@@ -22,7 +22,7 @@ cli_version: ">=1.0.15"
 - 单次批量操作不超过 30 条记录
 - 所有命令必须**严格遵循**对应产品参考文档里面规定的参数格式（如：如果有参数值，则参数和参数值之间至少用一个空格隔开）
 - **脚本优先**：[scripts/](./scripts/) 下的 `python scripts/<name>.py` 已封装翻页/轮询/批量逻辑，遇到对应场景（如 AI 表格批量导入导出、AI 应用创建轮询、文档创建后写内容、钉盘目录树等）**优先调用脚本**而非手写多步命令。脚本均支持 `--dry-run` 预览、`--format json` 输出，失败时回退到手动步骤
-- **实时个人消息事件例外**：用户要监听消息、订阅事件、自动回复消息或事件驱动 Agent 时，必须走 `dws event consume` 长连接，不要写脚本轮询消息历史
+- **实时个人消息事件例外**：用户要监听消息、订阅事件、自动回复消息或事件驱动 Agent 时，必须走 `dws event consume ... --flatten` 长连接，不要写脚本轮询消息历史
 
 ## Shortcut 与原子命令的使用原则
 
@@ -259,7 +259,7 @@ Schema 与 Help 冲突是**契约漂移**，不得静默猜测或把两边字段
 
 `dev.*` 包含 helper-only 执行面，其中远端 helper 未进入 pinned metadata 时标记为 `composite`，不能伪装成 `local`。`event list` / `event schema` 读取内置目录和 payload 定义，属于 `local`；`event consume` / `event status` / `event stop` 同时编排远端个人订阅控制面与本地 bus/consume，属于 `composite`。实现来源不同，不改变统一查询边界：进入全局 `dws schema` 的命令必须先进入 reviewed CommandRegistry，并由同一 `ToolSpec` 投影到 leaf、产品/分组、`--all` 与 Catalog。不得在查询时重新调用 MCP `tools/list`，也不得把 Cobra 临时合成结果作为第二条 Schema 数据路径。
 
-事件需要区分两种 Schema：`dws event schema <event_key>` 查询事件 payload 字段；`dws schema "event consume"` 查询 CLI 命令参数。前者是真实业务命令，后者只读取最终内嵌 SchemaRegistry；不能相互替代。
+事件需要区分两种 Schema：`dws event schema <event_key> --flatten` 查询 Agent 要消费的顶层业务字段；`dws schema "event consume"` 查询 CLI 命令参数。前者是真实业务命令，后者只读取最终内嵌 SchemaRegistry；不能相互替代。
 
 `source` 表示最终命令 identity 的来源，不表示运行时 backing；helper/local/MCP 实现机制读取 `interface_mode`、`availability` 和 provenance，不要假定 `dev.*` 必然是 `source=mcp:<server>`，也不要假定本地命令必然是 `source=cobra`。
 

skills/mono/references/products/event.md

@@ -13,8 +13,8 @@
 
 | Command | Purpose |
 |---|---|
-| `dws event schema <event_key>` | 查看事件参数和输出字段 schema |
-| `dws event consume <event_key> [flags]` | 阻塞消费，事件写到 stdout，用 `-f ndjson` |
+| `dws event schema <event_key> --flatten` | 查看 Agent 使用的顶层业务字段 schema |
+| `dws event consume <event_key> --flatten [flags]` | 阻塞消费，事件写到 stdout，用 `-f ndjson` |
 | `dws event status --event <event_key>` | 查看个人订阅、bus、本地 consume |
 | `dws event stop <subscribe_id> --dry-run` / `--yes` | 先预览，再确认取消订阅并停止对应本地消费 |
 | `dws event stop --all --dry-run` / `--yes` | 先预览，再确认清理当前身份下全部个人订阅 |
@@ -42,20 +42,20 @@
 
 | 用户说 | 下一步 |
 |---|---|
-| "监听有人 @ 我的消息" | `event consume`，事件码 `user_im_message_receive_at`，参数 `-f ndjson` |
-| "监听我和 userId test-user-001 的单聊消息" | `event consume`，事件码 `user_im_message_receive_o2o`，参数 `--user test-user-001 -f ndjson` |
-| "监听我和 openDingtalkId abc 的单聊消息" | `event consume`，事件码 `user_im_message_receive_o2o`，参数 `--open-dingtalk-id abc -f ndjson` |
+| "监听有人 @ 我的消息" | `event consume`，事件码 `user_im_message_receive_at`，参数 `--flatten -f ndjson` |
+| "监听我和 userId test-user-001 的单聊消息" | `event consume`，事件码 `user_im_message_receive_o2o`，参数 `--user test-user-001 --flatten -f ndjson` |
+| "监听我和 openDingtalkId abc 的单聊消息" | `event consume`，事件码 `user_im_message_receive_o2o`，参数 `--open-dingtalk-id abc --flatten -f ndjson` |
 | "监听 XX 群消息" | 先 `dws chat search --query "XX" --format json`，确认后 consume group |
-| "监听 userId test-user-001 发给我的消息" | `event consume`，事件码 `user_im_message_receive_user`，参数 `--user test-user-001 -f ndjson` |
-| "监听 openDingtalkId abc 发给我的消息" | `event consume`，事件码 `user_im_message_receive_user`，参数 `--open-dingtalk-id abc -f ndjson` |
-| "监听我发给 userId test-user-001 的消息是否已读" | `event consume`，事件码 `user_im_message_read_o2o`，参数 `--user test-user-001 -f ndjson` |
+| "监听 userId test-user-001 发给我的消息" | `event consume`，事件码 `user_im_message_receive_user`，参数 `--user test-user-001 --flatten -f ndjson` |
+| "监听 openDingtalkId abc 发给我的消息" | `event consume`，事件码 `user_im_message_receive_user`，参数 `--open-dingtalk-id abc --flatten -f ndjson` |
+| "监听我发给 userId test-user-001 的消息是否已读" | `event consume`，事件码 `user_im_message_read_o2o`，参数 `--user test-user-001 --flatten -f ndjson` |
 | "监听 XX 群消息已读" | 先解析群 ID，再 consume `user_im_message_read_group --group <id>` |
-| "监听我和 userId test-user-001 的消息撤回" | `event consume`，事件码 `user_im_message_recall_o2o`，参数 `--user test-user-001 -f ndjson` |
+| "监听我和 userId test-user-001 的消息撤回" | `event consume`，事件码 `user_im_message_recall_o2o`，参数 `--user test-user-001 --flatten -f ndjson` |
 | "监听 XX 群消息撤回" | 先解析群 ID，再 consume `user_im_message_recall_group --group <id>` |
-| "监听我和 userId test-user-001 的消息贴表情" | `event consume`，事件码 `user_im_message_reaction_o2o`，参数 `--user test-user-001 -f ndjson` |
+| "监听我和 userId test-user-001 的消息贴表情" | `event consume`，事件码 `user_im_message_reaction_o2o`，参数 `--user test-user-001 --flatten -f ndjson` |
 | "监听 XX 群消息表情回应" | 先解析群 ID，再 consume `user_im_message_reaction_group --group <id>` |
 | "监听并自动回复某人的单聊消息" | 先解析对端 userId，再启动 o2o consume；不要写轮询脚本 |
-| "查看个人消息事件 schema" | `dws event schema <event_key>` |
+| "查看个人消息事件 schema" | `dws event schema <event_key> --flatten` |
 | "看个人事件订阅状态" | `dws event status --event <event_key>` |
 | "停止这个个人事件订阅" | `dws event stop <subscribe_id> --dry-run`，确认后改用 `--yes` |
 
@@ -66,8 +66,8 @@
 ## Call flow
 
 1. 从用户意图选择事件码；人名或群名先解析成必填 ID。
-2. 需要了解字段时运行 `dws event schema <event_key>`，读取 `schema.properties`；`jq_root_path` 当前固定为 `.`。
-3. 启动 `dws event consume <event_key> ... -f ndjson`，等待 stderr 出现 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>` 后开始处理 stdout，不要用 `sleep` 猜测。
+2. 需要了解字段时运行 `dws event schema <event_key> --flatten`，读取 `schema.properties`；此模式的 `jq_root_path` 为 `.`。
+3. 启动 `dws event consume <event_key> ... --flatten -f ndjson`，等待 stderr 出现 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>` 后开始处理 stdout，不要用 `sleep` 猜测。
 4. stdout 每行是一个扁平事件 JSON；直接按该事件的 `schema.properties` 读取顶层字段。
 5. 需要确认监听状态时运行 `dws event status --event <event_key>`，查看 `Subscriptions` 和 `Consumers`。
 6. 任务完成后优雅结束 consume；本次新建的订阅会自动取消。复用已有订阅或需要从外部主动取消时，先运行 `dws event stop <subscribe_id> --dry-run`，向用户确认后再以 `--yes` 执行；自测可在 consume 加 `--max-events` 或 `--duration` 自动退出。
@@ -75,31 +75,31 @@
 ## Commands
 
 ```bash
-dws event schema user_im_message_receive_at
-dws event schema user_im_message_receive_o2o
-dws event schema user_im_message_receive_group
-dws event schema user_im_message_receive_user
-dws event schema user_im_message_read_o2o
-dws event schema user_im_message_read_group
-dws event schema user_im_message_recall_o2o
-dws event schema user_im_message_recall_group
-dws event schema user_im_message_reaction_o2o
-dws event schema user_im_message_reaction_group
+dws event schema user_im_message_receive_at --flatten
+dws event schema user_im_message_receive_o2o --flatten
+dws event schema user_im_message_receive_group --flatten
+dws event schema user_im_message_receive_user --flatten
+dws event schema user_im_message_read_o2o --flatten
+dws event schema user_im_message_read_group --flatten
+dws event schema user_im_message_recall_o2o --flatten
+dws event schema user_im_message_recall_group --flatten
+dws event schema user_im_message_reaction_o2o --flatten
+dws event schema user_im_message_reaction_group --flatten
 ```
 
 ```bash
-dws event consume user_im_message_receive_at -f ndjson
-dws event consume user_im_message_receive_o2o --user test-user-001 -f ndjson
-dws event consume user_im_message_receive_o2o --open-dingtalk-id abc -f ndjson
-dws event consume user_im_message_receive_group --group <openConversationId> -f ndjson
-dws event consume user_im_message_receive_user --user test-user-001 -f ndjson
-dws event consume user_im_message_receive_user --open-dingtalk-id abc -f ndjson
-dws event consume user_im_message_read_o2o --user test-user-001 -f ndjson
-dws event consume user_im_message_read_group --group <openConversationId> -f ndjson
-dws event consume user_im_message_recall_o2o --user test-user-001 -f ndjson
-dws event consume user_im_message_recall_group --group <openConversationId> -f ndjson
-dws event consume user_im_message_reaction_o2o --user test-user-001 -f ndjson
-dws event consume user_im_message_reaction_group --group <openConversationId> -f ndjson
+dws event consume user_im_message_receive_at --flatten -f ndjson
+dws event consume user_im_message_receive_o2o --user test-user-001 --flatten -f ndjson
+dws event consume user_im_message_receive_o2o --open-dingtalk-id abc --flatten -f ndjson
+dws event consume user_im_message_receive_group --group <openConversationId> --flatten -f ndjson
+dws event consume user_im_message_receive_user --user test-user-001 --flatten -f ndjson
+dws event consume user_im_message_receive_user --open-dingtalk-id abc --flatten -f ndjson
+dws event consume user_im_message_read_o2o --user test-user-001 --flatten -f ndjson
+dws event consume user_im_message_read_group --group <openConversationId> --flatten -f ndjson
+dws event consume user_im_message_recall_o2o --user test-user-001 --flatten -f ndjson
+dws event consume user_im_message_recall_group --group <openConversationId> --flatten -f ndjson
+dws event consume user_im_message_reaction_o2o --user test-user-001 --flatten -f ndjson
+dws event consume user_im_message_reaction_group --group <openConversationId> --flatten -f ndjson
 ```
 
 上述所有 `*_o2o` 命令和 `user_im_message_receive_user` 都可将 `--user <userId>` 替换为 `--open-dingtalk-id <openDingtalkId>`，但两个参数不能同时使用。
@@ -125,10 +125,10 @@ dws event stop --all --yes
 
 ## Output parsing
 
-- 推荐 `-f ndjson`：一行一个事件 JSON，适合 Agent 管道读取。
-- 人工取样可用 `-f json --max-events 1`。
-- `jq_root_path` 当前为 `.`；消息正文、发送人和会话 ID 分别直接读取顶层 `content`、`sender`、`conversation_id`。
-- 不要生成 `fromjson` 或内部 payload 路径。正常处理直接持续读取 stdout，不要改写为 `--output-dir` watcher。
+- 推荐 `--flatten -f ndjson`：顶层业务字段，一行一个事件 JSON，适合 Agent 管道读取。
+- 人工取样可用 `--flatten -f json --max-events 1`。`--format` 只控制序列化，`--flatten` 控制数据结构。
+- `--flatten` 的 `jq_root_path` 为 `.`；消息正文、发送人和会话 ID 分别直接读取顶层 `content`、`sender`、`conversation_id`。
+- Agent 已显式使用 `--flatten`，不要再生成 `fromjson` 或内部 payload 路径。不传时默认保持兼容 envelope，业务 payload 在 `.data | fromjson`。正常处理直接持续读取 stdout，不要改写为 `--output-dir` watcher。
 - 群自动回复使用顶层 `conversation_id`；单聊自动回复使用顶层 `sender_open_dingtalk_id`。
 - 已读事件直接读取 `reader/reader_open_dingtalk_id/read_time`；撤回事件读取 `recaller/recaller_open_dingtalk_id/recall_time`。
 - 表情回应事件直接读取 `operator/operator_open_dingtalk_id/reaction_name/reaction_text/operation_type/operation_time`。
@@ -136,7 +136,7 @@ dws event stop --all --yes
 - 正常动作事件输出不含内部 `payload/uid/corpid/clientId/filterSubId/bizid`；原始排查才使用 `-f raw` 或 `--debug-raw-events`。
 - 自己发的消息不作为事件回来（`isSelfLoop` 过滤）；自发验证会看到 0 事件，测试投递使用别人或机器人发消息。
 - `--jq <表达式>` 可进一步过滤或投影扁平输出。
-- `--debug-raw-events` 仅用于服务端联调，正常消费不要使用。
+- `--debug-raw-events` 仅用于服务端联调，正常消费不要使用；它和 `--flatten` 互斥，`-f raw` 也不能与 `--flatten` 同时使用。
 
 ## Troubleshooting
 

skills/multi/dingtalk-agoal/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 > 命令参考：[agoal.md](references/agoal.md)。

skills/multi/dingtalk-aisearch/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-aitable/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the root `dws` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-attendance/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-calendar/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-chat/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-contact/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-devdoc/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。
 
 

skills/multi/dingtalk-ding/SKILL.md

@@ -16,8 +16,6 @@ metadata:
 
 > **PREREQUISITE:** Read the `dws-shared` skill first for auth, global flags, product routing, URL preflight, error codes, and safety rules. The `dws` binary must be on PATH.
 
-<!-- SAFETY_PREAMBLE_INJECT -->
-
 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。