Merge pull request #859 from DingTalk-Real-AI/codex/changelog-v1.0.56

docs: seal v1.0.56 changelog
2026-08-04 10:05:35 +08:00 · 2026-08-04 10:00:32 +08:00 · 2026-08-04 01:55:53 +00:00 · 2026-08-04 09:46:33 +08:00 · 2026-08-04 09:35:44 +08:00 · 2026-08-04 09:29:17 +08:00
70 changed files with 6712 additions and 386 deletions
@@ -6,6 +6,88 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th

 ## [Unreleased]

+## [1.0.56] - 2026-08-04
+
+This stable release promotes the fully delivered `v1.0.56-beta.4` baseline.
+It includes PR #852's resilient multipart Drive download implementation,
+together with the v1.0.56 beta-line command, Schema, Skill, and runtime
+improvements already validated through the prerelease channel.
+
+### Added
+
+- **Resilient multipart Drive downloads** (#852) — `drive download` and
+  `drive download-version` support parallel chunk transfer, Range probing,
+  fingerprint-validated checkpoint resume, automatic 401/403 credential
+  refresh, and graceful interruption with checkpoint preservation.
+
+## [1.0.56-beta.4] - 2026-08-04
+
+This beta adds PR #852 on top of v1.0.56-beta.3. It makes Drive downloads
+resilient for large files through parallel transfer, validated resumable
+checkpoints, and automatic credential refresh.
+
+### Added
+
+- **Multipart Drive downloads** (#852) — adds `--part-size`, `--parallel`, and
+  `--no-resume` to `drive download` and `drive download-version`. Files above
+  the part-size threshold use a Range probe and parallel chunks, resume from a
+  fingerprint-validated checkpoint, refresh credentials on 401/403, and keep
+  the checkpoint when Ctrl+C interrupts a transfer.
+
+## [1.0.56-beta.3] - 2026-08-03
+
+This beta adds PRs #846 and #851 on top of v1.0.56-beta.2. It adds a
+service-provided Aitable workflow-editing reference command and makes local
+event-bus IPC reliable on shared filesystems by placing Unix sockets in a
+validated private runtime directory.
+
+### Added
+
+- **Aitable workflow editing reference** (#851) — adds `dws aitable workflow edit-example`, a parameter-free read command that returns the service-provided workflow editing documentation and `workflow-dsl/v1` examples through `aitable/edit_workflow_example`.
+
+### Fixed
+
+- **Event bus sockets on shared filesystems** (#846) — Unix event buses now place their local IPC socket in a private per-user runtime directory (`XDG_RUNTIME_DIR` when available, otherwise a `0700` per-UID directory under the system temporary directory) while retaining locks, metadata, logs, and subscription state in the configured Workdir. Listener and dial paths validate directory ownership and permissions before use. This prevents `dws event consume` from failing with `bind: errno 524` when `~/.dws` is hosted on NFS, CSI, FUSE, or another filesystem that does not support Unix Domain Sockets without exposing the socket directly in a shared `/tmp` root. When `XDG_RUNTIME_DIR` is unavailable, the per-UID directory name is deterministic: ownership validation prevents endpoint hijacking, but another local user can pre-create the directory to deny service; multi-user deployments should provide a private `XDG_RUNTIME_DIR`.
+
+## [1.0.56-beta.2] - 2026-07-30
+
+This beta adds PRs #831 and #835 on top of v1.0.56-beta.1. It separates
+Agent Product observability and IM display identity from the stable
+edition-owned PAT and routing identity, and reduces common-path Skill context
+loading without changing the public command or Runtime Schema surface.
+
+### Changed
+
+- **Agent Product identity separation** (#831) — sends `DWS_AGENT_PRODUCT` through the new `x-dws-agent-product` observability Header and uses a valid non-empty value for the IM `clawType` display label whenever `--ai-tag` is enabled. Because `--ai-tag` defaults to `true`, callers that set `DWS_AGENT_PRODUCT` change the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls preserve their existing wire shape by sending an empty IM `clawType`, while shortcut calls omit the argument. Unset or empty Product values omit the Header and preserve the active edition's IM display default.
+- **Agent Host dimension convention** (#831) — new integrations should send the runtime form (`cloud` or `desktop`) through `DWS_AGENT_HOST` and report the product separately through `DWS_AGENT_PRODUCT`. Legacy combined labels such as `qwenwork_cloud` remain syntactically valid for compatibility.
+- **Reduced common-path Skill context** (#835) — keeps the complete 97-command Chat Shortcut inventory in Runtime Catalog and leaf Schema while routing common intents through compact Skill tables and references. When an exact command path is already known, the mono Skill no longer requires eager loading of a complete product reference. The generated Skill policy now detects drift, forced full-reference loading, and context-budget regressions; the common Chat plus shared activation estimate drops from 7,301 to 4,771 `o200k_base` tokens without changing the 845-tool Schema surface.
+
+### Fixed
+
+- **Stable PAT/routing identity** (#831) — restores the CLI-emitted open-source HTTP `claw-type` and PAT `hostControl.clawType` to the edition-fixed `openClaw` value. `DWS_AGENT_PRODUCT` no longer changes those wire values, and the client continues to derive PAT, authentication, routing, and Discovery behaviour from the existing independent signals.
+- **Portable generated Skill validation** (#835) — resolves the mono Skill name by scanning upward from the generated target, keeping `--check` independent of the repository checkout path and preventing false drift failures when an ancestor directory resembles a Skill name.
+
+## [1.0.56-beta.1] - 2026-07-30
+
+This beta starts the v1.0.56 line on top of v1.0.55 and packages PRs #817,
+#806, and #834, together with release-validation fixes #838 and #839. It closes
+the remaining Agent-visible IM shortcut gaps, introduces reviewed
+command-scoped parameter normalization without guessing business identifiers
+or values, and prevents deterministic personal-event subscription failures
+from becoming unbounded retry storms.
+
+### Added
+
+- **Complete IM shortcut workflows** (#817) — publishes the previously excluded `+chat-messages`, `+messages-send`, `+messages-send-card`, `+search-msg`, and `+thread-replies` shortcuts in Runtime Schema. Unified send, streaming-card delivery, advanced search, thread replies, and opt-in resource downloads now share reviewed parameters, selection guidance, and runtime-aligned safety semantics.
+- **Reviewed parameter concept normalization** (#806) — adds a closed parameter-concept dictionary and generated command-level alias table, covering reviewed IM synonyms while preserving the boundaries between group, conversation, user, open-user, cursor, and paging identifiers.
+
+### Fixed
+
+- **Message delivery and resource handling** (#817) — resolves direct recipients through exact contact search, preserves rich and nested message resources, avoids same-name download overwrites, and prevents read shortcuts from silently returning empty results on non-interactive input.
+- **Parameter parsing safety** (#806) — rejects ambiguous, blocked, or conflicting aliases before dispatch, normalizes explicit boolean values such as `--dry-run false`, and keeps internal pre-parse handler details out of user-visible errors.
+- **Personal-event subscription retry safety** (#834) — adds cross-process attempt claims, deterministic backoff and jitter, `Retry-After` handling, terminal holds, compare-and-swap completion, and fail-closed state handling across all public personal-event subscriptions, preventing deterministic failures from causing unbounded callback retries.
+- **Scoped CI and release validation reliability** (#838, #839) — keeps scoped coverage aligned with intentionally skipped supporting profiles, gives focused race and Multi-profile E2E suites enough time for the current `internal/app` workload, and preserves hidden E2E diagnostics on failure.
+
 ## [1.0.55-beta.8] - 2026-07-30

 This beta revalidates the `v1.0.55-beta.7` product baseline through a complete
@@ -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.55-beta.8"
+  version "1.0.56-beta.4"
  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.55-beta.8/dws-darwin-arm64.tar.gz"
-      sha256 "07fabf720fa98f82c56027df703a3ad3f0aec16c957ea684047928f9f74fa00f"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.4/dws-darwin-arm64.tar.gz"
+      sha256 "f1f9b6394137edbd0b08d632aab34e92a0f3f81d80107a47de1bec9b384f0515"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-darwin-amd64.tar.gz"
-      sha256 "fbec64dc5c3463a04de9720ffb1fd247196e619ea81b976b47ecbf751a17fb72"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.4/dws-darwin-amd64.tar.gz"
+      sha256 "cd3c64d20723c420e2490405d0bf8eecfd7e2b8fc352f63f23de5847a1d38f55"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-linux-arm64.tar.gz"
-      sha256 "f111cdffef0188ddf954d2174fa0d318069bcec80104775483f13f645aa8089b"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.4/dws-linux-arm64.tar.gz"
+      sha256 "910918d88074534e680a2e320d3cb364ad092e96b9c422f9e75d11c9c0815dd8"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-linux-amd64.tar.gz"
-      sha256 "d69475b7f3cec4bad4c051834df22fbfadfa7075b82347e6ca7490f67d71d0b1"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.4/dws-linux-amd64.tar.gz"
+      sha256 "172fe0d84443be953d0c6f2c2433540e4b972fbe7776cff1417ec9c73723552b"
    end
  end

  resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-skills.zip"
-    sha256 "be8c9267704cfef1319fc9cd2fcba5aebe45b670b4dc37d3dae15f65523356f8"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.4/dws-skills.zip"
+    sha256 "a3457befe858cbf3fe85848428b630bfd3a5f626256ed6b49415267948915152"
  end

  def install
@@ -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 test-auth-legacy-compat 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 fetch-mcp-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 test-auth-legacy-compat 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 skill-context-budget cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema generate-schema-agent-metadata fetch-mcp-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

@@ -30,6 +30,7 @@ help:
 	@printf "  make reset-interface-baseline - DANGEROUS: replace all CLI compatibility history\n"
 	@printf "  make schema-compatibility BASE_REF=<ref> - Check the complete Schema contract against the PR merge-base\n"
 	@printf "  make skill-command-integrity - Check dws commands referenced by skills exist\n"
+	@printf "  make skill-context-budget - Check generated Skill drift and common-path context budgets\n"
 	@printf "  make cli-smoke     - Verify help for every public top-level command\n"
 	@printf "  make mock-mcp-smoke - Verify HTTP and stdio MCP request/response transport\n"
 	@printf "  make test-schema-agent-examples - Contract-check all Agent examples and dry-run the eligible subset\n"
@@ -84,6 +85,7 @@ fmt:
 policy: test-auth-legacy-compat
 	@mkdir -p "$(POLICY_GOTMPDIR)"
 	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
+	@$(POLICY_ENV) ./scripts/policy/check-skill-context-budget.sh
 	@$(POLICY_ENV) ./scripts/policy/check-schema-command-registry.sh
 	@$(POLICY_ENV) ./scripts/policy/check-command-surface.sh --strict
 	@$(POLICY_ENV) ./scripts/policy/check-generated-drift.sh
@@ -121,6 +123,9 @@ schema-compatibility:
 skill-command-integrity:
 	@./scripts/policy/check-skill-commands.sh

+skill-context-budget:
+	@./scripts/policy/check-skill-context-budget.sh
+
 cli-smoke:
 	@./scripts/policy/check-cli-smoke.sh

@@ -5,8 +5,8 @@
 | Variable | Purpose / 用途 |
 |---------|---------|
 | `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
-| `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent through the existing HTTP `claw-type` header (for example `qwenwork`). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9_-]*$`. Unset or empty values preserve the edition default (`openClaw` in the open-source build). / 可选、由调用方声明的 Agent 产品标识，经校验后覆盖 HTTP `claw-type` 请求头；未设置或为空时保持当前发行版默认值 |
-| `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[a-z0-9][a-z0-9_-]*$`; unset values are omitted. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送；未设置时省略 |
+| `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent as `x-dws-agent-product` (for example `qwenwork`) for downstream logs/BI and used as the IM `clawType` display label when `--ai-tag` is enabled. `--ai-tag` defaults to `true`, so a configured Product changes the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls send an empty `clawType`, while shortcut calls omit the argument. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9_-]*$`. Unset or empty values omit the Header and use the edition's IM display default. This client never uses Product to change the separate HTTP `claw-type` PAT/routing label. / 可选、由调用方声明的 Agent 产品标识，经校验后作为 `x-dws-agent-product` 发送，并用于 IM 小尾巴；`--ai-tag` 默认为 `true`，因此配置 Product 后默认会改变展示标签。使用 `--ai-tag=false` 时，原生 `chat message send` / `reply` 发送空的 `clawType`，shortcut 调用则省略该参数。未设置时省略请求头且 IM 使用发行版默认值；本客户端不会用 Product 修改独立的 HTTP `claw-type` |
+| `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`) for downstream logs/BI. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[a-z0-9][a-z0-9_-]*$`; unset values are omitted. This client does not use Host for PAT, authentication, Discovery, or MCP endpoint selection. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送给下游日志/BI；本客户端不使用该值进行 PAT、鉴权、Discovery 或 MCP 端点选择，未设置时省略 |
 | `DWS_<PRODUCT>_MCP_URL` | Override a product MCP endpoint for local development / 本地开发时覆盖指定产品 MCP endpoint |
 | `DWS_CLIENT_ID` | OAuth client ID (DingTalk AppKey) |
 | `DWS_CLIENT_SECRET` | OAuth client secret (DingTalk AppSecret) |
@@ -14,23 +14,36 @@
 | `DWS_ALLOW_HTTP_ENDPOINTS` | Set `1` to allow HTTP for loopback during dev / 设为 `1` 允许回环地址 HTTP，仅用于开发调试 |
 | `DWS_DISABLE_KEYCHAIN` | macOS only. Set `1` to skip system Keychain for the encryption key and use file-based storage (same scheme as Linux). For sandboxed runtimes (e.g. Codex App) that block Keychain APIs. Weakens at-rest protection — DEK and ciphertext live in the same directory. / 仅 macOS。设为 `1` 时跳过系统 Keychain，密钥以文件形式存储（与 Linux 一致）。用于 Keychain API 被拦截的沙盒环境（如 Codex App）。代价是 DEK 与密文同目录，保护强度低于默认方案 |

-### Agent Product and Host trust model / Agent 产品与运行形态的信任模型
+### Agent Product, Host, and `claw-type` / Agent 产品、运行形态与 `claw-type`

-`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared selection and
-observation signals. They are not credentials, attestations, or proof of the
-calling host's identity. DingTalk services may record them for logs/BI and may
-combine supported values with separately authenticated context for PAT
-compatibility, PAT identity/source derivation, or Discovery eligibility. A
-service must allowlist supported values and must never grant access, bypass
-authentication, or skip authorization solely because either Header claims a
-particular product or runtime form. They are not used to select ordinary MCP
-tool endpoints.
+`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared observation
+signals. They are not credentials, attestations, or proof of the calling
+host's identity. The CLI validates and emits `x-dws-agent-product` and
+`x-dws-agent-host`, but does not use either value to derive its authentication,
+PAT mode, Discovery behaviour, or ordinary MCP endpoint selection. Downstream
+services own and must document their own contracts for these caller-declared
+Headers.

-`DWS_AGENT_PRODUCT` controls only the HTTP `claw-type` Header. The similarly
-named `clawType` tool argument on IM send operations is an independent
-message-display axis used for the “Send from AI” label. It remains controlled
-by the active edition's `ClawTypeValue` and `--ai-tag`; changing
-`DWS_AGENT_PRODUCT` does not change that message label.
+Service integrators should treat both Headers as untrusted input, allowlist
+expected values, and should not grant access, bypass authentication, or skip
+authorization solely because a Header claims a particular Product or Host.
+
+The HTTP `claw-type` Header is a separate, edition-fixed PAT/routing label:
+`openClaw` in the open-source build. `DWS_AGENT_PRODUCT` never changes it or
+PAT `hostControl.clawType`. On IM send/reply operations with `--ai-tag`,
+however, a valid non-empty Product value is used as the `clawType` tool
+argument so the delivered message carries the matching “Send from AI” label.
+Because `--ai-tag` defaults to `true`, this display change is enabled by
+default for callers that set Product. With `--ai-tag=false`, native
+`chat message send` / `reply` calls serialize `clawType: ""`, while shortcut
+calls omit the argument; this client does not assume downstream services treat
+an empty value and an absent key as equivalent. The display-value precedence
+when the tag is enabled is valid non-empty `DWS_AGENT_PRODUCT`, then the active
+edition's `ClawTypeValue`, then `openClaw`.
+
+Do not set arbitrary Product values that the target downstream and IM services
+have not explicitly enabled; an unknown value may be ignored or may not render
+the expected label.

 For QwenWork, report the dimensions separately:

@@ -39,16 +52,25 @@ DWS_AGENT_PRODUCT=qwenwork
 DWS_AGENT_HOST=cloud       # or desktop
 ```

-Do not set arbitrary product values that the target service has not explicitly
-enabled. Older combined Host labels such as `qwenwork_cloud` still satisfy the
-generic syntax for compatibility, but new integrations should use the
-two-dimensional convention above.
+Older combined Host labels such as `qwenwork_cloud` still satisfy the generic
+syntax for compatibility, but new integrations should use the two-dimensional
+convention above.

 `DWS_AGENT_PRODUCT` 和 `DWS_AGENT_HOST` 均由调用方声明，不是认证凭据，也不能证明
-真实宿主身份。服务端可以在独立认证上下文中将受支持值用于日志/BI、PAT 兼容策略、
-PAT 身份/来源派生或 Discovery 准入，但不得仅凭这两个 Header 放权、绕过认证或跳过
-授权。HTTP `claw-type` 与 IM 消息发送参数 `clawType` 是两个独立维度；后者仅控制
-“Send from AI”展示，仍由发行版 `ClawTypeValue` 和 `--ai-tag` 决定。
+真实宿主身份。CLI 只负责校验并发送 `x-dws-agent-product` 与 `x-dws-agent-host`，
+不会用它们派生本客户端的鉴权、PAT 模式、Discovery 行为或 MCP 端点；下游服务的
+使用契约由对应服务自行定义和说明。HTTP `claw-type` 是发行版固定的 PAT/路由标签，
+开源版固定为 `openClaw`，不受 `DWS_AGENT_PRODUCT` 影响。
+
+服务集成方应将这两个请求头视为不可信输入并对白名单值做校验，不应仅因请求头声明了
+某个 Product 或 Host 就授予访问、绕过认证或跳过鉴权。
+
+`--ai-tag` 默认为 `true`，因此配置合法非空 Product 后，默认发送的 IM 工具参数
+`clawType` 及小尾巴会随之改变。传入 `--ai-tag=false` 时，原生
+`chat message send` / `reply` 会发送 `clawType: ""`，shortcut 调用则省略该参数；
+本客户端不假定下游会将空值与键缺失等价处理。启用小尾巴时，展示值优先级依次为
+`DWS_AGENT_PRODUCT`、当前发行版的 `ClawTypeValue`、`openClaw`。不要传入目标下游及
+IM 服务未明确支持的 Product 值，否则可能被忽略或无法展示预期标签。

 ## Exit Codes / 退出码

@@ -33,7 +33,7 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:        envDWSAgentHost,
 		Category:    configmeta.CategoryExternal,
-		Description: "调用 DWS 的 Agent 运行形态标识；服务端可结合产品用于观测和 PAT 兼容策略",
+		Description: "调用 DWS 的 Agent 运行形态标识；作为 x-dws-agent-host 发送供下游观测，本客户端不使用该值改变 PAT、鉴权或路由",
 		Example:     "cloud",
 	})
 }
@@ -24,8 +24,8 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:         agentproduct.EnvName,
 		Category:     configmeta.CategoryExternal,
-		Description:  "调用方声明的 Agent 产品标识；覆盖 HTTP claw-type，但不是认证凭据",
-		DefaultValue: "由当前发行版决定",
+		Description:  "调用方声明的 Agent 产品标识；作为 x-dws-agent-product 发送并用于 IM 小尾巴，本客户端不使用该值改变 HTTP claw-type/PAT",
+		DefaultValue: "未设置（请求头省略，IM 使用当前发行版默认值）",
 		Example:      "qwenwork",
 	})
 }
@@ -47,25 +47,26 @@ func invalidAgentProductError() error {
 	)
 }

-// resolveEffectiveAgentProduct resolves the request-header identity with one
-// shared precedence rule: a valid non-empty runtime override wins, otherwise
-// the edition's MergeHeaders value wins, otherwise the OSS default is used.
-// Invalid runtime input falls back here for library callers that bypass root
-// validation; normal CLI execution rejects it before network access.
-func resolveEffectiveAgentProduct(headers map[string]string) string {
-	fallback := edition.DefaultOSSClawType
-	if value := headers[agentproduct.HeaderName]; value != "" {
-		fallback = value
+// resolveEditionClawType resolves the fixed routing/PAT identity supplied by
+// the active edition. DWS_AGENT_PRODUCT is deliberately not consulted.
+func resolveEditionClawType(headers map[string]string) string {
+	if value := headers["claw-type"]; value != "" {
+		return value
 	}
-	value, err := agentproduct.ResolveFromEnv(fallback)
-	if err != nil {
-		return fallback
-	}
-	return value
+	return edition.DefaultOSSClawType
 }

-func applyAgentProductOverride(headers map[string]string) map[string]string {
-	value := resolveEffectiveAgentProduct(headers)
+// applyAgentProductHeader injects only a valid, non-empty caller-declared
+// product. Invalid values are omitted on library paths that bypass root
+// validation; normal CLI execution rejects them before network access.
+func applyAgentProductHeader(headers map[string]string) map[string]string {
+	value, err := agentproduct.ResolveFromEnv("")
+	if err != nil || value == "" {
+		if headers != nil {
+			delete(headers, agentproduct.HeaderName)
+		}
+		return headers
+	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}
@@ -26,13 +26,16 @@ import (
 	"github.com/spf13/cobra"
 )

-func TestUnsetAgentProductKeepsOpenSourceDefault(t *testing.T) {
+func TestUnsetAgentProductOmitsHeaderAndKeepsOpenSourceClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "")

 	headers := resolveIdentityHeaders()
-	if got := headers[agentproduct.HeaderName]; got != edition.DefaultOSSClawType {
-		t.Fatalf("%s = %q, want %q", agentproduct.HeaderName, got, edition.DefaultOSSClawType)
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 	}
 }

@@ -59,38 +62,46 @@ func TestParseAgentProductReturnsStableValidationError(t *testing.T) {
 	}
 }

-func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
+func TestResolveIdentityHeadersSeparatesAgentProductFromClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())

 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
+			headers[agentproduct.HeaderName] = "merge-product-must-not-win"
 			headers["x-edition-header"] = "preserved"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "credential-must-not-win"
+			headers[agentproduct.HeaderName] = "credential-product-must-not-win"
 			headers["x-enterprise-header"] = "preserved"
 			return headers
 		},
 	})

-	t.Run("unset keeps edition default", func(t *testing.T) {
+	t.Run("unset omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 		}
 	})

-	t.Run("valid override is final", func(t *testing.T) {
+	t.Run("valid Product is final without changing claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, " qwenwork ")
 		headers := resolveIdentityHeaders()
 		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 		}
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
 		if got := headers["x-edition-header"]; got != "preserved" {
 			t.Fatalf("edition header = %q, want preserved", got)
 		}
@@ -102,21 +113,48 @@ func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
 		}
 	})

-	t.Run("invalid library input falls back to edition", func(t *testing.T) {
+	t.Run("invalid library input omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "qwen work")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("invalid Product must omit %s", agentproduct.HeaderName)
 		}
 	})
 }

-func TestApplyAgentProductOverrideAllocatesHeaders(t *testing.T) {
-	t.Setenv(agentproduct.EnvName, "qwenwork")
+func TestApplyAgentProductHeader(t *testing.T) {
+	t.Run("valid value allocates headers", func(t *testing.T) {
+		t.Setenv(agentproduct.EnvName, "qwenwork")

-	headers := applyAgentProductOverride(nil)
-	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
-		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		headers := applyAgentProductHeader(nil)
+		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
+			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		}
+	})
+
+	for _, tc := range []struct {
+		name  string
+		value string
+	}{
+		{name: "empty value", value: ""},
+		{name: "invalid value", value: "qwen work"},
+	} {
+		t.Run(tc.name+" removes inherited header", func(t *testing.T) {
+			t.Setenv(agentproduct.EnvName, tc.value)
+			headers := applyAgentProductHeader(map[string]string{
+				agentproduct.HeaderName: "must-not-leak",
+				"x-preserved":           "yes",
+			})
+			if _, ok := headers[agentproduct.HeaderName]; ok {
+				t.Fatalf("%s must be omitted", agentproduct.HeaderName)
+			}
+			if got := headers["x-preserved"]; got != "yes" {
+				t.Fatalf("x-preserved = %q, want yes", got)
+			}
+		})
 	}
 }

@@ -167,17 +205,17 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	hookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
 			hookCalled = true
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "enterprise-default"
 			return headers
 		},
 	})

-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")
 	if got := effectiveClawType(); got != "wukong" {
 		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
@@ -186,7 +224,7 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	}
 }

-func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
+func TestAgentProductControlsObservabilityHeaderAndMessageClawTypeOnly(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")

@@ -195,20 +233,24 @@ func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
 	edition.Override(&edition.Hooks{
 		ClawTypeValue: "message-brand",
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})

-	if got := resolveIdentityHeaders()[agentproduct.HeaderName]; got != "qwenwork" {
+	headers := resolveIdentityHeaders()
+	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("HTTP %s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
-	if got := edition.ClawType(); got != "message-brand" {
-		t.Fatalf("message clawType = %q, want message-brand", got)
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("HTTP claw-type = %q, want wukong", got)
+	}
+	if got := edition.ClawType(); got != "qwenwork" {
+		t.Fatalf("message clawType = %q, want qwenwork", got)
 	}
 }

-func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *testing.T) {
+func TestResolveIdentityHeadersRestoresIdentityAfterNilCredentialHeaders(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")

@@ -218,7 +260,7 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	credentialHookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(map[string]string) map[string]string {
@@ -234,25 +276,49 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("claw-type = %q, want wukong", got)
+	}
 }

-func TestEffectiveClawTypeUsesAgentProductOverride(t *testing.T) {
+func TestResolveIdentityHeadersRestoresDefaultsAfterNilMergeHeaders(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(agentproduct.EnvName, "")
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	edition.Override(&edition.Hooks{
+		MergeHeaders: func(map[string]string) map[string]string {
+			return nil
+		},
+	})
+
+	headers := resolveIdentityHeaders()
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
+	}
+}
+
+func TestEffectiveClawTypeIgnoresAgentProduct(t *testing.T) {
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})

 	t.Setenv(agentproduct.EnvName, "qwenwork")
-	if got := effectiveClawType(); got != "qwenwork" {
-		t.Fatalf("effectiveClawType() = %q, want qwenwork", got)
+	if got := effectiveClawType(); got != "wukong" {
+		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
 	t.Setenv(authpkg.AgentCodeEnv, "agent-code")
-	if got := apperrors.HostControlBlock()["clawType"]; got != "qwenwork" {
-		t.Fatalf("hostControl.clawType = %q, want qwenwork", got)
+	if got := apperrors.HostControlBlock()["clawType"]; got != "wukong" {
+		t.Fatalf("hostControl.clawType = %q, want wukong", got)
 	}

 	t.Setenv(agentproduct.EnvName, "")
@@ -569,9 +569,9 @@ func handlePatAuthCheck(
 	// In host-controlled PAT mode (driven solely by DINGTALK_DWS_AGENTCODE),
 	// or when flowId is absent, the CLI returns machine-readable JSON to
 	// stderr and leaves UI/polling/retry to the host. `claw-type` is NOT
-	// used for this decision — it is only forwarded on the wire via
-	// the edition default / DWS_AGENT_PRODUCT override and surfaced in
-	// hostControl for traceability.
+	// used for this decision — its edition-fixed value is forwarded on the
+	// wire and surfaced in hostControl for traceability. DWS_AGENT_PRODUCT
+	// does not affect this PAT contract.
 	if hostOwnedPAT || patData.Data.FlowID == "" {
 		if hostOwnedPAT {
 			return executor.Result{}, &apperrors.PATError{RawJSON: enrichPATErrorForHostControl(patErr.RawJSON)}
@@ -1007,11 +1007,11 @@ func TestHandlePatAuthCheck_HostControlledFlowIDPassthrough(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", tmpDir)
 	// Host-owned decision: driven ONLY by DINGTALK_DWS_AGENTCODE.
 	// DINGTALK_AGENT is set to demonstrate it does NOT leak into
-	// hostControl.clawType. With no DWS_AGENT_PRODUCT override the
-	// open-source edition default remains "openClaw".
+	// hostControl.clawType. DWS_AGENT_PRODUCT is also set to demonstrate
+	// that Product does not change the open-source fixed "openClaw" value.
 	t.Setenv(authpkg.AgentCodeEnv, "agt-sales")
 	t.Setenv("DINGTALK_AGENT", "sales-copilot")
-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")

 	mock := &mockRunner{
 		runFunc: func(ctx context.Context, inv executor.Invocation) (executor.Result, error) {
@@ -29,9 +29,8 @@ import (
 //   - Host-owned is triggered iff DINGTALK_DWS_AGENTCODE is non-empty.
 //   - When triggered, `clawType` in the emitted hostControl block MUST be the
 //     exact value the CLI actually injects on the wire. Each edition supplies
-//     its existing default and an optional valid DWS_AGENT_PRODUCT overrides
-//     it. Invalid input falls back here for library compatibility; root command
-//     execution rejects it before network access.
+//     its fixed value; DWS_AGENT_PRODUCT is a separate observability and IM
+//     message-display signal and never affects this PAT value.
 //   - When DINGTALK_DWS_AGENTCODE is empty the provider returns "" so
 //     HostControlBlock yields nil and no hostControl block is emitted.
 func init() {
@@ -59,5 +58,5 @@ func effectiveClawType() string {
 			headers = h.MergeHeaders(headers)
 		}
 	}
-	return resolveEffectiveAgentProduct(headers)
+	return resolveEditionClawType(headers)
 }
@@ -1005,9 +1005,8 @@ func resolveIdentityHeaders() map[string]string {

 	// Inject environment variable based headers for MCP gateway tracking.
 	// DINGTALK_AGENT, if set by the caller, is forwarded verbatim as the
-	// x-dingtalk-agent header. It does NOT influence claw-type (which comes
-	// from the edition default plus the explicit DWS_AGENT_PRODUCT override)
-	// and it does NOT influence the host-owned PAT decision (driven solely by
+	// x-dingtalk-agent header. It does NOT influence the edition-fixed
+	// claw-type or the host-owned PAT decision (driven solely by
 	// DINGTALK_DWS_AGENTCODE).
 	sessionID := os.Getenv(envDingtalkSessionID)
 	if sessionID == "" {
@@ -1068,22 +1067,30 @@ func resolveIdentityHeaders() map[string]string {
 	if fn := edition.Get().MergeHeaders; fn != nil {
 		headers = fn(headers)
 	}
-	// Resolve the Agent Product before credential injection. The credential
-	// hook has a separate contract and must not be able to replace the
-	// request identity used by PAT hostControl serialization.
-	headers = applyAgentProductOverride(headers)
-	agentProduct := headers[agentproduct.HeaderName]
+	if headers == nil {
+		headers = make(map[string]string)
+	}
+
+	// claw-type is the edition-fixed routing/PAT identity. Agent Product is a
+	// separate caller-declared observability and IM-display dimension.
+	clawType := resolveEditionClawType(headers)
+	headers["claw-type"] = clawType
+	headers = applyAgentProductHeader(headers)
+	agentProduct, hasAgentProduct := headers[agentproduct.HeaderName]
 	if fn := edition.Get().EnterpriseCredentialHeaders; fn != nil {
 		headers = fn(headers)
 	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}
-	// DWS_AGENT_PRODUCT is the explicit caller override for the existing
-	// claw-type wire header. Reassert the resolved product after credential
-	// injection so that hook cannot alter identity. Invalid values are ignored
-	// on this best-effort library path; root execution rejects them earlier.
-	headers[agentproduct.HeaderName] = agentProduct
+	// Credential hooks cannot alter either identity dimension. Restore the
+	// fixed claw-type and the validated Product Header (or its absence).
+	headers["claw-type"] = clawType
+	if hasAgentProduct {
+		headers[agentproduct.HeaderName] = agentProduct
+	} else {
+		delete(headers, agentproduct.HeaderName)
+	}
 	return headers
 }

@@ -37075,6 +37075,265 @@
        "用户明确要求停止某自动化工作流时"
      ]
    },
+    "aitable workflow edit-example": {
+      "agent_summary": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+      "agent_summary_source": "dws-agent-selection/aitable",
+      "availability": "available",
+      "avoid_when": [
+        "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+      ],
+      "confirmation": "not_required",
+      "effect": "read",
+      "effect_source": "agent-hint",
+      "examples": [
+        "dws aitable workflow edit-example"
+      ],
+      "field_provenance": {
+        "agent_summary": {
+          "value": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "candidates": [
+            {
+              "value": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。"
+            }
+          ]
+        },
+        "availability": {
+          "value": "available",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "available",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "avoid_when": {
+          "value": [
+            "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+          ],
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "candidates": [
+            {
+              "value": [
+                "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+              ],
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。"
+            }
+          ]
+        },
+        "confirmation": {
+          "value": "not_required",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "not_required",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "effect": {
+          "value": "read",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "read",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "examples": {
+          "value": [
+            "dws aitable workflow edit-example"
+          ],
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "candidates": [
+            {
+              "value": [
+                "dws aitable workflow edit-example"
+              ],
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。"
+            }
+          ]
+        },
+        "idempotency": {
+          "value": "idempotent",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "idempotent",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "interface_mode": {
+          "value": "composite",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "composite",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "interface_reason": {
+          "value": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "interface_ref": {
+          "value": null,
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "interface_disposition_matrix",
+          "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
+          "candidates": [
+            {
+              "value": null,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "final interface mode composite forbids a direct MCP interface_ref"
+            }
+          ]
+        },
+        "reviewed": {
+          "value": true,
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            },
+            {
+              "value": true,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": false,
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。"
+            }
+          ]
+        },
+        "risk": {
+          "value": "low",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "candidates": [
+            {
+              "value": "low",
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry."
+            }
+          ]
+        },
+        "use_when": {
+          "value": [
+            "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+          ],
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "candidates": [
+            {
+              "value": [
+                "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+              ],
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "precedence": "reviewed_explicit",
+              "selected": true,
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。"
+            }
+          ]
+        }
+      },
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+      "reviewed": true,
+      "risk": "low",
+      "source_refs": [
+        "cobra-help:dws aitable workflow edit-example --help",
+        "internal/cli/schema_command_registry.json#aitable.workflow_edit_example",
+        "internal/cli/schema_hints/metadata/aitable.json",
+        "internal/cli/schema_hints/selection/aitable.json",
+        "mcp-contract:aitable/edit_workflow_example",
+        "skills/mono/references/products/aitable/aitable-workflow.md"
+      ],
+      "use_when": [
+        "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+      ]
+    },
    "aitable workflow enable": {
      "agent_summary": "启用工作流。",
      "agent_summary_source": "dws-agent-selection/aitable",
@@ -1,17 +1,17 @@
 {
  "version": 1,
-  "source_hash": "sha256:7484b82d1ca793a6129acfaa192ff08fc0864d47a6e75ecd16d8e7fa32857e16",
-  "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
+  "source_hash": "sha256:f3d5e5d6ca3c613b1d004d68eca89679d0f8cffe882d7fed0fbb1bcef078fdc9",
+  "surface_hash": "sha256:41044fe1b6723564c40d684381ac6d6f23c4dfd58f9769350f02f223f02fa894",
  "coverage": {
    "surface_products": 26,
    "products_with_metadata": 26,
-    "surface_tools": 845,
-    "tools_with_metadata": 845,
-    "tools_with_agent_summary": 845,
-    "tools_with_use_when": 845,
-    "tools_with_avoid_when": 845,
-    "tools_with_examples": 845,
-    "tools_with_interface_mode": 845,
+    "surface_tools": 846,
+    "tools_with_metadata": 846,
+    "tools_with_agent_summary": 846,
+    "tools_with_use_when": 846,
+    "tools_with_avoid_when": 846,
+    "tools_with_examples": 846,
+    "tools_with_interface_mode": 846,
    "unmatched_skill_tools": 122,
    "unreviewed_skill_tools": 11
  },
@@ -1,11 +1,11 @@
 {
  "version": 1,
-  "source_hash": "sha256:7484b82d1ca793a6129acfaa192ff08fc0864d47a6e75ecd16d8e7fa32857e16",
-  "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
+  "source_hash": "sha256:f3d5e5d6ca3c613b1d004d68eca89679d0f8cffe882d7fed0fbb1bcef078fdc9",
+  "surface_hash": "sha256:41044fe1b6723564c40d684381ac6d6f23c4dfd58f9769350f02f223f02fa894",
  "source_files": 160,
  "hint_files": 54,
  "hint_products": 43,
-  "hint_tools": 1842,
+  "hint_tools": 1844,
  "interface_metadata": {
    "source": "mcp-tools-list+cli-registry",
    "revision": "4574f7022c32cf4c033e9b7b4156e2fec815fed8",
@@ -29,13 +29,13 @@
  "coverage": {
    "surface_products": 26,
    "products_with_metadata": 26,
-    "surface_tools": 845,
-    "tools_with_metadata": 845,
-    "tools_with_agent_summary": 845,
-    "tools_with_use_when": 845,
-    "tools_with_avoid_when": 845,
-    "tools_with_examples": 845,
-    "tools_with_interface_mode": 845,
+    "surface_tools": 846,
+    "tools_with_metadata": 846,
+    "tools_with_agent_summary": 846,
+    "tools_with_use_when": 846,
+    "tools_with_avoid_when": 846,
+    "tools_with_examples": 846,
+    "tools_with_interface_mode": 846,
    "unmatched_skill_tools": 122,
    "unreviewed_skill_tools": 11
  },
@@ -1,17 +1,17 @@
 {
  "version": 1,
-  "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
-  "source_hash": "sha256:ba691e70f1c232fc3378a743c3fcd34113960d30b46bffa7d1fc8b524115052c",
+  "surface_hash": "sha256:41044fe1b6723564c40d684381ac6d6f23c4dfd58f9769350f02f223f02fa894",
+  "source_hash": "sha256:00285e7f05c4ed9e9e3aa7464c7114990187dd7ffdcc9e83e64f3ec33d22d0a8",
  "catalog": {
    "agent_metadata": {
      "products_with_metadata": 26,
      "source": "embedded-skill-metadata",
-      "source_hash": "sha256:7484b82d1ca793a6129acfaa192ff08fc0864d47a6e75ecd16d8e7fa32857e16",
-      "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
+      "source_hash": "sha256:f3d5e5d6ca3c613b1d004d68eca89679d0f8cffe882d7fed0fbb1bcef078fdc9",
+      "surface_hash": "sha256:41044fe1b6723564c40d684381ac6d6f23c4dfd58f9769350f02f223f02fa894",
      "surface_products": 26,
-      "surface_tools": 845,
-      "tools_with_agent_summary": 845,
-      "tools_with_metadata": 845,
+      "surface_tools": 846,
+      "tools_with_agent_summary": 846,
+      "tools_with_metadata": 846,
      "unmatched_skill_tools": 122,
      "version": 1
    },
@@ -288,7 +288,7 @@
        "id": "aitable",
        "name": "AI 表格操作",
        "runtime": true,
-        "tool_count": 145,
+        "tool_count": 146,
        "tools": [
          {
            "agent_metadata_source": "embedded-skill-metadata",
@@ -4449,6 +4449,33 @@
              "用户明确要求停止某自动化工作流时"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+            "agent_summary_source": "dws-agent-selection/aitable",
+            "availability": "available",
+            "avoid_when": [
+              "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+            ],
+            "canonical_path": "aitable.workflow_edit_example",
+            "cli_name": "edit-example",
+            "cli_path": "aitable workflow edit-example",
+            "confirmation": "not_required",
+            "description": "返回服务端提供的 AI 表格工作流编辑文档与示例。\n可作为 workflow create / workflow update 的 workflow-dsl/v1 结构参考；此命令不需要 Base ID 或其他参数。",
+            "effect": "read",
+            "group": "workflow",
+            "idempotency": "idempotent",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+            "name": "workflow_edit_example",
+            "primary_cli_path": "aitable workflow edit-example",
+            "reviewed": true,
+            "risk": "low",
+            "title": "获取工作流编辑文档与示例",
+            "use_when": [
+              "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "启用工作流。",
@@ -26644,6 +26671,6 @@
      }
    ],
    "source": "embedded-command-catalog",
-    "tool_count": 845
+    "tool_count": 846
  }
 }
@@ -97777,6 +97777,326 @@
        "用户明确要求停止某自动化工作流时"
      ]
    },
+    "aitable.workflow_edit_example": {
+      "agent_metadata_source": "embedded-skill-metadata",
+      "agent_source_refs": [
+        "cobra-help:dws aitable workflow edit-example --help",
+        "internal/cli/schema_command_registry.json#aitable.workflow_edit_example",
+        "internal/cli/schema_hints/metadata/aitable.json",
+        "internal/cli/schema_hints/selection/aitable.json",
+        "mcp-contract:aitable/edit_workflow_example",
+        "skills/mono/references/products/aitable/aitable-workflow.md"
+      ],
+      "agent_summary": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+      "agent_summary_source": "dws-agent-selection/aitable",
+      "availability": "available",
+      "avoid_when": [
+        "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+      ],
+      "canonical_path": "aitable.workflow_edit_example",
+      "cli_name": "edit-example",
+      "cli_path": "aitable workflow edit-example",
+      "confirmation": "not_required",
+      "description": "返回服务端提供的 AI 表格工作流编辑文档与示例。\n可作为 workflow create / workflow update 的 workflow-dsl/v1 结构参考；此命令不需要 Base ID 或其他参数。",
+      "display": "AI 表格操作",
+      "effect": "read",
+      "effect_source": "agent-hint",
+      "examples": [
+        "dws aitable workflow edit-example"
+      ],
+      "field_provenance": {
+        "agent_summary": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+              "selected": true,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "value": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "value": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。"
+        },
+        "availability": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "available"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "available"
+        },
+        "avoid_when": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+              "selected": true,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "value": [
+                "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+              ]
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "value": [
+            "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+          ]
+        },
+        "canonical_path": {
+          "candidates": [
+            {
+              "precedence": "command_registry",
+              "selected": true,
+              "source": "reviewed_command_registry",
+              "source_ref": "aitable workflow edit-example",
+              "value": "aitable.workflow_edit_example"
+            }
+          ],
+          "precedence": "command_registry",
+          "resolution": "registry_identity",
+          "source": "reviewed_command_registry",
+          "source_ref": "aitable workflow edit-example",
+          "value": "aitable.workflow_edit_example"
+        },
+        "confirmation": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "not_required"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "not_required"
+        },
+        "description": {
+          "candidates": [
+            {
+              "precedence": "cobra_help",
+              "selected": true,
+              "source": "cobra_help",
+              "value": "返回服务端提供的 AI 表格工作流编辑文档与示例。\n可作为 workflow create / workflow update 的 workflow-dsl/v1 结构参考；此命令不需要 Base ID 或其他参数。"
+            }
+          ],
+          "precedence": "cobra_help",
+          "resolution": "highest_precedence",
+          "source": "cobra_help",
+          "value": "返回服务端提供的 AI 表格工作流编辑文档与示例。\n可作为 workflow create / workflow update 的 workflow-dsl/v1 结构参考；此命令不需要 Base ID 或其他参数。"
+        },
+        "effect": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "read"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "read"
+        },
+        "examples": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+              "selected": true,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "value": [
+                "dws aitable workflow edit-example"
+              ]
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "value": [
+            "dws aitable workflow edit-example"
+          ]
+        },
+        "idempotency": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "idempotent"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "idempotent"
+        },
+        "interface_mode": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "composite"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "composite"
+        },
+        "interface_reason": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command."
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command."
+        },
+        "interface_ref": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": null
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "interface_disposition_matrix",
+          "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": null
+        },
+        "reviewed": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": true
+            },
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+              "selected": false,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "value": true
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": true
+        },
+        "risk": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+              "selected": true,
+              "source": "internal/cli/schema_hints/metadata/aitable.json",
+              "value": "low"
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+          "source": "internal/cli/schema_hints/metadata/aitable.json",
+          "value": "low"
+        },
+        "title": {
+          "candidates": [
+            {
+              "precedence": "cobra_help",
+              "selected": true,
+              "source": "cobra_help",
+              "value": "获取工作流编辑文档与示例"
+            }
+          ],
+          "precedence": "cobra_help",
+          "resolution": "highest_precedence",
+          "source": "cobra_help",
+          "value": "获取工作流编辑文档与示例"
+        },
+        "use_when": {
+          "candidates": [
+            {
+              "precedence": "reviewed_explicit",
+              "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+              "selected": true,
+              "source": "internal/cli/schema_hints/selection/aitable.json",
+              "value": [
+                "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+              ]
+            }
+          ],
+          "precedence": "reviewed_explicit",
+          "resolution": "highest_precedence",
+          "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+          "source": "internal/cli/schema_hints/selection/aitable.json",
+          "value": [
+            "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+          ]
+        }
+      },
+      "group": "workflow",
+      "has_parameters": false,
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+      "is_alias": false,
+      "name": "workflow_edit_example",
+      "parameter_count": 0,
+      "parameters": {},
+      "path": "aitable.workflow_edit_example",
+      "primary_cli_path": "aitable workflow edit-example",
+      "product_id": "aitable",
+      "reviewed": true,
+      "risk": "low",
+      "source": "reviewed_command_registry",
+      "title": "获取工作流编辑文档与示例",
+      "use_when": [
+        "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+      ]
+    },
    "aitable.workflow_enable": {
      "agent_metadata_source": "embedded-skill-metadata",
      "agent_source_refs": [
@@ -5312,8 +5312,99 @@
      "is_alias": false,
      "metadata_source": "embedded-mcp-metadata",
      "name": "download_file",
-      "parameter_count": 3,
+      "parameter_count": 6,
      "parameters": {
+        "no-resume": {
+          "description": "关闭断点续传 (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "关闭断点续传 (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "关闭断点续传 (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "CLI-only transfer-layer flag controlling download resume behaviour; not an MCP interface parameter.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "noResume"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "CLI-only transfer-layer flag controlling download resume behaviour; not an MCP interface parameter.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "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"
+            }
+          },
+          "required": false,
+          "type": "boolean"
+        },
        "node": {
          "description": "文件 ID (dentryUuid) (必填)",
          "field_provenance": {
@@ -5520,6 +5611,202 @@
          "required": true,
          "type": "string"
        },
+        "parallel": {
+          "default": "4",
+          "description": "分片下载并发数，范围 1-8 (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "分片下载并发数，范围 1-8 (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "分片下载并发数，范围 1-8 (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "CLI-only transfer-layer flag controlling parallel chunk downloads; not an MCP interface parameter.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "parallel"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "CLI-only transfer-layer flag controlling parallel chunk downloads; not an MCP interface parameter.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_nonzero_default",
+                  "value": false
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_nonzero_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": "integer"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "integer"
+            }
+          },
+          "required": false,
+          "type": "integer"
+        },
+        "part-size": {
+          "default": "16MB",
+          "description": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "CLI-only transfer-layer flag controlling download chunk size; not an MCP interface parameter.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "partSize"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "CLI-only transfer-layer flag controlling download chunk size; not an MCP interface parameter.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_nonzero_default",
+                  "value": false
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_nonzero_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": "string"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "string"
+            }
+          },
+          "required": false,
+          "type": "string"
+        },
        "space-id": {
          "description": "文件所属空间 ID (可选)",
          "field_provenance": {
@@ -5937,8 +6224,99 @@
      "interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
      "is_alias": false,
      "name": "download_file_version",
-      "parameter_count": 3,
+      "parameter_count": 6,
      "parameters": {
+        "no-resume": {
+          "description": "关闭断点续传 (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "关闭断点续传 (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "关闭断点续传 (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --no-resume is a CLI wrapper input and does not publish a direct interface property.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "noResume"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --no-resume is a CLI wrapper input and does not publish a direct interface property.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "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"
+            }
+          },
+          "required": false,
+          "type": "boolean"
+        },
        "node": {
          "description": "文件 ID (dentryUuid) 或 URL (必填)",
          "field_provenance": {
@@ -6133,6 +6511,202 @@
          "required": true,
          "type": "string"
        },
+        "parallel": {
+          "default": "4",
+          "description": "分片下载并发数，范围 1-8 (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "分片下载并发数，范围 1-8 (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "分片下载并发数，范围 1-8 (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --parallel is a CLI wrapper input and does not publish a direct interface property.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "parallel"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --parallel is a CLI wrapper input and does not publish a direct interface property.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_nonzero_default",
+                  "value": false
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_nonzero_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": "integer"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "integer"
+            }
+          },
+          "required": false,
+          "type": "integer"
+        },
+        "part-size": {
+          "default": "16MB",
+          "description": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)",
+          "field_provenance": {
+            "description": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_usage",
+                  "value": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)"
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": ""
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_usage",
+              "value": "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)"
+            },
+            "property": {
+              "candidates": [
+                {
+                  "precedence": "reviewed_mapping_exclusion",
+                  "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --part-size is a CLI wrapper input and does not publish a direct interface property.",
+                  "selected": true,
+                  "source": "reviewed_mapping_exclusion",
+                  "value": ""
+                },
+                {
+                  "precedence": "inference",
+                  "selected": false,
+                  "source": "flag_name_inference",
+                  "value": "partSize"
+                }
+              ],
+              "precedence": "reviewed_mapping_exclusion",
+              "resolution": "highest_precedence",
+              "review_reason": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --part-size is a CLI wrapper input and does not publish a direct interface property.",
+              "source": "reviewed_mapping_exclusion",
+              "value": ""
+            },
+            "required": {
+              "candidates": [
+                {
+                  "precedence": "cobra_contract",
+                  "selected": true,
+                  "source": "cobra_nonzero_default",
+                  "value": false
+                },
+                {
+                  "precedence": "default",
+                  "selected": false,
+                  "source": "default",
+                  "value": false
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_nonzero_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": "string"
+                }
+              ],
+              "precedence": "cobra_contract",
+              "resolution": "highest_precedence",
+              "source": "cobra_flag_type",
+              "value": "string"
+            }
+          },
+          "required": false,
+          "type": "string"
+        },
        "version": {
          "description": "历史版本号 (必填，正整数，从 drive list --versions 获取)",
          "field_provenance": {
@@ -452,6 +452,10 @@
      "canonical_path": "aitable.workflow_disable",
      "cli_path": "aitable workflow disable"
    },
+    {
+      "canonical_path": "aitable.workflow_edit_example",
+      "cli_path": "aitable workflow edit-example"
+    },
    {
      "canonical_path": "aitable.workflow_enable",
      "cli_path": "aitable workflow enable"
@@ -999,6 +999,19 @@
      "reviewed": true,
      "runtime_gate": "confirm_delete"
    },
+    "aitable.workflow_edit_example": {
+      "effect": "read",
+      "risk": "low",
+      "confirmation": "not_required",
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
+      "reviewed": true,
+      "review_reason": "The command sends empty arguments to aitable/edit_workflow_example and returns the service-provided workflow editing documentation and examples. The operation is read-only and safe to retry.",
+      "cli_path": "aitable workflow edit-example",
+      "runtime_gate": "none"
+    },
    "aitable.workflow_enable": {
      "interface_ref": {
        "product_id": "aitable-helper",
@@ -7,7 +7,7 @@
    "channel": "open-source"
  },
  "coverage": {
-    "source_tools": 845,
+    "source_tools": 846,
    "matched_tools": 71
  },
  "tools": {
@@ -2250,6 +2250,26 @@
        "dws-schema-live:none (helper/composite; Skill+Cobra)"
      ]
    },
+    "aitable.workflow_edit_example": {
+      "agent_summary": "获取 AI 表格工作流编辑文档与 workflow-dsl/v1 示例。",
+      "use_when": [
+        "创建或更新工作流前，需要确认最新 workflow-dsl/v1 结构、节点写法或完整示例时"
+      ],
+      "avoid_when": [
+        "实际创建工作流用 workflow create；修改已有工作流用 workflow update；查询已发布定义用 workflow get"
+      ],
+      "examples": [
+        "dws aitable workflow edit-example"
+      ],
+      "reviewed": true,
+      "review_reason": "依据新增 Cobra leaf 和用户提供的 aitable/edit_workflow_example 空参数 MCP 契约审阅选型语义，将该命令限定为 create/update 前的只读文档入口。",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#aitable.workflow_edit_example",
+        "cobra-help:dws aitable workflow edit-example --help",
+        "skills/mono/references/products/aitable/aitable-workflow.md",
+        "mcp-contract:aitable/edit_workflow_example"
+      ]
+    },
    "aitable.workflow_enable": {
      "agent_summary": "启用工作流。",
      "use_when": [
@@ -1790,9 +1790,15 @@
    "drive.apply_permission --reason": "Reviewed unpinned adapter: drive.apply_permission has no singular pinned interface_ref; --reason is a CLI wrapper input and does not publish a direct interface property.",
    "drive.apply_permission --role": "Reviewed unpinned adapter: drive.apply_permission has no singular pinned interface_ref; --role is a CLI wrapper input and does not publish a direct interface property.",
    "drive.apply_permission --users": "Reviewed unpinned adapter: drive.apply_permission has no singular pinned interface_ref; --users is a CLI wrapper input and does not publish a direct interface property.",
+    "drive.download_file --no-resume": "CLI-only transfer-layer flag controlling download resume behaviour; not an MCP interface parameter.",
    "drive.download_file --output": "local output path",
+    "drive.download_file --parallel": "CLI-only transfer-layer flag controlling parallel chunk downloads; not an MCP interface parameter.",
+    "drive.download_file --part-size": "CLI-only transfer-layer flag controlling download chunk size; not an MCP interface parameter.",
+    "drive.download_file_version --no-resume": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --no-resume is a CLI wrapper input and does not publish a direct interface property.",
    "drive.download_file_version --node": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
    "drive.download_file_version --output": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --output is a CLI wrapper input and does not publish a direct interface property.",
+    "drive.download_file_version --parallel": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --parallel is a CLI wrapper input and does not publish a direct interface property.",
+    "drive.download_file_version --part-size": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --part-size is a CLI wrapper input and does not publish a direct interface property.",
    "drive.download_file_version --version": "Reviewed unpinned adapter: drive.download_file_version has no singular pinned interface_ref; --version is a CLI wrapper input and does not publish a direct interface property.",
    "drive.get_cover --node": "Reviewed unpinned adapter: drive.get_cover has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
    "drive.get_star_list --content-types": "Reviewed unpinned adapter: drive.get_star_list has no singular pinned interface_ref; --content-types is a CLI wrapper input and does not publish a direct interface property.",
@@ -25,7 +25,9 @@ import (
 )

 // MetaFileName is the on-disk name of the bus metadata file. It lives
-// alongside bus.lock and bus.sock inside the bus working directory.
+// alongside bus.lock inside the bus working directory. Unix bus sockets live
+// in a private per-user runtime directory so shared config filesystems do not
+// need socket support.
 const MetaFileName = "bus.meta"

 // Meta is the JSON document written once at bus startup. Its primary
@@ -30,9 +30,9 @@ import (
 type SpawnFunc func(SpawnConfig) (pid int, err error)

 // DiscoverConfig describes one discover attempt. WorkDir holds bus.lock and
-// usually (on Unix) bus.sock — see dwsevent.IPCEndpoint for the short-path
-// fallback when WorkDir is too deep; the caller must mkdir it with
-// pkg/config.DirPerm beforehand.
+// persistent bus metadata; Unix sockets live in a private per-user runtime
+// directory so WorkDir may reside on a shared filesystem without socket
+// support. The caller must mkdir WorkDir with pkg/config.DirPerm beforehand.
 type DiscoverConfig struct {
 	WorkDir     string
 	IPCEndpoint string
@@ -69,8 +69,8 @@ type BusEntry struct {

 // IPCEndpoint returns the IPC endpoint for this entry. Delegates to
 // dwsevent.IPCEndpoint so status/stop dial exactly where consume and the
-// bus daemon bound (including the short-path fallback when WorkDir is too
-// deep for sun_path).
+// bus daemon bound (a private per-user runtime path on Unix and a named pipe
+// on Windows).
 func (e BusEntry) IPCEndpoint() string {
 	hash := e.ClientIDHash
 	if e.IdentityHash != "" {
@@ -17,8 +17,16 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strconv"
+	"strings"
 )

+const eventRuntimeDirPrefix = "dws-event-"
+
+func currentUserID() string {
+	return strconv.Itoa(os.Geteuid())
+}
+
 // MaxUnixSocketPath returns the longest Unix socket path accepted by
 // bind/connect on this OS (Go rejects longer names with EINVAL before
 // the syscall). sockaddr_un.sun_path is 104 bytes on darwin and the
@@ -35,17 +43,19 @@ func maxUnixSocketPath(goos string) int {
 }

 // IPCEndpoint returns the bus IPC endpoint for one identity: a Named Pipe
-// name on Windows, otherwise bus.sock inside workDir.
+// name on Windows, otherwise a deterministic Unix socket under a private
+// per-user runtime directory.
 //
-// The canonical Unix location is <workDir>/bus.sock, but workDir derives
-// from the config dir, which can be arbitrarily deep (e.g. dwssb sandboxes
-// use ~/.dwssb/sandboxes/<name>/config/...). When the canonical path would
-// exceed the OS sun_path limit, the socket falls back to a short
-// deterministic path under os.TempDir keyed by a hash of workDir, so every
-// process (consume parent, forked _bus child, status/stop tooling) that
-// derives the endpoint from the same workDir agrees on the location.
-// bus.lock / bus.meta / bus.log always stay in workDir — only the socket
-// moves.
+// Unix sockets must live on a local filesystem that supports bind(2).
+// Config directories may reside on NFS, CSI, FUSE, or other shared mounts
+// that reject Unix socket creation with ENOTSUPP. On Unix, the endpoint uses
+// XDG_RUNTIME_DIR when it is absolute and short enough; otherwise it falls
+// back to a per-UID directory under os.TempDir. The transport creates and
+// validates that directory as owner-only before listening or dialing. The
+// socket name is keyed by a hash of workDir so every process (consume parent,
+// forked _bus child, status/stop tooling) that derives the endpoint from the
+// same workDir agrees on the location. bus.lock / bus.meta / bus.log always
+// stay in workDir.
 //
 // This is the single source of truth for endpoint derivation; the cobra
 // layer and busctl must not re-implement the shape.
@@ -60,9 +70,21 @@ func ipcEndpointForOS(goos, workDir, editionName string, sourceKind SourceKind,
 	if goos == "windows" {
 		return `\\.\pipe\dws-event-` + editionName + "-" + string(sourceKind) + "-" + identityHash
 	}
-	sock := filepath.Join(workDir, "bus.sock")
-	if len(sock) <= maxUnixSocketPath(goos) {
-		return sock
+	return unixSocketEndpoint(goos, workDir, strings.TrimSpace(os.Getenv("XDG_RUNTIME_DIR")), os.TempDir())
+}
+
+func unixSocketEndpoint(goos, workDir, runtimeDir, tempDir string) string {
+	socketName := "dws-evt-" + IdentityHash(workDir) + ".sock"
+	userDirName := eventRuntimeDirPrefix + currentUserID()
+	if filepath.IsAbs(runtimeDir) {
+		candidate := filepath.Join(runtimeDir, userDirName, socketName)
+		if len(candidate) <= maxUnixSocketPath(goos) {
+			return candidate
+		}
 	}
-	return filepath.Join(os.TempDir(), "dws-evt-"+IdentityHash(workDir)+".sock")
+	fallback := filepath.Join(tempDir, userDirName, socketName)
+	if len(fallback) <= maxUnixSocketPath(goos) {
+		return fallback
+	}
+	return filepath.Join("/tmp", userDirName, socketName)
 }
@@ -14,6 +14,7 @@
 package event

 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -33,10 +34,27 @@ func TestCrossPlatformCoverageEndpointPortableCoverageEdges(t *testing.T) {
 	if got := ipcEndpointForOS("windows", "ignored", "open", "", "hash"); got != `\\.\pipe\dws-event-open-app_stream-hash` {
 		t.Fatalf("Windows endpoint = %q", got)
 	}
-	if got := ipcEndpointForOS("darwin", "short", "open", SourceKindPersonalStream, "hash"); got != filepath.Join("short", "bus.sock") {
+
+	runtimeRoot := filepath.VolumeName(os.TempDir()) + string(filepath.Separator)
+	runtimeDir := filepath.Join(runtimeRoot, "dws-xdg-runtime")
+	t.Setenv("XDG_RUNTIME_DIR", runtimeDir)
+	workDir := "portable-xdg-workdir"
+	wantXDG := filepath.Join(runtimeDir, eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash(workDir)+".sock")
+	if got := ipcEndpointForOS("linux", workDir, "open", SourceKindPersonalStream, "hash"); got != wantXDG {
+		t.Fatalf("XDG Unix endpoint = %q, want %q", got, wantXDG)
+	}
+
+	t.Setenv("XDG_RUNTIME_DIR", "")
+	if got := ipcEndpointForOS("darwin", "short", "open", SourceKindPersonalStream, "hash"); got != filepath.Join(os.TempDir(), eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash("short")+".sock") {
 		t.Fatalf("short Unix endpoint = %q", got)
 	}
 	if got := ipcEndpointForOS("darwin", strings.Repeat("x", 200), "open", SourceKindAppStream, "hash"); !strings.Contains(got, "dws-evt-") {
 		t.Fatalf("long Unix endpoint = %q", got)
 	}
+
+	longTempDir := filepath.Join(string(filepath.Separator), strings.Repeat("long-temp-root", 20))
+	wantShortFallback := filepath.Join("/tmp", eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash(workDir)+".sock")
+	if got := unixSocketEndpoint("darwin", workDir, "", longTempDir); got != wantShortFallback {
+		t.Fatalf("overlong temp endpoint = %q, want %q", got, wantShortFallback)
+	}
 }
@@ -23,6 +23,7 @@ import (
 )

 func TestEndpointPlatformVariants(t *testing.T) {
+	t.Setenv("XDG_RUNTIME_DIR", "")
 	if maxUnixSocketPath("linux") != 107 || maxUnixSocketPath("darwin") != 103 {
 		t.Fatal("Unix socket limits changed")
 	}
@@ -31,7 +32,7 @@ func TestEndpointPlatformVariants(t *testing.T) {
 		t.Fatalf("Windows pipe = %q", pipe)
 	}
 	short := ipcEndpointForOS("darwin", "/tmp/events", "open", SourceKindPersonalStream, "hash")
-	if short != filepath.Join("/tmp/events", "bus.sock") {
+	if short != filepath.Join(os.TempDir(), eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash("/tmp/events")+".sock") {
 		t.Fatalf("short Unix endpoint = %q", short)
 	}
 	long := ipcEndpointForOS("darwin", "/"+strings.Repeat("deep/", 40), "open", SourceKindAppStream, "hash")
@@ -40,16 +41,40 @@ func TestEndpointPlatformVariants(t *testing.T) {
 	}
 }

-func TestIPCEndpointShortWorkDirUsesCanonicalPath(t *testing.T) {
-	workDir := "/tmp/dws/events/open/app_stream/aabbccdd00112233"
+func TestIPCEndpointUsesXDGUserRuntimeDir(t *testing.T) {
+	tempRoot, err := filepath.EvalSymlinks("/tmp")
+	if err != nil {
+		t.Fatalf("EvalSymlinks: %v", err)
+	}
+	runtimeDir, err := os.MkdirTemp(tempRoot, "dws-xdg-")
+	if err != nil {
+		t.Fatalf("MkdirTemp: %v", err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(runtimeDir) })
+	t.Setenv("XDG_RUNTIME_DIR", runtimeDir)
+	workDir := "/shared/events/open/app_stream/aabbccdd00112233"
 	got := IPCEndpoint(workDir, "open", SourceKindAppStream, "aabbccdd00112233")
-	want := filepath.Join(workDir, "bus.sock")
+	want := filepath.Join(runtimeDir, eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash(workDir)+".sock")
 	if got != want {
 		t.Fatalf("IPCEndpoint = %q, want %q", got, want)
 	}
 }

-func TestIPCEndpointLongWorkDirFallsBackUnderTempDir(t *testing.T) {
+func TestIPCEndpointWithoutXDGUsesPerUserLocalTempDir(t *testing.T) {
+	t.Setenv("XDG_RUNTIME_DIR", "")
+	workDir := "/tmp/dws/events/open/app_stream/aabbccdd00112233"
+	got := IPCEndpoint(workDir, "open", SourceKindAppStream, "aabbccdd00112233")
+	want := filepath.Join(os.TempDir(), eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash(workDir)+".sock")
+	if got != want {
+		t.Fatalf("IPCEndpoint = %q, want %q", got, want)
+	}
+	if strings.HasPrefix(got, workDir) {
+		t.Fatalf("IPCEndpoint = %q, want endpoint outside workDir", got)
+	}
+}
+
+func TestIPCEndpointLongWorkDirUsesLocalTempDir(t *testing.T) {
+	t.Setenv("XDG_RUNTIME_DIR", "")
 	// Mirrors the dwssb sandbox layout that produced a 111-byte socket
 	// path — over macOS's 103-byte usable sun_path budget.
 	workDir := "/Users/zhengyubai/.dwssb/sandboxes/event-subscribe/config/events/open/personal_stream/3928ce0fb4860a52"
@@ -66,6 +91,7 @@ func TestIPCEndpointLongWorkDirFallsBackUnderTempDir(t *testing.T) {
 }

 func TestIPCEndpointFallbackIsDeterministicPerWorkDir(t *testing.T) {
+	t.Setenv("XDG_RUNTIME_DIR", "")
 	long := strings.Repeat("x", 120)
 	a := IPCEndpoint("/base/"+long+"/one", "open", SourceKindPersonalStream, "hash")
 	b := IPCEndpoint("/base/"+long+"/one", "open", SourceKindPersonalStream, "hash")
@@ -77,3 +103,29 @@ func TestIPCEndpointFallbackIsDeterministicPerWorkDir(t *testing.T) {
 		t.Fatalf("different workDirs collided on endpoint %q", a)
 	}
 }
+
+func TestIPCEndpointLongXDGPathFallsBackToTempDir(t *testing.T) {
+	t.Setenv("XDG_RUNTIME_DIR", "/"+strings.Repeat("runtime/", 30))
+	workDir := "/shared/events/open/personal_stream/aabbccdd00112233"
+	got := ipcEndpointForOS("linux", workDir, "open", SourceKindPersonalStream, "hash")
+	wantPrefix := filepath.Join(os.TempDir(), eventRuntimeDirPrefix+currentUserID()) + string(filepath.Separator)
+	if !strings.HasPrefix(got, wantPrefix) {
+		t.Fatalf("IPCEndpoint = %q, want fallback under %q", got, wantPrefix)
+	}
+	if len(got) > maxUnixSocketPath("linux") {
+		t.Fatalf("fallback path still too long: %d > %d (%q)", len(got), maxUnixSocketPath("linux"), got)
+	}
+}
+
+func TestIPCEndpointLongTempDirUsesShortSystemFallback(t *testing.T) {
+	workDir := "/shared/events/open/personal_stream/aabbccdd00112233"
+	longTempDir := "/" + strings.Repeat("long-temp-root/", 20)
+	got := unixSocketEndpoint("linux", workDir, "", longTempDir)
+	want := filepath.Join("/tmp", eventRuntimeDirPrefix+currentUserID(), "dws-evt-"+IdentityHash(workDir)+".sock")
+	if got != want {
+		t.Fatalf("IPCEndpoint = %q, want short fallback %q", got, want)
+	}
+	if len(got) > maxUnixSocketPath("linux") {
+		t.Fatalf("short fallback path too long: %d > %d (%q)", len(got), maxUnixSocketPath("linux"), got)
+	}
+}
@@ -73,6 +73,83 @@ func TestCrossPlatformCoverageUnixListenErrorCoverage(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageUnixSocketDirectoryErrorCoverage(t *testing.T) {
+	oldLstat, oldRuntimeStat, oldMkdir := lstatSocketPath, statSocketRuntimeRoot, mkdirSocketDir
+	t.Cleanup(func() {
+		lstatSocketPath, statSocketRuntimeRoot, mkdirSocketDir = oldLstat, oldRuntimeStat, oldMkdir
+	})
+
+	wantErr := errors.New("synthetic socket directory failure")
+	if err := ensureSocketDir("relative/bus.sock", true); err == nil || !strings.Contains(err.Error(), "must be absolute") {
+		t.Fatalf("relative socket path error = %v", err)
+	}
+
+	root := shortSecureTempDir(t)
+	missingRootPath := filepath.Join(root, "missing-root", "dws-event-test", "bus.sock")
+	if err := ensureSocketDir(missingRootPath, false); err == nil || !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("missing runtime root error = %v", err)
+	}
+
+	rootInfo, err := oldLstat(root)
+	if err != nil {
+		t.Fatalf("lstat secure root: %v", err)
+	}
+	lstatSocketPath = func(path string) (os.FileInfo, error) {
+		if path == "/tmp" {
+			return fileInfoWithMode{FileInfo: rootInfo, mode: os.ModeSymlink | 0o777}, nil
+		}
+		return oldLstat(path)
+	}
+	statSocketRuntimeRoot = func(path string) (os.FileInfo, error) {
+		if path == "/tmp" {
+			return nil, wantErr
+		}
+		return oldRuntimeStat(path)
+	}
+	if err := ensureSocketDir("/tmp/dws-event-coverage/bus.sock", false); !errors.Is(err, wantErr) {
+		t.Fatalf("runtime root resolution error = %v", err)
+	}
+	lstatSocketPath, statSocketRuntimeRoot = oldLstat, oldRuntimeStat
+
+	rootFile := filepath.Join(root, "runtime-root-file")
+	if err := os.WriteFile(rootFile, []byte("not a directory"), 0o600); err != nil {
+		t.Fatalf("write runtime root file: %v", err)
+	}
+	if err := ensureSocketDir(filepath.Join(rootFile, "dws-event-test", "bus.sock"), false); err == nil || !strings.Contains(err.Error(), "runtime root is not a directory") {
+		t.Fatalf("non-directory runtime root error = %v", err)
+	}
+
+	mkdirSocketDir = func(string, os.FileMode) error { return wantErr }
+	if err := ensureSocketDir(filepath.Join(root, "mkdir-failure", "bus.sock"), true); !errors.Is(err, wantErr) {
+		t.Fatalf("socket directory creation error = %v", err)
+	}
+	mkdirSocketDir = oldMkdir
+
+	if err := ensureSocketDir(filepath.Join(root, "missing-socket-dir", "bus.sock"), false); err == nil || !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("missing socket directory error = %v", err)
+	}
+
+	withoutOwner := fileInfoWithoutOwner{FileInfo: rootInfo}
+	if err := validateSocketRuntimeRoot(root, withoutOwner, uint32(os.Geteuid())); err == nil || !strings.Contains(err.Error(), "owner") {
+		t.Fatalf("runtime root owner error = %v", err)
+	}
+	if err := validatePrivateSocketDir(root, withoutOwner, uint32(os.Geteuid())); err == nil || !strings.Contains(err.Error(), "owner") {
+		t.Fatalf("socket directory owner error = %v", err)
+	}
+}
+
+type fileInfoWithMode struct {
+	os.FileInfo
+	mode os.FileMode
+}
+
+func (f fileInfoWithMode) Mode() os.FileMode { return f.mode }
+func (f fileInfoWithMode) IsDir() bool       { return f.mode.IsDir() }
+
+type fileInfoWithoutOwner struct{ os.FileInfo }
+
+func (fileInfoWithoutOwner) Sys() any { return struct{}{} }
+
 type stubNetListener struct {
 	close func() error
 }
@@ -16,9 +16,12 @@
 package transport

 import (
+	"errors"
 	"fmt"
 	"net"
 	"os"
+	"path/filepath"
+	"syscall"

 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
@@ -30,10 +33,13 @@ type unixListener struct {
 }

 var (
-	statSocket   = os.Stat
-	removeSocket = os.Remove
-	listenUnix   = net.Listen
-	chmodSocket  = os.Chmod
+	statSocket            = os.Stat
+	removeSocket          = os.Remove
+	listenUnix            = net.Listen
+	chmodSocket           = os.Chmod
+	lstatSocketPath       = os.Lstat
+	statSocketRuntimeRoot = os.Stat
+	mkdirSocketDir        = os.Mkdir
 )

 func (u *unixListener) Accept() (net.Conn, error) { return u.l.Accept() }
@@ -56,11 +62,95 @@ func checkSocketPath(path string) error {
 	return nil
 }

+// ensureSocketDir makes the socket's immediate parent an owner-only
+// directory and rejects unsafe pre-existing paths. The parent of that
+// directory must itself either be private to the effective user (for
+// XDG_RUNTIME_DIR and macOS temporary roots) or sticky (for Linux /tmp), so
+// another user cannot rename the private directory out from under us.
+func ensureSocketDir(path string, create bool) error {
+	if !filepath.IsAbs(path) {
+		return fmt.Errorf("transport: unix socket path must be absolute: %s", path)
+	}
+	dir := filepath.Dir(path)
+	root := filepath.Dir(dir)
+	rootInfo, err := lstatSocketPath(root)
+	if err != nil {
+		return fmt.Errorf("transport: inspect socket runtime root %s: %w", root, err)
+	}
+	// macOS exposes the system /tmp as a root-owned symlink to /private/tmp.
+	// Follow only that well-known alias, then apply the same ownership/sticky
+	// validation to its target. Arbitrary runtime-root symlinks remain rejected.
+	if rootInfo.Mode()&os.ModeSymlink != 0 && filepath.Clean(root) == "/tmp" {
+		rootInfo, err = statSocketRuntimeRoot(root)
+		if err != nil {
+			return fmt.Errorf("transport: resolve socket runtime root %s: %w", root, err)
+		}
+	}
+	if err := validateSocketRuntimeRoot(root, rootInfo, uint32(os.Geteuid())); err != nil {
+		return err
+	}
+	if create {
+		if err := mkdirSocketDir(dir, config.DirPerm); err != nil && !errors.Is(err, os.ErrExist) {
+			return fmt.Errorf("transport: create socket directory %s: %w", dir, err)
+		}
+	}
+	dirInfo, err := lstatSocketPath(dir)
+	if err != nil {
+		return fmt.Errorf("transport: inspect socket directory %s: %w", dir, err)
+	}
+	return validatePrivateSocketDir(dir, dirInfo, uint32(os.Geteuid()))
+}
+
+func validateSocketRuntimeRoot(path string, info os.FileInfo, effectiveUID uint32) error {
+	if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("transport: socket runtime root is not a directory: %s", path)
+	}
+	owner, err := fileOwnerUID(info)
+	if err != nil {
+		return fmt.Errorf("transport: inspect socket runtime root owner %s: %w", path, err)
+	}
+	privateOwnerRoot := owner == effectiveUID && info.Mode().Perm()&0o022 == 0
+	stickyRoot := info.Mode()&os.ModeSticky != 0
+	if !privateOwnerRoot && !stickyRoot {
+		return fmt.Errorf("transport: socket runtime root is neither private nor sticky: %s", path)
+	}
+	return nil
+}
+
+func validatePrivateSocketDir(path string, info os.FileInfo, effectiveUID uint32) error {
+	if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("transport: socket directory is not a directory: %s", path)
+	}
+	owner, err := fileOwnerUID(info)
+	if err != nil {
+		return fmt.Errorf("transport: inspect socket directory owner %s: %w", path, err)
+	}
+	if owner != effectiveUID {
+		return fmt.Errorf("transport: socket directory %s is owned by uid %d, want %d", path, owner, effectiveUID)
+	}
+	if perm := info.Mode().Perm(); perm != config.DirPerm {
+		return fmt.Errorf("transport: socket directory %s has permissions %04o, want %04o", path, perm, config.DirPerm)
+	}
+	return nil
+}
+
+func fileOwnerUID(info os.FileInfo) (uint32, error) {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, errors.New("stat result does not expose an owner uid")
+	}
+	return stat.Uid, nil
+}
+
 func listen(path string) (Listener, error) {
 	if err := checkSocketPath(path); err != nil {
 		return nil, err
 	}
-	// Stale socket cleanup. Caller holds bus.lock so this is race-safe.
+	if err := ensureSocketDir(path, true); err != nil {
+		return nil, err
+	}
+	// The private per-user parent excludes other users. The caller's bus.lock
+	// serializes stale-socket cleanup for processes using the same WorkDir.
 	if _, err := statSocket(path); err == nil {
 		if err := removeSocket(path); err != nil {
 			return nil, fmt.Errorf("transport: remove stale socket %s: %w", path, err)
@@ -82,5 +172,8 @@ func dial(path string) (net.Conn, error) {
 	if err := checkSocketPath(path); err != nil {
 		return nil, err
 	}
+	if err := ensureSocketDir(path, false); err != nil {
+		return nil, err
+	}
 	return net.Dial("unix", path)
 }
@@ -21,12 +21,32 @@ import (
 	"net"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"testing"
+
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 )

+func shortSecureTempDir(t *testing.T) string {
+	t.Helper()
+	tempRoot, err := filepath.EvalSymlinks("/tmp")
+	if err != nil {
+		t.Fatalf("EvalSymlinks: %v", err)
+	}
+	dir, err := os.MkdirTemp(tempRoot, "dws-et-")
+	if err != nil {
+		t.Fatalf("MkdirTemp: %v", err)
+	}
+	if err := os.Chmod(dir, 0o700); err != nil {
+		t.Fatalf("chmod temp dir: %v", err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(dir) })
+	return dir
+}
+
 func TestListen_DialRoundtrip(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "bus.sock")
+	path := filepath.Join(shortSecureTempDir(t), "bus.sock")
 	l, err := Listen(path)
 	if err != nil {
 		t.Fatalf("Listen: %v", err)
@@ -87,7 +107,7 @@ func TestListen_DialRoundtrip(t *testing.T) {
 }

 func TestListen_StaleSocketCleanup(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "bus.sock")
+	path := filepath.Join(shortSecureTempDir(t), "bus.sock")
 	// Pre-create a stale file at path (not a valid socket).
 	if err := os.WriteFile(path, []byte("stale"), 0o600); err != nil {
 		t.Fatalf("pre-create: %v", err)
@@ -99,8 +119,121 @@ func TestListen_StaleSocketCleanup(t *testing.T) {
 	defer l.Close()
 }

+func TestCrossPlatformCoverageListenCreatesPrivateSocketDirectory(t *testing.T) {
+	dir := filepath.Join(shortSecureTempDir(t), "dws-event-test")
+	path := filepath.Join(dir, "bus.sock")
+	l, err := Listen(path)
+	if err != nil {
+		t.Fatalf("Listen: %v", err)
+	}
+	defer l.Close()
+
+	st, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("stat socket directory: %v", err)
+	}
+	if mode := st.Mode().Perm(); mode != 0o700 {
+		t.Fatalf("socket directory mode = %04o, want 0700", mode)
+	}
+}
+
+func TestCrossPlatformCoverageListenRejectsWorldAccessibleSocketDirectory(t *testing.T) {
+	dir := filepath.Join(shortSecureTempDir(t), "dws-event-test")
+	if err := os.Mkdir(dir, 0o700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.Chmod(dir, 0o777); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	if _, err := Listen(filepath.Join(dir, "bus.sock")); err == nil || !strings.Contains(err.Error(), "want 0700") {
+		t.Fatalf("Listen error = %v, want 0700 directory rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageDialRejectsWorldAccessibleSocketDirectory(t *testing.T) {
+	dir := filepath.Join(shortSecureTempDir(t), "dws-event-test")
+	if err := os.Mkdir(dir, 0o700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.Chmod(dir, 0o777); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	if _, err := Dial(filepath.Join(dir, "bus.sock")); err == nil || !strings.Contains(err.Error(), "want 0700") {
+		t.Fatalf("Dial error = %v, want 0700 directory rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageListenRejectsSymlinkSocketDirectory(t *testing.T) {
+	root := shortSecureTempDir(t)
+	target := filepath.Join(root, "target")
+	if err := os.Mkdir(target, 0o700); err != nil {
+		t.Fatalf("mkdir target: %v", err)
+	}
+	link := filepath.Join(root, "dws-event-test")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	if _, err := Listen(filepath.Join(link, "bus.sock")); err == nil || !strings.Contains(err.Error(), "not a directory") {
+		t.Fatalf("Listen error = %v, want symlink directory rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidatePrivateSocketDirRejectsDifferentOwner(t *testing.T) {
+	dir := shortSecureTempDir(t)
+	st, err := os.Lstat(dir)
+	if err != nil {
+		t.Fatalf("lstat: %v", err)
+	}
+	otherUID := uint32(os.Geteuid() + 1)
+	if err := validatePrivateSocketDir(dir, st, otherUID); err == nil || !strings.Contains(err.Error(), "is owned by uid") {
+		t.Fatalf("validatePrivateSocketDir error = %v, want owner mismatch", err)
+	}
+}
+
+func TestCrossPlatformCoverageListenRejectsUntrustedRuntimeRoot(t *testing.T) {
+	root := filepath.Join(shortSecureTempDir(t), "untrusted")
+	if err := os.Mkdir(root, 0o700); err != nil {
+		t.Fatalf("mkdir root: %v", err)
+	}
+	if err := os.Chmod(root, 0o777); err != nil {
+		t.Fatalf("chmod root: %v", err)
+	}
+	dir := filepath.Join(root, "dws-event-test")
+	if err := os.Mkdir(dir, 0o700); err != nil {
+		t.Fatalf("mkdir socket dir: %v", err)
+	}
+	if _, err := Listen(filepath.Join(dir, "bus.sock")); err == nil || !strings.Contains(err.Error(), "neither private nor sticky") {
+		t.Fatalf("Listen error = %v, want untrusted runtime root rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageListenSharedWorkDirUsesLocalSecureRuntimeEndpoint(t *testing.T) {
+	root := shortSecureTempDir(t)
+	runtimeDir := filepath.Join(root, "runtime")
+	if err := os.Mkdir(runtimeDir, 0o700); err != nil {
+		t.Fatalf("mkdir runtime: %v", err)
+	}
+	t.Setenv("XDG_RUNTIME_DIR", runtimeDir)
+	sharedWorkDir := filepath.Join(root, "simulated-nfs", "events", "open", "personal_stream", "identity")
+	endpoint := dwsevent.IPCEndpoint(sharedWorkDir, "open", dwsevent.SourceKindPersonalStream, "identity")
+	if strings.HasPrefix(endpoint, sharedWorkDir) {
+		t.Fatalf("endpoint = %q, want socket outside shared WorkDir %q", endpoint, sharedWorkDir)
+	}
+
+	l, err := Listen(endpoint)
+	if err != nil {
+		t.Fatalf("Listen on local runtime endpoint: %v", err)
+	}
+	defer l.Close()
+	if mode, err := os.Stat(filepath.Dir(endpoint)); err != nil {
+		t.Fatalf("stat runtime socket directory: %v", err)
+	} else if mode.Mode().Perm() != 0o700 {
+		t.Fatalf("runtime socket directory mode = %04o, want 0700", mode.Mode().Perm())
+	}
+}
+
 func TestListen_CloseUnlinksSocket(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "bus.sock")
+	path := filepath.Join(shortSecureTempDir(t), "bus.sock")
 	l, err := Listen(path)
 	if err != nil {
 		t.Fatalf("Listen: %v", err)
@@ -114,7 +247,7 @@ func TestListen_CloseUnlinksSocket(t *testing.T) {
 }

 func TestDial_NoServerReturnsError(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "nonexistent.sock")
+	path := filepath.Join(shortSecureTempDir(t), "nonexistent.sock")
 	if _, err := Dial(path); err == nil {
 		t.Fatal("Dial to nonexistent socket should error")
 	}
@@ -124,7 +257,7 @@ func TestDial_NoServerReturnsError(t *testing.T) {
 // surfaces as io.EOF to the server's Reader — the EOF signal is what bus
 // uses to unregister dead consumers (plan invariant #5).
 func TestReader_HandlesPeerCloseEOF(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "bus.sock")
+	path := filepath.Join(shortSecureTempDir(t), "bus.sock")
 	l, err := Listen(path)
 	if err != nil {
 		t.Fatalf("Listen: %v", err)
@@ -853,6 +853,7 @@ func newAitableCommand() *cobra.Command {
  dws aitable form       [list|delete|update]                                           表单管理
  dws aitable form field [list|update|hide]                                             表单字段管理
  dws aitable form share [get|update|notify]                                            表单分享管理
+  dws aitable workflow   [edit-example|create|update|enable|disable|get|list]           自动化工作流管理
  dws aitable dashboard  [get|create|update|delete|config-example]                      仪表盘管理
  dws aitable chart      [get|create|update|delete|widgets-example]                     图表管理
  dws aitable export     data                                                           数据导出
@@ -3260,6 +3261,17 @@ valid=false 仍表示 DSL 校验或发布未通过，必须读取 issues 修正
 		},
 	}

+	workflowEditExampleCmd := &cobra.Command{
+		Use:   "edit-example",
+		Short: "获取工作流编辑文档与示例",
+		Long: `返回服务端提供的 AI 表格工作流编辑文档与示例。
+可作为 workflow create / workflow update 的 workflow-dsl/v1 结构参考；此命令不需要 Base ID 或其他参数。`,
+		Example: `  dws aitable workflow edit-example`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return callAitableTool("edit_workflow_example", map[string]any{})
+		},
+	}
+
 	workflowUpdateCmd := &cobra.Command{
 		Use:   "update",
 		Short: "更新并发布已有自动化工作流",
@@ -4856,7 +4868,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	workflowListCmd.Flags().Int("limit", 0, "分页大小 [1, 100]，不传走服务端默认 20")
 	workflowListCmd.Flags().Int("offset", 0, "分页偏移量，>= 0，不传走服务端默认 0")
 	workflowCmd.AddCommand(
-		workflowCreateCmd, workflowUpdateCmd,
+		workflowEditExampleCmd, workflowCreateCmd, workflowUpdateCmd,
 		workflowEnableCmd, workflowDisableCmd,
 		workflowGetCmd, workflowListCmd,
 	)
@@ -94,6 +94,23 @@ func TestAitableWorkflowCreateMapsDSLWithoutRetry(t *testing.T) {
 	}
 }

+func TestAitableWorkflowEditExampleMapsEmptyArguments(t *testing.T) {
+	caller, err := runAitableWorkflowCommand(t, nil, "edit-example")
+	if err != nil {
+		t.Fatalf("workflow edit-example returned error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("tool call count = %d, want 1", len(caller.calls))
+	}
+	call := caller.calls[0]
+	if call.productID != "aitable" || call.toolName != "edit_workflow_example" {
+		t.Fatalf("tool call = %s/%s, want aitable/edit_workflow_example", call.productID, call.toolName)
+	}
+	if len(call.args) != 0 {
+		t.Fatalf("tool args = %#v, want empty arguments", call.args)
+	}
+}
+
 func TestAitableWorkflowUpdateReadsDSLFile(t *testing.T) {
 	path := t.TempDir() + "/workflow.json"
 	if err := os.WriteFile(path, []byte(`{"version":"workflow-dsl/v1","name":"updated"}`), 0o600); err != nil {
@@ -22,6 +22,7 @@ import (
 	"testing"
 	"time"

+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )

@@ -217,6 +218,73 @@ func TestCrossPlatformCoverageChatSendResolvesUserBeforeDispatch(t *testing.T) {
 	}
 }

+func TestChatSendAndReplyDefaultToAgentProductForIMClawType(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "qwenwork")
+
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "send",
+			args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello"},
+		},
+		{
+			name: "reply",
+			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &chatChangedContractCaller{}
+			if err := executeChatChangedContract(t, caller, tc.args...); err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 || caller.calls[0].toolName != "send_personal_message" {
+				t.Fatalf("calls = %#v", caller.calls)
+			}
+			if got := caller.calls[0].args["clawType"]; got != "qwenwork" {
+				t.Fatalf("clawType = %#v, want qwenwork", got)
+			}
+		})
+	}
+}
+
+func TestChatSendAndReplyDisableAITagWithEmptyClawType(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "qwenwork")
+
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "send",
+			args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello", "--ai-tag=false"},
+		},
+		{
+			name: "reply",
+			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello", "--ai-tag=false"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &chatChangedContractCaller{}
+			if err := executeChatChangedContract(t, caller, tc.args...); err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 || caller.calls[0].toolName != "send_personal_message" {
+				t.Fatalf("calls = %#v", caller.calls)
+			}
+			got, present := caller.calls[0].args["clawType"]
+			if !present || got != "" {
+				t.Fatalf("clawType = %#v, present = %v; want present empty string", got, present)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageChatSendFailsClosedWhenUserCannotResolve(t *testing.T) {
 	caller := &chatChangedContractCaller{}
 	err := executeChatChangedContract(t, caller, "message", "send", "--user", "123", "--text", "hello")
@@ -276,7 +276,8 @@ func defaultHTTPPutFile(ctx context.Context, url string, headers map[string]stri

 	if resp.StatusCode != http.StatusOK {
 		body, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("OSS upload failed: HTTP %d: %s", resp.StatusCode, string(body))
+		// typed httpStatusError 供上层按 401/403 分支重取凭证
+		return fmt.Errorf("OSS upload failed: %w", &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)})
 	}

 	return nil
@@ -434,7 +435,8 @@ func defaultHTTPGetFile(ctx context.Context, url string, headers map[string]stri

 	if resp.StatusCode != http.StatusOK {
 		body, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
+		// typed httpStatusError 供上层按 401/403 分支重取凭证
+		return &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)}
 	}

 	outFile, err := docCreateDestination(destPath)
@@ -476,7 +476,8 @@ func newDriveCommand() *cobra.Command {
 --output 指定本地保存路径，可以是文件路径或目录。
 如果指定目录，文件名从下载 URL 中自动推断。`,
 		Example: `  dws drive download --node <dentryUuid> --output ./report.pdf
-  dws drive download --node <dentryUuid> --output ~/downloads/`,
+  dws drive download --node <dentryUuid> --output ~/downloads/
+  dws drive download --node <dentryUuid> --output ./big.zip --part-size 32MB --parallel 8`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			fileID := flagOrFallback(cmd, "node", "file-id")
 			if fileID == "" {
@@ -492,6 +493,15 @@ func newDriveCommand() *cobra.Command {
 				argsMap["spaceId"] = v
 			}

+			// fail-fast：分片下载参数校验
+			dlOpts, err := driveDownloadOptionsFromFlags(cmd)
+			if err != nil {
+				return err
+			}
+			dlOpts.logf = func(format string, a ...any) {
+				deps.Out.PrintInfo(fmt.Sprintf(format, a...))
+			}
+
 			if deps.Caller.DryRun() {
 				deps.Out.PrintKeyValue("操作", "下载钉盘文件")
 				deps.Out.PrintKeyValue("文件ID", fileID)
@@ -499,7 +509,7 @@ func newDriveCommand() *cobra.Command {
 				return nil
 			}

-			ctx := context.Background()
+			ctx := cmd.Context()

 			// Step 1: 获取下载 URL 和签名请求头
 			deps.Out.PrintInfo("[1/2] 获取下载链接...")
@@ -508,7 +518,7 @@ func newDriveCommand() *cobra.Command {
 				return err
 			}

-			resourceURL, dlHeaders, err := parseDownloadInfo(text)
+			resourceURL, dlHeaders, err := parseDriveDownloadInfo(text)
 			if err != nil {
 				return err
 			}
@@ -523,9 +533,34 @@ func newDriveCommand() *cobra.Command {
 				outputPath = filepath.Join(outputPath, filename)
 			}

-			// Step 2: HTTP GET 下载文件
+			// Step 2: 分片下载（自动分派 + 401/403 凭证刷新重试）
 			deps.Out.PrintInfo(fmt.Sprintf("[2/2] 下载文件到 %s ...", outputPath))
-			if err := httpGetFile(ctx, resourceURL, dlHeaders, outputPath); err != nil {
+			dlOpts.knownSize = parseDownloadFileSize(text)
+			dlOpts.nodeID = fileID
+			dlOpts.version = parseDownloadFileVersion(text)
+			fetchCred := func(fctx context.Context) (string, map[string]string, int, error) {
+				t, ferr := callMCPToolReturnText(fctx, "download_file", argsMap)
+				if ferr != nil {
+					return "", nil, 0, ferr
+				}
+				u, h, perr := parseDriveDownloadInfo(t)
+				if perr != nil {
+					return "", nil, 0, perr
+				}
+				return u, h, parseDownloadFileVersion(t), nil
+			}
+			if err := driveTransferDownload(ctx, fetchCred, resourceURL, dlHeaders, outputPath, dlOpts); err != nil {
+				if errors.Is(err, context.Canceled) || ctx.Err() == context.Canceled {
+					partSize, _ := cmd.Flags().GetString("part-size")
+					noResume, _ := cmd.Flags().GetBool("no-resume")
+					if partSize != "" && !noResume {
+						fmt.Fprintf(cmd.ErrOrStderr(), "\n[INFO] 下载中断，已保存断点（可重新执行相同命令续传）\n")
+					} else {
+						fmt.Fprintf(cmd.ErrOrStderr(), "\n[INFO] 下载中断\n")
+					}
+					cmd.SilenceErrors = true
+					return err
+				}
 				return err
 			}

@@ -564,6 +599,15 @@ func newDriveCommand() *cobra.Command {
 				return fmt.Errorf("flag --output is required")
 			}

+			// fail-fast：分片下载参数校验
+			dlOpts, err := driveDownloadOptionsFromFlags(cmd)
+			if err != nil {
+				return err
+			}
+			dlOpts.logf = func(format string, a ...any) {
+				deps.Out.PrintInfo(fmt.Sprintf(format, a...))
+			}
+
 			if deps.Caller.DryRun() {
 				deps.Out.PrintKeyValue("操作", "下载文件历史版本")
 				deps.Out.PrintKeyValue("节点ID", fileID)
@@ -572,16 +616,17 @@ func newDriveCommand() *cobra.Command {
 				return nil
 			}

-			ctx := context.Background()
+			ctx := cmd.Context()
 			deps.Out.PrintInfo("[1/2] 获取历史版本下载链接...")
-			text, err := callMCPToolReturnTextOnServer(ctx, "drive", "download_file_version", map[string]any{
+			dlArgsMap := map[string]any{
 				"nodeId":  fileID,
 				"version": versionNum,
-			})
+			}
+			text, err := callMCPToolReturnTextOnServer(ctx, "drive", "download_file_version", dlArgsMap)
 			if err != nil {
 				return err
 			}
-			resourceURL, dlHeaders, err := parseDownloadInfo(text)
+			resourceURL, dlHeaders, err := parseDriveDownloadInfo(text)
 			if err != nil {
 				return err
 			}
@@ -593,7 +638,32 @@ func newDriveCommand() *cobra.Command {
 				outputPath = filepath.Join(outputPath, filename)
 			}
 			deps.Out.PrintInfo(fmt.Sprintf("[2/2] 下载文件到 %s ...", outputPath))
-			if err := httpGetFile(ctx, resourceURL, dlHeaders, outputPath); err != nil {
+			dlOpts.knownSize = parseDownloadFileSize(text)
+			dlOpts.nodeID = fileID
+			dlOpts.version = versionNum
+			fetchCred := func(fctx context.Context) (string, map[string]string, int, error) {
+				t, ferr := callMCPToolReturnTextOnServer(fctx, "drive", "download_file_version", dlArgsMap)
+				if ferr != nil {
+					return "", nil, 0, ferr
+				}
+				u, h, perr := parseDriveDownloadInfo(t)
+				if perr != nil {
+					return "", nil, 0, perr
+				}
+				return u, h, parseDownloadFileVersion(t), nil
+			}
+			if err := driveTransferDownload(ctx, fetchCred, resourceURL, dlHeaders, outputPath, dlOpts); err != nil {
+				if errors.Is(err, context.Canceled) || ctx.Err() == context.Canceled {
+					partSize, _ := cmd.Flags().GetString("part-size")
+					noResume, _ := cmd.Flags().GetBool("no-resume")
+					if partSize != "" && !noResume {
+						fmt.Fprintf(cmd.ErrOrStderr(), "\n[INFO] 下载中断，已保存断点（可重新执行相同命令续传）\n")
+					} else {
+						fmt.Fprintf(cmd.ErrOrStderr(), "\n[INFO] 下载中断\n")
+					}
+					cmd.SilenceErrors = true
+					return err
+				}
 				return err
 			}
 			deps.Out.PrintInfo(fmt.Sprintf("下载完成: %s", outputPath))
@@ -709,10 +779,16 @@ func newDriveCommand() *cobra.Command {
 	driveDownloadCmd.Flags().String("node", "", "文件 ID (dentryUuid) (必填)")
 	driveDownloadCmd.Flags().String("space-id", "", "文件所属空间 ID (可选)")
 	driveDownloadCmd.Flags().String("output", "", "本地保存路径 (文件路径或目录，必填)")
+	driveDownloadCmd.Flags().String("part-size", "16MB", "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)")
+	driveDownloadCmd.Flags().Int("parallel", 4, "分片下载并发数，范围 1-8 (可选)")
+	driveDownloadCmd.Flags().Bool("no-resume", false, "关闭断点续传 (可选)")

 	driveDownloadVersionCmd.Flags().String("node", "", "文件 ID (dentryUuid) 或 URL (必填)")
 	driveDownloadVersionCmd.Flags().Int("version", 0, "历史版本号 (必填，正整数，从 drive list --versions 获取)")
 	driveDownloadVersionCmd.Flags().String("output", "", "本地保存路径 (文件路径或目录，必填)")
+	driveDownloadVersionCmd.Flags().String("part-size", "16MB", "分片下载的分片大小，如 8MB/16MB/1GB，范围 1MB-1GB (可选)")
+	driveDownloadVersionCmd.Flags().Int("parallel", 4, "分片下载并发数，范围 1-8 (可选)")
+	driveDownloadVersionCmd.Flags().Bool("no-resume", false, "关闭断点续传 (可选)")
 	for _, alias := range []string{"url", "id", "node-id", "doc-id", "file-id"} {
 		driveDownloadVersionCmd.Flags().String(alias, "", "")
 		_ = driveDownloadVersionCmd.Flags().MarkHidden(alias)
@@ -2006,13 +2082,13 @@ func uploadToDrive(ctx context.Context, filePath, fileName string, fileSize int6
 	if err != nil {
 		return err
 	}
-	resourceURL, uploadID, headers, err := parseDriveUploadInfo(text)
+	// HTTP PUT 上传文件（OSS 与中心协议同路径；headers 透传，401/403 重取凭证重试一次）
+	uploadID, err := driveUploadPut(ctx, text, func(rctx context.Context) (string, error) {
+		return callMCPToolReturnTextOnServer(rctx, "drive", "get_upload_info", step1Args)
+	}, filePath, fileSize)
 	if err != nil {
 		return err
 	}
-	if err := httpPutFile(ctx, resourceURL, headers, filePath, fileSize); err != nil {
-		return err
-	}

 	commitArgs := map[string]any{
 		"fileName": fileName,
@@ -2219,3 +2295,49 @@ func isPermissionCLIError(err error) bool {
 	var patErr *PATError
 	return errors.As(err, &patErr)
 }
+
+// parseDriveDownloadInfo 从 drive 的 download_file 返回里取下载 URL 与请求头。
+// drive 返回形如 {"result":{"downloadUrl":"https://..."}}；OSS 预签名 URL 自带签名参数、
+// 无额外请求头；中心协议（httpToCenterWithToken）返回的 headers 含 dentry-token，
+// 需原样透传。对历史字段名（resourceUrl / resourceUrls[].url）做 fallback。
+func parseDriveDownloadInfo(text string) (string, map[string]string, error) {
+	var data map[string]any
+	if err := json.Unmarshal([]byte(text), &data); err != nil {
+		return "", nil, fmt.Errorf("解析 download_file 返回失败: %w", err)
+	}
+	if result, ok := data["result"].(map[string]any); ok {
+		data = result
+	}
+
+	headers := make(map[string]string)
+	if h, ok := data["headers"].(map[string]any); ok {
+		for k, v := range h {
+			if s, ok := v.(string); ok {
+				headers[k] = s
+			}
+		}
+	}
+
+	dlURL, _ := data["downloadUrl"].(string)
+	if dlURL == "" {
+		dlURL, _ = data["resourceUrl"].(string)
+	}
+	if dlURL == "" {
+		if arr, ok := data["resourceUrls"].([]any); ok && len(arr) > 0 {
+			if first, ok := arr[0].(map[string]any); ok {
+				dlURL, _ = first["url"].(string)
+				if h, ok := first["headers"].(map[string]any); ok {
+					for k, v := range h {
+						if s, ok := v.(string); ok {
+							headers[k] = s
+						}
+					}
+				}
+			}
+		}
+	}
+	if dlURL == "" {
+		return "", nil, fmt.Errorf("download_file 未返回下载链接（downloadUrl 为空）")
+	}
+	return dlURL, headers, nil
+}
@@ -0,0 +1,847 @@
+package helpers
+
+// ──────────────────────────────────────────────────────────
+// drive 传输增强：中心协议（token 化凭证）+ 分片下载（Range）
+//
+// 下载：文件大小 ≥ 2×part-size 时自动分片并发下载（对齐 aws s3 cp /
+// ossutil 惯例），断点续传默认开启（<dest>.dwspart 临时文件 + checkpoint
+// 元信息），服务端不支持 Range 时自动回退整流；401/403（凭证过期）自动
+// 重新调用 MCP 取新凭证后续传。
+// 上传：中心协议（uploadType=httpToCenterWithToken）与 OSS 走同一 PUT
+// 路径（URL 服务端拼好、headers 透传、客户端零追加），401/403 重取凭证
+// 重试一次；服务端超限错误补充可读提示。
+// ──────────────────────────────────────────────────────────
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const (
+	driveDownloadDefaultPartSize = 16 * 1024 * 1024 // --part-size 默认 16MB
+	driveDownloadMinPartSize     = 1 * 1024 * 1024
+	driveDownloadMaxPartSize     = 1024 * 1024 * 1024
+	driveDownloadDefaultParallel = 4
+	driveDownloadMaxParallel     = 8
+	// 单分片常规失败指数退避重试次数（不含 401/403 凭证刷新）。
+	driveDownloadPartRetries = 3
+	// 单分片 401/403 凭证刷新重试上限（防止无效凭证死循环）。
+	driveDownloadPartAuthRetries = 2
+
+	drivePartFileSuffix     = ".dwspart"
+	drivePartMetaSuffix     = ".dwspart.meta"
+	driveCheckpointVersion  = 1
+	uploadTypeCenterToken   = "httpToCenterWithToken"
+	driveTransferBodyErrCap = 2048 // 错误响应 body 截断长度
+)
+
+// driveRangeClient 分片下载/探测专用 HTTP 客户端。
+// 整流路径仍走可注入的 httpGetFile，保持既有测试注入点不变。
+var driveRangeClient = &http.Client{Timeout: 10 * time.Minute}
+
+// errCredentialRefreshVersionUnknown 凭证刷新后无法验证文件版本一致性（双方之一
+// version=0），激进策略要求清空已完成分片从头下载。
+var errCredentialRefreshVersionUnknown = errors.New("凭证刷新后无法验证文件版本一致性，需从头下载")
+
+// Testable OS operation hooks (package-level for coverage injection).
+var (
+	driveJsonMarshal  = json.Marshal
+	driveOsRename     = os.Rename
+	driveFileTruncate = (*os.File).Truncate
+	driveFileSync     = (*os.File).Sync
+	driveFileStat     = (*os.File).Stat
+)
+
+// ──────────────────────────────────────────────────────────
+// HTTP 状态错误
+// ──────────────────────────────────────────────────────────
+
+// httpStatusError 表示非 2xx 的 HTTP 响应，供上层按状态码分支（401/403 重取凭证等）。
+type httpStatusError struct {
+	StatusCode int
+	Body       string
+}
+
+func (e *httpStatusError) Error() string {
+	return fmt.Sprintf("HTTP %d: %s", e.StatusCode, e.Body)
+}
+
+// isAuthStatusError 判断错误是否为 401/403（凭证过期/无效）。
+// 兼容 typed httpStatusError 与文本形态（测试注入或历史包装的 "HTTP 401/403" 错误）。
+func isAuthStatusError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var se *httpStatusError
+	if errors.As(err, &se) {
+		return se.StatusCode == http.StatusUnauthorized || se.StatusCode == http.StatusForbidden
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "HTTP 401") || strings.Contains(msg, "HTTP 403")
+}
+
+// ──────────────────────────────────────────────────────────
+// 参数解析
+// ──────────────────────────────────────────────────────────
+
+// parsePartSize 解析 --part-size 的人类可读值（16MB、512KB、1GB；纯数字按字节）。
+func parsePartSize(s string) (int64, error) {
+	v := strings.TrimSpace(strings.ToUpper(s))
+	if v == "" {
+		return 0, fmt.Errorf("--part-size 不能为空（示例: 16MB、512KB、1GB）")
+	}
+	unit := int64(1)
+	switch {
+	case strings.HasSuffix(v, "GB"):
+		unit, v = 1<<30, strings.TrimSuffix(v, "GB")
+	case strings.HasSuffix(v, "MB"):
+		unit, v = 1<<20, strings.TrimSuffix(v, "MB")
+	case strings.HasSuffix(v, "KB"):
+		unit, v = 1<<10, strings.TrimSuffix(v, "KB")
+	case strings.HasSuffix(v, "G"):
+		unit, v = 1<<30, strings.TrimSuffix(v, "G")
+	case strings.HasSuffix(v, "M"):
+		unit, v = 1<<20, strings.TrimSuffix(v, "M")
+	case strings.HasSuffix(v, "K"):
+		unit, v = 1<<10, strings.TrimSuffix(v, "K")
+	case strings.HasSuffix(v, "B"):
+		v = strings.TrimSuffix(v, "B")
+	}
+	n, err := strconv.ParseInt(strings.TrimSpace(v), 10, 64)
+	if err != nil || n <= 0 {
+		return 0, fmt.Errorf("--part-size 格式非法: %q（示例: 16MB、512KB、1GB）", s)
+	}
+	size := n * unit
+	if size < driveDownloadMinPartSize || size > driveDownloadMaxPartSize {
+		return 0, fmt.Errorf("--part-size 取值范围 %s - %s，当前值: %s",
+			formatByteSize(driveDownloadMinPartSize), formatByteSize(driveDownloadMaxPartSize), s)
+	}
+	return size, nil
+}
+
+func formatByteSize(n int64) string {
+	switch {
+	case n >= 1<<30 && n%(1<<30) == 0:
+		return fmt.Sprintf("%dGB", n/(1<<30))
+	case n >= 1<<20 && n%(1<<20) == 0:
+		return fmt.Sprintf("%dMB", n/(1<<20))
+	case n >= 1<<10 && n%(1<<10) == 0:
+		return fmt.Sprintf("%dKB", n/(1<<10))
+	default:
+		return fmt.Sprintf("%dB", n)
+	}
+}
+
+// driveDownloadOptions 分片下载选项（由 drive download 的 flag 解析而来）。
+type driveDownloadOptions struct {
+	partSize  int64
+	parallel  int
+	resume    bool
+	knownSize int64  // MCP 返回的 fileSize；未知(0)或小于阈值时直接整流
+	nodeID    string // 节点唯一标识（dentryUuid），用于生成 checkpoint 指纹
+	version   int    // 文件版本号；0 表示最新版
+	logf      func(format string, args ...any)
+}
+
+// driveDownloadOptionsFromFlags 解析并校验 --part-size / --parallel / --no-resume。
+func driveDownloadOptionsFromFlags(cmd *cobra.Command) (driveDownloadOptions, error) {
+	raw, _ := cmd.Flags().GetString("part-size")
+	partSize, err := parsePartSize(raw)
+	if err != nil {
+		return driveDownloadOptions{}, err
+	}
+	parallel, _ := cmd.Flags().GetInt("parallel")
+	if parallel < 1 || parallel > driveDownloadMaxParallel {
+		return driveDownloadOptions{}, fmt.Errorf("--parallel 取值范围 1-%d，当前值: %d", driveDownloadMaxParallel, parallel)
+	}
+	noResume, _ := cmd.Flags().GetBool("no-resume")
+	return driveDownloadOptions{partSize: partSize, parallel: parallel, resume: !noResume}, nil
+}
+
+// parseDownloadFileSize 从 download_file 返回中提取 fileSize（缺失/非法返回 0）。
+func parseDownloadFileSize(text string) int64 {
+	var data map[string]any
+	if json.Unmarshal([]byte(text), &data) != nil {
+		return 0
+	}
+	if r, ok := data["result"].(map[string]any); ok {
+		data = r
+	}
+	switch v := data["fileSize"].(type) {
+	case float64:
+		return int64(v)
+	case string:
+		n, _ := strconv.ParseInt(v, 10, 64)
+		return n
+	}
+	return 0
+}
+
+// parseDownloadFileVersion 从 MCP download_file 响应中提取文件当前版本号。
+// 返回 0 表示未获取到（兼容旧版 MCP 不返回 version 的场景）。
+func parseDownloadFileVersion(text string) int {
+	var data map[string]any
+	if json.Unmarshal([]byte(text), &data) != nil {
+		return 0
+	}
+	if r, ok := data["result"].(map[string]any); ok {
+		data = r
+	}
+	switch v := data["version"].(type) {
+	case float64:
+		return int(v)
+	case string:
+		n, _ := strconv.Atoi(v)
+		return n
+	}
+	return 0
+}
+
+// ──────────────────────────────────────────────────────────
+// 凭证状态（分片过程共享，401/403 时 single-flight 刷新）
+// ──────────────────────────────────────────────────────────
+
+// driveCredentialFetcher 重新调用 MCP 获取下载 URL + headers（含 dentry-token）。
+type driveCredentialFetcher func(ctx context.Context) (url string, headers map[string]string, version int, err error)
+
+type driveCredentialState struct {
+	mu             sync.Mutex
+	fetch          driveCredentialFetcher
+	url            string
+	headers        map[string]string
+	gen            int
+	initialVersion int // 首次获取的文件版本号；0 表示未知（兼容旧 MCP）
+}
+
+func (cs *driveCredentialState) current() (string, map[string]string, int) {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+	return cs.url, cs.headers, cs.gen
+}
+
+// refresh 重取凭证。仅当调用方持有的 generation 仍是最新时才真正重取
+// （其他并发分片已刷新过则直接复用新凭证，避免重复 MCP 调用）。
+func (cs *driveCredentialState) refresh(ctx context.Context, gen int) error {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+	if cs.gen > gen {
+		return nil // 已被其他分片刷新
+	}
+	if cs.fetch == nil {
+		return fmt.Errorf("下载凭证已过期且无法自动刷新")
+	}
+	url, headers, version, err := cs.fetch(ctx)
+	if err != nil {
+		return err
+	}
+	// 版本校验
+	if cs.initialVersion > 0 && version > 0 {
+		if version != cs.initialVersion {
+			// 双方版本已知且不同 → 文件已被覆盖，终止下载防止数据不一致
+			return fmt.Errorf("下载凭证刷新后文件版本已变更（%d → %d），终止下载以防数据不一致", cs.initialVersion, version)
+		}
+		// 版本一致，正常继续
+	} else {
+		// 激进策略：版本不可验证（至少一方为 0），更新凭证但返回特殊错误
+		// 让上层清空已完成分片从头下载
+		cs.url, cs.headers = url, headers
+		cs.gen++
+		return errCredentialRefreshVersionUnknown
+	}
+	cs.url, cs.headers = url, headers
+	cs.gen++
+	return nil
+}
+
+// ──────────────────────────────────────────────────────────
+// 下载入口：整流 / 分片自动分派
+// ──────────────────────────────────────────────────────────
+
+// driveTransferDownload 下载入口：按文件大小自动选择整流或分片下载。
+//   - 文件大小未知（MCP 未返回 fileSize）或 < 2×partSize → 直接整流
+//     （复用可注入的 httpGetFile，保持存量行为与测试注入边界不变，
+//     401/403 时重取凭证重试一次）；
+//   - 已知大小 ≥ 2×partSize → 首请求以 Range: bytes=0-0 探测：206 且解析出
+//     总长 → 分片下载；服务端返回 200（不支持 Range）→ 直接消费该响应整流落盘。
+func driveTransferDownload(ctx context.Context, fetch driveCredentialFetcher, rawURL string, headers map[string]string, destPath string, opts driveDownloadOptions) error {
+	if opts.partSize <= 0 {
+		opts.partSize = driveDownloadDefaultPartSize
+	}
+	if opts.parallel <= 0 {
+		opts.parallel = driveDownloadDefaultParallel
+	}
+	threshold := 2 * opts.partSize
+	if opts.knownSize < threshold {
+		// 含 knownSize==0（大小未知）：不发起额外探测请求，保持存量整流行为
+		return downloadSingleWithAuthRetry(ctx, fetch, rawURL, headers, destPath)
+	}
+
+	creds := &driveCredentialState{fetch: fetch, url: rawURL, headers: headers, initialVersion: opts.version}
+	totalSize, fullResp, err := probeRangeSupport(ctx, creds)
+	if err != nil {
+		return err
+	}
+	if fullResp != nil {
+		// 服务端不支持 Range（忽略探测请求头返回 200 全量流）：直接消费落盘
+		defer fullResp.Body.Close()
+		return writeStreamToFile(fullResp.Body, destPath)
+	}
+	curURL, curHeaders, _ := creds.current()
+	if totalSize <= 0 || totalSize < threshold {
+		// 总长未知（Content-Range 异常）或小于阈值：整流下载
+		return downloadSingleWithAuthRetry(ctx, func(fctx context.Context) (string, map[string]string, int, error) {
+			if fetch == nil {
+				return "", nil, 0, fmt.Errorf("下载凭证已过期且无法自动刷新")
+			}
+			return fetch(fctx)
+		}, curURL, curHeaders, destPath)
+	}
+	return downloadRangedParts(ctx, creds, destPath, totalSize, opts)
+}
+
+// downloadSingleWithAuthRetry 整流下载；401/403（凭证过期）时重新调用 MCP
+// 获取新 URL+token 重试一次，仍失败走既有错误路径。
+func downloadSingleWithAuthRetry(ctx context.Context, fetch driveCredentialFetcher, urlStr string, headers map[string]string, destPath string) error {
+	err := httpGetFile(ctx, urlStr, headers, destPath)
+	if err == nil || !isAuthStatusError(err) || fetch == nil {
+		return err
+	}
+	newURL, newHeaders, _, ferr := fetch(ctx)
+	if ferr != nil {
+		return err
+	}
+	return httpGetFile(ctx, newURL, newHeaders, destPath)
+}
+
+// probeRangeSupport 发送 Range: bytes=0-0 探测请求验证 206/Content-Range。
+// 返回 (totalSize, nil, nil) 表示支持 Range 且已知总长；
+// 返回 (0, resp, nil) 表示服务端忽略 Range 返回 200 全量响应（调用方直接消费）；
+// 401/403 时刷新凭证重试一次。
+func probeRangeSupport(ctx context.Context, creds *driveCredentialState) (int64, *http.Response, error) {
+	for attempt := 0; ; attempt++ {
+		urlStr, headers, gen := creds.current()
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, urlStr, nil)
+		if err != nil {
+			return 0, nil, err
+		}
+		for k, v := range headers {
+			req.Header.Set(k, v)
+		}
+		req.Header.Set("Range", "bytes=0-0")
+		resp, err := driveRangeClient.Do(req)
+		if err != nil {
+			return 0, nil, err
+		}
+		switch {
+		case resp.StatusCode == http.StatusPartialContent:
+			total, perr := parseContentRangeTotal(resp.Header.Get("Content-Range"))
+			_, _ = io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+			if perr != nil {
+				return 0, nil, nil // Content-Range 异常：总长未知，回退整流
+			}
+			return total, nil, nil
+		case resp.StatusCode == http.StatusOK:
+			return 0, resp, nil
+		case resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden:
+			body, _ := io.ReadAll(io.LimitReader(resp.Body, driveTransferBodyErrCap))
+			resp.Body.Close()
+			if attempt > 0 {
+				return 0, nil, fmt.Errorf("下载凭证刷新后仍鉴权失败")
+			}
+			if rerr := creds.refresh(ctx, gen); rerr != nil && !errors.Is(rerr, errCredentialRefreshVersionUnknown) {
+				return 0, nil, fmt.Errorf("重新获取下载凭证失败: %w (原错误: %v)",
+					rerr, &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)})
+			}
+			// errCredentialRefreshVersionUnknown 在探测阶段无需处理（尚无已完成分片）,
+			// 凭证已更新，循环继续用新凭证重试探测。
+		default:
+			body, _ := io.ReadAll(io.LimitReader(resp.Body, driveTransferBodyErrCap))
+			resp.Body.Close()
+			return 0, nil, &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)}
+		}
+	}
+}
+
+// parseContentRangeTotal 从 "bytes 0-0/12345" 解析总长；"*" 视为未知。
+func parseContentRangeTotal(cr string) (int64, error) {
+	idx := strings.LastIndex(cr, "/")
+	if idx < 0 || idx == len(cr)-1 {
+		return 0, fmt.Errorf("非法 Content-Range: %q", cr)
+	}
+	totalStr := cr[idx+1:]
+	if totalStr == "*" {
+		return 0, fmt.Errorf("Content-Range 总长未知: %q", cr)
+	}
+	total, err := strconv.ParseInt(totalStr, 10, 64)
+	if err != nil || total <= 0 {
+		return 0, fmt.Errorf("非法 Content-Range 总长: %q", cr)
+	}
+	return total, nil
+}
+
+// parseContentRange 解析 "bytes <start>-<end>/<total>" 格式的 Content-Range 头。
+// 返回值 start、end 为字节偏移（闭区间），total 为文件总长（"*" 视为 -1）。
+func parseContentRange(header string) (start, end, total int64, err error) {
+	if header == "" {
+		return 0, 0, 0, fmt.Errorf("Content-Range 为空")
+	}
+	// 去掉 "bytes " 前缀
+	const prefix = "bytes "
+	if !strings.HasPrefix(header, prefix) {
+		return 0, 0, 0, fmt.Errorf("非法 Content-Range 前缀: %q", header)
+	}
+	rest := header[len(prefix):] // e.g. "0-1048575/104857600"
+	// 按 "/" 分割范围与总长
+	slashIdx := strings.LastIndex(rest, "/")
+	if slashIdx < 0 || slashIdx == len(rest)-1 {
+		return 0, 0, 0, fmt.Errorf("非法 Content-Range 格式: %q", header)
+	}
+	rangePart := rest[:slashIdx]   // "0-1048575"
+	totalPart := rest[slashIdx+1:] // "104857600" 或 "*"
+	// 解析 total
+	if totalPart == "*" {
+		total = -1
+	} else {
+		total, err = strconv.ParseInt(totalPart, 10, 64)
+		if err != nil || total <= 0 {
+			return 0, 0, 0, fmt.Errorf("非法 Content-Range 总长: %q", header)
+		}
+	}
+	// 按 "-" 分割 start 和 end
+	dashIdx := strings.Index(rangePart, "-")
+	if dashIdx < 0 {
+		return 0, 0, 0, fmt.Errorf("非法 Content-Range 区间: %q", header)
+	}
+	start, err = strconv.ParseInt(rangePart[:dashIdx], 10, 64)
+	if err != nil || start < 0 {
+		return 0, 0, 0, fmt.Errorf("非法 Content-Range start: %q", header)
+	}
+	end, err = strconv.ParseInt(rangePart[dashIdx+1:], 10, 64)
+	if err != nil || end < start {
+		return 0, 0, 0, fmt.Errorf("非法 Content-Range end: %q", header)
+	}
+	return start, end, total, nil
+}
+
+func writeStreamToFile(r io.Reader, destPath string) error {
+	out, err := os.Create(destPath)
+	if err != nil {
+		return err
+	}
+	defer out.Close()
+	if _, err := io.Copy(out, r); err != nil {
+		return err
+	}
+	return nil
+}
+
+// ──────────────────────────────────────────────────────────
+// 分片切分与 checkpoint
+// ──────────────────────────────────────────────────────────
+
+type driveDownloadPart struct {
+	index  int
+	offset int64
+	length int64
+}
+
+// splitDownloadParts 按 partSize 等长切片，末片为余量。
+func splitDownloadParts(totalSize, partSize int64) []driveDownloadPart {
+	if totalSize <= 0 || partSize <= 0 {
+		return nil
+	}
+	count := int((totalSize + partSize - 1) / partSize)
+	parts := make([]driveDownloadPart, 0, count)
+	for i := 0; i < count; i++ {
+		offset := int64(i) * partSize
+		length := partSize
+		if offset+length > totalSize {
+			length = totalSize - offset
+		}
+		parts = append(parts, driveDownloadPart{index: i, offset: offset, length: length})
+	}
+	return parts
+}
+
+// driveDownloadCheckpoint 断点续传元信息，随每个分片完成原子落盘。
+type driveDownloadCheckpoint struct {
+	Version     int    `json:"version"`
+	Fingerprint string `json:"fingerprint"`
+	TotalSize   int64  `json:"totalSize"`
+	PartSize    int64  `json:"partSize"`
+	Completed   []bool `json:"completed"`
+}
+
+// driveDownloadFingerprint 基于节点 ID + 版本号 + 文件总长 + 资源 URL 计算指纹。
+// version>0 时只取 URL path（重签名不影响 checkpoint 复用）；version==0（最新版）时
+// 取完整 path+query——中心协议相同 path 可能对应不同实际版本，query 中的签名/token
+// 标识了具体资源快照，防止错误复用旧 checkpoint。
+// resourceURL 为空时不影响其他字段的指纹计算（安全降级）。
+func driveDownloadFingerprint(nodeID string, version int, totalSize int64, resourceURL string) string {
+	urlComponent := ""
+	if resourceURL != "" {
+		if u, err := url.Parse(resourceURL); err == nil && u != nil {
+			if version == 0 {
+				// 最新版：含 query 以区分不同签名（不同实际版本）
+				urlComponent = u.RequestURI()
+			} else {
+				// 指定版本：只取 path，重签名不应废弃 checkpoint
+				urlComponent = u.Path
+			}
+		}
+	}
+	sum := sha256.Sum256([]byte(fmt.Sprintf("%s|%d|%d|%s", nodeID, version, totalSize, urlComponent)))
+	return hex.EncodeToString(sum[:])
+}
+
+// loadDriveDownloadCheckpoint 读取并校验 checkpoint；任一字段不匹配返回 nil（从头下载）。
+func loadDriveDownloadCheckpoint(metaPath, fingerprint string, totalSize, partSize int64, partCount int) *driveDownloadCheckpoint {
+	data, err := os.ReadFile(metaPath)
+	if err != nil {
+		return nil
+	}
+	var cp driveDownloadCheckpoint
+	if err := json.Unmarshal(data, &cp); err != nil {
+		return nil
+	}
+	if cp.Version != driveCheckpointVersion || cp.Fingerprint != fingerprint ||
+		cp.TotalSize != totalSize || cp.PartSize != partSize || len(cp.Completed) != partCount {
+		return nil
+	}
+	return &cp
+}
+
+// save 原子写入（临时文件 + rename），避免中断产生半截 checkpoint。
+func (cp *driveDownloadCheckpoint) save(metaPath string) error {
+	data, err := driveJsonMarshal(cp)
+	if err != nil {
+		return err
+	}
+	tmp := metaPath + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+		return err
+	}
+	return driveOsRename(tmp, metaPath)
+}
+
+// ──────────────────────────────────────────────────────────
+// 分片下载引擎
+// ──────────────────────────────────────────────────────────
+
+// downloadRangedParts 并发分片下载到 <dest>.dwspart，全部完成后校验总长并
+// 原子重命名为 destPath、清理 checkpoint；中途失败保留分片产物供断点续传。
+func downloadRangedParts(ctx context.Context, creds *driveCredentialState, destPath string, totalSize int64, opts driveDownloadOptions) error {
+	parts := splitDownloadParts(totalSize, opts.partSize)
+	partPath := destPath + drivePartFileSuffix
+	metaPath := destPath + drivePartMetaSuffix
+	// 取首次凭证 URL 用于指纹计算，防止同大小文件覆盖后 checkpoint 错误复用
+	initialURL, _, _ := creds.current()
+	fingerprint := driveDownloadFingerprint(opts.nodeID, opts.version, totalSize, initialURL)
+
+	var cp *driveDownloadCheckpoint
+	if opts.resume {
+		cp = loadDriveDownloadCheckpoint(metaPath, fingerprint, totalSize, opts.partSize, len(parts))
+		// 分片数据文件缺失或长度不符时 checkpoint 作废，从头下载
+		if cp != nil {
+			if fi, err := os.Stat(partPath); err != nil || fi.Size() != totalSize {
+				cp = nil
+			}
+		}
+	} else {
+		// --no-resume：清理历史断点产物，从头下载且不写 checkpoint
+		_ = os.Remove(partPath)
+		_ = os.Remove(metaPath)
+	}
+	if cp == nil {
+		cp = &driveDownloadCheckpoint{
+			Version:     driveCheckpointVersion,
+			Fingerprint: fingerprint,
+			TotalSize:   totalSize,
+			PartSize:    opts.partSize,
+			Completed:   make([]bool, len(parts)),
+		}
+	}
+
+	f, err := os.OpenFile(partPath, os.O_RDWR|os.O_CREATE, 0o644)
+	if err != nil {
+		return fmt.Errorf("创建分片临时文件失败: %w", err)
+	}
+	if err := driveFileTruncate(f, totalSize); err != nil {
+		f.Close()
+		return fmt.Errorf("预分配分片临时文件失败: %w", err)
+	}
+
+	remaining := 0
+	for _, p := range parts {
+		if !cp.Completed[p.index] {
+			remaining++
+		}
+	}
+	if opts.logf != nil {
+		if remaining < len(parts) {
+			opts.logf("断点续传: 共 %d 分片（%s/片，并发 %d），已完成 %d，续传 %d",
+				len(parts), formatByteSize(opts.partSize), opts.parallel, len(parts)-remaining, remaining)
+		} else {
+			opts.logf("分片下载: 共 %d 分片（%s/片，并发 %d）", len(parts), formatByteSize(opts.partSize), opts.parallel)
+		}
+	}
+
+	runCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	var (
+		mu       sync.Mutex // 保护 cp 与 checkpoint 落盘
+		wg       sync.WaitGroup
+		errOnce  sync.Once
+		firstErr error
+	)
+	fail := func(err error) {
+		errOnce.Do(func() {
+			firstErr = err
+			cancel()
+		})
+	}
+
+	jobs := make(chan driveDownloadPart)
+	workers := opts.parallel
+	if workers > remaining {
+		workers = remaining
+	}
+	if workers < 1 {
+		workers = 1
+	}
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for part := range jobs {
+				if runCtx.Err() != nil {
+					return
+				}
+				if err := downloadOnePart(runCtx, creds, f, part, totalSize); err != nil {
+					fail(fmt.Errorf("分片 %d/%d 下载失败: %w", part.index+1, len(parts), err))
+					return
+				}
+				mu.Lock()
+				cp.Completed[part.index] = true
+				var saveErr error
+				if opts.resume {
+					saveErr = cp.save(metaPath)
+				}
+				mu.Unlock()
+				if saveErr != nil {
+					fail(fmt.Errorf("写入下载断点信息失败: %w", saveErr))
+					return
+				}
+			}
+		}()
+	}
+
+dispatch:
+	for _, part := range parts {
+		if cp.Completed[part.index] {
+			continue
+		}
+		select {
+		case jobs <- part:
+		case <-runCtx.Done():
+			break dispatch
+		}
+	}
+	close(jobs)
+	wg.Wait()
+
+	if firstErr != nil {
+		f.Close()
+		if errors.Is(firstErr, errCredentialRefreshVersionUnknown) {
+			// 激进策略：版本不可验证，清空 checkpoint 和分片文件防止错误续传；
+			// 用户重跑时将自然从头下载。
+			_ = os.Remove(metaPath)
+			_ = os.Remove(partPath)
+		}
+		return firstErr // 其他错误保留 .dwspart 与 checkpoint，重跑同一命令自动续传
+	}
+	if err := driveFileSync(f); err != nil {
+		f.Close()
+		return err
+	}
+	fi, statErr := driveFileStat(f)
+	f.Close()
+	if statErr != nil {
+		return statErr
+	}
+	if fi.Size() != totalSize {
+		return fmt.Errorf("下载完成但文件长度不符: got %d, want %d", fi.Size(), totalSize)
+	}
+	if err := driveOsRename(partPath, destPath); err != nil {
+		return fmt.Errorf("重命名下载文件失败: %w", err)
+	}
+	_ = os.Remove(metaPath)
+	return nil
+}
+
+// downloadOnePart 下载单个分片：常规失败指数退避重试 driveDownloadPartRetries 次；
+// 401/403 触发凭证 single-flight 刷新（不计入常规重试，上限 driveDownloadPartAuthRetries），
+// 刷新后用新凭证续传，不重下其他已完成分片。
+func downloadOnePart(ctx context.Context, creds *driveCredentialState, f *os.File, part driveDownloadPart, totalSize int64) error {
+	attempt := 0
+	authRetries := 0
+	backoff := 500 * time.Millisecond
+	for {
+		urlStr, headers, gen := creds.current()
+		err := fetchRangeInto(ctx, urlStr, headers, f, part, totalSize)
+		if err == nil {
+			return nil
+		}
+		if ctx.Err() != nil {
+			return err
+		}
+		if isAuthStatusError(err) && authRetries < driveDownloadPartAuthRetries {
+			authRetries++
+			if rerr := creds.refresh(ctx, gen); rerr != nil {
+				return fmt.Errorf("重新获取下载凭证失败: %w (原错误: %v)", rerr, err)
+			}
+			continue // 凭证刷新不计常规重试、不退避
+		}
+		attempt++
+		if attempt > driveDownloadPartRetries {
+			return err
+		}
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return err
+		}
+		backoff *= 2
+	}
+}
+
+// fetchRangeInto 拉取 [offset, offset+length) 区间并写入文件对应偏移。
+func fetchRangeInto(ctx context.Context, urlStr string, headers map[string]string, f *os.File, part driveDownloadPart, expectedTotal int64) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, urlStr, nil)
+	if err != nil {
+		return err
+	}
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	req.Header.Set("Range", fmt.Sprintf("bytes=%d-%d", part.offset, part.offset+part.length-1))
+	resp, err := driveRangeClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusPartialContent {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, driveTransferBodyErrCap))
+		return &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)}
+	}
+	// 校验 Content-Range 响应区间与请求分片一致，防止代理/服务端返回错位数据
+	cr := resp.Header.Get("Content-Range")
+	if cr == "" {
+		return fmt.Errorf("分片响应缺少 Content-Range 头，无法验证数据偏移一致性")
+	}
+	{
+		crStart, crEnd, crTotal, crErr := parseContentRange(cr)
+		if crErr != nil {
+			return fmt.Errorf("Content-Range 解析失败: %w", crErr)
+		}
+		wantStart := part.offset
+		wantEnd := part.offset + part.length - 1
+		if crStart != wantStart || crEnd != wantEnd {
+			return fmt.Errorf("Content-Range 区间不匹配: 响应 %d-%d, 期望 %d-%d",
+				crStart, crEnd, wantStart, wantEnd)
+		}
+		if crTotal > 0 && expectedTotal > 0 && crTotal != expectedTotal {
+			return fmt.Errorf("Content-Range 总长不匹配: 响应 %d, 期望 %d", crTotal, expectedTotal)
+		}
+	}
+	n, err := io.Copy(io.NewOffsetWriter(f, part.offset), io.LimitReader(resp.Body, part.length))
+	if err != nil {
+		return err
+	}
+	if n != part.length {
+		return fmt.Errorf("分片长度不符: got %d, want %d", n, part.length)
+	}
+	return nil
+}
+
+// ──────────────────────────────────────────────────────────
+// 上传：中心协议识别 + 401/403 重试 + 超限可读提示
+// ──────────────────────────────────────────────────────────
+
+// parseDriveUploadType 提取 get_upload_info 返回中的 uploadType（可选字段）。
+// "httpToCenterWithToken" 表示中心协议；存量 OSS 返回无该字段，返回空串。
+func parseDriveUploadType(text string) string {
+	var data map[string]any
+	if json.Unmarshal([]byte(text), &data) != nil {
+		return ""
+	}
+	if r, ok := data["result"].(map[string]any); ok {
+		data = r
+	}
+	t, _ := data["uploadType"].(string)
+	return t
+}
+
+// decorateUploadSizeError 为服务端上传超限错误补充可读提示。
+// 不做本地文件大小上限校验（上限为服务端动态权益值，本地硬编码会漂移）。
+func decorateUploadSizeError(err error, uploadType string) error {
+	var se *httpStatusError
+	if !errors.As(err, &se) {
+		return err
+	}
+	if se.StatusCode == http.StatusRequestEntityTooLarge ||
+		(uploadType == uploadTypeCenterToken && likelySizeLimitBody(se.Body)) {
+		return fmt.Errorf("%w\n提示: 文件大小可能超出空间容量或上传上限，请确认文件大小、清理空间或联系管理员调整容量后重试", err)
+	}
+	return err
+}
+
+func likelySizeLimitBody(body string) bool {
+	b := strings.ToLower(body)
+	if strings.Contains(b, "超限") || strings.Contains(b, "超出") || strings.Contains(b, "容量") {
+		return true
+	}
+	return strings.Contains(b, "size") && (strings.Contains(b, "limit") || strings.Contains(b, "exceed") || strings.Contains(b, "over"))
+}
+
+// driveUploadPut 解析上传凭证并执行 HTTP PUT；401/403（token 过期）时通过 refetch
+// 重新获取凭证重试一次。返回最终生效凭证的 uploadId（凭证刷新后以新值为准）。
+// 中心协议（uploadType=httpToCenterWithToken）与 OSS 走同一路径：resourceUrl 为
+// 服务端拼好的完整 PUT URL（客户端零追加），headers（含 dentry-token）原样透传。
+func driveUploadPut(ctx context.Context, credText string, refetch func(context.Context) (string, error), filePath string, fileSize int64) (string, error) {
+	resourceURL, uploadID, headers, err := parseDriveUploadInfo(credText)
+	if err != nil {
+		return "", err
+	}
+	uploadType := parseDriveUploadType(credText)
+	putErr := httpPutFile(ctx, resourceURL, headers, filePath, fileSize)
+	if putErr != nil && isAuthStatusError(putErr) && refetch != nil {
+		text2, rerr := refetch(ctx)
+		if rerr == nil {
+			if url2, id2, headers2, perr := parseDriveUploadInfo(text2); perr == nil {
+				uploadID = id2
+				uploadType = parseDriveUploadType(text2)
+				putErr = httpPutFile(ctx, url2, headers2, filePath, fileSize)
+			}
+		}
+	}
+	if putErr != nil {
+		return "", decorateUploadSizeError(putErr, uploadType)
+	}
+	return uploadID, nil
+}
@@ -55,12 +55,15 @@ Host-owned PAT 开关：
  由宿主处理全部 UI / 交互 / 回调节奏 / 重试逻辑，
  CLI 侧不再拉起任何本地浏览器 / 轮询。

-服务端 Agent 产品标签 claw-type：
-  开源构建默认在出站 MCP 请求中注入 claw-type: openClaw。
-  如设置 DWS_AGENT_PRODUCT，则使用经校验的环境变量值覆盖该默认值。
-  hostControl.clawType 会回填请求实际使用的值，避免 PAT 与请求标识漂移。
-  该值由调用方声明，不是认证凭据；服务端不得仅凭它放权或跳过授权。
-  它也不会修改 IM 消息展示使用的 clawType 参数或 --ai-tag 行为。
+服务端 PAT / 路由标签 claw-type：
+  开源构建固定在出站 MCP 请求中注入 claw-type: openClaw，
+  hostControl.clawType 会回填相同值。DWS_AGENT_PRODUCT 不会修改它。
+
+Agent 产品标识 DWS_AGENT_PRODUCT：
+  合法非空值作为 x-dws-agent-product 请求头发送，供下游日志 / BI 使用；
+  本客户端不使用该值派生或改变 PAT、鉴权或路由，下游使用契约由对应
+  服务自行定义。同时该值作为启用 --ai-tag 时 IM 消息小尾巴的 clawType
+  参数。未设置或为空时请求头省略，小尾巴回退发行版默认值。

 DINGTALK_AGENT（可选，仅供 x-dingtalk-agent 使用）：
  如设置，将原样注入 HTTP 请求头 x-dingtalk-agent，
@@ -24,6 +24,7 @@ import (

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -99,6 +100,8 @@ func newPlatformCoverageRoot() *cobra.Command {
 }

 func TestCrossPlatformCoverageAIMessageTag(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "qwenwork")
+
 	tests := []struct {
 		name string
 		argv []string
@@ -125,8 +128,8 @@ func TestCrossPlatformCoverageAIMessageTag(t *testing.T) {
 			if send.product != "chat" || send.tool != "send_personal_message" {
 				t.Fatalf("last call = %s/%s, want chat/send_personal_message", send.product, send.tool)
 			}
-			if got := send.args["clawType"]; got != edition.ClawType() {
-				t.Fatalf("clawType = %#v, want %q", got, edition.ClawType())
+			if got := send.args["clawType"]; got != "qwenwork" {
+				t.Fatalf("clawType = %#v, want qwenwork", got)
 			}
 		})
 	}
@@ -12,7 +12,7 @@
 // limitations under the License.

 // Package agentproduct defines the caller-provided Agent product identity
-// carried on outbound DWS requests.
+// used for outbound observability and IM message display.
 package agentproduct

 import (
@@ -25,8 +25,9 @@ import (
 const (
 	// EnvName is the runtime override for the Agent product identity.
 	EnvName = "DWS_AGENT_PRODUCT"
-	// HeaderName is the existing wire header used for the Agent product.
-	HeaderName = "claw-type"
+	// HeaderName is the observability header used for the Agent product.
+	// It is intentionally separate from the routing/PAT claw-type header.
+	HeaderName = "x-dws-agent-product"
 	// MaxValueBytes bounds the value because it is attached to every outbound
 	// MCP request. Supported values are ASCII, so bytes and characters match.
 	MaxValueBytes = 64
@@ -103,3 +103,12 @@ func TestResolveFromEnv(t *testing.T) {
 		}
 	})
 }
+
+func TestHeaderNameIsSeparateFromClawType(t *testing.T) {
+	if HeaderName != "x-dws-agent-product" {
+		t.Fatalf("HeaderName = %q, want x-dws-agent-product", HeaderName)
+	}
+	if HeaderName == "claw-type" {
+		t.Fatal("Agent Product observability Header must not reuse claw-type")
+	}
+}
@@ -15,18 +15,18 @@ package edition

 import "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/syncdata"

-// DefaultOSSClawType is the default wire value for request header claw-type
-// in the open-source build. DWS_AGENT_PRODUCT may explicitly override the
-// request identity; unrelated caller inputs such as DINGTALK_AGENT do not.
+// DefaultOSSClawType is the fixed wire value for request header claw-type in
+// the open-source build. It is intentionally independent of caller-provided
+// environment variables so PAT and routing behaviour stays predictable.
 const DefaultOSSClawType = "openClaw"

 // defaultHooks returns the open-source edition defaults.
 //
 // MergeHeaders is the only hook that ships with behaviour: it supplies
 // DefaultOSSClawType so every open-source MCP request has a stable default.
-// The core applies an optional DWS_AGENT_PRODUCT override after edition hooks.
-// All other fields are nil — the internal code interprets nil as "use
-// standard open-source behaviour".
+// DWS_AGENT_PRODUCT is sent through a separate observability Header and never
+// changes claw-type. All other fields are nil — the internal code interprets
+// nil as "use standard open-source behaviour".
 func defaultHooks() *Hooks {
 	return &Hooks{
 		Name: "open",
@@ -21,6 +21,7 @@ import (
 	"context"
 	"sync"

+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/spf13/cobra"
 )

@@ -87,10 +88,10 @@ type Hooks struct {

 	// ClawTypeValue is the display identity carried only in message-send tool
 	// arguments (parameter clawType) so the IM server can render the
-	// "Send from AI" indicator on delivered messages. It is intentionally
-	// separate from the HTTP claw-type Agent Product header and is not
-	// overridden by DWS_AGENT_PRODUCT. Empty → DefaultOSSClawType; overlays
-	// set their own message-display value (e.g. "wukong").
+	// "Send from AI" indicator on delivered messages. A valid non-empty
+	// DWS_AGENT_PRODUCT overrides this display default, but never the separate
+	// HTTP claw-type routing/PAT header. Empty → DefaultOSSClawType; overlays
+	// set their own message-display default (e.g. "wukong").
 	ClawTypeValue string

 	// PersonalEventSourceID identifies the personal-event source channel
@@ -115,8 +116,8 @@ type Hooks struct {
 	MergeHeaders func(base map[string]string) map[string]string

 	// --- EnterpriseCredential HTTP headers ---
-	// This hook is only for credential material. It must not set claw-type;
-	// the core reasserts that Header after the hook returns.
+	// This hook is only for credential material. It must not set claw-type or
+	// x-dws-agent-product; the core reasserts both after the hook returns.
 	EnterpriseCredentialHeaders func(base map[string]string) map[string]string

 	// --- auth ---
@@ -206,16 +207,22 @@ func Override(h *Hooks) {
 	current = h
 }

-// ClawType returns the message-display identity for the active edition,
-// falling back to DefaultOSSClawType when the overlay does not set one.
-// Message-send helpers attach this value as the clawType tool argument so the
-// IM server can label delivered messages as sent via AI. It is a separate axis
-// from the HTTP claw-type header and is not affected by DWS_AGENT_PRODUCT.
+// ClawType returns the message-display identity for the active edition.
+// A valid non-empty DWS_AGENT_PRODUCT wins; otherwise the active edition's
+// ClawTypeValue (or DefaultOSSClawType) is used. Message-send helpers attach
+// this value as the clawType tool argument so the IM server can label delivered
+// messages as sent via AI. It never changes the HTTP claw-type routing/PAT
+// header.
 func ClawType() string {
-	if v := Get().ClawTypeValue; v != "" {
-		return v
+	fallback := Get().ClawTypeValue
+	if fallback == "" {
+		fallback = DefaultOSSClawType
 	}
-	return DefaultOSSClawType
+	value, err := agentproduct.ResolveFromEnv(fallback)
+	if err != nil {
+		return fallback
+	}
+	return value
 }

 // PersonalEventSourceID returns the source channel for user-level events.
@@ -13,9 +13,14 @@

 package edition

-import "testing"
+import (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
+)

 func TestClawTypeDefaultsToOSSValue(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "")
 	prev := Get()
 	defer Override(prev)

@@ -26,6 +31,7 @@ func TestClawTypeDefaultsToOSSValue(t *testing.T) {
 }

 func TestClawTypeUsesOverlayValue(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "")
 	prev := Get()
 	defer Override(prev)

@@ -35,6 +41,28 @@ func TestClawTypeUsesOverlayValue(t *testing.T) {
 	}
 }

+func TestClawTypeUsesValidAgentProduct(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, " qwenwork ")
+	prev := Get()
+	defer Override(prev)
+
+	Override(&Hooks{Name: "overlay", ClawTypeValue: "wukong"})
+	if got := ClawType(); got != "qwenwork" {
+		t.Fatalf("ClawType() = %q, want qwenwork", got)
+	}
+}
+
+func TestClawTypeInvalidAgentProductFallsBackToOverlay(t *testing.T) {
+	t.Setenv(agentproduct.EnvName, "qwen work")
+	prev := Get()
+	defer Override(prev)
+
+	Override(&Hooks{Name: "overlay", ClawTypeValue: "wukong"})
+	if got := ClawType(); got != "wukong" {
+		t.Fatalf("ClawType() = %q, want overlay fallback wukong", got)
+	}
+}
+
 func TestOpenStaticServersIncludesCoreProducts(t *testing.T) {
 	servers := openStaticServers()
 	byID := make(map[string]ServerInfo, len(servers))
@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
-"""Generate shortcut sections for DWS skills.
+"""Generate shortcut discovery sections for DWS skills.

 The skill should teach agents which high-level shortcut entries are available
-in the public catalog and Runtime Schema. Leaf Schema publishes the Agent
-contract, while leaf `--help` remains the source of truth for accepted flags.
+without forcing large product catalogs into every common task. Leaf Schema
+publishes the Agent contract, while leaf `--help` remains the source of truth
+for accepted flags.
 """

 from __future__ import annotations

+import argparse
 import json
 import os
 import sys
@@ -47,6 +49,13 @@ MONO_END = "<!-- VISIBLE_SHORTCUTS_OVERVIEW_END -->"
 PRODUCT_START = "<!-- VISIBLE_SHORTCUTS_START -->"
 PRODUCT_END = "<!-- VISIBLE_SHORTCUTS_END -->"

+# Large, high-frequency product skills should route known intents directly and
+# keep their full shortcut inventory in Runtime Catalog/Schema. Add services
+# here only after verifying that the product skill has its own reviewed routing
+# section and intent table; compacting a sparse skill without an alternative
+# route would make its shortcuts harder to discover.
+COMPACT_PRODUCT_SERVICES = {"chat"}
+

 def md_escape(value: Any) -> str:
    text = str(value or "")
@@ -90,21 +99,24 @@ def mono_overview(items: list[dict[str, Any]]) -> str:
        path = SERVICE_TO_SKILL.get(service)
        skill = "—"
        if path:
-            skill = next((part for part in path.parts if part.startswith("dingtalk-")), path.parent.name)
-        rows.append(f"| `{md_escape(service)}` | {count} | `{md_escape(skill)}` | `dws shortcut list --service {md_escape(service)} --format json` |")
+            skill = next((part for part in reversed(path.parts) if part.startswith("dingtalk-")), path.parent.name)
+        rows.append(f"| `{md_escape(service)}` | {count} | `{md_escape(skill)}` |")
    body = "\n".join(rows)
    return f"""{MONO_START}
 ## Shortcut 总览

-下面统计当前公开 catalog 中的 shortcut。mono 模式不展开 200+ 行明细，避免 skill 过重；需要执行时先按产品路由，再用 `dws shortcut list --service <service> --format json` 读取参数、约束、风险和示例，最后用 `dws <service> +<shortcut> --help` 核对当前 Cobra flags。multi 模式的各产品 skill 会展开该产品的 shortcut 表。
+下面只统计当前公开 catalog 中的 shortcut，不展开完整明细。已知意图应先按产品 Skill、意图表或任务 reference 选择唯一命令；命令已选中时直接执行，只在参数或安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service <service> --format json` 做最后回退；不要为已知高频意图加载完整产品 Catalog。

-| 服务 | shortcut 数 | multi skill | 发现命令 |
-|---|---:|---|---|
+| 服务 | shortcut 数 | multi skill |
+|---|---:|---|
 {body}
 {MONO_END}"""


 def product_section(service: str, rows: list[dict[str, Any]]) -> str:
+    if service in COMPACT_PRODUCT_SERVICES:
+        return compact_product_section(service, rows)
+
    table = []
    for item in rows:
        table.append(
@@ -114,7 +126,7 @@ def product_section(service: str, rows: list[dict[str, Any]]) -> str:
    return f"""{PRODUCT_START}
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "{service} +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service {service} --format json` 批量发现；最后以 `dws {service} <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "{service} +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws {service} <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service {service} --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -122,17 +134,38 @@ def product_section(service: str, rows: list[dict[str, Any]]) -> str:
 {PRODUCT_END}"""


-def update_mono(items: list[dict[str, Any]]) -> None:
+def compact_product_section(service: str, rows: list[dict[str, Any]]) -> str:
+    return f"""{PRODUCT_START}
+## Shortcut 发现（按需）
+
+`{md_escape(service)}` 当前有 {len(rows)} 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图直接使用下方的优先路由、意图表或任务 reference；命令已选中时直接执行，只在参数/安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。
+
+仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service {md_escape(service)} --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
+{PRODUCT_END}"""
+
+
+def apply_update(path: Path, text: str, updated: str, check: bool) -> bool:
+    if updated == text:
+        return False
+    if check:
+        print(f"generated skill drift: {path.relative_to(ROOT)}", file=sys.stderr)
+    else:
+        path.write_text(updated, encoding="utf-8")
+    return True
+
+
+def update_mono(items: list[dict[str, Any]], check: bool) -> list[Path]:
    text = MONO_SKILL.read_text(encoding="utf-8")
    block = mono_overview(items)
    updated = replace_block(text, MONO_START, MONO_END, block, "## 产品总览")
-    MONO_SKILL.write_text(updated, encoding="utf-8")
+    return [MONO_SKILL] if apply_update(MONO_SKILL, text, updated, check) else []


-def update_product_skills(items: list[dict[str, Any]]) -> None:
+def update_product_skills(items: list[dict[str, Any]], check: bool) -> list[Path]:
    by_service: dict[str, list[dict[str, Any]]] = defaultdict(list)
    for item in items:
        by_service[item["service"]].append(item)
+    changed = []
    for service, path in SERVICE_TO_SKILL.items():
        if service not in by_service:
            continue
@@ -142,13 +175,26 @@ def update_product_skills(items: list[dict[str, Any]]) -> None:
        block = product_section(service, by_service[service])
        anchor = "## 概念地图" if service == "devapp" else "## 意图表"
        updated = replace_block(text, PRODUCT_START, PRODUCT_END, block, anchor)
-        path.write_text(updated, encoding="utf-8")
+        if apply_update(path, text, updated, check):
+            changed.append(path)
+    return changed


 def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify generated skill sections are current without rewriting files",
+    )
+    args = parser.parse_args()
+
    items = collect_visible()
-    update_mono(items)
-    update_product_skills(items)
+    changed = update_mono(items, args.check)
+    changed.extend(update_product_skills(items, args.check))
+    if args.check and changed:
+        print("run: python3 scripts/gen_skill_shortcut_sections.py", file=sys.stderr)
+        return 1
    print(f"visible_shortcuts={len(items)} services={len(set(item['service'] for item in items))}")
    return 0

@@ -0,0 +1,41 @@
+#!/bin/sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+cd "$ROOT"
+
+python3 scripts/gen_skill_shortcut_sections.py --check
+
+chat_skill="skills/multi/dingtalk-chat/SKILL.md"
+mono_skill="skills/mono/SKILL.md"
+chat_max_bytes=14000
+
+chat_bytes="$(wc -c < "$chat_skill" | tr -d ' ')"
+if [ "$chat_bytes" -gt "$chat_max_bytes" ]; then
+	printf '%s\n' \
+		"skill context budget exceeded: $chat_skill is ${chat_bytes} bytes (max ${chat_max_bytes})" >&2
+	exit 1
+fi
+
+shortcut_rows="$(
+	awk '
+		/<!-- VISIBLE_SHORTCUTS_START -->/ { in_block = 1; next }
+		/<!-- VISIBLE_SHORTCUTS_END -->/ { in_block = 0 }
+		in_block && /^\| `dws chat \+/ { count++ }
+		END { print count + 0 }
+	' "$chat_skill"
+)"
+if [ "$shortcut_rows" -ne 0 ]; then
+	printf '%s\n' \
+		"skill context budget exceeded: $chat_skill re-expanded $shortcut_rows shortcut rows" >&2
+	exit 1
+fi
+
+if grep -Fq "充分阅读产品参考文件" "$mono_skill"; then
+	printf '%s\n' \
+		"skill context budget regression: $mono_skill requires full product-reference loading" >&2
+	exit 1
+fi
+
+printf '%s\n' \
+	"skill context budget: ok (chat_bytes=$chat_bytes max=$chat_max_bytes shortcut_rows=$shortcut_rows)"
@@ -39,26 +39,26 @@ cli_version: ">=1.0.15"
 <!-- VISIBLE_SHORTCUTS_OVERVIEW_START -->
 ## Shortcut 总览

-下面统计当前公开 catalog 中的 shortcut。mono 模式不展开 200+ 行明细，避免 skill 过重；需要执行时先按产品路由，再用 `dws shortcut list --service <service> --format json` 读取参数、约束、风险和示例，最后用 `dws <service> +<shortcut> --help` 核对当前 Cobra flags。multi 模式的各产品 skill 会展开该产品的 shortcut 表。
+下面只统计当前公开 catalog 中的 shortcut，不展开完整明细。已知意图应先按产品 Skill、意图表或任务 reference 选择唯一命令；命令已选中时直接执行，只在参数或安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service <service> --format json` 做最后回退；不要为已知高频意图加载完整产品 Catalog。

-| 服务 | shortcut 数 | multi skill | 发现命令 |
-|---|---:|---|---|
-| `aitable` | 29 | `dingtalk-workspace` | `dws shortcut list --service aitable --format json` |
-| `attendance` | 19 | `dingtalk-workspace` | `dws shortcut list --service attendance --format json` |
-| `calendar` | 20 | `dingtalk-workspace` | `dws shortcut list --service calendar --format json` |
-| `chat` | 97 | `dingtalk-workspace` | `dws shortcut list --service chat --format json` |
-| `contact` | 14 | `dingtalk-workspace` | `dws shortcut list --service contact --format json` |
-| `devapp` | 19 | `dingtalk-workspace` | `dws shortcut list --service devapp --format json` |
-| `ding` | 4 | `dingtalk-workspace` | `dws shortcut list --service ding --format json` |
-| `doc` | 17 | `dingtalk-workspace` | `dws shortcut list --service doc --format json` |
-| `drive` | 7 | `dingtalk-workspace` | `dws shortcut list --service drive --format json` |
-| `mail` | 10 | `dingtalk-workspace` | `dws shortcut list --service mail --format json` |
-| `minutes` | 6 | `dingtalk-workspace` | `dws shortcut list --service minutes --format json` |
-| `oa` | 7 | `dingtalk-workspace` | `dws shortcut list --service oa --format json` |
-| `report` | 2 | `dingtalk-workspace` | `dws shortcut list --service report --format json` |
-| `sheet` | 2 | `dingtalk-workspace` | `dws shortcut list --service sheet --format json` |
-| `todo` | 11 | `dingtalk-workspace` | `dws shortcut list --service todo --format json` |
-| `wiki` | 1 | `dingtalk-workspace` | `dws shortcut list --service wiki --format json` |
+| 服务 | shortcut 数 | multi skill |
+|---|---:|---|
+| `aitable` | 29 | `dingtalk-aitable` |
+| `attendance` | 19 | `dingtalk-misc` |
+| `calendar` | 20 | `dingtalk-calendar` |
+| `chat` | 97 | `dingtalk-chat` |
+| `contact` | 14 | `dingtalk-contact` |
+| `devapp` | 19 | `dingtalk-dev` |
+| `ding` | 4 | `dingtalk-misc` |
+| `doc` | 17 | `dingtalk-doc` |
+| `drive` | 7 | `dingtalk-drive` |
+| `mail` | 10 | `dingtalk-mail` |
+| `minutes` | 6 | `dingtalk-minutes` |
+| `oa` | 7 | `dingtalk-misc` |
+| `report` | 2 | `dingtalk-misc` |
+| `sheet` | 2 | `dingtalk-misc` |
+| `todo` | 11 | `dingtalk-todo` |
+| `wiki` | 1 | `dingtalk-wiki` |
 <!-- VISIBLE_SHORTCUTS_OVERVIEW_END -->

 ## 多组织 / 多账号
@@ -174,7 +174,7 @@ Step 3 → 加 --yes 执行命令
 1. 意图分类：首先，判断用户指令的核心 动词/动作 属于哪一类。这比关注名词更重要。
 2. 歧义处理与信息追问：如果用户指令模糊或包含多个产品的关键字，严禁猜测。必须主动向用户追问以澄清意图。这是你作为智能助手而非命令执行器的核心价值。
 3. 精准产品映射：在完成前两步，意图已经清晰后，参考产品总览和意图判断决策树 来选择产品。
-4. 充分阅读产品参考文件，通过编写代码或直接调用指令实现用户意图。
+4. 按任务最小化读取：已知高频意图直接使用本 Skill 或产品 reference 已给出的唯一命令，不预加载完整产品参考文件；只有路由、参数或异常恢复确实需要时，才读取对应产品或任务 reference。

 ## 命令发现（Schema 渐进查询 + --help 互为补充）

@@ -184,6 +184,8 @@ Step 3 → 加 --yes 执行命令

 本节同时适用于基础/原子命令与公开内建 `+` shortcut。用户自定义或未公开 shortcut 不进入发布 Schema；其是否可执行仍以当前 Cobra help 为准。

+**已知命令路径例外**：当本 Skill、产品意图表或任务 reference 已经给出精确 CLI path 时，不要再查询产品级/分组级 Schema，也不要调用完整 Shortcut Catalog；可直接执行。只有参数、约束或安全语义不确定时才读取该命令的 leaf Schema，只有当前 Cobra flags 不确定时才补读 leaf Help。
+
 稳定 command identity、主 CLI path 和 alias 已在构建时由 reviewed registry 与真实 Cobra tree 精确绑定。Agent 不应读取 Catalog 文件、native annotation 或其他生成 JSON 来重新推断命令；所有运行时查询都以当前二进制交付的 Schema 投影为准。

 ```bash
@@ -250,7 +252,7 @@ dws schema --all --format json
 |------|--------|
 | 命令是否存在、当前 Cobra 接受哪些 flags | `dws <cli_path> --help` |
 | Agent 选择、参数映射/required/组合约束、risk/confirmation（原子/基础命令） | `dws schema "<cli_path>"`（按需加 `--compact`） |
-| shortcut 的参数、组合约束、risk/confirmation、示例 | `dws shortcut list --service <service> --format json` |
+| shortcut 的参数、组合约束、risk/confirmation、示例 | 已知路径优先 `dws schema --cli-path "<service> +<shortcut>" --compact --format json`；完整 `shortcut list` 仅用于无法定位低频能力时的最后回退 |
 | 人类可读用法 | `dws <cli_path> --help` |
 | 钉钉中的文档、文件、日程、消息等实际数据 | 真正执行对应的 `read` / `search` / `list` 命令 |

@@ -105,6 +105,7 @@

 | 命令 | 用途 | 必填参数 | 路由提醒 |
 |------|------|----------|----------|
+| `workflow edit-example` | 获取编辑文档与 DSL 示例 | 无 | create/update 前优先调用，内容由服务端提供 |
 | `workflow create` | 创建并发布工作流 | `--base-id` `--dsl` | `--dsl` 为完整 workflow-dsl/v1；非幂等，不自动重试 |
 | `workflow update` | 更新并发布工作流 | `--base-id` `--workflow-id` `--dsl` | 全量替换，先 get 留底；检查 `data.valid/issues` |
 | `workflow list` | 列出 Base 下所有工作流 | `--base-id` | 支持 `--limit [1,100]` / `--offset >=0`；list 出参字段叫 `flowId` |
@@ -7,6 +7,7 @@

 | 命令 | 用途 |
 |------|------|
+| `workflow edit-example` | 获取工作流编辑文档与 workflow-dsl/v1 示例 |
 | `workflow create` | 创建并发布自动化工作流 |
 | `workflow update` | 更新并发布已有自动化工作流 |
 | `workflow list` | 列出 Base 下所有工作流（含状态/创建人/最后修改时间），支持分页 |
@@ -14,11 +15,11 @@
 | `workflow enable` | 启用指定工作流（按配置的触发条件自动执行） |
 | `workflow disable` | 禁用指定工作流（高危，建议 `--yes` 二次确认） |

-> 所有子命令的 `--base-id` 必填（可用隐藏别名 `--base`）。
+> `workflow edit-example` 无参数；其他子命令的 `--base-id` 必填（可用隐藏别名 `--base`）。

 ## DSL 入参格式与最小 Demo

-`workflow create/update` 的 `--dsl` 接收完整的 `workflow-dsl/v1` JSON object，不是局部 patch。支持内联 JSON、`@文件路径` 或 `-` 从 stdin 读取。
+先运行 `workflow edit-example` 获取服务端提供的最新编辑文档和示例。`workflow create/update` 的 `--dsl` 接收完整的 `workflow-dsl/v1` JSON object，不是局部 patch。支持内联 JSON、`@文件路径` 或 `-` 从 stdin 读取。

 复杂工作流应先用 `table get` / `field get` / `view list` 确认真实 `sheetId`、`fieldId`、`viewId`，并检查所有 `next`、`loopEntry`、branch `to` 和 ref。下面是一个不依赖数据表字段的最小定时消息工作流：

@@ -53,6 +54,14 @@ create 和 update 都必须同时满足 `status=success`、`data.valid=true`、`

 ## 命令详情

+### workflow edit-example — 获取编辑文档与示例
+
+```bash
+dws aitable workflow edit-example --format json
+```
+
+该命令无业务参数，调用 `aitable/edit_workflow_example` 返回服务端提供的工作流编辑文档和示例。创建或更新复杂工作流前优先调用它，避免依赖可能过期的本地 DSL 结构。
+
 ### workflow create — 创建并发布工作流

 ```bash
@@ -202,14 +202,23 @@ Usage:
 Example:
  dws drive download --node <dentryUuid> --output ./report.pdf
  dws drive download --node <dentryUuid> --output ~/downloads/
+  dws drive download --node <dentryUuid> --output ./big.zip --part-size 32MB --parallel 8
 Flags:
      --node string       文件 ID (dentryUuid) (必填)
      --output string     本地保存路径 (必填)，可以是文件路径或目录；如果指定目录，文件名从下载 URL 中自动推断
      --space-id string   文件所属空间 ID (可选)
+      --part-size string  分片下载的分片大小，支持 KB/MB/GB 单位，范围 1MB-1GB (默认 16MB)
+      --parallel int      分片下载并发数，范围 1-8 (默认 4)
+      --no-resume         关闭断点续传，忽略历史下载进度从头下载 (默认开启续传)
 ```

 > **注意**：`--output` 是必填参数，不传会报错。

+> **大文件分片下载**：
+> - 大文件自动分片并发下载，小文件整流下载，行为对用户透明，无需任何额外操作。
+> - 断点续传默认开启：下载中断后重跑同一命令会自动跳过已完成部分继续下载（`<目标文件>.dwspart` 为临时进度文件，下载完成后自动清理）；不需要续传时加 `--no-resume`。
+> - 下载凭证过期会自动刷新并继续下载，已完成的部分不会重下；单个分片失败会自动重试，无需手动处理。
+
 ### 创建文件夹

 ```
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "aitable +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service aitable --format json` 批量发现；最后以 `dws aitable <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "aitable +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws aitable <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service aitable --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -134,6 +134,7 @@ Flags:

 | 命令 | 用途 | 必填参数 | 路由提醒 |
 |------|------|----------|----------|
+| `workflow edit-example` | 获取编辑文档与 DSL 示例 | 无 | create/update 前优先调用，内容由服务端提供 |
 | `workflow create` | 创建并发布自动化工作流 | `--base-id` `--dsl` | 按子文档 Demo 组装 DSL；必须检查返回的 `data.valid` / `issues`；create 不自动重试 |
 | `workflow update` | 更新并发布已有自动化工作流 | `--base-id` `--workflow-id` `--dsl` | 先 get 留底；提交完整目标 DSL；必须检查 `data.valid` / `issues` |
 | `workflow list` | 列出 Base 下所有工作流 | `--base-id` | 支持 `--limit [1,100]` / `--offset >=0`；list 出参字段叫 `flowId` |
@@ -7,6 +7,7 @@

 | 命令 | 用途 |
 |------|------|
+| `workflow edit-example` | 获取工作流编辑文档与 workflow-dsl/v1 示例 |
 | `workflow create` | 创建并发布自动化工作流 |
 | `workflow update` | 更新并发布已有自动化工作流 |
 | `workflow list` | 列出 Base 下所有工作流（含状态/创建人/最后修改时间），支持分页 |
@@ -14,15 +15,15 @@
 | `workflow enable` | 启用指定工作流（按配置的触发条件自动执行） |
 | `workflow disable` | 禁用指定工作流（高危，建议 `--yes` 二次确认） |

-> 所有子命令的 `--base-id` 必填（可用隐藏别名 `--base`）。
+> `workflow edit-example` 无参数；其他子命令的 `--base-id` 必填（可用隐藏别名 `--base`）。

 ## DSL 入参格式与最小 Demo

-`workflow create/update` 的 `--dsl` 接收钉钉 AI 表格 `workflow-dsl/v1` JSON object。当前同步范围只包含 create/update，没有新增 DSL 文档子命令；其他 Agent 可以直接使用下面的最小 Demo 理解调用格式。
+先运行 `workflow edit-example` 获取服务端提供的最新编辑文档和示例。`workflow create/update` 的 `--dsl` 接收钉钉 AI 表格 `workflow-dsl/v1` JSON object。

 复杂工作流还应注意：

-1. 如果 Agent 运行环境直接提供 AI 表格 MCP 的 `get_workflow_dsl_docs`，可用它获取最新 DSL Guide、Schema 和示例。
+1. 使用 `workflow edit-example` 获取最新 DSL Guide、结构和示例。
 2. 涉及数据表、字段或视图的节点，先用 `table get` / `field get` / `view list` 确认真实 `sheetId`、`fieldId`、`viewId`。
 3. create 和 update 都提交完整的 workflow-dsl/v1 JSON object，并检查所有 `next`、`loopEntry`、branch `to` 和 ref。

@@ -82,6 +83,14 @@ create 和 update 都必须同时满足 `status=success`、`data.valid=true`、`

 ## 命令详情

+### workflow edit-example — 获取编辑文档与示例
+
+```bash
+dws aitable workflow edit-example --format json
+```
+
+该命令无业务参数，调用 `aitable/edit_workflow_example` 返回服务端提供的工作流编辑文档和示例。创建或更新复杂工作流前优先调用它，避免依赖可能过期的本地 DSL 结构。
+
 ### workflow create — 创建并发布工作流

 ```bash
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "calendar +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service calendar --format json` 批量发现；最后以 `dws calendar <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "calendar +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws calendar <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service calendar --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -18,109 +18,11 @@ metadata:
 > 命令参考：[chat.md](references/chat.md)；表情：[chat-emoji-list.md](references/chat-emoji-list.md)；剧本：[01-messaging.md](references/01-messaging.md)。

 <!-- VISIBLE_SHORTCUTS_START -->
-## Shortcuts（无专用脚本/recipe 时优先）
+## Shortcut 发现（按需）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "chat +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service chat --format json` 批量发现；最后以 `dws chat <shortcut> --help` 核对当前 Cobra flags。
+`chat` 当前有 97 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图直接使用下方的优先路由、意图表或任务 reference；命令已选中时直接执行，只在参数/安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。

-| Shortcut | 风险 | 适用场景 |
-|---|---|---|
-| `dws chat +at-me` | read | 查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话） |
-| `dws chat +bot-find` | read | 搜索全部可用机器人（含他人/官方，返回 openDingTalkId 可发单聊） |
-| `dws chat +bot-search` | read | 搜索当前用户自己创建的机器人 |
-| `dws chat +broadcast` | write | 按姓名逐一给多个人群发同一条单聊消息（自动解析 userId、逐个发送） |
-| `dws chat +category-add-conversation` | write | 将会话移动到指定的自定义分组中 |
-| `dws chat +category-create` | write | 创建用户自定义会话分组 |
-| `dws chat +category-delete` | high-risk-write | 删除用户自定义会话分组 |
-| `dws chat +category-list` | read | 获取用户自定义会话分组 |
-| `dws chat +category-list-conversations` | read | 拉取指定自定义会话分组下的会话 |
-| `dws chat +category-remove-conversation` | write | 将会话从指定的自定义分组中移出 |
-| `dws chat +category-rename` | write | 更新用户自定义会话分组的名称 |
-| `dws chat +chat-add-bot` | write | 将机器人添加到群中 |
-| `dws chat +chat-audit-join` | write | 审批入群验证（通过/拒绝/删除/忽略/拉黑） |
-| `dws chat +chat-bots` | read | 查看群内所有机器人 |
-| `dws chat +chat-create` | write | 以当前用户身份创建钉钉群聊 |
-| `dws chat +chat-dismiss` | high-risk-write | 解散群聊（不可逆，需群主权限） |
-| `dws chat +chat-get-by-id` | read | 根据群号获取群聊信息 |
-| `dws chat +chat-invite-url` | read | 获取群邀请链接 |
-| `dws chat +chat-list-all` | read | 分页拉取我加入的所有群列表 |
-| `dws chat +chat-list-join-requests` | read | 分页拉取入群验证记录 |
-| `dws chat +chat-list-mine` | read | 拉取我创建/管理的群 |
-| `dws chat +chat-members-get` | read | 根据成员 openDingTalkId 批量查询群成员详情 |
-| `dws chat +chat-members-list` | read | 列出群成员并把用户与机器人分桶（支持群名语义解析） |
-| `dws chat +chat-messages` | read | 拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间 |
-| `dws chat +chat-mute` | write | 全员禁言 / 取消全员禁言 |
-| `dws chat +chat-mute-member` | write | 指定群成员禁言 / 取消禁言 |
-| `dws chat +chat-quit` | write | 退出群聊 |
-| `dws chat +chat-remove-bot` | high-risk-write | 从群内移除机器人 |
-| `dws chat +chat-role-add` | write | 添加群身份 |
-| `dws chat +chat-role-list` | read | 拉取会话的群身份列表 |
-| `dws chat +chat-role-query-user` | read | 查询群成员的群身份 |
-| `dws chat +chat-role-remove` | high-risk-write | 删除群身份 |
-| `dws chat +chat-role-remove-user` | write | 移除用户的指定群身份 |
-| `dws chat +chat-role-set-user` | write | 设置用户的群身份（覆盖该用户的全部群身份） |
-| `dws chat +chat-role-update` | write | 更新群身份名称 |
-| `dws chat +chat-search` | read | 按关键词搜索群聊 |
-| `dws chat +chat-set-admin` | write | 设置 / 取消群管理员 |
-| `dws chat +chat-set-history` | write | 设置新成员入群可查看历史消息范围 |
-| `dws chat +chat-transfer-owner` | write | 转让群主 |
-| `dws chat +chat-update` | write | 更新群名称（仅名称，不支持 description） |
-| `dws chat +chat-update-alias` | write | 设置群备注（仅自己可见） |
-| `dws chat +chat-update-icon` | write | 更新群头像 |
-| `dws chat +chat-update-nick` | write | 设置当前用户在群内的群昵称 |
-| `dws chat +chat-update-settings` | write | 更新群设置（settingKey + status） |
-| `dws chat +conversation-clear-all-red-point` | write | 清除所有会话红点（全部已读） |
-| `dws chat +conversation-clear-messages` | high-risk-write | 清空当前用户指定会话的聊天记录（仅本人视角，不可逆） |
-| `dws chat +conversation-clear-red-point` | write | 清除会话红点 |
-| `dws chat +conversation-hide` | write | 会话列表中隐藏会话（收到新消息会重新出现） |
-| `dws chat +conversation-info` | read | 获取会话信息（群聊传 --group，单聊传 --open-dingtalk-id） |
-| `dws chat +conversation-list` | read | 分页获取当前用户的全部会话列表（单聊+群聊） |
-| `dws chat +conversation-list-top` | read | 拉取置顶会话列表，可只看群聊或单聊 |
-| `dws chat +conversation-mark-read` | write | 标记消息已读（该消息及之前的消息都标记为已读） |
-| `dws chat +conversation-mark-unread` | write | 标记会话为未读 |
-| `dws chat +conversation-mute` | write | 会话消息免打扰（支持单聊/群聊） |
-| `dws chat +conversation-set-top` | write | 批量会话置顶 / 取消置顶（最多 10 个） |
-| `dws chat +dm` | write | 按姓名直接给某人发单聊消息（自动解析 userId） |
-| `dws chat +feed-group-query-item` | read | 在会话分组结果中按会话 ID 精确查询多项 |
-| `dws chat +flag-cancel` | write | 取消收藏一条或多条消息（最多 10 条） |
-| `dws chat +flag-create` | write | 收藏一条或多条消息（最多 10 条） |
-| `dws chat +flag-list` | read | 分页查询当前用户收藏的消息 |
-| `dws chat +group-members` | read | 按群名列出群成员（自动搜群解析 openConversationId） |
-| `dws chat +messages-add-emoji` | write | 对消息添加 emoji 表情回应 |
-| `dws chat +messages-add-text-emotion` | write | 对消息添加文字表情回应 |
-| `dws chat +messages-batch-recall-by-bot` | write | 机器人撤回单聊消息 |
-| `dws chat +messages-batch-send-by-bot` | write | 机器人批量向用户发送单聊 Markdown 消息 |
-| `dws chat +messages-combine-forward` | write | 合并转发多条消息 |
-| `dws chat +messages-create-text-emotion` | write | 创建文字表情（获取 emotionId） |
-| `dws chat +messages-forward` | write | 转发单条消息 |
-| `dws chat +messages-forward-topic` | write | 转发话题消息到目标会话 |
-| `dws chat +messages-list` | read | 拉取群聊会话消息 |
-| `dws chat +messages-list-direct` | read | 拉取单聊会话消息 |
-| `dws chat +messages-list-pin` | read | 拉取会话中钉住的消息列表 |
-| `dws chat +messages-list-unread-conversations` | read | 获取有未读消息的会话列表 |
-| `dws chat +messages-mget` | read | 根据消息 ID 批量查询消息（最多 50 条） |
-| `dws chat +messages-query-send-status` | read | 查询消息发送状态 |
-| `dws chat +messages-read-status` | read | 查询消息的已读/未读状态 |
-| `dws chat +messages-recall` | write | 撤回当前用户发送的消息 |
-| `dws chat +messages-recall-by-bot` | write | 机器人撤回群消息 |
-| `dws chat +messages-remove-emoji` | write | 移除消息的 emoji 表情回应 |
-| `dws chat +messages-remove-text-emotion` | write | 移除消息的文字表情回应 |
-| `dws chat +messages-reply` | write | 以当前用户身份引用回复消息（自动补全原发送者） |
-| `dws chat +messages-resource-download` | read | 安全下载消息资源（图片/视频/语音/文件）到工作目录内，无需交互确认 |
-| `dws chat +messages-resource-url` | read | 获取消息资源（图片/视频/语音）下载链接 |
-| `dws chat +messages-send` | write | 统一发送文本、Markdown、当前用户文件或已有 mediaId 图片 |
-| `dws chat +messages-send-by-bot` | write | 机器人向群聊发送 Markdown 消息 |
-| `dws chat +messages-send-by-webhook` | write | 自定义机器人 Webhook 发送群消息 |
-| `dws chat +messages-send-card` | write | 创建流式卡片，可在同一次调用中写入内容并结束 |
-| `dws chat +messages-set-pin` | write | 钉住消息（Pin） |
-| `dws chat +messages-set-top` | write | 置顶消息 |
-| `dws chat +messages-unset-pin` | write | 取消钉住消息（Unpin） |
-| `dws chat +messages-unset-top` | write | 取消置顶消息 |
-| `dws chat +messages-update-card` | write | 流式更新卡片内容（最后一次 --flow-status 应为 3） |
-| `dws chat +my-groups` | read | 列出我加入的群，可按类型过滤并投影关键字段 |
-| `dws chat +search-msg` | read | 多维搜索消息，可全量翻页并批量富化详情 |
-| `dws chat +send-to-group` | write | 按群名直接给群发消息（自动搜群解析 openConversationId） |
-| `dws chat +thread-replies` | read | 拉取某条话题消息的全部回复并投影出发言人/文本/时间 |
-| `dws chat +unread-chats` | read | 列出我有未读消息的会话（投影会话名/未读数/会话ID） |
+仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service chat --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
 <!-- VISIBLE_SHORTCUTS_END -->

 ## IM Shortcut 优先路由
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "contact +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service contact --format json` 批量发现；最后以 `dws contact <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "contact +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws contact <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service contact --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -29,7 +29,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "devapp +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service devapp --format json` 批量发现；最后以 `dws devapp <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "devapp +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws devapp <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service devapp --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -29,7 +29,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "doc +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service doc --format json` 批量发现；最后以 `dws doc <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "doc +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws doc <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service doc --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "drive +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service drive --format json` 批量发现；最后以 `dws drive <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "drive +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws drive <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service drive --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -170,14 +170,23 @@ Usage:
 Example:
  dws drive download --node <dentryUuid> --output ./report.pdf
  dws drive download --node <dentryUuid> --output ~/downloads/
+  dws drive download --node <dentryUuid> --output ./big.zip --part-size 32MB --parallel 8
 Flags:
      --node string    文件 ID (dentryUuid) (必填)
      --output string     本地保存路径 (文件路径或目录，不传则保存到当前目录)；如果指定目录，文件名从下载 URL 中自动推断 (可选)
      --space-id string   文件所属空间 ID (可选)
+      --part-size string  分片下载的分片大小，支持 KB/MB/GB 单位，范围 1MB-1GB (默认 16MB)
+      --parallel int      分片下载并发数，范围 1-8 (默认 4)
+      --no-resume         关闭断点续传，忽略历史下载进度从头下载 (默认开启续传)
 ```

 > **提示**：`--output` 为可选参数，不传则保存到当前目录，文件名从下载 URL 中自动推断。

+> **大文件分片下载**：
+> - 大文件自动分片并发下载，小文件整流下载，行为对用户透明，无需任何额外操作。
+> - 断点续传默认开启：下载中断后重跑同一命令会自动跳过已完成部分继续下载（`<目标文件>.dwspart` 为临时进度文件，下载完成后自动清理）；不需要续传时加 `--no-resume`。
+> - 下载凭证过期会自动刷新并继续下载，已完成的部分不会重下；单个分片失败会自动重试，无需手动处理。
+
 ### 创建文件夹

 ```
@@ -526,6 +535,7 @@ Flags:

 > **两步下载流程**：先调用 MCP 工具获取历史版本下载 URL 和签名头，再 HTTP GET 下载文件内容到本地。
 > `--output` 指定目录时，优先从文件信息中获取原始文件名，获取不到时从下载 URL 推断。
+> 历史版本下载同样支持 `--part-size` / `--parallel` / `--no-resume` 分片下载参数，行为与最新版下载一致。

 #### 回滚文件到指定历史版本

@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "mail +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service mail --format json` 批量发现；最后以 `dws mail <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "mail +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws mail <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service mail --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "minutes +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service minutes --format json` 批量发现；最后以 `dws minutes <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "minutes +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws minutes <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service minutes --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -1411,7 +1411,7 @@ dws attendance boss-check --plan-id 948964045503 --time "2026-05-13 18:00" --res
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "attendance +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service attendance --format json` 批量发现；最后以 `dws attendance <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "attendance +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws attendance <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service attendance --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -169,7 +169,7 @@ dws ding message recall-personal --id <OPEN_DING_ID> --format json
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "ding +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service ding --format json` 批量发现；最后以 `dws ding <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "ding +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws ding <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service ding --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -473,7 +473,7 @@ dws oa approval revert-task --instance-id <processInstanceId> --task-id <taskId>
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "oa +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service oa --format json` 批量发现；最后以 `dws oa <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "oa +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws oa <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service oa --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -445,7 +445,7 @@ dws report outbox list --cursor 0 --size 20 --format json
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "report +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service report --format json` 批量发现；最后以 `dws report <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "report +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws report <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service report --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -210,7 +210,7 @@ Flags:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "sheet +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service sheet --format json` 批量发现；最后以 `dws sheet <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "sheet +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws sheet <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service sheet --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "todo +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service todo --format json` 批量发现；最后以 `dws todo <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "todo +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws todo <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service todo --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
@@ -20,7 +20,7 @@ metadata:
 <!-- VISIBLE_SHORTCUTS_START -->
 ## Shortcuts（无专用脚本/recipe 时优先）

-以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。用 leaf Schema（例如 `dws schema --cli-path "wiki +<shortcut>" --format json`）读取 Agent 选择、参数、约束、风险和确认语义；用 `dws shortcut list --service wiki --format json` 批量发现；最后以 `dws wiki <shortcut> --help` 核对当前 Cobra flags。
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 leaf Schema（例如 `dws schema --cli-path "wiki +<shortcut>" --format json`），在当前 Cobra flags 不确定时读取 `dws wiki <shortcut> --help`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service wiki --format json` 批量发现。

 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
Author	SHA1	Message	Date
chichuan	d3f62193e7	Merge pull request #859 from DingTalk-Real-AI/codex/changelog-v1.0.56 docs: seal v1.0.56 changelog	2026-08-04 10:05:35 +08:00
chichuan	f26df04679	docs: seal v1.0.56 changelog	2026-08-04 10:00:32 +08:00
github-actions[bot]	d02b03436d	chore: update beta formula for v1.0.56-beta.4 [skip ci]	2026-08-04 01:55:53 +00:00
chichuan	bc7b96ba5f	Merge pull request #858 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.4 docs: seal v1.0.56-beta.4 changelog	2026-08-04 09:46:33 +08:00
chichuan	9539c887f6	docs: seal v1.0.56-beta.4 changelog	2026-08-04 09:35:44 +08:00
github-actions[bot]	6607f44724	Merge pull request #852 from AlwaysLee/feat/center-protocol-transfer feat: multipart download engine with checkpoint resume and credential refresh	2026-08-04 09:29:17 +08:00
半圭	837a96fe3d	fix: show friendly message on Ctrl+C instead of internal error JSON When user interrupts multipart download with Ctrl+C, display a helpful message indicating checkpoint is saved and download can be resumed, instead of returning an internal error with context.Canceled.	2026-08-04 08:58:17 +08:00
半圭	fdcd44f9e3	fix: handle Ctrl+C (SIGINT) gracefully during drive download - Replace context.Background() with cmd.Context() in download and download-version commands so SIGINT propagates to download goroutines - Enables graceful interruption of multipart downloads via Ctrl+C	2026-08-03 23:21:59 +08:00
半圭	34c0c86a59	feat: center protocol upload/download refactoring with multipart download - Add multipart download engine (drive_transfer.go) with Range probe, resume support, and credential auto-refresh on 401/403 - Add --part-size, --parallel, --no-resume flags to drive download and download-version commands - Replace httpGetFile with driveTransferDownload for chunked parallel downloads in download and download-version commands - Replace uploadToDrive credential parsing with driveUploadPut (transparent header pass-through, retry on 401/403) - Add typed httpStatusError for non-2xx HTTP responses in doc.go - Add comprehensive unit tests (32 cases) for drive_transfer - Update drive reference documentation with multipart download behavior - Add E2E test for multipart download (auto-test/, gitignored) CR: 28984991	2026-08-03 23:21:59 +08:00
github-actions[bot]	b2cbca2762	chore: update beta formula for v1.0.56-beta.3 [skip ci]	2026-08-03 12:55:19 +00:00
chichuan	9ce95db08e	Merge pull request #855 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.3 docs: seal v1.0.56-beta.3 changelog	2026-08-03 20:39:44 +08:00
chichuan	e99c20a0a1	docs: seal v1.0.56-beta.3 changelog	2026-08-03 20:34:17 +08:00
github-actions[bot]	96bfae079a	Merge pull request #846 from wxianfeng/fix/event-unix-socket-tmpdir fix(event): use secure Unix bus runtime directory	2026-08-03 16:04:41 +08:00
wxianfeng	bb18cdba3b	Merge upstream/main into fix/event-unix-socket-tmpdir	2026-08-03 15:45:38 +08:00
wxianfeng	015a1f85ca	fix(event): satisfy platform coverage gate	2026-08-03 15:42:17 +08:00
github-actions[bot]	8854e0d1d4	Merge pull request #851 from abucraft/codex/aitable-workflow-docs feat: add aitable workflow edit example command	2026-08-03 07:01:27 +00:00
镜玄	22862508b8	feat: add aitable workflow edit example command	2026-08-03 14:47:59 +08:00
wxianfeng	5459bcc524	fix(event): secure Unix bus runtime directory	2026-08-03 11:40:01 +08:00
wxianfeng	029c665029	fix(event): place Unix bus sockets in temp dir	2026-07-31 18:01:34 +08:00
github-actions[bot]	187787040b	chore: update beta formula for v1.0.56-beta.2 [skip ci]	2026-07-30 15:00:34 +00:00
chichuan	cd6e854bf1	Merge pull request #843 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.2-admission-final docs(release): clarify v1.0.56-beta.2 skill routing	2026-07-30 22:48:59 +08:00
chichuan	61124f8768	docs(release): clarify v1.0.56-beta.2 skill routing	2026-07-30 22:44:52 +08:00
github-actions[bot]	6cfeac3179	Merge pull request #842 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.2-admission docs(release): complete v1.0.56-beta.2 notes	2026-07-30 22:43:08 +08:00
chichuan	acd293cc83	docs(release): complete v1.0.56-beta.2 notes	2026-07-30 22:40:59 +08:00
github-actions[bot]	d2045c3441	Merge pull request #841 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.2 docs(release): seal v1.0.56-beta.2 changelog	2026-07-30 22:38:42 +08:00
chichuan	4de41c27c7	docs(release): add v1.0.56-beta.2 notes	2026-07-30 22:36:34 +08:00
github-actions[bot]	5df2860e66	Merge pull request #831 from wxianfeng/fix/agent-product-header-separation fix: separate Agent Product from claw-type	2026-07-30 14:35:55 +00:00
chichuan	f3390b6875	Merge branch 'main' into fix/agent-product-header-separation	2026-07-30 22:16:13 +08:00
github-actions[bot]	55f25d8d48	Merge pull request #835 from DingTalk-Real-AI/codex/skill-token-shallow-water perf(skills): reduce common-path context loading	2026-07-30 14:04:51 +00:00
chichuan	67fbf65916	Merge branch 'main' into fix/agent-product-header-separation	2026-07-30 21:54:11 +08:00
chichuan	7f82e46adf	Merge branch 'main' into codex/skill-token-shallow-water	2026-07-30 21:52:17 +08:00
chichuan	1fb1ae3e23	Merge remote-tracking branch 'origin/main' into codex/pr-831-conflict-fix # Conflicts: # CHANGELOG.md	2026-07-30 21:47:14 +08:00
github-actions[bot]	fd0ab16c7f	chore: update beta formula for v1.0.56-beta.1 [skip ci]	2026-07-30 13:46:57 +00:00
chichuan	daaad35f5b	Merge pull request #840 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.1-followup docs(release): complete v1.0.56-beta.1 notes	2026-07-30 21:33:31 +08:00
chichuan	953a36f4c9	docs(release): complete v1.0.56-beta.1 notes	2026-07-30 21:30:31 +08:00
github-actions[bot]	e015f40ae2	Merge pull request #836 from DingTalk-Real-AI/codex/changelog-v1.0.56-beta.1 docs(release): add v1.0.56-beta.1 notes	2026-07-30 21:27:07 +08:00
chichuan	84226b963c	Merge branch 'main' into codex/changelog-v1.0.56-beta.1	2026-07-30 21:22:16 +08:00
chichuan	1d1c06aaae	Merge branch 'main' into fix/agent-product-header-separation	2026-07-30 21:17:23 +08:00
github-actions[bot]	f34f9e8223	Merge pull request #839 from DingTalk-Real-AI/codex/fix-multi-profile-e2e-timeout ci: increase integration test timeouts	2026-07-30 21:14:44 +08:00
chichuan	a54ee24acb	Merge branch 'main' into fix/agent-product-header-separation	2026-07-30 20:21:34 +08:00
chichuan	320582f98c	Merge branch 'main' into fix/agent-product-header-separation	2026-07-30 19:04:13 +08:00
Dennis	e04ff5a12b	Merge remote-tracking branch 'origin/main' into codex/skill-token-shallow-water # Conflicts: # internal/cli/schema_agent_metadata/index.json # internal/cli/schema_agent_metadata_audit.json # internal/cli/schema_catalog/catalog.json	2026-07-30 17:39:06 +08:00
wxianfeng	c569def067	docs: clarify disabled AI tag argument shape	2026-07-30 16:55:46 +08:00
chichuan	584b1bd9d4	docs(release): add v1.0.56-beta.1 notes	2026-07-30 15:42:05 +08:00
Dennis	c350311048	chore: keep analysis report out of PR	2026-07-30 15:20:51 +08:00
Dennis	158e7ec701	perf(skills): reduce common-path context loading	2026-07-30 15:17:48 +08:00
wxianfeng	125a101487	fix: separate Agent Product from claw-type	2026-07-30 14:34:22 +08:00