feat: align open CLI with dws-wukong via cedar discovery version code (#509)

Switches the discovery version code bamboo -> cedar and aligns the open edition CLI with dws-wukong across communication (calendar book/acl/attendee, minutes tag, mail folder/template/contact, chat file upload, todo add-attachment, attendance transforms) and structured-office (aitable advperm/view/section/workflow/record, sheet/drive/wiki/doc) domains. Includes output-envelope parity, parse_bool/attendance_class_check_time transforms, --calendar-id support, CHANGELOG 1.0.43 and README command-index refresh. cedar config validated on pre and prod endpoints.

.github/badges/coverage.svg

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

.github/workflows/mirror-to-gitee.yml

@@ -0,0 +1,75 @@
+# 把本仓库代码自动镜像到 Gitee，供国内用户访问（raw 脚本入口 + tags）。
+# 用 HTTPS + 令牌直接 git push（无需 SSH key），复用已配置的 secret：
+#   GITEE_TOKEN  —— Gitee 私人令牌（勾 projects）
+#   GITEE_USER   —— 令牌所属 Gitee 用户名（用于 https 推送鉴权）
+#   GITEE_REPO   —— "owner/repo"，如 DingTalk-Real-AI/dingtalk-workspace-cli
+# 未配置 GITEE_TOKEN 时（如 fork）自动跳过，不报红叉。
+name: Mirror code to Gitee
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  schedule:
+    - cron: '0 18 * * *'
+  workflow_dispatch:
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    # GitHub Actions 不允许在 job-level if 直接引用 secrets，故先用 env 暴露再在 step 守卫。
+    env:
+      GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
+      GITEE_USER: ${{ secrets.GITEE_USER }}
+      GITEE_REPO: ${{ secrets.GITEE_REPO }}
+    steps:
+      - name: Checkout (full history + tags)
+        if: env.GITEE_TOKEN != ''
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push main + tags to Gitee (with README localization)
+        if: env.GITEE_TOKEN != ''
+        run: |
+          set -eu
+          REMOTE="https://${GITEE_USER}:${GITEE_TOKEN}@gitee.com/${GITEE_REPO}.git"
+          # 取到 main 与所有 tag（落到 origin/* 与本地 tags，避免推当前分支引用冲突）
+          git fetch --force --tags origin 'refs/heads/main:refs/remotes/origin/main'
+
+          # Gitee 专属分支：在 origin/main 之上叠加一个 README 本地化 commit。
+          # GitHub 那份 README 不变；只有推往 Gitee 的副本被改写。
+          git checkout -B gitee-main origin/main
+          git config user.email "actions@github.com"
+          git config user.name "github-actions[bot]"
+
+          # 1) 安装命令本地化：raw.githubusercontent → gitee raw（国内可达）。
+          for f in README.md README_zh.md; do
+            [ -f "$f" ] || continue
+            sed -i "s#raw.githubusercontent.com/${GITEE_REPO}/main#gitee.com/${GITEE_REPO}/raw/main#g" "$f"
+          done
+
+          # 2) coverage 徽章：仓库内相对路径 svg 在 Gitee 渲染不出来（gitee raw 对 svg
+          #    返回需签名、会过期的 URL，且 content-type 为 text/plain）。改成 shields.io
+          #    静态徽章——数值取自仓库 coverage.svg，颜色按覆盖率阈值。
+          SVG=".github/badges/coverage.svg"
+          if [ -f "$SVG" ]; then
+            PCT="$(grep -oE '[0-9]+(\.[0-9]+)?%' "$SVG" | head -1)"
+            NUM="${PCT%\%}"; INT="${NUM%.*}"
+            if [ "${INT:-0}" -ge 80 ]; then C=brightgreen; elif [ "${INT:-0}" -ge 60 ]; then C=yellow; else C=red; fi
+            BADGE="https://img.shields.io/badge/coverage-${NUM}%25-${C}"
+            for f in README.md README_zh.md; do
+              [ -f "$f" ] || continue
+              sed -i "s#\.github/badges/coverage\.svg#${BADGE}#g" "$f"
+            done
+          fi
+
+          git add README.md README_zh.md 2>/dev/null || true
+          git commit -m "docs(gitee): localize install commands + coverage badge for Gitee mirror" || true
+
+          # 镜像对齐（force：Gitee 始终跟随 GitHub + Gitee 专属 README 本地化）
+          git push --force "$REMOTE" 'gitee-main:refs/heads/main'
+          git push --force --tags "$REMOTE"
+          echo "✅ 已镜像 main(+Gitee README 本地化) + tags 到 Gitee ${GITEE_REPO}"

.github/workflows/release.yml

@@ -12,7 +12,10 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    # 60 (not 30): mirroring every release asset to Gitee is slow; 30 min cut the
+    # Gitee step off mid-upload on the v1.0.42 release. The Gitee step is now also
+    # idempotent (re-runs only upload missing assets).
+    timeout-minutes: 60
 
     steps:
       - name: Check out repository
@@ -58,6 +61,28 @@ jobs:
         run: |
           gh release upload "${{ github.ref_name }}" dist/dws-skills.zip --clobber
 
+      - name: Sync release to China OSS mirror
+        # 自动同步到国内镜像，供 install.sh 的 DWS_RELEASE_BASE 开关消费。
+        # 脚本自带门控：未配置 OSS_* secret 时优雅跳过，不影响海外发布。
+        run: ./scripts/release/sync-to-oss.sh
+        env:
+          VERSION: ${{ github.ref_name }}
+          OSS_ACCESS_KEY_ID: ${{ secrets.OSS_ACCESS_KEY_ID }}
+          OSS_ACCESS_KEY_SECRET: ${{ secrets.OSS_ACCESS_KEY_SECRET }}
+          OSS_ENDPOINT: ${{ secrets.OSS_ENDPOINT }}
+          OSS_BUCKET: ${{ secrets.OSS_BUCKET }}
+          OSS_PREFIX: ${{ secrets.OSS_PREFIX }}
+
+      - name: Mirror release to Gitee (China)
+        # 把 release 附件（二进制/校验和/skills 包）镜像到 Gitee release，供 install.sh
+        # 的 DWS_GITEE_REPO 开关消费（仓库代码由 Gitee 仓库镜像功能自动同步，附件不在其内）。
+        # 脚本自带门控：未配置 GITEE_TOKEN / GITEE_REPO 时优雅跳过，不影响海外发布。
+        run: ./scripts/release/sync-to-gitee.sh
+        env:
+          VERSION: ${{ github.ref_name }}
+          GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
+          GITEE_REPO: ${{ secrets.GITEE_REPO }}
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -65,6 +90,8 @@ jobs:
           registry-url: "https://registry.npmjs.org"
 
       - name: Publish to npm
+        # 只有官方仓库发 npm；fork（dev 预览）没有 NPM_TOKEN，跳过以免红叉
+        if: ${{ github.repository_owner == 'DingTalk-Real-AI' }}
         working-directory: dist/npm/dingtalk-workspace-cli
         run: npm publish --access public
         env:

.github/workflows/sync-release-to-gitee.yml

@@ -0,0 +1,49 @@
+name: Sync release to Gitee
+
+# Manually mirror a published GitHub release's assets to the matching Gitee
+# release. Use this to repair a release whose Gitee mirror is incomplete (e.g.
+# the Release job timed out mid-upload). It runs ONLY the idempotent Gitee sync
+# step — it does not run GoReleaser and does not touch the GitHub release, so
+# there is no release outage. The sync script skips assets already on Gitee, so
+# this only uploads what is missing.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release tag to mirror to Gitee (e.g. v1.0.42)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  sync-gitee:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download GitHub release assets
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -eu
+          mkdir -p dist
+          gh release download "${{ inputs.version }}" \
+            --repo "${{ github.repository }}" \
+            --dir dist \
+            --pattern 'dws-*' \
+            --pattern 'checksums.txt' \
+            --clobber
+          ls -la dist
+
+      - name: Mirror release to Gitee (China)
+        # Idempotent: uploads only assets not already present on the Gitee release.
+        run: ./scripts/release/sync-to-gitee.sh
+        env:
+          VERSION: ${{ inputs.version }}
+          GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
+          GITEE_REPO: ${{ secrets.GITEE_REPO }}

.gitignore

@@ -26,6 +26,7 @@ test/cli_compat/testdata/
 *.pem
 *.key
 credentials*
+!skills/**/credentials.md
 plans
 _docs
 dws.zip
@@ -34,3 +35,10 @@ dws.zip
 
 # envelope/discovery.pre.json synced via Portal, not git-tracked
 /envelope/discovery.pre.json
+
+# local/pre-release MCP service configs may contain personal gateway keys
+/docs/mcp/serviceconfig-pre*
+
+# 功能测试运行产物
+results.jsonl
+test/dev_functional/results.jsonl

.goreleaser.yaml

@@ -64,7 +64,8 @@ changelog:
 
 release:
   github:
-    owner: DingTalk-Real-AI
+    # 用当前运行 CI 的仓库 owner: fork CI 发到 fork, 官方 CI 发到官方, 两边都对
+    owner: "{{ .Env.GITHUB_REPOSITORY_OWNER }}"
     name: dingtalk-workspace-cli
   draft: false
   prerelease: auto

CHANGELOG.md

@@ -6,6 +6,76 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+### Added
+
+- **`dingtalk-dev` skill: image-upload → `mediaId` recipe + per-resource command discovery** (`skills/multi/dingtalk-dev/references/`) — documents how to obtain a `mediaId` for app / robot icons via the DingTalk OpenAPI (`credentials get` → `gettoken` → `/media/upload?type=image` → `--icon-media-id` → read back), since the dev command set has no upload command; and adds a "discovering commands" block to all 10 product refs pointing at each group's `--help` and `dws schema dev.app.<group>.<method>` (`dws schema dev.connect` for connect), so agents inspect commands instead of relying on memory.
+
+## [1.0.43] - 2026-06-26
+
+This release aligns the open edition's CLI surface with **dws-wukong** across the communication domain (chat / mail / minutes / todo / calendar / contact / aisearch / live / report / ding) and the structured-office domain (aitable / sheet / drive / wiki / doc), and switches the discovery version code from `bamboo` to `cedar` so the aligned command tree is served from its own discovery config.
+
+### Added
+
+- **`calendar book get|search` and `calendar acl list`** (cedar discovery overrides) — query a specific calendar (primary via `--id primary`), fuzzy-search calendars by name, and list a calendar's access-control entries. Maps to the calendar MCP `get_calendar` / `search_calendar` / `list_acls` tools.
+- **`calendar attendee list|add|delete`** (`internal/helpers/calendar_commands.go`) — manage event participants under the wukong-aligned `attendee` naming (equivalent to the legacy `participant` group; calls `get/add/remove_calendar_participant`).
+- **`minutes tag list` and `minutes tag query --tag-id`** — list a user's AI-minutes tags and query minutes by tag (`query_user_tag_list` / `query_minutes_by_tag_id`).
+- **`minutes list mine|shared|all`** (`internal/helpers/minutes_commands.go`) — list own / shared / all minutes with renamed output fields.
+- **`mail folder create|update|delete`, `mail template create|list|get|update|delete`, `mail contact create|list|update|batch-delete`, and `mail message list`** — full mail folder / message-template / contact CRUD plus folder-scoped message listing.
+- **`chat file upload`** (`internal/helpers/chat_file.go`) — upload a local file (init/PUT/commit) or a remote URL to a conversation's file space.
+- **`todo task add-attachment`** (`internal/helpers/todo_commands.go`) — attach a local file to a todo (multi-step upload).
+- **aitable extensions** (`internal/helpers/aitable_extra.go`) — advanced permission / roles, view sub-commands (lock / duplicate / frozen-cols / row-height / fill-color-rule / card / timebar), section node management, workflow enable/disable, record `upsert` / `share-url` / `history-list` / primary-doc, and field search-options. Helper tools route to the hardcoded `aitable-helper` supplement endpoint.
+- **sheet, drive, wiki, doc helper coverage** synced from dws-wukong (`internal/helpers/sheet.go`, `drive.go`, `wiki.go`, `doc.go`).
+
+### Changed
+
+- **Discovery version code `bamboo` → `cedar`** (`internal/market/registry.go`; `discoveryAPIPath = "/cli/discovery/apis/cedar"`) — version codes step by first letter (bamboo → cedar → …); `cedar` carries the dws-wukong alignment. Older binaries keep reading `bamboo`, so the change is isolated to this release line. All test/mock/generator fixtures updated to the cedar path.
+- **CLI output envelope aligned with wukong for cross-edition parity** (`internal/app/runner.go`, `internal/compat/registry.go`) — dry-run prints a `DRY-RUN Arguments:` line, successful results carry `success: true`, missing-required-flag wording is unified to `missing required flag(s): --x`, and OutputTransform applies to the response content layer.
+- **New flag transforms** (`internal/compat/transform.go`) — `parse_bool` (explicit boolean strings so `--flag false` is honoured) and `attendance_class_check_time` (`HH:mm` → UTC+8 milliseconds for shift check-times).
+- **`--calendar-id` accepted on calendar event / participant / room / attachment commands** so calendars other than the primary can be targeted.
+
+### Fixed
+
+- **Client-side validation** for calendar recurrence completeness and attendance schedule / class / group inputs, surfacing input errors before they reach the server.
+
+## [1.0.42] - 2026-06-25
+
+This release rounds out `dws dev connect` — bridge a DingTalk robot to your local AI (Claude Code / Codex / opencode / Qoder / …): a generic `custom` channel for any headless CLI tool, in-chat `/new` / `/clear` session commands aligned to each agent's real session op, and a fix for long opencode turns being cut at 30 seconds.
+
+### Added
+
+- **`dws devapp robot connect` — generic `custom` channel for self-built / unsupported AI tools** (issue #37; `internal/helpers/devapp_connect.go`, `internal/helpers/connect_stream.go`) — a new `--agent-cmd "<command>"` flag (and `custom` channel) lets the bot forward to any headless AI CLI that takes a question as its trailing argument and prints the answer to stdout, so tools that aren't built-in (e.g. 网易有道龙虾 LobsterAI) or self-built agents can be onboarded without code changes. `--agent-cmd` forces the `custom` channel unless `--channel` is set explicitly; detection also falls back to `custom` when `DWS_AGENT_CMD` is present.
+
+### Changed
+
+- **`robot connect` now hints how to match terminal answer quality** (issue #39; `internal/helpers/devapp_connect.go`) — when neither a work dir nor a knowledge source is configured, the connector prints a one-time note that the bot runs in a clean temp dir without local project context, pointing at `--agent-workdir` / `--knowledge-dir` / `--knowledge-source` / `--agent-model`. The robot quickstart gains matching FAQ entries, plus a clarification that step 3 (`robot connect`) produces no approval ticket (issue #19).
+
+- **`robot connect` session commands `/new` vs `/clear` now use each channel's real session op** (PR #20; `internal/helpers/connect_opencode.go`, `internal/helpers/connect_stream.go`) — `/new` (and `/start`, `/reset`) opens a fresh session and leaves the previous one intact (resumable where the agent supports it); `/clear` actively disposes the current session through the agent's real delete primitive — opencode issues `DELETE /session/:id`. Channels whose agent exposes no delete in the mode DWS drives it (Codex app-server, Qoder stream, Claude-family exec) fall back to a reset, so `/clear` behaves like `/new` there. Previously both commands only dropped the local `conversationId → sessionId` mapping, so the two were indistinguishable and opencode sessions were never disposed (they leaked).
+
+### Fixed
+
+- **`robot connect` no longer aborts long opencode turns at 30 seconds** (PR #19; `internal/helpers/connect_opencode.go`) — the shared opencode HTTP client hard-coded a 30s `Timeout` that covered every request, including `POST /session/{id}/message`, so a long agent turn (e.g. a multi-minute research report) was killed mid-flight with `context deadline exceeded (Client.Timeout exceeded while awaiting headers)` even though the per-turn budget (`DWS_AGENT_TIMEOUT_MS`, default 300s) was far larger. The client-level deadline is removed so the per-request ctx governs the round-trip; only the `/global/health` probe keeps a short 10s timeout so startup detection stays snappy.
+
+## [1.0.41] - 2026-06-24
+
+This release makes the installers work from mainland China out of the box (no env var) and keeps the Gitee mirror in sync automatically.
+
+### Added
+
+- **Auto-fallback to the Gitee mirror when GitHub is unreachable** (#492; `scripts/install.sh`, `scripts/install.ps1`, `scripts/install-skills.sh`) — the installers probe GitHub Releases on startup and, when it is unreachable (typical in mainland China), automatically resolve the version and download every asset (binary, `checksums.txt`, `dws-skills.zip`) from the Gitee mirror instead. A plain `curl … | sh` now works in China with no `DWS_GITEE_REPO` needed. Explicit `DWS_GITEE_REPO` still wins, `DWS_NO_FALLBACK=1` forces GitHub, and local source-checkout installs skip the probe.
+
+### Changed
+
+- **CI mirrors repo code to Gitee automatically** (#493; `.github/workflows/mirror-to-gitee.yml`) — the mirror workflow now pushes `main` + tags to the Gitee mirror over HTTPS using `GITEE_TOKEN` (no SSH key), on every push to `main` and every tag, keeping the Gitee `raw/main` install scripts and tags in sync without any manual `git push`. Gated on `GITEE_TOKEN`; skips cleanly when unset.
+
+## [1.0.40] - 2026-06-24
+
+This release adds China-accessible install mirrors so the CLI installs reliably from mainland China, where GitHub raw + Releases are slow or fail.
+
+### Added
+
+- **China mirror via Gitee + npmmirror** (#486; `scripts/install.sh`, `scripts/install.ps1`, `scripts/install-skills.sh`, `scripts/release/sync-to-gitee.sh`, `.github/workflows/release.yml`, `.github/workflows/mirror-to-gitee.yml`) — an opt-in `DWS_GITEE_REPO` env var makes all three installers resolve the latest version and every release asset (binary, `checksums.txt`, `dws-skills.zip`) from the Gitee OpenAPI v5 instead of GitHub; with it unset, installation defaults to GitHub (fully backward compatible). The release pipeline mirrors release attachments to the matching Gitee release after each tag (gated on `GITEE_TOKEN`/`GITEE_REPO`), and a hub-mirror workflow keeps the repo code in sync (gated on `GITEE_PRIVATE_KEY`). README documents three China install channels: Gitee raw script, Gitee release binaries, and the npm package via `registry.npmmirror.com`.
+- **Skills embedded in the binary** (#488; `skills_embed.go`, `internal/app/skill_setup.go`, `internal/app/skill_setup_embed.go`) — the `skills/` tree (mono + multi) is embedded into the `dws` binary via `go:embed` and `dws skill setup` defaults to the embedded copy, refreshing the installed skill instead of silently reusing a stale copy probed from the current working directory — so skills install offline with no separate download.
+
 ## [1.0.39] - 2026-06-18
 
 This release makes the AI-sent indicator opt-in. 1.0.38 unconditionally tagged every user-identity send/reply with the edition claw identity, so the IM server rendered a "Send from AI" badge under every message — and on the open edition a stale hardcoded value even leaked the Wukong-branded label (「悟空AI发送」) to external users. The badge is now off by default and shown only when the caller explicitly asks for it.

README.md

@@ -113,6 +113,36 @@ cp dws ~/.local/bin/         # install to PATH
 
 </details>
 
+## China mirror
+
+For users in mainland China, the following channels avoid GitHub network issues. By default (without setting these environment variables) the installer pulls from GitHub.
+
+**1. Install script + pre-built binary (Gitee mirror):**
+
+Repository mirror: `https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli`
+
+```bash
+DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | sh
+```
+
+> With `DWS_GITEE_REPO` set, the installer resolves the latest version and every release asset (binary, checksums, skills) from the Gitee API instead of GitHub. If it is unset, installation defaults to GitHub.
+
+**2. npm package (npmmirror mirror):**
+
+```bash
+npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com
+```
+
+> npmmirror automatically syncs public packages from the public npm registry, so this works directly in China.
+
+**3. Skills only (Gitee mirror):**
+
+```bash
+DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install-skills.sh | sh
+```
+
+> With `DWS_GITEE_REPO` set, `install-skills.sh` resolves the version and skills package from Gitee; it also auto-falls back to the Gitee mirror when GitHub is unreachable.
+
 ## Upgrade
 
 > Requires **v1.0.7** or later. For earlier versions, please re-run the [install script](#installation) to upgrade.
@@ -277,7 +307,7 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
 The repo ships a complete Agent Skill system under `skills/`, now organized into two layouts:
 
 - `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), recommended default.
-- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ... 18 products in total), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**
+- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ... 20 products in total), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**
 
 After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:
 
@@ -287,6 +317,8 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 ```
 
 > `install.sh` installs to `$HOME/.agents/skills/dws` (global); `install-skills.sh` installs to `./.agents/skills/dws` (current project).
+>
+> China users: prefix `DWS_GITEE_REPO` to use the Gitee mirror — see [China mirror](#china-mirror).
 
 **Switching or re-installing with `dws skill setup`:**
 
@@ -473,31 +505,48 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 
 </details>
 
+## DingTalk bot — connect a robot to your local AI
+
+`dws dev connect` bridges a DingTalk robot to a local AI CLI (Claude Code / Codex / opencode / Qoder / Gemini, or any tool via `--agent-cmd`): @-mention the bot in a chat and it answers using your local agent, keeping per-conversation multi-turn memory.
+
+```bash
+dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <secret>
+```
+
+In-chat **session commands** (send the bare command as the whole message — no agent turn, no tokens):
+
+| Command | Effect |
+|---------|--------|
+| `/new` (aliases `/start`, `/reset`) | Start a fresh session; the previous one is left intact (resumable where the agent supports it) |
+| `/clear` | Wipe the current session — disposed through the agent's real session op (opencode issues `DELETE /session/:id`); channels whose agent exposes no delete primitive fall back to a reset |
+
+See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step walkthrough (install → create robot → connect → add to a group).
+
 ## Key Services
 
 | Service | Command | Commands | Subcommands | Description |
 |---------|---------|:--------:|-------------|-------------|
 | Contact | `contact` | 15 | `user` `dept` `label` `relation` | Search users by name / mobile / job-number, batch query, departments, labels & roles, person relations, roster profile & dismissions, current user |
 | Chat / IM | `chat` (alias `im`) | 65 | `message` `group` `bot` `conversation-info` `search` `search-common` `list-top-conversations` `group-mute` `group-mute-member` `mute` `set-top` `list-categories` `list-conversations` | Messages (send / reply / list / list-all / by-sender / mentions / focused / unread / topic replies / search / advanced search / forward / cards / emoji & text-emotion reactions / recall / read & send status queries), group CRUD + member management (members add / remove / list / `add-bot`, member-role CRUD, invite URL, icon, settings, transfer-owner, set-admin, quit), bot-identity messaging (`send-by-bot` / `recall-by-bot` / `send-by-webhook`), conversation info, common-groups lookup, group/member/conversation mute, conversation set-top, conversation categories |
-| Calendar | `calendar` | 17 | `event` `room` `participant` `busy` | Events CRUD + suggested times + attachments, meeting room booking, free-busy query, participant management |
+| Calendar | `calendar` | 23 | `event` `book` `acl` `attendee` `participant` `room` `busy` `attachment` | Events CRUD + suggested times + attachments, calendar books (get / search / primary via `--id primary`), access-control list, attendee management (wukong-aligned naming, `--calendar-id` aware), meeting room booking, free-busy query |
 | Todo | `todo` | 16 | `task` `comment` | Create / list / update / done / get / delete tasks, plus task comments |
 | Approval | `oa` | 15 | `approval` | Approve / reject / revoke / redirect tasks, pending / initiated / submitted / executed / cc instances, process forms, comments, operation records |
 | Attendance | `attendance` | 4 | `record` `shift` `summary` `rules` | Clock-in records, shift schedules, attendance summary, group rules |
 | Ding | `ding` | 2 | `message` | Send / recall DING messages |
 | Report | `report` | 20 | `create` `submit` `list` `detail` `template` `stats` `inbox` `outbox` `entry` | Create / submit reports, sent & received (inbox / outbox) lists, templates (get / list), statistics, single-entry get |
-| AI Tables | `aitable` | 52 | `base` `table` `record` `field` `view` `dashboard` `chart` `import` `export` `attachment` `template` `form` | Full CRUD for Bases / datasheets / records / fields / views; charts & dashboards with public-share configs; data import/export; attachments (prepare-only `upload` + one-shot `upload-file`); datasheet forms; templates |
-| Doc | `doc` | 28 | `search` `list` `info` `read` `create` `update` `upload` `download` `copy` `move` `rename` `file` `folder` `block` `comment` | Search / read / write docs, file & folder create, block-level editing, comments (list / create / reply / create-inline), upload / download |
-| Drive | `drive` | 9 | `list` `list-spaces` `info` `download` `mkdir` `upload` `upload-info` `commit` `delete` | DingTalk drive file ops: list spaces, list / info / download, create folders, one-shot `upload` (three-step composite) or two-phase `upload-info` + `commit`, delete |
-| Minutes | `minutes` | 19 | `list` `get` `update` `mind-graph` `speaker` `hot-word` `upload` | List AI meeting notes (mine / shared), details (info / summary / keywords / transcription / todos / batch), title/summary updates, mind map, speaker replace, hot-word, upload session |
-| Mail | `mail` | 18 | `mailbox` `message` `draft` `folder` `tag` `thread` `attachment` `user` | List mailboxes, KQL message search, read & send messages, drafts, folders, tags, threads, attachments, address-book user search |
-| Sheet | `sheet` | 23 | `range` `filter-view` (top-level: `create` `new` `list` `info` `read` `get` `update` `find` `replace` `append` `merge-cells` `unmerge-cells` `add-dimension` `insert-dimension` `delete-dimension` `move-dimension` `update-dimension` `write-image`) | Online spreadsheet (`contentType=ALIDOC`, `extension=axls`): worksheet CRUD, range read / write / append, dimension ops, cell merge / unmerge, find / replace, named filter views + sheet-level filters, image write |
-| Wiki | `wiki` | 21 | `space` `member` `node` `doc` `file` | Knowledge base management: spaces (`create` / `get` / `list` / `search`), members (`add` / `list` / `update`), node tree, docs & files |
-| DevDoc | `devdoc` | 2 | `article` `error` | Search Open Platform documentation and troubleshoot API errors |
+| AI Tables | `aitable` | 102 | `base` `table` `record` `field` `view` `section` `advperm` `workflow` `dashboard` `chart` `import` `export` `attachment` `template` `form` | Full CRUD for Bases / datasheets / records / fields / views; node (section) management, advanced permission & roles, automation workflows; record upsert / share-url / history / primary-doc; view lock / duplicate / frozen-cols / row-height / fill-color-rule / card / timebar; charts & dashboards; import/export; attachments; forms; templates |
+| Doc | `doc` | 29 | `search` `list` `info` `read` `create` `update` `upload` `download` `copy` `move` `rename` `file` `folder` `block` `comment` `permission` `media` | Search / read / write docs, file & folder create, block-level editing, comments (list / create / reply / create-inline), permission management, media, upload / download |
+| Drive | `drive` | 17 | `list` `list-spaces` `info` `download` `mkdir` `upload` `upload-info` `commit` `delete` `copy` `move` `rename` `search` `permission` | DingTalk drive file ops: list / search / info / download, create folders, upload (one-shot or two-phase), copy / move / rename, permission management (list / mutation / remove), doc-transfer, delete |
+| Minutes | `minutes` | 31 | `list` `get` `tag` `update` `mind-graph` `speaker` `permission` `hot-word` `record` `upload` `replace-text` | List AI meeting notes (mine / shared / all), tags (list / query by tag), details (info / summary / keywords / transcription / todos / batch), title/summary updates, mind map, speaker, member permission, hot-word, recording control, upload session |
+| Mail | `mail` | 33 | `mailbox` `message` `send` `draft` `folder` `template` `contact` `tag` `thread` `attachment` `user` | List mailboxes, KQL search + folder-scoped message list, read & send messages, drafts, folder CRUD, message templates (CRUD), mail contacts (CRUD), tags, threads, attachments, address-book user search |
+| Sheet | `sheet` | 60 | `range` `filter` `filter-view` `cond-format` (+ dimension, float-image, dropdown, csv, merge, find/replace, write-image, …) | Online spreadsheet (`contentType=ALIDOC`, `extension=axls`): worksheet CRUD, range read / write / copy / fill / sort / style, dimension ops, filters & filter views, conditional formatting, float images, dropdowns, CSV get/put, cell merge / unmerge, find / replace, image write |
+| Wiki | `wiki` | 27 | `space` `member` `node` `doc` `file` | Knowledge base management: spaces (create / get / list / search / delete), members (add / list / update / remove), node tree (create / delete / list / search / move / copy / transfer), docs & files |
+| DevDoc | `devdoc` | 2 | `article` `error` | Search the DingTalk Open Platform documentation and diagnose API errors |
 | AI Search | `aisearch` | 3 | `person` | Enterprise people search by name / department / position / duty / supervisor / subordinate / phone / job-number (single command, multi-dimension filter) |
 | Live | `live` | 1 | `stream` | DingTalk live streaming: list my lives |
 | Raw API | `api` | 1 | — | Call any DingTalk OpenAPI directly (api / oapi dual-form), with automatic app-level token management |
 
-> **331 commands across 18 products.** Full listing with descriptions and usage scenarios: [`docs/command-index.md`](./docs/command-index.md). Run `dws --help` for the top-level tree, or `dws <service> --help` for subcommands.
+> **466 commands across 18 products** (after the dws-wukong alignment in 1.0.43). Full listing with descriptions and usage scenarios: [`docs/command-index.md`](./docs/command-index.md). Run `dws --help` for the top-level tree, or `dws <service> --help` for subcommands.
 
 > **Note on `chat bot`**: bot capabilities (`send-by-bot` / `recall-by-bot` / `add-bot` / `send-by-webhook` / bot search) are merged into the relevant `chat` subtrees (e.g. `dws chat message send-by-bot`, `dws chat group members add-bot`) so the agent-facing command surface stays flat and discoverable. There is no longer a separate top-level `bot` product.
 
@@ -557,6 +606,7 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 - [Command Index](./docs/command-index.md) — every runtime command with description and when-to-use guidance
 - [Reference](./docs/reference.md) — environment variables, exit codes, output formats, shell completion
 - [Architecture](./docs/architecture.md) — discovery-driven pipeline, IR, transport layer
+- [Open Platform App Command Routing](./docs/dev-yulan-command-routing.md) — yulan dev app command design, MCP overlay, permission flow, and Agent routing
 - [Changelog](./CHANGELOG.md) — release history and migration notes
 
 ## Contributing

README_zh.md

@@ -71,9 +71,9 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 | 模式 | 安装内容 | 适合场景 |
 |------|----------|----------|
 | **mono**（稳定，默认） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
-| **multi** 🧪 **试验版 / Preview** | 18 个独立产品 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
+| **multi** 🧪 **试验版 / Preview** | 20 个独立产品 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
 
-> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。18 个独立 skill 全部通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。
+> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。20 个独立 skill 全部通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。
 
 怎么选：
 
@@ -113,6 +113,36 @@ cp dws ~/.local/bin/         # 安装到 PATH
 
 </details>
 
+## 国内加速安装
+
+国内用户可使用以下通道，避免 GitHub 网络问题。默认（不设置这些环境变量）走 GitHub。
+
+**1. 安装脚本 + 预编译二进制（Gitee 镜像）：**
+
+仓库镜像地址：`https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli`
+
+```bash
+DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | sh
+```
+
+> 设置 `DWS_GITEE_REPO` 后，安装脚本会改从 Gitee API 解析最新版本和各个 release 产物（二进制、校验和、skills 包），而不是走 GitHub。不设置时默认从 GitHub 安装。
+
+**2. npm 包（npmmirror 镜像）：**
+
+```bash
+npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com
+```
+
+> npmmirror 会自动同步公网 npm 的公开包，国内可直接使用。
+
+**3. 单独安装 Skills（Gitee 镜像）：**
+
+```bash
+DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install-skills.sh | sh
+```
+
+> 同样设置 `DWS_GITEE_REPO`，`install-skills.sh` 会从 Gitee 解析版本和 skills 包；GitHub 不可达时也会自动回退到 Gitee 镜像。
+
 ## 升级
 
 > 需要 **v1.0.7** 及以上版本。更早版本请重新执行[安装脚本](#安装)进行升级。
@@ -284,6 +314,8 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 ```
 
 > `install.sh` 安装到 `$HOME/.agents/skills/dws`（全局）；`install-skills.sh` 安装到 `./.agents/skills/dws`（当前项目）。
+>
+> 国内用户加 `DWS_GITEE_REPO` 走 Gitee 镜像，见 [国内加速安装](#国内加速安装)。
 
 **用 `dws skill setup` 切换或重装：**
 
@@ -469,6 +501,23 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 
 </details>
 
+## 钉钉机器人 —— 把机器人接到你本地的 AI
+
+`dws dev connect` 把一个钉钉机器人接到本地 AI CLI（Claude Code / Codex / opencode / Qoder / Gemini，或用 `--agent-cmd` 接任意工具）：群里 @ 机器人提问，它用你本地的 agent 回答，按会话保留多轮上下文。
+
+```bash
+dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <secret>
+```
+
+聊天里的**会话指令**（整条消息就是指令时生效，不消耗一次 AI 调用）：
+
+| 指令 | 作用 |
+|------|------|
+| `/new`（别名 `/start`、`/reset`） | 开启新会话；旧会话保留（agent 支持的话仍可回溯） |
+| `/clear` | 清空当前会话 —— 调 agent 真实会话原语真删（opencode 走 `DELETE /session/:id`）；驱动接口没有删除原语的渠道退化为重置 |
+
+完整四步教程见 [`docs/robot-quickstart.md`](./docs/robot-quickstart.md)（装工具 → 建机器人 → 接上 AI → 拉进群）。
+
 ## 核心服务
 
 | 服务 | 命令 | 命令数 | 子命令 | 描述 |
@@ -488,7 +537,7 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 | 邮箱 | `mail` | 18 | `mailbox` `message` `draft` `folder` `tag` `thread` `attachment` `user` | 邮箱地址列表、KQL 邮件搜索、读取与发送邮件、草稿、文件夹、标签、会话、附件、通讯录用户搜索 |
 | 在线电子表格 | `sheet` | 23 | `range` `filter-view`（顶层：`create` `new` `list` `info` `read` `get` `update` `find` `replace` `append` `merge-cells` `unmerge-cells` `add-dimension` `insert-dimension` `delete-dimension` `move-dimension` `update-dimension` `write-image`） | 在线电子表格（`contentType=ALIDOC`、`extension=axls`）：工作表 CRUD、区域读写/追加、行列操作、合并/取消合并、查找替换、命名筛选视图 + 表级筛选、写入图片 |
 | 知识库 | `wiki` | 21 | `space` `member` `node` `doc` `file` | 知识库管理：空间（`create` / `get` / `list` / `search`）、成员（`add` / `list` / `update`）、节点树、文档与文件 |
-| 开发者文档 | `devdoc` | 2 | `article` `error` | 搜索钉钉开放平台文档、排查开放平台调用错误 |
+| 开发者文档 | `devdoc` | 2 | `article` `error` | 搜索钉钉开放平台文档并排查 API 调用错误 |
 | AI 搜问 | `aisearch` | 3 | `person` | 企业人员搜索：按姓名 / 部门 / 职位 / 职责 / 上级 / 下级 / 手机号 / 工号 多维度过滤（单命令） |
 | 直播 | `live` | 1 | `stream` | 钉钉直播：查看我的直播列表 |
 | Raw API | `api` | 1 | — | 直接调用任意钉钉 OpenAPI（api / oapi 双形态），自动管理应用级 Token |
@@ -555,6 +604,7 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 - [命令索引](./docs/command-index.md) — 全部运行时命令，带描述与使用场景
 - [参考手册](./docs/reference.md) — 环境变量、退出码、输出格式、Shell 补全
 - [架构设计](./docs/architecture.md) — 发现驱动管道、IR、Transport 层
+- [开放平台应用指令设计](./docs/dev-yulan-command-routing.md) — yulan dev app 应用侧命令、MCP overlay、权限流程与 Agent 路由
 - [更新日志](./CHANGELOG.md) — 版本历史与迁移说明
 
 ## 贡献指南

build/homebrew.rb.tmpl

@@ -43,6 +43,8 @@ __KEG_ONLY_LINE__
       Pathname.new(File.join(Dir.home, ".agents/skills/dws")),
       Pathname.new(File.join(Dir.home, ".claude/skills/dws")),
       Pathname.new(File.join(Dir.home, ".cursor/skills/dws")),
+      Pathname.new(File.join(Dir.home, ".qoder/skills/dws")),
+      Pathname.new(File.join(Dir.home, ".qoderwork/skills/dws")),
       Pathname.new(File.join(Dir.home, ".gemini/skills/dws")),
       Pathname.new(File.join(Dir.home, ".codex/skills/dws")),
       Pathname.new(File.join(Dir.home, ".github/skills/dws")),

build/npm/install.js

@@ -12,6 +12,8 @@ const AGENT_DIRS = [
   ".agents/skills",
   ".claude/skills",
   ".cursor/skills",
+  ".qoder/skills",
+  ".qoderwork/skills",
   ".gemini/skills",
   ".codex/skills",
   ".github/skills",

docs/command-index.md

@@ -187,7 +187,7 @@ _Search the DingTalk Open Platform documentation._
 | Command | Description | When to use |
 |---|---|---|
 | `dws devdoc article search` | Search the DingTalk Open Platform documentation by keyword. | When the agent needs authoritative API reference or guides to answer a developer question. |
-| `dws devdoc error diagnose` | Troubleshoot an Open Platform API failure by requestId, error code, error message, or context. | When the agent has a requestId, traceId, error code, or failure description and needs diagnostic facts plus references. |
+| `dws devdoc error diagnose` | Troubleshoot an Open Platform API failure by requestId, traceId, error code, error message, or context. | When the agent has a requestId, traceId, error code, or failure description and needs diagnostic facts plus references. |
 
 ## `dws ding` — DING Messages
 

docs/connect-daemon-service.md

@@ -0,0 +1,128 @@
+# Running the connector as a 7x24 service
+
+`dws devapp robot connect` keeps a DingTalk robot wired to a local agent over a
+Stream long-connection. By default it runs in the foreground and dies when the
+terminal closes. For an unattended "digital employee" you have two options.
+
+## Option A: built-in daemon (recommended for a quick start)
+
+```bash
+# Detach into a background supervisor that restarts the connector if it crashes.
+dws devapp robot connect --daemon \
+  --channel claudecode \
+  --robot-client-id <clientId> --robot-client-secret <clientSecret>
+
+# Inspect / stop it.
+dws devapp robot connect status --robot-client-id <clientId>
+dws devapp robot connect stop   --robot-client-id <clientId>
+```
+
+- The parent prints the daemon pid and the log path, then exits.
+- A supervisor process (POSIX `setsid`, detached from the terminal) keeps a
+  worker connector alive, restarting it with exponential backoff (1s..60s, up to
+  10 consecutive fast failures) when it exits abnormally.
+- The single-instance lock (one connector per robot per machine) is reused, so a
+  duplicate daemon refuses to start.
+- Logs go to `~/.dws/connect/<clientId>/daemon.log` with size-based rotation
+  (5 MB x 2 backups), and the pid file lives at
+  `~/.dws/connect/<clientId>/daemon.pid`.
+- The daemon does NOT survive a reboot. For that, use Option B.
+
+> Windows: `--daemon` is not supported (no `setsid` / POSIX signal stop). Use a
+> Windows service wrapper around the foreground command instead.
+
+## Option B: OS service manager (survives reboot)
+
+Use the foreground command (NOT `--daemon`) and let the OS supervise and
+restart it. This is the most robust way to get boot-time auto-start.
+
+### macOS — launchd
+
+Save as `~/Library/LaunchAgents/com.dingtalk.dws.connect.plist`, edit the paths
+and credentials, then `launchctl load -w <path>`.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.dingtalk.dws.connect</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/dws</string>
+    <string>devapp</string>
+    <string>robot</string>
+    <string>connect</string>
+    <string>--channel</string>
+    <string>claudecode</string>
+    <string>--robot-client-id</string>
+    <string>REPLACE_CLIENT_ID</string>
+    <string>--robot-client-secret</string>
+    <string>REPLACE_CLIENT_SECRET</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/dws-connect.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/dws-connect.err.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>
+```
+
+`KeepAlive=true` makes launchd restart the connector if it exits; the connector
+itself relies on the single-instance lock to avoid duplicates.
+
+### Linux — systemd (user service)
+
+Save as `~/.config/systemd/user/dws-connect.service`, edit paths/credentials,
+then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now dws-connect.service
+# allow it to keep running after logout:
+loginctl enable-linger "$USER"
+```
+
+```ini
+[Unit]
+Description=DWS DingTalk robot connector
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/dws devapp robot connect \
+  --channel claudecode \
+  --robot-client-id REPLACE_CLIENT_ID \
+  --robot-client-secret REPLACE_CLIENT_SECRET
+Restart=always
+RestartSec=5
+# Optional hardening:
+# NoNewPrivileges=true
+# PrivateTmp=true
+
+[Install]
+WantedBy=default.target
+```
+
+`Restart=always` + `RestartSec` gives crash recovery; systemd captures stdout/
+stderr into the journal (`journalctl --user -u dws-connect -f`).
+
+## Which to choose
+
+- Just need it to outlive the terminal and self-heal on crash → `--daemon`.
+- Need it to come back after a reboot, with the OS owning the lifecycle → use
+  launchd / systemd with the foreground command.

docs/dev-agent-test-cases.md

@@ -0,0 +1,137 @@
+# dws dev 命令集 · Agent 人肉手工评测集（10 条复合用例）
+
+> 性质：**人肉手工评测集**——由测评人逐条手工跑、肉眼核对、人工判分，不是自动化脚本。
+> 用途：评测 agent（加载 `dingtalk-dev` 技能后）能否正确处理开放平台 dev 任务。
+> 特点：10 条**复合用例**，每条串多个子任务，一条覆盖一类完整场景；10 条合起来覆盖全部 34 个子命令 + 8 类横切行为。
+> 约定：所有命令应带 `--format json`；写操作应先 `--dry-run` 预览、用户确认后再 `--yes`；应用定位只用 `--unified-app-id`。
+
+## 手工评测流程
+
+逐条执行，每条三步：
+
+1. **发起**：在一个干净的 agent 会话里，把该条的「用户说」原样发给 agent（不给额外提示）。
+2. **观察**：看 agent 选了哪些命令、什么 flag、做了哪些判断/追问。
+3. **判分**：对照「通过判据」人工打分。复合用例含多个判据，**全部满足才记 PASS**；部分满足记 PASS\*（半通过）并在备注写清缺哪条。记一行 `用例# | PASS / PASS* / FAIL | 备注（错在哪）`。
+
+> 「易错点」是常见扣分项，重点盯。建议每次技能改动后整套重跑，对比上次。
+
+## 覆盖矩阵
+
+| 用例 | 覆盖的子命令 | 横切行为 |
+|------|-------------|---------|
+| C1 建应用配齐基础 | app create / get / credentials get / update | dry-run/yes、定位符、密钥脱敏 |
+| C2 列表与定位 | app list | cursor 分页、按名定位、多命中候选 |
+| C3 生命周期 | app disable / enable / delete | 写后回读、appStatus、pretty 标签、confirm-name 防误删 |
+| C4 网页应用到生效 | webapp get / config | 生效模型（改配置≠生效） |
+| C5 版本发布全流程 | version create / list / get / check-approval / publish / status | 生效模型、审批人由用户拍板 |
+| C6 权限全流程 | permission list / add / remove | 过滤分页、生效模型、批量聚合出参 |
+| C7 成员与安全 | member list / add / remove、security config | 整组覆盖语义 |
+| C8 机器人与建联 | robot submit / result / get / config / enable / disable、dev connect | 异步轮询、robot info not exist、建联依赖预检、长驻进程 |
+| C9 事件与文档排查 | event list / subscribe / unsubscribe、dev doc search | 错误码透传、文档 RAG |
+| C10 意图消歧 | （不进 dev，先澄清） | 泛词边界、转其它技能出口 |
+
+---
+
+## 用例
+
+### C1. 新建应用并配齐基础
+- **用户说**：「建一个内部应用叫 DemoApp，描述『内部测试』；建好后给我看看它的详情，把它的 AppKey/AppSecret 也取出来；对了名字再改成 DemoApp2。」
+- **覆盖**：`app create` / `get` / `credentials get` / `update`；dry-run/yes、定位符、密钥脱敏。
+- **期望（分步）**：
+  1. `app create --name DemoApp --desc 内部测试 --dry-run` → 给用户看 `invocation.params` 确认 → `--yes`，记下返回的 `unifiedAppId`。
+  2. `app get --unified-app-id <id> --format json` 看详情。
+  3. `credentials get --unified-app-id <id> --format json` 取凭证。
+  4. `app update --unified-app-id <id> --name DemoApp2 --dry-run` → `--yes`。
+- **通过判据**：每个写操作先 dry-run 再 yes；全程用 `unifiedAppId` 定位；取凭证走 `credentials get`（不是 app get）；`clientSecret/appSecret` 按敏感处理、不明文写进回答。
+- **易错点**：不 dry-run 直接 yes；把 secret 打印给用户；用 `app get` 当取凭证。
+
+### C2. 应用列表与按名定位
+- **用户说**：「列出我们企业的开放平台应用，一页 20 条，有下一页继续翻；再帮我找名字叫『早晚会』的那个应用，看它详情。」
+- **覆盖**：`app list`；cursor 分页、按名定位、多命中。
+- **期望（分步）**：
+  1. `app list --page-size 20 --format json`；出参有 `nextCursor` 则续翻 `--cursor <上次 nextCursor>` 直到为空。
+  2. `app list --name 早晚会 --format json` 找 `unifiedAppId` → 唯一命中后 `app get --unified-app-id <id>`。
+- **通过判据**：首次不传 `--cursor`，续翻原样回传 `nextCursor`，不自己构造/解析、不跨命令复用；用 list 过滤拿 id 再 get；多条命中时展示候选让用户选、不取第一条。
+- **易错点**：用 `--page/--offset` 翻页；`app get --name xxx`（get 不接受 name 定位）。
+
+### C3. 应用生命周期（停用 / 启用 / 删除）
+- **用户说**：「先把 DemoApp2 停用，确认停好了告诉我；然后再启用回来；最后这个应用不要了，删掉。」
+- **覆盖**：`app disable` / `enable` / `delete`；写后回读、appStatus、pretty、confirm-name。
+- **期望（分步）**：
+  1. `disable --unified-app-id <id> --dry-run` → `--yes` → 回读 `app get`（可 `--format pretty` 看 `appStatusText`），确认 `appStatus=0` 才算停用完成。
+  2. `enable --dry-run` → `--yes` → 回读确认 `appStatus=1`。
+  3. 删除：先 `app get` 展示摘要 → `delete --dry-run` → 真删需 `--confirm-name <应用真实名>`（与定位到的名一致）+ `--yes`。
+- **通过判据**：写成功 ≠ 状态已变，每步回读 appStatus（0停/1激活/2待激活/3过期）；删除前展示摘要并让用户确认；confirm-name 匹配才删，读不到应用名时中止（fail-closed）。
+- **易错点**：看到 success 就回报已停/已删不回读；不带 confirm-name 直接删。
+
+### C4. 网页应用配置到生效
+- **用户说**：「给这个应用配个钉钉里打开的移动端首页 https://example.com/m，配完要真正能用。」
+- **覆盖**：`webapp config` / `get`；生效模型。
+- **期望（分步）**：`webapp config --unified-app-id <id> --homepage-url https://example.com/m --dry-run` → `--yes` → `webapp get` 回读；明确说明「改配置 ≠ 线上生效，需走版本通道」：`version create → check-approval → publish`（详见 C5）。
+- **通过判据**：先 dry-run 再 yes；配完回读 webapp get；主动点明需发版本才生效，不谎称「已生效」。
+- **易错点**：配完直接说已生效，不提版本通道。
+
+### C5. 版本发布全流程（含选审批人）
+- **用户说**：「我刚改了配置，发个版本上线；先看下历史版本和这次要发的版本详情；需要审批的话我来选审批人。」
+- **覆盖**：`version create` / `list` / `get` / `check-approval` / `publish` / `status`；生效模型、审批人由用户拍板。
+- **期望（分步）**：
+  1. `version create --unified-app-id <id> --version <号> --desc <说明> --yes`，记 `versionId`（新应用 `version list` 空时先 create，不要误判无可发布）。
+  2. `version list` 看历史、`version get --version-id <id>` 看详情。
+  3. `version check-approval --version-id <id>`（预检，不发布，返回是否需审批 + 候选审批人）。
+  4. 把候选审批人列表给用户选 → `version publish --version-id <id> --approver <用户选的> --yes`（含高敏权限加 `--confirm-sensitive`）。
+  5. `version status --version-id <id>` 跟踪到 `versionStatus=RELEASE` 才算生效。
+- **通过判据**：check-approval 不实际发布；审批人由用户拍板、agent 不默认取第一个；发布后回读 status 到 RELEASE。
+- **易错点**：跳过 check-approval 直接 publish；agent 自己选审批人；version list 空就说没东西可发。
+
+### C6. 权限全流程（查 / 申请 / 批量取消）
+- **用户说**：「查下跟『机器人发消息』有关、还没开通的权限；开通其中合适的那个，要真正生效；再把另外两个不需要的权限点 A、B 一起取消掉。」
+- **覆盖**：`permission list` / `add` / `remove`；过滤分页、生效模型、批量聚合。
+- **期望（分步）**：
+  1. `permission list --unified-app-id <id> --keyword 机器人发消息 --status UNAUTHED --page-size 50` 找 `scopeValue`（150+ 时用 `nextCursor` 续翻）。
+  2. `permission add --permissions <scopeValue> --dry-run` → `--yes`；若 `requiredApproval=true`，走版本通道生效（接 C5）。
+  3. `permission remove --permissions A,B --dry-run` → `--yes`，读出参 `{results, ok, total, failedCount}` 逐条判断。
+- **通过判据**：只传 `scopeValue`（不传 API/分组名）；用 keyword+status 过滤、分页不漏；需审批的明确走版本；批量取消读 `ok/failedCount` 报告部分失败，不只看命令成功。
+- **易错点**：把 API 名当权限点；add 后就说开通了；批量 remove 漏报部分失败。
+
+### C7. 成员与安全配置
+- **用户说**：「把 userId 张三、李四加成这个应用的开发者，加完看下成员列表，回头把李四移除；另外给应用加一个登录重定向地址 https://b.example.com/cb，别把原来的地址冲掉。」
+- **覆盖**：`member list` / `add` / `remove`、`security config`；整组覆盖。
+- **期望（分步）**：
+  1. `member add --unified-app-id <id> --user-ids 张三id,李四id --member-type DEVELOPER --dry-run` → `--yes` → `member list` 回读 → `member remove --user-ids 李四id --member-type DEVELOPER --dry-run` → `--yes`。
+  2. 安全配置：提醒 `--redirect-urls` 是**整组覆盖、不是追加**——要保留原地址需把旧+新一起传：`security config --redirect-urls <旧1,旧2,新> --dry-run` → `--yes`。
+- **通过判据**：`--user-ids` 逗号分隔、`--member-type` 必填、用 userId 不用姓名；识别整组覆盖语义、避免只传新地址冲掉旧的；未提供的字段（如 ip-whitelist）不动。
+- **易错点**：漏 `--member-type`；security 只传新 redirect-urls 把旧的清空。
+
+### C8. 机器人建号、配置与本地建联
+- **用户说**：「帮我建一个叫『小助手』的答疑机器人；另外这个现有应用还没机器人，给它也配上并启用；最后把机器人接到我本地的 Claude Code 调试。」
+- **覆盖**：`robot submit` / `result` / `get` / `config` / `enable` / `disable`、`dev connect`；异步轮询、robot info not exist、建联依赖预检、长驻进程、密钥脱敏。
+- **期望（分步）**：
+  1. 新建：`robot submit --name <应用名> --robot-name 小助手 --desc <功能> --dry-run` → `--yes`（拿 taskId）→ 按 `intervalSeconds` 轮询 `robot result --task-id <taskId>`，只有 `SUCCESS` 才用返回 `robotCode/clientId/clientSecret`（敏感）。
+  2. 现有应用：`robot get` 若 `robotStatus=UNCONFIGURED` → `robot config --unified-app-id <id> --name ... --mode STREAM --dry-run` → `--yes`（upsert 首次即创建）→ 回读 `robot get` 看 `robotStatus=ONLINE` → 需要时 `robot enable`（停用 `robot disable`）。
+  3. 建联：`dev connect --channel auto --robot-client-id x --robot-client-secret y --dry-run` 看出参 `cli` 字段做依赖预检；正式 connect 是前台长驻进程，对话里跑要后台运行并告诉用户怎么停，或引导自己开终端。
+- **通过判据**：走异步 submit/result（同步建号已下线），轮询到 SUCCESS 再用凭证；未配置时走 config 不是 enable；config 是 upsert；写后回读 `robotStatus`；建联先 dry-run 预检、处理好长驻/缺凭证（先 submit/result 建号）。
+- **易错点**：找「同步一次建好」的命令；WAITING 就用凭证；robot info not exist 时去 enable；前台直接起 connect 卡住对话。
+
+### C9. 事件订阅与上游错误排查
+- **用户说**：「让这个应用订阅『群成员入群』事件，订阅完看下当前订阅了哪些，再把它取消掉；对了我之前发版本报了个 errcode 62012，这是啥意思？」
+- **覆盖**：`event list` / `subscribe` / `unsubscribe`、`dev doc search`；错误码透传、文档 RAG。
+- **期望（分步）**：
+  1. `event list --unified-app-id <id> --page-size 20 --format json` 取 `eventCode` → `event subscribe --unified-app-id <id> --event-codes chat_add_member_org --dry-run` → `--yes` → `event list` 回读 → `event unsubscribe --unified-app-id <id> --event-codes chat_add_member_org --dry-run` → `--yes`。事件码不确定先 `event list` 翻页查。
+  2. 错误码：业务错误 `ServiceResult.success=false` 原样透传 `errorCode/errorMsg`，再 `dev doc search --keyword "errcode 62012 <message>" --format json` 做官方文档 RAG，结论基于命中条目。
+- **通过判据**：`--event-codes` 逗号分隔，写操作先 dry-run；`event list` 使用 `hasMore/nextCursor` 翻页；不编造事件码/错误含义；先透传原始错误再走 RAG，结论不臆测、不编不存在的命令。
+- **易错点**：编事件码；把事件回调地址塞进事件订阅命令；凭空解释错误码。
+
+### C10. 意图消歧（泛词边界）
+- **用户说**：「帮我建个机器人。」（无任何开放平台上下文）
+- **覆盖**：泛词消歧、边界与角色。
+- **期望**：`应用`/`机器人` 是泛词——先追问确认是不是开发者后台的「企业内部应用机器人」，还是工作台应用、或群里发消息的机器人（→ `dingtalk-chat`）；确认是开放平台场景后才走 dev 流程（接 C8）。
+- **通过判据**：不直接假设走 dev，先澄清；能正确指向其它技能出口。
+- **易错点**：上来就 `robot submit`，没确认是不是开放平台场景。
+
+---
+
+## 备注
+
+- 10 条合起来覆盖全部 34 个子命令 + 8 类横切行为（见覆盖矩阵）。
+- 评测可分两层：**静态**——无环境，只看 agent 选的命令/flag/判断是否符合「期望/通过判据」；**真机**——有联调环境时核对真实出参。
+- 真机注意：`dev connect` 正式连接是长驻进程；`version publish`/`app delete` 等写操作请用占位应用或停在 dry-run，避免动真实数据。

docs/devapp-agent-install-guide.md

@@ -0,0 +1,321 @@
+# dws dev 一键安装与 Agent 接入指南
+
+面向希望用 Codex、Claude、Cursor 等开发 Agent 管理钉钉开放平台应用的开发者。
+
+这份指南参考 Notion Developer Platform 的引导方式：先给出一条可复制的安装命令，再用最短路径完成验证、登录、Agent 调用和排障。
+
+## 一键安装
+
+`dws dev` 能力已经合入主干并随正式版发布。专用安装脚本会下载预编译二进制 + `dingtalk-dev` skill，**只需要 curl + tar，不需要 git / go / make**。
+
+### macOS / Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-devapp.sh | sh
+```
+
+### Windows（PowerShell）
+
+```powershell
+irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-devapp.ps1 | iex
+```
+
+这个脚本会：
+
+1. 从 `DingTalk-Real-AI/dingtalk-workspace-cli` 的最新 Release 下载对应平台的预编译二进制。
+2. 安装 `dws` 到默认目录 `~/.local/bin`。
+3. 从 Release 的 skills 包里安装 `dingtalk-dev` skill 到本机已检测到的 Agent 目录。
+
+支持这些环境变量（全部可选）：
+
+| 变量 | 说明 |
+|---|---|
+| `DEVAPP_REPO` | 覆盖发布仓库，默认 `DingTalk-Real-AI/dingtalk-workspace-cli` |
+| `DEVAPP_VERSION` | 钉某个 release tag，默认取最新 release |
+| `DWS_INSTALL_DIR` | 二进制安装目录，默认 `~/.local/bin` |
+| `DWS_NO_SKILLS` | 设为 `1` 跳过 `dingtalk-dev` skill 安装 |
+
+> `dws dev` 已在正式版里，所以你也可以直接用标准安装脚本 `install.sh`，二者都会带上 `dws dev`。
+
+### 国内加速
+
+`dws dev` 已在正式版里，国内用户直接用标准安装脚本的 Gitee 镜像即可（二进制和 skill 都从 Gitee 拉，避免 GitHub 网络问题）：
+
+```bash
+DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | sh
+```
+
+## 安装后验证
+
+先确认 `dws` 可执行：
+
+```bash
+dws version
+```
+
+确认 `dws dev app` 命令存在：
+
+```bash
+dws dev app --help --format json
+```
+
+如果能看到 `list`、`get`、`create`、`update`、`permission`、`member`、`robot`、`security`、`version`、`webapp`、`event`、`credentials` 等子命令，说明已安装成功。
+
+确认登录状态：
+
+```bash
+dws auth status
+```
+
+如果尚未登录：
+
+```bash
+dws auth login
+```
+
+登录完成后读取应用列表：
+
+```bash
+dws dev app list --format json
+```
+
+## dws dev 是什么
+
+`dws dev` 是钉钉开放平台开发者命令组，三块能力：
+
+- `dws dev app` — 开放平台企业内部应用的全生命周期管理（创建、配置、权限、成员、安全、机器人、版本发布、事件订阅）。
+- `dws dev connect` — 把现成机器人接到当前本地 agent（起 Stream 连接做本地转发，不建号、不产生审批工单）。
+- `dws dev doc` — 开放平台开发文档搜索。
+
+安装后，开发者和 Agent 可以用统一命令管理企业内部应用，而不需要反复进入开发者后台页面。它让 Agent 可以完成这些工作：
+
+- 查询、创建、更新、启用、停用、删除开放平台应用。
+- 查询应用凭证，读取 `clientId` / `appKey`，敏感凭证走专用命令。
+- 配置网页应用首页和管理后台地址。
+- 查询、申请、移除权限点。
+- 管理应用成员。
+- 配置安全项，包括 IP 白名单、登录重定向 URL、端内免登地址。
+- 异步创建机器人、配置/启停现有机器人。
+- 创建版本、发起发布、查询审批和发布状态。
+
+## 给 Agent 使用
+
+安装完成后，可以直接让 Agent 操作 `dws dev`。
+
+示例：
+
+```text
+帮我查一下最近创建的开放平台应用。
+```
+
+```text
+帮我给 unifiedAppId=<unifiedAppId> 的应用配置机器人，先 dry-run 给我确认。
+```
+
+```text
+帮我查询这个应用缺哪些权限点，并申请 Contact.User.mobile。
+```
+
+```text
+帮我发布这个应用版本，先预检是否需要审批。
+```
+
+Agent 写操作必须遵循：
+
+1. 先查询定位应用。
+2. 先 dry-run 预览。
+3. 明确展示将要修改的应用、字段和值。
+4. 用户确认后加 `--yes` 执行。
+5. 执行后回读验证。
+
+## 第一个写操作
+
+推荐用机器人配置作为 smoke test。建号是异步的，分两步。
+
+提交建号任务（记下返回的 `taskId`）：
+
+```bash
+dws dev app robot submit \
+  --name "告警助手" \
+  --robot-name "告警机器人" \
+  --desc "处理告警通知和事件回调" \
+  --dry-run \
+  --format json
+```
+
+确认预览无误后去掉 `--dry-run`、加 `--yes` 执行，再用返回的 `taskId` 查结果，直到 `status` 变成 `SUCCESS`：
+
+```bash
+dws dev app robot result --task-id <taskId> --format json
+```
+
+对**已有机器人**的应用，改配置/启停用 `robot config` / `robot enable` / `robot disable`：
+
+```bash
+dws dev app robot get --unified-app-id <unifiedAppId> --format json
+dws dev app robot config --unified-app-id <unifiedAppId> --name "新机器人名称" --dry-run --format json
+```
+
+## 常用命令
+
+### 应用管理
+
+```bash
+dws dev app list --format json
+dws dev app get --unified-app-id <unifiedAppId> --format json
+dws dev app create --name "考勤应用" --dry-run --format json
+dws dev app update --unified-app-id <unifiedAppId> --name "新应用名" --dry-run --format json
+dws dev app enable --unified-app-id <unifiedAppId> --dry-run --format json
+dws dev app disable --unified-app-id <unifiedAppId> --dry-run --format json
+dws dev app delete --unified-app-id <unifiedAppId> --confirm-name "<应用名>" --format json
+```
+
+> 删除不可逆，需要用 `--confirm-name` 传入应用名做二次确认。
+
+### 凭证查询
+
+```bash
+dws dev app credentials get --unified-app-id <unifiedAppId> --format json
+```
+
+凭证输出可能包含敏感字段，不要把完整结果写入文档、日志或长期记忆。
+
+### 权限点管理
+
+```bash
+dws dev app permission list --unified-app-id <unifiedAppId> --format json
+dws dev app permission add --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run --format json
+dws dev app permission remove --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run --format json
+```
+
+权限申请和移除只使用 `scopeValue`，不要传 API 名或权限分组名。
+
+### 机器人能力
+
+```bash
+dws dev app robot get --unified-app-id <unifiedAppId> --format json
+dws dev app robot submit --name "<智能体名>" --robot-name "<机器人名>" --desc "<描述>" --dry-run --format json
+dws dev app robot result --task-id <taskId> --format json
+dws dev app robot config --unified-app-id <unifiedAppId> --name "机器人名称" --dry-run --format json
+dws dev app robot enable --unified-app-id <unifiedAppId> --dry-run --format json
+dws dev app robot disable --unified-app-id <unifiedAppId> --dry-run --format json
+```
+
+### 成员与安全
+
+```bash
+dws dev app member list --unified-app-id <unifiedAppId> --format json
+dws dev app member add --unified-app-id <unifiedAppId> --user-ids <userId> --dry-run --format json
+dws dev app member remove --unified-app-id <unifiedAppId> --user-ids <userId> --dry-run --format json
+dws dev app security config --unified-app-id <unifiedAppId> --redirect-urls <url> --dry-run --format json
+dws dev app security config --unified-app-id <unifiedAppId> --ip-whitelist <ip> --dry-run --format json
+```
+
+### 网页应用与事件
+
+```bash
+dws dev app webapp get --unified-app-id <unifiedAppId> --format json
+dws dev app webapp config --unified-app-id <unifiedAppId> --homepage-url <url> --dry-run --format json
+dws dev app event list --unified-app-id <unifiedAppId> --format json
+dws dev app event subscribe --unified-app-id <unifiedAppId> --dry-run --format json
+dws dev app event unsubscribe --unified-app-id <unifiedAppId> --dry-run --format json
+```
+
+### 版本发布
+
+```bash
+dws dev app version list --unified-app-id <unifiedAppId> --format json
+dws dev app version create --unified-app-id <unifiedAppId> --dry-run --format json
+dws dev app version check-approval --unified-app-id <unifiedAppId> --version-id <versionId> --format json
+dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --dry-run --format json
+dws dev app version status --unified-app-id <unifiedAppId> --version-id <versionId> --format json
+```
+
+> 发布前先用 `version check-approval` 预检是否需要审批。含高敏权限的版本，`publish` 需加 `--confirmed-sensitive`。
+
+## 安全边界
+
+`dws dev` 的目标不是绕过开发者后台权限，而是让 CLI、MCP 和 Web 后台保持一致。
+
+默认安全策略：
+
+- 写操作先 dry-run。
+- 删除、停用、发布必须由用户确认（删除还需 `--confirm-name` 二次确认）。
+- Agent 不接收用户手动传入的 access token、cookie、`clientSecret`、`appSecret`。
+- 应用定位优先使用 `unifiedAppId`、`agentId`、`appKey`。
+- 对权限点申请、成员变更、安全配置、版本发布记录操作结果，便于审计和回滚。
+
+## 排障
+
+### `dws dev app` 不存在
+
+先确认装上的是带 `dws dev` 的版本：
+
+```bash
+dws version
+dws dev app --help --format json
+```
+
+如果命令缺失，重新执行本文的一键安装命令（或标准 `install.sh`）升级到最新正式版。
+
+### `dws dev app list` 失败
+
+优先检查登录态：
+
+```bash
+dws auth status
+dws auth login
+```
+
+然后确认当前账号能访问目标企业，并且当前用户在目标企业内。
+
+### 提示"当前用户没有开发者身份"
+
+创建应用需要开放平台开发者权限。请企业管理员在钉钉开放平台（open-dev.dingtalk.com）的「权限管理」中把你的账号添加为开发者，然后重试。
+
+### 页面能操作，但 CLI 或 MCP 提示无权限
+
+通常说明 CLI/MCP 后端鉴权和 Web 后台权限没有对齐。先确认当前用户是否满足以下任一条件：
+
+- 应用 owner。
+- 应用管理员。
+- 应用开发者。
+- 企业管理员或具备开放平台应用管理权限的角色。
+
+### 机器人配置失败
+
+先查当前机器人状态：
+
+```bash
+dws dev app robot get --unified-app-id <unifiedAppId> --format json
+```
+
+如果机器人不存在，用 `robot submit` 异步创建；如果已存在，用 `robot config` 修改，或用 `robot enable` 重新启用。
+
+## 页面文案建议
+
+用于产品页顶部：
+
+```text
+Install dws dev in one command.
+
+Let your coding agents manage DingTalk Open Platform apps from the terminal:
+create apps, configure robots, apply permissions, manage security settings,
+and publish versions with dry-run safety built in.
+```
+
+中文版本：
+
+```text
+一行命令接入 dws dev。
+
+让 Codex、Claude、Cursor 等开发 Agent 直接管理钉钉开放平台应用：
+创建应用、配置机器人、申请权限、管理安全配置、发布版本。
+所有写操作先预览，再确认执行。
+```
+
+## 参考
+
+- Notion Developer Platform: https://www.notion.com/product/dev
+- Notion CLI Help: https://www.notion.com/help/use-notion-from-your-terminal-with-notion-cli
+- Notion Developer Platform Blog: https://www.notion.com/blog/introducing-developer-platform

docs/robot-quickstart.md

@@ -0,0 +1,147 @@
+# 钉钉 AI 群机器人快速上手
+
+10 分钟搭一个自己的钉钉群答疑机器人：群里 @它 提问，它用你本地的 AI（Claude Code / Codex / Qoder 等）回答，支持发文字和报错截图。
+
+只需四步：装工具 → 建机器人 → 接上 AI → 拉进群。
+
+## 第一步：安装 dws
+
+一键脚本会自动下载最新版二进制 + `dingtalk-dev` skill，只需要 curl（无需 go / git）。
+
+### macOS / Linux
+
+打开终端，整段复制执行：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-devapp.sh | sh
+```
+
+> 国内用户：`dws dev` 已在正式版里，直接用标准安装脚本的 Gitee 镜像即可（二进制和 skill 都从 Gitee 拉，避免 GitHub 网络问题）：
+> ```bash
+> DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | sh
+> ```
+
+装完按提示把 `~/.local/bin` 加进 `PATH`（脚本会在末尾提示），然后执行 `dws version` 确认。
+
+### Windows
+
+打开 PowerShell，整段复制执行：
+
+```powershell
+irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-devapp.ps1 | iex
+```
+
+然后**重新打开一个 PowerShell 窗口**，执行 `dws version` 确认。
+
+> 能打印出版本号即安装成功（脚本默认装最新正式版）。脚本走 GitHub API 取最新 release，无需手动填版本号；想钉某个版本可设环境变量 `DEVAPP_VERSION`。
+
+### 登录钉钉
+
+```bash
+dws auth login
+```
+
+按提示扫码登录即可。
+
+## 第二步：创建机器人
+
+建号是异步的，两步（名字、描述可以改成你自己的）：
+
+```bash
+# 1) 提交建号任务，记下返回的 taskId
+dws dev app robot submit --name 我的智能体 --robot-name 小助手 --desc "群内答疑" --yes --format json
+
+# 2) 用上一步的 taskId 查结果，直到 status 变成 SUCCESS（还是 WAITING 就过几秒再查一次）
+dws dev app robot result --task-id 上一步返回的taskId --format json
+```
+
+`status` 变成 `SUCCESS` 后，返回结果里的 `clientId` 和 `clientSecret` **保存好**，下一步要用。
+
+## 第三步：把机器人接上你本地的 AI
+
+```bash
+dws dev connect --channel auto --robot-client-id dingxxxxxxxxxxxxxxxx --robot-client-secret yyyyyyyyyyyyyyyyyyyy
+```
+
+- 把 `dingxxxxxxxxxxxxxxxx` 和 `yyyyyyyyyyyyyyyyyyyy` 换成第二步返回的 `clientId` 和 `clientSecret` 的实际值
+- `--channel auto` 自动识别你电脑上装的 AI 工具（Claude Code / Codex / Qoder / Gemini 等）
+- 这个命令是前台运行的：窗口开着机器人在线，关掉窗口机器人下线
+
+## 第四步：拉进群聊
+
+在钉钉里打开目标群：
+
+**群设置 → 机器人 → 添加机器人 → 在企业机器人里搜"小助手"（你起的名字）→ 添加**
+
+完成。现在在群里 @小助手 提问试试，发文字、发报错截图都能答。
+
+## 进阶配置（可选）
+
+按需加在第三步的命令后面：
+
+| 参数 | 作用 |
+|------|------|
+| `--agent-workdir ./项目目录` | 让机器人在你的项目目录里跑，能读到和终端一样的本地文件（详见下方「机器人答得不如终端准？」） |
+| `--knowledge-dir ./docs` | 挂本地知识目录（.md/.txt），回答自动带上你的资料 |
+| `--agent-cmd "<命令>"` | 接入内置列表之外的 AI 工具（自研的、或还没内置支持的），详见下方「想用没在列表里的 AI 工具？」 |
+| `--allowed-users 工号1,工号2` | 用户白名单，名单外的人无法触发机器人 |
+| `--allowed-groups 群ID` | 群白名单 |
+| `--user-rate-limit 0` | 关闭限流（默认每人每分钟 20 条） |
+
+### 想用没在列表里的 AI 工具？（自研 / 未内置支持）
+
+`--channel auto` 只认内置的几款工具（Claude Code / Codex / Qoder / Gemini 等）。如果你用的是自研的、或还没内置支持的 AI（比如网易有道龙虾 LobsterAI），用 `--agent-cmd` 把它接进来——只要它能在命令行「一次性」跑（给一段问题、把答案打到标准输出），就能接：
+
+```bash
+dws dev connect \
+  --agent-cmd "你的AI命令 一次性问答参数" \
+  --robot-client-id dingxxxx --robot-client-secret yyyy
+```
+
+机器人收到群消息后，会执行 `你的AI命令 一次性问答参数 "用户的问题"`（问题作为最后一个参数追加），把它打印出来的内容当作回复发回群里。
+
+举例：假设龙虾的命令行叫 `lobster`、一次性问答用 `-p` 参数，就写 `--agent-cmd "lobster -p"`。命令里有空格就整体用引号括起来。
+
+## 常见问题
+
+**执行命令报 `zsh: parse error near '\n'`？**
+命令里残留了 `<...>` 尖括号占位符（旧版文档的写法），shell 会把尖括号当成重定向符。把占位符整体替换成实际值、不要保留尖括号，再执行。
+
+**群里 @机器人 没反应？**
+确认第三步的 `dev connect` 窗口还开着——关掉窗口机器人就下线了。
+
+**第二步提示"当前用户没有开发者身份"？**
+创建应用需要开放平台开发者权限。请企业管理员在钉钉开放平台（open-dev.dingtalk.com）的「权限管理」中把你的账号添加为开发者，然后重试第二步。
+
+**提示找不到 dws 命令？**
+macOS 重开一个终端窗口；Windows 重开一个 PowerShell 窗口（安装时改了 PATH，需要新窗口才生效）。
+
+**提示本地没有装 AI 工具？**
+机器人背后需要一个本地 AI CLI。推荐先装 [Claude Code](https://claude.com/claude-code) 或 Codex，装好后重新执行第三步。
+
+**机器人回复"调用失败"？**
+通常是本地 AI 工具未登录或额度用尽，单独运行一次该 AI 工具确认其本身可用。
+
+**机器人答得不如终端准？（同样的问题，终端对、机器人不对）**
+这通常不是模型问题，而是"机器人看到的上下文比终端少"：
+
+- **工作目录不同**：默认机器人在一个空白临时目录里跑（为了启动快、回复中立），它看不到你终端所在项目里的文件。要让它和终端读到同样的资料，在第三步加 `--agent-workdir ./你的项目目录`（指到你平时在终端里跑 AI 的那个目录）。
+- **知识没挂上**：如果靠的是本地文档/知识库，加 `--knowledge-dir ./docs`（或 `--knowledge-source wiki:<spaceId>`）把资料显式挂给机器人，别指望它自己去翻。
+- **模型不同**：机器人默认走一个偏快的小模型；如果你终端用的是更强的模型，给机器人也指定同一个：`--agent-model <模型名>`。
+- **回答"水位"上下浮动**：先确认没关 `--agent-memory`（默认开）。Codex 走 app-server thread 续聊；Qoder/Claude Code/CodeBuddy/WorkBuddy 走可恢复会话，其中 Qoder 的映射只保存在当前 DWS 进程内，重启后会重新开始；Gemini 仍是一次性调用。
+
+一句话：让机器人和终端"看到一样的东西、用一样的模型"，差距基本就抹平了。
+
+## 会话指令：`/new` 和 `/clear`
+
+机器人默认记住同一个会话的上下文（多轮对话）。想重置上下文，直接在聊天里发这两个斜杠指令——整条消息就是指令时才生效（普通问题不受影响），不消耗一次 AI 调用，秒回提示：
+
+| 指令 | 作用 |
+|------|------|
+| `/new`（或 `/start`、`/reset`） | **开启新会话**：之前的上下文不再带入，旧会话保留（agent 支持的话仍可回溯） |
+| `/clear` | **清空当前会话**：彻底从头开始 |
+
+两者按各渠道**真实能力**对齐：`/clear` 在 opencode 渠道会真正删除当前会话（调 opencode 的 `DELETE /session/:id`）；Codex / Qoder / Claude 系等驱动接口没有删除原语的渠道，`/clear` 退化为与 `/new` 相同的重置。
+
+**第三步执行完，在蚂蚁钉/开放平台搜不到审批工单？**
+这是正常的，不是出错。第三步 `dev connect`（把机器人接到本地 AI）只是用现成机器人的凭证起一条连接、本地转发，**不产生任何审批工单**。会产生审批工单的是第二步「建机器人」（`dev app robot submit`），由平台/管理员审批。所以第三步之后搜不到工单是预期内的。

go.mod

@@ -3,9 +3,12 @@ module github.com/DingTalk-Real-AI/dingtalk-workspace-cli
 go 1.25.8
 
 require (
+	github.com/RealAlexandreAI/json-repair v0.0.15
+	github.com/charmbracelet/huh v1.0.0
 	github.com/fatih/color v1.18.0
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.18
+	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/spf13/cobra v1.10.2
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/crypto v0.49.0
@@ -14,14 +17,12 @@ require (
 )
 
 require (
-	github.com/RealAlexandreAI/json-repair v0.0.15 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 // indirect
 	github.com/charmbracelet/bubbletea v1.3.6 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/huh v1.0.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.9.3 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
@@ -33,6 +34,7 @@ require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
+	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/itchyny/timefmt-go v0.1.7 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect

go.sum

@@ -1,9 +1,13 @@
+github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
+github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/RealAlexandreAI/json-repair v0.0.15 h1:AN8/yt8rcphwQrIs/FZeki+cKaIERUNr25zf1flirIs=
 github.com/RealAlexandreAI/json-repair v0.0.15/go.mod h1:GKJi5borR78O8c7HCVbgqjhoiVibZ6hJldxbc6dGrAI=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/aymanbagabas/go-udiff v0.3.1 h1:LV+qyBQ2pqe0u42ZsUEtPiCaUoqgA9gYRDs3vj1nolY=
+github.com/aymanbagabas/go-udiff v0.3.1/go.mod h1:G0fsKmG+P6ylD0r6N/KgQD/nWzgfnl8ZBcNLgcbrw8E=
 github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY=
 github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc=
 github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 h1:JFgG/xnwFfbezlUnFMJy0nusZvytYysV4SCS2cYbvws=
@@ -20,15 +24,27 @@ github.com/charmbracelet/x/ansi v0.9.3 h1:BXt5DHS/MKF+LjuK4huWrC6NCvHtexww7dMayh
 github.com/charmbracelet/x/ansi v0.9.3/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
 github.com/charmbracelet/x/cellbuf v0.0.13 h1:/KBBKHuVRbq1lYx5BzEHBAFBP8VcQzJejZ/IA3iR28k=
 github.com/charmbracelet/x/cellbuf v0.0.13/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/conpty v0.1.0 h1:4zc8KaIcbiL4mghEON8D72agYtSeIgq8FSThSPQIb+U=
+github.com/charmbracelet/x/conpty v0.1.0/go.mod h1:rMFsDJoDwVmiYM10aD4bH2XiRgwI7NYJtQgl5yskjEQ=
+github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86 h1:JSt3B+U9iqk37QUU2Rvb6DSBYRLtWqFqfxf8l5hOZUA=
+github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86/go.mod h1:2P0UgXMEa6TsToMSuFqKFQR+fZTO9CNGUNokkPatT/0=
+github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91 h1:payRxjMjKgx2PaCWLZ4p3ro9y97+TVLZNaRZgJwSVDQ=
+github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
 github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 h1:qko3AQ4gK1MTS/de7F5hPGx6/k1u0w4TeYmBFwzYVP4=
 github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0/go.mod h1:pBhA0ybfXv6hDjQUZ7hk1lVxBiUbupdw5R31yPUViVQ=
 github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
 github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
+github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
+github.com/charmbracelet/x/xpty v0.1.2 h1:Pqmu4TEJ8KeA9uSkISKMU3f+C1F6OGBn8ABuGlqCbtI=
+github.com/charmbracelet/x/xpty v0.1.2/go.mod h1:XK2Z0id5rtLWcpeNiMYBccNNBrP2IJnzHI0Lq13Xzq4=
 github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
 github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
 github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuhIGpJy4=
 github.com/clipperhouse/uax29/v2 v2.3.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
 github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -43,6 +59,8 @@ github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
 github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
+github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/itchyny/gojq v0.12.18 h1:gFGHyt/MLbG9n6dqnvlliiya2TaMMh6FFaR2b1H6Drc=
@@ -68,6 +86,8 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv81PdkYOiWbI8CNBi1boC8=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
@@ -88,6 +108,8 @@ github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cma
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
 golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

internal/app/auth_command.go

@@ -30,18 +30,39 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/charmbracelet/huh"
+	"github.com/charmbracelet/lipgloss"
 	"github.com/spf13/cobra"
 )
 
 type authLoginConfig struct {
-	Token  string
-	Force  bool
-	Device bool
+	Token     string
+	Force     bool
+	Device    bool
+	Recommend bool
+	Yes       bool
 }
 
-func buildAuthCommand() *cobra.Command {
+type authLoginGuideAction string
+
+const (
+	authLoginGuideDirectCLI         authLoginGuideAction = "direct_cli"
+	authLoginGuideConfigureAgentApp authLoginGuideAction = "configure_agent_app"
+	authLoginGuideManualCredentials authLoginGuideAction = "manual_credentials"
+)
+
+var (
+	authLoginBrandBlue = lipgloss.AdaptiveColor{Light: "#1677FF", Dark: "#69B1FF"}
+	authLoginInk       = lipgloss.AdaptiveColor{Light: "#1F2937", Dark: "#EAF2FF"}
+	authLoginMuted     = lipgloss.AdaptiveColor{Light: "#667085", Dark: "#8A96A8"}
+	authLoginLine      = lipgloss.AdaptiveColor{Light: "#D6E4FF", Dark: "#2F3B52"}
+	authLoginDanger    = lipgloss.AdaptiveColor{Light: "#D92D20", Dark: "#FF6B6B"}
+)
+
+func buildAuthCommand(patCaller edition.ToolCaller) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "auth",
 		Short:             "认证管理",
@@ -55,7 +76,7 @@ func buildAuthCommand() *cobra.Command {
 	}
 
 	if !edition.Get().HideAuthLogin {
-		cmd.AddCommand(newAuthLoginCommand())
+		cmd.AddCommand(newAuthLoginCommand(patCaller))
 	}
 	cmd.AddCommand(
 		newAuthLogoutCommand(),
@@ -68,7 +89,7 @@ func buildAuthCommand() *cobra.Command {
 	return cmd
 }
 
-func newAuthLoginCommand() *cobra.Command {
+func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "login",
 		Short: "登录钉钉（自动刷新 token，必要时扫码）",
@@ -88,7 +109,8 @@ func newAuthLoginCommand() *cobra.Command {
       否则 OAuth 回调会跳到本机不可达的 127.0.0.1 链接，授权完成后无法回写 token。
 
 示例:
-  dws auth login              # 本机扫码登录 (loopback 流)
+  dws auth login              # 本机登录后选择推荐/全部权限与授权业务域
+  dws auth login --recommend  # 无交互批量授权服务端推荐权限
   dws auth login --device     # SSH 远程 / 无头环境登录 (设备流)
   dws auth login --force      # 强制重新登录 (忽略缓存 token)
   dws auth login --token xxx  # 使用指定 token`,
@@ -100,6 +122,10 @@ func newAuthLoginCommand() *cobra.Command {
 			}
 			configDir := defaultConfigDir()
 			var tokenData *authpkg.TokenData
+			format, _ := cmd.Root().PersistentFlags().GetString("format")
+			postLoginTUIMode := !cfg.Yes && authLoginShouldUsePostLoginTUIMode(cmd, format, cfg.Recommend)
+			recommendAuthMode := cfg.Recommend || postLoginTUIMode
+			humanAuthMode := !cfg.Yes && authLoginShouldUseHumanAuthorizationMode(cmd, format, recommendAuthMode)
 
 			switch {
 			case strings.TrimSpace(cfg.Token) != "":
@@ -139,41 +165,93 @@ func newAuthLoginCommand() *cobra.Command {
 			clearCompatCache()
 
 			w := cmd.OutOrStdout()
+			runPostLoginAuthorization := func() error {
+				if !recommendAuthMode {
+					return nil
+				}
+				recommendScopeMode := pat.LoginRecommendScopeRecommended
+				var initialPlan *pat.LoginRecommendPlan
+				if postLoginTUIMode {
+					var planErr error
+					initialPlan, planErr = pat.PlanLoginRecommendAuthorization(cmd.Context(), patCaller)
+					if planErr != nil {
+						return planErr
+					}
+					if authLoginRecommendPlanSkipsInteractiveAuthorization(initialPlan) {
+						fmt.Fprintln(cmd.ErrOrStderr(), "推荐权限已全部授权或没有可授权项")
+						return nil
+					}
+					var err error
+					recommendScopeMode, err = loginRecommendScopeModeSelector()
+					if err != nil {
+						return err
+					}
+				}
+				opts := pat.LoginRecommendOptions{Confirmed: cfg.Yes, ScopeMode: recommendScopeMode, InitialPlan: initialPlan}
+				if postLoginTUIMode {
+					opts.ProductSelector = func(products []pat.LoginRecommendProduct) ([]string, error) {
+						return loginRecommendProductSelector(products)
+					}
+				}
+				retryFormat := format
+				if humanAuthMode {
+					retryFormat = "table"
+				}
+				run := func(ctx context.Context) error {
+					return pat.RunLoginRecommendAuthorizationWithOptions(ctx, patCaller, cmd.ErrOrStderr(), opts)
+				}
+				err := run(cmd.Context())
+				if patErr := apperrors.AsPatAuthCheckError(err); patErr != nil {
+					return runDirectPATAuthCheckWaitOnly(
+						cmd.Context(),
+						&GlobalFlags{Format: retryFormat},
+						patErr,
+						cmd.ErrOrStderr(),
+					)
+				}
+				return err
+			}
 
 			// Check if JSON output is requested
-			format, _ := cmd.Root().PersistentFlags().GetString("format")
-			if strings.EqualFold(strings.TrimSpace(format), "json") {
+			if strings.EqualFold(strings.TrimSpace(format), "json") && !humanAuthMode {
+				if err := runPostLoginAuthorization(); err != nil {
+					return err
+				}
 				return writeAuthLoginJSON(w, tokenData, cfg.Force)
 			}
 
 			// Default table output
+			if err := runPostLoginAuthorization(); err != nil {
+				return err
+			}
 			fmt.Fprintln(w)
 			if !cfg.Device && tokenData != nil && tokenData.IsAccessTokenValid() && !cfg.Force {
-				fmt.Fprintf(w, "[OK] Token 有效，无需重新登录\n")
+				fmt.Fprintln(w, authLoginStatusLine("Token 有效，无需重新登录"))
 			} else {
-				fmt.Fprintf(w, "[OK] 登录成功！\n")
+				fmt.Fprintln(w, authLoginStatusLine("登录成功！"))
 			}
 			if tokenData != nil {
 				if tokenData.CorpName != "" {
-					fmt.Fprintf(w, "%-16s%s\n", "企业:", tokenData.CorpName)
+					fmt.Fprintln(w, authLoginInfoLine("企业", tokenData.CorpName))
 				}
 				if tokenData.CorpID != "" {
-					fmt.Fprintf(w, "%-16s%s\n", "企业 ID:", tokenData.CorpID)
+					fmt.Fprintln(w, authLoginInfoLine("企业 ID", tokenData.CorpID))
 				}
 				if tokenData.UserName != "" {
-					fmt.Fprintf(w, "%-16s%s\n", "用户:", tokenData.UserName)
+					fmt.Fprintln(w, authLoginInfoLine("用户", tokenData.UserName))
 				}
 				if expiry := authLoginDisplayExpiry(tokenData); expiry != "" {
-					fmt.Fprintf(w, "%-16s%s\n", "有效期:", expiry)
+					fmt.Fprintln(w, authLoginInfoLine("有效期", expiry))
 				}
 			}
-			fmt.Fprintf(w, "Token 将自动刷新，无需重复登录\n")
+			fmt.Fprintln(w, authLoginMutedStyle().Render("Token 将自动刷新，无需重复登录"))
 			return nil
 		},
 	}
 	cmd.Flags().String("token", "", "Access token")
 	cmd.Flags().Bool("device", false, "Use device authorization flow")
 	cmd.Flags().Bool("force", false, "Force interactive login (ignore cached token)")
+	cmd.Flags().Bool("recommend", false, "登录成功后无交互批量授权服务端推荐权限")
 	// Hidden compatibility flags
 	cmd.Flags().String("redirect-url", "", "Loopback redirect URL")
 	cmd.Flags().String("scopes", "", "Space-separated DingTalk OAuth scopes")
@@ -191,6 +269,109 @@ func newAuthLoginCommand() *cobra.Command {
 	return cmd
 }
 
+var (
+	authLoginGuideActionSelector    = selectAuthLoginGuideAction
+	authLoginGuideActionApplier     = applyAuthLoginGuideAction
+	loginRecommendScopeModeSelector = selectLoginRecommendScopeMode
+	loginRecommendProductSelector   = selectLoginRecommendProducts
+	authLoginInteractiveTerminal    = isInteractiveTerminal
+)
+
+func selectAuthLoginGuideAction() (authLoginGuideAction, error) {
+	choice := authLoginGuideDirectCLI
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[authLoginGuideAction]().
+				Title("选择操作").
+				Options(
+					huh.NewOption("直接使用CLI", authLoginGuideDirectCLI),
+					huh.NewOption("一键配置智能体应用", authLoginGuideConfigureAgentApp),
+					huh.NewOption("手动输入应用凭证", authLoginGuideManualCredentials),
+				).
+				Value(&choice),
+		),
+	).WithTheme(authLoginHuhTheme())
+	if err := form.Run(); err != nil {
+		return "", fmt.Errorf("使用引导选择中止: %w", err)
+	}
+	return choice, nil
+}
+
+func applyAuthLoginGuideAction(cmd *cobra.Command, configDir string, action authLoginGuideAction) error {
+	switch action {
+	case authLoginGuideDirectCLI:
+		return nil
+	case authLoginGuideConfigureAgentApp:
+		fmt.Fprintln(cmd.ErrOrStderr(), "一键配置智能体应用暂未开放，已继续使用 CLI 登录")
+		return nil
+	case authLoginGuideManualCredentials:
+		clientID, clientSecret, err := promptAuthLoginManualCredentials()
+		if err != nil {
+			return err
+		}
+		authpkg.SetClientID(clientID)
+		authpkg.SetClientSecret(clientSecret)
+		if err := authpkg.SaveAppConfig(configDir, &authpkg.AppConfig{
+			ClientID:     clientID,
+			ClientSecret: authpkg.PlainSecret(clientSecret),
+		}); err != nil {
+			return apperrors.NewInternal(fmt.Sprintf("failed to persist app credentials: %v", err))
+		}
+		return nil
+	default:
+		return fmt.Errorf("未知操作: %s", action)
+	}
+}
+
+func promptAuthLoginManualCredentials() (string, string, error) {
+	var clientID, clientSecret string
+	nonEmpty := func(label string) func(string) error {
+		return func(value string) error {
+			if strings.TrimSpace(value) == "" {
+				return fmt.Errorf("%s 不能为空", label)
+			}
+			return nil
+		}
+	}
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewInput().
+				Title("输入 AppKey").
+				Value(&clientID).
+				Validate(nonEmpty("AppKey")),
+			huh.NewInput().
+				Title("输入 AppSecret").
+				EchoMode(huh.EchoModePassword).
+				Value(&clientSecret).
+				Validate(nonEmpty("AppSecret")),
+		),
+	).WithTheme(authLoginHuhTheme())
+	if err := form.Run(); err != nil {
+		return "", "", fmt.Errorf("应用凭证输入中止: %w", err)
+	}
+	return strings.TrimSpace(clientID), strings.TrimSpace(clientSecret), nil
+}
+
+func selectLoginRecommendScopeMode() (pat.LoginRecommendScopeMode, error) {
+	choice := pat.LoginRecommendScopeRecommended
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[pat.LoginRecommendScopeMode]().
+				Title("选择授权范围").
+				Description("空格选择 回车确认").
+				Options(
+					huh.NewOption("推荐授权", pat.LoginRecommendScopeRecommended),
+					huh.NewOption("全部授权", pat.LoginRecommendScopeAll),
+				).
+				Value(&choice),
+		),
+	).WithTheme(authLoginHuhTheme())
+	if err := form.Run(); err != nil {
+		return "", fmt.Errorf("授权范围选择中止: %w", err)
+	}
+	return choice, nil
+}
+
 func newAuthLogoutCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:               "logout",
@@ -230,7 +411,7 @@ func newAuthLogoutCommand() *cobra.Command {
 			w := cmd.OutOrStdout()
 			fmt.Fprintln(w, "[OK] 已清除所有认证信息")
 			if !edition.Get().IsEmbedded {
-				fmt.Fprintln(w, "请运行 dws auth login 重新登录")
+				fmt.Fprintln(w, "请运行 dws auth login --recommend 重新登录")
 			}
 			return nil
 		},
@@ -298,7 +479,7 @@ func newAuthStatusCommand() *cobra.Command {
 			} else {
 				fmt.Fprintf(w, "%-16s%s\n", "状态:", "未登录")
 				if !edition.Get().IsEmbedded {
-					fmt.Fprintln(w, "运行 dws auth login 进行登录")
+					fmt.Fprintln(w, "运行 dws auth login --recommend 进行登录")
 				}
 			}
 			return nil
@@ -338,7 +519,7 @@ func newAuthExportCommand() *cobra.Command {
 				))
 			}
 			if !authpkg.PortableAuthSourceReady() {
-				return apperrors.NewValidation("尚未登录，请先运行 dws auth login")
+				return apperrors.NewValidation("尚未登录，请先运行 dws auth login --recommend")
 			}
 
 			var bundle bytes.Buffer
@@ -512,7 +693,7 @@ func newAuthResetCommand() *cobra.Command {
 			w := cmd.OutOrStdout()
 			fmt.Fprintln(w, "[OK] 认证信息已重置")
 			if !edition.Get().IsEmbedded {
-				fmt.Fprintln(w, "请运行 dws auth login 重新登录")
+				fmt.Fprintln(w, "请运行 dws auth login --recommend 重新登录")
 			}
 			return nil
 		},
@@ -553,6 +734,205 @@ func authLoginDisplayExpiry(data *authpkg.TokenData) string {
 	return ""
 }
 
+func selectLoginRecommendProducts(products []pat.LoginRecommendProduct) ([]string, error) {
+	if len(products) == 0 {
+		return nil, nil
+	}
+	selected := make([]string, 0, len(products))
+	options := make([]huh.Option[string], 0, len(products))
+	for _, product := range products {
+		code := strings.TrimSpace(product.ProductCode)
+		if code == "" {
+			continue
+		}
+		selected = append(selected, code)
+		options = append(options, huh.NewOption(loginRecommendProductLabel(product), code).Selected(true))
+	}
+	if len(options) == 0 {
+		return nil, nil
+	}
+	height := len(options)
+	if height > 15 {
+		height = 15
+	}
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewMultiSelect[string]().
+				Title("选择要授权的业务域").
+				Description("空格选择 回车确认").
+				Options(options...).
+				Height(height).
+				Value(&selected).
+				Validate(func(values []string) error {
+					if len(values) == 0 {
+						return fmt.Errorf("至少选择一个授权业务域")
+					}
+					return nil
+				}),
+		),
+	).WithTheme(authLoginHuhTheme())
+	if err := form.Run(); err != nil {
+		return nil, fmt.Errorf("授权业务域选择中止: %w", err)
+	}
+	return selected, nil
+}
+
+func authLoginHuhTheme() *huh.Theme {
+	t := huh.ThemeBase()
+
+	t.Form.Base = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.FieldSeparator = lipgloss.NewStyle().SetString("\n")
+
+	t.Focused.Base = t.Focused.Base.BorderForeground(authLoginBrandBlue)
+	t.Focused.Card = t.Focused.Base
+	t.Focused.Title = lipgloss.NewStyle().Foreground(authLoginBrandBlue).Bold(true)
+	t.Focused.NoteTitle = t.Focused.Title.MarginBottom(1)
+	t.Focused.Description = authLoginMutedStyle()
+	t.Focused.ErrorIndicator = lipgloss.NewStyle().SetString(" *").Foreground(authLoginDanger)
+	t.Focused.ErrorMessage = lipgloss.NewStyle().SetString(" *").Foreground(authLoginDanger)
+	t.Focused.SelectSelector = lipgloss.NewStyle().SetString("› ").Foreground(authLoginBrandBlue).Bold(true)
+	t.Focused.MultiSelectSelector = t.Focused.SelectSelector
+	t.Focused.Option = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.Focused.SelectedOption = lipgloss.NewStyle().Foreground(authLoginBrandBlue).Bold(true)
+	t.Focused.SelectedPrefix = lipgloss.NewStyle().SetString("● ").Foreground(authLoginBrandBlue)
+	t.Focused.UnselectedOption = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.Focused.UnselectedPrefix = lipgloss.NewStyle().SetString("○ ").Foreground(authLoginMuted)
+	t.Focused.NextIndicator = lipgloss.NewStyle().SetString("→").Foreground(authLoginBrandBlue)
+	t.Focused.PrevIndicator = lipgloss.NewStyle().SetString("←").Foreground(authLoginMuted)
+	t.Focused.FocusedButton = lipgloss.NewStyle().
+		Foreground(lipgloss.AdaptiveColor{Light: "#FFFFFF", Dark: "#0B1220"}).
+		Background(authLoginBrandBlue).
+		Padding(0, 2).
+		Bold(true)
+	t.Focused.BlurredButton = lipgloss.NewStyle().
+		Foreground(authLoginInk).
+		Background(authLoginLine).
+		Padding(0, 2)
+	t.Focused.Next = t.Focused.FocusedButton
+	t.Focused.TextInput.Cursor = lipgloss.NewStyle().Foreground(authLoginBrandBlue)
+	t.Focused.TextInput.CursorText = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.Focused.TextInput.Placeholder = authLoginMutedStyle()
+	t.Focused.TextInput.Prompt = lipgloss.NewStyle().Foreground(authLoginBrandBlue)
+	t.Focused.TextInput.Text = lipgloss.NewStyle().Foreground(authLoginInk)
+
+	t.Blurred = t.Focused
+	t.Blurred.Base = t.Focused.Base.BorderStyle(lipgloss.HiddenBorder()).BorderForeground(authLoginLine)
+	t.Blurred.Card = t.Blurred.Base
+	t.Blurred.Title = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.Blurred.NoteTitle = t.Blurred.Title.MarginBottom(1)
+	t.Blurred.Description = authLoginMutedStyle()
+	t.Blurred.SelectSelector = lipgloss.NewStyle().SetString("  ")
+	t.Blurred.MultiSelectSelector = t.Blurred.SelectSelector
+	t.Blurred.SelectedOption = lipgloss.NewStyle().Foreground(authLoginInk)
+	t.Blurred.SelectedPrefix = lipgloss.NewStyle().SetString("● ").Foreground(authLoginBrandBlue)
+	t.Blurred.UnselectedOption = lipgloss.NewStyle().Foreground(authLoginMuted)
+	t.Blurred.UnselectedPrefix = lipgloss.NewStyle().SetString("○ ").Foreground(authLoginMuted)
+	t.Blurred.NextIndicator = lipgloss.NewStyle()
+	t.Blurred.PrevIndicator = lipgloss.NewStyle()
+	t.Blurred.TextInput.Prompt = lipgloss.NewStyle().Foreground(authLoginMuted)
+	t.Blurred.TextInput.Text = lipgloss.NewStyle().Foreground(authLoginInk)
+
+	t.Group.Title = t.Focused.Title
+	t.Group.Description = t.Focused.Description
+
+	t.Help.ShortKey = authLoginMutedStyle()
+	t.Help.ShortDesc = authLoginMutedStyle()
+	t.Help.ShortSeparator = authLoginMutedStyle()
+	t.Help.FullKey = authLoginMutedStyle()
+	t.Help.FullDesc = authLoginMutedStyle()
+	t.Help.FullSeparator = authLoginMutedStyle()
+	t.Help.Ellipsis = authLoginMutedStyle()
+
+	return t
+}
+
+func authLoginStatusLine(message string) string {
+	return fmt.Sprintf("%s %s",
+		lipgloss.NewStyle().Foreground(authLoginBrandBlue).Bold(true).Render("[OK]"),
+		lipgloss.NewStyle().Foreground(authLoginInk).Bold(true).Render(message),
+	)
+}
+
+func authLoginInfoLine(key, value string) string {
+	label := authLoginMutedStyle().Width(14).Render(key + ":")
+	return fmt.Sprintf("%s %s", label, value)
+}
+
+func authLoginMutedStyle() lipgloss.Style {
+	return lipgloss.NewStyle().Foreground(authLoginMuted)
+}
+
+func authLoginShouldShowPostLoginTUI(cmd *cobra.Command, format string, recommend bool) bool {
+	return authLoginShouldUsePostLoginTUIModeForTerminal(cmd, format, recommend, authLoginInteractiveTerminal())
+}
+
+func authLoginShouldShowPostLoginTUIForTerminal(cmd *cobra.Command, format string, recommend bool, interactive bool) bool {
+	return authLoginShouldUsePostLoginTUIModeForTerminal(cmd, format, recommend, interactive)
+}
+
+func authLoginShouldUsePostLoginTUIMode(cmd *cobra.Command, format string, recommend bool) bool {
+	return authLoginShouldUsePostLoginTUIModeForTerminal(cmd, format, recommend, authLoginInteractiveTerminal())
+}
+
+func authLoginShouldUsePostLoginTUIModeForTerminal(cmd *cobra.Command, format string, recommend bool, interactive bool) bool {
+	if recommend || !interactive {
+		return false
+	}
+	return authLoginAllowsInteractiveDefault(cmd, format)
+}
+
+func authLoginShouldUseHumanAuthorizationMode(cmd *cobra.Command, format string, hasAuthorizationFlow bool) bool {
+	return authLoginShouldUseHumanAuthorizationModeForTerminal(cmd, format, hasAuthorizationFlow, authLoginInteractiveTerminal())
+}
+
+func authLoginShouldUseHumanAuthorizationModeForTerminal(cmd *cobra.Command, format string, hasAuthorizationFlow bool, interactive bool) bool {
+	if !hasAuthorizationFlow || !interactive {
+		return false
+	}
+	return authLoginAllowsInteractiveDefault(cmd, format)
+}
+
+func authLoginRecommendPlanSkipsInteractiveAuthorization(plan *pat.LoginRecommendPlan) bool {
+	if plan == nil {
+		return false
+	}
+	return plan.AllGranted || len(plan.Scopes) == 0
+}
+
+func authLoginAllowsInteractiveDefault(cmd *cobra.Command, format string) bool {
+	if cmd == nil || cmd.Root() == nil {
+		return false
+	}
+	if !strings.EqualFold(strings.TrimSpace(format), "json") {
+		return true
+	}
+	flags := cmd.Root().PersistentFlags()
+	return !flags.Changed("format")
+}
+
+func loginRecommendProductLabel(product pat.LoginRecommendProduct) string {
+	name := strings.TrimSpace(product.ProductName)
+	if name == "" || name == product.ProductCode {
+		name = product.ProductCode
+	}
+	summary := strings.TrimSpace(product.Summary)
+	if summary != "" {
+		summary = " - " + clipRunes(summary, 42)
+	}
+	return fmt.Sprintf("%-10s %s%s", product.ProductCode, name, summary)
+}
+
+func clipRunes(value string, limit int) string {
+	if limit <= 0 {
+		return ""
+	}
+	runes := []rune(value)
+	if len(runes) <= limit {
+		return value
+	}
+	return string(runes[:limit]) + "..."
+}
+
 func clearCompatCache() {
 	store := cacheStoreFromEnv()
 	if store != nil {
@@ -573,10 +953,20 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
 	if err != nil {
 		return authLoginConfig{}, apperrors.NewInternal("failed to read --force")
 	}
+	recommend, err := cmd.Flags().GetBool("recommend")
+	if err != nil {
+		return authLoginConfig{}, apperrors.NewInternal("failed to read --recommend")
+	}
+	yes := false
+	if cmd.Root() != nil {
+		yes, _ = cmd.Root().PersistentFlags().GetBool("yes")
+	}
 	return authLoginConfig{
-		Token:  strings.TrimSpace(token),
-		Force:  force,
-		Device: device,
+		Token:     strings.TrimSpace(token),
+		Force:     force,
+		Device:    device,
+		Recommend: recommend,
+		Yes:       yes,
 	}, nil
 }
 

internal/app/auth_command_test.go

@@ -15,6 +15,7 @@ package app
 
 import (
 	"bytes"
+	"context"
 	"errors"
 	"net/http"
 	"os"
@@ -26,6 +27,9 @@ import (
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
 )
 
 func TestAuthExportImportBase64RoundTrip(t *testing.T) {
@@ -180,8 +184,461 @@ func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
 	}
 }
 
+func TestAuthLoginPostLoginTUIModeRespectsRecommendAndFormat(t *testing.T) {
+	newRoot := func(t *testing.T) *cobra.Command {
+		t.Helper()
+		root := &cobra.Command{Use: "dws"}
+		root.PersistentFlags().String("format", "json", "")
+		return root
+	}
+
+	t.Run("recommend skips tui but keeps human auth for interactive login", func(t *testing.T) {
+		root := newRoot(t)
+		if authLoginShouldShowPostLoginTUIForTerminal(root, "json", true, true) {
+			t.Fatal("--recommend must not show the post-login product TUI")
+		}
+		if !authLoginShouldUseHumanAuthorizationModeForTerminal(root, "json", true, true) {
+			t.Fatal("default interactive --recommend should still use human authorization flow")
+		}
+	})
+
+	t.Run("without recommend shows two-step authorization tui", func(t *testing.T) {
+		root := newRoot(t)
+		if !authLoginShouldShowPostLoginTUIForTerminal(root, "json", false, true) {
+			t.Fatal("default interactive login should show post-login authorization TUI")
+		}
+		if !authLoginShouldUseHumanAuthorizationModeForTerminal(root, "json", true, true) {
+			t.Fatal("default interactive post-login authorization should use human authorization flow")
+		}
+	})
+
+	t.Run("explicit json keeps machine mode", func(t *testing.T) {
+		root := newRoot(t)
+		if err := root.PersistentFlags().Set("format", "json"); err != nil {
+			t.Fatalf("set format: %v", err)
+		}
+		if authLoginShouldShowPostLoginTUIForTerminal(root, "json", false, true) {
+			t.Fatal("explicit --format json must not show post-login TUI")
+		}
+		if authLoginShouldUseHumanAuthorizationModeForTerminal(root, "json", true, true) {
+			t.Fatal("explicit --format json must keep machine-readable authorization flow")
+		}
+	})
+
+	t.Run("table without recommend shows authorization tui", func(t *testing.T) {
+		root := newRoot(t)
+		if err := root.PersistentFlags().Set("format", "table"); err != nil {
+			t.Fatalf("set format: %v", err)
+		}
+		if !authLoginShouldShowPostLoginTUIForTerminal(root, "table", false, true) {
+			t.Fatal("table format should show post-login TUI without --recommend")
+		}
+		if !authLoginShouldUseHumanAuthorizationModeForTerminal(root, "table", true, true) {
+			t.Fatal("table format should use human authorization flow in an interactive terminal")
+		}
+	})
+
+	t.Run("non interactive skips selector", func(t *testing.T) {
+		root := newRoot(t)
+		if authLoginShouldShowPostLoginTUIForTerminal(root, "json", false, false) {
+			t.Fatal("non-interactive login should skip post-login TUI")
+		}
+		if authLoginShouldUseHumanAuthorizationModeForTerminal(root, "json", true, false) {
+			t.Fatal("non-interactive login should keep machine-readable authorization flow")
+		}
+	})
+
+	t.Run("without authorization flow keeps normal login output contract", func(t *testing.T) {
+		root := newRoot(t)
+		if authLoginShouldUseHumanAuthorizationModeForTerminal(root, "json", false, true) {
+			t.Fatal("login without a post-login authorization flow should not switch default json to human mode")
+		}
+	})
+}
+
+func TestLoginRecommendProductLabelMatchesTUITarget(t *testing.T) {
+	label := loginRecommendProductLabel(pat.LoginRecommendProduct{
+		ProductCode: "approval",
+		ProductName: "审批",
+		Summary:     "审批实例，审批模板，审批任务管理",
+		ScopeCount:  12,
+	})
+	if label != "approval   审批 - 审批实例，审批模板，审批任务管理" {
+		t.Fatalf("label = %q", label)
+	}
+}
+
+func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().Bool("yes", false, "")
+	login := &cobra.Command{Use: "login"}
+	login.Flags().String("token", "", "")
+	login.Flags().Bool("device", false, "")
+	login.Flags().Bool("force", false, "")
+	login.Flags().Bool("recommend", false, "")
+	root.AddCommand(login)
+
+	if err := root.PersistentFlags().Set("yes", "true"); err != nil {
+		t.Fatalf("set yes: %v", err)
+	}
+	if err := login.Flags().Set("recommend", "true"); err != nil {
+		t.Fatalf("set recommend: %v", err)
+	}
+
+	cfg, err := resolveAuthLoginConfig(login)
+	if err != nil {
+		t.Fatalf("resolveAuthLoginConfig error = %v", err)
+	}
+	if !cfg.Recommend {
+		t.Fatal("Recommend = false, want true")
+	}
+	if !cfg.Yes {
+		t.Fatal("Yes = false, want true")
+	}
+}
+
+func TestAuthLoginRecommendSkipsPostLoginTUI(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	oldGuideSelector := authLoginGuideActionSelector
+	oldGuideApplier := authLoginGuideActionApplier
+	oldScopeSelector := loginRecommendScopeModeSelector
+	oldProductSelector := loginRecommendProductSelector
+	oldInteractiveTerminal := authLoginInteractiveTerminal
+	t.Cleanup(func() {
+		authLoginGuideActionSelector = oldGuideSelector
+		authLoginGuideActionApplier = oldGuideApplier
+		loginRecommendScopeModeSelector = oldScopeSelector
+		loginRecommendProductSelector = oldProductSelector
+		authLoginInteractiveTerminal = oldInteractiveTerminal
+	})
+	authLoginInteractiveTerminal = func() bool { return true }
+	authLoginGuideActionSelector = func() (authLoginGuideAction, error) {
+		t.Fatal("--recommend must not call the post-login guide selector")
+		return "", nil
+	}
+	authLoginGuideActionApplier = func(*cobra.Command, string, authLoginGuideAction) error {
+		t.Fatal("--recommend must not apply a post-login guide action")
+		return nil
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) {
+		t.Fatal("--recommend must not call the scope-mode TUI")
+		return "", nil
+	}
+	loginRecommendProductSelector = func([]pat.LoginRecommendProduct) ([]string, error) {
+		t.Fatal("--recommend must not call the product-domain TUI")
+		return nil, nil
+	}
+
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"data":{"items":[{"scope":"calendar.event:read","productCode":"calendar","productName":"日历"}],"selectedScopes":["calendar.event:read"]}}`,
+		`{"success":true,"data":{"grantedScopes":["calendar.event:read"]}}`,
+	}}
+	cmd := newAuthLoginCommand(fake)
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--token", "login-token", "--recommend"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth login --recommend error = %v\noutput:\n%s", err, out.String())
+	}
+	if len(fake.tools) != 2 {
+		t.Fatalf("CallTool count = %d, want plan + grant", len(fake.tools))
+	}
+	if fake.tools[0] != "pat.batch_plan" || fake.tools[1] != "pat.batch_grant" {
+		t.Fatalf("tool sequence = %v, want plan, grant", fake.tools)
+	}
+	if got := fake.args[0]["recommend"]; got != true {
+		t.Fatalf("--recommend plan recommend = %#v, want true", got)
+	}
+}
+
+func TestAuthLoginDefaultTUIModeSkipsSelectorWhenAllGranted(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	oldGuideSelector := authLoginGuideActionSelector
+	oldGuideApplier := authLoginGuideActionApplier
+	oldScopeSelector := loginRecommendScopeModeSelector
+	oldProductSelector := loginRecommendProductSelector
+	oldInteractiveTerminal := authLoginInteractiveTerminal
+	t.Cleanup(func() {
+		authLoginGuideActionSelector = oldGuideSelector
+		authLoginGuideActionApplier = oldGuideApplier
+		loginRecommendScopeModeSelector = oldScopeSelector
+		loginRecommendProductSelector = oldProductSelector
+		authLoginInteractiveTerminal = oldInteractiveTerminal
+	})
+	authLoginInteractiveTerminal = func() bool { return true }
+	authLoginGuideActionSelector = func() (authLoginGuideAction, error) {
+		t.Fatal("default auth login must not call the operation guide selector")
+		return "", nil
+	}
+	authLoginGuideActionApplier = func(*cobra.Command, string, authLoginGuideAction) error {
+		t.Fatal("default auth login must not apply a post-login guide action")
+		return nil
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) {
+		t.Fatal("all-granted recommend plan must not call the scope-mode TUI")
+		return "", nil
+	}
+	loginRecommendProductSelector = func([]pat.LoginRecommendProduct) ([]string, error) {
+		t.Fatal("all-granted recommend plan must not call the product-domain TUI")
+		return nil, nil
+	}
+
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"data":{"allGranted":true,"selectedScopes":[]}}`,
+	}}
+	cmd := newAuthLoginCommand(fake)
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--token", "login-token"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth login error = %v\noutput:\n%s", err, out.String())
+	}
+	if len(fake.tools) != 1 {
+		t.Fatalf("CallTool count = %d, want only preflight plan", len(fake.tools))
+	}
+	if fake.tools[0] != "pat.batch_plan" {
+		t.Fatalf("tool sequence = %v, want only plan", fake.tools)
+	}
+	if !strings.Contains(out.String(), "推荐权限已全部授权或没有可授权项") {
+		t.Fatalf("output = %q, want all-granted message", out.String())
+	}
+}
+
+func TestAuthLoginDefaultTUIModeRecommendedAlreadyGrantedSkipsTUIAndAuthorizationPage(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	oldGuideSelector := authLoginGuideActionSelector
+	oldGuideApplier := authLoginGuideActionApplier
+	oldScopeSelector := loginRecommendScopeModeSelector
+	oldProductSelector := loginRecommendProductSelector
+	oldInteractiveTerminal := authLoginInteractiveTerminal
+	t.Cleanup(func() {
+		authLoginGuideActionSelector = oldGuideSelector
+		authLoginGuideActionApplier = oldGuideApplier
+		loginRecommendScopeModeSelector = oldScopeSelector
+		loginRecommendProductSelector = oldProductSelector
+		authLoginInteractiveTerminal = oldInteractiveTerminal
+	})
+	authLoginInteractiveTerminal = func() bool { return true }
+	authLoginGuideActionSelector = func() (authLoginGuideAction, error) {
+		t.Fatal("default auth login must not call the operation guide selector")
+		return "", nil
+	}
+	authLoginGuideActionApplier = func(*cobra.Command, string, authLoginGuideAction) error {
+		t.Fatal("default auth login must not apply a post-login guide action")
+		return nil
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) {
+		t.Fatal("already-granted recommended auth must not call the scope-mode TUI")
+		return "", nil
+	}
+	loginRecommendProductSelector = func([]pat.LoginRecommendProduct) ([]string, error) {
+		t.Fatal("already-granted recommended auth must not call product-domain TUI")
+		return nil, nil
+	}
+
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"data":{"allGranted":false,"items":[{"scope":"calendar.event:read","productCode":"calendar","productName":"日历"}],"selectedScopes":[]}}`,
+	}}
+	cmd := newAuthLoginCommand(fake)
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--token", "login-token"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth login error = %v\noutput:\n%s", err, out.String())
+	}
+	if len(fake.tools) != 1 {
+		t.Fatalf("CallTool count = %d, want only preflight recommend plan", len(fake.tools))
+	}
+	if fake.tools[0] != "pat.batch_plan" {
+		t.Fatalf("tool sequence = %v, want only plan", fake.tools)
+	}
+	if !strings.Contains(out.String(), "推荐权限已全部授权或没有可授权项") {
+		t.Fatalf("output = %q, want already-granted message", out.String())
+	}
+}
+
+func TestAuthLoginDefaultTUIRunsAfterLoginTokenSaved(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+
+	oldGuideSelector := authLoginGuideActionSelector
+	oldGuideApplier := authLoginGuideActionApplier
+	oldScopeSelector := loginRecommendScopeModeSelector
+	oldProductSelector := loginRecommendProductSelector
+	oldInteractiveTerminal := authLoginInteractiveTerminal
+	t.Cleanup(func() {
+		authLoginGuideActionSelector = oldGuideSelector
+		authLoginGuideActionApplier = oldGuideApplier
+		loginRecommendScopeModeSelector = oldScopeSelector
+		loginRecommendProductSelector = oldProductSelector
+		authLoginInteractiveTerminal = oldInteractiveTerminal
+	})
+	authLoginInteractiveTerminal = func() bool { return true }
+
+	var sawTokenBeforeScopeTUI bool
+	var sawTokenBeforeProductTUI bool
+	var sawTokenBeforePlan bool
+	authLoginGuideActionSelector = func() (authLoginGuideAction, error) {
+		t.Fatal("default login must not call the operation guide selector")
+		return "", nil
+	}
+	authLoginGuideActionApplier = func(*cobra.Command, string, authLoginGuideAction) error {
+		t.Fatal("default login must not apply a post-login guide action")
+		return nil
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) {
+		token, err := authpkg.LoadTokenData(configDir)
+		if err != nil {
+			t.Fatalf("LoadTokenData before scope TUI error = %v", err)
+		}
+		if token.AccessToken != "login-token" {
+			t.Fatalf("AccessToken before scope TUI = %q, want login-token", token.AccessToken)
+		}
+		sawTokenBeforeScopeTUI = true
+		return pat.LoginRecommendScopeAll, nil
+	}
+	loginRecommendProductSelector = func(products []pat.LoginRecommendProduct) ([]string, error) {
+		token, err := authpkg.LoadTokenData(configDir)
+		if err != nil {
+			t.Fatalf("LoadTokenData before product TUI error = %v", err)
+		}
+		if token.AccessToken != "login-token" {
+			t.Fatalf("AccessToken before product TUI = %q, want login-token", token.AccessToken)
+		}
+		sawTokenBeforeProductTUI = true
+		if len(products) != 1 || products[0].ProductCode != "calendar" {
+			t.Fatalf("selector products = %+v, want calendar", products)
+		}
+		return []string{"calendar"}, nil
+	}
+
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"data":{"items":[{"scope":"calendar.event:read","productCode":"calendar","productName":"日历"}],"selectedScopes":["calendar.event:read"]}}`,
+		`{"success":true,"data":{"items":[{"scope":"calendar.event:read","productCode":"calendar","productName":"日历"}],"selectedScopes":["calendar.event:read"]}}`,
+		`{"success":true,"data":{"grantedScopes":["calendar.event:read"]}}`,
+	}, beforeCall: func(toolName string) {
+		token, err := authpkg.LoadTokenData(configDir)
+		if err != nil {
+			t.Fatalf("LoadTokenData before %s error = %v", toolName, err)
+		}
+		if token.AccessToken != "login-token" {
+			t.Fatalf("AccessToken before %s = %q, want login-token", toolName, token.AccessToken)
+		}
+		sawTokenBeforePlan = true
+	}}
+	cmd := newAuthLoginCommand(fake)
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--token", "login-token"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth login error = %v\noutput:\n%s", err, out.String())
+	}
+	if !sawTokenBeforeScopeTUI {
+		t.Fatal("scope-mode TUI was not called after token save")
+	}
+	if !sawTokenBeforeProductTUI {
+		t.Fatal("product-domain TUI was not called after token save")
+	}
+	if !sawTokenBeforePlan {
+		t.Fatal("authorization plan was not called after token save")
+	}
+	if len(fake.tools) != 3 {
+		t.Fatalf("CallTool count = %d, want discovery plan + selected plan + grant", len(fake.tools))
+	}
+	if fake.tools[0] != "pat.batch_plan" || fake.tools[1] != "pat.batch_plan" || fake.tools[2] != "pat.batch_grant" {
+		t.Fatalf("tool sequence = %v, want plan, plan, grant", fake.tools)
+	}
+	if got := fake.args[0]["recommend"]; got != true {
+		t.Fatalf("discovery plan recommend = %#v, want true", got)
+	}
+	if got := fake.args[1]["recommend"]; got != false {
+		t.Fatalf("selected all-scope plan recommend = %#v, want false", got)
+	}
+	if got := fake.args[1]["productCodes"]; !stringSliceArgEqual(got, []string{"calendar"}) {
+		t.Fatalf("selected all-scope plan productCodes = %#v, want calendar", got)
+	}
+}
+
 type roundTripFunc func(*http.Request) (*http.Response, error)
 
 func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
 	return f(req)
 }
+
+type authLoginRecommendSequenceCaller struct {
+	responses  []string
+	tools      []string
+	args       []map[string]any
+	beforeCall func(toolName string)
+}
+
+func (f *authLoginRecommendSequenceCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	if f.beforeCall != nil {
+		f.beforeCall(toolName)
+	}
+	f.tools = append(f.tools, toolName)
+	copiedArgs := make(map[string]any, len(args))
+	for key, value := range args {
+		copiedArgs[key] = value
+	}
+	f.args = append(f.args, copiedArgs)
+	response := `{"success":true,"data":{}}`
+	if len(f.responses) > 0 {
+		response = f.responses[0]
+		f.responses = f.responses[1:]
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: response}}}, nil
+}
+
+func (f *authLoginRecommendSequenceCaller) Format() string { return "table" }
+
+func (f *authLoginRecommendSequenceCaller) DryRun() bool { return false }
+
+func stringSliceArgEqual(got any, want []string) bool {
+	if got == nil {
+		return len(want) == 0
+	}
+	switch values := got.(type) {
+	case []string:
+		if len(values) != len(want) {
+			return false
+		}
+		for i := range values {
+			if values[i] != want[i] {
+				return false
+			}
+		}
+		return true
+	case []any:
+		if len(values) != len(want) {
+			return false
+		}
+		for i := range values {
+			if values[i] != want[i] {
+				return false
+			}
+		}
+		return true
+	default:
+		return false
+	}
+}

internal/app/catalog_command.go

@@ -0,0 +1,203 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/ir"
+	"github.com/spf13/cobra"
+)
+
+// toolMappingParam 描述一个 MCP 参数到 CLI flag + 中文友好名的映射。
+type toolMappingParam struct {
+	Flag  string `json:"flag"`
+	Label string `json:"label"`
+	Type  string `json:"type,omitempty"`
+}
+
+// toolMappingEntry 是单个 MCP 工具的映射条目。key 用 RPCName，对齐 SLS 日志的 tool 字段。
+type toolMappingEntry struct {
+	Product     string                      `json:"product"`
+	CLICommand  string                      `json:"cliCommand"`
+	DisplayName string                      `json:"displayName"`
+	Params      map[string]toolMappingParam `json:"params,omitempty"`
+}
+
+// toolMapping 是给开放平台日志页渲染用的全量映射契约。
+type toolMapping struct {
+	Version string                      `json:"version"`
+	Count   int                         `json:"count"`
+	Tools   map[string]toolMappingEntry `json:"tools"`
+}
+
+// newCatalogCommand 提供 `dws catalog export`：把已发现的工具目录投影成
+// tool→指令 映射 JSON，供开放平台 MCP/DWS 日志页把 tool/args 渲染成中文友好名。
+// 复用 root 注入的带 auth 的 loader（缓存优先；建议先 `dws cache refresh`）。
+func newCatalogCommand(loader cli.CatalogLoader) *cobra.Command {
+	catalogCmd := &cobra.Command{
+		Use:    "catalog",
+		Short:  "导出已发现的工具目录（内部用）",
+		Hidden: true,
+	}
+
+	var out string
+	var version string
+	exportCmd := &cobra.Command{
+		Use:   "export",
+		Short: "导出 tool→指令 映射 JSON（供开放平台日志页渲染）",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			catalog, err := loader.Load(cmd.Context())
+			if err != nil {
+				return err
+			}
+			mapping := projectToolMapping(catalog, version)
+			data, err := json.MarshalIndent(mapping, "", "  ")
+			if err != nil {
+				return err
+			}
+			data = append(data, '\n')
+			if strings.TrimSpace(out) == "" {
+				_, werr := os.Stdout.Write(data)
+				return werr
+			}
+			return os.WriteFile(out, data, 0o644)
+		},
+	}
+	exportCmd.Flags().StringVar(&out, "out", "", "输出文件路径（默认 stdout）")
+	exportCmd.Flags().StringVar(&version, "version", "dev", "版本号标记")
+
+	catalogCmd.AddCommand(exportCmd)
+	return catalogCmd
+}
+
+// projectToolMapping 把 ir.Catalog 投影成 toolMapping 契约。
+func projectToolMapping(catalog ir.Catalog, version string) toolMapping {
+	mapping := toolMapping{Version: version, Tools: make(map[string]toolMappingEntry)}
+	for _, product := range catalog.Products {
+		command := ""
+		if product.CLI != nil {
+			command = strings.TrimSpace(product.CLI.Command)
+		}
+		if command == "" {
+			command = product.ID
+		}
+		for _, tool := range product.Tools {
+			if tool.Hidden {
+				continue
+			}
+			entry := toolMappingEntry{
+				Product:     command,
+				CLICommand:  tmBuildCLICommand(command, tool),
+				DisplayName: tmFirstNonEmpty(tool.Title, tmFirstNonEmpty(tmFirstLine(tool.Description), tool.RPCName)),
+				Params:      make(map[string]toolMappingParam),
+			}
+			for name, raw := range tmSchemaProperties(tool.InputSchema) {
+				prop, _ := raw.(map[string]any)
+				overlay, hasOverlay := tool.FlagOverlay[name]
+				if hasOverlay && overlay.Hidden {
+					continue
+				}
+				flag := tmKebab(name)
+				if hasOverlay && strings.TrimSpace(overlay.Alias) != "" {
+					flag = strings.TrimSpace(overlay.Alias)
+				}
+				label := tmMapStr(prop, "title")
+				if label == "" {
+					label = tmFirstLine(tmMapStr(prop, "description"))
+				}
+				entry.Params[name] = toolMappingParam{
+					Flag:  flag,
+					Label: label,
+					Type:  tmMapStr(prop, "type"),
+				}
+			}
+			if len(entry.Params) == 0 {
+				entry.Params = nil
+			}
+			mapping.Tools[tool.RPCName] = entry
+		}
+	}
+	mapping.Count = len(mapping.Tools)
+	return mapping
+}
+
+// tmBuildCLICommand 拼出 CLI 命令路径，如 chat + message + list -> "chat message list"。
+func tmBuildCLICommand(command string, tool ir.ToolDescriptor) string {
+	parts := make([]string, 0, 3)
+	if command != "" {
+		parts = append(parts, command)
+	}
+	if g := strings.TrimSpace(tool.Group); g != "" {
+		parts = append(parts, g)
+	}
+	name := strings.TrimSpace(tool.CLIName)
+	if name == "" {
+		name = tool.RPCName
+	}
+	parts = append(parts, name)
+	return strings.Join(parts, " ")
+}
+
+func tmSchemaProperties(schema map[string]any) map[string]any {
+	if schema == nil {
+		return nil
+	}
+	props, _ := schema["properties"].(map[string]any)
+	return props
+}
+
+func tmMapStr(m map[string]any, key string) string {
+	if m == nil {
+		return ""
+	}
+	s, _ := m[key].(string)
+	return strings.TrimSpace(s)
+}
+
+// tmFirstLine 取第一句中文/换行前的片段，作为长描述的短标签兜底。
+func tmFirstLine(s string) string {
+	s = strings.TrimSpace(s)
+	if i := strings.IndexAny(s, "\n。"); i >= 0 {
+		return strings.TrimSpace(s[:i])
+	}
+	return s
+}
+
+func tmFirstNonEmpty(a, b string) string {
+	if strings.TrimSpace(a) != "" {
+		return strings.TrimSpace(a)
+	}
+	return strings.TrimSpace(b)
+}
+
+// tmKebab 把 camelCase 参数名转 kebab-case 作为默认 flag。
+func tmKebab(s string) string {
+	var b strings.Builder
+	for i, r := range s {
+		if r >= 'A' && r <= 'Z' {
+			if i > 0 {
+				b.WriteByte('-')
+			}
+			b.WriteRune(r - 'A' + 'a')
+			continue
+		}
+		b.WriteRune(r)
+	}
+	return b.String()
+}

internal/app/direct_runtime.go

@@ -24,6 +24,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
 var (
@@ -45,8 +46,17 @@ const (
 	defaultPATProductID   = "pat"
 	defaultPATDisplayName = "行为授权"
 	defaultPATServerID    = "abc3c880fb90f04b52d1426aaf093766e5fc9ec38411688cbb74df42a584d374"
+	devappProductID       = "devapp"
+	devappServerPath      = "/server/op-app"
 )
 
+// devappMCPEndpoint resolves the open-platform app-management MCP endpoint
+// from the configured gateway base URL, so it follows the active environment
+// (production by default, pre when ~/.dws/mcp_url points at the pre gateway).
+func devappMCPEndpoint() string {
+	return defaultPATGatewayBaseURL() + devappServerPath
+}
+
 func defaultPATServerDescriptor() market.ServerDescriptor {
 	return market.ServerDescriptor{
 		Key:         defaultPATProductID,
@@ -220,12 +230,9 @@ func directRuntimeToolEndpoint(toolName string) (string, bool) {
 		return "", false
 	}
 	dynamicMu.RLock()
-	te := dynamicToolEndpoints
-	dynamicMu.RUnlock()
-	if te == nil {
-		return "", false
-	}
-	endpoint, ok := te[toolName]
+	defer dynamicMu.RUnlock()
+
+	endpoint, ok := dynamicToolEndpoints[toolName]
 	return endpoint, ok && strings.TrimSpace(endpoint) != ""
 }
 
@@ -241,24 +248,27 @@ func directRuntimeEndpoint(productID, toolName string) (string, bool) {
 		}
 	}
 
-	dynamicMu.RLock()
-	de := dynamicEndpoints
-	te := dynamicToolEndpoints
-	dynamicMu.RUnlock()
+	// Hardcoded built-in: devapp is pinned to the open-platform app-management
+	// MCP server in source (NOT service discovery), per product decision.
+	for _, candidate := range []string{strings.TrimSpace(productID), normalized} {
+		if candidate == devappProductID {
+			return devappMCPEndpoint(), true
+		}
+	}
 
 	// Priority 1: product-level endpoint.
 	// When the caller already knows the productID (e.g. "drive"), the product
 	// endpoint is authoritative. This prevents cross-product tool name
 	// collisions (e.g. both "drive" and "doc" register "create_folder") from
 	// routing the request to the wrong MCP server. See issue #219.
+	dynamicMu.RLock()
 	for _, candidate := range []string{strings.TrimSpace(productID), normalized} {
 		if candidate == "" {
 			continue
 		}
-		if de != nil {
-			if endpoint, ok := de[candidate]; ok {
-				return endpoint, true
-			}
+		if endpoint, ok := dynamicEndpoints[candidate]; ok {
+			dynamicMu.RUnlock()
+			return endpoint, true
 		}
 	}
 
@@ -266,11 +276,13 @@ func directRuntimeEndpoint(productID, toolName string) (string, bool) {
 	// This path is used when the caller does not know the productID but has a
 	// tool name, e.g. in helper invocations or plugin routes where only the
 	// tool name is available.
-	if tool := strings.TrimSpace(toolName); tool != "" && te != nil {
-		if endpoint, ok := te[tool]; ok {
+	if tool := strings.TrimSpace(toolName); tool != "" {
+		if endpoint, ok := dynamicToolEndpoints[tool]; ok {
+			dynamicMu.RUnlock()
 			return endpoint, true
 		}
 	}
+	dynamicMu.RUnlock()
 
 	// Priority 3: built-in PAT fallback for cold-start paths that run before
 	// discovery/plugin registration has populated the dynamic registry.
@@ -279,18 +291,69 @@ func directRuntimeEndpoint(productID, toolName string) (string, bool) {
 			return defaultPATMCPEndpoint(), true
 		}
 	}
+
+	// Priority 4: edition-owned static/supplement endpoints. Helper-only
+	// products such as devapp intentionally do not depend on Market discovery,
+	// so the internal edition may provide only an endpoint and no tool list.
+	for _, candidate := range []string{strings.TrimSpace(productID), normalized} {
+		if endpoint, ok := editionServerEndpoint(candidate); ok {
+			return endpoint, true
+		}
+	}
 	return "", false
 }
 
-// DirectRuntimeProductIDs returns the set of product IDs that have direct
-// runtime endpoints configured, sourced from dynamic server discovery.
+func editionServerEndpoint(productID string) (string, bool) {
+	productID = strings.TrimSpace(productID)
+	if productID == "" {
+		return "", false
+	}
+	hooks := edition.Get()
+	if hooks == nil {
+		return "", false
+	}
+	if endpoint, ok := endpointFromEditionServers(productID, hooks.StaticServers); ok {
+		return endpoint, true
+	}
+	if endpoint, ok := endpointFromEditionServers(productID, hooks.SupplementServers); ok {
+		return endpoint, true
+	}
+	return "", false
+}
+
+func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo) (string, bool) {
+	if fn == nil {
+		return "", false
+	}
+	for _, server := range fn() {
+		endpoint := strings.TrimSpace(server.Endpoint)
+		if endpoint == "" {
+			continue
+		}
+		if strings.TrimSpace(server.ID) == productID {
+			return endpoint, true
+		}
+		for _, prefix := range server.Prefixes {
+			if strings.TrimSpace(prefix) == productID {
+				return endpoint, true
+			}
+		}
+	}
+	return "", false
+}
+
+// DirectRuntimeProductIDs returns product IDs that should stay visible for
+// direct runtime execution. Dynamic products come from MCP discovery/plugin
+// registration; built-in helper products such as devapp resolve their endpoint
+// through DINGTALK_<PRODUCT>_MCP_URL instead of requiring discovery.
 func DirectRuntimeProductIDs() map[string]bool {
 	dynamicMu.RLock()
-	dp := dynamicProducts
-	dynamicMu.RUnlock()
-	ids := make(map[string]bool, len(dp)+1)
+	defer dynamicMu.RUnlock()
+
+	ids := make(map[string]bool, len(dynamicProducts)+2)
 	ids[defaultPATProductID] = true
-	for key := range dp {
+	ids[devappProductID] = true
+	for key := range dynamicProducts {
 		ids[key] = true
 	}
 	return ids
@@ -365,15 +428,14 @@ func AppendDynamicServer(server market.ServerDescriptor) {
 }
 
 func normalizeDirectRuntimeProductID(productID string) string {
-	dynamicMu.RLock()
-	da := dynamicAliases
-	dynamicMu.RUnlock()
 	trimmed := strings.TrimSpace(productID)
-	if da != nil {
-		if normalizedID, ok := da[trimmed]; ok && normalizedID != "" {
-			return normalizedID
-		}
+	dynamicMu.RLock()
+	if normalizedID, ok := dynamicAliases[trimmed]; ok && normalizedID != "" {
+		dynamicMu.RUnlock()
+		return normalizedID
 	}
+	dynamicMu.RUnlock()
+
 	if normalizedID, ok := legacyDirectRuntimeAliases[trimmed]; ok {
 		return normalizedID
 	}

internal/app/direct_runtime_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
 func TestDefaultPATServerDescriptorUsesBehaviorAuthorizationName(t *testing.T) {
@@ -38,6 +39,107 @@ func TestDirectRuntimeProductIDsIncludesDefaultPAT(t *testing.T) {
 	}
 }
 
+func TestDirectRuntimeProductIDsIncludesDevappHelper(t *testing.T) {
+	withCleanDynamicRegistry(t)
+
+	ids := DirectRuntimeProductIDs()
+	if !ids["devapp"] {
+		t.Fatalf("DirectRuntimeProductIDs() missing devapp helper product: %#v", ids)
+	}
+}
+
+func TestDirectRuntimeEndpoint_DevappEnvOverrideWithoutRegistry(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp")
+
+	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp")
+}
+
+func TestDirectRuntimeEndpoint_DevappEnvOverridePreservesQuery(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp?key=secret")
+
+	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp?key=secret")
+}
+
+func TestDirectRuntimeEndpoint_DevappDynamicServerDoesNotOverrideHardcoded(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	SetDynamicServers([]market.ServerDescriptor{
+		{
+			Endpoint: "https://example.test/server/devapp-supplement",
+			CLI: market.CLIOverlay{
+				ID:      "devapp",
+				Command: "devapp",
+			},
+		},
+	})
+
+	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
+}
+
+func TestDirectRuntimeEndpoint_DevappEditionSupplementDoesNotOverrideHardcoded(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		Name: "wukong",
+		SupplementServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{
+				{
+					ID:       "devapp",
+					Name:     "开放平台应用管理",
+					Endpoint: "https://example.test/server/devapp-edition-supplement?key=secret",
+					Prefixes: []string{"devapp", "app"},
+				},
+			}
+		},
+	})
+	t.Cleanup(func() { edition.Override(prev) })
+
+	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
+}
+
+func TestDirectRuntimeEndpoint_DevappEditionStaticDoesNotOverrideHardcoded(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		Name: "wukong",
+		StaticServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{
+				{
+					ID:       "devapp",
+					Name:     "开放平台应用管理",
+					Endpoint: "https://example.test/server/devapp-edition-static",
+					Prefixes: []string{"devapp", "app"},
+				},
+			}
+		},
+	})
+	t.Cleanup(func() { edition.Override(prev) })
+
+	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
+}
+
+func TestDirectRuntimeEndpoint_DevappEnvOverrideWinsOverEditionSupplement(t *testing.T) {
+	withCleanDynamicRegistry(t)
+	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp-env")
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		Name: "wukong",
+		SupplementServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{
+				{
+					ID:       "devapp",
+					Name:     "开放平台应用管理",
+					Endpoint: "https://example.test/server/devapp-edition-supplement",
+				},
+			}
+		},
+	})
+	t.Cleanup(func() { edition.Override(prev) })
+
+	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp-env")
+}
+
 func TestDirectRuntimeEndpoint_DefaultPATFallbackWhenRegistryMissing(t *testing.T) {
 	withCleanDynamicRegistry(t)
 	assertEndpoint(t, "pat", "", defaultPATMCPEndpoint())

internal/app/doctor_command.go

@@ -24,6 +24,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cache"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -112,7 +113,8 @@ func runDoctor(cmd *cobra.Command, _ []string) error {
 		return output.WriteJSON(w, result)
 	}
 
-	fmt.Fprintf(w, "\n诊断完成: %d 项通过, %d 项警告, %d 项失败\n", pass, warn, fail)
+	fmt.Fprintf(w, "\n%s\n", tui.Header("Doctor", fmt.Sprintf("%d pass · %d warn · %d fail", pass, warn, fail)))
+	fmt.Fprintf(w, "%s 诊断完成: %d 项通过, %d 项警告, %d 项失败\n", tui.StateMark("ok"), pass, warn, fail)
 	if fail > 0 {
 		return fmt.Errorf("诊断发现 %d 项失败", fail)
 	}
@@ -123,7 +125,7 @@ func runDoctor(cmd *cobra.Command, _ []string) error {
 
 func doctorCheckAuth(ctx context.Context, w io.Writer, jsonOut bool) checkResult {
 	if !jsonOut {
-		fmt.Fprint(w, "检查登录状态...       ")
+		fmt.Fprint(w, tui.Dim("检查登录状态...       "))
 	}
 
 	configDir := defaultConfigDir()
@@ -186,7 +188,7 @@ func doctorCheckAuth(ctx context.Context, w io.Writer, jsonOut bool) checkResult
 
 func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout time.Duration) checkResult {
 	if !jsonOut {
-		fmt.Fprint(w, "检查网络连通性...     ")
+		fmt.Fprint(w, tui.Dim("检查网络连通性...     "))
 	}
 
 	baseURL := config.GetMCPBaseURL()
@@ -228,7 +230,7 @@ func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout
 
 func doctorCheckCache(w io.Writer, jsonOut bool) checkResult {
 	if !jsonOut {
-		fmt.Fprint(w, "检查缓存状态...       ")
+		fmt.Fprint(w, tui.Dim("检查缓存状态...       "))
 	}
 
 	store := cacheStoreFromEnv()
@@ -300,7 +302,7 @@ func doctorCheckCache(w io.Writer, jsonOut bool) checkResult {
 
 func doctorCheckVersion(w io.Writer, jsonOut bool, timeout time.Duration) checkResult {
 	if !jsonOut {
-		fmt.Fprint(w, "检查版本更新...       ")
+		fmt.Fprint(w, tui.Dim("检查版本更新...       "))
 	}
 
 	currentVer := version
@@ -348,9 +350,18 @@ func doctorCheckVersion(w io.Writer, jsonOut bool, timeout time.Duration) checkR
 
 func printCheckResult(w io.Writer, r checkResult) {
 	icon := statusIcon(r.Status)
-	fmt.Fprintf(w, "%s %s\n", icon, r.Message)
+	message := r.Message
+	switch r.Status {
+	case statusPass:
+		message = tui.Success(message)
+	case statusWarn:
+		message = tui.Warning(message)
+	case statusFail:
+		message = tui.Danger(message)
+	}
+	fmt.Fprintf(w, "%s %s\n", icon, message)
 	if r.Hint != "" {
-		fmt.Fprintf(w, "                      %s\n", r.Hint)
+		fmt.Fprintf(w, "                      %s\n", tui.Dim(r.Hint))
 	}
 }
 
@@ -385,7 +396,7 @@ func countResults(checks []checkResult) (pass, warn, fail int) {
 
 func doctorCheckPerf(w io.Writer, jsonOut bool) checkResult {
 	if !jsonOut {
-		fmt.Fprint(w, "检查性能报告...       ")
+		fmt.Fprint(w, tui.Dim("检查性能报告...       "))
 	}
 
 	report, err := LoadLatestReport()

internal/app/help_source_test.go

@@ -55,9 +55,11 @@ func TestRootCommandDoesNotInjectPatchedHelpCommands(t *testing.T) {
 	t.Cleanup(func() { SetDiscoveryBaseURL("") })
 
 	root := NewRootCommand()
+	// `minutes list all` is intentionally provided as a hardcoded helper
+	// (see internal/helpers/minutes_commands.go) to align with the wukong
+	// baseline, so it is expected to resolve and is no longer asserted here.
 	for _, path := range []string{
 		"chat message list-topic-replies",
-		"minutes list all",
 	} {
 		if cmd := lookupCommand(root, path); cmd != nil {
 			t.Fatalf("findCommand(%q) = %q, want nil", path, cmd.CommandPath())

internal/app/helper_tool_fetcher.go

@@ -0,0 +1,136 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"context"
+	"fmt"
+	"sync"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+// newHelperToolFetcher returns a cli.HelperToolFetcher that loads a helper MCP
+// server's tools/list LIVE (by source) and projects each tool into a
+// cli.HelperToolSchema (name, description, inputSchema properties/required). It
+// is injected into the schema command so the cli package can render
+// `dws schema dev.*` from real server schema without importing app/transport.
+//
+// Sources: "op-app" backs the dev app commands (pinned endpoint); "devdoc"
+// backs `dws dev doc search` (endpoint resolved dynamically, see
+// helperSourceEndpoint). Results are memoized per source per process so
+// repeated `dws schema dev.*` hit the network at most once per source. A failed
+// fetch is not cached, allowing a later retry within the same process.
+func newHelperToolFetcher() cli.HelperToolFetcher {
+	var (
+		mu     sync.Mutex
+		cached = map[string]map[string]cli.HelperToolSchema{}
+	)
+	return func(ctx context.Context, source string) (map[string]cli.HelperToolSchema, error) {
+		mu.Lock()
+		if got, ok := cached[source]; ok {
+			mu.Unlock()
+			return got, nil
+		}
+		mu.Unlock()
+
+		endpoint, err := helperSourceEndpoint(source)
+		if err != nil {
+			return nil, err
+		}
+		schemas, err := fetchHelperToolSchemas(ctx, endpoint)
+		if err != nil {
+			return nil, err
+		}
+		mu.Lock()
+		cached[source] = schemas
+		mu.Unlock()
+		return schemas, nil
+	}
+}
+
+// helperSourceEndpoint maps a schema source to its MCP endpoint. op-app (dev
+// app) is pinned in source (devappMCPEndpoint, derived from the active gateway
+// base — production by default, pre when ~/.dws/mcp_url points at pre); other
+// sources (e.g. devdoc) are resolved the same way the runner resolves a product
+// endpoint — env override → discovery → edition StaticServers/SupplementServers.
+func helperSourceEndpoint(source string) (string, error) {
+	switch source {
+	case "", "op-app", "devapp":
+		return devappMCPEndpoint(), nil
+	default:
+		if endpoint, ok := directRuntimeEndpoint(source, ""); ok {
+			return endpoint, nil
+		}
+		return "", fmt.Errorf("no MCP endpoint resolved for source %q (not injected by edition/discovery)", source)
+	}
+}
+
+// fetchHelperToolSchemas performs the live tools/list call against endpoint and
+// converts the descriptors. Auth and identity headers are resolved the same way
+// the runner does for direct-runtime invocations.
+func fetchHelperToolSchemas(ctx context.Context, endpoint string) (map[string]cli.HelperToolSchema, error) {
+	token := resolveRuntimeAuthToken(ctx, "")
+	headers := resolveIdentityHeaders()
+	client := transport.NewClient(nil).WithAuth(token, headers)
+
+	result, err := client.ListTools(ctx, endpoint)
+	if err != nil {
+		return nil, err
+	}
+
+	out := make(map[string]cli.HelperToolSchema, len(result.Tools))
+	for _, td := range result.Tools {
+		out[td.Name] = cli.HelperToolSchema{
+			Name:        td.Name,
+			Description: td.Description,
+			Properties:  inputSchemaProperties(td.InputSchema),
+			Required:    inputSchemaRequired(td.InputSchema),
+		}
+	}
+	return out, nil
+}
+
+// inputSchemaProperties pulls the "properties" object out of a deserialized
+// MCP inputSchema map. Returns an empty (non-nil) map when absent.
+func inputSchemaProperties(schema map[string]any) map[string]any {
+	if schema == nil {
+		return map[string]any{}
+	}
+	props, _ := schema["properties"].(map[string]any)
+	if props == nil {
+		return map[string]any{}
+	}
+	return props
+}
+
+// inputSchemaRequired pulls the "required" string list out of a deserialized
+// MCP inputSchema map.
+func inputSchemaRequired(schema map[string]any) []string {
+	if schema == nil {
+		return nil
+	}
+	raw, ok := schema["required"].([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(raw))
+	for _, v := range raw {
+		if s, ok := v.(string); ok && s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}

internal/app/legacy.go

@@ -310,7 +310,7 @@ func loadDynamicCommands(ctx context.Context, runner executor.Runner) []*cobra.C
 				// no-op: fall through to FallbackServers check below
 			}
 		} else {
-			servers = market.NormalizeServers(resp, "market")
+			servers = market.NormalizeServersForBaseURL(resp, "market", registryDiscoveryBaseURL())
 			if discoveryTraceEnabled() {
 				slog.Info("loadDynamicCommands: sync discovery fetch ok",
 					"partition", partition,
@@ -568,6 +568,13 @@ func fetchRegistryServers(ctx context.Context, httpClient *http.Client) (market.
 	return client.FetchServers(ctx, config.DefaultFetchServersLimit)
 }
 
+func registryDiscoveryBaseURL() string {
+	if editionURL := strings.TrimSpace(edition.Get().DiscoveryURL); editionURL != "" {
+		return editionURL
+	}
+	return DiscoveryBaseURL()
+}
+
 // asyncRevalidateRegistry refreshes the registry cache in the background.
 // Uses a short timeout derived from the parent context and silently ignores
 // errors — the next CLI invocation will pick up the refreshed cache or retry.
@@ -580,7 +587,7 @@ func asyncRevalidateRegistry(parent context.Context, store *cache.Store, partiti
 		slog.Debug("asyncRevalidateRegistry: fetch failed", "error", err)
 		return
 	}
-	servers := market.NormalizeServers(resp, "market")
+	servers := market.NormalizeServersForBaseURL(resp, "market", registryDiscoveryBaseURL())
 	if saveErr := store.SaveRegistry(partition, cache.RegistrySnapshot{Servers: servers}); saveErr != nil {
 		slog.Debug("asyncRevalidateRegistry: save failed", "error", saveErr)
 	}

internal/app/legacy_cache_test.go

@@ -359,7 +359,7 @@ func TestLoadDynamicCommandsDoesNotSynchronouslyFetchDetailMetadata(t *testing.T
 
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch {
-		case r.URL.Path == "/cli/discovery/apis/bamboo":
+		case r.URL.Path == "/cli/discovery/apis/cedar":
 			payload := map[string]any{
 				"metadata": map[string]any{"count": 2, "nextCursor": ""},
 				"servers": []any{
@@ -433,7 +433,7 @@ func TestLoadDynamicCommandsDoesNotSynchronouslyFetchDetailMetadataWhenRegistryT
 
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch {
-		case r.URL.Path == "/cli/discovery/apis/bamboo":
+		case r.URL.Path == "/cli/discovery/apis/cedar":
 			_ = json.NewEncoder(w).Encode(map[string]any{
 				"metadata": map[string]any{"count": 2, "nextCursor": ""},
 				"servers": []any{

internal/app/pat_auth_retry.go

@@ -33,8 +33,9 @@ import (
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
-	"github.com/fatih/color"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 )
 
 const (
@@ -51,6 +52,10 @@ const (
 
 var openBrowserFunc = tryOpenBrowser
 
+type patSuppressBrowserOpenKeyType struct{}
+
+var patSuppressBrowserOpenKey = patSuppressBrowserOpenKeyType{}
+
 // PatScopeError holds information about a missing PAT scope.
 type PatScopeError struct {
 	OriginalError string
@@ -153,36 +158,31 @@ func extractPatScopeError(err error) *PatScopeError {
 
 // PrintPatAuthError prints a human-readable PAT authorization error.
 func PrintPatAuthError(w io.Writer, scopeErr *PatScopeError) {
-	bold := color.New(color.Bold).SprintFunc()
-	cyan := color.New(color.FgCyan).SprintFunc()
-	dim := color.New(color.Faint).SprintFunc()
-	green := color.New(color.FgGreen).SprintFunc()
-
 	fmt.Fprintln(w)
 	fmt.Fprintf(w, "{\n")
-	fmt.Fprintf(w, "  %s: %s,\n", bold("\"ok\""), "false")
-	fmt.Fprintf(w, "  %s: %q,\n", bold("\"identity\""), scopeErr.Identity)
-	fmt.Fprintf(w, "  %s: {\n", bold("\"error\""))
-	fmt.Fprintf(w, "    %s: %q,\n", bold("\"type\""), scopeErr.ErrorType)
-	fmt.Fprintf(w, "    %s: %q,\n", bold("\"message\""), scopeErr.Message)
-	fmt.Fprintf(w, "    %s: %q\n", bold("\"hint\""), scopeErr.Hint)
+	fmt.Fprintf(w, "  %s: %s,\n", tui.Bold("\"ok\""), "false")
+	fmt.Fprintf(w, "  %s: %q,\n", tui.Bold("\"identity\""), scopeErr.Identity)
+	fmt.Fprintf(w, "  %s: {\n", tui.Bold("\"error\""))
+	fmt.Fprintf(w, "    %s: %q,\n", tui.Bold("\"type\""), scopeErr.ErrorType)
+	fmt.Fprintf(w, "    %s: %q,\n", tui.Bold("\"message\""), scopeErr.Message)
+	fmt.Fprintf(w, "    %s: %q\n", tui.Bold("\"hint\""), scopeErr.Hint)
 	fmt.Fprintf(w, "  }\n")
 	fmt.Fprintf(w, "}\n")
 	fmt.Fprintln(w)
 
 	// Print authorization instructions
-	fmt.Fprintf(w, "%s %s\n", green("▶"), bold("需要额外授权"))
+	fmt.Fprintf(w, "%s %s\n", tui.StateMark("warning"), tui.Bold("需要额外授权"))
 	fmt.Fprintln(w)
-	fmt.Fprintf(w, "  %s %s\n", dim("#"), dim("运行以下命令完成授权"))
+	fmt.Fprintf(w, "  %s %s\n", tui.Dim("#"), tui.Dim("运行以下命令完成授权"))
 
 	if scopeErr.MissingScope != "" {
-		fmt.Fprintf(w, "  %s %s\n", cyan("$"), cyan(fmt.Sprintf("dws auth login --scope %q", scopeErr.MissingScope)))
+		fmt.Fprintf(w, "  %s %s\n", tui.Cyan("$"), tui.Cyan(fmt.Sprintf("dws auth login --scope %q", scopeErr.MissingScope)))
 	} else {
-		fmt.Fprintf(w, "  %s %s\n", cyan("$"), cyan("dws auth login"))
+		fmt.Fprintf(w, "  %s %s\n", tui.Cyan("$"), tui.Cyan("dws auth login"))
 	}
 
 	fmt.Fprintln(w)
-	fmt.Fprintf(w, "  %s 在浏览器中打开授权链接，完成授权后重新执行命令\n", dim("ℹ"))
+	fmt.Fprintf(w, "  %s 在浏览器中打开授权链接，完成授权后重新执行命令\n", tui.Dim("ℹ"))
 	fmt.Fprintln(w)
 }
 
@@ -206,7 +206,10 @@ func wantsStructuredPATOutputFromRunner(runner executor.Runner) bool {
 	return wantsStructuredPATOutput(rr)
 }
 
-func currentPATOpenBrowser(configDir string) bool {
+func currentPATOpenBrowser(ctx context.Context, configDir string) bool {
+	if suppressed, _ := ctx.Value(patSuppressBrowserOpenKey).(bool); suppressed {
+		return false
+	}
 	return pat.EffectiveOpenBrowser(configDir)
 }
 
@@ -225,8 +228,11 @@ func enrichPATErrorWithOpenBrowser(raw string, openBrowser bool) string {
 		data = map[string]any{}
 		payload["data"] = data
 	}
-	if rawURI, ok := data["uri"].(string); ok && strings.TrimSpace(rawURI) != "" {
-		data["authorizationUrl"] = apperrors.PATAuthorizationURL(rawURI)
+	if rawURI := patAuthorizationURIFromData(data); rawURI != "" {
+		authURL := apperrors.PATAuthorizationURL(rawURI)
+		data["uri"] = authURL
+		delete(data, "authUrl")
+		delete(data, "authorizationUrl")
 	}
 	data["openBrowser"] = openBrowser
 
@@ -237,15 +243,19 @@ func enrichPATErrorWithOpenBrowser(raw string, openBrowser bool) string {
 	return string(encoded)
 }
 
+func patAuthorizationURIFromData(data map[string]any) string {
+	for _, key := range []string{"uri", "authUrl", "authorizationUrl"} {
+		value, _ := data[key].(string)
+		if strings.TrimSpace(value) != "" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
 // WaitForPatAuthorization polls until the user completes authorization or timeout.
 // It returns true if authorization was completed, false if timed out or cancelled.
 func WaitForPatAuthorization(ctx context.Context, configDir string, output io.Writer) bool {
-	bold := color.New(color.Bold).SprintFunc()
-	yellow := color.New(color.FgYellow).SprintFunc()
-	green := color.New(color.FgGreen).SprintFunc()
-	red := color.New(color.FgRed).SprintFunc()
-	dim := color.New(color.Faint).SprintFunc()
-
 	timeout := PatAuthRetryTimeout
 	deadline := time.Now().Add(timeout)
 	pollTicker := time.NewTicker(PatAuthPollInterval)
@@ -253,21 +263,21 @@ func WaitForPatAuthorization(ctx context.Context, configDir string, output io.Wr
 	start := time.Now()
 
 	fmt.Fprintln(output)
-	fmt.Fprintf(output, "%s %s\n", yellow("⏳"), bold("等待用户授权..."))
-	fmt.Fprintf(output, "  %s 请在另一个终端完成 dws auth login 授权\n", dim("ℹ"))
-	fmt.Fprintf(output, "  %s 超时时间: %s\n", dim("⏱"), timeout)
+	fmt.Fprintf(output, "%s %s\n", tui.StateMark("pending"), tui.Bold("等待用户授权..."))
+	fmt.Fprintf(output, "  %s 请在另一个终端完成 dws auth login 授权\n", tui.Dim("ℹ"))
+	fmt.Fprintf(output, "  %s 超时时间: %s\n", tui.Dim("⏱"), timeout)
 	fmt.Fprintln(output)
 
 	pollCount := 0
 	for {
 		select {
 		case <-ctx.Done():
-			fmt.Fprintf(output, "%s 操作已取消\n", red("✗"))
+			fmt.Fprintf(output, "%s 操作已取消\n", tui.StateMark("error"))
 			return false
 
 		case <-time.After(time.Until(deadline)):
-			fmt.Fprintf(output, "%s 等待授权超时 (%s)\n", red("✗"), timeout)
-			fmt.Fprintf(output, "  %s 请重新执行命令\n", dim("ℹ"))
+			fmt.Fprintf(output, "%s 等待授权超时 (%s)\n", tui.StateMark("error"), timeout)
+			fmt.Fprintf(output, "  %s 请重新执行命令\n", tui.Dim("ℹ"))
 			return false
 
 		case <-pollTicker.C:
@@ -280,7 +290,7 @@ func WaitForPatAuthorization(ctx context.Context, configDir string, output io.Wr
 			if err == nil && tokenData != nil {
 				if tokenData.IsAccessTokenValid() || tokenData.IsRefreshTokenValid() {
 					fmt.Fprintf(output, "\r%s %s (%s 已用, %s 剩余)          \n",
-						green("✓"), bold("授权成功!"), elapsed, remaining)
+						tui.StateMark("ok"), tui.Bold("授权成功!"), elapsed, remaining)
 					fmt.Fprintln(output)
 					return true
 				}
@@ -288,7 +298,7 @@ func WaitForPatAuthorization(ctx context.Context, configDir string, output io.Wr
 
 			// Show polling status
 			fmt.Fprintf(output, "\r%s [%d] 等待授权中... (%s 已用, %s 剩余)          ",
-				dim("⟳"), pollCount, elapsed, remaining)
+				tui.Dim("⟳"), pollCount, elapsed, remaining)
 		}
 	}
 }
@@ -328,8 +338,7 @@ func retryWithPatAuthRetry(ctx context.Context, runner executor.Runner, invocati
 
 	// Retry the invocation
 	fmt.Fprintln(output)
-	fmt.Fprintf(output, "%s %s\n", color.New(color.FgGreen).SprintFunc()("▶"),
-		color.New(color.Bold).SprintFunc()("授权完成，正在重试..."))
+	fmt.Fprintf(output, "%s %s\n", tui.StateMark("ok"), tui.Bold("授权完成，正在重试..."))
 	fmt.Fprintln(output)
 
 	return runner.Run(ctx, invocation)
@@ -340,6 +349,9 @@ func retryWithPatAuthRetry(ctx context.Context, runner executor.Runner, invocati
 const (
 	// patPollInterval is how often we poll the device flow status endpoint.
 	patPollInterval = 2 * time.Second
+	// patMaxPollInterval caps a server-provided poll interval so a malformed
+	// response cannot make the CLI look permanently stuck.
+	patMaxPollInterval = 30 * time.Second
 	// patPollTimeout is the maximum time to wait for user authorization via device flow.
 	patPollTimeout = 10 * time.Minute
 )
@@ -350,6 +362,12 @@ type patRetryingKeyType struct{}
 
 var patRetryingKey = patRetryingKeyType{}
 
+type patRetryRunnerFunc func(context.Context, executor.Invocation) (executor.Result, error)
+
+func (f patRetryRunnerFunc) Run(ctx context.Context, invocation executor.Invocation) (executor.Result, error) {
+	return f(ctx, invocation)
+}
+
 // IsPatRetrying returns true if the current context is already in a PAT retry.
 func IsPatRetrying(ctx context.Context) bool {
 	v, _ := ctx.Value(patRetryingKey).(bool)
@@ -364,8 +382,8 @@ func openPATAuthorizationURI(rawURI string) error {
 	}
 	// The PAT service returns the complete authorization URL. Treat it as an
 	// opaque string unless it is the known legacy DingTalk hash-route variant.
-	// That variant is normalized by the PAT error contract helper while still
-	// preserving the original data.uri in structured output.
+	// That variant is normalized by the PAT error contract helper before being
+	// printed, opened, or returned in structured output.
 	return openBrowserFunc(apperrors.PATAuthorizationURL(rawURI))
 }
 
@@ -382,6 +400,70 @@ func printPATPollDebugResponse(output io.Writer, statusCode int, body []byte) {
 	fmt.Fprintf(output, "    %s\n", trimmed)
 }
 
+func runDirectPATAuthCheck(
+	ctx context.Context,
+	globalFlags *GlobalFlags,
+	patErr *apperrors.PATError,
+	retry func(context.Context) error,
+	output io.Writer,
+) error {
+	if retry == nil {
+		return patErr
+	}
+	return runDirectPATAuthCheckWithMode(ctx, globalFlags, patErr, retry, output, true)
+}
+
+func runDirectPATAuthCheckWaitOnly(
+	ctx context.Context,
+	globalFlags *GlobalFlags,
+	patErr *apperrors.PATError,
+	output io.Writer,
+) error {
+	ctx = context.WithValue(ctx, patSuppressBrowserOpenKey, true)
+	return runDirectPATAuthCheckWithMode(ctx, globalFlags, patErr, nil, output, false)
+}
+
+func runDirectPATAuthCheckWithMode(
+	ctx context.Context,
+	globalFlags *GlobalFlags,
+	patErr *apperrors.PATError,
+	retry func(context.Context) error,
+	output io.Writer,
+	retryAfterApproval bool,
+) error {
+	if retryAfterApproval && retry == nil {
+		return patErr
+	}
+	runner := &runtimeRunner{
+		globalFlags: globalFlags,
+		fallback: patRetryRunnerFunc(func(retryCtx context.Context, invocation executor.Invocation) (executor.Result, error) {
+			if retry != nil {
+				if err := retry(retryCtx); err != nil {
+					return executor.Result{}, err
+				}
+			}
+			invocation.Implemented = true
+			return executor.Result{
+				Invocation: invocation,
+				Response: map[string]any{
+					"ok": true,
+				},
+			}, nil
+		}),
+	}
+	_, err := handlePatAuthCheck(ctx, runner, executor.Invocation{
+		Kind:             "direct_pat_authorization",
+		Stage:            "auth_login_recommend",
+		CanonicalProduct: defaultPATProductID,
+		Tool:             "pat.batch_grant",
+		CanonicalPath:    "pat.batch_grant",
+		Params: map[string]any{
+			"retryAfterApproval": retryAfterApproval,
+		},
+	}, patErr, defaultConfigDir(), output)
+	return err
+}
+
 // handlePatAuthCheck is called by runner.executeInvocation when a PAT
 // authorization error is detected.  It injects the server-assigned clientId
 // as x-robot-uid header, prints authorization details, opens the browser,
@@ -399,16 +481,25 @@ func handlePatAuthCheck(
 	var patData struct {
 		Code string `json:"code"`
 		Data struct {
-			Desc         string `json:"desc"`
-			FlowID       string `json:"flowId"`
-			URI          string `json:"uri"`
-			ClientID     string `json:"clientId"`
-			ClientSecret string `json:"clientSecret"`
+			Desc             string `json:"desc"`
+			FlowID           string `json:"flowId"`
+			URI              string `json:"uri"`
+			AuthURL          string `json:"authUrl"`
+			AuthorizationURL string `json:"authorizationUrl"`
+			ClientID         string `json:"clientId"`
+			ClientSecret     string `json:"clientSecret"`
+			PollIntervalSecs int    `json:"pollIntervalSeconds"`
 		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(patErr.RawJSON), &patData); err != nil {
 		return executor.Result{}, patErr
 	}
+	if patData.Data.URI == "" {
+		patData.Data.URI = patData.Data.AuthURL
+	}
+	if patData.Data.URI == "" {
+		patData.Data.URI = patData.Data.AuthorizationURL
+	}
 
 	slog.Debug("PAT auth check",
 		"clientId", patData.Data.ClientID,
@@ -416,7 +507,7 @@ func handlePatAuthCheck(
 		"hasSecret", patData.Data.ClientSecret != "",
 	)
 	hostOwnedPAT := authpkg.HostOwnsPATFlow()
-	openBrowser := currentPATOpenBrowser(configDir)
+	openBrowser := currentPATOpenBrowser(ctx, configDir)
 	slog.Debug("pat.host_owned_decision",
 		"site", "handlePatAuthCheck",
 		"hostOwned", hostOwnedPAT,
@@ -466,44 +557,40 @@ func handlePatAuthCheck(
 		return executor.Result{}, &apperrors.PATError{RawJSON: enrichPATErrorWithOpenBrowser(patErr.RawJSON, openBrowser)}
 	}
 
-	bold := color.New(color.Bold).SprintFunc()
-	cyan := color.New(color.FgCyan).SprintFunc()
-	greenFn := color.New(color.FgGreen).SprintFunc()
-	yellowFn := color.New(color.FgYellow).SprintFunc()
-	redFn := color.New(color.FgRed).SprintFunc()
-	dim := color.New(color.Faint).SprintFunc()
-
 	fmt.Fprintln(output)
-	fmt.Fprintf(output, "%s %s\n", greenFn("▶"), bold("需要 PAT 授权"))
+	fmt.Fprintf(output, "%s %s\n", tui.StateMark("warning"), tui.Bold("需要 PAT 授权"))
 	if patData.Data.Desc != "" {
-		fmt.Fprintf(output, "  %s %s\n", dim("ℹ"), patData.Data.Desc)
+		fmt.Fprintf(output, "  %s %s\n", tui.Dim("ℹ"), patData.Data.Desc)
 	}
 	if patData.Data.URI != "" {
 		authURL := apperrors.PATAuthorizationURL(patData.Data.URI)
-		fmt.Fprintf(output, "  %s 授权链接: %s\n", dim("🔗"), cyan(authURL))
-		fmt.Fprintf(output, "  PAT_AUTHORIZATION_URL=%s\n\n", authURL)
+		fmt.Fprintf(output, "  %s 授权链接: %s\n", tui.Dim("🔗"), authURL)
+		fmt.Fprintln(output)
 		if openBrowser {
 			_ = openPATAuthorizationURI(authURL)
 		}
 	}
 
 	// Poll the device flow status until user authorizes, rejects, or timeout.
-	fmt.Fprintf(output, "%s %s\n", yellowFn("⏳"), bold("等待用户授权..."))
-	fmt.Fprintf(output, "  %s 请在浏览器中完成授权，超时时间: %s\n", dim("ℹ"), patPollTimeout)
+	fmt.Fprintf(output, "%s %s\n", tui.StateMark("pending"), tui.Bold("等待用户授权..."))
+	fmt.Fprintf(output, "  %s 请在浏览器中完成授权，超时时间: %s\n", tui.Dim("ℹ"), patPollTimeout)
 	fmt.Fprintln(output)
 
 	pollCtx, cancel := context.WithTimeout(ctx, patPollTimeout)
 	defer cancel()
 
-	status, authCode, err := pollPatDeviceFlow(pollCtx, patData.Data.FlowID, configDir, output)
+	status, authCode, err := pollPatDeviceFlowWithInterval(
+		pollCtx, patData.Data.FlowID, configDir, output,
+		resolvePATPollInterval(patData.Data.PollIntervalSecs),
+	)
 	if err != nil {
-		fmt.Fprintf(output, "%s 轮询授权状态失败: %v\n", redFn("✗"), err)
+		fmt.Fprintf(output, "%s 轮询授权状态失败: %v\n", tui.StateMark("error"), err)
 		return executor.Result{}, patErr
 	}
 
 	switch status {
 	case authpkg.StatusApproved:
-		fmt.Fprintf(output, "%s %s\n", greenFn("✓"), bold("授权成功!"))
+		fmt.Fprintf(output, "%s %s\n", tui.StateMark("ok"), tui.Bold("授权成功!"))
 		fmt.Fprintln(output)
 
 		if appCfg != nil {
@@ -519,11 +606,11 @@ func handlePatAuthCheck(
 			tokenData, exchErr := authpkg.ExchangeCodeForToken(ctx, configDir, authCode)
 			if exchErr != nil {
 				slog.Warn("PAT retry: exchangeCode failed, retrying with existing token", "error", exchErr)
-				fmt.Fprintf(output, "  %s 换取新 token 失败: %v (将使用现有凭证重试)\n", yellowFn("⚠"), exchErr)
+				fmt.Fprintf(output, "  %s 换取新 token 失败: %v (将使用现有凭证重试)\n", tui.StateMark("warning"), exchErr)
 			} else {
 				if err := authpkg.SaveTokenData(configDir, tokenData); err != nil {
 					slog.Warn("PAT retry: failed to save new token", "error", err)
-					fmt.Fprintf(output, "  %s 保存新 token 失败: %v\n", yellowFn("⚠"), err)
+					fmt.Fprintf(output, "  %s 保存新 token 失败: %v\n", tui.StateMark("warning"), err)
 				} else {
 					slog.Debug("PAT retry: token refreshed and saved")
 				}
@@ -533,13 +620,23 @@ func handlePatAuthCheck(
 		// Clear token cache so the new credentials take effect.
 		ResetRuntimeTokenCache()
 
+		if shouldSkipPATRetryAfterApproval(invocation) {
+			invocation.Implemented = true
+			return executor.Result{
+				Invocation: invocation,
+				Response: map[string]any{
+					"ok": true,
+				},
+			}, nil
+		}
+
 		// Workaround: brief delay to let server-side authorization state propagate
 		// before retrying.  Without this the retry may use stale credentials.
 		slog.Debug("PAT retry: waiting for server-side state propagation", "delay", "1s")
 		time.Sleep(1 * time.Second)
 
 		// Retry the original invocation with pat-retrying flag to prevent recursion.
-		fmt.Fprintf(output, "%s %s\n", greenFn("▶"), bold("授权完成，正在重试..."))
+		fmt.Fprintf(output, "%s %s\n", tui.StateMark("ok"), tui.Bold("授权完成，正在重试..."))
 		fmt.Fprintln(output)
 		slog.Debug("PAT retry: identity env check",
 			"DWS_CLIENT_ID", os.Getenv("DWS_CLIENT_ID"),
@@ -548,7 +645,7 @@ func handlePatAuthCheck(
 		return r.Run(retryCtx, invocation)
 
 	case authpkg.StatusRejected:
-		fmt.Fprintf(output, "%s %s\n", redFn("✗"), bold("用户已拒绝授权"))
+		fmt.Fprintf(output, "%s %s\n", tui.StateMark("error"), tui.Bold("用户已拒绝授权"))
 		return executor.Result{}, apperrors.NewAuth(
 			"用户已拒绝授权",
 			apperrors.WithReason("pat_auth_rejected"),
@@ -556,7 +653,7 @@ func handlePatAuthCheck(
 		)
 
 	case authpkg.StatusExpired:
-		fmt.Fprintf(output, "%s %s\n", redFn("✗"), bold("授权超时"))
+		fmt.Fprintf(output, "%s %s\n", tui.StateMark("error"), tui.Bold("授权超时"))
 		return executor.Result{}, apperrors.NewAuth(
 			"授权超时",
 			apperrors.WithReason("pat_auth_expired"),
@@ -564,7 +661,7 @@ func handlePatAuthCheck(
 		)
 
 	case authpkg.StatusCancelled:
-		fmt.Fprintf(output, "%s %s\n", redFn("✗"), bold("操作已取消"))
+		fmt.Fprintf(output, "%s %s\n", tui.StateMark("error"), tui.Bold("操作已取消"))
 		return executor.Result{}, apperrors.NewAuth(
 			"操作已取消",
 			apperrors.WithReason("pat_auth_cancelled"),
@@ -572,11 +669,23 @@ func handlePatAuthCheck(
 		)
 
 	default:
-		fmt.Fprintf(output, "%s 未知授权状态: %s\n", redFn("✗"), status)
+		fmt.Fprintf(output, "%s 未知授权状态: %s\n", tui.StateMark("error"), status)
 		return executor.Result{}, patErr
 	}
 }
 
+func shouldSkipPATRetryAfterApproval(invocation executor.Invocation) bool {
+	if invocation.Params == nil {
+		return false
+	}
+	value, ok := invocation.Params["retryAfterApproval"]
+	if !ok {
+		return false
+	}
+	retry, ok := value.(bool)
+	return ok && !retry
+}
+
 func enrichPATErrorForHostControl(raw string) string {
 	if strings.TrimSpace(raw) == "" {
 		return raw
@@ -630,7 +739,7 @@ func buildPATScopeJSON(scopeErr *PatScopeError, includeHostControl bool) string
 		"data":    data,
 	}
 	// stderr JSON MUST be single-line.
-	b, err := json.Marshal(payload)
+	b, err := jsonutil.Marshal(payload)
 	if err != nil {
 		return `{"success":false,"code":"PAT_SCOPE_AUTH_REQUIRED"}`
 	}
@@ -655,6 +764,13 @@ func marshalSingleLineJSONNoHTMLEscape(v any) ([]byte, error) {
 // state (APPROVED/REJECTED/EXPIRED) is reached or the context is cancelled.
 // Returns the final status string and the authCode (non-empty only on APPROVED).
 func pollPatDeviceFlow(ctx context.Context, flowID string, configDir string, output io.Writer) (string, string, error) {
+	return pollPatDeviceFlowWithInterval(ctx, flowID, configDir, output, patPollInterval)
+}
+
+func pollPatDeviceFlowWithInterval(ctx context.Context, flowID string, configDir string, output io.Writer, interval time.Duration) (string, string, error) {
+	if interval <= 0 {
+		interval = patPollInterval
+	}
 	pollURL := fmt.Sprintf("%s%s?flowId=%s",
 		authpkg.GetMCPBaseURL(), authpkg.DevicePollPath, url.QueryEscape(flowID))
 
@@ -671,10 +787,9 @@ func pollPatDeviceFlow(ctx context.Context, flowID string, configDir string, out
 		},
 	}
 
-	ticker := time.NewTicker(patPollInterval)
+	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 
-	dim := color.New(color.Faint).SprintFunc()
 	pollCount := 0
 
 	for {
@@ -686,7 +801,7 @@ func pollPatDeviceFlow(ctx context.Context, flowID string, configDir string, out
 			return authpkg.StatusExpired, "", nil
 		case <-ticker.C:
 			pollCount++
-			fmt.Fprintf(output, "\r%s [%d] 等待授权中...          ", dim("⟳"), pollCount)
+			fmt.Fprintf(output, "\r%s [%d] 等待授权中...          ", tui.Dim("⟳"), pollCount)
 
 			req, err := http.NewRequestWithContext(ctx, http.MethodGet, pollURL, nil)
 			if err != nil {
@@ -738,6 +853,20 @@ func pollPatDeviceFlow(ctx context.Context, flowID string, configDir string, out
 	}
 }
 
+func resolvePATPollInterval(seconds int) time.Duration {
+	if seconds <= 0 {
+		return patPollInterval
+	}
+	interval := time.Duration(seconds) * time.Second
+	if interval < time.Second {
+		return time.Second
+	}
+	if interval > patMaxPollInterval {
+		return patMaxPollInterval
+	}
+	return interval
+}
+
 func browserOpenCommand(goos, rawURL string) *exec.Cmd {
 	switch goos {
 	case "darwin":

internal/app/pat_auth_retry_test.go

@@ -608,8 +608,14 @@ func TestEnrichPATErrorWithOpenBrowserKeepsAuthorizationURLAmpersandReadable(t *
 		t.Fatalf("json.Unmarshal(enriched PAT payload) error = %v\nraw=%s", err, out)
 	}
 	data, _ := payload["data"].(map[string]any)
-	if got, _ := data["authorizationUrl"].(string); got != rawURI {
-		t.Fatalf("data.authorizationUrl = %q, want %q", got, rawURI)
+	if got, _ := data["uri"].(string); got != rawURI {
+		t.Fatalf("data.uri = %q, want %q", got, rawURI)
+	}
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted from enriched PAT payload")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted from enriched PAT payload")
 	}
 }
 
@@ -656,6 +662,192 @@ func TestHandlePatAuthCheck_Approved(t *testing.T) {
 	}
 }
 
+func TestRunDirectPATAuthCheck_ApprovedRetriesCallback(t *testing.T) {
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	server, _ := setupHandlePATServer(t, "APPROVED", "")
+	defer server.Close()
+
+	patErr := &apperrors.PATError{RawJSON: makePATErrorJSONWithURI("flow-direct", "test-client-id", "https://example.com/pat")}
+	var retried atomic.Bool
+	var retryHadKey atomic.Bool
+	err := runDirectPATAuthCheck(context.Background(), &GlobalFlags{}, patErr, func(ctx context.Context) error {
+		retried.Store(true)
+		retryHadKey.Store(IsPatRetrying(ctx))
+		return nil
+	}, &bytes.Buffer{})
+	if err != nil {
+		t.Fatalf("runDirectPATAuthCheck error = %v", err)
+	}
+	if !retried.Load() {
+		t.Fatal("expected direct PAT auth retry callback to run")
+	}
+	if !retryHadKey.Load() {
+		t.Fatal("expected direct PAT auth retry context to be marked as PAT retrying")
+	}
+}
+
+func TestRunDirectPATAuthCheckWaitOnly_ApprovedDoesNotRetry(t *testing.T) {
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	server, _ := setupHandlePATServer(t, "APPROVED", "")
+	defer server.Close()
+
+	patErr := &apperrors.PATError{RawJSON: makePATErrorJSONWithURI("flow-direct", "test-client-id", "https://example.com/pat")}
+	var out bytes.Buffer
+	err := runDirectPATAuthCheckWaitOnly(context.Background(), &GlobalFlags{}, patErr, &out)
+	if err != nil {
+		t.Fatalf("runDirectPATAuthCheckWaitOnly error = %v", err)
+	}
+	if strings.Contains(out.String(), "授权完成，正在重试") {
+		t.Fatalf("wait-only auth must not print retry prompt, output:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "授权成功") {
+		t.Fatalf("wait-only auth should still report success, output:\n%s", out.String())
+	}
+}
+
+func TestRunDirectPATAuthCheckWaitOnly_SuppressesBrowserOpen(t *testing.T) {
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	server, configDir := setupHandlePATServer(t, "APPROVED", "")
+	defer server.Close()
+	if _, err := pat.SetBrowserPolicy(configDir, "", true); err != nil {
+		t.Fatalf("SetBrowserPolicy(default) error = %v", err)
+	}
+
+	var opened bool
+	origOpenBrowser := openBrowserFunc
+	openBrowserFunc = func(rawURL string) error {
+		opened = true
+		return nil
+	}
+	t.Cleanup(func() { openBrowserFunc = origOpenBrowser })
+
+	patErr := &apperrors.PATError{RawJSON: makePATErrorJSONWithURI("flow-direct", "test-client-id", "https://example.com/pat")}
+	var out bytes.Buffer
+	err := runDirectPATAuthCheckWaitOnly(context.Background(), &GlobalFlags{}, patErr, &out)
+	if err != nil {
+		t.Fatalf("runDirectPATAuthCheckWaitOnly error = %v", err)
+	}
+	if opened {
+		t.Fatal("wait-only auth must not open a second browser tab")
+	}
+	if !strings.Contains(out.String(), "授权链接:") {
+		t.Fatalf("wait-only auth should still print the authorization URL, output:\n%s", out.String())
+	}
+}
+
+func TestResolvePATPollInterval(t *testing.T) {
+	tests := []struct {
+		name    string
+		seconds int
+		want    time.Duration
+	}{
+		{name: "default", seconds: 0, want: patPollInterval},
+		{name: "server value", seconds: 3, want: 3 * time.Second},
+		{name: "cap excessive value", seconds: 90, want: patMaxPollInterval},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := resolvePATPollInterval(tt.seconds); got != tt.want {
+				t.Fatalf("resolvePATPollInterval(%d) = %s, want %s", tt.seconds, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRunDirectPATAuthCheck_JSONModeReturnsStructuredPending(t *testing.T) {
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	if _, err := pat.SetBrowserPolicy(configDir, "", false); err != nil {
+		t.Fatalf("SetBrowserPolicy(default) error = %v", err)
+	}
+
+	rawURI := "https://example.com/personalAuthorization?flowId=flow-json&userCode=ABCD-EFGH"
+	raw := `{"success":false,"code":"PAT_BATCH_AUTH_PENDING","data":{"flowId":"flow-json","uri":"` + rawURI + `","authUrl":"` + rawURI + `","clientId":"test-client-id"}}`
+	err := runDirectPATAuthCheck(context.Background(), &GlobalFlags{Format: "json"},
+		&apperrors.PATError{RawJSON: raw},
+		func(ctx context.Context) error {
+			t.Fatal("retry callback should not run in structured PAT output mode")
+			return nil
+		},
+		&bytes.Buffer{},
+	)
+	if err == nil {
+		t.Fatal("expected structured PATError")
+	}
+	patOut, ok := err.(*apperrors.PATError)
+	if !ok {
+		t.Fatalf("expected *PATError, got %T: %v", err, err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(patOut.RawJSON), &payload); err != nil {
+		t.Fatalf("json.Unmarshal(PAT payload) error = %v\nraw=%s", err, patOut.RawJSON)
+	}
+	if got, _ := payload["code"].(string); got != "PAT_BATCH_AUTH_PENDING" {
+		t.Fatalf("code = %q, want PAT_BATCH_AUTH_PENDING", got)
+	}
+	data, _ := payload["data"].(map[string]any)
+	if got, _ := data["uri"].(string); got != rawURI {
+		t.Fatalf("data.uri = %q, want %q", got, rawURI)
+	}
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted from structured PAT output")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted from structured PAT output")
+	}
+	if got, ok := data["openBrowser"].(bool); !ok || got {
+		t.Fatalf("data.openBrowser = %#v, want false", data["openBrowser"])
+	}
+}
+
+func TestRunDirectPATAuthCheck_JSONModeBackfillsSingleURIFromAuthURL(t *testing.T) {
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	if _, err := pat.SetBrowserPolicy(configDir, "", false); err != nil {
+		t.Fatalf("SetBrowserPolicy(default) error = %v", err)
+	}
+
+	rawURL := "https://open-dev.dingtalk.com/fe/old#%2FpersonalAuthorization%3FflowId%3Dflow-json%26userCode%3DABCD-EFGH"
+	wantURL := "https://open-dev.dingtalk.com/fe/old?hash=%23%2FpersonalAuthorization%3FflowId%3Dflow-json%26userCode%3DABCD-EFGH#/personalAuthorization?flowId=flow-json&userCode=ABCD-EFGH"
+	raw := `{"success":false,"code":"PAT_BATCH_AUTH_PENDING","data":{"flowId":"flow-json","authUrl":"` + rawURL + `","clientId":"test-client-id"}}`
+	err := runDirectPATAuthCheck(context.Background(), &GlobalFlags{Format: "json"},
+		&apperrors.PATError{RawJSON: raw},
+		func(ctx context.Context) error {
+			t.Fatal("retry callback should not run in structured PAT output mode")
+			return nil
+		},
+		&bytes.Buffer{},
+	)
+	if err == nil {
+		t.Fatal("expected structured PATError")
+	}
+	patOut, ok := err.(*apperrors.PATError)
+	if !ok {
+		t.Fatalf("expected *PATError, got %T: %v", err, err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(patOut.RawJSON), &payload); err != nil {
+		t.Fatalf("json.Unmarshal(PAT payload) error = %v\nraw=%s", err, patOut.RawJSON)
+	}
+	if strings.Contains(patOut.RawJSON, `\u0026`) {
+		t.Fatalf("PAT output escaped URL separators: %s", patOut.RawJSON)
+	}
+	data, _ := payload["data"].(map[string]any)
+	if got, _ := data["uri"].(string); got != wantURL {
+		t.Fatalf("data.uri = %q, want %q", got, wantURL)
+	}
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted after backfilling data.uri")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted after backfilling data.uri")
+	}
+}
+
 func TestHandlePatAuthCheck_Rejected(t *testing.T) {
 	t.Setenv(authpkg.AgentCodeEnv, "")
 	server, configDir := setupHandlePATServer(t, "REJECTED", "")
@@ -951,6 +1143,12 @@ func TestHandlePatAuthCheck_JSONModeCanOpenBrowserWithoutTextOutput(t *testing.T
 	if !ok {
 		t.Fatalf("expected *PATError, got %T: %v", err, err)
 	}
+	if strings.Contains(patOut.RawJSON, `\u0026`) {
+		t.Fatalf("PATError RawJSON escaped ampersands in authorization URL: %s", patOut.RawJSON)
+	}
+	if !strings.Contains(patOut.RawJSON, "&userCode=98JV-JSBL") {
+		t.Fatalf("PATError RawJSON missing literal ampersand route separator: %s", patOut.RawJSON)
+	}
 	var payload map[string]any
 	if err := json.Unmarshal([]byte(patOut.RawJSON), &payload); err != nil {
 		t.Fatalf("json.Unmarshal(json PAT payload) error = %v\nraw=%s", err, patOut.RawJSON)
@@ -959,8 +1157,11 @@ func TestHandlePatAuthCheck_JSONModeCanOpenBrowserWithoutTextOutput(t *testing.T
 	if got, _ := data["uri"].(string); got != rawURI {
 		t.Fatalf("data.uri = %q, want verbatim %q", got, rawURI)
 	}
-	if got, _ := data["authorizationUrl"].(string); got != rawURI {
-		t.Fatalf("data.authorizationUrl = %q, want %q", got, rawURI)
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted from json PAT output")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted from json PAT output")
 	}
 	if got, ok := data["openBrowser"].(bool); !ok || !got {
 		t.Fatalf("data.openBrowser = %#v, want true", data["openBrowser"])
@@ -995,7 +1196,7 @@ func TestHandlePatAuthCheck_NonJSONModeRespectsBrowserPolicy(t *testing.T) {
 		fallback:    mock,
 		globalFlags: &GlobalFlags{Format: "table"},
 	}
-	raw := `{"code":"AGENT_CODE_NOT_EXISTS","data":{"desc":"test auth","flowId":"flow-approved","uri":"https://example.com/pat","clientId":"test-client-id"}}`
+	raw := `{"code":"AGENT_CODE_NOT_EXISTS","data":{"desc":"test auth","flowId":"flow-approved","authorizationUrl":"https://example.com/pat","clientId":"test-client-id"}}`
 
 	var buf bytes.Buffer
 	_, err := handlePatAuthCheck(context.Background(), runner, executor.Invocation{
@@ -1015,6 +1216,12 @@ func TestHandlePatAuthCheck_NonJSONModeRespectsBrowserPolicy(t *testing.T) {
 	if !strings.Contains(buf.String(), "需要 PAT 授权") {
 		t.Fatalf("expected human-readable PAT output, got %q", buf.String())
 	}
+	if !strings.Contains(buf.String(), "授权链接: https://example.com/pat") {
+		t.Fatalf("expected authorization URL in human-readable PAT output, got %q", buf.String())
+	}
+	if strings.Contains(buf.String(), "PAT_AUTHORIZATION_URL=") {
+		t.Fatalf("human-readable PAT output should not emit a second machine-readable URL line, got %q", buf.String())
+	}
 }
 
 func TestRetryWithPatAuthRetry_JSONModeReturnsStructuredPATError(t *testing.T) {
@@ -1246,8 +1453,8 @@ func TestHandlePatAuthCheck_OpensOpaqueURIWithoutRebuild(t *testing.T) {
 	if opened != rawURI {
 		t.Fatalf("opened url = %q, want verbatim %q", opened, rawURI)
 	}
-	if got := buf.String(); !strings.Contains(got, "PAT_AUTHORIZATION_URL="+rawURI) {
-		t.Fatalf("output missing copy-safe PAT_AUTHORIZATION_URL line:\n%s", got)
+	if got := buf.String(); strings.Contains(got, "PAT_AUTHORIZATION_URL=") {
+		t.Fatalf("human-readable PAT output should not emit PAT_AUTHORIZATION_URL line:\n%s", got)
 	}
 }
 
@@ -1292,8 +1499,8 @@ func TestHandlePatAuthCheck_NormalizesLegacyHashRouteForBrowserAndOutput(t *test
 	if opened != wantURL {
 		t.Fatalf("opened url = %q, want normalized %q", opened, wantURL)
 	}
-	if got := buf.String(); !strings.Contains(got, "PAT_AUTHORIZATION_URL="+wantURL) {
-		t.Fatalf("output missing normalized PAT_AUTHORIZATION_URL line:\n%s", got)
+	if got := buf.String(); strings.Contains(got, "PAT_AUTHORIZATION_URL=") {
+		t.Fatalf("human-readable PAT output should not emit PAT_AUTHORIZATION_URL line:\n%s", got)
 	}
 }
 

internal/app/root.go

@@ -96,6 +96,7 @@ func Execute() (exitCode int) {
 		if executed == nil {
 			executed = root
 		}
+		err = rewordRequiredFlagError(err)
 		if isUnknownCommandError(err) {
 			executed.SetOut(os.Stderr)
 			_ = executed.Help()
@@ -114,6 +115,36 @@ func isUnknownCommandError(err error) bool {
 	return err != nil && strings.Contains(err.Error(), "unknown command")
 }
 
+// rewordRequiredFlagError rewrites cobra's default missing-required-flag message
+// (`required flag(s) "email" not set`) into the wukong-aligned form
+// (`missing required flag(s): --email`). cobra's ValidateRequiredFlags returns
+// this error directly (it does not pass through FlagErrorFunc), so it is
+// normalised here. The substring "required flag" is preserved for compatibility
+// with existing assertions; flag names gain the "--" prefix and quotes are
+// dropped so error output matches hardcoded cmdutil.ValidateRequiredFlags.
+func rewordRequiredFlagError(err error) error {
+	if err == nil {
+		return err
+	}
+	const pfx = "required flag(s) "
+	const sfx = " not set"
+	msg := err.Error()
+	if !strings.HasPrefix(msg, pfx) || !strings.HasSuffix(msg, sfx) {
+		return err
+	}
+	mid := strings.TrimSuffix(strings.TrimPrefix(msg, pfx), sfx)
+	var flags []string
+	for _, part := range strings.Split(mid, ", ") {
+		if name := strings.Trim(strings.TrimSpace(part), "\""); name != "" {
+			flags = append(flags, "--"+name)
+		}
+	}
+	if len(flags) == 0 {
+		return err
+	}
+	return apperrors.NewValidation(fmt.Sprintf("missing required flag(s): %s", strings.Join(flags, ", ")))
+}
+
 // flagErrorWithSuggestions provides helpful suggestions for common flag mistakes.
 //
 // 所有 flag 解析错误都会在 message 末尾追加 "See '<CommandPath> --help' for usage."，
@@ -323,12 +354,14 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 	genSkillsCmd.Hidden = true
 	mcpCmd := newMCPCommand(rootCtx, loader, runner, engine)
 	mcpCmd.Hidden = true
+	patCaller := newToolCallerAdapter(runner, flags)
 
 	utilityCommands := []*cobra.Command{
-		newAuthCommand(),
+		newAuthCommand(patCaller),
 		newAPICommand(flags),
 		newSkillCommand(),
 		newCacheCommand(),
+		newCatalogCommand(loader),
 		newConfigCommand(),
 		newDoctorCommand(),
 		newCompletionCommand(root),
@@ -354,7 +387,6 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 	}
 
 	// PAT authorization commands (open-source core)
-	patCaller := newToolCallerAdapter(runner, flags)
 	pat.RegisterCommands(root, patCaller)
 
 	if fn := edition.Get().RegisterExtraCommands; fn != nil {
@@ -372,8 +404,8 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 	return root
 }
 
-func newAuthCommand() *cobra.Command {
-	return buildAuthCommand()
+func newAuthCommand(patCaller edition.ToolCaller) *cobra.Command {
+	return buildAuthCommand(patCaller)
 }
 
 func newSkillCommand() *cobra.Command {
@@ -474,7 +506,7 @@ func newCacheCommand() *cobra.Command {
 			if err != nil {
 				return apperrors.NewDiscovery(fmt.Sprintf("cache refresh: fetch server list failed: %v", err))
 			}
-			servers := market.NormalizeServers(resp, "live_market")
+			servers := market.NormalizeServersForBaseURL(resp, "live_market", registryDiscoveryBaseURL())
 			_ = store.SaveRegistry(service.CachePartition(), cache.RegistrySnapshot{Servers: servers})
 
 			selected := selectServersForProduct(servers, product)
@@ -596,7 +628,7 @@ func newVersionCommand() *cobra.Command {
 }
 
 func newSchemaCommand(loader cli.CatalogLoader) *cobra.Command {
-	return cli.NewSchemaCommand(loader)
+	return cli.NewSchemaCommand(loader, newHelperToolFetcher())
 }
 
 func newGenerateSkillsCommand() *cobra.Command {

internal/app/root_cache_refresh_test.go

@@ -24,7 +24,7 @@ func TestCacheRefreshClearsExistingCachesAndSkipsCLISkippedServers(t *testing.T)
 	var srv *httptest.Server
 	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
-		case "/cli/discovery/apis/bamboo":
+		case "/cli/discovery/apis/cedar":
 			_ = json.NewEncoder(w).Encode(market.ListResponse{
 				Metadata: market.ListMetadata{Count: 2},
 				Servers: []market.ServerEnvelope{
@@ -146,7 +146,7 @@ func TestCacheRefreshHonorsEditionDiscoveryURL(t *testing.T) {
 					},
 				},
 			})
-		case "/cli/discovery/apis/bamboo":
+		case "/cli/discovery/apis/cedar":
 			marketHits.Add(1)
 			http.Error(w, "market endpoint must not be called when edition DiscoveryURL is set", http.StatusNotFound)
 		default:

internal/app/root_help.go

@@ -6,6 +6,7 @@ import (
 	"text/tabwriter"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/i18n"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -50,38 +51,42 @@ func renderRootHelp(root *cobra.Command) {
 	utilities := visibleUtilityRootCommands(root)
 	w := root.OutOrStdout()
 
+	_, _ = fmt.Fprintln(w, tui.Header("Workspace CLI", "DingTalk blue-white technical console"))
+	_, _ = fmt.Fprintln(w, tui.Rule(76))
+	_, _ = fmt.Fprintln(w)
+
 	if len(services) == 0 {
-		_, _ = fmt.Fprintln(w, "No MCP services discovered.")
+		_, _ = fmt.Fprintf(w, "%s %s\n", tui.StateMark("warning"), tui.Warning("No MCP services discovered."))
 		_, _ = fmt.Fprintln(w)
 	} else {
-		_, _ = fmt.Fprintln(w, "Discovered MCP Services:")
+		_, _ = fmt.Fprintln(w, tui.Section("Discovered MCP Services:"))
 		_, _ = fmt.Fprintln(w)
 
 		tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
 		for _, service := range services {
-			_, _ = fmt.Fprintf(tw, "  %s\t%s\n", service.Name(), strings.TrimSpace(service.Short))
+			_, _ = fmt.Fprintf(tw, "  %s %s\t%s\n", tui.StateMark("ok"), tui.Bold(service.Name()), tui.Dim(strings.TrimSpace(service.Short)))
 		}
 		_ = tw.Flush()
 		_, _ = fmt.Fprintln(w)
 	}
 
-	_, _ = fmt.Fprintln(w, "Usage:")
-	_, _ = fmt.Fprintln(w, "  dws <service> [command] [flags]")
+	_, _ = fmt.Fprintln(w, tui.Section("Usage:"))
+	_, _ = fmt.Fprintf(w, "  %s %s\n", tui.Bullet(), tui.White("dws <service> [command] [flags]"))
 	if len(utilities) > 0 {
-		_, _ = fmt.Fprintln(w, "  dws <command> [flags]")
+		_, _ = fmt.Fprintf(w, "  %s %s\n", tui.Bullet(), tui.White("dws <command> [flags]"))
 	}
 	_, _ = fmt.Fprintln(w)
 	if len(utilities) > 0 {
-		_, _ = fmt.Fprintln(w, "Utility Commands:")
+		_, _ = fmt.Fprintln(w, tui.Section("Utility Commands:"))
 		_, _ = fmt.Fprintln(w)
 		tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
 		for _, utility := range utilities {
-			_, _ = fmt.Fprintf(tw, "  %s\t%s\n", utility.Name(), strings.TrimSpace(utility.Short))
+			_, _ = fmt.Fprintf(tw, "  %s %s\t%s\n", tui.Bullet(), tui.Bold(utility.Name()), tui.Dim(commandShort(utility)))
 		}
 		_ = tw.Flush()
 		_, _ = fmt.Fprintln(w)
 	}
-	_, _ = fmt.Fprintln(w, `Use "dws <service> --help" for more information about a discovered MCP service or "dws <command> --help" for utility commands.`)
+	_, _ = fmt.Fprintf(w, "%s %s\n", tui.Key("Next"), `Use "dws <service> --help" for more information about a discovered MCP service or "dws <command> --help" for utility commands.`)
 
 	// Render root.Long after the command list so agents see the upgrade
 	// hint (or any other root-level guidance) after browsing all available
@@ -90,10 +95,21 @@ func renderRootHelp(root *cobra.Command) {
 	// it and dropped this, so we restore it explicitly here.
 	if long := strings.TrimSpace(root.Long); long != "" {
 		_, _ = fmt.Fprintln(w)
-		_, _ = fmt.Fprintln(w, long)
+		_, _ = fmt.Fprintln(w, tui.Dim(long))
 	}
 }
 
+func commandShort(cmd *cobra.Command) string {
+	if cmd == nil {
+		return ""
+	}
+	short := strings.TrimSpace(cmd.Short)
+	if cmd.Name() == "help" && short == "Help about any command" {
+		return i18n.T("查看任意命令的帮助信息")
+	}
+	return short
+}
+
 // resolveVisibleProducts returns the set of top-level product IDs that should
 // be treated as visible. It unions the edition's VisibleProducts hook (when
 // set) with DirectRuntimeProductIDs(), so dynamically-registered products —

internal/app/runner.go

@@ -17,6 +17,7 @@ import (
 	"context"
 	"crypto/rand"
 	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -259,13 +260,22 @@ func (r *runtimeRunner) handleCatalogMiss(ctx context.Context, invocation execut
 		invocation.DryRun = true
 		return r.fallback.Run(ctx, invocation)
 	}
+	hint := "产品 envelope 可能未下发到 discovery，或已经被 serverDeps fail-fast 丢弃；可执行 'dws cache refresh' 强制重新 discovery，仍失败请向 Portal 确认 envelope 状态。"
+	actions := []string{"dws cache refresh"}
+	if strings.TrimSpace(invocation.CanonicalProduct) == devappProductID {
+		hint = "dev app（product id: devapp）是 helper-only 产品，命令树不依赖 discovery；真实调用需要内部版通过 SupplementServers/StaticServers 注入 MCP endpoint，或本地调试临时设置 DINGTALK_DEVAPP_MCP_URL。"
+		actions = []string{
+			"检查内部版 SupplementServers/StaticServers 是否包含 devapp endpoint",
+			"本地调试可临时设置 DINGTALK_DEVAPP_MCP_URL 后重试",
+		}
+	}
 	return executor.Result{}, apperrors.NewAPI(
 		fmt.Sprintf("endpoint not resolved for product %q (tool %q): %s", invocation.CanonicalProduct, invocation.Tool, detail),
 		apperrors.WithOperation("discovery.resolve"),
 		apperrors.WithReason("endpoint_not_resolved"),
 		apperrors.WithServerKey(invocation.CanonicalProduct),
-		apperrors.WithHint("产品 envelope 可能未下发到 discovery，或已经被 serverDeps fail-fast 丢弃；可执行 'dws cache refresh' 强制重新 discovery，仍失败请向 Portal 确认 envelope 状态。"),
-		apperrors.WithActions("dws cache refresh"),
+		apperrors.WithHint(hint),
+		apperrors.WithActions(actions...),
 	)
 }
 
@@ -324,6 +334,14 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 		invocation.CanonicalProduct, invocation.Tool, endpoint, version, authToken != "", timeoutSec)
 
 	if invocation.DryRun {
+		// Emit a wukong-aligned human-readable preview on stderr so the dry-run
+		// surface advertises the resolved MCP arguments without polluting the
+		// stdout payload (which stays valid JSON in --format json mode). Mirrors
+		// wukong's "Arguments: {...}" dry-run line; stderr keeps it out of the
+		// machine-readable channel.
+		if argsJSON, err := json.Marshal(invocation.Params); err == nil {
+			fmt.Fprintf(os.Stderr, "DRY-RUN Arguments: %s\n", argsJSON)
+		}
 		return executor.Result{
 			Invocation: invocation,
 			Response: map[string]any{
@@ -483,6 +501,15 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 	}
 
 	invocation.Implemented = true
+	// Align with wukong's response envelope: stamp a top-level success=true on
+	// map payloads that don't already carry a success flag. Business errors
+	// (success=false) are intercepted above, so reaching here means the call
+	// succeeded. Additive only — existing keys are never overwritten.
+	if callResult.Content != nil {
+		if _, has := callResult.Content["success"]; !has {
+			callResult.Content["success"] = true
+		}
+	}
 	response := map[string]any{
 		"endpoint": transport.RedactURL(endpoint),
 		"content":  callResult.Content,
@@ -708,7 +735,6 @@ func resolveIdentityHeaders() map[string]string {
 	if version != "" {
 		headers[transport.HeaderVersion] = version
 	}
-
 	envHeaders := map[string]string{
 		"x-dingtalk-agent":          os.Getenv(envDingtalkAgent),
 		"x-dingtalk-dws-agent-code": agentCode,
@@ -738,13 +764,23 @@ func resolveIdentityHeaders() map[string]string {
 // errors (success=false + errorCode/errorMsg) that are not flagged at the MCP
 // protocol level. Returns the error message, or "" if the response is OK.
 func detectBusinessError(content map[string]any) string {
+	return detectBusinessErrorAtDepth(content, 0)
+}
+
+func detectBusinessErrorAtDepth(content map[string]any, depth int) string {
+	if content == nil || depth > 8 {
+		return ""
+	}
 	success, ok := content["success"]
 	if !ok {
-		return ""
+		return detectNestedBusinessError(content, depth)
 	}
 	b, ok := success.(bool)
 	if !ok || b {
-		return ""
+		return detectNestedBusinessError(content, depth)
+	}
+	if nested := detectNestedBusinessError(content, depth); nested != "" {
+		return nested
 	}
 	if msg, ok := content["errorMsg"].(string); ok && strings.TrimSpace(msg) != "" {
 		return strings.TrimSpace(msg)
@@ -755,6 +791,28 @@ func detectBusinessError(content map[string]any) string {
 	return "business error: success=false"
 }
 
+func detectNestedBusinessError(content map[string]any, depth int) string {
+	for _, key := range []string{"content", "result", "data"} {
+		switch child := content[key].(type) {
+		case map[string]any:
+			if msg := detectBusinessErrorAtDepth(child, depth+1); msg != "" {
+				return msg
+			}
+		case []any:
+			for _, item := range child {
+				childMap, ok := item.(map[string]any)
+				if !ok {
+					continue
+				}
+				if msg := detectBusinessErrorAtDepth(childMap, depth+1); msg != "" {
+					return msg
+				}
+			}
+		}
+	}
+	return ""
+}
+
 // extractMCPErrorMessage builds an error message from a ToolCallResult with
 // isError=true. It extracts text from content blocks when available.
 func extractMCPErrorMessage(result transport.ToolCallResult) string {

internal/app/runner_test.go

@@ -321,6 +321,7 @@ func TestRuntimeRunnerInjectsAuthTokenFromFlag(t *testing.T) {
 func TestResolveIdentityHeadersForwardsAgentCode(t *testing.T) {
 	setupRuntimeCommandTest(t)
 	t.Setenv(authpkg.AgentCodeEnv, " cursor ")
+	t.Setenv(authpkg.AgentCodeEnvCompat, "")
 
 	headers := resolveIdentityHeaders()
 	if got := headers["x-dingtalk-dws-agent-code"]; got != "cursor" {
@@ -943,6 +944,20 @@ func jsonRPCToolName(req map[string]any) string {
 	return name
 }
 
+func TestDetectBusinessErrorNestedServiceResult(t *testing.T) {
+	content := map[string]any{
+		"success": false,
+		"result": map[string]any{
+			"success":   false,
+			"errorCode": "ROBOT_NOT_FOUND",
+			"errorMsg":  "robot info is not exist",
+		},
+	}
+	if got := detectBusinessError(content); got != "robot info is not exist" {
+		t.Fatalf("detectBusinessError() = %q, want nested errorMsg", got)
+	}
+}
+
 func writeJSONRPCToolResult(t *testing.T, w http.ResponseWriter, req map[string]any, content map[string]any, isError bool) {
 	t.Helper()
 	_ = json.NewEncoder(w).Encode(map[string]any{

internal/app/skill_command.go

@@ -95,12 +95,13 @@ var agentSkillPaths = map[string]string{
 	// `agents` is the generic-agent sentinel: install scripts and `setup`
 	// special-case ~/.agents/skills as a no-checks-required fallback so a
 	// fresh machine without any IDE/agent registry still gets skills.
-	"agents":   ".agents/skills",
-	"qoder":    ".qoder/skills",
-	"claude":   ".claude/skills",
-	"cursor":   ".cursor/skills",
-	"codex":    ".codex/skills",
-	"opencode": filepath.Join(".config", "opencode", "skills"),
+	"agents":    ".agents/skills",
+	"qoder":     ".qoder/skills",
+	"qoderwork": ".qoderwork/skills",
+	"claude":    ".claude/skills",
+	"cursor":    ".cursor/skills",
+	"codex":     ".codex/skills",
+	"opencode":  filepath.Join(".config", "opencode", "skills"),
 	// IDE / agent registries also probed by `dws skill setup --target all`.
 	"gemini":   ".gemini/skills",
 	"github":   ".github/skills",

internal/app/skill_setup.go

@@ -21,6 +21,8 @@ var skillSetupAgentHomes = []string{
 	".agents/skills",
 	".claude/skills",
 	".cursor/skills",
+	".qoder/skills",
+	".qoderwork/skills",
 	".gemini/skills",
 	".codex/skills",
 	".github/skills",
@@ -56,7 +58,8 @@ multi 模式支持按产品挑选：
   -x/--exclude 从全装里剔除指定子 skill（可重复，与 --skill 互斥）
   未列出的已有 dingtalk-* skill 会保留（additive 叠加语义）
 
-不带 --mode 时进入交互式询问；不带 --target 时铺到所有检测到的 Agent 目录。`,
+不带 --mode 时进入交互式询问；不带 --target 时铺到所有检测到的 Agent 目录。
+skill 源默认取二进制内嵌的版本（升级二进制即升级 skill）；--source / DWS_SKILL_SOURCE 可显式覆盖。`,
 		Example: `  dws skill setup                                       # 交互式
   dws skill setup --mode mono --yes                     # 非交互装 mono
   dws skill setup --mode multi --target claude          # multi 全装到 ~/.claude/skills/
@@ -68,7 +71,7 @@ multi 模式支持按产品挑选：
 	}
 	cmd.Flags().String("mode", "", "skill 模式：mono | multi（不指定则交互询问）")
 	cmd.Flags().String("target", "all", "目标 Agent：all | "+supportedTargets())
-	cmd.Flags().String("source", "", "skill 源目录（默认自动查找二进制旁边或当前目录）")
+	cmd.Flags().String("source", "", "skill 源目录（默认使用二进制内嵌的 skill 源，与当前版本一致）")
 	cmd.Flags().Bool("yes", false, "跳过所有确认提示")
 	cmd.Flags().StringSliceP("skill", "s", nil, "multi 模式：仅安装指定子 skill（可重复，接受短名 aitable 或全名 dingtalk-aitable）")
 	cmd.Flags().StringSliceP("exclude", "x", nil, "multi 模式：从全装中剔除指定子 skill（可重复，与 --skill 互斥）")
@@ -95,10 +98,11 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 		return fmt.Errorf("--skill / --exclude 仅在 --mode multi 下有效（mono 只有一个 skill，无需挑选）")
 	}
 
-	skillSrc, err := resolveSkillSetupSource(source, mode)
+	skillSrc, srcCleanup, err := resolveSkillSetupSourceOrEmbedded(source, mode)
 	if err != nil {
 		return err
 	}
+	defer srcCleanup()
 
 	dests, err := resolveSkillSetupTargets(target, mode)
 	if err != nil {
@@ -313,7 +317,31 @@ func resolveSkillSetupMode(mode string, autoYes bool, out io.Writer) (string, er
 func resolveSkillSetupSource(explicit, mode string) (string, error) {
 	subdir := mode // "mono" or "multi"
 
-	candidates := skillSourceCandidates(explicit, subdir)
+	// An explicit override (--source flag or DWS_SKILL_SOURCE) wins, and an
+	// override that does not contain a skill root is an error — never a
+	// silent fallback to another source the user did not ask for.
+	var overrides []string
+	if explicit != "" {
+		overrides = append(overrides, explicit, filepath.Join(explicit, "skills", subdir))
+	}
+	if env := strings.TrimSpace(os.Getenv("DWS_SKILL_SOURCE")); env != "" {
+		overrides = append(overrides, env, filepath.Join(env, "skills", subdir))
+	}
+	if len(overrides) > 0 {
+		for _, c := range overrides {
+			if isSkillSourceRoot(c, mode) {
+				return c, nil
+			}
+		}
+		hint := strings.Join(overrides, "\n  - ")
+		return "", fmt.Errorf("未找到 %s 模式的 skill 源目录（--source / DWS_SKILL_SOURCE 显式指定时不回退到内嵌源），已尝试：\n  - %s", mode, hint)
+	}
+
+	// No explicit override: legacy fallback only — embedded materialization
+	// is handled by resolveSkillSetupSourceOrEmbedded (skill_setup_embed.go),
+	// the wrapper that callers use. This branch is reachable only when the
+	// wrapper passes through with an empty explicit/env (legacy direct call).
+	candidates := skillSourceCandidates("", subdir)
 	for _, c := range candidates {
 		if isSkillSourceRoot(c, mode) {
 			return c, nil
@@ -639,7 +667,14 @@ func copyFileContent(src, dst string, mode os.FileMode) error {
 }
 
 func isInteractiveTerminal() bool {
-	fi, err := os.Stdin.Stat()
+	return isCharDevice(os.Stdin) && isCharDevice(os.Stdout) && isCharDevice(os.Stderr)
+}
+
+func isCharDevice(file *os.File) bool {
+	if file == nil {
+		return false
+	}
+	fi, err := file.Stat()
 	if err != nil {
 		return false
 	}

internal/app/skill_setup_embed.go

@@ -0,0 +1,86 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+
+	dwsroot "github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+)
+
+// resolveSkillSetupSourceOrEmbedded resolves the skill source for `skill
+// setup`. An explicit --source or DWS_SKILL_SOURCE is honored as a developer
+// override (validated as an on-disk dir). Otherwise it falls back to the skill
+// bundle embedded in THIS binary, so a plain `dws skill setup` always installs
+// the version shipped with the running binary — upgrading the binary therefore
+// refreshes the installed skill, instead of silently reusing a stale copy from
+// the current working directory.
+//
+// The returned cleanup func removes any temp dir created for the embedded
+// bundle; it is a no-op when an on-disk source is used. Always call it.
+func resolveSkillSetupSourceOrEmbedded(explicit, mode string) (string, func(), error) {
+	noop := func() {}
+	explicit = strings.TrimSpace(explicit)
+	env := strings.TrimSpace(os.Getenv("DWS_SKILL_SOURCE"))
+	if explicit != "" || env != "" {
+		dir, err := resolveSkillSetupSource(explicit, mode)
+		return dir, noop, err
+	}
+	return materializeEmbeddedSkillSource(mode)
+}
+
+// materializeEmbeddedSkillSource extracts the embedded skills/<mode> subtree
+// into a fresh temp dir and returns its path plus a cleanup func. Reusing a
+// real directory lets the existing dir-based install/copy logic stay unchanged.
+func materializeEmbeddedSkillSource(mode string) (string, func(), error) {
+	noop := func() {}
+	sub := "skills/" + mode // embed.FS always uses forward slashes
+	if _, err := fs.Stat(dwsroot.EmbeddedSkills, sub); err != nil {
+		return "", noop, fmt.Errorf("内嵌 skill 不含 %q（二进制可能未随 skills/ 重新构建）: %w", sub, err)
+	}
+
+	tmp, err := os.MkdirTemp("", "dws-skill-"+mode+"-")
+	if err != nil {
+		return "", noop, fmt.Errorf("创建临时 skill 目录失败: %w", err)
+	}
+	cleanup := func() { _ = os.RemoveAll(tmp) }
+
+	walkErr := fs.WalkDir(dwsroot.EmbeddedSkills, sub, func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel := strings.TrimPrefix(strings.TrimPrefix(p, sub), "/")
+		dst := filepath.Join(tmp, filepath.FromSlash(rel))
+		if d.IsDir() {
+			return os.MkdirAll(dst, 0o755)
+		}
+		data, readErr := dwsroot.EmbeddedSkills.ReadFile(p)
+		if readErr != nil {
+			return readErr
+		}
+		if mkErr := os.MkdirAll(filepath.Dir(dst), 0o755); mkErr != nil {
+			return mkErr
+		}
+		return os.WriteFile(dst, data, 0o644)
+	})
+	if walkErr != nil {
+		cleanup()
+		return "", noop, fmt.Errorf("展开内嵌 skill 到临时目录失败: %w", walkErr)
+	}
+	return tmp, cleanup, nil
+}

internal/app/skill_setup_embed_test.go

@@ -0,0 +1,68 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestMaterializeEmbeddedSkillSourceMono verifies that the mono skill bundle
+// baked into the binary can be extracted to a temp dir and is a valid skill
+// source root (so `dws skill setup` works with zero local checkout). The
+// nested-reference and _common checks guard against the embed dropping nested
+// docs or the `all:` prefix being lost (which would silently skip
+// dot/underscore dirs).
+func TestMaterializeEmbeddedSkillSourceMono(t *testing.T) {
+	dir, cleanup, err := materializeEmbeddedSkillSource(skillSetupModeMono)
+	if err != nil {
+		t.Fatalf("materializeEmbeddedSkillSource: %v", err)
+	}
+	defer cleanup()
+
+	if !isSkillSourceRoot(dir, skillSetupModeMono) {
+		t.Fatalf("extracted dir %s is not a valid mono skill source root", dir)
+	}
+	for _, rel := range []string{
+		"SKILL.md",
+		filepath.Join("references", "global-reference.md"),
+		filepath.Join("references", "best_practices", "_common"),
+	} {
+		if _, err := os.Stat(filepath.Join(dir, rel)); err != nil {
+			t.Errorf("expected embedded skill to contain %s: %v", rel, err)
+		}
+	}
+
+	// cleanup must actually remove the temp dir.
+	cleanup()
+	if _, err := os.Stat(dir); !os.IsNotExist(err) {
+		t.Errorf("cleanup did not remove temp dir %s (err=%v)", dir, err)
+	}
+}
+
+// TestResolveSkillSetupSourceOrEmbeddedFallsBackToEmbedded verifies that with
+// no --source and no DWS_SKILL_SOURCE, resolution uses the embedded bundle
+// rather than probing the current working directory (the stale-skill footgun).
+func TestResolveSkillSetupSourceOrEmbeddedFallsBackToEmbedded(t *testing.T) {
+	t.Setenv("DWS_SKILL_SOURCE", "")
+	dir, cleanup, err := resolveSkillSetupSourceOrEmbedded("", skillSetupModeMono)
+	if err != nil {
+		t.Fatalf("resolveSkillSetupSourceOrEmbedded: %v", err)
+	}
+	defer cleanup()
+	if !isSkillSourceRoot(dir, skillSetupModeMono) {
+		t.Fatalf("embedded fallback returned non-source-root dir %s", dir)
+	}
+}

internal/app/skill_setup_test.go

@@ -47,6 +47,22 @@ func TestResolveSkillSetupModeNonInteractiveDefaultsMono(t *testing.T) {
 	}
 }
 
+func TestIsCharDeviceRejectsNilAndRegularFiles(t *testing.T) {
+	if isCharDevice(nil) {
+		t.Fatal("nil file must not be treated as interactive")
+	}
+
+	file, err := os.CreateTemp(t.TempDir(), "stdout")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer file.Close()
+
+	if isCharDevice(file) {
+		t.Fatal("regular files must not be treated as interactive terminals")
+	}
+}
+
 func TestResolveSkillSetupSourceFindsMonoRoot(t *testing.T) {
 	tmp := t.TempDir()
 	monoDir := filepath.Join(tmp, "skills", "mono")
@@ -317,36 +333,6 @@ func TestSkillSourceCandidatesIncludesUserCache(t *testing.T) {
 
 // TestResolveSkillSetupSourceFallsBackToUserCache verifies that when no
 // --source / DWS_SKILL_SOURCE / source checkout is available, the resolver
-// successfully discovers ~/.dws/skills/multi/ as the source.
-func TestResolveSkillSetupSourceFallsBackToUserCache(t *testing.T) {
-	fakeHome := t.TempDir()
-	t.Setenv("HOME", fakeHome)
-	t.Setenv("DWS_SKILL_SOURCE", "")
-
-	cacheRoot := filepath.Join(fakeHome, ".dws", "skills", "multi")
-	for _, n := range []string{"dingtalk-aitable", "dingtalk-doc"} {
-		if err := os.MkdirAll(filepath.Join(cacheRoot, n), 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(filepath.Join(cacheRoot, n, "SKILL.md"), []byte("# "+n), 0o644); err != nil {
-			t.Fatal(err)
-		}
-	}
-
-	// Run resolver from a tempdir that has no skills/ on disk, simulating a
-	// fresh user machine without a source checkout.
-	scratch := t.TempDir()
-	t.Chdir(scratch)
-
-	got, err := resolveSkillSetupSource("", skillSetupModeMulti)
-	if err != nil {
-		t.Fatalf("expected user-cache fallback to succeed, got err=%v", err)
-	}
-	if got != cacheRoot {
-		t.Fatalf("expected %s, got %s", cacheRoot, got)
-	}
-}
-
 func TestNormalizeMultiSkillName(t *testing.T) {
 	cases := []struct {
 		in, want string

internal/app/tool_caller_adapter.go

@@ -15,10 +15,10 @@ package app
 
 import (
 	"context"
-	"encoding/json"
 	"log/slog"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
@@ -77,7 +77,7 @@ func convertResult(r executor.Result) *edition.ToolResult {
 	contentRaw, ok := resp["content"]
 	if !ok {
 		// Dry-run or echo mode: serialize the whole response as text.
-		data, _ := json.Marshal(resp)
+		data, _ := jsonutil.Marshal(resp)
 		return &edition.ToolResult{
 			Content: []edition.ContentBlock{{Type: "text", Text: string(data)}},
 		}
@@ -98,12 +98,12 @@ func convertResult(r executor.Result) *edition.ToolResult {
 		}
 		return &edition.ToolResult{Content: blocks}
 	case map[string]any:
-		data, _ := json.Marshal(v)
+		data, _ := jsonutil.Marshal(v)
 		return &edition.ToolResult{
 			Content: []edition.ContentBlock{{Type: "text", Text: string(data)}},
 		}
 	default:
-		data, _ := json.Marshal(contentRaw)
+		data, _ := jsonutil.Marshal(contentRaw)
 		return &edition.ToolResult{
 			Content: []edition.ContentBlock{{Type: "text", Text: string(data)}},
 		}

internal/app/upgrade.go

@@ -15,20 +15,20 @@ import (
 	"strings"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
-	"github.com/fatih/color"
 	"github.com/spf13/cobra"
 )
 
 var (
-	ugBold    = color.New(color.Bold).SprintFunc()
-	ugGreen   = color.New(color.FgGreen).SprintFunc()
-	ugYellow  = color.New(color.FgYellow).SprintFunc()
-	ugRed     = color.New(color.FgRed).SprintFunc()
-	ugCyan    = color.New(color.FgCyan).SprintFunc()
-	ugDim     = color.New(color.Faint).SprintFunc()
-	ugBoldGrn = color.New(color.Bold, color.FgGreen).SprintFunc()
+	ugBold    = tui.Bold
+	ugGreen   = tui.Success
+	ugYellow  = tui.Warning
+	ugRed     = tui.Danger
+	ugCyan    = tui.Cyan
+	ugDim     = tui.Dim
+	ugBoldGrn = tui.Success
 )
 
 const defaultListLimit = 10

internal/app/upgrade_embedded_guard_test.go

@@ -11,7 +11,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
-func TestUpgradeCommand_BlockedInEmbeddedMode(t *testing.T) {
+func TestUpgradeCommand_BlockedWhenEmbedded(t *testing.T) {
 	prev := edition.Get()
 	edition.Override(&edition.Hooks{IsEmbedded: true, Name: "embedded"})
 	t.Cleanup(func() { edition.Override(prev) })

internal/auth/channel.go

@@ -23,6 +23,10 @@ const (
 	// injects to declare "this process is driven by a third-party Agent host,
 	// render authorization UI yourselves".
 	AgentCodeEnv = "DINGTALK_DWS_AGENTCODE"
+
+	// AgentCodeEnvCompat is a compatibility alias for hosts that shipped the
+	// reversed prefix before AgentCodeEnv became the public spelling.
+	AgentCodeEnvCompat = "DWS_DINGTALK_AGENTCODE"
 )
 
 // AgentCodeFromEnv returns the effective host agent code and the env name that

internal/auth/device_flow.go

@@ -27,8 +27,8 @@ import (
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/i18n"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
-	"github.com/fatih/color"
 )
 
 const (
@@ -147,13 +147,14 @@ type serviceResult struct {
 }
 
 // resetCredentialState clears any stale credential state inherited from
-// previous login methods (OAuth, PAT, etc.) so that device flow always
-// starts fresh by fetching clientID from MCP.
+// previous login methods (OAuth, PAT, etc.) before device flow falls back to
+// MCP-managed credentials.
 //
 // This is a defensive measure: no matter what a prior login wrote to
-// app.json or runtime globals, device flow will re-fetch from MCP and
-// set the correct clientIDFromMCP flag, ensuring exchangeCode() uses
-// the MCP proxy path (which doesn't require clientSecret).
+// app.json, device flow will re-fetch from MCP and set the correct
+// clientIDFromMCP flag, ensuring exchangeCode() uses the MCP proxy path
+// (which doesn't require clientSecret). Complete runtime AppKey/AppSecret
+// overrides intentionally skip this reset.
 func (p *DeviceFlowProvider) resetCredentialState() {
 	p.clientID = ""
 	clientMu.Lock()
@@ -162,22 +163,29 @@ func (p *DeviceFlowProvider) resetCredentialState() {
 }
 
 func (p *DeviceFlowProvider) Login(ctx context.Context) (*TokenData, error) {
-	// Defensive reset: clear any stale credential state from previous login
-	// methods (OAuth scan, PAT, etc.) so we always re-fetch from MCP.
-	// This ensures --device login works regardless of what app.json contains.
-	p.resetCredentialState()
+	if runtimeClientID, _, ok := getCompleteRuntimeCredentials(); ok {
+		p.clientID = runtimeClientID
+		clientMu.Lock()
+		clientIDFromMCP = false
+		clientMu.Unlock()
+	} else {
+		// Defensive reset: clear any stale credential state from previous login
+		// methods (OAuth scan, PAT, etc.) so we can re-fetch from MCP. This
+		// ensures --device login works regardless of what app.json contains.
+		p.resetCredentialState()
 
-	if p.logger != nil {
-		p.logger.Debug("fetching client ID from MCP server (device flow always re-fetches)")
-	}
-	mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
-	if mcpErr != nil {
-		return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
-	}
-	p.clientID = mcpClientID
-	SetClientIDFromMCP(mcpClientID)
-	if p.logger != nil {
-		p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
+		if p.logger != nil {
+			p.logger.Debug("fetching client ID from MCP server (device flow always re-fetches)")
+		}
+		mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
+		if mcpErr != nil {
+			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
+		}
+		p.clientID = mcpClientID
+		SetClientIDFromMCP(mcpClientID)
+		if p.logger != nil {
+			p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
+		}
 	}
 
 	const maxAttempts = 3
@@ -583,20 +591,21 @@ func truncateBody(body []byte, maxLen int) string {
 }
 
 var (
-	dfBold   = color.New(color.Bold).SprintFunc()
-	dfGreen  = color.New(color.FgGreen).SprintFunc()
-	dfYellow = color.New(color.FgYellow).SprintFunc()
-	dfRed    = color.New(color.FgRed).SprintFunc()
-	dfCyan   = color.New(color.FgCyan).SprintFunc()
-	dfDim    = color.New(color.Faint).SprintFunc()
+	dfBold   = tui.Bold
+	dfGreen  = tui.Success
+	dfYellow = tui.Warning
+	dfRed    = tui.Danger
+	dfCyan   = tui.Cyan
+	dfDim    = tui.Dim
 )
 
 func dfPrintStep(w io.Writer, step int, message string, attempt int) {
+	label := fmt.Sprintf("Step %d", step)
 	if attempt > 1 {
-		_, _ = fmt.Fprintf(w, i18n.T("%s (第 %d 次尝试)\\n"), dfBold(fmt.Sprintf("▶ Step %d: %s", step, message)), attempt)
+		_, _ = fmt.Fprintf(w, i18n.T("%s %s: %s (第 %d 次尝试)\\n"), tui.StateMark("ok"), dfBold(label), message, attempt)
 		return
 	}
-	_, _ = fmt.Fprintf(w, "%s\n", dfBold(fmt.Sprintf("▶ Step %d: %s", step, message)))
+	_, _ = fmt.Fprintf(w, "%s %s: %s\n", tui.StateMark("ok"), dfBold(label), message)
 }
 
 func dfPrintDeviceCodeBox(w io.Writer, auth *DeviceAuthResponse) {
@@ -622,7 +631,7 @@ func dfPrintDeviceCodeBox(w io.Writer, auth *DeviceAuthResponse) {
 func dfPrintBox(w io.Writer, lines []string) {
 	maxLen := 0
 	for _, line := range lines {
-		if l := dfPlainLength(line); l > maxLen {
+		if l := tui.PlainRuneWidth(line); l > maxLen {
 			maxLen = l
 		}
 	}
@@ -631,38 +640,19 @@ func dfPrintBox(w io.Writer, lines []string) {
 	}
 
 	border := strings.Repeat("─", maxLen+4)
-	_, _ = fmt.Fprintf(w, "  ┌%s┐\n", border)
+	_, _ = fmt.Fprintf(w, "  %s\n", tui.Blue("╭"+border+"╮"))
 	for _, line := range lines {
-		pad := maxLen - dfPlainLength(line)
+		pad := maxLen - tui.PlainRuneWidth(line)
 		if pad < 0 {
 			pad = 0
 		}
-		_, _ = fmt.Fprintf(w, "  │  %s%s  │\n", line, strings.Repeat(" ", pad))
+		_, _ = fmt.Fprintf(w, "  %s  %s%s  %s\n", tui.Blue("│"), line, strings.Repeat(" ", pad), tui.Blue("│"))
 	}
-	_, _ = fmt.Fprintf(w, "  └%s┘\n", border)
-}
-
-func dfPlainLength(s string) int {
-	inEscape := false
-	length := 0
-	for _, r := range s {
-		if r == '\033' {
-			inEscape = true
-			continue
-		}
-		if inEscape {
-			if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') {
-				inEscape = false
-			}
-			continue
-		}
-		length++
-	}
-	return length
+	_, _ = fmt.Fprintf(w, "  %s\n", tui.Blue("╰"+border+"╯"))
 }
 
 func dfPrintPollStatus(w io.Writer, count, elapsedSec int) {
-	_, _ = fmt.Fprintf(w, "  %s ", dfDim(fmt.Sprintf(i18n.T("[%d] 轮询中... (%ds)"), count, elapsedSec)))
+	_, _ = fmt.Fprintf(w, "  %s %s ", tui.StateMark("pending"), dfDim(fmt.Sprintf(i18n.T("[%d] 轮询中... (%ds)"), count, elapsedSec)))
 }
 
 func dfPrintPollResult(w io.Writer, status, message string) {

internal/auth/endpoints.go

@@ -290,6 +290,11 @@ func getRuntimeCredentials() (clientID, clientSecret string) {
 	return runtimeClientID, runtimeClientSecret
 }
 
+func getCompleteRuntimeCredentials() (clientID, clientSecret string, ok bool) {
+	clientID, clientSecret = getRuntimeCredentials()
+	return clientID, clientSecret, strings.TrimSpace(clientID) != "" && strings.TrimSpace(clientSecret) != ""
+}
+
 // getDefaultConfigDir returns the default configuration directory.
 // Priority: DWS_CONFIG_DIR env var > ~/.dws
 func getDefaultConfigDir() string {

internal/auth/oauth_provider.go

@@ -57,8 +57,8 @@ func NewOAuthProvider(configDir string, logger *slog.Logger) *OAuthProvider {
 }
 
 // resetCredentialState clears any stale credential state inherited from
-// previous login methods so that OAuth flow always starts fresh by
-// fetching clientID from MCP.
+// previous login methods before the OAuth flow falls back to MCP-managed
+// credentials. Complete runtime AppKey/AppSecret overrides skip this reset.
 func (p *OAuthProvider) resetCredentialState() {
 	p.clientID = ""
 	clientMu.Lock()
@@ -110,22 +110,29 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 	}
 
 	// Fall through: full browser OAuth flow.
-	// Defensive reset: clear any stale credential state from previous login
-	// methods so we always re-fetch clientID from MCP. This ensures
-	// --force login works regardless of what app.json contains.
-	p.resetCredentialState()
+	if runtimeClientID, _, ok := getCompleteRuntimeCredentials(); ok {
+		p.clientID = runtimeClientID
+		clientMu.Lock()
+		clientIDFromMCP = false
+		clientMu.Unlock()
+	} else {
+		// Defensive reset: clear any stale credential state from previous login
+		// methods so we can re-fetch clientID from MCP. This ensures --force
+		// login works regardless of what app.json contains.
+		p.resetCredentialState()
 
-	if p.logger != nil {
-		p.logger.Debug("fetching client ID from MCP server (OAuth flow always re-fetches)")
-	}
-	mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
-	if mcpErr != nil {
-		return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
-	}
-	p.clientID = mcpClientID
-	SetClientIDFromMCP(mcpClientID)
-	if p.logger != nil {
-		p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
+		if p.logger != nil {
+			p.logger.Debug("fetching client ID from MCP server (OAuth flow always re-fetches)")
+		}
+		mcpClientID, mcpErr := FetchClientIDFromMCP(ctx)
+		if mcpErr != nil {
+			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
+		}
+		p.clientID = mcpClientID
+		SetClientIDFromMCP(mcpClientID)
+		if p.logger != nil {
+			p.logger.Debug("fetched client ID from MCP server", "clientID", mcpClientID)
+		}
 	}
 
 	// Find a free port for the callback server.

internal/cli/canonical.go

@@ -103,7 +103,7 @@ func NewMCPCommand(ctx context.Context, loader CatalogLoader, runner executor.Ru
 	return cmd
 }
 
-func NewSchemaCommand(loader CatalogLoader) *cobra.Command {
+func NewSchemaCommand(loader CatalogLoader, helperTools HelperToolFetcher) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "schema [path]",
 		Short: "查看 MCP 工具 Schema (产品列表 / 工具参数)",
@@ -125,7 +125,13 @@ func NewSchemaCommand(loader CatalogLoader) *cobra.Command {
   dws schema --cli-path "ding message send" # 同上，显式 flag（脚本友好）
   dws schema calendar.create_event --jq '.tool.auth'
   dws schema -f pretty ding.send_ding_message  # ANSI 彩色分区展示
-  dws schema --jq '.tool.flag_overlay'      # 只看 CLI overlay`,
+  dws schema --jq '.tool.flag_overlay'      # 只看 CLI overlay
+
+helper-only 命令组（如 dev，不走服务发现）也支持查询，schema 从 op-app
+MCP 服务端实时拉取，输出对齐 gws 的扁平格式（parameters 内联 required，
+键为 CLI flag）：
+  dws schema "dev app robot config"         # 实时 MCP 参数 schema（gws-flat）
+  dws schema "dev app"                      # 列出该分组下的子命令`,
 		Args:              cobra.MaximumNArgs(1),
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -137,6 +143,29 @@ func NewSchemaCommand(loader CatalogLoader) *cobra.Command {
 				}
 				args = []string{cliPath}
 			}
+
+			// Helper-only subtrees (e.g. `dws dev ...`) aren't in the discovery
+			// catalog; their schema CONTENT is fetched LIVE from the helper's
+			// pinned MCP server (op-app) and rendered in the gws-flat shape, so
+			// `dws schema "dev app robot config"` answers without touching
+			// discovery. Only the `dev` root claims this path; everything else
+			// falls through to the catalog below.
+			if len(args) > 0 {
+				payload, ok, err := renderHelperSchema(cmd.Context(), cmd.Root(), args[0], helperTools)
+				if err != nil {
+					return err
+				}
+				if ok {
+					return output.WriteFiltered(
+						cmd.OutOrStdout(),
+						output.ResolveFormat(cmd, output.FormatJSON),
+						payload,
+						output.ResolveFields(cmd),
+						output.ResolveJQ(cmd),
+					)
+				}
+			}
+
 			catalog, err := loader.Load(cmd.Context())
 			if err != nil {
 				var degraded *CatalogDegraded
@@ -166,6 +195,17 @@ func NewSchemaCommand(loader CatalogLoader) *cobra.Command {
 				return err
 			}
 
+			// Append helper-only subtrees (e.g. `dev`) to the no-arg product
+			// listing so browsing all products also surfaces helper commands.
+			if len(args) == 0 {
+				if helpers := helperProductSummaries(cmd.Root()); len(helpers) > 0 {
+					if products, ok := payload["products"].([]map[string]any); ok {
+						payload["products"] = append(products, helpers...)
+						payload["count"] = len(payload["products"].([]map[string]any))
+					}
+				}
+			}
+
 			return output.WriteFiltered(
 				cmd.OutOrStdout(),
 				output.ResolveFormat(cmd, output.FormatJSON),

internal/cli/canonical_test.go

@@ -288,7 +288,7 @@ func TestSchemaCommandCLIPathFlag(t *testing.T) {
 	}}
 
 	t.Run("resolves via --cli-path", func(t *testing.T) {
-		cmd := NewSchemaCommand(loader)
+		cmd := NewSchemaCommand(loader, nil)
 		var out bytes.Buffer
 		cmd.SetOut(&out)
 		cmd.SetErr(&bytes.Buffer{})
@@ -310,7 +310,7 @@ func TestSchemaCommandCLIPathFlag(t *testing.T) {
 	})
 
 	t.Run("rejects positional + flag collision", func(t *testing.T) {
-		cmd := NewSchemaCommand(loader)
+		cmd := NewSchemaCommand(loader, nil)
 		var out bytes.Buffer
 		cmd.SetOut(&out)
 		cmd.SetErr(&bytes.Buffer{})
@@ -1252,7 +1252,7 @@ func TestSchemaCommandOutputsDegradedOnUnauthenticated(t *testing.T) {
 		Reason: DegradedUnauthenticated,
 		Hint:   "未登录，无法发现 MCP 服务。请先执行: dws auth login",
 	}
-	cmd := NewSchemaCommand(errorLoader{err: degradedErr})
+	cmd := NewSchemaCommand(errorLoader{err: degradedErr}, nil)
 
 	var out, errOut bytes.Buffer
 	cmd.SetOut(&out)
@@ -1285,9 +1285,9 @@ func TestSchemaCommandOutputsDegradedOnMarketUnreachable(t *testing.T) {
 
 	degradedErr := &CatalogDegraded{
 		Reason: DegradedMarketUnreachable,
-		Hint:   "无法连接 MCP 市场 (mcp.dingtalk.com)，请检查网络",
+		Hint:   "无法连接 MCP 市场，请检查网络",
 	}
-	cmd := NewSchemaCommand(errorLoader{err: degradedErr})
+	cmd := NewSchemaCommand(errorLoader{err: degradedErr}, nil)
 
 	var out, errOut bytes.Buffer
 	cmd.SetOut(&out)
@@ -1310,7 +1310,7 @@ func TestSchemaCommandPropagatesNonDegradedError(t *testing.T) {
 	t.Parallel()
 
 	wantErr := errors.New("unexpected failure")
-	cmd := NewSchemaCommand(errorLoader{err: wantErr})
+	cmd := NewSchemaCommand(errorLoader{err: wantErr}, nil)
 
 	var out bytes.Buffer
 	cmd.SetOut(&out)

internal/cli/dev_schema.go

@@ -0,0 +1,345 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"unicode"
+
+	"github.com/spf13/cobra"
+)
+
+// helperSchemaRoots are top-level command names whose subtrees are helper-only
+// (hard-coded cobra commands, not in the discovery catalog). `dws schema` still
+// answers for them, but unlike discovery products the schema CONTENT is fetched
+// LIVE from the helper's pinned MCP server (op-app) and rendered in the flat
+// gws-aligned shape — never synthesized from local cobra flags, never
+// hardcoded. The mapping from a leaf command to its MCP tool comes from the
+// `mcp-tool` cobra annotation set in internal/helpers/devapp.go.
+var helperSchemaRoots = map[string]bool{"dev": true}
+
+// HelperToolSchema is the live op-app tool schema the renderer needs: the raw
+// MCP description plus the inputSchema's properties/required, exactly as the
+// server returned them (no local transformation of CONTENT).
+type HelperToolSchema struct {
+	Name        string
+	Description string
+	Properties  map[string]any // MCP param name → property object {type,description,default?,...}
+	Required    []string       // MCP param names that are required
+}
+
+// HelperToolFetcher loads a helper MCP server's tools/list LIVE and returns
+// toolName→schema for the given source (e.g. "op-app" for dev app commands,
+// "devdoc" for dev doc commands). The schema command injects this so
+// dev_schema.go can resolve a command's MCP tool and render its real schema
+// without the cli package importing app/transport. Implementations should
+// cache per-source per-process so repeated `dws schema dev.*` only hit the
+// network once per source.
+type HelperToolFetcher func(ctx context.Context, source string) (map[string]HelperToolSchema, error)
+
+// renderHelperSchema builds the `dws schema` payload for helper-only command
+// subtrees. Returns (payload, true) when the path targets a helper subtree (so
+// the caller skips catalog resolution); (nil, false) otherwise so the caller
+// falls back to the discovery catalog.
+//
+// Leaf commands render the gws-flat object {description, path, source,
+// parameters{<kebab>:{type,description,default?,required}}} with all CONTENT
+// pulled live from the MCP tool named by the command's `mcp-tool` annotation.
+// Group/root paths render a browse listing {path, commands:[...]} from the
+// cobra tree (no MCP needed).
+func renderHelperSchema(ctx context.Context, root *cobra.Command, rawPath string, fetch HelperToolFetcher) (map[string]any, bool, error) {
+	if root == nil {
+		return nil, false, nil
+	}
+	tokens := splitSchemaPathTokens(rawPath)
+	if len(tokens) == 0 || !helperSchemaRoots[tokens[0]] {
+		return nil, false, nil
+	}
+
+	target, rest, err := root.Find(tokens)
+	if err != nil || target == nil {
+		target = root
+		rest = tokens[1:]
+	}
+	// Find resolves to the deepest matching command and returns trailing tokens
+	// it couldn't match as (sub)commands. Any non-flag leftover means a typo'd
+	// or unknown subcommand — surface it with the closest group's children.
+	if unknown := firstNonFlag(rest); unknown != "" {
+		return map[string]any{
+			"path":      rawPath,
+			"error":     "unknown subcommand \"" + unknown + "\" under \"" + helperCommandPath(target) + "\"",
+			"available": helperSubcommands(target),
+		}, true, nil
+	}
+
+	// A runnable leaf → emit its live MCP schema in gws-flat shape.
+	// A group → browse its subcommands.
+	if target.Runnable() && !target.HasAvailableSubCommands() {
+		payload, err := helperLeafSchema(ctx, target, fetch)
+		return payload, true, err
+	}
+
+	return map[string]any{
+		"path":     helperCommandPath(target),
+		"commands": helperSubcommands(target),
+	}, true, nil
+}
+
+// helperLeafSchema renders a single leaf command as the gws-flat object,
+// fetching its MCP tool schema live. The command must carry an `mcp-tool`
+// annotation; commands without one (e.g. `dev connect`, `dev doc search`) are
+// not devapp tools and get a clear, non-fatal explanation instead.
+func helperLeafSchema(ctx context.Context, cmd *cobra.Command, fetch HelperToolFetcher) (map[string]any, error) {
+	toolName, source := "", ""
+	if cmd.Annotations != nil {
+		toolName = strings.TrimSpace(cmd.Annotations["mcp-tool"])
+		source = strings.TrimSpace(cmd.Annotations["mcp-source"])
+	}
+	// Default source is op-app (dev app commands); dev doc commands annotate
+	// mcp-source=devdoc to pull from the devdoc MCP server instead.
+	if source == "" {
+		source = "op-app"
+	}
+	path := helperCommandPath(cmd)
+	if toolName == "" {
+		return map[string]any{
+			"path":  path,
+			"error": "no MCP tool bound to this command; schema is unavailable",
+		}, nil
+	}
+	if fetch == nil {
+		return map[string]any{
+			"path":  path,
+			"error": "live MCP schema fetcher not configured",
+		}, nil
+	}
+
+	tools, err := fetch(ctx, source)
+	if err != nil {
+		return nil, fmt.Errorf("fetch %s tool schemas: %w", source, err)
+	}
+	tool, ok := tools[toolName]
+	if !ok {
+		return map[string]any{
+			"path":  path,
+			"error": fmt.Sprintf("MCP tool %q not found in %s tools/list", toolName, source),
+		}, nil
+	}
+
+	return map[string]any{
+		"description": tool.Description,
+		"path":        path,
+		"source":      "mcp:" + source,
+		"parameters":  helperFlatParameters(tool),
+	}, nil
+}
+
+// helperFlatParameters projects an MCP tool's inputSchema into the gws-flat
+// per-parameter object. Keys are kebab-case of the MCP param name (== the CLI
+// flag); each value is {type, description, default?, required} with type mapped
+// to a JSON-type string, description verbatim from MCP, default only when MCP
+// provides one (stringified), and required inline (true iff the param is in the
+// tool's required[]).
+func helperFlatParameters(tool HelperToolSchema) map[string]any {
+	required := make(map[string]bool, len(tool.Required))
+	for _, r := range tool.Required {
+		required[r] = true
+	}
+
+	params := make(map[string]any, len(tool.Properties))
+	for name, raw := range tool.Properties {
+		prop, _ := raw.(map[string]any)
+		entry := map[string]any{
+			"type":        mcpJSONType(prop),
+			"description": mcpString(prop, "description"),
+			"required":    required[name],
+		}
+		if def, ok := mcpDefault(prop); ok {
+			entry["default"] = def
+		}
+		params[kebabCase(name)] = entry
+	}
+	return params
+}
+
+// mcpJSONType normalizes the MCP property "type" to a JSON-type string. MCP
+// reports standard JSON Schema types; pass them through, defaulting to "string"
+// when absent/unknown so the contract is always populated.
+func mcpJSONType(prop map[string]any) string {
+	t, _ := prop["type"].(string)
+	switch t {
+	case "string", "integer", "number", "boolean", "array", "object":
+		return t
+	default:
+		return "string"
+	}
+}
+
+// mcpString reads a string field from an MCP property object.
+func mcpString(prop map[string]any, key string) string {
+	if prop == nil {
+		return ""
+	}
+	v, _ := prop[key].(string)
+	return v
+}
+
+// mcpDefault returns the MCP-provided default, stringified, only when present.
+// gws renders default as a string; mirror that. Non-string JSON defaults
+// (numbers/bools) are formatted with %v so e.g. 0 → "0", true → "true".
+func mcpDefault(prop map[string]any) (string, bool) {
+	if prop == nil {
+		return "", false
+	}
+	v, ok := prop["default"]
+	if !ok || v == nil {
+		return "", false
+	}
+	switch tv := v.(type) {
+	case string:
+		return tv, true
+	case float64:
+		// JSON numbers decode to float64; render integers without a fraction.
+		if tv == float64(int64(tv)) {
+			return fmt.Sprintf("%d", int64(tv)), true
+		}
+		return fmt.Sprintf("%v", tv), true
+	default:
+		return fmt.Sprintf("%v", tv), true
+	}
+}
+
+// kebabCase converts an MCP camelCase param name to the CLI flag's kebab form,
+// matching how flags are registered in internal/helpers/devapp.go:
+//
+//	eventCallbackUrl → event-callback-url
+//	unifiedAppId     → unified-app-id
+//	disableSSLVerify → disable-ssl-verify
+//
+// A boundary is inserted before an uppercase letter that follows a lowercase
+// letter or digit, and before the final uppercase of a run that starts a new
+// lowercase word (so SSLVerify → ssl-verify, not s-s-l-verify).
+func kebabCase(name string) string {
+	runes := []rune(name)
+	var b strings.Builder
+	for i, r := range runes {
+		if unicode.IsUpper(r) {
+			prevLowerOrDigit := i > 0 && (unicode.IsLower(runes[i-1]) || unicode.IsDigit(runes[i-1]))
+			nextLower := i+1 < len(runes) && unicode.IsLower(runes[i+1])
+			if i > 0 && (prevLowerOrDigit || nextLower) {
+				b.WriteByte('-')
+			}
+			b.WriteRune(unicode.ToLower(r))
+			continue
+		}
+		b.WriteRune(r)
+	}
+	// Collapse any accidental double dashes and trim, just in case the source
+	// already contained separators.
+	out := strings.ReplaceAll(b.String(), "_", "-")
+	for strings.Contains(out, "--") {
+		out = strings.ReplaceAll(out, "--", "-")
+	}
+	return strings.Trim(out, "-")
+}
+
+// helperProductSummaries returns light product entries for every helper-only
+// subtree, appended to the no-arg `dws schema` product listing so agents
+// browsing all products also see helper commands. Tools are listed by path +
+// summary only; drill in with `dws schema "<path>"` for full parameter schema.
+func helperProductSummaries(root *cobra.Command) []map[string]any {
+	if root == nil {
+		return nil
+	}
+	out := []map[string]any{}
+	for name := range helperSchemaRoots {
+		top, _, err := root.Find([]string{name})
+		if err != nil || top == nil || !top.HasParent() {
+			continue
+		}
+		leaves := []map[string]any{}
+		walkLeafCommands(top, func(leaf *cobra.Command) {
+			leaves = append(leaves, map[string]any{
+				"cli_name":    leaf.Name(),
+				"cli_path":    helperCommandPath(leaf),
+				"description": strings.TrimSpace(leaf.Short),
+			})
+		})
+		out = append(out, map[string]any{
+			"id":          name,
+			"name":        strings.TrimSpace(top.Short),
+			"description": "helper-only 命令组（不走服务发现）；schema 从 op-app MCP 实时拉取，用 `dws schema \"" + helperCommandPath(top) + " ...\"` 查具体参数",
+			"helper":      true,
+			"tools":       leaves,
+		})
+	}
+	return out
+}
+
+// walkLeafCommands invokes fn for every runnable leaf under cmd (depth-first).
+func walkLeafCommands(cmd *cobra.Command, fn func(*cobra.Command)) {
+	if cmd.Runnable() && !cmd.HasAvailableSubCommands() {
+		fn(cmd)
+		return
+	}
+	for _, sub := range cmd.Commands() {
+		if !sub.IsAvailableCommand() || sub.Name() == "help" {
+			continue
+		}
+		walkLeafCommands(sub, fn)
+	}
+}
+
+// helperSubcommands lists a group's runnable children for browse mode, sorted
+// by name for deterministic output.
+func helperSubcommands(cmd *cobra.Command) []map[string]any {
+	out := []map[string]any{}
+	for _, sub := range cmd.Commands() {
+		if !sub.IsAvailableCommand() || sub.Name() == "help" {
+			continue
+		}
+		out = append(out, map[string]any{
+			"cli_path":    helperCommandPath(sub),
+			"description": strings.TrimSpace(sub.Short),
+		})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		return out[i]["cli_path"].(string) < out[j]["cli_path"].(string)
+	})
+	return out
+}
+
+// helperCommandPath returns the space-joined path from root to cmd, e.g.
+// "dev app robot config".
+func helperCommandPath(cmd *cobra.Command) string {
+	parts := []string{}
+	for c := cmd; c != nil && c.HasParent(); c = c.Parent() {
+		parts = append([]string{c.Name()}, parts...)
+	}
+	return strings.Join(parts, " ")
+}
+
+// firstNonFlag returns the first token that is not a flag (does not start with
+// "-"), or "" if there is none.
+func firstNonFlag(tokens []string) string {
+	for _, t := range tokens {
+		if t != "" && !strings.HasPrefix(t, "-") {
+			return t
+		}
+	}
+	return ""
+}

internal/cli/dev_schema_test.go

@@ -0,0 +1,254 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// buildHelperTestTree mirrors the shape of the real `dws dev` subtree closely
+// enough to exercise the live-schema renderer: a group and leaves carrying the
+// `mcp-tool` annotation that names the op-app tool to fetch.
+func buildHelperTestTree() *cobra.Command {
+	root := &cobra.Command{Use: "dws"}
+
+	create := &cobra.Command{
+		Use:         "create",
+		Short:       "创建应用",
+		Annotations: map[string]string{"mcp-tool": "create_dev_app"},
+		Run:         func(*cobra.Command, []string) {},
+	}
+
+	config := &cobra.Command{
+		Use:         "config",
+		Short:       "配置机器人",
+		Annotations: map[string]string{"mcp-tool": "set_extension_robot_config"},
+		Run:         func(*cobra.Command, []string) {},
+	}
+
+	// A leaf without an mcp-tool annotation (e.g. dev connect / dev doc search).
+	noTool := &cobra.Command{Use: "connect", Short: "无 MCP 工具", Run: func(*cobra.Command, []string) {}}
+
+	robot := &cobra.Command{Use: "robot", Short: "机器人能力"}
+	robot.AddCommand(config)
+
+	app := &cobra.Command{Use: "app", Short: "应用"}
+	app.AddCommand(create, robot)
+
+	dev := &cobra.Command{Use: "dev", Short: "开放平台开发者命令"}
+	dev.AddCommand(app, noTool)
+
+	root.AddCommand(dev)
+	return root
+}
+
+// fakeFetcher returns a canned op-app tools/list so the renderer is exercised
+// without network. It mirrors the MCP shape: properties keyed by camelCase param
+// name, required[] listing the camelCase names.
+func fakeFetcher(tools map[string]HelperToolSchema) HelperToolFetcher {
+	return func(context.Context, string) (map[string]HelperToolSchema, error) {
+		return tools, nil
+	}
+}
+
+func robotConfigToolSchema() HelperToolSchema {
+	return HelperToolSchema{
+		Name:        "set_extension_robot_config",
+		Description: "创建或更新现有应用的机器人配置",
+		Properties: map[string]any{
+			"unifiedAppId":     map[string]any{"type": "string", "description": "统一应用 ID"},
+			"eventCallbackUrl": map[string]any{"type": "string", "description": "事件回调地址"},
+			"skills":           map[string]any{"type": "array", "description": "技能列表"},
+			"mode":             map[string]any{"type": "string", "description": "机器人模式", "enum": []any{"HTTPS", "STREAM", "AISKILL"}},
+		},
+		Required: []string{"unifiedAppId"},
+	}
+}
+
+func TestRenderHelperSchema_LeafGwsFlat(t *testing.T) {
+	root := buildHelperTestTree()
+	fetch := fakeFetcher(map[string]HelperToolSchema{
+		"set_extension_robot_config": robotConfigToolSchema(),
+	})
+
+	payload, ok, err := renderHelperSchema(context.Background(), root, "dev app robot config", fetch)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected helper renderer to claim the path")
+	}
+
+	// Flat top-level: description / path / source / parameters; no wrapper.
+	if payload["description"] != "创建或更新现有应用的机器人配置" {
+		t.Fatalf("description = %v", payload["description"])
+	}
+	if payload["path"] != "dev app robot config" {
+		t.Fatalf("path = %v", payload["path"])
+	}
+	if payload["source"] != "mcp:op-app" {
+		t.Fatalf("source = %v", payload["source"])
+	}
+	for _, leaked := range []string{"kind", "tool", "product", "helper"} {
+		if _, present := payload[leaked]; present {
+			t.Fatalf("gws-flat output must not carry %q wrapper key", leaked)
+		}
+	}
+
+	params, _ := payload["parameters"].(map[string]any)
+	if params == nil {
+		t.Fatalf("no parameters: %#v", payload)
+	}
+
+	// Keys are kebab-case of the MCP param name == the CLI flag.
+	uid, _ := params["unified-app-id"].(map[string]any)
+	if uid == nil {
+		t.Fatalf("missing unified-app-id param: %#v", params)
+	}
+	if uid["type"] != "string" || uid["required"] != true {
+		t.Fatalf("unified-app-id = %#v, want string+required", uid)
+	}
+	if _, hasDefault := uid["default"]; hasDefault {
+		t.Fatal("unified-app-id must not carry a default (MCP provides none)")
+	}
+
+	cb, _ := params["event-callback-url"].(map[string]any)
+	if cb == nil || cb["required"] != false {
+		t.Fatalf("event-callback-url = %#v, want required=false", cb)
+	}
+
+	skills, _ := params["skills"].(map[string]any)
+	if skills == nil || skills["type"] != "array" {
+		t.Fatalf("skills = %#v, want array", skills)
+	}
+
+	mode, _ := params["mode"].(map[string]any)
+	if mode == nil || mode["type"] != "string" {
+		t.Fatalf("mode = %#v, want string", mode)
+	}
+	if _, hasDefault := mode["default"]; hasDefault {
+		t.Fatalf("mode default = %v, want none", mode["default"])
+	}
+	if mode["required"] != false {
+		t.Fatalf("mode required = %v, want false", mode["required"])
+	}
+}
+
+func TestRenderHelperSchema_Group(t *testing.T) {
+	root := buildHelperTestTree()
+	payload, ok, err := renderHelperSchema(context.Background(), root, "dev app", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected claim")
+	}
+	if payload["path"] != "dev app" {
+		t.Fatalf("path = %v", payload["path"])
+	}
+	cmds, _ := payload["commands"].([]map[string]any)
+	if len(cmds) != 2 { // create + robot
+		t.Fatalf("commands count = %d, want 2", len(cmds))
+	}
+}
+
+func TestRenderHelperSchema_NoAnnotation(t *testing.T) {
+	root := buildHelperTestTree()
+	payload, ok, err := renderHelperSchema(context.Background(), root, "dev connect", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected claim")
+	}
+	if payload["error"] == nil {
+		t.Fatalf("expected a clear no-MCP-tool error, got %#v", payload)
+	}
+	if _, present := payload["parameters"]; present {
+		t.Fatal("no-tool command must not emit parameters")
+	}
+}
+
+func TestRenderHelperSchema_UnknownSubcommand(t *testing.T) {
+	root := buildHelperTestTree()
+	payload, ok, err := renderHelperSchema(context.Background(), root, "dev app nope", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected claim")
+	}
+	if payload["error"] == nil {
+		t.Fatalf("expected error for unknown subcommand, got %#v", payload)
+	}
+	if avail, _ := payload["available"].([]map[string]any); len(avail) == 0 {
+		t.Fatal("expected available subcommands listed")
+	}
+}
+
+func TestRenderHelperSchema_ToolMissingInList(t *testing.T) {
+	root := buildHelperTestTree()
+	// Fetcher returns an empty list — the annotated tool isn't present.
+	payload, ok, err := renderHelperSchema(context.Background(), root, "dev app create", fakeFetcher(map[string]HelperToolSchema{}))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected claim")
+	}
+	if payload["error"] == nil {
+		t.Fatalf("expected not-found error, got %#v", payload)
+	}
+}
+
+func TestRenderHelperSchema_FetchError(t *testing.T) {
+	root := buildHelperTestTree()
+	failing := func(context.Context, string) (map[string]HelperToolSchema, error) {
+		return nil, errors.New("network down")
+	}
+	_, ok, err := renderHelperSchema(context.Background(), root, "dev app create", failing)
+	if !ok {
+		t.Fatal("expected claim even on fetch error")
+	}
+	if err == nil {
+		t.Fatal("expected the fetch error to surface")
+	}
+}
+
+func TestRenderHelperSchema_NonHelperPathDeclined(t *testing.T) {
+	root := buildHelperTestTree()
+	if _, ok, _ := renderHelperSchema(context.Background(), root, "ding.message.send", nil); ok {
+		t.Fatal("non-helper path must not be claimed by the helper renderer")
+	}
+}
+
+func TestKebabCase(t *testing.T) {
+	cases := map[string]string{
+		"eventCallbackUrl": "event-callback-url",
+		"unifiedAppId":     "unified-app-id",
+		"disableSSLVerify": "disable-ssl-verify",
+		"mode":             "mode",
+		"skills":           "skills",
+		"i18nName":         "i18n-name",
+	}
+	for in, want := range cases {
+		if got := kebabCase(in); got != want {
+			t.Errorf("kebabCase(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

internal/cli/loader.go

@@ -90,7 +90,7 @@ func degradedHint(reason CatalogDegradedReason, serverCount int) string {
 		if embedded {
 			return "无法连接 MCP 市场，请检查网络"
 		}
-		return "无法连接 MCP 市场 (mcp.dingtalk.com)，请检查网络"
+		return "无法连接 MCP 市场，请检查网络"
 	case DegradedRuntimeAllFailed:
 		if embedded {
 			return fmt.Sprintf("已发现 %d 个服务但连接全部失败，请稍后重试", serverCount)
@@ -279,7 +279,7 @@ func (l EnvironmentLoader) Load(ctx context.Context) (ir.Catalog, error) {
 	// accepted subset. See plan fix-wukong-discovery-missing-servers Phase 4.3.
 	logDiscoveryWarnings(response.Metadata.Warnings)
 
-	servers := market.NormalizeServers(response, "live_market")
+	servers := market.NormalizeServersForBaseURL(response, "live_market", baseURL)
 	_ = store.SaveRegistry(partition, cache.RegistrySnapshot{Servers: servers})
 
 	changedKeys := cache.ChangedServerKeysByUpdatedAt(cached.Registry.Servers, servers)

internal/compat/attendance_hooks.go

@@ -0,0 +1,192 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package compat
+
+import (
+	"encoding/json"
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// attendanceScheduleInnerRequired are the fields every scheduleVOS item must
+// carry; the backend rejects partial items with an opaque error, so the CLI
+// validates them up front (mirrors wukong's attendance.go).
+var attendanceScheduleInnerRequired = []string{"userId", "workDate", "classId", "isRest"}
+
+var attendanceGroupTypes = map[string]bool{"FIXED": true, "TURN": true, "NONE": true}
+
+var attendanceApproveTypes = map[string]bool{
+	"overtime": true, "trip": true, "travel": true, "business_trip": true,
+	"business-trip": true, "out": true, "leave": true, "patch": true,
+	"repair_check": true, "repair-check": true,
+}
+
+// installAttendanceHook wires attendance-specific PreRunE validators that
+// mirror wukong's client-side checks (inner-JSON required fields, group type,
+// FIXED conditional requirements, group-update no-op). No-op for other
+// products / tools. Preserves any PreRunE NewDirectCommand already installed.
+func installAttendanceHook(cmd *cobra.Command, canonicalProduct, toolName string) {
+	if cmd == nil || strings.TrimSpace(canonicalProduct) != "attendance" {
+		return
+	}
+	var validate func(*cobra.Command) error
+	switch toolName {
+	case "generateTurnSchedule":
+		validate = validateAttendanceScheduleImport
+	case "create_class_setting":
+		validate = validateAttendanceClassCreate
+	case "create_group_setting":
+		validate = validateAttendanceGroupCreate
+	case "update_group_setting":
+		validate = validateAttendanceGroupUpdate
+	case "update_group_member":
+		validate = validateAttendanceUpdateMembers
+	case "save_self_setting":
+		validate = validateAttendanceSelfSettingSave
+	case "query_at_approve_template":
+		validate = validateAttendanceApproveTemplates
+	default:
+		return
+	}
+	original := cmd.PreRunE
+	cmd.PreRunE = func(c *cobra.Command, args []string) error {
+		if original != nil {
+			if err := original(c, args); err != nil {
+				return err
+			}
+		}
+		return validate(c)
+	}
+}
+
+func attFlagString(cmd *cobra.Command, names ...string) string {
+	for _, n := range names {
+		if cmd.Flags().Lookup(n) == nil {
+			continue
+		}
+		if v, err := cmd.Flags().GetString(n); err == nil && strings.TrimSpace(v) != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func validateAttendanceScheduleImport(cmd *cobra.Command) error {
+	raw := attFlagString(cmd, "scheduleVOS", "schedules")
+	if raw == "" {
+		return nil // empty is owned by the required-flag check
+	}
+	var items []map[string]any
+	if err := json.Unmarshal([]byte(raw), &items); err != nil {
+		return nil // malformed JSON is owned by a separate check
+	}
+	if len(items) == 0 {
+		return apperrors.NewValidation("--scheduleVOS requires at least one schedule entry (empty array not allowed)")
+	}
+	for _, item := range items {
+		for _, f := range attendanceScheduleInnerRequired {
+			if _, ok := item[f]; !ok {
+				return apperrors.NewValidation("missing required field: " + f + "（--scheduleVOS 每个排班项必填）")
+			}
+		}
+	}
+	return nil
+}
+
+func validateAttendanceClassCreate(cmd *cobra.Command) error {
+	raw := attFlagString(cmd, "class-vo", "TopAtClassVO")
+	if raw == "" {
+		return nil
+	}
+	var vo map[string]any
+	if err := json.Unmarshal([]byte(raw), &vo); err != nil {
+		return nil
+	}
+	if _, ok := vo["sections"]; !ok {
+		return apperrors.NewValidation("missing required field: sections（班次时段，--class-vo 内必填）")
+	}
+	return nil
+}
+
+func validateAttendanceGroupCreate(cmd *cobra.Command) error {
+	typ := strings.TrimSpace(attFlagString(cmd, "type"))
+	if typ != "" && !attendanceGroupTypes[typ] {
+		return apperrors.NewValidation("考勤组类型不合法：--type 应为 FIXED / TURN / NONE 之一")
+	}
+	if typ == "FIXED" {
+		var vo map[string]any
+		if raw := attFlagString(cmd, "group-vo", "groupVO"); raw != "" {
+			_ = json.Unmarshal([]byte(raw), &vo)
+		}
+		if vo == nil {
+			vo = map[string]any{}
+		}
+		if _, ok := vo["workDayClassList"]; !ok {
+			return apperrors.NewValidation("type=FIXED 时 --group-vo 内必填 workDayClassList（工作日班次列表）")
+		}
+		if _, ok := vo["defaultClassId"]; !ok {
+			return apperrors.NewValidation("type=FIXED 时 --group-vo 内必填 defaultClassId（默认班次 ID）")
+		}
+	}
+	return nil
+}
+
+func validateAttendanceGroupUpdate(cmd *cobra.Command) error {
+	if v := strings.TrimSpace(attFlagString(cmd, "enable-outside-check")); v != "" && v != "true" && v != "false" {
+		return apperrors.NewValidation("--enable-outside-check must be true or false")
+	}
+	for _, f := range []string{"name", "type", "owner", "enable-outside-check", "classIds", "group-vo"} {
+		if fl := cmd.Flags().Lookup(f); fl != nil && cmd.Flags().Changed(f) {
+			return nil
+		}
+	}
+	return apperrors.NewValidation("至少需要指定一个修改项（--name / --type / --owner / --enable-outside-check / --classIds / --group-vo）")
+}
+
+func validateAttendanceUpdateMembers(cmd *cobra.Command) error {
+	for _, f := range []string{"add-users", "remove-users", "add-extra-users", "remove-extra-users", "add-depts", "remove-depts"} {
+		if fl := cmd.Flags().Lookup(f); fl != nil && cmd.Flags().Changed(f) {
+			return nil
+		}
+	}
+	return apperrors.NewValidation("至少需要指定一个变更项（--add-users / --remove-users / --add-extra-users / --remove-extra-users / --add-depts / --remove-depts）")
+}
+
+func validateAttendanceSelfSettingSave(cmd *cobra.Command) error {
+	hasField := false
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		switch f.Name {
+		case "setting-scene", "user", "yes", "format", "debug", "verbose", "dry-run",
+			"client-id", "client-secret", "fields", "jq", "mock", "timeout":
+			// control / identity flags, not setting fields
+		default:
+			hasField = true
+		}
+	})
+	if !hasField {
+		return apperrors.NewValidation("至少需要指定一个设置项（--setting-scene / --user 之外的任一字段）")
+	}
+	return nil
+}
+
+func validateAttendanceApproveTemplates(cmd *cobra.Command) error {
+	typ := strings.TrimSpace(attFlagString(cmd, "type"))
+	if typ != "" && !attendanceApproveTypes[typ] {
+		return apperrors.NewValidation("无效的审批类型：--type 应为 overtime / leave / patch / trip(travel) / business_trip 之一")
+	}
+	return nil
+}

internal/compat/calendar_hooks.go

@@ -0,0 +1,123 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package compat
+
+import (
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/spf13/cobra"
+)
+
+// calendarRecurrenceTools are the calendar leaves whose recurrence fields must
+// be supplied as a complete set (the MCP backend does not merge partial
+// recurrence, so a partial update would silently overwrite the rule). Mirrors
+// wukong's calendar.go event create/update validation.
+var calendarRecurrenceTools = map[string]bool{
+	"create_calendar_event": true,
+	"update_calendar_event": true,
+}
+
+// calendarRecurrenceFlags is the full set of --recurrence-* flags; touching any
+// of them requires the core structural fields to be present.
+var calendarRecurrenceFlags = []string{
+	"recurrence-type", "recurrence-interval", "recurrence-range-type",
+	"recurrence-count", "recurrence-end-date", "recurrence-days-of-week",
+	"recurrence-day-of-month", "recurrence-month", "recurrence-week-index",
+	"recurrence-first-day-of-week",
+}
+
+// installCalendarHook wires calendar-specific PreRunE validators onto leaf
+// commands emitted by BuildDynamicCommands. No-op for non-calendar products and
+// calendar tools without extra client-side checks. The hook chain preserves the
+// PreRunE that NewDirectCommand already installed by invoking it first.
+func installCalendarHook(cmd *cobra.Command, canonicalProduct, toolName string) {
+	if cmd == nil || strings.TrimSpace(canonicalProduct) != "calendar" {
+		return
+	}
+	if !calendarRecurrenceTools[toolName] {
+		return
+	}
+	original := cmd.PreRunE
+	cmd.PreRunE = func(c *cobra.Command, args []string) error {
+		if original != nil {
+			if err := original(c, args); err != nil {
+				return err
+			}
+		}
+		return validateCalendarRecurrence(c)
+	}
+}
+
+// validateCalendarRecurrence refuses a partial recurrence structure. If any
+// --recurrence-* flag is set, recurrence-type / interval / range-type must be
+// present, and weekly / relativeMonthly patterns require days-of-week. Error
+// wording carries the kebab flag names so the messages match wukong and the
+// auto-test substring assertions (days-of-week / recurrence-type).
+func validateCalendarRecurrence(cmd *cobra.Command) error {
+	if cmd == nil {
+		return nil
+	}
+	used := false
+	for _, f := range calendarRecurrenceFlags {
+		if fl := cmd.Flags().Lookup(f); fl != nil && cmd.Flags().Changed(f) {
+			used = true
+			break
+		}
+	}
+	if !used {
+		return nil
+	}
+
+	recType := strings.TrimSpace(calendarFlagString(cmd, "recurrence-type"))
+	if recType == "" {
+		return apperrors.NewValidation(
+			"recurrence 结构不完整：使用任一 --recurrence-* 时必须整体重传完整循环字段" +
+				"（至少 --recurrence-type / --recurrence-interval / --recurrence-range-type，" +
+				"MCP 不合并部分字段）")
+	}
+	if !calendarFlagSet(cmd, "recurrence-interval") {
+		return apperrors.NewValidation(
+			"recurrence 结构不完整：缺少 --recurrence-interval（循环间隔，recurrence 整体必填）")
+	}
+	if !calendarFlagSet(cmd, "recurrence-range-type") {
+		return apperrors.NewValidation(
+			"recurrence 结构不完整：缺少 --recurrence-range-type（循环范围类型，recurrence 整体必填）")
+	}
+	if recType == "weekly" || recType == "relativeMonthly" {
+		if strings.TrimSpace(calendarFlagString(cmd, "recurrence-days-of-week")) == "" {
+			return apperrors.NewValidation(
+				"weekly / relativeMonthly 循环必须提供 --recurrence-days-of-week (daysOfWeek)")
+		}
+	}
+	return nil
+}
+
+func calendarFlagString(cmd *cobra.Command, name string) string {
+	if cmd.Flags().Lookup(name) == nil {
+		return ""
+	}
+	v, _ := cmd.Flags().GetString(name)
+	return v
+}
+
+// calendarFlagSet reports whether a flag was explicitly provided by the user,
+// tolerating both string and int (--recurrence-interval) flag kinds.
+func calendarFlagSet(cmd *cobra.Command, name string) bool {
+	fl := cmd.Flags().Lookup(name)
+	if fl == nil {
+		return false
+	}
+	return cmd.Flags().Changed(name)
+}

internal/compat/dynamic_commands.go

@@ -239,6 +239,15 @@ func BuildDynamicCommands(servers []market.ServerDescriptor, runner executor.Run
 			// todo_hooks.go for the full rationale). No-op for non-todo.
 			installTodoHook(cmd, canonicalProduct, toolName)
 
+			// §calendar-hook: reject partial recurrence on event create/update
+			// (see calendar_hooks.go). No-op for non-calendar.
+			installCalendarHook(cmd, canonicalProduct, toolName)
+
+			// §attendance-hook: inner-JSON required fields, group type and
+			// FIXED conditional checks (see attendance_hooks.go). No-op for
+			// non-attendance.
+			installAttendanceHook(cmd, canonicalProduct, toolName)
+
 			// §1.4: Add to the right parent group
 			attachToGroup(rootCmd, override.Group, groupCmds, cmd)
 		}

internal/compat/registry.go

@@ -336,7 +336,16 @@ func NewDirectCommand(route Route, runner executor.Runner) *cobra.Command {
 					Response: resp,
 				}
 				if route.OutputTransform != nil && result.Response != nil {
-					result.Response = route.OutputTransform(result.Response)
+					// Shape the MCP content payload (the actual data), not the
+					// {endpoint, content} runtime envelope, so rename/drop/table
+					// paths resolve against response fields (e.g. result.items)
+					// rather than the wrapper. Falls back to the whole Response
+					// when no content map is present (degraded/echo paths).
+					if content, ok := result.Response["content"].(map[string]any); ok {
+						result.Response["content"] = route.OutputTransform(content)
+					} else {
+						result.Response = route.OutputTransform(result.Response)
+					}
 				}
 				return output.WriteCommandPayload(cmd, result, output.FormatJSON)
 			}
@@ -862,7 +871,7 @@ func CollectBindings(cmd *cobra.Command, bindings []FlagBinding, existing map[st
 			if _, ok := existing[binding.Property]; ok {
 				continue
 			}
-			return nil, apperrors.NewValidation(fmt.Sprintf("--%s is required", primaryName))
+			return nil, apperrors.NewValidation(fmt.Sprintf("missing required flag: --%s is required", primaryName))
 		}
 		if !anyChanged {
 			continue

internal/compat/transform.go

@@ -30,7 +30,7 @@ import (
 
 // ApplyTransform applies a named transform rule to a value.
 // Supported transforms: iso8601_to_millis, csv_to_array, json_parse,
-// json_parse_strict, enum_map, file_read, invert_bool, string_to_int64.
+// json_parse_strict, enum_map, file_read, invert_bool, parse_bool, string_to_int64.
 func ApplyTransform(value any, transform string, args map[string]any) (any, error) {
 	switch strings.TrimSpace(transform) {
 	case "":
@@ -49,6 +49,10 @@ func ApplyTransform(value any, transform string, args map[string]any) (any, erro
 		return transformFileRead(value)
 	case "invert_bool":
 		return transformInvertBool(value)
+	case "parse_bool":
+		return transformParseBool(value)
+	case "attendance_class_check_time":
+		return transformAttendanceClassCheckTime(value)
 	case "string_to_int64":
 		return transformStringToInt64(value)
 	default:
@@ -79,6 +83,77 @@ func transformInvertBool(value any) (any, error) {
 	}
 }
 
+// transformParseBool coerces a CLI string flag into a real JSON boolean so the
+// MCP body carries `false`/`true` (not the string "false"/"true" or a swallowed
+// zero value). Used by envelope flags that are semantically boolean but must be
+// declared as string flags to accept an explicit `false` on the command line
+// (cobra bool flags drop the space-form value). Unknown tokens pass through
+// unchanged so upstream validators own the error wording.
+func transformParseBool(value any) (any, error) {
+	switch v := value.(type) {
+	case bool:
+		return v, nil
+	case string:
+		switch strings.ToLower(strings.TrimSpace(v)) {
+		case "true", "1", "yes", "on":
+			return true, nil
+		case "false", "0", "no", "off":
+			return false, nil
+		}
+		return value, nil
+	default:
+		return value, nil
+	}
+}
+
+// transformAttendanceClassCheckTime parses a class-VO JSON string and converts
+// every "HH:mm" checkTime under sections[*].times[*] and
+// setting.topRestTimeList[*] into a Unix-millis number (1970-01-01 HH:mm in
+// UTC+8), mirroring wukong's convertClassCheckTime. The MCP backend expects the
+// numeric form; the envelope cannot express this nested walk, so it lives here.
+func transformAttendanceClassCheckTime(value any) (any, error) {
+	parsed, err := transformJSONParseStrict(value)
+	if err != nil {
+		return nil, err
+	}
+	classVO, ok := parsed.(map[string]any)
+	if !ok {
+		return parsed, nil
+	}
+	cst := time.FixedZone("CST", 8*3600)
+	convertOne := func(obj map[string]any) {
+		if ct, ok := obj["checkTime"].(string); ok {
+			ct = strings.TrimSpace(ct)
+			if t, err := time.ParseInLocation("2006-01-02 15:04", "1970-01-01 "+ct, cst); err == nil {
+				obj["checkTime"] = float64(t.UnixMilli())
+			}
+		}
+	}
+	if sections, ok := classVO["sections"].([]any); ok {
+		for _, sec := range sections {
+			if secMap, ok := sec.(map[string]any); ok {
+				if times, ok := secMap["times"].([]any); ok {
+					for _, t := range times {
+						if tMap, ok := t.(map[string]any); ok {
+							convertOne(tMap)
+						}
+					}
+				}
+			}
+		}
+	}
+	if setting, ok := classVO["setting"].(map[string]any); ok {
+		if restList, ok := setting["topRestTimeList"].([]any); ok {
+			for _, item := range restList {
+				if itemMap, ok := item.(map[string]any); ok {
+					convertOne(itemMap)
+				}
+			}
+		}
+	}
+	return classVO, nil
+}
+
 func transformISO8601ToMillis(value any) (any, error) {
 	s, ok := toString(value)
 	if !ok {

internal/discovery/service.go

@@ -94,7 +94,7 @@ func (s *Service) DiscoverServers(ctx context.Context) ([]market.ServerDescripto
 
 	response, err := s.MarketClient.FetchServers(ctx, 200)
 	if err == nil {
-		servers := market.NormalizeServers(response, "live_market")
+		servers := market.NormalizeServersForBaseURL(response, "live_market", s.MarketClient.BaseURL)
 		_ = s.Cache.SaveRegistry(partition, cache.RegistrySnapshot{Servers: servers})
 		return servers, nil
 	}

internal/discovery/service_test.go

@@ -13,13 +13,13 @@ import (
 )
 
 // newTestMCPServer returns an httptest.Server that handles both market registry
-// and MCP JSON-RPC endpoints. marketOK controls whether /cli/discovery/apis/bamboo
+// and MCP JSON-RPC endpoints. marketOK controls whether /cli/discovery/apis/cedar
 // succeeds, and mcpOK controls whether initialize+tools/list succeed.
 func newTestMCPServer(t *testing.T, marketOK, mcpOK bool) *httptest.Server {
 	t.Helper()
 	mux := http.NewServeMux()
 
-	mux.HandleFunc("/cli/discovery/apis/bamboo", func(w http.ResponseWriter, r *http.Request) {
+	mux.HandleFunc("/cli/discovery/apis/cedar", func(w http.ResponseWriter, r *http.Request) {
 		if !marketOK {
 			http.Error(w, "market unavailable", http.StatusInternalServerError)
 			return

internal/errors/errors.go

@@ -21,6 +21,8 @@ import (
 	"io"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 )
 
@@ -309,7 +311,7 @@ func PrintJSON(w io.Writer, err error) error {
 	}
 	payload := map[string]any{"error": errorPayload}
 
-	data, marshalErr := json.MarshalIndent(payload, "", "  ")
+	data, marshalErr := jsonutil.MarshalIndent(payload, "", "  ")
 	if marshalErr != nil {
 		_, writeErr := fmt.Fprintf(w, "{\"error\":{\"code\":5,\"category\":\"internal\",\"message\":\"failed to encode error output\"}}\n")
 		return writeErr
@@ -344,25 +346,25 @@ func PrintHumanAt(w io.Writer, err error, v Verbosity) error {
 
 	var typed *Error
 	if !stderrors.As(err, &typed) {
-		_, writeErr := fmt.Fprintf(w, "Error: %s\n", err.Error())
+		_, writeErr := fmt.Fprintf(w, "%s %s\n", tui.StateMark("error"), tui.Danger("Error: "+err.Error()))
 		return writeErr
 	}
 
 	// Line 1: Error summary
 	lines := []string{
-		fmt.Sprintf("Error: [%s] %s", strings.ToUpper(string(typed.Category)), typed.Message),
+		fmt.Sprintf("%s %s", tui.StateMark("error"), tui.Danger(fmt.Sprintf("Error: [%s] %s", strings.ToUpper(string(typed.Category)), typed.Message))),
 	}
 
 	// Always shown: hint, actions, retryable
 	if typed.Hint != "" {
-		lines = append(lines, fmt.Sprintf("Hint: %s", typed.Hint))
+		lines = append(lines, tui.Cyan(fmt.Sprintf("Hint: %s", typed.Hint)))
 	}
 
 	// Add user-friendly hint for specific server error codes
 	switch typed.ServerDiag.ServerErrorCode {
 	case "TOKEN_VERIFIED_FAILED", "CLI_ORG_NOT_AUTHORIZED":
-		lines = append(lines, "Hint: 该组织尚未开启 CLI 数据访问权限，请联系组织主管理员开启。")
-		lines = append(lines, "Action: 开启地址: "+config.GetDeveloperSettingsURL())
+		lines = append(lines, tui.Cyan("Hint: 该组织尚未开启 CLI 数据访问权限，请联系组织主管理员开启。"))
+		lines = append(lines, tui.White("Action: 开启地址: "+config.GetDeveloperSettingsURL()))
 	}
 
 	if len(typed.Actions) > 0 {
@@ -370,53 +372,53 @@ func PrintHumanAt(w io.Writer, err error, v Verbosity) error {
 			if strings.TrimSpace(action) == "" {
 				continue
 			}
-			lines = append(lines, fmt.Sprintf("Action: %s", action))
+			lines = append(lines, tui.White(fmt.Sprintf("Action: %s", action)))
 		}
 	}
 	if line := formatAvailableFlagsHumanLine(typed.AvailableFlags); line != "" {
-		lines = append(lines, line)
+		lines = append(lines, tui.Dim(line))
 	}
 	if typed.Retryable {
-		lines = append(lines, "Retryable: true")
+		lines = append(lines, tui.Warning("Retryable: true"))
 	}
 
 	// Always shown when present: Trace ID, Server Code
 	if typed.ServerDiag.TraceID != "" {
-		lines = append(lines, fmt.Sprintf("Trace ID: %s", typed.ServerDiag.TraceID))
+		lines = append(lines, tui.Dim(fmt.Sprintf("Trace ID: %s", typed.ServerDiag.TraceID)))
 	}
 	if typed.ServerDiag.ServerErrorCode != "" {
-		lines = append(lines, fmt.Sprintf("Server Code: %s", typed.ServerDiag.ServerErrorCode))
+		lines = append(lines, tui.Dim(fmt.Sprintf("Server Code: %s", typed.ServerDiag.ServerErrorCode)))
 	}
 
 	// Verbose+: technical detail, snapshot, reason, server key
 	if v >= VerbosityVerbose {
 		if typed.ServerDiag.TechnicalDetail != "" {
-			lines = append(lines, fmt.Sprintf("Detail: %s", typed.ServerDiag.TechnicalDetail))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Detail: %s", typed.ServerDiag.TechnicalDetail)))
 		}
 		if typed.Reason != "" {
-			lines = append(lines, fmt.Sprintf("Reason: %s", typed.Reason))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Reason: %s", typed.Reason)))
 		}
 		if typed.ServerKey != "" {
-			lines = append(lines, fmt.Sprintf("Server: %s", typed.ServerKey))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Server: %s", typed.ServerKey)))
 		}
 		if typed.Snapshot != "" {
-			lines = append(lines, fmt.Sprintf("Snapshot: %s", typed.Snapshot))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Snapshot: %s", typed.Snapshot)))
 		}
 		if typed.Cause != nil {
-			lines = append(lines, fmt.Sprintf("Cause: %s", typed.Cause.Error()))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Cause: %s", typed.Cause.Error())))
 		}
 	}
 
 	// Debug: all internal diagnostics
 	if v >= VerbosityDebug {
 		if typed.Operation != "" {
-			lines = append(lines, fmt.Sprintf("Operation: %s", typed.Operation))
+			lines = append(lines, tui.Dim(fmt.Sprintf("Operation: %s", typed.Operation)))
 		}
 		if typed.RPCCode != 0 {
-			lines = append(lines, fmt.Sprintf("RPC Code: %d", typed.RPCCode))
+			lines = append(lines, tui.Dim(fmt.Sprintf("RPC Code: %d", typed.RPCCode)))
 		}
 		if len(typed.RPCData) > 0 {
-			lines = append(lines, fmt.Sprintf("RPC Data: %s", string(typed.RPCData)))
+			lines = append(lines, tui.Dim(fmt.Sprintf("RPC Data: %s", string(typed.RPCData))))
 		}
 	}
 

internal/errors/pat.go

@@ -21,6 +21,8 @@ import (
 	"net/url"
 	"strings"
 	"sync"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil"
 )
 
 // hostControlProvider returns the host-owned clawType for the current
@@ -105,12 +107,10 @@ const ExitCodePermission = 4
 // json.Unmarshal-able payload of the form
 // {"success":false,"code":<frozen enum>,"data":{...}}.
 //
-// When the payload includes data.uri, that URL is the authoritative
-// server-provided authorization link. Hosts must treat it as opaque and open
-// it verbatim instead of parsing and reconstructing it locally, because
-// required parameters may live in query, encoded hash, or fragment sections.
-// New hosts may prefer data.authorizationUrl when present; it preserves data.uri
-// while adding a copy/open-safe URL for legacy DingTalk hash-route variants.
+// When the payload includes data.uri/authUrl/authorizationUrl, that value is
+// the authoritative server-provided authorization link. The CLI accepts all
+// legacy aliases, normalizes the known DingTalk hash-route variant, and emits a
+// single data.uri field so terminals and hosts do not need to deduplicate links.
 type PATError struct {
 	RawJSON string
 }
@@ -147,6 +147,7 @@ var patNoPermissionCodes = map[string]bool{
 //     `dws auth login --scope <data.missingScope>`.
 var patAuthRequiredCodes = map[string]bool{
 	"AGENT_CODE_NOT_EXISTS":   true,
+	"PAT_BATCH_AUTH_PENDING":  true,
 	"PAT_SCOPE_AUTH_REQUIRED": true,
 }
 
@@ -241,7 +242,7 @@ func isBusinessError(body map[string]any) bool {
 // Check order: DWS gateway auth > PAT permission.
 func ClassifyToolResultContent(content map[string]any) error {
 	if _, ok := getDWSGatewayErrorCode(content); ok {
-		raw, _ := json.Marshal(content)
+		raw, _ := jsonutil.Marshal(content)
 		return NewAuth(string(raw),
 			WithReason("gateway_auth_expired"),
 			WithHint(authExpiredHint()),
@@ -353,8 +354,11 @@ func ApplyHostMutations(out map[string]any) {
 		data = map[string]any{}
 		out["data"] = data
 	}
-	if rawURI, ok := data["uri"].(string); ok && strings.TrimSpace(rawURI) != "" {
-		data["authorizationUrl"] = PATAuthorizationURL(rawURI)
+	if rawURI := patAuthorizationURIFromData(data); rawURI != "" {
+		authURL := PATAuthorizationURL(rawURI)
+		data["uri"] = authURL
+		delete(data, "authUrl")
+		delete(data, "authorizationUrl")
 	}
 	if block := HostControlBlock(); block != nil {
 		delete(data, "callbacks")
@@ -363,6 +367,16 @@ func ApplyHostMutations(out map[string]any) {
 	data["openBrowser"] = PATOpenBrowserValue()
 }
 
+func patAuthorizationURIFromData(data map[string]any) string {
+	for _, key := range []string{"uri", "authUrl", "authorizationUrl"} {
+		value, _ := data[key].(string)
+		if strings.TrimSpace(value) != "" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
 // PATAuthorizationURL returns the best URL for hosts to open or show to users.
 // It keeps already-complete PAT URLs unchanged. For DingTalk's legacy
 // /fe/old#%2FpersonalAuthorization?... hash-route form, it adds the explicit
@@ -443,9 +457,9 @@ func cleanPATJSON(body map[string]any, code string) string {
 		"code":    code,
 	}
 	if data, ok := body["data"]; ok {
-		// Keep data.uri exactly as returned by the service. Host consumers open
-		// that link directly, so local normalization would risk dropping
-		// parameters embedded in query/hash/fragment sections.
+		// ApplyHostMutations canonicalizes PAT URL aliases into one data.uri
+		// before JSON encoding, while stripClassFields keeps the rest of the
+		// service payload intact.
 		out["data"] = stripClassFields(data)
 	} else {
 		fallback := map[string]any{}

internal/errors/pat_test.go

@@ -378,6 +378,25 @@ func TestClassifyMCPResponseText_PATAuthRequired(t *testing.T) {
 	}
 }
 
+func TestClassifyMCPResponseText_PATBatchAuthPending(t *testing.T) {
+	t.Parallel()
+	text := `{"success":false,"code":"PAT_BATCH_AUTH_PENDING","data":{"flowId":"flow-1","uri":"https://example.test/auth"}}`
+	err := ClassifyMCPResponseText(text)
+	if err == nil {
+		t.Fatal("expected non-nil error")
+	}
+	var patErr *PATError
+	if !stderrors.As(err, &patErr) {
+		t.Fatalf("expected *PATError, got %T", err)
+	}
+	if !strings.Contains(patErr.RawJSON, "PAT_BATCH_AUTH_PENDING") {
+		t.Errorf("RawJSON should contain PAT_BATCH_AUTH_PENDING, got: %s", patErr.RawJSON)
+	}
+	if !strings.Contains(patErr.RawJSON, "flow-1") {
+		t.Errorf("RawJSON should preserve flowId, got: %s", patErr.RawJSON)
+	}
+}
+
 func TestClassifyMCPResponseText_BusinessError(t *testing.T) {
 	t.Parallel()
 	text := `{"success":false,"errorMsg":"搜索内容不能为空"}`
@@ -729,6 +748,12 @@ func TestCleanPATJSON_PreservesOpaqueURIVerbatim(t *testing.T) {
 	}
 
 	result := cleanPATJSON(body, "PAT_MEDIUM_RISK_NO_PERMISSION")
+	if strings.Contains(result, `\u0026`) {
+		t.Fatalf("cleanPATJSON escaped ampersands in URL: %s", result)
+	}
+	if !strings.Contains(result, "&userCode=Q8RY-X6E9") {
+		t.Fatalf("cleanPATJSON output missing literal ampersand route separator: %s", result)
+	}
 
 	if strings.Contains(result, `\u0026`) {
 		t.Fatalf("cleanPATJSON should keep URL ampersands readable for mobile copy/linkify, got: %s", result)
@@ -745,8 +770,40 @@ func TestCleanPATJSON_PreservesOpaqueURIVerbatim(t *testing.T) {
 	if got, _ := data["uri"].(string); got != rawURI {
 		t.Fatalf("data.uri = %q, want verbatim %q", got, rawURI)
 	}
-	if got, _ := data["authorizationUrl"].(string); got != rawURI {
-		t.Fatalf("data.authorizationUrl = %q, want %q", got, rawURI)
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted when data.uri is present")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted when data.uri is present")
+	}
+}
+
+func TestCleanPATJSON_BackfillsSingleURIFromAuthURL(t *testing.T) {
+	t.Parallel()
+	rawURI := "https://open-dev.dingtalk.com/fe/old?hash=%23%2FpersonalAuthorization%3FflowId%3D50dff7654b7444e88ced7489b07cce8d%26userCode%3DQ8RY-X6E9#/personalAuthorization?flowId=50dff7654b7444e88ced7489b07cce8d&userCode=Q8RY-X6E9"
+	body := map[string]any{
+		"success": false,
+		"code":    "PAT_BATCH_AUTH_PENDING",
+		"data": map[string]any{
+			"flowId":  "50dff7654b7444e88ced7489b07cce8d",
+			"authUrl": rawURI,
+		},
+	}
+
+	result := cleanPATJSON(body, "PAT_BATCH_AUTH_PENDING")
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(result), &parsed); err != nil {
+		t.Fatalf("unmarshal cleanPATJSON output: %v\nraw=%s", err, result)
+	}
+	data, _ := parsed["data"].(map[string]any)
+	if got, _ := data["uri"].(string); got != rawURI {
+		t.Fatalf("data.uri = %q, want %q", got, rawURI)
+	}
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted after backfilling data.uri")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted after backfilling data.uri")
 	}
 }
 
@@ -802,7 +859,7 @@ func TestPATAuthorizationURL_NormalizesLegacyHashRoutePreservesExtraQuery(t *tes
 	}
 }
 
-func TestCleanPATJSON_AddsNormalizedAuthorizationURL(t *testing.T) {
+func TestCleanPATJSON_NormalizesSingleURI(t *testing.T) {
 	t.Parallel()
 	rawURI := "https://open-dev.dingtalk.com/fe/old#%2FpersonalAuthorization%3FflowId%3D56b12fd3201d4efab9a9138672cf4deb%26userCode%3DCFTC-27ZN"
 	want := "https://open-dev.dingtalk.com/fe/old?hash=%23%2FpersonalAuthorization%3FflowId%3D56b12fd3201d4efab9a9138672cf4deb%26userCode%3DCFTC-27ZN#/personalAuthorization?flowId=56b12fd3201d4efab9a9138672cf4deb&userCode=CFTC-27ZN"
@@ -817,17 +874,26 @@ func TestCleanPATJSON_AddsNormalizedAuthorizationURL(t *testing.T) {
 	}
 
 	result := cleanPATJSON(body, "PAT_MEDIUM_RISK_NO_PERMISSION")
+	if strings.Contains(result, `\u0026`) {
+		t.Fatalf("cleanPATJSON escaped ampersands in normalized URL: %s", result)
+	}
+	if !strings.Contains(result, "&userCode=CFTC-27ZN") {
+		t.Fatalf("cleanPATJSON output missing literal ampersand route separator: %s", result)
+	}
 
 	var parsed map[string]any
 	if err := json.Unmarshal([]byte(result), &parsed); err != nil {
 		t.Fatalf("unmarshal cleanPATJSON output: %v\nraw=%s", err, result)
 	}
 	data, _ := parsed["data"].(map[string]any)
-	if got, _ := data["uri"].(string); got != rawURI {
-		t.Fatalf("data.uri = %q, want verbatim %q", got, rawURI)
+	if got, _ := data["uri"].(string); got != want {
+		t.Fatalf("data.uri = %q, want normalized %q", got, want)
 	}
-	if got, _ := data["authorizationUrl"].(string); got != want {
-		t.Fatalf("data.authorizationUrl = %q, want %q", got, want)
+	if _, ok := data["authUrl"]; ok {
+		t.Fatalf("data.authUrl should be omitted after normalizing data.uri")
+	}
+	if _, ok := data["authorizationUrl"]; ok {
+		t.Fatalf("data.authorizationUrl should be omitted after normalizing data.uri")
 	}
 }
 

internal/generator/cmd_snapshot/main.go

@@ -259,7 +259,7 @@ func newDocsMCPGateway(expectations []docsServerExpectation) *httptest.Server {
 	mux := http.NewServeMux()
 	server := httptest.NewServer(mux)
 
-	mux.HandleFunc("/cli/discovery/apis/bamboo", func(w http.ResponseWriter, r *http.Request) {
+	mux.HandleFunc("/cli/discovery/apis/cedar", func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet {
 			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 			return

internal/helpers/aitable.go

@@ -110,6 +110,7 @@ func (aitableHandler) Command(runner executor.Runner) *cobra.Command {
 		newAitableFieldCreateCommand(runner),
 		newAitableFieldUpdateCommand(runner),
 		newAitableFieldDeleteCommand(runner),
+		newAitableFieldSearchOptionsCommand(runner),
 		newAitableFieldListAlias(runner),
 	)
 
@@ -129,7 +130,13 @@ func (aitableHandler) Command(runner executor.Runner) *cobra.Command {
 		newAitableRecordCreateCommand(runner),
 		newAitableRecordUpdateCommand(runner),
 		newAitableRecordBatchUpdateCommand(runner),
+		newAitableRecordQueryEmptyCommand(runner),
 		newAitableRecordDeleteCommand(runner),
+		newAitableRecordHistoryListCommand(runner),
+		newAitableRecordShareURLCommand(runner),
+		newAitableRecordUpsertCommand(runner),
+		newAitableRecordPrimaryDocGetCommand(runner),
+		newAitableRecordPrimaryDocCreateCommand(runner),
 		newAitableRecordListAlias(runner),
 	)
 
@@ -251,6 +258,7 @@ func (aitableHandler) Command(runner executor.Runner) *cobra.Command {
 		newAitableDashboardUpdateCommand(runner),
 		newAitableDashboardDeleteCommand(runner),
 		newAitableDashboardConfigExampleCommand(runner),
+		newAitableDashboardArrangeCommand(runner),
 		dashboardShare,
 	)
 
@@ -264,15 +272,53 @@ func (aitableHandler) Command(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
+	viewGet := newAitableViewGetCommand(runner)
+	viewGet.AddCommand(
+		newAitableViewGetCardCommand(runner),
+		newAitableViewGetTimebarCommand(runner),
+		newAitableViewGetAggregateCommand(runner),
+		newAitableViewGetFilterCommand(runner),
+		newAitableViewGetSortCommand(runner),
+		newAitableViewGetGroupCommand(runner),
+		newAitableViewGetVisibleFieldsCommand(runner),
+		newAitableViewGetFieldWidthsCommand(runner),
+		newAitableViewGetLockCommand(runner),
+		newAitableViewGetFrozenColsCommand(runner),
+		newAitableViewGetRowHeightCommand(runner),
+		newAitableViewGetFillColorRuleCommand(runner),
+	)
+	viewUpdate := newAitableViewUpdateCommand(runner)
+	viewUpdate.AddCommand(
+		newAitableViewUpdateCardCommand(runner),
+		newAitableViewUpdateTimebarCommand(runner),
+		newAitableViewUpdateAggregateCommand(runner),
+		newAitableViewUpdateFieldWidthsCommand(runner),
+		newAitableViewUpdateVisibleFieldsCommand(runner),
+		newAitableViewUpdateFilterCommand(runner),
+		newAitableViewUpdateSortCommand(runner),
+		newAitableViewUpdateGroupCommand(runner),
+		newAitableViewUpdateNameCommand(runner),
+		newAitableViewUpdateFrozenColsCommand(runner),
+		newAitableViewUpdateRowHeightCommand(runner),
+		newAitableViewUpdateFillColorRuleCommand(runner),
+	)
 	view.AddCommand(
-		newAitableViewGetCommand(runner),
+		viewGet,
 		newAitableViewListCommand(runner),
 		newAitableViewCreateCommand(runner),
-		newAitableViewUpdateCommand(runner),
+		viewUpdate,
 		newAitableViewDeleteCommand(runner),
+		newAitableViewLockCommand(runner),
+		newAitableViewDuplicateCommand(runner),
 	)
 
-	root.AddCommand(base, table, field, record, newAitableFormCommand(runner), template, attachment, export, importCmd, dashboard, chart, view)
+	root.AddCommand(
+		base, table, field, record, newAitableFormCommand(runner),
+		newAitableWorkflowCommand(runner),
+		template, attachment, export, importCmd, dashboard, chart, view,
+		newAitableAdvpermCommand(runner),
+		newAitableSectionCommand(runner),
+	)
 
 	// 顶层别名：dws aitable search/list/create/info → base search/list/create/get
 	// 每个 alias 复用现有 constructor，独立 cobra.Command 实例（避免与 base.* 共享 flag 指针）

internal/helpers/aitable_commands.go

@@ -130,7 +130,33 @@ func newAitableBaseCreateCommand(runner executor.Runner) *cobra.Command {
 			if folderID := aitableStringFlag(cmd, "folder-id"); folderID != "" {
 				params["folderId"] = folderID
 			}
-			return runAitableTool(cmd, runner, "create_base", params)
+			// dry-run 或带模板：保持单步 create_base 语义。
+			if commandDryRun(cmd) {
+				return runAitableTool(cmd, runner, "create_base", params)
+			}
+			result, err := runAitableProductToolResult(cmd, runner, "aitable", "create_base", params)
+			if err != nil {
+				return err
+			}
+			// 默认表由服务端按 scenario 决定：wukong 场景建、openClaw 不建。
+			// 为与 wukong 行为对齐，无模板时在 CLI 侧兜底补建一张默认表，
+			// 使新 base 立即可用（含 tableId）。输出仍保持原 create_base 结果，
+			// 不把内部补建步骤暴露给调用方。
+			if _, hasTemplate := params["templateId"]; !hasTemplate {
+				if baseID := findStringDeep(result.Response, "baseId", "baseID"); baseID != "" {
+					if _, terr := runAitableProductToolResult(cmd, runner, "aitable", "create_table", map[string]any{
+						"baseId":    baseID,
+						"tableName": "表格1",
+						"fields": []any{map[string]any{
+							"fieldName": "标题",
+							"type":      "text",
+						}},
+					}); terr != nil {
+						fmt.Fprintf(cmd.ErrOrStderr(), "warning: created base %s but default table creation failed: %v\n", baseID, terr)
+					}
+				}
+			}
+			return writeCommandPayload(cmd, result)
 		},
 	}
 	preferLegacyLeaf(cmd)
@@ -1440,6 +1466,9 @@ func newAitableViewUpdateCommand(runner executor.Runner) *cobra.Command {
 				if err != nil {
 					return err
 				}
+				if err := normalizeAitableViewConfigBlock(cmd, config); err != nil {
+					return err
+				}
 				params["config"] = config
 			}
 			if _, hasName := params["newViewName"]; !hasName {
@@ -1499,6 +1528,14 @@ func runAitableFormTool(cmd *cobra.Command, runner executor.Runner, tool string,
 }
 
 func runAitableProductTool(cmd *cobra.Command, runner executor.Runner, product, tool string, params map[string]any) error {
+	result, err := runAitableProductToolResult(cmd, runner, product, tool, params)
+	if err != nil {
+		return err
+	}
+	return writeCommandPayload(cmd, result)
+}
+
+func runAitableProductToolResult(cmd *cobra.Command, runner executor.Runner, product, tool string, params map[string]any) (executor.Result, error) {
 	invocation := executor.NewHelperInvocation(
 		cobracmd.LegacyCommandPath(cmd),
 		product,
@@ -1509,9 +1546,9 @@ func runAitableProductTool(cmd *cobra.Command, runner executor.Runner, product,
 	if invocation.DryRun {
 		result, err := runner.Run(cmd.Context(), invocation)
 		if err != nil {
-			return err
+			return executor.Result{}, err
 		}
-		return writeCommandPayload(cmd, result)
+		return result, nil
 	}
 
 	var lastErr error
@@ -1523,7 +1560,7 @@ func runAitableProductTool(cmd *cobra.Command, runner executor.Runner, product,
 			select {
 			case <-cmd.Context().Done():
 				timer.Stop()
-				return cmd.Context().Err()
+				return executor.Result{}, cmd.Context().Err()
 			case <-timer.C:
 			}
 		}
@@ -1531,16 +1568,16 @@ func runAitableProductTool(cmd *cobra.Command, runner executor.Runner, product,
 		result, err := runner.Run(cmd.Context(), invocation)
 		lastErr = err
 		if err == nil {
-			return writeCommandPayload(cmd, result)
+			return result, nil
 		}
 		if !aitableErrorRetryable(err) {
-			return err
+			return executor.Result{}, err
 		}
 	}
 	if lastErr != nil {
-		return lastErr
+		return executor.Result{}, lastErr
 	}
-	return nil
+	return executor.Result{}, nil
 }
 
 const aitableHelperMaxRetries = 3
@@ -1906,11 +1943,15 @@ func normalizeAitableSort(items []any) []any {
 }
 
 func parseAitableJSONArray(raw, flagName string) ([]any, error) {
-	var value []any
+	var value any
 	if err := json.Unmarshal([]byte(raw), &value); err != nil {
 		return nil, apperrors.NewValidation(fmt.Sprintf("--%s JSON parse failed: %v", flagName, err))
 	}
-	return value, nil
+	arr, ok := value.([]any)
+	if !ok {
+		return nil, apperrors.NewValidation(fmt.Sprintf("--%s must be a JSON array / 数组, got %T", flagName, value))
+	}
+	return arr, nil
 }
 
 func parseAitableJSONObject(raw, flagName string) (map[string]any, error) {

internal/helpers/aitable_commands_test.go

@@ -1393,3 +1393,55 @@ func singleAitableRecord(t *testing.T, value any) map[string]any {
 	}
 	return record
 }
+
+// base create 无模板时，CLI 兜底补建一张默认表（与 wukong 场景行为对齐：
+// 服务端对 openClaw 不建默认表，CLI 侧补齐使新 base 立即含 tableId）。
+func TestAitableBaseCreateAddsDefaultTableWithoutTemplate(t *testing.T) {
+	t.Parallel()
+	runner := &aitableSequencedRunner{responses: []map[string]any{
+		{"data": map[string]any{"baseId": "BASE_001"}},
+		{"data": map[string]any{"tableId": "TABLE_001"}},
+	}}
+	cmd := newAitableBaseCreateCommand(runner)
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{"--name", "项目跟踪"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+	if len(runner.calls) != 2 {
+		t.Fatalf("calls = %d, want create_base + create_table", len(runner.calls))
+	}
+	if got := runner.calls[0].Tool; got != "create_base" {
+		t.Fatalf("first tool = %q, want create_base", got)
+	}
+	if got := runner.calls[1].Tool; got != "create_table" {
+		t.Fatalf("second tool = %q, want create_table", got)
+	}
+	if got := runner.calls[1].Params["baseId"]; got != "BASE_001" {
+		t.Fatalf("create_table baseId = %#v, want BASE_001", got)
+	}
+}
+
+// base create 带 --template-id 时不补建默认表（模板自带结构）。
+func TestAitableBaseCreateWithTemplateSkipsDefaultTable(t *testing.T) {
+	t.Parallel()
+	runner := &aitableSequencedRunner{responses: []map[string]any{
+		{"data": map[string]any{"baseId": "BASE_001"}},
+	}}
+	cmd := newAitableBaseCreateCommand(runner)
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{"--name", "项目跟踪", "--template-id", "TPL_001"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+	if len(runner.calls) != 1 {
+		t.Fatalf("calls = %d, want only create_base", len(runner.calls))
+	}
+	if got := runner.calls[0].Tool; got != "create_base" {
+		t.Fatalf("tool = %q, want create_base", got)
+	}
+}

internal/helpers/aitable_extra_test.go

@@ -0,0 +1,420 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/spf13/cobra"
+)
+
+func executeAitableExtraCommand(t *testing.T, cmd *cobra.Command, args ...string) {
+	t.Helper()
+
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs(args)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+}
+
+type aitableSequencedRunner struct {
+	calls     []executor.Invocation
+	responses []map[string]any
+}
+
+func (r *aitableSequencedRunner) Run(_ context.Context, invocation executor.Invocation) (executor.Result, error) {
+	r.calls = append(r.calls, invocation)
+	var response map[string]any
+	if idx := len(r.calls) - 1; idx >= 0 && idx < len(r.responses) {
+		response = r.responses[idx]
+	}
+	return executor.Result{Invocation: invocation, Response: response}, nil
+}
+
+func TestAitableFieldSearchOptionsRoutesToAitable(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableFieldSearchOptionsCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--field-id", "FIELD_001",
+		"--keyword", "已",
+		"--limit", "10",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable" {
+		t.Fatalf("CanonicalProduct = %q, want aitable", got)
+	}
+	if got := runner.last.Tool; got != "search_field_options" {
+		t.Fatalf("Tool = %q, want search_field_options", got)
+	}
+	if got := runner.last.Params["keyword"]; got != "已" {
+		t.Fatalf("keyword = %#v, want 已", got)
+	}
+	if got := runner.last.Params["limit"]; got != 10 {
+		t.Fatalf("limit = %#v, want 10", got)
+	}
+}
+
+func TestAitableViewGetFieldWidthsProjectsCustomWidthMap(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableSequencedRunner{responses: []map[string]any{{
+		"content": map[string]any{
+			"status": "success",
+			"data": map[string]any{"views": []any{map[string]any{
+				"viewId":   "VIEW_001",
+				"viewType": "Grid",
+				"custom": map[string]any{
+					"widthMap": map[string]any{"FIELD_001": 240},
+				},
+			}}},
+		},
+	}}}
+	cmd := newAitableViewGetFieldWidthsCommand(runner)
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--view-id", "VIEW_001",
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(out.Bytes(), &payload); err != nil {
+		t.Fatalf("output JSON parse error = %v\nstdout:\n%s", err, out.String())
+	}
+	data, ok := payload["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("data = %#v, want object", payload["data"])
+	}
+	if got := data["FIELD_001"]; got != float64(240) {
+		t.Fatalf("FIELD_001 width = %#v, want 240", got)
+	}
+}
+
+func TestAitableViewUpdateCardDispatchesGalleryConfig(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableSequencedRunner{responses: []map[string]any{
+		{"content": map[string]any{
+			"status": "success",
+			"data": map[string]any{"views": []any{map[string]any{
+				"viewId":   "VIEW_001",
+				"viewType": "Gallery",
+			}}},
+		}},
+		{"content": map[string]any{"status": "success"}},
+	}}
+	cmd := newAitableViewUpdateCardCommand(runner)
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--view-id", "VIEW_001",
+		"--cover-mode", "custom",
+		"--cover-field-id", "FIELD_001",
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+	if len(runner.calls) != 2 {
+		t.Fatalf("calls = %d, want 2", len(runner.calls))
+	}
+	update := runner.calls[1]
+	if update.Tool != "update_view" {
+		t.Fatalf("second tool = %q, want update_view", update.Tool)
+	}
+	config, ok := update.Params["config"].(map[string]any)
+	if !ok {
+		t.Fatalf("config = %#v, want object", update.Params["config"])
+	}
+	card, ok := config["galleryCard"].(map[string]any)
+	if !ok {
+		t.Fatalf("galleryCard = %#v, want object", config["galleryCard"])
+	}
+	if got := card["coverMode"]; got != "custom" {
+		t.Fatalf("coverMode = %#v, want custom", got)
+	}
+}
+
+func TestAitableViewUpdateConfigRoutedKeyHintsSubcommand(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableViewUpdateCommand(runner)
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--view-id", "VIEW_001",
+		"--config", `{"frozenColCount":2}`,
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\nstderr:\n%s", err, errOut.String())
+	}
+	if !strings.Contains(errOut.String(), "frozen-cols") {
+		t.Fatalf("stderr missing frozen-cols hint:\n%s", errOut.String())
+	}
+}
+
+func TestAitableRecordHistoryListRoutesToHelper(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableRecordHistoryListCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--record-id", "REC_001",
+		"--offset", "10",
+		"--limit", "30",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "query_record_history" {
+		t.Fatalf("Tool = %q, want query_record_history", got)
+	}
+	if got := runner.last.Params["recordId"]; got != "REC_001" {
+		t.Fatalf("recordId = %#v, want REC_001", got)
+	}
+	if got := runner.last.Params["offset"]; got != 10 {
+		t.Fatalf("offset = %#v, want 10", got)
+	}
+	if got := runner.last.Params["limit"]; got != 30 {
+		t.Fatalf("limit = %#v, want 30", got)
+	}
+}
+
+func TestAitableRecordUpsertAcceptsFieldsAlias(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableRecordUpsertCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--fields", `[{"recordId":"REC_001","cells":{"fld":"updated"}},{"cells":{"fld":"new"}}]`,
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "record_upsert" {
+		t.Fatalf("Tool = %q, want record_upsert", got)
+	}
+	records, ok := runner.last.Params["records"].([]any)
+	if !ok {
+		t.Fatalf("records type = %T, want []any", runner.last.Params["records"])
+	}
+	if len(records) != 2 {
+		t.Fatalf("records len = %d, want 2", len(records))
+	}
+}
+
+func TestAitableViewExtraCommandsRouteToExpectedTools(t *testing.T) {
+	t.Parallel()
+
+	t.Run("lock unlock", func(t *testing.T) {
+		t.Parallel()
+		runner := &aitableCommandRunner{}
+		cmd := newAitableViewLockCommand(runner)
+		executeAitableExtraCommand(t, cmd,
+			"--base-id", "BASE_001",
+			"--table-id", "TABLE_001",
+			"--view-id", "VIEW_001",
+			"--off",
+		)
+		if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+			t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+		}
+		if got := runner.last.Tool; got != "lock_or_unlock_view" {
+			t.Fatalf("Tool = %q, want lock_or_unlock_view", got)
+		}
+		if got := runner.last.Params["action"]; got != "unlock" {
+			t.Fatalf("action = %#v, want unlock", got)
+		}
+	})
+
+	t.Run("fill color rule", func(t *testing.T) {
+		t.Parallel()
+		runner := &aitableCommandRunner{}
+		cmd := newAitableViewUpdateFillColorRuleCommand(runner)
+		executeAitableExtraCommand(t, cmd,
+			"--base-id", "BASE_001",
+			"--table-id", "TABLE_001",
+			"--view-id", "VIEW_001",
+			"--json", `[]`,
+		)
+		if got := runner.last.CanonicalProduct; got != "aitable" {
+			t.Fatalf("CanonicalProduct = %q, want aitable", got)
+		}
+		if got := runner.last.Tool; got != "set_view_fill_color_rule" {
+			t.Fatalf("Tool = %q, want set_view_fill_color_rule", got)
+		}
+		if formats, ok := runner.last.Params["conditionalFormats"].([]any); !ok || len(formats) != 0 {
+			t.Fatalf("conditionalFormats = %#v, want empty []any", runner.last.Params["conditionalFormats"])
+		}
+	})
+}
+
+func TestAitableWorkflowListRoutesToHelper(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableWorkflowListCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--limit", "50",
+		"--offset", "100",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "list_workflows" {
+		t.Fatalf("Tool = %q, want list_workflows", got)
+	}
+	if got := runner.last.Params["limit"]; got != 50 {
+		t.Fatalf("limit = %#v, want 50", got)
+	}
+	if got := runner.last.Params["offset"]; got != 100 {
+		t.Fatalf("offset = %#v, want 100", got)
+	}
+}
+
+func TestAitableRecordQueryEmptyRoutesToHelper(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableRecordQueryEmptyCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--limit", "50",
+		"--cursor", "CUR_001",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "query_empty_records" {
+		t.Fatalf("Tool = %q, want query_empty_records", got)
+	}
+	if got := runner.last.Params["limit"]; got != 50 {
+		t.Fatalf("limit = %#v, want 50", got)
+	}
+	if got := runner.last.Params["cursor"]; got != "CUR_001" {
+		t.Fatalf("cursor = %#v, want CUR_001", got)
+	}
+}
+
+func TestAitableRecordQueryEmptyRejectsOutOfRangeLimit(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableRecordQueryEmptyCommand(runner)
+	cmd.SetArgs([]string{
+		"--base-id", "BASE_001",
+		"--table-id", "TABLE_001",
+		"--limit", "200",
+	})
+	cmd.SetOut(&bytes.Buffer{})
+	cmd.SetErr(&bytes.Buffer{})
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("expected error for --limit 200, got nil")
+	}
+	if runner.last.Tool != "" {
+		t.Fatalf("runner should not be called on invalid limit, got tool %q", runner.last.Tool)
+	}
+}
+
+func TestAitableDashboardArrangeRoutesToHelper(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableDashboardArrangeCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--dashboard-id", "DASH_001",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "align_dashboard" {
+		t.Fatalf("Tool = %q, want align_dashboard", got)
+	}
+	if got := runner.last.Params["dashboardId"]; got != "DASH_001" {
+		t.Fatalf("dashboardId = %#v, want DASH_001", got)
+	}
+}
+
+func TestAitableAdvpermRoleCreateParsesSubRoles(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableAdvpermRoleCreateCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--name", "市场可读",
+		"--sub-roles", `[{"targetId":"TABLE_001","targetType":"sheet","authLevel":"read"}]`,
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "create_role" {
+		t.Fatalf("Tool = %q, want create_role", got)
+	}
+	subRoles, ok := runner.last.Params["subRoles"].([]any)
+	if !ok || len(subRoles) != 1 {
+		t.Fatalf("subRoles = %#v, want single-item []any", runner.last.Params["subRoles"])
+	}
+}
+
+func TestAitableSectionMoveNodeAllowsRootParent(t *testing.T) {
+	t.Parallel()
+
+	runner := &aitableCommandRunner{}
+	cmd := newAitableSectionMoveNodeCommand(runner)
+	executeAitableExtraCommand(t, cmd,
+		"--base-id", "BASE_001",
+		"--node-id", "NODE_001",
+		"--new-parent-section-id", "",
+		"--target-index", "0",
+	)
+
+	if got := runner.last.CanonicalProduct; got != "aitable-helper" {
+		t.Fatalf("CanonicalProduct = %q, want aitable-helper", got)
+	}
+	if got := runner.last.Tool; got != "move_nsheet_node" {
+		t.Fatalf("Tool = %q, want move_nsheet_node", got)
+	}
+	if got := runner.last.Params["newParentSectionId"]; got != "" {
+		t.Fatalf("newParentSectionId = %#v, want empty string", got)
+	}
+	if got := runner.last.Params["targetIndex"]; got != 0 {
+		t.Fatalf("targetIndex = %#v, want 0", got)
+	}
+}

internal/helpers/calendar_commands.go

@@ -0,0 +1,167 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/i18n"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	RegisterPublic(func() Handler { return calendarHandler{} })
+}
+
+// calendarHandler contributes the `calendar attendee list|add|delete` group.
+// wukong renamed the calendar participant commands to "attendee" (former name:
+// participant); the envelope still exposes them under "participant". These
+// leaves call the same MCP tools (get/add/remove_calendar_participant) so the
+// wukong command surface is aligned without dropping the legacy participant
+// path. MergeCommandTree folds the attendee group into the calendar tree.
+type calendarHandler struct{}
+
+func (calendarHandler) Name() string { return "calendar" }
+
+func (calendarHandler) Command(runner executor.Runner) *cobra.Command {
+	root := &cobra.Command{
+		Use:               "calendar",
+		Short:             i18n.T("日历"),
+		Args:              cobra.NoArgs,
+		TraverseChildren:  true,
+		DisableAutoGenTag: true,
+		RunE:              func(cmd *cobra.Command, args []string) error { return cmd.Help() },
+	}
+	attendee := &cobra.Command{
+		Use:               "attendee",
+		Short:             i18n.T("参会人管理（与 participant 等价，对齐 wukong 命名）"),
+		Args:              cobra.NoArgs,
+		TraverseChildren:  true,
+		DisableAutoGenTag: true,
+		RunE:              func(cmd *cobra.Command, args []string) error { return cmd.Help() },
+	}
+	attendee.AddCommand(
+		newCalendarAttendeeListCommand(runner),
+		newCalendarAttendeeAddCommand(runner),
+		newCalendarAttendeeDeleteCommand(runner),
+	)
+	root.AddCommand(attendee)
+	return root
+}
+
+func newCalendarAttendeeListCommand(runner executor.Runner) *cobra.Command {
+	cmd := &cobra.Command{
+		Use: "list", Short: i18n.T("查询日程参会人"),
+		Example: "  dws calendar attendee list --event <eventId>", Args: cobra.NoArgs, DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			eventID := strings.TrimSpace(firstNonEmptyFlag(cmd, "event", "event-id"))
+			if eventID == "" {
+				return apperrors.NewValidation("missing required flag(s): --event")
+			}
+			params := map[string]any{"eventId": eventID}
+			if v := strings.TrimSpace(firstNonEmptyFlag(cmd, "calendar-id", "calendarId")); v != "" {
+				params["calendarId"] = v
+			}
+			return runCalendarTool(cmd, runner, "get_calendar_participants", params)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("event", "", i18n.T("日程 eventId (必填)"))
+	cmd.Flags().String("calendar-id", "", i18n.T("日历 ID (可选, 默认主日历)"))
+	return cmd
+}
+
+func newCalendarAttendeeAddCommand(runner executor.Runner) *cobra.Command {
+	cmd := &cobra.Command{
+		Use: "add", Short: i18n.T("添加日程参会人"),
+		Example: "  dws calendar attendee add --event <eventId> --users userId1,userId2", Args: cobra.NoArgs, DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			eventID := strings.TrimSpace(firstNonEmptyFlag(cmd, "event", "event-id"))
+			users := strings.TrimSpace(firstNonEmptyFlag(cmd, "users", "attendees", "user-ids"))
+			if eventID == "" {
+				return apperrors.NewValidation("missing required flag(s): --event")
+			}
+			if users == "" {
+				return apperrors.NewValidation("missing required flag(s): --users")
+			}
+			params := map[string]any{"eventId": eventID, "attendeesToAdd": csvToList(users)}
+			if v := strings.TrimSpace(firstNonEmptyFlag(cmd, "optional")); v != "" {
+				params["optional"] = v
+			}
+			if v := strings.TrimSpace(firstNonEmptyFlag(cmd, "calendar-id", "calendarId")); v != "" {
+				params["calendarId"] = v
+			}
+			return runCalendarTool(cmd, runner, "add_calendar_participant", params)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("event", "", i18n.T("日程 eventId (必填)"))
+	cmd.Flags().String("users", "", i18n.T("参会人 userId 列表，逗号分隔 (必填)"))
+	cmd.Flags().String("optional", "", i18n.T("是否可选参会人 (可选)"))
+	cmd.Flags().String("calendar-id", "", i18n.T("日历 ID (可选)"))
+	return cmd
+}
+
+func newCalendarAttendeeDeleteCommand(runner executor.Runner) *cobra.Command {
+	cmd := &cobra.Command{
+		Use: "delete", Short: i18n.T("移除日程参会人"),
+		Example: "  dws calendar attendee delete --event <eventId> --users userId1", Args: cobra.NoArgs, DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			eventID := strings.TrimSpace(firstNonEmptyFlag(cmd, "event", "event-id"))
+			users := strings.TrimSpace(firstNonEmptyFlag(cmd, "users", "attendees", "user-ids"))
+			if eventID == "" {
+				return apperrors.NewValidation("missing required flag(s): --event")
+			}
+			if users == "" {
+				return apperrors.NewValidation("missing required flag(s): --users")
+			}
+			params := map[string]any{"eventId": eventID, "attendeesToRemove": csvToList(users)}
+			if v := strings.TrimSpace(firstNonEmptyFlag(cmd, "calendar-id", "calendarId")); v != "" {
+				params["calendarId"] = v
+			}
+			return runCalendarTool(cmd, runner, "remove_calendar_participant", params)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("event", "", i18n.T("日程 eventId (必填)"))
+	cmd.Flags().String("users", "", i18n.T("参会人 userId 列表，逗号分隔 (必填)"))
+	cmd.Flags().String("calendar-id", "", i18n.T("日历 ID (可选)"))
+	return cmd
+}
+
+func runCalendarTool(cmd *cobra.Command, runner executor.Runner, tool string, params map[string]any) error {
+	inv := executor.NewHelperInvocation(cobracmd.LegacyCommandPath(cmd), "calendar", tool, params)
+	if commandDryRun(cmd) {
+		return writeCommandPayload(cmd, inv)
+	}
+	result, err := runner.Run(cmd.Context(), inv)
+	if err != nil {
+		return err
+	}
+	return writeCommandPayload(cmd, result)
+}
+
+func csvToList(s string) []any {
+	parts := strings.Split(s, ",")
+	out := make([]any, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}

internal/helpers/chat.go

@@ -121,7 +121,7 @@ func (chatHandler) Command(runner executor.Runner) *cobra.Command {
 		newChatBotSearchCommand(runner),
 	)
 
-	root.AddCommand(message, group, bot)
+	root.AddCommand(message, group, bot, newChatFileGroup(runner))
 	return root
 }
 

internal/helpers/chat_file.go

@@ -0,0 +1,206 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/spf13/cobra"
+)
+
+// newChatFileGroup builds `dws chat file upload`. wukong implements it as a
+// multi-step upload to the conversation file space: for --file it does
+// init_conversation_file_upload (im) -> HTTP PUT -> commit_conversation_file_upload
+// (im); for --url it calls upload_conversation_file_by_url (chat). The envelope
+// cannot express the local pipeline, so it lives here. Wired into the chat
+// handler (see chat.go).
+func newChatFileGroup(runner executor.Runner) *cobra.Command {
+	file := &cobra.Command{
+		Use:               "file",
+		Short:             "会话文件上传",
+		Args:              cobra.NoArgs,
+		TraverseChildren:  true,
+		DisableAutoGenTag: true,
+		RunE:              func(cmd *cobra.Command, args []string) error { return cmd.Help() },
+	}
+	file.AddCommand(newChatFileUploadCommand(runner))
+	return file
+}
+
+func newChatFileUploadCommand(runner executor.Runner) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "upload",
+		Short: "上传本地文件或 URL 文件到会话文件空间",
+		Example: "  dws chat file upload --group <openConversationId> --file ./report.pdf\n" +
+			"  dws chat file upload --user <userId> --url https://example.com/a.pdf --file-name a.pdf",
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			target, err := chatConversationTargetArgs(cmd)
+			if err != nil {
+				return err
+			}
+			filePath := strings.TrimSpace(firstNonEmptyFlag(cmd, "file", "file-path"))
+			fileURL := strings.TrimSpace(firstNonEmptyFlag(cmd, "url"))
+			if filePath == "" && fileURL == "" {
+				return apperrors.NewValidation("--file or --url is required")
+			}
+			if filePath != "" && fileURL != "" {
+				return apperrors.NewValidation("--file and --url are mutually exclusive")
+			}
+			fileName := strings.TrimSpace(firstNonEmptyFlag(cmd, "file-name"))
+			md5v := strings.TrimSpace(firstNonEmptyFlag(cmd, "md5"))
+			uuid := strings.TrimSpace(firstNonEmptyFlag(cmd, "uuid"))
+
+			// URL path: server pulls the file (chat server).
+			if fileURL != "" {
+				if fileName == "" {
+					fileName = filepath.Base(fileURL)
+				}
+				params := cloneStringAnyMap(target)
+				params["fileUrl"] = fileURL
+				params["fileName"] = fileName
+				if md5v != "" {
+					params["md5"] = md5v
+				}
+				if uuid != "" {
+					params["uuid"] = uuid
+				}
+				inv := executor.NewHelperInvocation(cobracmd.LegacyCommandPath(cmd), "chat", "upload_conversation_file_by_url", params)
+				if commandDryRun(cmd) {
+					return writeCommandPayload(cmd, inv)
+				}
+				result, err := runner.Run(cmd.Context(), inv)
+				if err != nil {
+					return err
+				}
+				return writeCommandPayload(cmd, result)
+			}
+
+			// Local path: init (im) -> HTTP PUT -> commit (im).
+			fi, err := os.Stat(filePath)
+			if err != nil {
+				return apperrors.NewValidation("cannot read file " + filePath + ": " + err.Error())
+			}
+			if fi.IsDir() {
+				return apperrors.NewValidation(filePath + " is a directory, not a file")
+			}
+			if fileName == "" {
+				fileName = filepath.Base(filePath)
+			}
+			fileSize := fi.Size()
+			if md5v == "" {
+				if md5v, err = fileMD5Hex(filePath); err != nil {
+					return err
+				}
+			}
+			if commandDryRun(cmd) {
+				preview := cloneStringAnyMap(target)
+				preview["fileName"] = fileName
+				preview["fileSize"] = fileSize
+				preview["md5"] = md5v
+				return writeCommandPayload(cmd, executor.NewHelperInvocation(
+					cobracmd.LegacyCommandPath(cmd), "im", "init_conversation_file_upload", preview))
+			}
+
+			ctx, cancel := context.WithTimeout(cmd.Context(), 10*time.Minute)
+			defer cancel()
+
+			initParams := cloneStringAnyMap(target)
+			initParams["fileName"] = fileName
+			initParams["fileSize"] = fileSize
+			initParams["md5"] = md5v
+			initRes, err := runner.Run(ctx, executor.NewHelperInvocation(
+				cobracmd.LegacyCommandPath(cmd), "im", "init_conversation_file_upload", initParams))
+			if err != nil {
+				return err
+			}
+			resourceURL := findStringDeep(initRes.Response, "resourceUrl", "resourceURL", "url")
+			if resourceURL == "" {
+				resourceURL = findFirstInStringArrayDeep(initRes.Response, "resourceUrls", "resourceURLs")
+			}
+			uploadKey := findStringDeep(initRes.Response, "uploadKey", "key")
+			if resourceURL == "" || uploadKey == "" {
+				return apperrors.NewAPI("incomplete upload credentials: resourceUrl=" + resourceURL + " uploadKey=" + uploadKey)
+			}
+			headers := findHeadersDeep(initRes.Response, "headers", "ossHeaders")
+			if err := httpPutLocalFile(ctx, resourceURL, headers, filePath, fileSize); err != nil {
+				return err
+			}
+
+			commitParams := cloneStringAnyMap(target)
+			commitParams["uploadKey"] = uploadKey
+			commitParams["fileName"] = fileName
+			commitParams["fileSize"] = fileSize
+			commitParams["md5"] = md5v
+			if uuid != "" {
+				commitParams["uuid"] = uuid
+			}
+			commitRes, err := runner.Run(ctx, executor.NewHelperInvocation(
+				cobracmd.LegacyCommandPath(cmd), "im", "commit_conversation_file_upload", commitParams))
+			if err != nil {
+				return err
+			}
+			return writeCommandPayload(cmd, commitRes)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("group", "", "群聊 openConversationId（群聊时使用）")
+	cmd.Flags().String("conversation-id", "", "--group 的别名")
+	cmd.Flags().String("id", "", "--group 的别名")
+	cmd.Flags().String("user", "", "单聊对方 userId（单聊时使用）")
+	cmd.Flags().String("open-dingtalk-id", "", "单聊对方 openDingTalkId（单聊时使用）")
+	cmd.Flags().String("file", "", "本地文件路径（与 --url 二选一）")
+	cmd.Flags().String("file-path", "", "--file 的别名")
+	cmd.Flags().String("url", "", "远程文件 URL（与 --file 二选一，服务端代传）")
+	cmd.Flags().String("file-name", "", "文件名（可选）")
+	cmd.Flags().String("md5", "", "文件 MD5（可选，本地不传自动计算）")
+	cmd.Flags().String("uuid", "", "幂等 UUID（可选）")
+	return cmd
+}
+
+func chatConversationTargetArgs(cmd *cobra.Command) (map[string]any, error) {
+	group := strings.TrimSpace(firstNonEmptyFlag(cmd, "group", "conversation-id", "id"))
+	user := strings.TrimSpace(firstNonEmptyFlag(cmd, "user"))
+	openDingTalkID := strings.TrimSpace(firstNonEmptyFlag(cmd, "open-dingtalk-id"))
+	if group == "" && user == "" && openDingTalkID == "" {
+		return nil, apperrors.NewValidation("需指定会话目标：--group（群聊）或 --user / --open-dingtalk-id（单聊）之一")
+	}
+	m := map[string]any{}
+	if group != "" {
+		m["openConversationId"] = group
+	}
+	if user != "" {
+		m["userId"] = user
+	}
+	if openDingTalkID != "" {
+		m["openDingTalkId"] = openDingTalkID
+	}
+	return m, nil
+}
+
+func cloneStringAnyMap(in map[string]any) map[string]any {
+	out := make(map[string]any, len(in)+4)
+	for k, v := range in {
+		out[k] = v
+	}
+	return out
+}

internal/helpers/connect_acl.go

@@ -0,0 +1,115 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"strings"
+	"sync"
+	"time"
+)
+
+// connectGate enforces the connector's access policy: optional user/group
+// allowlists plus a per-sender rate limit. A long-lived Q&A bot is otherwise
+// drivable (and billable — every message is an LLM call) by anyone who can
+// reach it in a group.
+type connectGate struct {
+	allowedUsers  map[string]struct{}
+	allowedGroups map[string]struct{}
+	perMinute     int
+
+	mu   sync.Mutex
+	hits map[string][]time.Time
+	now  func() time.Time // test hook
+}
+
+// splitCommaList splits a comma-separated flag/env value, trimming blanks.
+func splitCommaList(s string) []string {
+	var out []string
+	for _, p := range strings.Split(s, ",") {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// newConnectGate builds a gate from staffId / openConversationId allowlists
+// and a per-sender messages-per-minute cap (0 = unlimited).
+func newConnectGate(users, groups []string, perMinute int) *connectGate {
+	g := &connectGate{perMinute: perMinute, hits: map[string][]time.Time{}, now: time.Now}
+	for _, u := range users {
+		if u = strings.TrimSpace(u); u != "" {
+			if g.allowedUsers == nil {
+				g.allowedUsers = map[string]struct{}{}
+			}
+			g.allowedUsers[u] = struct{}{}
+		}
+	}
+	for _, grp := range groups {
+		if grp = strings.TrimSpace(grp); grp != "" {
+			if g.allowedGroups == nil {
+				g.allowedGroups = map[string]struct{}{}
+			}
+			g.allowedGroups[grp] = struct{}{}
+		}
+	}
+	return g
+}
+
+// enabled reports whether any policy is configured at all.
+func (g *connectGate) enabled() bool {
+	return g != nil && (len(g.allowedUsers) > 0 || len(g.allowedGroups) > 0 || g.perMinute > 0)
+}
+
+// allow reports whether a message may proceed; on denial, reason names the
+// rule that fired (for the connector log). Group messages must pass the group
+// allowlist AND, when a user allowlist is set, the sender allowlist too.
+func (g *connectGate) allow(staffID, convType, convID string) (bool, string) {
+	if g == nil {
+		return true, ""
+	}
+	if convType == "2" && len(g.allowedGroups) > 0 {
+		if _, ok := g.allowedGroups[convID]; !ok {
+			return false, "group-not-allowed"
+		}
+	}
+	if len(g.allowedUsers) > 0 {
+		if _, ok := g.allowedUsers[staffID]; !ok {
+			return false, "user-not-allowed"
+		}
+	}
+	if g.perMinute > 0 && staffID != "" {
+		g.mu.Lock()
+		defer g.mu.Unlock()
+		now := g.now()
+		cutoff := now.Add(-time.Minute)
+		kept := g.hits[staffID][:0]
+		for _, t := range g.hits[staffID] {
+			if t.After(cutoff) {
+				kept = append(kept, t)
+			}
+		}
+		if len(kept) >= g.perMinute {
+			g.hits[staffID] = kept
+			return false, "rate-limited"
+		}
+		g.hits[staffID] = append(kept, now)
+		// Bound memory against sender-id churn: keep only the current sender
+		// when the map grows absurdly large.
+		if len(g.hits) > 4096 {
+			g.hits = map[string][]time.Time{staffID: g.hits[staffID]}
+		}
+	}
+	return true, ""
+}

internal/helpers/connect_acl_test.go

@@ -0,0 +1,97 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"testing"
+	"time"
+)
+
+func TestConnectGateAllowlists(t *testing.T) {
+	cases := []struct {
+		name       string
+		users      []string
+		groups     []string
+		staff      string
+		convType   string
+		convID     string
+		wantOK     bool
+		wantReason string
+	}{
+		{"no policy allows everyone", nil, nil, "u1", "1", "", true, ""},
+		{"user in list", []string{"u1", "u2"}, nil, "u1", "1", "", true, ""},
+		{"user not in list", []string{"u1"}, nil, "u9", "1", "", false, "user-not-allowed"},
+		{"group in list", nil, []string{"cid-a"}, "u9", "2", "cid-a", true, ""},
+		{"group not in list", nil, []string{"cid-a"}, "u9", "2", "cid-b", false, "group-not-allowed"},
+		{"group list does not gate DMs", nil, []string{"cid-a"}, "u9", "1", "", true, ""},
+		{"both lists: group ok user not", []string{"u1"}, []string{"cid-a"}, "u9", "2", "cid-a", false, "user-not-allowed"},
+		{"both lists: both ok", []string{"u1"}, []string{"cid-a"}, "u1", "2", "cid-a", true, ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			g := newConnectGate(tc.users, tc.groups, 0)
+			ok, reason := g.allow(tc.staff, tc.convType, tc.convID)
+			if ok != tc.wantOK || reason != tc.wantReason {
+				t.Fatalf("allow = (%v, %q), want (%v, %q)", ok, reason, tc.wantOK, tc.wantReason)
+			}
+		})
+	}
+}
+
+func TestConnectGateRateLimit(t *testing.T) {
+	g := newConnectGate(nil, nil, 2)
+	now := time.Unix(1_700_000_000, 0)
+	g.now = func() time.Time { return now }
+
+	for i := 0; i < 2; i++ {
+		if ok, _ := g.allow("u1", "1", ""); !ok {
+			t.Fatalf("message %d should pass", i+1)
+		}
+	}
+	if ok, reason := g.allow("u1", "1", ""); ok || reason != "rate-limited" {
+		t.Fatalf("3rd message = (%v, %q), want rate-limited", ok, reason)
+	}
+	// Another sender is unaffected.
+	if ok, _ := g.allow("u2", "1", ""); !ok {
+		t.Fatal("other sender should pass")
+	}
+	// The window slides: a minute later the sender passes again.
+	now = now.Add(61 * time.Second)
+	if ok, _ := g.allow("u1", "1", ""); !ok {
+		t.Fatal("after window slides the sender should pass")
+	}
+}
+
+func TestConnectGateDisabled(t *testing.T) {
+	var nilGate *connectGate
+	if nilGate.enabled() {
+		t.Fatal("nil gate must report disabled")
+	}
+	if ok, _ := nilGate.allow("u", "1", ""); !ok {
+		t.Fatal("nil gate must allow")
+	}
+	if newConnectGate(nil, nil, 0).enabled() {
+		t.Fatal("empty gate must report disabled")
+	}
+}
+
+func TestSplitCommaList(t *testing.T) {
+	got := splitCommaList(" a, b ,, c ")
+	if len(got) != 3 || got[0] != "a" || got[1] != "b" || got[2] != "c" {
+		t.Fatalf("splitCommaList = %v", got)
+	}
+	if splitCommaList("") != nil {
+		t.Fatal("empty input should yield nil")
+	}
+}

internal/helpers/connect_agent_options_test.go

@@ -0,0 +1,239 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeExecStub drops an executable shell stub named name into dir so PATH
+// lookups resolve without the real CLI installed.
+func writeExecStub(dir, name string) error {
+	return os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"), 0o755)
+}
+
+// TestConvSessions covers the per-conversation session contract: first message
+// creates (--session-id), follow-ups resume (--resume), reset re-mints.
+func TestConvSessions(t *testing.T) {
+	s := newConvSessions("")
+
+	first := s.args("conv-1")
+	if len(first) != 2 || first[0] != "--session-id" || first[1] == "" {
+		t.Fatalf("first args = %v, want [--session-id <uuid>]", first)
+	}
+	second := s.args("conv-1")
+	if len(second) != 2 || second[0] != "--resume" || second[1] != first[1] {
+		t.Fatalf("second args = %v, want [--resume %s]", second, first[1])
+	}
+
+	// A different conversation gets its own session.
+	other := s.args("conv-2")
+	if other[0] != "--session-id" || other[1] == first[1] {
+		t.Fatalf("conv-2 args = %v, want a fresh --session-id distinct from %s", other, first[1])
+	}
+
+	// reset self-heals a broken session: next message starts fresh with a NEW
+	// uuid (the old one may or may not exist agent-side; a new one is safe).
+	s.reset("conv-1")
+	again := s.args("conv-1")
+	if again[0] != "--session-id" || again[1] == first[1] {
+		t.Fatalf("post-reset args = %v, want fresh --session-id != %s", again, first[1])
+	}
+}
+
+// TestApplyModelArg covers both shapes: replacing an existing model pin
+// (claudecode's built-in haiku) and inserting before the tail (gemini-style
+// tails that end with -p and need the prompt to stay trailing).
+func TestApplyModelArg(t *testing.T) {
+	replaced := applyModelArg(
+		[]string{"claude", "-p", "--model", "claude-haiku-4-5-20251001", "--strict-mcp-config"},
+		"--model", "claude-sonnet-4-6")
+	want := []string{"claude", "-p", "--model", "claude-sonnet-4-6", "--strict-mcp-config"}
+	if strings.Join(replaced, " ") != strings.Join(want, " ") {
+		t.Fatalf("replace: got %v, want %v", replaced, want)
+	}
+
+	inserted := applyModelArg([]string{"gemini", "-p"}, "-m", "gemini-2.5-pro")
+	wantIns := []string{"gemini", "-m", "gemini-2.5-pro", "-p"}
+	if strings.Join(inserted, " ") != strings.Join(wantIns, " ") {
+		t.Fatalf("insert: got %v, want %v", inserted, wantIns)
+	}
+}
+
+// TestForwarderSessionAndModelWiring checks forwarderForChannel applies the
+// options: memory only on ccSessions channels, model only via the spec's flag.
+func TestForwarderSessionAndModelWiring(t *testing.T) {
+	t.Setenv("DWS_CONNECT_NO_INSTALL", "1")
+	t.Setenv("DWS_AGENT_CMD", "") // ensure no override
+	// Use DWS_AGENT_CMD-free resolution; claudecode requires the binary on
+	// PATH, which CI may lack — fake it via DWS_AGENT_CMD is wrong (disables
+	// extras by design), so point PATH at a stub.
+	stub := t.TempDir()
+	for _, name := range []string{"claude", "qodercli"} {
+		if err := writeExecStub(stub, name); err != nil {
+			t.Fatalf("stub %s: %v", name, err)
+		}
+	}
+	t.Setenv("PATH", stub)
+
+	fwd, err := forwarderForChannel("claudecode", "", connectAgentOptions{Memory: true, Model: "claude-sonnet-4-6"})
+	if err != nil {
+		t.Fatalf("claudecode forwarder: %v", err)
+	}
+	ef := fwd.(*execForwarder)
+	if ef.sessions == nil {
+		t.Fatal("claudecode with Memory=true should have sessions enabled")
+	}
+	if !strings.Contains(strings.Join(ef.argv, " "), "--model claude-sonnet-4-6") {
+		t.Fatalf("model not applied: %v", ef.argv)
+	}
+	if strings.Contains(strings.Join(ef.argv, " "), "haiku") {
+		t.Fatalf("built-in haiku pin should be replaced: %v", ef.argv)
+	}
+
+	// qoder family runs a persistent stream-json subprocess and carries the
+	// addressable Qoder session id inside each JSON user message. DWS persists
+	// the mapping so a connector restart can resume the same conversation.
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	qf, err := forwarderForChannel("qoder", "qoder-client", connectAgentOptions{Memory: true})
+	if err != nil {
+		t.Fatalf("qoder forwarder: %v", err)
+	}
+	qsf := qf.(*qoderStreamForwarder)
+	if qsf.sessions == nil {
+		t.Fatal("qoder with Memory=true should have sessions")
+	}
+	if qsf.sessions.path == "" {
+		t.Fatal("qoder sessions should persist to disk")
+	}
+	if got := strings.Join(qsf.commandArgs(), " "); !strings.Contains(got, "--input-format stream-json") || !strings.Contains(got, "--output-format stream-json") {
+		t.Fatalf("qoder stream-json args mismatch: argv = %v", qsf.commandArgs())
+	}
+
+	qwf, err := forwarderForChannel("qoderwork", "robot-client", connectAgentOptions{Memory: true})
+	if err != nil {
+		t.Fatalf("qoderwork forwarder: %v", err)
+	}
+	qwsf := qwf.(*qoderStreamForwarder)
+	if qwsf.sessions == nil {
+		t.Fatal("qoderwork with Memory=true should have sessions")
+	}
+	if qwsf.sessions.path == "" {
+		t.Fatal("qoderwork sessions should persist to disk")
+	}
+
+	// Memory off on a supporting channel.
+	off, err := forwarderForChannel("claudecode", "", connectAgentOptions{Memory: false})
+	if err != nil {
+		t.Fatalf("claudecode memory-off forwarder: %v", err)
+	}
+	if off.(*execForwarder).sessions != nil {
+		t.Fatal("Memory=false must disable sessions")
+	}
+}
+
+// TestRobotConnectAgentFlagsInDryRun checks the new flags surface in the
+// dry-run preview so callers can see the effective agent tuning.
+func TestRobotConnectAgentFlagsInDryRun(t *testing.T) {
+	root := newDevAppTestRoot(&captureRunner{})
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(&out)
+	root.SetArgs([]string{"dev", "connect",
+		"--channel", "claudecode",
+		"--robot-client-id", "id1", "--robot-client-secret", "sec1",
+		"--agent-model", "claude-sonnet-4-6", "--agent-workdir", "/tmp/kb",
+		"--dry-run"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\n%s", err, out.String())
+	}
+	for _, sub := range []string{"claude-sonnet-4-6", "/tmp/kb", "per-conversation"} {
+		if !strings.Contains(out.String(), sub) {
+			t.Fatalf("dry-run output missing %q:\n%s", sub, out.String())
+		}
+	}
+
+	// memory=false shows as disabled.
+	out.Reset()
+	root = newDevAppTestRoot(&captureRunner{})
+	root.SetOut(&out)
+	root.SetErr(&out)
+	root.SetArgs([]string{"dev", "connect",
+		"--channel", "claudecode",
+		"--robot-client-id", "id1", "--robot-client-secret", "sec1",
+		"--agent-memory=false", "--dry-run"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v\n%s", err, out.String())
+	}
+	if !strings.Contains(out.String(), `"memory": "disabled"`) {
+		t.Fatalf("dry-run output missing disabled memory:\n%s", out.String())
+	}
+}
+
+func TestQoderAgentMemoryPayloadIsPerConversation(t *testing.T) {
+	payload := connectAgentOptionsPayload("qoder", connectAgentOptions{Memory: true})
+	if got := payload["memory"]; got != "per-conversation-qoder-stream" {
+		t.Fatalf("qoder memory = %v, want per-conversation-qoder-stream", got)
+	}
+	payload = connectAgentOptionsPayload("qoderwork", connectAgentOptions{Memory: true})
+	if got := payload["memory"]; got != "per-conversation-qoder-stream" {
+		t.Fatalf("qoderwork memory = %v, want per-conversation-qoder-stream", got)
+	}
+	payload = connectAgentOptionsPayload("qoder", connectAgentOptions{Memory: false})
+	if got := payload["memory"]; got != "disabled" {
+		t.Fatalf("qoder memory disabled = %v, want disabled", got)
+	}
+}
+
+// TestRobotConnectDryRunShowsCliStatus checks the dependency preflight agents
+// rely on: dry-run reports whether the channel CLI is installed, with the
+// install hint when missing.
+func TestRobotConnectDryRunShowsCliStatus(t *testing.T) {
+	t.Setenv("DWS_CONNECT_NO_INSTALL", "1")
+	stub := t.TempDir()
+	if err := writeExecStub(stub, "claude"); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", stub)
+
+	run := func(channel string) string {
+		root := newDevAppTestRoot(&captureRunner{})
+		var out bytes.Buffer
+		root.SetOut(&out)
+		root.SetErr(&out)
+		root.SetArgs([]string{"dev", "connect", "--channel", channel,
+			"--robot-client-id", "a", "--robot-client-secret", "b", "--dry-run"})
+		if err := root.Execute(); err != nil {
+			t.Fatalf("Execute(%s): %v\n%s", channel, err, out.String())
+		}
+		return out.String()
+	}
+
+	// claude on PATH → installed true with path
+	if got := run("claudecode"); !strings.Contains(got, `"installed": true`) {
+		t.Fatalf("claudecode should be installed:\n%s", got)
+	}
+	// codex NOT on PATH → installed false + hint
+	got := run("codex")
+	if !strings.Contains(got, `"installed": false`) || !strings.Contains(got, "@openai/codex") {
+		t.Fatalf("codex should be missing with hint:\n%s", got)
+	}
+	if !strings.Contains(got, "per-conversation-app-server") {
+		t.Fatalf("codex dry-run should advertise app-server memory:\n%s", got)
+	}
+}

internal/helpers/connect_approval.go

@@ -0,0 +1,698 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+)
+
+// The "digital twin" confirmation gate. When someone @-mentions the bot with an
+// *action* request ("create a todo for me"), the bot does NOT execute it: it
+// records an ApprovalRequest, sends an interactive card with [Approve]/[Reject]
+// buttons to the owner, and only runs the planned action after the owner taps
+// Approve. A Reject (or timeout) declines without executing.
+//
+// This file owns the gate engine: the request/state model, the thread-safe
+// store with crash-safe on-disk persistence (so a Pending request survives a
+// connector restart), and the Submit/Decide/Await/Get API. Card delivery and
+// the connector wiring live in connect_approval_card.go and connect_stream.go.
+
+// approvalState is the request lifecycle: Pending → Approved|Rejected →
+// Executed|Failed. A decision (Approve/Reject) is the owner's call; execution
+// is what the orchestrator does afterwards on an approved request.
+type approvalState string
+
+const (
+	approvalPending  approvalState = "pending"
+	approvalApproved approvalState = "approved"
+	approvalRejected approvalState = "rejected"
+	approvalExecuted approvalState = "executed"
+	approvalFailed   approvalState = "failed"
+	// approvalDeferred is an approved request whose execution could not complete
+	// right now — typically because the connector's dws login is not (yet) the
+	// bot's owner, so an owner-scoped action can't run. The request is NOT lost:
+	// it stays on disk in this state, the owner is told to recover (log in), and
+	// a later "retry" flushes it. Distinct from Failed, which is terminal.
+	approvalDeferred approvalState = "deferred"
+)
+
+// plannedAction is the structured command the gate will run once approved. It
+// is intentionally generic (product + tool + params) so it maps straight onto
+// executor.NewHelperInvocation without the gate knowing about any specific
+// command. For the M2 vertical slice the orchestrator only emits todo.create,
+// but the shape already supports any helper tool.
+type plannedAction struct {
+	// Product/Tool/LegacyPath feed executor.NewHelperInvocation. Product is the
+	// canonical product (e.g. "todo"); Tool is the RPC name (e.g.
+	// "create_personal_todo"); LegacyPath is the human command path for logs.
+	Product    string         `json:"product"`
+	Tool       string         `json:"tool"`
+	LegacyPath string         `json:"legacy_path,omitempty"`
+	Params     map[string]any `json:"params,omitempty"`
+}
+
+// ApprovalRequest is one pending/decided confirmation. It is the on-disk record
+// too (marshalled as-is), so every field is JSON-tagged and self-describing.
+type ApprovalRequest struct {
+	ID        string        `json:"id"`
+	Requester string        `json:"requester"`      // staffId of who asked
+	ConvID    string        `json:"conv_id"`        // conversation to reply into
+	Summary   string        `json:"summary"`        // human-readable "what will happen"
+	Verb      string        `json:"verb,omitempty"` // action verb, e.g. "todo.create" (remember key)
+	Action    plannedAction `json:"action"`         // structured command to run on approve
+	State     approvalState `json:"state"`
+	// OutTrackID is the delivered card's instance id, recorded so a button
+	// callback that only carries the card id (not the approval id in its action
+	// params) can still be mapped back to this request.
+	OutTrackID string `json:"out_track_id,omitempty"`
+	DecidedBy  string `json:"decided_by,omitempty"` // staffId who approved/rejected
+	ExecErr    string `json:"exec_err,omitempty"`   // failure detail when State=failed
+	// AutoApproved marks a request the owner made of THEMSELVES: no second
+	// confirmation is asked (the owner asking IS the authorization), but the
+	// full record is still persisted for audit, with DecidedBy=owner. Lets the
+	// audit trail distinguish an auto-run from an explicitly-confirmed one.
+	AutoApproved bool      `json:"auto_approved,omitempty"`
+	CreatedAt    time.Time `json:"created_at"`
+	DecidedAt    time.Time `json:"decided_at,omitempty"`
+}
+
+// decided reports whether the owner has made a call (approved or rejected),
+// regardless of any later execution outcome.
+func (r *ApprovalRequest) decided() bool {
+	switch r.State {
+	case approvalApproved, approvalRejected, approvalExecuted, approvalFailed, approvalDeferred:
+		return true
+	}
+	return false
+}
+
+// approved reports whether the owner approved (in any post-approval state,
+// including deferred — a deferred request WAS approved, its execution just
+// hasn't completed yet).
+func (r *ApprovalRequest) approved() bool {
+	switch r.State {
+	case approvalApproved, approvalExecuted, approvalFailed, approvalDeferred:
+		return true
+	}
+	return false
+}
+
+// approvalGate is the thread-safe confirmation-gate store. It keeps every
+// request in memory and mirrors each one to <config>/connect/<clientId>/
+// approvals/<id>.json so a Pending request survives a connector restart.
+// Persistence is best-effort and never blocks a decision: a write failure only
+// logs (mirroring connect_sessions_store's contract). An empty clientId means
+// in-memory only (used by tests).
+type approvalGate struct {
+	clientID string
+
+	mu      sync.Mutex
+	reqs    map[string]*ApprovalRequest
+	waiters map[string]chan struct{} // id → closed when the request is decided
+}
+
+// newApprovalGate builds the gate and eagerly loads any persisted requests from
+// disk (so a restart can still resolve a card tapped while the bot was down).
+func newApprovalGate(clientID string) *approvalGate {
+	g := &approvalGate{
+		clientID: strings.TrimSpace(clientID),
+		reqs:     make(map[string]*ApprovalRequest),
+		waiters:  make(map[string]chan struct{}),
+	}
+	g.loadAll()
+	return g
+}
+
+// approvalDir returns the on-disk directory for this gate's requests, or "" when
+// persistence is disabled (empty clientId). The clientId is sanitized exactly
+// like the session store / lock file so it is always filesystem-safe.
+func (g *approvalGate) approvalDir() string {
+	if g.clientID == "" {
+		return ""
+	}
+	return filepath.Join(config.DefaultConfigDir(), "connect", sanitizeLockID(g.clientID), "approvals")
+}
+
+// Submit records a new request in the Pending state, persists it, and returns
+// the stored request (with a generated ID and CreatedAt). A blank requester or
+// summary is allowed — the gate does not police content, it only sequences the
+// approval — but an empty action means "nothing to run on approve", which the
+// orchestrator must guard before calling Submit.
+func (g *approvalGate) Submit(req ApprovalRequest) *ApprovalRequest {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	if strings.TrimSpace(req.ID) == "" {
+		req.ID = uuid.NewString()
+	}
+	req.State = approvalPending
+	if req.CreatedAt.IsZero() {
+		req.CreatedAt = time.Now()
+	}
+	stored := req // copy
+	g.reqs[stored.ID] = &stored
+	g.persist(&stored)
+	return &stored
+}
+
+// setOutTrackID records the delivered card instance id for a request so a
+// callback that carries only the card id can be mapped back. No-op for unknown
+// ids; persists on success.
+func (g *approvalGate) setOutTrackID(id, outTrackID string) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	r, ok := g.reqs[id]
+	if !ok {
+		return
+	}
+	r.OutTrackID = outTrackID
+	g.persist(r)
+}
+
+// findByOutTrackID returns the request whose delivered card has the given
+// instance id, used as the fallback association when a callback's action params
+// did not carry the approval id. Returns nil when none match.
+func (g *approvalGate) findByOutTrackID(outTrackID string) *ApprovalRequest {
+	outTrackID = strings.TrimSpace(outTrackID)
+	if outTrackID == "" {
+		return nil
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	for _, r := range g.reqs {
+		if r.OutTrackID == outTrackID {
+			cp := *r
+			return &cp
+		}
+	}
+	return nil
+}
+
+// pendingForConv returns a snapshot of the most-recent still-Pending request in
+// the given conversation, or nil when none is awaiting a decision there. It is
+// the lookup the text-approval mode needs to map an owner's "同意/拒绝" reply
+// (which only carries the conversation, not an approval id) back to its request.
+func (g *approvalGate) pendingForConv(convID string) *ApprovalRequest {
+	convID = strings.TrimSpace(convID)
+	if convID == "" {
+		return nil
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	var best *ApprovalRequest
+	for _, r := range g.reqs {
+		if r.State == approvalPending && r.ConvID == convID {
+			if best == nil || r.CreatedAt.After(best.CreatedAt) {
+				best = r
+			}
+		}
+	}
+	if best == nil {
+		return nil
+	}
+	cp := *best
+	return &cp
+}
+
+// latestPending returns a snapshot of the most-recent still-Pending request
+// across all conversations, or nil when none awaits a decision. Text approval
+// uses it to map the owner's "同意/拒绝" — sent from the owner's OWN 1:1 chat
+// with the bot, a different conversation than where the request originated —
+// onto the request they are deciding. One bot has one owner, so every pending
+// request belongs to that owner; newest-first matches "decide what I was just
+// asked about".
+func (g *approvalGate) latestPending() *ApprovalRequest {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	var best *ApprovalRequest
+	for _, r := range g.reqs {
+		if r.State == approvalPending {
+			if best == nil || r.CreatedAt.After(best.CreatedAt) {
+				best = r
+			}
+		}
+	}
+	if best == nil {
+		return nil
+	}
+	cp := *best
+	return &cp
+}
+
+// Decide records the owner's call on a Pending request and wakes any Await.
+// It is idempotent and race-safe: a second decision (e.g. a double-tap, or a
+// reject after an approve) is ignored once the request has already been
+// decided, and the function reports whether THIS call was the deciding one.
+func (g *approvalGate) Decide(id string, approve bool, by string) (*ApprovalRequest, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	r, ok := g.reqs[id]
+	if !ok {
+		return nil, false
+	}
+	if r.decided() {
+		cp := *r
+		return &cp, false // already decided; not the deciding call
+	}
+	if approve {
+		r.State = approvalApproved
+	} else {
+		r.State = approvalRejected
+	}
+	r.DecidedBy = strings.TrimSpace(by)
+	r.DecidedAt = time.Now()
+	g.persist(r)
+	g.wake(id)
+	cp := *r
+	return &cp, true
+}
+
+// markExecuted / markFailed record the post-approval execution outcome. They do
+// not gate or wake anything (Await already returned on the decision); they exist
+// so the on-disk record reflects what actually happened, for audit and restart.
+func (g *approvalGate) markExecuted(id string) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if r, ok := g.reqs[id]; ok && r.approved() {
+		r.State = approvalExecuted
+		g.persist(r)
+	}
+}
+
+func (g *approvalGate) markFailed(id string, cause string) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if r, ok := g.reqs[id]; ok && r.approved() {
+		r.State = approvalFailed
+		r.ExecErr = truncateRunes(strings.TrimSpace(cause), 500)
+		g.persist(r)
+	}
+}
+
+// markDeferred records that an approved request could not execute now and is
+// being held for a later retry (it is NOT lost). The cause is kept so the owner
+// and the audit trail can see why. Persisted so a connector restart still
+// remembers the backlog.
+func (g *approvalGate) markDeferred(id string, cause string) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if r, ok := g.reqs[id]; ok && r.approved() {
+		r.State = approvalDeferred
+		r.ExecErr = truncateRunes(strings.TrimSpace(cause), 500)
+		g.persist(r)
+	}
+}
+
+// allDeferred returns snapshots of every request awaiting retry, oldest first
+// (so a flush replays them in the order they were asked).
+func (g *approvalGate) allDeferred() []*ApprovalRequest {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	out := make([]*ApprovalRequest, 0)
+	for _, r := range g.reqs {
+		if r.State == approvalDeferred {
+			cp := *r
+			out = append(out, &cp)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].CreatedAt.Before(out[j].CreatedAt) })
+	return out
+}
+
+// Get returns a snapshot copy of a request, or nil if unknown.
+func (g *approvalGate) Get(id string) *ApprovalRequest {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if r, ok := g.reqs[id]; ok {
+		cp := *r
+		return &cp
+	}
+	return nil
+}
+
+// Await blocks until the request is decided (approved or rejected), the context
+// is cancelled, or the timeout elapses, and returns the final snapshot. A
+// request already decided returns immediately. On timeout the request stays
+// Pending (a late tap can still resolve it) and Await returns (snapshot, false).
+// The bool reports whether a decision was observed within the wait.
+func (g *approvalGate) Await(ctx context.Context, id string, timeout time.Duration) (*ApprovalRequest, bool) {
+	// Fast path + waiter registration under the lock so we never miss a Decide
+	// that lands between the check and the channel subscribe.
+	g.mu.Lock()
+	r, ok := g.reqs[id]
+	if !ok {
+		g.mu.Unlock()
+		return nil, false
+	}
+	if r.decided() {
+		cp := *r
+		g.mu.Unlock()
+		return &cp, true
+	}
+	ch, exists := g.waiters[id]
+	if !exists {
+		ch = make(chan struct{})
+		g.waiters[id] = ch
+	}
+	g.mu.Unlock()
+
+	var timer *time.Timer
+	var timeout_c <-chan time.Time
+	if timeout > 0 {
+		timer = time.NewTimer(timeout)
+		defer timer.Stop()
+		timeout_c = timer.C
+	}
+
+	select {
+	case <-ch:
+		return g.Get(id), true
+	case <-ctx.Done():
+		return g.Get(id), false
+	case <-timeout_c:
+		return g.Get(id), false
+	}
+}
+
+// wake closes and clears the waiter channel for id (must hold g.mu). Safe to
+// call when there is no waiter.
+func (g *approvalGate) wake(id string) {
+	if ch, ok := g.waiters[id]; ok {
+		close(ch)
+		delete(g.waiters, id)
+	}
+}
+
+// persist atomically writes one request to disk (must hold g.mu). Best-effort:
+// a failure only logs and never blocks the decision path, exactly like
+// saveConvSessionMap. No-op when persistence is disabled.
+func (g *approvalGate) persist(r *ApprovalRequest) {
+	dir := g.approvalDir()
+	if dir == "" {
+		return
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 创建审批目录失败，跳过落盘：%v\n", err)
+		return
+	}
+	data, err := json.MarshalIndent(r, "", "  ")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 序列化审批失败，跳过落盘：%v\n", err)
+		return
+	}
+	path := filepath.Join(dir, sanitizeLockID(r.ID)+".json")
+	tmp, err := os.CreateTemp(dir, "approval-*.json.tmp")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 创建审批临时文件失败，跳过落盘：%v\n", err)
+		return
+	}
+	tmpName := tmp.Name()
+	if err := tmp.Chmod(config.FilePerm); err != nil {
+		tmp.Close()
+		_ = os.Remove(tmpName)
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 设置审批文件权限失败，跳过落盘：%v\n", err)
+		return
+	}
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		_ = os.Remove(tmpName)
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 写入审批临时文件失败，跳过落盘：%v\n", err)
+		return
+	}
+	if err := tmp.Close(); err != nil {
+		_ = os.Remove(tmpName)
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 关闭审批临时文件失败，跳过落盘：%v\n", err)
+		return
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		_ = os.Remove(tmpName)
+		fmt.Fprintf(os.Stderr, "[connect][approval][warn] 原子替换审批存档失败，跳过落盘：%v\n", err)
+	}
+}
+
+// loadAll reads every persisted request back into memory at startup. It is
+// forgiving like loadConvSessionMap: a missing dir (first run) is silent, and a
+// single corrupt file is skipped with a warning rather than aborting the load.
+func (g *approvalGate) loadAll() {
+	dir := g.approvalDir()
+	if dir == "" {
+		return
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			fmt.Fprintf(os.Stderr, "[connect][approval][warn] 读取审批目录失败，按空起：%v\n", err)
+		}
+		return
+	}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".json") {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, e.Name()))
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "[connect][approval][warn] 读取审批存档 %s 失败，跳过：%v\n", e.Name(), err)
+			continue
+		}
+		var r ApprovalRequest
+		if err := json.Unmarshal(raw, &r); err != nil {
+			fmt.Fprintf(os.Stderr, "[connect][approval][warn] 审批存档 %s 已损坏，跳过：%v\n", e.Name(), err)
+			continue
+		}
+		if strings.TrimSpace(r.ID) == "" {
+			continue
+		}
+		g.reqs[r.ID] = &r
+	}
+}
+
+// ---- "Execution-class" request detection (simplified for the M2 slice) ----
+//
+// We do NOT build a general NLP intent classifier here (that is a later task).
+// Instead the orchestrator instructs the agent to emit a structured marker for
+// any action it would take, and we parse that marker out of the reply:
+//
+//   [[ACTION:todo.create title="交方案" due="2026-06-14T18:00:00+08:00"]]
+//
+// Matched → route through the gate. No marker → ordinary Q&A, replied directly.
+// The grammar is deliberately tiny: ACTION:<verb> followed by key="value"
+// pairs. The only verb wired end-to-end in this slice is todo.create.
+
+var actionMarkerRe = regexp.MustCompile(`\[\[ACTION:\s*([a-zA-Z0-9_.]+)\s*(.*?)\]\]`)
+
+// actionKVRe captures key="value" (or key='value') pairs inside a marker.
+var actionKVRe = regexp.MustCompile(`([a-zA-Z0-9_]+)\s*=\s*"([^"]*)"|([a-zA-Z0-9_]+)\s*=\s*'([^']*)'`)
+
+// detectedAction is one parsed [[ACTION:...]] marker: its verb (e.g.
+// "todo.create") and its key/value arguments.
+type detectedAction struct {
+	Verb string
+	Args map[string]string
+}
+
+// parseActionMarker extracts the first [[ACTION:...]] marker from an agent
+// reply, returning (action, cleaned-reply, found). cleanedReply is the reply
+// with the marker stripped (and surrounding whitespace tidied) so it can be
+// shown to a human without the machine syntax leaking through.
+func parseActionMarker(reply string) (detectedAction, string, bool) {
+	loc := actionMarkerRe.FindStringSubmatchIndex(reply)
+	if loc == nil {
+		return detectedAction{}, reply, false
+	}
+	verb := strings.TrimSpace(reply[loc[2]:loc[3]])
+	argStr := reply[loc[4]:loc[5]]
+	act := detectedAction{Verb: verb, Args: map[string]string{}}
+	for _, m := range actionKVRe.FindAllStringSubmatch(argStr, -1) {
+		if m[1] != "" {
+			act.Args[m[1]] = m[2]
+		} else if m[3] != "" {
+			act.Args[m[3]] = m[4]
+		}
+	}
+	cleaned := strings.TrimSpace(reply[:loc[0]] + reply[loc[1]:])
+	return act, cleaned, true
+}
+
+// toPlannedAction maps a detected marker onto the structured command the gate
+// will execute. It returns (action, summary, ok): ok is false for an unknown or
+// malformed verb (e.g. todo.create without a title), so the orchestrator can
+// fall back to a plain reply instead of submitting a no-op approval.
+//
+// ownerStaffID is the todo executor (the owner is who the reminder is for); the
+// slice intentionally creates the todo for the owner, matching "create a todo
+// for me" where "me" is the digital-twin owner.
+func toPlannedAction(act detectedAction, ownerStaffID string) (plannedAction, string, bool) {
+	switch act.Verb {
+	case "todo.create":
+		title := strings.TrimSpace(act.Args["title"])
+		if title == "" {
+			title = strings.TrimSpace(act.Args["subject"])
+		}
+		if title == "" {
+			return plannedAction{}, "", false
+		}
+		vo := map[string]any{
+			"subject":     title,
+			"executorIds": []string{ownerStaffID},
+		}
+		summary := fmt.Sprintf("创建待办：%s", title)
+		if due := strings.TrimSpace(act.Args["due"]); due != "" {
+			if ms, err := parseDueToMillis(due); err == nil {
+				vo["dueTime"] = ms
+				summary += fmt.Sprintf("（截止 %s）", due)
+			}
+		}
+		pa := plannedAction{
+			Product:    "todo",
+			Tool:       "create_personal_todo",
+			LegacyPath: "todo task create",
+			Params:     map[string]any{"PersonalTodoCreateVO": vo},
+		}
+		return pa, summary, true
+
+	case "calendar.create":
+		title := firstNonEmpty(act.Args["title"], act.Args["summary"])
+		start := strings.TrimSpace(act.Args["start"])
+		end := strings.TrimSpace(act.Args["end"])
+		if title == "" || start == "" || end == "" {
+			return plannedAction{}, "", false
+		}
+		pa := plannedAction{
+			Product:    "calendar",
+			Tool:       "create_calendar_event",
+			LegacyPath: "calendar event create",
+			Params: map[string]any{
+				"summary":       title,
+				"startDateTime": start,
+				"endDateTime":   end,
+			},
+		}
+		return pa, fmt.Sprintf("创建日程：%s（%s ~ %s）", title, start, end), true
+
+	case "doc.create":
+		name := firstNonEmpty(act.Args["name"], act.Args["title"])
+		if name == "" {
+			return plannedAction{}, "", false
+		}
+		pa := plannedAction{
+			Product:    "doc",
+			Tool:       "create_document",
+			LegacyPath: "doc create",
+			Params:     map[string]any{"name": name},
+		}
+		return pa, fmt.Sprintf("创建文档：%s", name), true
+
+	default:
+		return plannedAction{}, "", false
+	}
+}
+
+// firstNonEmpty returns the first trimmed non-empty string among the args.
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if t := strings.TrimSpace(v); t != "" {
+			return t
+		}
+	}
+	return ""
+}
+
+// approveWords / rejectWords are the whole-message replies the text-approval
+// mode treats as the owner's decision. The match is on the ENTIRE trimmed
+// message (case-insensitive) so a casual mention ("同意他的看法") never
+// accidentally approves an action — only a bare "同意" / "拒绝" decides.
+var (
+	approveWords = map[string]struct{}{
+		"同意": {}, "通过": {}, "批准": {}, "确认": {}, "同意执行": {},
+		"approve": {}, "ok": {}, "yes": {}, "y": {},
+	}
+	rejectWords = map[string]struct{}{
+		"拒绝": {}, "驳回": {}, "不行": {}, "不同意": {}, "取消": {}, "否决": {},
+		"reject": {}, "no": {}, "n": {},
+	}
+)
+
+// retryWords are the whole-message replies that flush the deferred backlog
+// (the owner has recovered — e.g. logged dws in as themselves — and wants the
+// held requests replayed).
+var retryWords = map[string]struct{}{
+	"重试": {}, "恢复": {}, "补做": {}, "重新执行": {}, "继续": {},
+	"retry": {}, "resume": {},
+}
+
+// isRetryWord reports whether a whole message is a bare "flush the backlog"
+// command.
+func isRetryWord(msg string) bool {
+	_, ok := retryWords[strings.ToLower(strings.TrimSpace(msg))]
+	return ok
+}
+
+// parseDecisionWord classifies a whole message as an approve/reject decision.
+// It returns (approve, ok): ok is false when the message is not a bare decision
+// keyword, so the caller forwards it to the agent as an ordinary message.
+func parseDecisionWord(msg string) (approve bool, ok bool) {
+	m := strings.ToLower(strings.TrimSpace(msg))
+	if _, yes := approveWords[m]; yes {
+		return true, true
+	}
+	if _, no := rejectWords[m]; no {
+		return false, true
+	}
+	return false, false
+}
+
+// classifyPlannedAction maps a planned command onto its read/write class so the
+// gate can honor the "写类才拦" design: only a write (or Unknown — per the
+// CmdClass safety contract) action needs the owner's sign-off; a read-class
+// action is safe to let through without gating.
+//
+// It classifies on the human command path (LegacyPath, e.g. "todo task create")
+// first, since that is exactly the space-joined segment shape ClassifyDwsCommand
+// expects. When LegacyPath is absent or yields Unknown, it falls back to the
+// product + RPC tool name (e.g. "todo" + "create_personal_todo"), whose leading
+// verb token ("create") the classifier can still recognise.
+func classifyPlannedAction(pa plannedAction) CmdClass {
+	if path := strings.TrimSpace(pa.LegacyPath); path != "" {
+		if c := ClassifyDwsCommand(strings.Fields(path)...); c != CmdClassUnknown {
+			return c
+		}
+	}
+	return ClassifyDwsCommand(pa.Product, pa.Tool)
+}
+
+// parseDueToMillis converts an ISO-8601 due string to epoch millis, accepting
+// the common RFC3339 shapes the agent is asked to emit. Kept local to the gate
+// so detection has no dependency on the cobra todo command's flag plumbing.
+func parseDueToMillis(due string) (int64, error) {
+	for _, layout := range []string{time.RFC3339, "2006-01-02T15:04:05Z07:00", "2006-01-02T15:04:05", "2006-01-02 15:04", "2006-01-02"} {
+		if t, err := time.Parse(layout, due); err == nil {
+			return t.UnixMilli(), nil
+		}
+	}
+	return 0, fmt.Errorf("unrecognized due time %q", due)
+}

internal/helpers/connect_approval_card.go

@@ -0,0 +1,857 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/card"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+)
+
+// This file wires the confirmation gate to DingTalk:
+//   - approvalCardSender: the dependency-injected boundary that delivers the
+//     [Approve]/[Reject] card to the owner and updates it with the outcome.
+//     Tests inject a fake; production uses dingtalkApprovalCardSender (HTTP).
+//   - approvalOrchestrator: the connector-side glue. It owns the gate + sender +
+//     runner, decides whether an agent reply is an action request, drives the
+//     Submit → card → Await → execute → reply loop, and routes button callbacks
+//     into gate.Decide. connect_stream.go calls into it; it never imports stream
+//     internals back, so it stays unit-testable without a live connection.
+
+// Button action constants. The card's two buttons each carry a fixed action
+// id; the approval id and the decision travel as private action params so a
+// callback can be associated and resolved without any server-side lookup table.
+const (
+	approvalActionApprove   = "dws_approval_approve"
+	approvalActionReject    = "dws_approval_reject"
+	approvalParamID         = "dwsApprovalId" // approval request id
+	approvalParamDecision   = "dwsDecision"   // "approve" | "reject"
+	approvalDecisionApprove = "approve"
+	approvalDecisionReject  = "reject"
+)
+
+// approvalCardSender delivers and updates the owner-facing confirmation card.
+// It is an interface so the orchestrator and its tests never touch the network:
+// the real sender talks to the DingTalk card API, the fake records calls.
+type approvalCardSender interface {
+	// SendApprovalCard delivers an interactive card with [Approve]/[Reject]
+	// buttons (each carrying req.ID + its decision in the action params) to the
+	// owner's 1:1 chat with the bot, returning the delivered card instance id
+	// (outTrackId) for later result updates and callback association.
+	SendApprovalCard(ctx context.Context, ownerUserID string, req *ApprovalRequest) (string, error)
+	// UpdateApprovalCard replaces the card body with the final outcome text
+	// (best-effort; an error must not fail the surrounding flow).
+	UpdateApprovalCard(ctx context.Context, outTrackID, text string) error
+}
+
+// approvalRunner is the subset of executor.Runner the orchestrator needs. Kept
+// as a named alias so the dependency is explicit and easy to fake.
+type approvalRunner interface {
+	Run(context.Context, executor.Invocation) (executor.Result, error)
+}
+
+// approvalReplier abstracts "send a plain text line back into the conversation"
+// (the group reply after approve/reject). connect_stream.go supplies a closure
+// over the chatbot replier + sessionWebhook; tests supply a recorder.
+type approvalReplier func(ctx context.Context, convID, text string) error
+
+// ownerNotifier sends a proactive 1:1 message to specific users (the owner, the
+// requester), independent of any inbound sessionWebhook. Text approval needs it
+// because the approval conversation (owner's 1:1 with the bot) is not the
+// conversation the request arrived on, and because the decision can land minutes
+// later when the original webhook is stale. *aiCardClient implements it.
+type ownerNotifier interface {
+	sendOTOText(ctx context.Context, userIDs []string, text string) error
+}
+
+// auditSink records a terminal-state request to a durable, reviewable place
+// (e.g. a DingTalk online sheet) so every action the twin takes is auditable
+// beyond the local approvals JSON. Best-effort: a sink failure must never block
+// or fail the action.
+type auditSink interface {
+	record(ctx context.Context, req *ApprovalRequest)
+}
+
+// sheetAuditSink appends one row per action to a DingTalk online sheet (axls)
+// via the sheet `append_rows` tool, run under the connector's (bot) identity.
+// Columns: 时间 | 摘要 | 请求人 | 状态 | 批准人 | 是否自动 | 失败原因 | 单据ID.
+type sheetAuditSink struct {
+	runner  approvalRunner
+	nodeID  string // axls doc id / URL
+	sheetID string // worksheet id or name (e.g. "Sheet1")
+}
+
+func (s *sheetAuditSink) record(ctx context.Context, req *ApprovalRequest) {
+	if s == nil || s.runner == nil || req == nil {
+		return
+	}
+	auto := ""
+	if req.AutoApproved {
+		auto = "自动"
+	}
+	decidedAt := ""
+	if !req.DecidedAt.IsZero() {
+		decidedAt = req.DecidedAt.Format("2006-01-02 15:04:05")
+	}
+	row := []any{
+		req.CreatedAt.Format("2006-01-02 15:04:05"),
+		req.Summary,
+		req.Requester,
+		string(req.State),
+		req.DecidedBy,
+		auto,
+		req.ExecErr,
+		req.ID,
+		decidedAt,
+	}
+	inv := executor.NewHelperInvocation("sheet append", "sheet", "append_rows", map[string]any{
+		"nodeId":  s.nodeID,
+		"sheetId": s.sheetID,
+		"values":  [][]any{row},
+	})
+	// The online-sheet API throttles (e.g. THREADPOOL_BUSY) under bursts, dropping
+	// an audit row on a transient error. Retry a few times with backoff so the
+	// trail stays complete; still best-effort — give up (log) after the last try.
+	var err error
+	for attempt := 1; attempt <= 3; attempt++ {
+		if _, err = s.runner.Run(ctx, inv); err == nil {
+			return
+		}
+		if attempt < 3 && isTransientSheetErr(err) {
+			time.Sleep(time.Duration(attempt) * 600 * time.Millisecond)
+			continue
+		}
+		break
+	}
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval][audit] 写审计表格失败（已重试）approvalId=%s: %v\n", req.ID, err)
+	}
+}
+
+// isTransientSheetErr reports whether a sheet-append error is a transient
+// throttle/timeout worth retrying (vs. a permanent error like a bad node id).
+func isTransientSheetErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := strings.ToUpper(err.Error())
+	for _, sig := range []string{"BUSY", "THREADPOOL", "TIMEOUT", "RATE", "LIMIT", "TOO MANY", "503", "429"} {
+		if strings.Contains(s, sig) {
+			return true
+		}
+	}
+	return false
+}
+
+// approvalOrchestrator is the connector-side controller for the gate. It is
+// constructed per connector with the owner's userId, the gate, the card sender
+// and the runner. Zero owner / nil sender disables the gate (the connector then
+// behaves exactly as before — plain Q&A).
+type approvalOrchestrator struct {
+	gate        *approvalGate
+	sender      approvalCardSender
+	runner      approvalRunner
+	ownerUserID string
+	awaitWindow time.Duration
+	// textMode swaps the interactive [Approve]/[Reject] card for a private
+	// text confirmation: the bot DMs the OWNER "X 请求执行……" and the owner
+	// replies "同意"/"拒绝" in their own 1:1 chat with the bot. The requester
+	// never sees the approval — they only get the final result. Used when no
+	// approval-card template is configured, so the gate works with zero
+	// card-platform setup. The decision is captured asynchronously (see
+	// handleOwnerDecision), not by blocking on Await.
+	textMode bool
+	// notifier delivers the proactive owner/requester 1:1 messages text mode
+	// needs (nil in card mode).
+	notifier ownerNotifier
+	// audit, when set, records every terminal-state request to a durable sink
+	// (e.g. a DingTalk online sheet) on top of the local approvals JSON. nil =
+	// local-file audit only.
+	audit auditSink
+	// allowedScopes is the role's capability allowlist (product names). When
+	// non-empty, an action whose product is not listed is refused before it ever
+	// reaches the gate, keeping the role in its lane. Empty = no restriction.
+	allowedScopes []string
+	// confirmPolicy governs how OTHERS' requests are confirmed: "manual" (ask
+	// every time, the default), "auto" (run without asking, still audited),
+	// "remember" (ask once per action verb then reuse). The owner's own requests
+	// always auto-run regardless.
+	confirmPolicy string
+	// remembered caches the owner's decision per action verb for the "remember"
+	// policy (verb → approved). Guarded by rememberMu.
+	rememberMu sync.Mutex
+	remembered map[string]bool
+}
+
+// gateDecision decides how to handle a write action: "auto" (run now), "ask"
+// (route to the owner), or "reject" (a remembered rejection). The owner's own
+// requests always auto-run. For others it follows confirmPolicy.
+func (o *approvalOrchestrator) gateDecision(requester, verb string) string {
+	if strings.TrimSpace(requester) != "" && strings.TrimSpace(requester) == o.ownerUserID {
+		return "auto"
+	}
+	switch strings.ToLower(strings.TrimSpace(o.confirmPolicy)) {
+	case "auto":
+		return "auto"
+	case "remember":
+		o.rememberMu.Lock()
+		decided, ok := o.remembered[verb]
+		o.rememberMu.Unlock()
+		if !ok {
+			return "ask"
+		}
+		if decided {
+			return "auto"
+		}
+		return "reject"
+	default: // manual / empty
+		return "ask"
+	}
+}
+
+// rememberDecision records the owner's decision for an action verb so the
+// "remember" policy can reuse it. No-op unless the policy is "remember".
+func (o *approvalOrchestrator) rememberDecision(verb string, approved bool) {
+	if strings.ToLower(strings.TrimSpace(o.confirmPolicy)) != "remember" || strings.TrimSpace(verb) == "" {
+		return
+	}
+	o.rememberMu.Lock()
+	if o.remembered == nil {
+		o.remembered = make(map[string]bool)
+	}
+	o.remembered[verb] = approved
+	o.rememberMu.Unlock()
+}
+
+// scopeAllows reports whether the role may use the given product. An empty
+// allowlist means no restriction (allow all).
+func (o *approvalOrchestrator) scopeAllows(product string) bool {
+	if len(o.allowedScopes) == 0 {
+		return true
+	}
+	product = strings.ToLower(strings.TrimSpace(product))
+	for _, s := range o.allowedScopes {
+		if strings.ToLower(strings.TrimSpace(s)) == product {
+			return true
+		}
+	}
+	return false
+}
+
+// recordAudit writes the request's current (terminal) state to the audit sink,
+// fetching the fresh snapshot so state/exec_err reflect the final outcome.
+// No-op when no sink is configured; best-effort.
+func (o *approvalOrchestrator) recordAudit(ctx context.Context, id string) {
+	if o == nil || o.audit == nil {
+		return
+	}
+	if r := o.gate.Get(id); r != nil {
+		o.audit.record(ctx, r)
+	}
+}
+
+// newApprovalOrchestrator builds the card-mode controller. awaitWindow caps how
+// long the connector blocks for the owner's decision before giving up (the
+// request stays Pending on disk, so a late tap still records and executes
+// nothing twice).
+func newApprovalOrchestrator(gate *approvalGate, sender approvalCardSender, runner approvalRunner, ownerUserID string) *approvalOrchestrator {
+	return &approvalOrchestrator{
+		gate:        gate,
+		sender:      sender,
+		runner:      runner,
+		ownerUserID: strings.TrimSpace(ownerUserID),
+		awaitWindow: 10 * time.Minute,
+	}
+}
+
+// newTextApprovalOrchestrator builds the text-mode controller (no card sender).
+// notifier delivers the private owner/requester messages. The owner confirms by
+// replying "同意"/"拒绝" in their 1:1 chat with the bot; the decision is captured
+// by handleOwnerDecision on the next inbound message, so handleReply must NOT
+// block waiting for it.
+func newTextApprovalOrchestrator(gate *approvalGate, runner approvalRunner, ownerUserID string, notifier ownerNotifier) *approvalOrchestrator {
+	o := newApprovalOrchestrator(gate, nil, runner, ownerUserID)
+	o.textMode = true
+	o.notifier = notifier
+	return o
+}
+
+// enabled reports whether the gate is active. Card mode needs an owner + a card
+// sender; text mode needs an owner + a notifier to reach them privately.
+func (o *approvalOrchestrator) enabled() bool {
+	if o == nil || o.ownerUserID == "" || o.gate == nil {
+		return false
+	}
+	if o.textMode {
+		return o.notifier != nil
+	}
+	return o.sender != nil
+}
+
+// agentSystemHint is appended to the forwarded prompt so the agent emits the
+// structured action marker (see parseActionMarker) instead of executing
+// anything itself. It is the simplified "intent detection" for the slice.
+const agentSystemHint = "\n\n[系统提示] 如果用户的请求是要执行一个动作（而不是单纯提问），" +
+	"不要假装已经完成，而是在回复末尾用下面其中一个标记声明这个动作，由主人确认后再执行：\n" +
+	`· 建待办：[[ACTION:todo.create title="待办标题" due="2026-06-14T18:00:00+08:00"]]（due 可省略）` + "\n" +
+	`· 建日程：[[ACTION:calendar.create title="日程标题" start="2026-06-20T10:00:00+08:00" end="2026-06-20T11:00:00+08:00"]]` + "\n" +
+	`· 建文档：[[ACTION:doc.create name="文档名"]]` + "\n" +
+	"时间一律用 ISO-8601（带时区）。如果只是普通提问，正常回答即可，不要输出任何标记。"
+
+// decorateForActionDetection appends the action-marker instruction to a prompt
+// when the gate is enabled. A no-op when disabled, so plain Q&A is untouched.
+func (o *approvalOrchestrator) decorateForActionDetection(prompt string) string {
+	if !o.enabled() {
+		return prompt
+	}
+	return prompt + agentSystemHint
+}
+
+// handleReply is the orchestration hook the connector calls with the agent's
+// raw reply. It returns (finalReply, handled): when handled is true the gate
+// took over (it has already sent the card / will reply asynchronously via
+// reply) and the connector must NOT send finalReply itself. When false the
+// connector replies normally with finalReply (the marker, if any, is stripped).
+//
+// requester is the staffId who asked; convID is where the group answer goes;
+// reply is the function used to post the approve/reject outcome back.
+func (o *approvalOrchestrator) handleReply(ctx context.Context, requester, convID, agentReply string, reply approvalReplier) (string, bool) {
+	if !o.enabled() {
+		return agentReply, false
+	}
+	act, cleaned, found := parseActionMarker(agentReply)
+	if !found {
+		return agentReply, false // plain Q&A
+	}
+	pa, summary, ok := toPlannedAction(act, o.ownerUserID)
+	if !ok {
+		// Unknown/blank action: degrade to a plain reply (marker stripped) so a
+		// malformed marker never silently swallows the answer.
+		return cleaned, false
+	}
+
+	// Role scope: an action outside the role's capability allowlist is refused
+	// up front (never reaches the gate or the owner). The requester is told it is
+	// out of lane — this is a capability boundary, not an approval, so it is fine
+	// to surface to them.
+	if !o.scopeAllows(pa.Product) {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 越权拦截：角色无 %q 能力，拒绝动作 %s\n", pa.Product, summary)
+		return fmt.Sprintf("（该数字员工没有「%s」能力，无法执行此操作：%s）", pa.Product, summary), false
+	}
+
+	// 写类才拦：route the gate-or-not decision through the read/write classifier
+	// instead of gating every detected marker. A definitively read-class action
+	// is safe and bypasses the gate (the marker is stripped and the reply goes
+	// out normally). Write — and Unknown, per the CmdClass safety contract — keep
+	// the owner's sign-off requirement.
+	if classifyPlannedAction(pa) == CmdClassRead {
+		return cleaned, false
+	}
+
+	// Confirmation strategy: owner-self always auto-runs; others follow
+	// confirmPolicy (manual=ask / auto=run / remember=reuse last decision).
+	decision := o.gateDecision(requester, act.Verb)
+	req := o.gate.Submit(ApprovalRequest{
+		Requester:    requester,
+		ConvID:       convID,
+		Summary:      summary,
+		Verb:         act.Verb,
+		Action:       pa,
+		AutoApproved: decision == "auto",
+	})
+
+	switch decision {
+	case "auto":
+		// Asking IS the authorization (owner-self), or the policy pre-authorized
+		// it (auto / remembered-approve). Execute directly; still fully audited.
+		return o.autoApproveAndExecute(ctx, req, convID, reply)
+	case "reject":
+		// Remembered rejection for this action kind — decline without bothering
+		// the owner, and tell the requester.
+		o.gate.Decide(req.ID, false, o.ownerUserID)
+		o.recordAudit(ctx, req.ID)
+		fmt.Fprintf(os.Stderr, "[connect][approval] 记忆策略：%q 此前被拒，自动拒绝 approvalId=%s\n", act.Verb, req.ID)
+		return fmt.Sprintf("（主人此前已拒绝这类操作，本次未执行：%s）", summary), false
+	default: // "ask"
+		// Text mode: privately DM the owner and return immediately — the owner's
+		// "同意/拒绝" reply is captured asynchronously by handleOwnerDecision
+		// (blocking here would deadlock the per-conversation worker that must also
+		// process that reply). The requester (this conversation) sees nothing.
+		if o.textMode {
+			return o.handleReplyText(ctx, req)
+		}
+		return o.handleReplyCard(ctx, req, convID, reply)
+	}
+}
+
+// autoApproveAndExecute runs an owner's own request without a second
+// confirmation, while still recording the full lifecycle (Decide by the owner →
+// execute) so the on-disk approvals log audits it like any other action. It
+// replies into the conversation the owner asked in (the inbound webhook is still
+// fresh — the owner just messaged). Used for both card and text mode.
+func (o *approvalOrchestrator) autoApproveAndExecute(ctx context.Context, req *ApprovalRequest, convID string, reply approvalReplier) (string, bool) {
+	decided, _ := o.gate.Decide(req.ID, true, o.ownerUserID)
+	if decided == nil {
+		decided = req
+	}
+	fmt.Fprintf(os.Stderr, "[connect][approval][audit] 主人自助操作，自动执行 approvalId=%s owner=%s: %s\n",
+		decided.ID, o.ownerUserID, decided.Summary)
+	out, execErr := o.execute(ctx, decided)
+	if execErr != nil {
+		// Do not lose it: hold for retry and tell the owner to recover. Most
+		// likely the connector's dws login is not the bot owner, so an
+		// owner-scoped action can't run yet.
+		o.gate.markDeferred(decided.ID, execErr.Error())
+		o.recordAudit(ctx, decided.ID)
+		o.notifyOwnerDeferred(ctx, decided, execErr)
+		if reply != nil {
+			_ = reply(ctx, convID, "收到，但现在没能直接完成（已记下，稍后会补做）。")
+		}
+		return "", true
+	}
+	o.gate.markExecuted(decided.ID)
+	o.recordAudit(ctx, decided.ID)
+	if reply != nil {
+		_ = reply(ctx, convID, "已为你完成："+decided.Summary+"\n"+out)
+	}
+	return "", true
+}
+
+// notifyOwnerDeferred privately tells the owner that an action could not run now
+// and is being held, with the likely cause and how to recover (log dws in as the
+// bot owner, then reply "重试"). Best-effort.
+func (o *approvalOrchestrator) notifyOwnerDeferred(ctx context.Context, req *ApprovalRequest, execErr error) {
+	if o.notifier == nil {
+		return
+	}
+	who := strings.TrimSpace(req.Requester)
+	if who == "" || who == o.ownerUserID {
+		who = "你"
+	}
+	msg := fmt.Sprintf("⚠️ %s 请求执行：%s\n但我现在没能以你的身份完成（很可能这台连接器的 dws 没有登录成你本人的账号）。\n"+
+		"已先记下，不会丢。把 dws 登录成机器人主人账号后会自动补做；想立即补做可回复「重试」。\n（错误：%s）",
+		who, req.Summary, truncateRunes(execErr.Error(), 120))
+	_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, msg)
+}
+
+// handleReplyText privately DMs the OWNER the approval request and hands control
+// back to the connector (handled=true). The requester sees nothing — the
+// approval happens only between the owner and the bot. It never blocks: the
+// owner's decision arrives later as an inbound message routed through
+// handleOwnerDecision.
+func (o *approvalOrchestrator) handleReplyText(ctx context.Context, req *ApprovalRequest) (string, bool) {
+	who := strings.TrimSpace(req.Requester)
+	if who == "" {
+		who = "有人"
+	}
+	prompt := fmt.Sprintf("🔔 %s 请求执行一个操作，需要你确认：\n%s\n回复「同意」执行，或「拒绝」取消。", who, req.Summary)
+	if err := o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, prompt); err != nil {
+		// Cannot reach the owner: the action does not run. Do NOT leak the
+		// approval to the requester — text mode's whole point is privacy — so
+		// just log and swallow (handled), leaving the request Pending on disk.
+		fmt.Fprintf(os.Stderr, "[connect][approval] 私聊主人 %s 失败，本次未执行: %v\n", o.ownerUserID, err)
+		return "", true
+	}
+	fmt.Fprintf(os.Stderr, "[connect][approval] 已私聊主人 %s 待确认 approvalId=%s requester=%s: %s\n",
+		o.ownerUserID, req.ID, req.Requester, req.Summary)
+	return "", true
+}
+
+// handleOwnerDecision intercepts an inbound message that is the OWNER replying
+// "同意/拒绝" (in their own 1:1 chat with the bot) to the pending request. It
+// decides, executes-or-declines, privately acks the owner, and sends the
+// outcome to the original requester. Returns true when it consumed the message
+// (so the connector skips forwarding it to the agent). A non-owner sender, a
+// non-decision message, or no pending request all return false (ordinary
+// message). Only active in text mode.
+func (o *approvalOrchestrator) handleOwnerDecision(ctx context.Context, senderStaffID, text string) bool {
+	if o == nil || !o.textMode || !o.enabled() {
+		return false
+	}
+	if senderStaffID == "" || senderStaffID != o.ownerUserID {
+		return false
+	}
+	// "重试/恢复": the owner has recovered — flush the deferred backlog.
+	if isRetryWord(text) {
+		return o.flushDeferred(ctx)
+	}
+	approve, ok := parseDecisionWord(text)
+	if !ok {
+		return false
+	}
+	req := o.gate.latestPending()
+	if req == nil {
+		return false
+	}
+	decided, deciding := o.gate.Decide(req.ID, approve, senderStaffID)
+	if !deciding {
+		// Already decided (e.g. a double reply): consume the keyword, do not
+		// re-execute.
+		return decided != nil
+	}
+	// "remember" policy: cache this decision for the action kind so the next
+	// same-verb request reuses it without asking again.
+	o.rememberDecision(decided.Verb, approve)
+	if !decided.approved() {
+		o.recordAudit(ctx, decided.ID)
+		_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, "好的，已拒绝，未执行。")
+		o.notifyRequester(ctx, decided, "你的请求未获主人批准，本次未执行。")
+		return true
+	}
+	out, execErr := o.execute(ctx, decided)
+	if execErr != nil {
+		// Approved but could not run now → hold for retry, tell the owner how to
+		// recover. The requester is NOT told it failed (their task is not lost).
+		o.gate.markDeferred(decided.ID, execErr.Error())
+		o.recordAudit(ctx, decided.ID)
+		o.notifyOwnerDeferred(ctx, decided, execErr)
+		return true
+	}
+	o.gate.markExecuted(decided.ID)
+	o.recordAudit(ctx, decided.ID)
+	_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, "已同意并执行完成："+decided.Summary)
+	o.notifyRequester(ctx, decided, "已为你完成："+decided.Summary+"\n"+out)
+	return true
+}
+
+// flushDeferred replays the deferred backlog after the owner recovers. Each
+// request is re-executed; on success it is marked executed and the original
+// requester gets the outcome, on failure it stays deferred (still not lost).
+// The owner gets a summary. Returns true (the "重试" message is always consumed).
+func (o *approvalOrchestrator) flushDeferred(ctx context.Context) bool {
+	pending := o.gate.allDeferred()
+	if len(pending) == 0 {
+		_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, "当前没有积压的请求。")
+		return true
+	}
+	done, stuck := o.flushDeferredOnce(ctx, pending)
+	// Manual "重试" always reports back (the owner asked), naming what was done.
+	var b strings.Builder
+	fmt.Fprintf(&b, "已补做 %d 个积压请求", len(done))
+	if len(done) > 0 {
+		b.WriteString("：\n")
+		for i, s := range done {
+			fmt.Fprintf(&b, "%d. %s\n", i+1, s)
+		}
+	} else {
+		b.WriteString("。")
+	}
+	if stuck > 0 {
+		fmt.Fprintf(&b, "仍有 %d 个未成功（身份可能还没对上，确认 dws 登录后再回复「重试」）。", stuck)
+	}
+	_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, strings.TrimRight(b.String(), "\n"))
+	return true
+}
+
+// flushDeferredOnce re-executes each given deferred request once. Successful
+// ones are marked executed and their requester is notified; failed ones stay
+// deferred. Returns the completed summaries and the still-stuck count. Shared by
+// the manual "重试" path and the background auto-retry.
+func (o *approvalOrchestrator) flushDeferredOnce(ctx context.Context, pending []*ApprovalRequest) (done []string, stuck int) {
+	for _, req := range pending {
+		out, execErr := o.execute(ctx, req)
+		if execErr != nil {
+			o.gate.markDeferred(req.ID, execErr.Error())
+			o.recordAudit(ctx, req.ID)
+			stuck++
+			continue
+		}
+		o.gate.markExecuted(req.ID)
+		o.recordAudit(ctx, req.ID)
+		o.notifyRequester(ctx, req, "（已恢复）已为你完成："+req.Summary+"\n"+out)
+		done = append(done, req.Summary)
+	}
+	return done, stuck
+}
+
+// autoFlushDeferred is the background-retry pass: it replays the backlog and
+// messages the owner ONLY when something actually completed (so a periodic tick
+// while the identity is still wrong stays silent — no spam). The requester is
+// still notified per completed item inside flushDeferredOnce.
+func (o *approvalOrchestrator) autoFlushDeferred(ctx context.Context) {
+	pending := o.gate.allDeferred()
+	if len(pending) == 0 {
+		return
+	}
+	done, _ := o.flushDeferredOnce(ctx, pending)
+	if len(done) == 0 {
+		return
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "（已自动恢复）补做了 %d 个积压请求：\n", len(done))
+	for i, s := range done {
+		fmt.Fprintf(&b, "%d. %s\n", i+1, s)
+	}
+	_ = o.notifier.sendOTOText(ctx, []string{o.ownerUserID}, strings.TrimRight(b.String(), "\n"))
+}
+
+// startAutoRetry runs autoFlushDeferred on an interval until ctx is cancelled,
+// so a deferred backlog drains by itself once the owner's identity comes back —
+// no manual "重试" needed. A no-op when there is no notifier (card mode) or a
+// non-positive interval.
+func (o *approvalOrchestrator) startAutoRetry(ctx context.Context, interval time.Duration) {
+	if o == nil || o.notifier == nil || interval <= 0 {
+		return
+	}
+	go func() {
+		t := time.NewTicker(interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				o.autoFlushDeferred(ctx)
+			}
+		}
+	}()
+}
+
+// notifyRequester sends the outcome to the original requester, unless they are
+// the owner themselves (who already got the owner-side ack — no need to double
+// message). Best-effort.
+func (o *approvalOrchestrator) notifyRequester(ctx context.Context, req *ApprovalRequest, text string) {
+	who := strings.TrimSpace(req.Requester)
+	if who == "" || who == o.ownerUserID {
+		return
+	}
+	_ = o.notifier.sendOTOText(ctx, []string{who}, text)
+}
+
+// handleReplyCard runs the interactive-card flow: deliver the [Approve]/[Reject]
+// card to the owner, block for the decision, then execute-or-decline and report
+// the outcome into the conversation.
+func (o *approvalOrchestrator) handleReplyCard(ctx context.Context, req *ApprovalRequest, convID string, reply approvalReplier) (string, bool) {
+	outTrackID, err := o.sender.SendApprovalCard(ctx, o.ownerUserID, req)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 确认卡片投放失败: %v\n", err)
+		// Cannot ask the owner → tell the requester the gate could not engage,
+		// rather than silently executing or silently dropping.
+		return "（需要主人确认，但确认卡片发送失败，本次未执行）", false
+	}
+	o.gate.setOutTrackID(req.ID, outTrackID)
+	fmt.Fprintf(os.Stderr, "[connect][approval] 已向主人 %s 发送确认卡片 approvalId=%s outTrackId=%s: %s\n",
+		o.ownerUserID, req.ID, outTrackID, req.Summary)
+
+	// Block for the owner's decision off the connector's per-conversation
+	// worker is fine: the worker already serializes one conversation, and the
+	// gate persists so a restart mid-wait loses only the in-memory block.
+	decided, gotDecision := o.gate.Await(ctx, req.ID, o.awaitWindow)
+	if !gotDecision || decided == nil {
+		_ = reply(ctx, convID, "（等待主人确认超时，本次未执行）")
+		return "", true
+	}
+	if !decided.approved() {
+		o.recordAudit(ctx, decided.ID)
+		_ = o.sender.UpdateApprovalCard(ctx, decided.OutTrackID, "已拒绝：未执行。")
+		_ = reply(ctx, convID, "主人暂时没批准。")
+		return "", true
+	}
+
+	// Approved → the orchestrator runs the planned command directly (no agent
+	// round-trip), then reports the outcome to the group and the card.
+	out, execErr := o.execute(ctx, decided)
+	if execErr != nil {
+		o.gate.markFailed(decided.ID, execErr.Error())
+		o.recordAudit(ctx, decided.ID)
+		_ = o.sender.UpdateApprovalCard(ctx, decided.OutTrackID, "已同意，但执行失败："+execErr.Error())
+		_ = reply(ctx, convID, "主人已同意，但执行失败："+execErr.Error())
+		return "", true
+	}
+	o.gate.markExecuted(decided.ID)
+	o.recordAudit(ctx, decided.ID)
+	_ = o.sender.UpdateApprovalCard(ctx, decided.OutTrackID, "已同意并执行完成。")
+	_ = reply(ctx, convID, "主人已同意，已执行："+decided.Summary+"\n"+out)
+	return "", true
+}
+
+// execute runs the request's planned action via the runner and returns a short
+// human-readable result line. It is the only place the gate touches the
+// executor, so adding a new approvable verb is a matter of toPlannedAction +
+// the runner already supporting that tool.
+func (o *approvalOrchestrator) execute(ctx context.Context, req *ApprovalRequest) (string, error) {
+	if o.runner == nil {
+		return "", fmt.Errorf("no runner configured")
+	}
+	inv := executor.NewHelperInvocation(req.Action.LegacyPath, req.Action.Product, req.Action.Tool, req.Action.Params)
+	res, err := o.runner.Run(ctx, inv)
+	if err != nil {
+		return "", err
+	}
+	if !res.Invocation.Implemented {
+		// The helper override was not wired at runtime (e.g. dry-run / discovery
+		// gap): surface it rather than claim success.
+		return "（动作已受理，但运行时未实际执行——请检查命令是否在当前环境可用）", nil
+	}
+	return "（待办已创建）", nil
+}
+
+// handleCardCallback maps a button tap to gate.Decide. It pulls the approval id
+// and decision from the action params (primary association), falling back to the
+// card instance id (OutTrackId) when the params are absent. Returns a card
+// response that flips the buttons to a decided state. Safe to call repeatedly:
+// a second tap after a decision is a no-op (Decide is idempotent).
+func (o *approvalOrchestrator) handleCardCallback(ctx context.Context, req *card.CardRequest) (*card.CardResponse, error) {
+	if o == nil || o.gate == nil || req == nil {
+		return &card.CardResponse{}, nil
+	}
+	id, approve, ok := decodeCardAction(req)
+	if !ok {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 卡片回调无法解析动作 outTrackId=%s\n", req.OutTrackId)
+		return &card.CardResponse{}, nil
+	}
+	if id == "" {
+		// No approval id in the params: associate by the card instance id.
+		if found := o.gate.findByOutTrackID(req.OutTrackId); found != nil {
+			id = found.ID
+		}
+	}
+	if id == "" {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 卡片回调无法关联审批 outTrackId=%s\n", req.OutTrackId)
+		return &card.CardResponse{}, nil
+	}
+	decided, deciding := o.gate.Decide(id, approve, strings.TrimSpace(req.UserId))
+	verb := "同意"
+	if !approve {
+		verb = "拒绝"
+	}
+	if deciding {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 主人 %s 点了[%s] approvalId=%s\n", req.UserId, verb, id)
+	} else if decided != nil {
+		fmt.Fprintf(os.Stderr, "[connect][approval] 审批 %s 已是终态(%s)，忽略重复点击\n", id, decided.State)
+	}
+	// Echo the decision back into the card's private data so the renderer can
+	// show a decided state. Best-effort; the gate state is the source of truth.
+	return &card.CardResponse{
+		UserPrivateData: &card.CardDataDto{
+			CardParamMap: map[string]string{"dwsDecision": verb},
+		},
+	}, nil
+}
+
+// decodeCardAction extracts (approvalId, approve, ok) from a card callback. It
+// prefers the explicit decision param, then the tapped action id, so the card
+// can carry the decision either way. ok is false when neither identifies a
+// decision (a non-approval card, or a malformed payload).
+func decodeCardAction(req *card.CardRequest) (id string, approve bool, ok bool) {
+	id = strings.TrimSpace(req.GetActionString(approvalParamID))
+	decision := strings.TrimSpace(req.GetActionString(approvalParamDecision))
+	switch decision {
+	case approvalDecisionApprove:
+		return id, true, true
+	case approvalDecisionReject:
+		return id, false, true
+	}
+	// Fall back to which button was pressed (its action id).
+	for _, a := range req.CardActionData.CardPrivateData.ActionIdList {
+		switch strings.TrimSpace(a) {
+		case approvalActionApprove:
+			return id, true, true
+		case approvalActionReject:
+			return id, false, true
+		}
+	}
+	return id, false, false
+}
+
+// ---- Real (HTTP) card sender ----
+
+// dingtalkApprovalCardSender delivers the interactive approval card via the
+// DingTalk card API, reusing aiCardClient for auth + the create/deliver/update
+// HTTP plumbing. The card template must define two buttons whose action params
+// the connector fills in (approval id + decision); see the docstring on
+// SendApprovalCard for the contract.
+type dingtalkApprovalCardSender struct {
+	cli        *aiCardClient
+	templateID string
+}
+
+// newDingtalkApprovalCardSender builds the real sender. An empty templateID
+// returns nil: without an interactive-card template the connector cannot render
+// buttons, so the caller must keep the gate disabled rather than deliver a card
+// the owner cannot act on.
+func newDingtalkApprovalCardSender(clientID, clientSecret, templateID string) approvalCardSender {
+	templateID = strings.TrimSpace(templateID)
+	if templateID == "" {
+		return nil
+	}
+	return &dingtalkApprovalCardSender{
+		cli:        newAICardClient(clientID, clientSecret, templateID),
+		templateID: templateID,
+	}
+}
+
+// SendApprovalCard creates an interactive card instance and delivers it to the
+// owner's 1:1 chat with the bot. The approval id and per-button decision are
+// passed in cardData.cardParamMap so the template's [Approve]/[Reject] buttons
+// echo them back as action params on tap (see decodeCardAction). Best-effort
+// result-check via callChecked surfaces a per-target deliver failure that the
+// card API hides inside an HTTP 200.
+func (s *dingtalkApprovalCardSender) SendApprovalCard(ctx context.Context, ownerUserID string, req *ApprovalRequest) (string, error) {
+	outTrackID := "dws_approval_" + req.ID
+	create := map[string]any{
+		"cardTemplateId": s.templateID,
+		"outTrackId":     outTrackID,
+		"cardData": map[string]any{
+			"cardParamMap": map[string]any{
+				"title":           "需要你确认",
+				"summary":         req.Summary,
+				"requester":       req.Requester,
+				approvalParamID:   req.ID,
+				"approveDecision": approvalDecisionApprove,
+				"rejectDecision":  approvalDecisionReject,
+				"approveActionId": approvalActionApprove,
+				"rejectActionId":  approvalActionReject,
+				"config":          `{"autoLayout":true}`,
+			},
+		},
+		"callbackType":          "STREAM",
+		"imRobotOpenSpaceModel": map[string]any{"supportForward": true},
+	}
+	if err := s.cli.call(ctx, http.MethodPost, "/v1.0/card/instances", create); err != nil {
+		return "", err
+	}
+	deliver := map[string]any{
+		"outTrackId":  outTrackID,
+		"userIdType":  1,
+		"openSpaceId": "dtv1.card//IM_ROBOT." + ownerUserID,
+		"imRobotOpenDeliverModel": map[string]any{
+			"spaceType": "IM_ROBOT",
+			"robotCode": s.cli.clientID,
+		},
+	}
+	if err := s.cli.callChecked(ctx, http.MethodPost, "/v1.0/card/instances/deliver", deliver); err != nil {
+		return "", err
+	}
+	return outTrackID, nil
+}
+
+// UpdateApprovalCard rewrites the card's result line after a decision. It is
+// best-effort: a stuck card is bad UX but must never fail the gate flow, so
+// callers ignore the error.
+func (s *dingtalkApprovalCardSender) UpdateApprovalCard(ctx context.Context, outTrackID, text string) error {
+	return s.cli.call(ctx, http.MethodPut, "/v1.0/card/instances", map[string]any{
+		"outTrackId":        outTrackID,
+		"cardData":          map[string]any{"cardParamMap": map[string]any{"result": text, "summary": text}},
+		"cardUpdateOptions": map[string]any{"updateCardDataByKey": true},
+	})
+}

internal/helpers/connect_approval_card_test.go

@@ -0,0 +1,863 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/card"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+)
+
+// ---- fakes (no network, no real runner) ----
+
+type fakeCardSender struct {
+	mu        sync.Mutex
+	sent      []*ApprovalRequest
+	updates   []string
+	failSend  bool
+	lastTrack string
+}
+
+func (f *fakeCardSender) SendApprovalCard(_ context.Context, _ string, req *ApprovalRequest) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.failSend {
+		return "", context.DeadlineExceeded
+	}
+	f.sent = append(f.sent, req)
+	f.lastTrack = "track-" + req.ID
+	return f.lastTrack, nil
+}
+
+func (f *fakeCardSender) UpdateApprovalCard(_ context.Context, _, text string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.updates = append(f.updates, text)
+	return nil
+}
+
+// fakeRunner records the invocations it is asked to run and reports them as
+// implemented (so the orchestrator treats them as executed).
+type fakeRunner struct {
+	mu   sync.Mutex
+	runs []executor.Invocation
+	fail bool // when true, Run returns an error (simulates identity not ready)
+}
+
+func (r *fakeRunner) Run(_ context.Context, inv executor.Invocation) (executor.Result, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.runs = append(r.runs, inv)
+	if r.fail {
+		return executor.Result{}, context.DeadlineExceeded
+	}
+	inv.Implemented = true
+	return executor.Result{Invocation: inv}, nil
+}
+
+func (r *fakeRunner) setFail(v bool) { r.mu.Lock(); defer r.mu.Unlock(); r.fail = v }
+
+func (r *fakeRunner) count() int { r.mu.Lock(); defer r.mu.Unlock(); return len(r.runs) }
+
+// fakeNotifier records the proactive 1:1 messages text-mode approval sends to
+// the owner and the requester.
+type fakeNotifier struct {
+	mu   sync.Mutex
+	sent []sentMsg
+}
+
+type sentMsg struct {
+	to   []string
+	text string
+}
+
+func (n *fakeNotifier) sendOTOText(_ context.Context, userIDs []string, text string) error {
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	n.sent = append(n.sent, sentMsg{to: append([]string(nil), userIDs...), text: text})
+	return nil
+}
+
+// toUser reports whether any recorded message was sent to userID.
+func (n *fakeNotifier) toUser(userID string) bool {
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	for _, m := range n.sent {
+		for _, u := range m.to {
+			if u == userID {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func (n *fakeNotifier) count() int { n.mu.Lock(); defer n.mu.Unlock(); return len(n.sent) }
+
+// cardClickReq builds a card callback as DingTalk delivers it: the tapped
+// button's action id plus its private params (approval id + decision).
+func cardClickReq(outTrackID, approvalID, decision, actionID, userID string) *card.CardRequest {
+	return &card.CardRequest{
+		OutTrackId: outTrackID,
+		UserId:     userID,
+		CardActionData: card.PrivateCardActionData{
+			CardPrivateData: card.CardPrivateData{
+				ActionIdList: []string{actionID},
+				Params: map[string]any{
+					approvalParamID:       approvalID,
+					approvalParamDecision: decision,
+				},
+			},
+		},
+	}
+}
+
+// TestDecodeCardAction verifies the action parser pulls the approval id and the
+// approve/reject decision from a button tap, via params and via the action id
+// fallback.
+func TestDecodeCardAction(t *testing.T) {
+	approve := cardClickReq("t1", "appr-1", approvalDecisionApprove, approvalActionApprove, "owner")
+	id, ok2, ok := decodeCardAction(approve)
+	if !ok || !ok2 || id != "appr-1" {
+		t.Fatalf("approve decode: id=%q approve=%v ok=%v", id, ok2, ok)
+	}
+
+	reject := cardClickReq("t2", "appr-2", approvalDecisionReject, approvalActionReject, "owner")
+	id, ok2, ok = decodeCardAction(reject)
+	if !ok || ok2 || id != "appr-2" {
+		t.Fatalf("reject decode: id=%q approve=%v ok=%v", id, ok2, ok)
+	}
+
+	// Decision param missing → fall back to the tapped action id.
+	fallback := &card.CardRequest{
+		OutTrackId: "t3",
+		CardActionData: card.PrivateCardActionData{
+			CardPrivateData: card.CardPrivateData{
+				ActionIdList: []string{approvalActionApprove},
+				Params:       map[string]any{approvalParamID: "appr-3"},
+			},
+		},
+	}
+	id, ok2, ok = decodeCardAction(fallback)
+	if !ok || !ok2 || id != "appr-3" {
+		t.Fatalf("fallback decode: id=%q approve=%v ok=%v", id, ok2, ok)
+	}
+
+	// A non-approval card → not ok.
+	if _, _, ok := decodeCardAction(&card.CardRequest{OutTrackId: "x"}); ok {
+		t.Fatal("non-approval card should not decode as a decision")
+	}
+}
+
+// TestHandleCardCallback_DrivesDecide verifies a button callback flips the gate
+// state and that an approval id missing from params is recovered by outTrackId.
+func TestHandleCardCallback_DrivesDecide(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("c1")
+	o := newApprovalOrchestrator(gate, &fakeCardSender{}, &fakeRunner{}, "owner")
+
+	app := gate.Submit(ApprovalRequest{Summary: "x"})
+	gate.setOutTrackID(app.ID, "track-x")
+
+	// Callback carries no approval id in params → associate by outTrackId.
+	req := &card.CardRequest{
+		OutTrackId: "track-x",
+		UserId:     "owner",
+		CardActionData: card.PrivateCardActionData{
+			CardPrivateData: card.CardPrivateData{ActionIdList: []string{approvalActionApprove}},
+		},
+	}
+	if _, err := o.handleCardCallback(context.Background(), req); err != nil {
+		t.Fatalf("callback err: %v", err)
+	}
+	if got := gate.Get(app.ID); !got.approved() {
+		t.Fatalf("state = %s, want approved after approve tap", got.State)
+	}
+}
+
+// TestHandleReply_RejectDoesNotExecute is the reject-path guarantee: a rejected
+// approval must NOT run the planned command.
+func TestHandleReply_RejectDoesNotExecute(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("c2")
+	sender := &fakeCardSender{}
+	runner := &fakeRunner{}
+	o := newApprovalOrchestrator(gate, sender, runner, "owner")
+	o.awaitWindow = time.Second
+
+	var replies []string
+	var rmu sync.Mutex
+	reply := func(_ context.Context, _, text string) error {
+		rmu.Lock()
+		replies = append(replies, text)
+		rmu.Unlock()
+		return nil
+	}
+
+	// The owner rejects shortly after the card is sent.
+	go func() {
+		deadline := time.Now().Add(time.Second)
+		for time.Now().Before(deadline) {
+			sender.mu.Lock()
+			n := len(sender.sent)
+			var id string
+			if n > 0 {
+				id = sender.sent[0].ID
+			}
+			sender.mu.Unlock()
+			if id != "" {
+				gate.Decide(id, false, "owner")
+				return
+			}
+			time.Sleep(5 * time.Millisecond)
+		}
+	}()
+
+	agentReply := `好的。[[ACTION:todo.create title="交方案"]]`
+	out, handled := o.handleReply(context.Background(), "requester", "conv-1", agentReply, reply)
+	if !handled {
+		t.Fatal("an action reply must be handled by the gate")
+	}
+	if out != "" {
+		t.Fatalf("handled reply should return empty connector reply, got %q", out)
+	}
+	if runner.count() != 0 {
+		t.Fatalf("reject path must NOT execute, runner ran %d times", runner.count())
+	}
+	if gate.Get(gate.list()[0].ID).State != approvalRejected {
+		t.Fatal("request should be rejected")
+	}
+	rmu.Lock()
+	joined := strings.Join(replies, " | ")
+	rmu.Unlock()
+	if !strings.Contains(joined, "没批准") {
+		t.Fatalf("reject reply not posted: %q", joined)
+	}
+}
+
+// TestToPlannedAction_Actions covers the action verbs the twin can execute:
+// each maps to the right product/tool, and missing required args degrade to
+// "not an action" (ok=false) so a malformed marker never submits a no-op.
+func TestToPlannedAction_Actions(t *testing.T) {
+	cases := []struct {
+		name        string
+		act         detectedAction
+		wantOK      bool
+		wantProduct string
+		wantTool    string
+	}{
+		{"todo", detectedAction{Verb: "todo.create", Args: map[string]string{"title": "交方案"}}, true, "todo", "create_personal_todo"},
+		{"calendar", detectedAction{Verb: "calendar.create", Args: map[string]string{"title": "评审会", "start": "2026-06-20T10:00:00+08:00", "end": "2026-06-20T11:00:00+08:00"}}, true, "calendar", "create_calendar_event"},
+		{"calendar missing time", detectedAction{Verb: "calendar.create", Args: map[string]string{"title": "评审会"}}, false, "", ""},
+		{"doc", detectedAction{Verb: "doc.create", Args: map[string]string{"name": "周报"}}, true, "doc", "create_document"},
+		{"doc missing name", detectedAction{Verb: "doc.create", Args: map[string]string{}}, false, "", ""},
+		{"unknown verb", detectedAction{Verb: "drive.delete", Args: map[string]string{}}, false, "", ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			pa, summary, ok := toPlannedAction(tc.act, "owner")
+			if ok != tc.wantOK {
+				t.Fatalf("ok=%v want %v", ok, tc.wantOK)
+			}
+			if !ok {
+				return
+			}
+			if pa.Product != tc.wantProduct || pa.Tool != tc.wantTool {
+				t.Fatalf("got %s/%s want %s/%s", pa.Product, pa.Tool, tc.wantProduct, tc.wantTool)
+			}
+			if summary == "" {
+				t.Fatal("summary should not be empty for a valid action")
+			}
+			// Every twin action is write-class → must be gated.
+			if classifyPlannedAction(pa) != CmdClassWrite {
+				t.Fatalf("%s should classify as write (gated), got %s", tc.name, classifyPlannedAction(pa))
+			}
+		})
+	}
+}
+
+// TestClassifyPlannedAction verifies the gate's read/write bridge: it classifies
+// on the human command path first and falls back to product + RPC tool name.
+func TestClassifyPlannedAction(t *testing.T) {
+	cases := []struct {
+		name string
+		pa   plannedAction
+		want CmdClass
+	}{
+		{
+			name: "write via legacy path",
+			pa:   plannedAction{Product: "todo", Tool: "create_personal_todo", LegacyPath: "todo task create"},
+			want: CmdClassWrite,
+		},
+		{
+			name: "read via legacy path",
+			pa:   plannedAction{Product: "todo", Tool: "list_personal_todo", LegacyPath: "todo task list"},
+			want: CmdClassRead,
+		},
+		{
+			name: "empty legacy path falls back to product+tool",
+			pa:   plannedAction{Product: "todo", Tool: "create_personal_todo"},
+			want: CmdClassWrite,
+		},
+		{
+			name: "unrecognised path falls back to tool verb",
+			pa:   plannedAction{Product: "todo", Tool: "delete_personal_todo", LegacyPath: "todo xyz123"},
+			want: CmdClassWrite,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := classifyPlannedAction(tc.pa); got != tc.want {
+				t.Fatalf("classifyPlannedAction(%+v) = %s, want %s", tc.pa, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestHandleReply_ReadClassBypassesGate proves the "写类才拦" wiring: when the
+// planned command classifies as read-only, the gate does not engage — no card is
+// sent, nothing runs, and the cleaned reply goes out normally (handled=false).
+// We force the todo.create path to read-class via an override so the test drives
+// the real handleReply → classifyPlannedAction path end to end.
+func TestHandleReply_ReadClassBypassesGate(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	SetCmdClassOverride("todo task create", CmdClassRead)
+	defer SetCmdClassOverride("todo task create", CmdClassUnknown)
+
+	gate := newApprovalGate("c3")
+	sender := &fakeCardSender{}
+	runner := &fakeRunner{}
+	o := newApprovalOrchestrator(gate, sender, runner, "owner")
+
+	reply := func(_ context.Context, _, _ string) error { return nil }
+	agentReply := `好的，已为你查到。[[ACTION:todo.create title="交方案"]]`
+	out, handled := o.handleReply(context.Background(), "requester", "conv-1", agentReply, reply)
+
+	if handled {
+		t.Fatal("a read-class action must NOT be handled by the gate")
+	}
+	if !strings.Contains(out, "已为你查到") || strings.Contains(out, "[[ACTION") {
+		t.Fatalf("read-class reply should be the cleaned text without the marker, got %q", out)
+	}
+	sender.mu.Lock()
+	nSent := len(sender.sent)
+	sender.mu.Unlock()
+	if nSent != 0 {
+		t.Fatalf("read-class action must not send a confirmation card, sent %d", nSent)
+	}
+	if runner.count() != 0 {
+		t.Fatalf("read-class action must not execute, runner ran %d times", runner.count())
+	}
+	if len(gate.list()) != 0 {
+		t.Fatalf("read-class action must not create an approval request, got %d", len(gate.list()))
+	}
+}
+
+// TestParseDecisionWord checks whole-message decision parsing: a bare keyword
+// decides, anything else (including a keyword embedded in a sentence) does not.
+func TestParseDecisionWord(t *testing.T) {
+	cases := []struct {
+		in          string
+		wantApprove bool
+		wantOk      bool
+	}{
+		{"同意", true, true},
+		{"  同意  ", true, true},
+		{"通过", true, true},
+		{"Yes", true, true},
+		{"OK", true, true},
+		{"拒绝", false, true},
+		{"no", false, true},
+		{"不同意", false, true},
+		{"同意他的看法", false, false}, // embedded, not a bare decision
+		{"帮我创建个待办", false, false},
+		{"", false, false},
+	}
+	for _, tc := range cases {
+		gotApprove, gotOk := parseDecisionWord(tc.in)
+		if gotOk != tc.wantOk || (tc.wantOk && gotApprove != tc.wantApprove) {
+			t.Fatalf("parseDecisionWord(%q) = (%v,%v), want (%v,%v)", tc.in, gotApprove, gotOk, tc.wantApprove, tc.wantOk)
+		}
+	}
+}
+
+// TestPendingForConv finds the pending request for a conversation and stops
+// returning it once decided.
+func TestPendingForConv(t *testing.T) {
+	gate := newApprovalGate("") // in-memory
+	a := gate.Submit(ApprovalRequest{ConvID: "c1", Summary: "a"})
+	gate.Submit(ApprovalRequest{ConvID: "c2", Summary: "b"})
+
+	if got := gate.pendingForConv("c1"); got == nil || got.ID != a.ID {
+		t.Fatalf("pendingForConv(c1) = %v, want request %s", got, a.ID)
+	}
+	if got := gate.pendingForConv("none"); got != nil {
+		t.Fatalf("pendingForConv(none) = %v, want nil", got)
+	}
+	gate.Decide(a.ID, true, "owner")
+	if got := gate.pendingForConv("c1"); got != nil {
+		t.Fatalf("decided request must not be pending, got %v", got)
+	}
+}
+
+// TestHandleReply_TextMode_OwnerApproves is the private text-approval happy
+// path: an action privately DMs the OWNER (the requester sees nothing, no
+// execution yet); a non-owner "同意" is ignored; the owner's "同意" — sent from
+// their own chat, NOT the request conversation — decides and executes.
+func TestHandleReply_TextMode_OwnerApproves(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ct1")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	// A group requester (not the owner) asks for an action.
+	out, handled := o.handleReply(context.Background(), "requester", "conv-group", `好的。[[ACTION:todo.create title="交方案"]]`, nil)
+	if !handled || out != "" {
+		t.Fatalf("text-mode action: handled=%v out=%q, want handled with empty out (requester sees nothing)", handled, out)
+	}
+	if runner.count() != 0 {
+		t.Fatalf("must not execute before the owner decides, ran %d", runner.count())
+	}
+	if len(gate.list()) != 1 {
+		t.Fatalf("expected one pending request, got %d", len(gate.list()))
+	}
+	// The approval prompt went privately to the OWNER, never to the requester.
+	if !notifier.toUser("owner") {
+		t.Fatalf("approval prompt was not DMed to the owner: %+v", notifier.sent)
+	}
+	if notifier.toUser("requester") {
+		t.Fatal("the requester must NOT be notified of the approval")
+	}
+
+	// A non-owner saying 同意 must not decide or execute.
+	if o.handleOwnerDecision(context.Background(), "intruder", "同意") {
+		t.Fatal("non-owner must not be able to approve")
+	}
+	if runner.count() != 0 {
+		t.Fatalf("non-owner approval must not execute, ran %d", runner.count())
+	}
+
+	// The owner saying 同意 decides and executes; the requester then gets the
+	// outcome.
+	if !o.handleOwnerDecision(context.Background(), "owner", "同意") {
+		t.Fatal("owner approval must be consumed")
+	}
+	if runner.count() != 1 {
+		t.Fatalf("owner approval must execute exactly once, ran %d", runner.count())
+	}
+	if gate.list()[0].State != approvalExecuted {
+		t.Fatalf("request state = %s, want executed", gate.list()[0].State)
+	}
+	if !notifier.toUser("requester") {
+		t.Fatal("the requester should get the final outcome after execution")
+	}
+}
+
+// TestHandleReply_TextMode_OwnerSelfAutoApproves: when the requester IS the
+// owner, the action runs immediately with NO confirmation round-trip, but is
+// still recorded (auto_approved=true, decided-by owner, executed) for audit.
+func TestHandleReply_TextMode_OwnerSelfAutoApproves(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctself")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	var replies []string
+	reply := func(_ context.Context, _, text string) error { replies = append(replies, text); return nil }
+
+	// The OWNER asks for the action themselves.
+	out, handled := o.handleReply(context.Background(), "owner", "conv-owner", `好。[[ACTION:todo.create title="自己的待办"]]`, reply)
+	if !handled || out != "" {
+		t.Fatalf("owner self-request: handled=%v out=%q", handled, out)
+	}
+	// Executed immediately — no second confirmation asked.
+	if runner.count() != 1 {
+		t.Fatalf("owner self-request must execute immediately, ran %d", runner.count())
+	}
+	if notifier.count() != 0 {
+		t.Fatalf("owner self-request must NOT send an approval DM, sent %d", notifier.count())
+	}
+	// Still recorded for audit: auto_approved + executed + decided by owner.
+	rec := gate.list()[0]
+	if !rec.AutoApproved || rec.State != approvalExecuted || rec.DecidedBy != "owner" {
+		t.Fatalf("audit record wrong: autoApproved=%v state=%s decidedBy=%s", rec.AutoApproved, rec.State, rec.DecidedBy)
+	}
+	if !strings.Contains(strings.Join(replies, "|"), "已为你完成") {
+		t.Fatalf("owner should get the result, replies=%v", replies)
+	}
+}
+
+// fakeAudit records the requests handed to the audit sink.
+type fakeAudit struct {
+	mu   sync.Mutex
+	recs []*ApprovalRequest
+}
+
+func (a *fakeAudit) record(_ context.Context, req *ApprovalRequest) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	cp := *req
+	a.recs = append(a.recs, &cp)
+}
+
+func (a *fakeAudit) count() int { a.mu.Lock(); defer a.mu.Unlock(); return len(a.recs) }
+
+// TestAudit_RecordsTerminalOutcomes verifies the audit sink gets one terminal
+// record per action: an auto-executed owner request, and an approved request.
+func TestAudit_RecordsTerminalOutcomes(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("cta")
+	audit := &fakeAudit{}
+	o := newTextApprovalOrchestrator(gate, &fakeRunner{}, "owner", &fakeNotifier{})
+	o.audit = audit
+	reply := func(_ context.Context, _, _ string) error { return nil }
+
+	// Owner self-request → auto-executed → audited once, as executed.
+	o.handleReply(context.Background(), "owner", "conv-o", `[[ACTION:todo.create title="自己"]]`, reply)
+	if audit.count() != 1 {
+		t.Fatalf("auto-exec must produce one audit record, got %d", audit.count())
+	}
+	if audit.recs[0].State != approvalExecuted || !audit.recs[0].AutoApproved {
+		t.Fatalf("auto audit record: state=%s auto=%v", audit.recs[0].State, audit.recs[0].AutoApproved)
+	}
+
+	// Someone else's request, approved by the owner → audited as executed.
+	o.handleReply(context.Background(), "requester", "conv-g", `[[ACTION:todo.create title="别人"]]`, reply)
+	if audit.count() != 1 {
+		t.Fatal("a pending (not yet decided) request must not be audited yet")
+	}
+	o.handleOwnerDecision(context.Background(), "owner", "同意")
+	if audit.count() != 2 {
+		t.Fatalf("owner approval must produce a second audit record, got %d", audit.count())
+	}
+	if audit.recs[1].State != approvalExecuted || audit.recs[1].DecidedBy != "owner" {
+		t.Fatalf("approved audit record: state=%s decidedBy=%s", audit.recs[1].State, audit.recs[1].DecidedBy)
+	}
+}
+
+// TestDeferredExecution_HoldsAndRetries is the graceful-degradation path: when
+// execution fails (identity not ready), the request is DEFERRED (not lost, not
+// failed), the owner is privately notified; after the owner recovers and replies
+// "重试", the backlog is replayed, executes, and the requester gets the result.
+func TestDeferredExecution_HoldsAndRetries(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctdef")
+	runner := &fakeRunner{fail: true} // identity not ready → execution fails
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	// A non-owner request, approved by the owner, but execution fails → deferred.
+	o.handleReply(context.Background(), "requester", "conv-g", `[[ACTION:todo.create title="待恢复"]]`, nil)
+	if !o.handleOwnerDecision(context.Background(), "owner", "同意") {
+		t.Fatal("owner approval must be consumed")
+	}
+	rec := gate.list()[0]
+	if rec.State != approvalDeferred {
+		t.Fatalf("failed execution must DEFER (not fail), got state=%s", rec.State)
+	}
+	// Owner was told to recover; requester was NOT told it failed (task not lost).
+	if !notifier.toUser("owner") {
+		t.Fatal("owner should be notified of the deferred action")
+	}
+	if notifier.toUser("requester") {
+		t.Fatal("requester must NOT be told it failed — their task is held, not lost")
+	}
+
+	// A bare non-retry word from the owner should pass through (not consumed).
+	if o.handleOwnerDecision(context.Background(), "owner", "在吗") {
+		t.Fatal("ordinary owner message must not be consumed")
+	}
+
+	// Owner recovers (identity now works) and replies "重试" → backlog flushes.
+	runner.setFail(false)
+	if !o.handleOwnerDecision(context.Background(), "owner", "重试") {
+		t.Fatal("retry word must be consumed")
+	}
+	if gate.list()[0].State != approvalExecuted {
+		t.Fatalf("after retry the deferred request must execute, got %s", gate.list()[0].State)
+	}
+	if !notifier.toUser("requester") {
+		t.Fatal("requester should get the outcome after the backlog is flushed")
+	}
+}
+
+// TestConfirmPolicy_Auto: a non-owner request runs without asking under "auto".
+func TestConfirmPolicy_Auto(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctauto2")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+	o.confirmPolicy = "auto"
+
+	_, handled := o.handleReply(context.Background(), "someone", "c1", `[[ACTION:todo.create title="x"]]`, func(_ context.Context, _, _ string) error { return nil })
+	if !handled {
+		t.Fatal("auto policy should handle (run) the action")
+	}
+	if runner.count() != 1 {
+		t.Fatalf("auto policy must execute without asking, ran %d", runner.count())
+	}
+	if gate.list()[0].State != approvalExecuted {
+		t.Fatalf("state=%s want executed", gate.list()[0].State)
+	}
+}
+
+// TestConfirmPolicy_Manual: a non-owner request asks the owner (default).
+func TestConfirmPolicy_Manual(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctman")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier) // no policy = manual
+
+	o.handleReply(context.Background(), "someone", "c1", `[[ACTION:todo.create title="x"]]`, nil)
+	if runner.count() != 0 {
+		t.Fatal("manual policy must NOT execute before the owner decides")
+	}
+	if gate.list()[0].State != approvalPending {
+		t.Fatalf("state=%s want pending (awaiting owner)", gate.list()[0].State)
+	}
+	if !notifier.toUser("owner") {
+		t.Fatal("manual policy should DM the owner for approval")
+	}
+}
+
+// TestConfirmPolicy_Remember: ask once per verb, then reuse the decision.
+func TestConfirmPolicy_Remember(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctrem")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+	o.confirmPolicy = "remember"
+
+	// First todo.create from a non-owner → asks (pending).
+	o.handleReply(context.Background(), "someone", "c1", `[[ACTION:todo.create title="第一次"]]`, nil)
+	if gate.latestPending() == nil {
+		t.Fatal("first request should ask the owner")
+	}
+	// Owner approves → remembered, executes.
+	o.handleOwnerDecision(context.Background(), "owner", "同意")
+	if runner.count() != 1 {
+		t.Fatalf("approved request should execute, ran %d", runner.count())
+	}
+
+	// Second todo.create → reused decision, auto-runs (no new pending).
+	_, handled := o.handleReply(context.Background(), "someone", "c2", `[[ACTION:todo.create title="第二次"]]`, func(_ context.Context, _, _ string) error { return nil })
+	if !handled || runner.count() != 2 {
+		t.Fatalf("remembered approve should auto-run the 2nd request, handled=%v ran=%d", handled, runner.count())
+	}
+}
+
+// TestScopeEnforcement: an action outside the role's allowlist is refused up
+// front (the requester is told, nothing reaches the gate); an in-scope action
+// proceeds; an empty allowlist allows everything.
+func TestScopeEnforcement(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctscope")
+	runner := &fakeRunner{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", &fakeNotifier{})
+	o.allowedScopes = []string{"todo"} // HR-style: only todo
+
+	// doc.create is out of scope → refused, NOT gated, requester told.
+	out, handled := o.handleReply(context.Background(), "requester", "c1", `[[ACTION:doc.create name="周报"]]`, nil)
+	if handled {
+		t.Fatal("out-of-scope action must not be handled by the gate")
+	}
+	if !strings.Contains(out, "没有") || !strings.Contains(out, "doc") {
+		t.Fatalf("requester should be told it's out of scope, got %q", out)
+	}
+	if len(gate.list()) != 0 {
+		t.Fatal("out-of-scope action must not create an approval request")
+	}
+
+	// todo.create is in scope → proceeds (owner self-request auto-executes).
+	o.handleReply(context.Background(), "owner", "c2", `[[ACTION:todo.create title="排期"]]`, func(_ context.Context, _, _ string) error { return nil })
+	if len(gate.list()) != 1 {
+		t.Fatalf("in-scope action should be processed, got %d requests", len(gate.list()))
+	}
+
+	// scopeAllows: empty allowlist = allow all.
+	o.allowedScopes = nil
+	if !o.scopeAllows("anything") {
+		t.Fatal("empty allowlist must allow all products")
+	}
+}
+
+// TestAutoFlushDeferred verifies the background retry: silent while the identity
+// is still wrong (no spam), and it drains + notifies once execution works.
+func TestAutoFlushDeferred(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctauto")
+	runner := &fakeRunner{fail: true}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	// Defer one (identity not ready).
+	o.handleReply(context.Background(), "owner", "conv-o", `[[ACTION:todo.create title="自动恢复"]]`, func(_ context.Context, _, _ string) error { return nil })
+	deferNotices := notifier.count() // the deferred DM
+	if gate.list()[0].State != approvalDeferred {
+		t.Fatalf("want deferred, got %s", gate.list()[0].State)
+	}
+
+	// Auto-retry while still failing → stays deferred, NO new owner message.
+	o.autoFlushDeferred(context.Background())
+	if gate.list()[0].State != approvalDeferred {
+		t.Fatal("should still be deferred while identity is wrong")
+	}
+	if notifier.count() != deferNotices {
+		t.Fatalf("auto-retry must stay silent when nothing completes (sent %d, was %d)", notifier.count(), deferNotices)
+	}
+
+	// Identity recovers → auto-retry drains it and notifies once.
+	runner.setFail(false)
+	o.autoFlushDeferred(context.Background())
+	if gate.list()[0].State != approvalExecuted {
+		t.Fatalf("auto-retry should execute once identity is back, got %s", gate.list()[0].State)
+	}
+	notifier.mu.Lock()
+	last := notifier.sent[len(notifier.sent)-1].text
+	notifier.mu.Unlock()
+	if !strings.Contains(last, "已自动恢复") || !strings.Contains(last, "自动恢复") {
+		t.Fatalf("owner should get an auto-recovery notice, got %q", last)
+	}
+}
+
+// TestIsTransientSheetErr distinguishes retryable throttles from permanent errors.
+func TestIsTransientSheetErr(t *testing.T) {
+	for _, e := range []string{"system error: THREADPOOL_BUSY", "server busy", "request timeout", "HTTP 429 too many requests"} {
+		if !isTransientSheetErr(fmt.Errorf("%s", e)) {
+			t.Fatalf("%q should be transient", e)
+		}
+	}
+	for _, e := range []string{"invalid nodeId", "permission denied", "not found"} {
+		if isTransientSheetErr(fmt.Errorf("%s", e)) {
+			t.Fatalf("%q should NOT be transient", e)
+		}
+	}
+	if isTransientSheetErr(nil) {
+		t.Fatal("nil is not transient")
+	}
+}
+
+// TestFlushDeferred_ReportsCompletedItems verifies the owner gets a per-item
+// completion list (not just a count) when the backlog is flushed.
+func TestFlushDeferred_ReportsCompletedItems(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ctflush")
+	runner := &fakeRunner{fail: true}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	o.handleReply(context.Background(), "owner", "conv-o", `[[ACTION:todo.create title="我的待办"]]`, func(_ context.Context, _, _ string) error { return nil })
+	if gate.list()[0].State != approvalDeferred {
+		t.Fatalf("want deferred, got %s", gate.list()[0].State)
+	}
+
+	runner.setFail(false)
+	o.handleOwnerDecision(context.Background(), "owner", "重试")
+
+	notifier.mu.Lock()
+	var last string
+	if len(notifier.sent) > 0 {
+		last = notifier.sent[len(notifier.sent)-1].text
+	}
+	notifier.mu.Unlock()
+	if !strings.Contains(last, "已补做 1 个") || !strings.Contains(last, "创建待办：我的待办") {
+		t.Fatalf("flush summary should list the completed item, got %q", last)
+	}
+}
+
+// TestIsRetryWord checks whole-message retry-keyword matching.
+func TestIsRetryWord(t *testing.T) {
+	for _, w := range []string{"重试", " 恢复 ", "retry", "继续"} {
+		if !isRetryWord(w) {
+			t.Fatalf("%q should be a retry word", w)
+		}
+	}
+	for _, w := range []string{"重试一下他的方案", "", "你好"} {
+		if isRetryWord(w) {
+			t.Fatalf("%q should NOT be a retry word", w)
+		}
+	}
+}
+
+// TestHandleReply_TextMode_OwnerRejects: the owner's "拒绝" declines without
+// executing.
+func TestHandleReply_TextMode_OwnerRejects(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ct2")
+	runner := &fakeRunner{}
+	notifier := &fakeNotifier{}
+	o := newTextApprovalOrchestrator(gate, runner, "owner", notifier)
+
+	o.handleReply(context.Background(), "requester", "conv-group", `[[ACTION:todo.create title="x"]]`, nil)
+	if !o.handleOwnerDecision(context.Background(), "owner", "拒绝") {
+		t.Fatal("owner rejection must be consumed")
+	}
+	if runner.count() != 0 {
+		t.Fatalf("rejection must NOT execute, ran %d", runner.count())
+	}
+	if gate.list()[0].State != approvalRejected {
+		t.Fatalf("state = %s, want rejected", gate.list()[0].State)
+	}
+}
+
+// TestHandleOwnerDecision_NotADecision: an ordinary owner message (not a bare
+// keyword) is not consumed, so it still reaches the agent.
+func TestHandleOwnerDecision_NotADecision(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	gate := newApprovalGate("ct3")
+	o := newTextApprovalOrchestrator(gate, &fakeRunner{}, "owner", &fakeNotifier{})
+	gate.Submit(ApprovalRequest{ConvID: "conv-1", Summary: "x", State: approvalPending})
+
+	if o.handleOwnerDecision(context.Background(), "owner", "顺便帮我查下天气") {
+		t.Fatal("a non-decision owner message must pass through to the agent")
+	}
+}
+
+// TestLatestPending returns the newest pending request across conversations.
+func TestLatestPending(t *testing.T) {
+	gate := newApprovalGate("")
+	gate.Submit(ApprovalRequest{ConvID: "c1", Summary: "old", CreatedAt: time.Unix(100, 0)})
+	newer := gate.Submit(ApprovalRequest{ConvID: "c2", Summary: "new", CreatedAt: time.Unix(200, 0)})
+	if got := gate.latestPending(); got == nil || got.ID != newer.ID {
+		t.Fatalf("latestPending = %v, want newest %s", got, newer.ID)
+	}
+	gate.Decide(newer.ID, true, "owner")
+	if got := gate.latestPending(); got == nil || got.Summary != "old" {
+		t.Fatalf("after deciding newest, latestPending should fall back to the older pending, got %v", got)
+	}
+}
+
+// list is a tiny test helper to enumerate the gate's requests.
+func (g *approvalGate) list() []*ApprovalRequest {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	out := make([]*ApprovalRequest, 0, len(g.reqs))
+	for _, r := range g.reqs {
+		cp := *r
+		out = append(out, &cp)
+	}
+	return out
+}

internal/helpers/connect_approval_e2e_test.go

@@ -0,0 +1,129 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/card"
+)
+
+// TestApprovalGate_EndToEndApprove exercises the whole vertical slice with no
+// network: an agent reply carrying a todo.create marker → Submit → approval card
+// → owner taps [Approve] via a card callback → the planned todo.create runs on
+// the (fake) runner → the group is told it was executed.
+//
+// It mirrors exactly what runStreamConnector wires together, but with the card
+// sender and runner faked, so the orchestration logic is verified end to end.
+func TestApprovalGate_EndToEndApprove(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	gate := newApprovalGate("e2e-client")
+	sender := &fakeCardSender{}
+	runner := &fakeRunner{}
+	o := newApprovalOrchestrator(gate, sender, runner, "owner-007")
+	o.awaitWindow = 2 * time.Second
+
+	var replies []string
+	var rmu sync.Mutex
+	groupReply := func(_ context.Context, _, text string) error {
+		rmu.Lock()
+		replies = append(replies, text)
+		rmu.Unlock()
+		return nil
+	}
+
+	// Simulate the owner tapping [Approve] once the card has been delivered, via
+	// the exact card-callback path the Stream router would invoke.
+	go func() {
+		deadline := time.Now().Add(2 * time.Second)
+		for time.Now().Before(deadline) {
+			sender.mu.Lock()
+			track := sender.lastTrack
+			sender.mu.Unlock()
+			if track != "" {
+				_, _ = o.handleCardCallback(context.Background(), &card.CardRequest{
+					OutTrackId: track,
+					UserId:     "owner-007",
+					CardActionData: card.PrivateCardActionData{
+						CardPrivateData: card.CardPrivateData{
+							ActionIdList: []string{approvalActionApprove},
+							Params: map[string]any{
+								approvalParamDecision: approvalDecisionApprove,
+							},
+						},
+					},
+				})
+				return
+			}
+			time.Sleep(5 * time.Millisecond)
+		}
+	}()
+
+	// This is the agent reply for: 群里有人 @机器人 "帮我建个待办：明天下班前交方案".
+	agentReply := `收到，我来帮你建这个待办。[[ACTION:todo.create title="明天下班前交方案" due="2026-06-14T18:00:00+08:00"]]`
+
+	out, handled := o.handleReply(context.Background(), "requester-zhang", "group-conv-9", agentReply, groupReply)
+
+	if !handled {
+		t.Fatal("action reply must be handled by the gate")
+	}
+	if out != "" {
+		t.Fatalf("handled reply returns empty connector reply, got %q", out)
+	}
+
+	// The planned command ran exactly once, and it was todo.create.
+	if runner.count() != 1 {
+		t.Fatalf("expected exactly 1 execution, got %d", runner.count())
+	}
+	runner.mu.Lock()
+	inv := runner.runs[0]
+	runner.mu.Unlock()
+	if inv.CanonicalProduct != "todo" || inv.Tool != "create_personal_todo" {
+		t.Fatalf("executed wrong command: %s.%s", inv.CanonicalProduct, inv.Tool)
+	}
+	vo, _ := inv.Params["PersonalTodoCreateVO"].(map[string]any)
+	if vo == nil || vo["subject"] != "明天下班前交方案" {
+		t.Fatalf("todo subject wrong: %+v", vo)
+	}
+
+	// State machine reached Executed.
+	final := gate.list()[0]
+	if final.State != approvalExecuted {
+		t.Fatalf("final state = %s, want executed", final.State)
+	}
+
+	// The owner saw [Approve]/[Reject] (the card was delivered), and the group
+	// got the executed-confirmation reply.
+	if len(sender.sent) != 1 {
+		t.Fatalf("expected 1 card delivered, got %d", len(sender.sent))
+	}
+	rmu.Lock()
+	joined := strings.Join(replies, " | ")
+	rmu.Unlock()
+	if !strings.Contains(joined, "已同意") || !strings.Contains(joined, "已执行") {
+		t.Fatalf("group not told of execution: %q", joined)
+	}
+
+	t.Logf("E2E approve chain OK:\n"+
+		"  card delivered to owner: %v\n"+
+		"  approval state: %s\n"+
+		"  command executed: %s.%s (subject=%q)\n"+
+		"  group replies: %s",
+		sender.sent[0].Summary, final.State, inv.CanonicalProduct, inv.Tool, vo["subject"], joined)
+}

internal/helpers/connect_approval_test.go

@@ -0,0 +1,206 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestApprovalGate_SubmitPending verifies Submit lands a request in Pending with
+// a generated id and timestamp.
+func TestApprovalGate_SubmitPending(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	g := newApprovalGate("client-A")
+	req := g.Submit(ApprovalRequest{Requester: "u1", ConvID: "cid", Summary: "do thing"})
+	if req.ID == "" {
+		t.Fatal("Submit should assign an ID")
+	}
+	if req.State != approvalPending {
+		t.Fatalf("state = %s, want pending", req.State)
+	}
+	if req.CreatedAt.IsZero() {
+		t.Fatal("CreatedAt should be set")
+	}
+	if got := g.Get(req.ID); got == nil || got.State != approvalPending {
+		t.Fatalf("Get returned %+v, want pending", got)
+	}
+}
+
+// TestApprovalGate_DecideApproveReject covers both decision branches and the
+// idempotency of a second decision.
+func TestApprovalGate_DecideApproveReject(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	g := newApprovalGate("client-B")
+
+	app := g.Submit(ApprovalRequest{Summary: "approve me"})
+	decided, deciding := g.Decide(app.ID, true, "owner")
+	if !deciding || decided.State != approvalApproved || decided.DecidedBy != "owner" {
+		t.Fatalf("approve decision = %+v deciding=%v", decided, deciding)
+	}
+	// Second decision is a no-op.
+	if _, again := g.Decide(app.ID, false, "owner"); again {
+		t.Fatal("second Decide must not be the deciding call")
+	}
+	if g.Get(app.ID).State != approvalApproved {
+		t.Fatal("state must stay approved after a redundant reject")
+	}
+
+	rej := g.Submit(ApprovalRequest{Summary: "reject me"})
+	d2, _ := g.Decide(rej.ID, false, "owner")
+	if d2.State != approvalRejected {
+		t.Fatalf("reject decision = %s, want rejected", d2.State)
+	}
+
+	// Unknown id.
+	if _, ok := g.Decide("nope", true, "owner"); ok {
+		t.Fatal("deciding unknown id should report false")
+	}
+}
+
+// TestApprovalGate_AwaitWakesOnDecide verifies Await blocks until a decision and
+// returns the decided snapshot.
+func TestApprovalGate_AwaitWakesOnDecide(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	g := newApprovalGate("client-C")
+	app := g.Submit(ApprovalRequest{Summary: "wait for me"})
+
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		g.Decide(app.ID, true, "owner")
+	}()
+
+	decided, got := g.Await(context.Background(), app.ID, time.Second)
+	if !got || decided == nil || !decided.approved() {
+		t.Fatalf("Await = %+v got=%v, want approved", decided, got)
+	}
+}
+
+// TestApprovalGate_AwaitTimeout verifies a timeout leaves the request Pending and
+// reports no decision.
+func TestApprovalGate_AwaitTimeout(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	g := newApprovalGate("client-D")
+	app := g.Submit(ApprovalRequest{Summary: "nobody decides"})
+	decided, got := g.Await(context.Background(), app.ID, 10*time.Millisecond)
+	if got {
+		t.Fatal("Await should report no decision on timeout")
+	}
+	if decided.State != approvalPending {
+		t.Fatalf("state = %s, want pending after timeout", decided.State)
+	}
+}
+
+// TestApprovalGate_PersistAndRecover verifies a Pending request written by one
+// gate is recovered by a fresh gate over the same config dir (restart survival).
+func TestApprovalGate_PersistAndRecover(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+
+	g1 := newApprovalGate("client-E")
+	app := g1.Submit(ApprovalRequest{Requester: "u9", Summary: "survive restart",
+		Action: plannedAction{Product: "todo", Tool: "create_personal_todo"}})
+	g1.setOutTrackID(app.ID, "card-123")
+
+	// Fresh gate, same dir → must recover the request and its outTrackId.
+	g2 := newApprovalGate("client-E")
+	got := g2.Get(app.ID)
+	if got == nil {
+		t.Fatal("request not recovered from disk")
+	}
+	if got.State != approvalPending || got.Summary != "survive restart" {
+		t.Fatalf("recovered = %+v", got)
+	}
+	if got.OutTrackID != "card-123" {
+		t.Fatalf("recovered outTrackId = %q, want card-123", got.OutTrackID)
+	}
+	if byTrack := g2.findByOutTrackID("card-123"); byTrack == nil || byTrack.ID != app.ID {
+		t.Fatal("findByOutTrackID failed after recovery")
+	}
+}
+
+// TestApprovalGate_NoPersistWhenEmptyClient verifies an empty clientId keeps the
+// gate in memory only (no disk writes, mirroring the session store).
+func TestApprovalGate_NoPersistWhenEmptyClient(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	g := newApprovalGate("")
+	if g.approvalDir() != "" {
+		t.Fatal("empty clientId must disable persistence")
+	}
+	app := g.Submit(ApprovalRequest{Summary: "memory only"})
+	if g.Get(app.ID) == nil {
+		t.Fatal("in-memory request should still be retrievable")
+	}
+}
+
+// TestParseActionMarker covers the simplified execution-class detection: a
+// marker is extracted with its args and stripped from the human-facing reply,
+// while plain Q&A is left untouched.
+func TestParseActionMarker(t *testing.T) {
+	reply := `好的，我来帮你建。[[ACTION:todo.create title="交方案" due="2026-06-14T18:00:00+08:00"]]`
+	act, cleaned, found := parseActionMarker(reply)
+	if !found {
+		t.Fatal("marker should be detected")
+	}
+	if act.Verb != "todo.create" {
+		t.Fatalf("verb = %s", act.Verb)
+	}
+	if act.Args["title"] != "交方案" || act.Args["due"] != "2026-06-14T18:00:00+08:00" {
+		t.Fatalf("args = %+v", act.Args)
+	}
+	if cleaned != "好的，我来帮你建。" {
+		t.Fatalf("cleaned = %q", cleaned)
+	}
+
+	if _, _, f := parseActionMarker("这是一个普通问题的回答，没有动作。"); f {
+		t.Fatal("plain reply must not match")
+	}
+}
+
+// TestToPlannedAction verifies the marker → command mapping, including the
+// reject of a malformed (titleless) action.
+func TestToPlannedAction(t *testing.T) {
+	pa, summary, ok := toPlannedAction(detectedAction{
+		Verb: "todo.create",
+		Args: map[string]string{"title": "交方案", "due": "2026-06-14T18:00:00+08:00"},
+	}, "owner-1")
+	if !ok {
+		t.Fatal("valid todo.create should map")
+	}
+	if pa.Product != "todo" || pa.Tool != "create_personal_todo" {
+		t.Fatalf("planned = %+v", pa)
+	}
+	vo, _ := pa.Params["PersonalTodoCreateVO"].(map[string]any)
+	if vo == nil || vo["subject"] != "交方案" {
+		t.Fatalf("vo = %+v", vo)
+	}
+	if _, hasDue := vo["dueTime"]; !hasDue {
+		t.Fatal("due should be parsed into dueTime")
+	}
+	execs, _ := vo["executorIds"].([]string)
+	if len(execs) != 1 || execs[0] != "owner-1" {
+		t.Fatalf("executors = %+v, want [owner-1]", execs)
+	}
+	if summary == "" {
+		t.Fatal("summary should be non-empty")
+	}
+
+	if _, _, ok := toPlannedAction(detectedAction{Verb: "todo.create", Args: map[string]string{}}, "o"); ok {
+		t.Fatal("titleless action must be rejected")
+	}
+	if _, _, ok := toPlannedAction(detectedAction{Verb: "unknown.verb"}, "o"); ok {
+		t.Fatal("unknown verb must be rejected")
+	}
+}

internal/helpers/connect_card.go

@@ -0,0 +1,578 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/chatbot"
+)
+
+// AI-card reply support for the stream-bridge channels: instead of a plain
+// one-shot text message, the bot answers with a DingTalk AI card that shows a
+// "Thinking" state while the local agent runs and flips to done with the
+// final content — the same UX the hermes official pipeline provides.
+//
+// The experience combines the two verified official implementations:
+//   - the "🤔Thinking/🥳Done" chip on the user's message is a text emotion
+//     (message reaction), ported from the hermes gateway adapter;
+//   - the card itself uses the openclaw connector's public template and
+//     payload contract (msgContent + flowStatus state machine), because card
+//     templates are app-scoped: hermes' own template (c629162a-...) renders
+//     "内容加载失败" for any other app — confirmed by A/B on the same robot.
+//
+// Call order: create instance → deliver → flowStatus INPUTING → streaming
+// frames (throttled, isFull) → finalize frame → flowStatus FINISHED.
+const (
+	// defaultAICardTemplateID is the public AI-card streaming template the
+	// openclaw connector ships with (messaging/card.ts) — a best-effort
+	// default. Card templates are APP-SCOPED: the reliable production setup is
+	// registering an AI-card template under YOUR app in the DingTalk developer
+	// console (the hermes docs prescribe exactly this) and passing its ID via
+	// --card-template / DWS_CARD_TEMPLATE. Using another app's template (e.g.
+	// hermes' c629162a-...) renders "内容加载失败" — confirmed by live A/B on
+	// the same robot.
+	defaultAICardTemplateID = "02fcf2f4-5e02-4a85-b672-46d1f715543e.schema"
+
+	// aiCardMaxContent mirrors hermes' MAX_MESSAGE_LENGTH truncation.
+	aiCardMaxContent = 20000
+
+	// flowStatus states of the AI-card template (openclaw AICardStatus).
+	aiCardFlowInputing = "2"
+	aiCardFlowFinished = "3"
+	aiCardFlowFailed   = "5"
+)
+
+// dingtalkCardAPIBase is a var so tests can point it at a httptest server.
+var dingtalkCardAPIBase = "https://api.dingtalk.com"
+
+// aiCardClient creates and finalizes AI cards using the robot's own
+// credentials (clientId/clientSecret → app access token, cached ~2h).
+type aiCardClient struct {
+	clientID     string
+	clientSecret string
+	templateID   string
+	httpClient   *http.Client
+
+	mu       sync.Mutex
+	token    string
+	tokenExp time.Time
+}
+
+// newAICardClient builds the reply-UX client. With an empty templateID the
+// client does emotions only (Thinking/Done chips) and no cards — mirroring
+// hermes, where cards are an opt-in enabled by configuring a template ID and
+// replies stay plain text otherwise. This avoids the silent-failure trap:
+// card APIs all succeed even when the client cannot render the template.
+func newAICardClient(clientID, clientSecret, templateID string) *aiCardClient {
+	templateID = strings.TrimSpace(templateID)
+	return &aiCardClient{
+		clientID:     clientID,
+		clientSecret: clientSecret,
+		templateID:   templateID,
+		httpClient:   &http.Client{Timeout: 15 * time.Second},
+	}
+}
+
+// hasTemplate reports whether card replies are enabled (a template is
+// configured); without one the client is used for emotions only.
+func (c *aiCardClient) hasTemplate() bool { return c.templateID != "" }
+
+// aiCardInstance is one delivered card, identified by its outTrackId.
+type aiCardInstance struct {
+	outTrackID string
+	// inputing marks that the INPUTING flow state was already set (once per
+	// card, before the first streaming frame).
+	inputing bool
+	// lastFrame timestamps the last non-final streaming frame for the
+	// per-card throttle (the streaming endpoint 403s on <~500ms updates;
+	// hermes uses 800ms).
+	lastFrame time.Time
+}
+
+// accessToken returns a cached app access token, refreshing 5 minutes early.
+func (c *aiCardClient) accessToken(ctx context.Context) (string, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.token != "" && time.Now().Before(c.tokenExp.Add(-5*time.Minute)) {
+		return c.token, nil
+	}
+	body, err := json.Marshal(map[string]string{
+		"appKey":    c.clientID,
+		"appSecret": c.clientSecret,
+	})
+	if err != nil {
+		return "", err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		dingtalkCardAPIBase+"/v1.0/oauth2/accessToken", bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode >= 400 {
+		return "", fmt.Errorf("accessToken HTTP %d: %s", resp.StatusCode, truncateRunes(string(raw), 200))
+	}
+	var parsed struct {
+		AccessToken string `json:"accessToken"`
+		ExpireIn    int64  `json:"expireIn"`
+	}
+	if err := json.Unmarshal(raw, &parsed); err != nil || parsed.AccessToken == "" {
+		return "", fmt.Errorf("accessToken parse failed: %s", truncateRunes(string(raw), 200))
+	}
+	c.token = parsed.AccessToken
+	expire := parsed.ExpireIn
+	if expire <= 0 {
+		expire = 7200
+	}
+	c.tokenExp = time.Now().Add(time.Duration(expire) * time.Second)
+	return c.token, nil
+}
+
+// call performs one authenticated card-API request and fails on non-2xx.
+func (c *aiCardClient) call(ctx context.Context, method, path string, payload map[string]any) error {
+	_, err := c.callRaw(ctx, method, path, payload)
+	return err
+}
+
+func (c *aiCardClient) callRaw(ctx context.Context, method, path string, payload map[string]any) (string, error) {
+	token, err := c.accessToken(ctx)
+	if err != nil {
+		return "", err
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+	req, err := http.NewRequestWithContext(ctx, method, dingtalkCardAPIBase+path, bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("x-acs-dingtalk-access-token", token)
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode >= 400 {
+		return "", fmt.Errorf("%s %s HTTP %d: %s", method, path, resp.StatusCode, truncateRunes(string(raw), 300))
+	}
+	// Surface every response body in the connector log: the card APIs report
+	// business-level failures inside a 200, and a silently dropped frame is
+	// otherwise indistinguishable from the client-side "内容加载失败".
+	fmt.Fprintf(os.Stderr, "[connect][card][api] %s %s -> %d %s\n", method, path, resp.StatusCode, truncateRunes(string(raw), 200))
+	return string(raw), nil
+}
+
+// sendOTOText sends a plain-text 1:1 (robot → person) message to each userId,
+// using the robot batch one-to-one send API. It is how the connector reaches a
+// specific person (e.g. the digital-twin owner) proactively, outside the
+// ephemeral inbound sessionWebhook — the webhook can only reply into the
+// conversation a message arrived on, and may be stale by the time an owner
+// decides. Auth reuses the app access token (the bot's own clientId/secret), so
+// the message is sent as the bot in its own org.
+func (c *aiCardClient) sendOTOText(ctx context.Context, userIDs []string, text string) error {
+	if len(userIDs) == 0 {
+		return nil
+	}
+	param, err := json.Marshal(map[string]string{"content": text})
+	if err != nil {
+		return err
+	}
+	return c.call(ctx, http.MethodPost, "/v1.0/robot/oToMessages/batchSend", map[string]any{
+		"robotCode": c.clientID,
+		"userIds":   userIDs,
+		"msgKey":    "sampleText",
+		"msgParam":  string(param),
+	})
+}
+
+// createAndDeliver creates an AI-card instance and delivers it into the
+// conversation the message came from. With empty content the template
+// renders the "Thinking" state while the agent runs. Group messages deliver
+// to IM_GROUP (with robotCode), 1:1 to IM_ROBOT (spaceType only) — exactly
+// the hermes deliver shapes.
+func (c *aiCardClient) createAndDeliver(ctx context.Context, data *chatbot.BotCallbackDataModel) (*aiCardInstance, error) {
+	outTrackID := "dws_" + uuid.NewString()
+	create := map[string]any{
+		"cardTemplateId": c.templateID,
+		"outTrackId":     outTrackID,
+		"cardData": map[string]any{
+			"cardParamMap": map[string]any{"config": `{"autoLayout":true}`},
+		},
+		"callbackType":          "STREAM",
+		"imGroupOpenSpaceModel": map[string]any{"supportForward": true},
+		"imRobotOpenSpaceModel": map[string]any{"supportForward": true},
+	}
+	if err := c.call(ctx, http.MethodPost, "/v1.0/card/instances", create); err != nil {
+		return nil, err
+	}
+
+	deliver := map[string]any{
+		"outTrackId": outTrackID,
+		"userIdType": 1,
+	}
+	if data.ConversationType == "2" { // group chat
+		deliver["openSpaceId"] = "dtv1.card//IM_GROUP." + data.ConversationId
+		deliver["imGroupOpenDeliverModel"] = map[string]any{"robotCode": c.clientID}
+	} else { // 1:1 chat with the robot
+		if data.SenderStaffId == "" {
+			return nil, fmt.Errorf("missing senderStaffId for 1:1 card delivery")
+		}
+		deliver["openSpaceId"] = "dtv1.card//IM_ROBOT." + data.SenderStaffId
+		deliver["imRobotOpenDeliverModel"] = map[string]any{
+			"spaceType": "IM_ROBOT",
+			"robotCode": c.clientID,
+			"extension": map[string]any{"dynamicSummary": "true"},
+		}
+	}
+	if err := c.callChecked(ctx, http.MethodPost, "/v1.0/card/instances/deliver", deliver); err != nil {
+		return nil, err
+	}
+	return &aiCardInstance{outTrackID: outTrackID}, nil
+}
+
+// callChecked is call() plus a business-level result check: the deliver API
+// reports per-target failures INSIDE a HTTP 200 (e.g. {"result":[{"success":
+// false,"errorMsg":"spaceId is illegal"}],"success":true}) — observed live.
+func (c *aiCardClient) callChecked(ctx context.Context, method, path string, payload map[string]any) error {
+	raw, err := c.callRaw(ctx, method, path, payload)
+	if err != nil {
+		return err
+	}
+	if strings.Contains(raw, `"success":false`) {
+		return fmt.Errorf("%s %s business failure: %s", method, path, truncateRunes(raw, 300))
+	}
+	return nil
+}
+
+// streamingUpdate sends one full content frame to the card.
+func (c *aiCardClient) streamingUpdate(ctx context.Context, card *aiCardInstance, content string, finalize, isError bool) error {
+	if r := []rune(content); len(r) > aiCardMaxContent {
+		content = string(r[:aiCardMaxContent])
+	}
+	return c.call(ctx, http.MethodPut, "/v1.0/card/streaming", map[string]any{
+		"outTrackId": card.outTrackID,
+		"guid":       uuid.NewString(),
+		"key":        "msgContent",
+		"content":    content,
+		"isFull":     true,
+		"isFinalize": finalize,
+		"isError":    isError,
+	})
+}
+
+// aiCardFrameGap spaces the deliver → content → finalize frames. Delivering
+// and finalizing back-to-back races the client's card fetch and intermittently
+// renders "内容加载失败" (the very failure that killed the #407 card attempt);
+// a short gap lets the client subscribe before the closing frame lands.
+var aiCardFrameGap = 500 * time.Millisecond
+
+// cardContentParams is the cardParamMap contract of the openclaw template.
+func cardContentParams(flowStatus, content string) map[string]any {
+	return map[string]any{
+		"flowStatus":        flowStatus,
+		"msgContent":        content,
+		"staticMsgContent":  "",
+		"sys_full_json_obj": `{"order":["msgContent"]}`,
+		"config":            `{"autoLayout":true}`,
+	}
+}
+
+// setFlowStatus updates the card instance's flow state (openclaw contract:
+// INPUTING before streaming, FINISHED after the finalize frame).
+func (c *aiCardClient) setFlowStatus(ctx context.Context, card *aiCardInstance, flowStatus, content string, byKey bool) error {
+	payload := map[string]any{
+		"outTrackId": card.outTrackID,
+		"cardData":   map[string]any{"cardParamMap": cardContentParams(flowStatus, content)},
+	}
+	if byKey {
+		payload["cardUpdateOptions"] = map[string]any{"updateCardDataByKey": true}
+	}
+	return c.call(ctx, http.MethodPut, "/v1.0/card/instances", payload)
+}
+
+// aiCardFrameThrottle is the minimum spacing between non-final streaming
+// frames per card (hermes uses 800ms; the endpoint 403s on rapid updates).
+var aiCardFrameThrottle = 800 * time.Millisecond
+
+// streamFrame pushes one full-content frame into the card, switching the card
+// to INPUTING before the first frame. Non-final frames are throttled per
+// card — a skipped frame is fine because every frame carries the full text so
+// far (isFull). The final frame always goes out.
+func (c *aiCardClient) streamFrame(ctx context.Context, card *aiCardInstance, content string, final bool) error {
+	normalized := normalizeForCard(content)
+	if !card.inputing {
+		if err := c.setFlowStatus(ctx, card, aiCardFlowInputing, normalized, false); err != nil {
+			return err
+		}
+		card.inputing = true
+		card.lastFrame = time.Now()
+	}
+	if !final {
+		if time.Since(card.lastFrame) < aiCardFrameThrottle {
+			return nil // skip; a later frame re-sends the full text
+		}
+	}
+	if err := c.streamingUpdate(ctx, card, normalized, final, false); err != nil {
+		return err
+	}
+	card.lastFrame = time.Now()
+	return nil
+}
+
+// finish closes the card: the finalized streaming frame plus the FINISHED
+// flow state. A failure leaves the card spinning, so callers must treat an
+// error as "fall back to a plain webhook reply" (after markFailed).
+func (c *aiCardClient) finish(ctx context.Context, card *aiCardInstance, content string) error {
+	normalized := normalizeForCard(content)
+	if err := c.streamFrame(ctx, card, content, true); err != nil {
+		return err
+	}
+	if err := sleepCtx(ctx, aiCardFrameGap); err != nil {
+		return err
+	}
+	return c.setFlowStatus(ctx, card, aiCardFlowFinished, normalized, true)
+}
+
+// finalize is the one-shot path for channels without incremental output:
+// INPUTING → final frame → FINISHED in one call.
+func (c *aiCardClient) finalize(ctx context.Context, card *aiCardInstance, content string) error {
+	if err := sleepCtx(ctx, aiCardFrameGap); err != nil {
+		return err
+	}
+	return c.finish(ctx, card, content)
+}
+
+// repair re-pushes the finalize frame once, a few seconds after the reply.
+// hermes streams many frames so a client that misses one recovers on the
+// next; our burst of two frames has no such retry, and a missed fetch shows
+// "内容加载失败" until a new frame arrives. Best-effort by design.
+func (c *aiCardClient) repair(ctx context.Context, card *aiCardInstance, content string) {
+	if err := sleepCtx(ctx, aiCardRepairDelay); err != nil {
+		return
+	}
+	_ = c.setFlowStatus(ctx, card, aiCardFlowFinished, normalizeForCard(content), true)
+}
+
+// aiCardRepairDelay is how long after finalize the repair frame goes out.
+var aiCardRepairDelay = 3 * time.Second
+
+func sleepCtx(ctx context.Context, d time.Duration) error {
+	if d <= 0 {
+		return nil
+	}
+	t := time.NewTimer(d)
+	defer t.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-t.C:
+		return nil
+	}
+}
+
+// markFailed best-effort closes a stuck card in the error state so the
+// Thinking chip does not spin forever when finalize failed and the reply
+// went out as a plain message instead. Errors are ignored by design.
+func (c *aiCardClient) markFailed(ctx context.Context, card *aiCardInstance) {
+	_ = c.setFlowStatus(ctx, card, aiCardFlowFailed, "", true)
+}
+
+// ---- Message reactions (the "🤔Thinking" chip) ----
+//
+// The status chip attached to the user's message is NOT a card: it is a text
+// emotion (message reaction) — hermes fires "🤔Thinking" on receive and swaps
+// it for "🥳Done" when the reply lands (gateway/platforms/dingtalk.py,
+// _send_emotion / _fire_done_reaction). During thinking there is no card at
+// all; the card only appears with the final content.
+
+const (
+	emotionThinking = "🤔Thinking"
+	emotionDone     = "🥳Done"
+)
+
+// sendEmotion adds (or recalls) a text reaction on the user's message.
+// Failures are logged by callers at most — the reaction is decoration, never
+// worth failing the reply over. Payload contract per the robot_1_0 SDK:
+// POST /v1.0/robot/emotion/reply | /v1.0/robot/emotion/recall.
+func (c *aiCardClient) sendEmotion(ctx context.Context, conversationID, msgID, name string, recall bool) error {
+	if conversationID == "" || msgID == "" {
+		return fmt.Errorf("emotion needs openConversationId and openMsgId")
+	}
+	path := "/v1.0/robot/emotion/reply"
+	if recall {
+		path = "/v1.0/robot/emotion/recall"
+	}
+	return c.call(ctx, http.MethodPost, path, map[string]any{
+		"robotCode":          c.clientID,
+		"openConversationId": conversationID,
+		"openMsgId":          msgID,
+		"emotionType":        2,
+		"emotionName":        name,
+		"textEmotion": map[string]any{
+			"emotionId":    "2659900",
+			"emotionName":  name,
+			"text":         name,
+			"backgroundId": "im_bg_1",
+		},
+	})
+}
+
+// markThinking fires the "🤔Thinking" chip on the user's message.
+func (c *aiCardClient) markThinking(ctx context.Context, conversationID, msgID string) error {
+	return c.sendEmotion(ctx, conversationID, msgID, emotionThinking, false)
+}
+
+// swapThinkingToDone replaces the chip with "🥳Done" after the reply landed.
+// Best-effort by design (mirrors hermes' fire-and-forget swap).
+func (c *aiCardClient) swapThinkingToDone(ctx context.Context, conversationID, msgID string) {
+	_ = c.sendEmotion(ctx, conversationID, msgID, emotionThinking, true)
+	_ = c.sendEmotion(ctx, conversationID, msgID, emotionDone, false)
+}
+
+// ---- Markdown normalization for the AI-card renderer ----
+//
+// Ported from openclaw's normalizeForCard (messaging/card.ts): the 02fcf2f4
+// template renders <br> as visual line breaks in plain text, needs real \n
+// inside code fences and before Markdown block syntax, and a blank line
+// before tables.
+
+var (
+	cardTableDividerRe = regexp.MustCompile(`^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$`)
+	cardTableRowRe     = regexp.MustCompile(`^\s*\|?.*\|.*\|?\s*$`)
+	cardBlockStartRe   = regexp.MustCompile(`^(\s{0,3}(?:[-*+]|\d+[.)])[ ])|(\s{0,3}\|)|(\s{0,3}#{1,6}\s)|(\s{0,3}(?:[-*_])\s*(?:[-*_])\s*(?:[-*_]))`)
+	cardFenceRe        = regexp.MustCompile("^\\s{0,3}```")
+	cardQuoteRe        = regexp.MustCompile(`^\s{0,3}>\s?`)
+)
+
+func normalizeCardLineEndings(text string) string {
+	text = strings.ReplaceAll(text, "\r\n", "\n")
+	return strings.ReplaceAll(text, "\r", "\n")
+}
+
+// ensureCardTableBlankLines inserts a blank line before a table header that
+// directly follows non-table text, which the card renderer requires.
+func ensureCardTableBlankLines(text string) string {
+	lines := strings.Split(normalizeCardLineEndings(text), "\n")
+	out := make([]string, 0, len(lines))
+	isDivider := func(line string) bool {
+		return strings.Contains(line, "|") && cardTableDividerRe.MatchString(line)
+	}
+	for i, line := range lines {
+		next := ""
+		if i+1 < len(lines) {
+			next = lines[i+1]
+		}
+		if cardTableRowRe.MatchString(line) && isDivider(next) && i > 0 &&
+			strings.TrimSpace(lines[i-1]) != "" && !cardTableRowRe.MatchString(lines[i-1]) {
+			out = append(out, "")
+		}
+		out = append(out, line)
+	}
+	return strings.Join(out, "\n")
+}
+
+// fixCardNewlines converts single \n to <br> for plain text while keeping
+// real newlines inside code fences and before Markdown block syntax, and
+// merges consecutive quote lines with <br> (lazy continuation).
+func fixCardNewlines(text string) string {
+	normalized := normalizeCardLineEndings(text)
+
+	var merged []string
+	var pendingQuote []string
+	inCode := false
+	flushQuote := func() {
+		if len(pendingQuote) > 0 {
+			merged = append(merged, strings.Join(pendingQuote, "<br>"))
+			pendingQuote = nil
+		}
+	}
+	for _, line := range strings.Split(normalized, "\n") {
+		isFence := cardFenceRe.MatchString(line)
+		if inCode {
+			flushQuote()
+			merged = append(merged, line)
+			if isFence {
+				inCode = false
+			}
+			continue
+		}
+		if isFence {
+			flushQuote()
+			merged = append(merged, line)
+			inCode = true
+			continue
+		}
+		if cardQuoteRe.MatchString(line) {
+			if len(pendingQuote) == 0 {
+				pendingQuote = append(pendingQuote, line)
+			} else {
+				pendingQuote = append(pendingQuote, cardQuoteRe.ReplaceAllString(line, ""))
+			}
+		} else {
+			flushQuote()
+			merged = append(merged, line)
+		}
+	}
+	flushQuote()
+
+	inCode = false
+	var b strings.Builder
+	for i, line := range merged {
+		nextInCode := inCode
+		if cardFenceRe.MatchString(line) {
+			nextInCode = !inCode
+		}
+		if i < len(merged)-1 {
+			next := merged[i+1]
+			keepNewline := nextInCode || line == "" || next == "" ||
+				cardFenceRe.MatchString(next) || cardBlockStartRe.MatchString(next)
+			b.WriteString(line)
+			if keepNewline {
+				b.WriteString("\n")
+			} else {
+				b.WriteString("<br>")
+			}
+		} else {
+			b.WriteString(line)
+		}
+		inCode = nextInCode
+	}
+	return b.String()
+}
+
+// normalizeForCard prepares agent output for the AI-card renderer.
+func normalizeForCard(content string) string {
+	return fixCardNewlines(ensureCardTableBlankLines(content))
+}

internal/helpers/connect_card_test.go

@@ -0,0 +1,298 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/chatbot"
+)
+
+// cardAPIRecorder fakes the DingTalk card endpoints and records every call.
+type cardAPIRecorder struct {
+	mu     sync.Mutex
+	calls  []string         // "METHOD path"
+	bodies []map[string]any // parsed request bodies, same order
+	tokens int              // accessToken request count
+	fail   map[string]int   // "METHOD path" -> HTTP status to return
+}
+
+func newCardAPIServer(t *testing.T) (*cardAPIRecorder, *httptest.Server) {
+	t.Helper()
+	rec := &cardAPIRecorder{fail: map[string]int{}}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, _ := io.ReadAll(r.Body)
+		var body map[string]any
+		_ = json.Unmarshal(raw, &body)
+		key := r.Method + " " + r.URL.Path
+
+		rec.mu.Lock()
+		if r.URL.Path == "/v1.0/oauth2/accessToken" {
+			rec.tokens++
+		} else {
+			rec.calls = append(rec.calls, key)
+			rec.bodies = append(rec.bodies, body)
+		}
+		status := rec.fail[key]
+		rec.mu.Unlock()
+
+		if status != 0 {
+			w.WriteHeader(status)
+			_, _ = w.Write([]byte(`{"code":"boom"}`))
+			return
+		}
+		if r.URL.Path == "/v1.0/oauth2/accessToken" {
+			_, _ = w.Write([]byte(`{"accessToken":"tok-1","expireIn":7200}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"success":true}`))
+	}))
+	t.Cleanup(srv.Close)
+	return rec, srv
+}
+
+func withCardAPIBase(t *testing.T, base string) {
+	t.Helper()
+	old := dingtalkCardAPIBase
+	dingtalkCardAPIBase = base
+	oldGap, oldRepair := aiCardFrameGap, aiCardRepairDelay
+	aiCardFrameGap, aiCardRepairDelay = 0, 0
+	t.Cleanup(func() {
+		dingtalkCardAPIBase = old
+		aiCardFrameGap, aiCardRepairDelay = oldGap, oldRepair
+	})
+}
+
+func groupCallback() *chatbot.BotCallbackDataModel {
+	return &chatbot.BotCallbackDataModel{
+		ConversationId:   "cid-group-1",
+		ConversationType: "2",
+		SenderStaffId:    "staff-1",
+	}
+}
+
+// TestAICardCreateFinalizeSequence verifies the hermes-contract happy path:
+// create (empty content = Thinking) → deliver → ONE finalized streaming frame.
+func TestAICardCreateFinalizeSequence(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", defaultAICardTemplateID)
+	card, err := c.createAndDeliver(context.Background(), groupCallback())
+	if err != nil {
+		t.Fatalf("createAndDeliver: %v", err)
+	}
+	if !strings.HasPrefix(card.outTrackID, "dws_") {
+		t.Fatalf("outTrackID = %q, want dws_ prefix", card.outTrackID)
+	}
+	if err := c.finalize(context.Background(), card, "你好，**答案是 42**"); err != nil {
+		t.Fatalf("finalize: %v", err)
+	}
+
+	wantSeq := []string{
+		"POST /v1.0/card/instances",
+		"POST /v1.0/card/instances/deliver",
+		"PUT /v1.0/card/instances", // INPUTING + content
+		"PUT /v1.0/card/streaming", // finalize frame
+		"PUT /v1.0/card/instances", // FINISHED
+	}
+	if strings.Join(rec.calls, ",") != strings.Join(wantSeq, ",") {
+		t.Fatalf("call sequence = %v, want %v", rec.calls, wantSeq)
+	}
+	if rec.tokens != 1 {
+		t.Fatalf("token requests = %d, want 1 (cached)", rec.tokens)
+	}
+
+	// create: hermes template + empty "content" param (renders Thinking)
+	create := rec.bodies[0]
+	if create["cardTemplateId"] != defaultAICardTemplateID || create["callbackType"] != "STREAM" {
+		t.Fatalf("create payload wrong: %v", create)
+	}
+	pm := create["cardData"].(map[string]any)["cardParamMap"].(map[string]any)
+	if _, ok := pm["config"]; !ok {
+		t.Fatalf("create cardParamMap = %v, want config key (openclaw contract)", pm)
+	}
+
+	// deliver: group space + robotCode
+	deliver := rec.bodies[1]
+	if deliver["openSpaceId"] != "dtv1.card//IM_GROUP.cid-group-1" {
+		t.Fatalf("deliver openSpaceId = %v", deliver["openSpaceId"])
+	}
+	if deliver["imGroupOpenDeliverModel"].(map[string]any)["robotCode"] != "ding-client" {
+		t.Fatalf("deliver robotCode missing: %v", deliver)
+	}
+
+	// INPUTING then FINISHED flowStatus around a finalized streaming frame
+	statusOf := func(b map[string]any) string {
+		pm := b["cardData"].(map[string]any)["cardParamMap"].(map[string]any)
+		v, _ := pm["flowStatus"].(string)
+		return v
+	}
+	if statusOf(rec.bodies[2]) != aiCardFlowInputing {
+		t.Fatalf("flowStatus[2] = %v, want INPUTING", statusOf(rec.bodies[2]))
+	}
+	stream := rec.bodies[3]
+	if stream["key"] != "msgContent" || stream["isFinalize"] != true || stream["isError"] != false {
+		t.Fatalf("finalize frame wrong: %v", stream)
+	}
+	if statusOf(rec.bodies[4]) != aiCardFlowFinished {
+		t.Fatalf("flowStatus[4] = %v, want FINISHED", statusOf(rec.bodies[4]))
+	}
+}
+
+// TestAICardDeliverOneToOne checks 1:1 messages deliver into the IM_ROBOT
+// space with the hermes shape (spaceType only, no robotCode).
+func TestAICardDeliverOneToOne(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", defaultAICardTemplateID)
+	data := &chatbot.BotCallbackDataModel{ConversationType: "1", SenderStaffId: "staff-9"}
+	if _, err := c.createAndDeliver(context.Background(), data); err != nil {
+		t.Fatalf("createAndDeliver: %v", err)
+	}
+	deliver := rec.bodies[1]
+	if deliver["openSpaceId"] != "dtv1.card//IM_ROBOT.staff-9" {
+		t.Fatalf("deliver openSpaceId = %v, want IM_ROBOT.staff-9", deliver["openSpaceId"])
+	}
+	model := deliver["imRobotOpenDeliverModel"].(map[string]any)
+	if model["spaceType"] != "IM_ROBOT" || model["robotCode"] != "ding-client" {
+		t.Fatalf("imRobotOpenDeliverModel = %v", model)
+	}
+}
+
+// TestAICardCreateFailure checks errors surface so callers fall back to plain
+// replies (never silently lost), and that missing staffId in 1:1 is rejected.
+func TestAICardCreateFailure(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+	rec.fail["POST /v1.0/card/instances"] = 500
+
+	c := newAICardClient("ding-client", "ding-secret", defaultAICardTemplateID)
+	if _, err := c.createAndDeliver(context.Background(), groupCallback()); err == nil {
+		t.Fatal("want error when card create fails")
+	}
+
+	rec.fail = map[string]int{}
+	if _, err := c.createAndDeliver(context.Background(),
+		&chatbot.BotCallbackDataModel{ConversationType: "1"}); err == nil {
+		t.Fatal("want error for 1:1 without senderStaffId")
+	}
+}
+
+// TestAICardMarkFailed checks the stuck-Thinking remedy: a finalized error
+// frame, errors swallowed.
+func TestAICardMarkFailed(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", defaultAICardTemplateID)
+	c.markFailed(context.Background(), &aiCardInstance{outTrackID: "dws_x"})
+	last := rec.bodies[len(rec.bodies)-1]
+	pm := last["cardData"].(map[string]any)["cardParamMap"].(map[string]any)
+	if pm["flowStatus"] != aiCardFlowFailed {
+		t.Fatalf("markFailed frame wrong: %v", last)
+	}
+}
+
+// TestRobotConnectReplyCardFlag checks the flag default and dry-run surface.
+func TestRobotConnectReplyCardFlag(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{"default: no template -> text + emotions", nil, "thinking/done表态"},
+		{"template configured -> ai-card", []string{"--card-template", "tpl-1.schema"}, `"replyStyle": "ai-card"`},
+		{"public alias -> ai-card", []string{"--card-template", "public"}, `"replyStyle": "ai-card"`},
+		{"explicit off", []string{"--reply-card=false"}, `"replyStyle": "text/markdown"`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := newDevAppTestRoot(&captureRunner{})
+			var out strings.Builder
+			root.SetOut(&out)
+			root.SetErr(&out)
+			args := append([]string{"dev", "connect",
+				"--channel", "claudecode",
+				"--robot-client-id", "a", "--robot-client-secret", "b", "--dry-run"}, tc.args...)
+			root.SetArgs(args)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute: %v\n%s", err, out.String())
+			}
+			if !strings.Contains(out.String(), tc.want) {
+				t.Fatalf("missing %q in:\n%s", tc.want, out.String())
+			}
+		})
+	}
+}
+
+// TestAICardEmotions covers the Thinking chip contract: reply on receive,
+// recall+Done on completion (POST /v1.0/robot/emotion/*).
+func TestAICardEmotions(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", defaultAICardTemplateID)
+	if err := c.markThinking(context.Background(), "cid-1", "msg-1"); err != nil {
+		t.Fatalf("markThinking: %v", err)
+	}
+	c.swapThinkingToDone(context.Background(), "cid-1", "msg-1")
+
+	wantSeq := []string{
+		"POST /v1.0/robot/emotion/reply",  // Thinking
+		"POST /v1.0/robot/emotion/recall", // Thinking recalled
+		"POST /v1.0/robot/emotion/reply",  // Done
+	}
+	if strings.Join(rec.calls, ",") != strings.Join(wantSeq, ",") {
+		t.Fatalf("call sequence = %v, want %v", rec.calls, wantSeq)
+	}
+	first := rec.bodies[0]
+	if first["emotionName"] != "🤔Thinking" || first["openMsgId"] != "msg-1" ||
+		first["robotCode"] != "ding-client" {
+		t.Fatalf("thinking payload wrong: %v", first)
+	}
+	te := first["textEmotion"].(map[string]any)
+	if te["emotionId"] != "2659900" || te["backgroundId"] != "im_bg_1" || te["text"] != "🤔Thinking" {
+		t.Fatalf("textEmotion wrong: %v", te)
+	}
+	if rec.bodies[2]["emotionName"] != "🥳Done" {
+		t.Fatalf("done payload wrong: %v", rec.bodies[2])
+	}
+
+	// Missing ids must error (e.g. payloads without MsgId).
+	if err := c.markThinking(context.Background(), "", "msg-1"); err == nil {
+		t.Fatal("want error for missing conversation id")
+	}
+}
+
+// TestAICardCustomTemplate checks --card-template plumbs through to create.
+func TestAICardCustomTemplate(t *testing.T) {
+	rec, srv := newCardAPIServer(t)
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", "my-own-template.schema")
+	if _, err := c.createAndDeliver(context.Background(), groupCallback()); err != nil {
+		t.Fatalf("createAndDeliver: %v", err)
+	}
+	if rec.bodies[0]["cardTemplateId"] != "my-own-template.schema" {
+		t.Fatalf("cardTemplateId = %v, want custom template", rec.bodies[0]["cardTemplateId"])
+	}
+}

internal/helpers/connect_cmd_class.go

@@ -0,0 +1,290 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import "strings"
+
+// CmdClass describes whether a dws command is read-only or mutating. It is the
+// signal a connector confirmation gate consumes to decide whether a robot may
+// run a command directly (read-only) or must first ask the principal to
+// approve it (write / mutating).
+//
+// SAFETY CONTRACT: callers MUST treat CmdClassUnknown conservatively, i.e. as
+// if it were CmdClassWrite (require confirmation). The classifier deliberately
+// returns Unknown rather than silently coercing it to Write so that the
+// confirmation gate keeps full information and can, for example, log/telemeter
+// "unclassified" commands separately. Never auto-allow an Unknown command.
+type CmdClass int
+
+const (
+	// CmdClassUnknown means the leaf verb was not recognised by the
+	// heuristics or any override. Callers must default to requiring
+	// confirmation (treat as write) for safety.
+	CmdClassUnknown CmdClass = iota
+	// CmdClassRead is a read-only / non-mutating command that may be run
+	// without principal confirmation.
+	CmdClassRead
+	// CmdClassWrite is a mutating / state-changing command that must be
+	// confirmed by the principal before it runs.
+	CmdClassWrite
+)
+
+// String renders the class as a stable lowercase token, handy for logs and
+// telemetry.
+func (c CmdClass) String() string {
+	switch c {
+	case CmdClassRead:
+		return "read"
+	case CmdClassWrite:
+		return "write"
+	default:
+		return "unknown"
+	}
+}
+
+// readVerbs and writeVerbs are calibrated against the verbs that real dws
+// cobra commands expose (scanned from `Use:` definitions across the repo, e.g.
+// todo task create/list/get/update/delete/done, attendance get, approval
+// submit, chat send / recall, drive upload / download / mkdir / chmod, doc
+// export, contact search, etc). They are NOT invented: every entry below has
+// at least one real command using it (or a "<verb>-by-..." / "batch-<verb>"
+// compound that normalises to it).
+var (
+	readVerbs = map[string]struct{}{
+		"list":     {},
+		"get":      {},
+		"search":   {},
+		"read":     {},
+		"view":     {},
+		"query":    {},
+		"show":     {},
+		"detail":   {},
+		"details":  {},
+		"status":   {},
+		"download": {},
+		"export":   {},
+		"fetch":    {},
+		"info":     {},
+		"find":     {},
+		"stats":    {},
+		"stat":     {},
+		"summary":  {},
+		"check":    {},
+		"inspect":  {},
+		"doctor":   {},
+		"version":  {},
+		"whoami":   {},
+		"ls":       {},
+		"cat":      {},
+		"describe": {},
+		"diff":     {},
+		"preview":  {},
+	}
+
+	writeVerbs = map[string]struct{}{
+		"create":     {},
+		"update":     {},
+		"delete":     {},
+		"submit":     {},
+		"send":       {},
+		"done":       {},
+		"cancel":     {},
+		"offline":    {},
+		"online":     {},
+		"enable":     {},
+		"disable":    {},
+		"remove":     {},
+		"add":        {},
+		"set":        {},
+		"unset":      {},
+		"approve":    {},
+		"reject":     {},
+		"write":      {},
+		"upload":     {},
+		"move":       {},
+		"mv":         {},
+		"copy":       {},
+		"cp":         {},
+		"rename":     {},
+		"reply":      {},
+		"recall":     {},
+		"publish":    {},
+		"insert":     {},
+		"import":     {},
+		"install":    {},
+		"uninstall":  {},
+		"mkdir":      {},
+		"share":      {},
+		"unshare":    {},
+		"commit":     {},
+		"reset":      {},
+		"stop":       {},
+		"start":      {},
+		"restart":    {},
+		"hide":       {},
+		"unhide":     {},
+		"finalize":   {},
+		"execute":    {},
+		"run":        {},
+		"exec":       {},
+		"chmod":      {},
+		"rm":         {},
+		"clean":      {},
+		"clear":      {},
+		"refresh":    {},
+		"recover":    {},
+		"recovery":   {},
+		"login":      {},
+		"logout":     {},
+		"register":   {},
+		"connect":    {},
+		"disconnect": {},
+		"upgrade":    {},
+		"setup":      {},
+		"generate":   {},
+		"batch":      {},
+		"apply":      {},
+		"patch":      {},
+		"put":        {},
+		"post":       {},
+		"sync":       {},
+		"link":       {},
+		"unlink":     {},
+		"grant":      {},
+		"revoke":     {},
+		"assign":     {},
+		"close":      {},
+		"open":       {},
+		"archive":    {},
+		"restore":    {},
+		"finish":     {},
+	}
+)
+
+// defaultClassOverrides is the package-level override table. It is intentionally
+// empty by default: heuristics are expected to cover the common case, and the
+// override table exists only to correct individual misclassifications without
+// touching the heuristic verb tables. Mutate it via SetCmdClassOverride.
+//
+// Keys may be either a single verb ("download") or a full space-joined command
+// path ("doc export"); both are matched case-insensitively. A full-path key
+// wins over a single-verb key when both are present.
+var defaultClassOverrides = map[string]CmdClass{}
+
+// SetCmdClassOverride registers a process-wide classification override for the
+// given key. The key may be a single verb or a space-joined command path; it is
+// normalised to lowercase. Passing CmdClassUnknown removes the override.
+func SetCmdClassOverride(key string, class CmdClass) {
+	key = strings.ToLower(strings.TrimSpace(key))
+	if key == "" {
+		return
+	}
+	if class == CmdClassUnknown {
+		delete(defaultClassOverrides, key)
+		return
+	}
+	defaultClassOverrides[key] = class
+}
+
+// ClassifyDwsCommand classifies a dws command given its path segments (e.g.
+// "todo", "task", "create"). It consults the package-level override table and
+// then the read/write verb heuristics, scanning segments right-to-left so the
+// leaf action verb dominates a container/noun segment.
+//
+// Remember the SAFETY CONTRACT on CmdClass: a CmdClassUnknown result MUST be
+// treated as write (require confirmation) by the caller.
+func ClassifyDwsCommand(parts ...string) CmdClass {
+	return ClassifyDwsCommandWith(defaultClassOverrides, parts...)
+}
+
+// ClassifyDwsCommandWith is like ClassifyDwsCommand but lets the caller supply
+// an explicit override table (e.g. a per-tenant or per-request map) instead of
+// the package-level one. A nil overrides map is allowed and means "no
+// overrides". Override lookups always win over the heuristics.
+func ClassifyDwsCommandWith(overrides map[string]CmdClass, parts ...string) CmdClass {
+	norm := normalizeParts(parts)
+	if len(norm) == 0 {
+		return CmdClassUnknown
+	}
+
+	// 1. Full-path override (most specific) wins.
+	if overrides != nil {
+		fullKey := strings.Join(norm, " ")
+		if c, ok := overrides[fullKey]; ok {
+			return c
+		}
+	}
+
+	// 2. Walk segments right-to-left: the leaf action verb is the most
+	//    meaningful, but a leaf may be a noun/placeholder (e.g. an id) that
+	//    we do not recognise, so fall back toward the root.
+	for i := len(norm) - 1; i >= 0; i-- {
+		seg := norm[i]
+		if overrides != nil {
+			if c, ok := overrides[seg]; ok {
+				return c
+			}
+		}
+		if c, ok := classifyVerb(seg); ok {
+			return c
+		}
+	}
+
+	return CmdClassUnknown
+}
+
+// classifyVerb classifies a single segment, handling compound verbs such as
+// "send-by-bot", "list-forms", "batch-update" or "create_inline" by also
+// trying the token before the first separator. Returns (class, true) when the
+// segment maps to a known verb.
+func classifyVerb(seg string) (CmdClass, bool) {
+	candidates := verbCandidates(seg)
+	for _, v := range candidates {
+		if _, ok := readVerbs[v]; ok {
+			return CmdClassRead, true
+		}
+		if _, ok := writeVerbs[v]; ok {
+			return CmdClassWrite, true
+		}
+	}
+	return CmdClassUnknown, false
+}
+
+// verbCandidates expands a segment into the tokens worth checking against the
+// verb tables, in priority order: the whole segment first, then the leading
+// token before the first '-' or '_' separator (so "batch-update" tries
+// "update"-as-prefix... no: it tries "batch" first which is itself a write
+// verb; and "send-by-bot" tries "send"). This handles both "<verb>-<qualifier>"
+// and "<verb>_<qualifier>" compounds where the action sits at the front.
+func verbCandidates(seg string) []string {
+	out := []string{seg}
+	if i := strings.IndexAny(seg, "-_"); i > 0 {
+		out = append(out, seg[:i])
+	}
+	return out
+}
+
+// normalizeParts lowercases, trims and drops empty/whitespace segments so that
+// callers can pass raw argv-style slices without pre-cleaning them.
+func normalizeParts(parts []string) []string {
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.ToLower(strings.TrimSpace(p))
+		if p == "" {
+			continue
+		}
+		out = append(out, p)
+	}
+	return out
+}

internal/helpers/connect_cmd_class_test.go

@@ -0,0 +1,176 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import "testing"
+
+func TestClassifyDwsCommandReadVerbs(t *testing.T) {
+	readLeaves := []string{
+		"list", "get", "search", "read", "view", "query", "show",
+		"detail", "status", "download", "export", "fetch", "info",
+		"find", "summary",
+	}
+	for _, v := range readLeaves {
+		if got := ClassifyDwsCommand("todo", "task", v); got != CmdClassRead {
+			t.Errorf("verb %q: got %v, want CmdClassRead", v, got)
+		}
+	}
+}
+
+func TestClassifyDwsCommandWriteVerbs(t *testing.T) {
+	writeLeaves := []string{
+		"create", "update", "delete", "submit", "send", "done",
+		"cancel", "offline", "enable", "disable", "remove", "add",
+		"set", "approve", "reject", "write", "upload", "move", "copy",
+	}
+	for _, v := range writeLeaves {
+		if got := ClassifyDwsCommand("approval", "instance", v); got != CmdClassWrite {
+			t.Errorf("verb %q: got %v, want CmdClassWrite", v, got)
+		}
+	}
+}
+
+func TestClassifyDwsCommandUnknown(t *testing.T) {
+	cases := [][]string{
+		{},
+		{"todo"},                   // container only, no action verb
+		{"todo", "task"},           // still only containers
+		{"frobnicate"},             // nonsense verb
+		{"todo", "task", "wibble"}, // unknown leaf, no known ancestor
+		{"   ", ""},                // all empty after trim
+	}
+	for _, c := range cases {
+		if got := ClassifyDwsCommand(c...); got != CmdClassUnknown {
+			t.Errorf("parts %v: got %v, want CmdClassUnknown", c, got)
+		}
+	}
+}
+
+func TestClassifyDwsCommandRealSamples(t *testing.T) {
+	cases := []struct {
+		parts []string
+		want  CmdClass
+	}{
+		// Real dws command paths sampled from the repo's cobra Use: defs.
+		{[]string{"todo", "task", "create"}, CmdClassWrite},
+		{[]string{"todo", "task", "list"}, CmdClassRead},
+		{[]string{"todo", "task", "get"}, CmdClassRead},
+		{[]string{"todo", "task", "update"}, CmdClassWrite},
+		{[]string{"todo", "task", "delete"}, CmdClassWrite},
+		{[]string{"todo", "task", "done"}, CmdClassWrite},
+		{[]string{"approval", "instance", "submit"}, CmdClassWrite},
+		{[]string{"attendance", "get"}, CmdClassRead},
+		{[]string{"chat", "message", "send"}, CmdClassWrite},
+		{[]string{"chat", "message", "list"}, CmdClassRead},
+		{[]string{"drive", "file", "download"}, CmdClassRead},
+		{[]string{"drive", "file", "upload"}, CmdClassWrite},
+		{[]string{"drive", "dir", "mkdir"}, CmdClassWrite},
+		{[]string{"doc", "export"}, CmdClassRead},
+		{[]string{"contact", "user", "search"}, CmdClassRead},
+		{[]string{"report", "status"}, CmdClassRead},
+	}
+	for _, c := range cases {
+		if got := ClassifyDwsCommand(c.parts...); got != c.want {
+			t.Errorf("cmd %v: got %v, want %v", c.parts, got, c.want)
+		}
+	}
+}
+
+func TestClassifyDwsCommandCompoundVerbs(t *testing.T) {
+	cases := []struct {
+		parts []string
+		want  CmdClass
+	}{
+		// Compound leaf verbs that exist in the repo.
+		{[]string{"chat", "send-by-bot"}, CmdClassWrite},
+		{[]string{"chat", "send-by-webhook"}, CmdClassWrite},
+		{[]string{"chat", "recall-by-bot"}, CmdClassWrite},
+		{[]string{"aitable", "form", "list-forms"}, CmdClassRead},
+		{[]string{"wiki", "space", "list-spaces"}, CmdClassRead},
+		{[]string{"record", "batch-update"}, CmdClassWrite},
+		{[]string{"group", "add-bot"}, CmdClassWrite},
+		{[]string{"group", "remove-bot"}, CmdClassWrite},
+	}
+	for _, c := range cases {
+		if got := ClassifyDwsCommand(c.parts...); got != c.want {
+			t.Errorf("compound %v: got %v, want %v", c.parts, got, c.want)
+		}
+	}
+}
+
+func TestClassifyDwsCommandLeafFallbackToAncestor(t *testing.T) {
+	// When the true leaf is a placeholder/id segment we don't recognise,
+	// classification falls back to the nearest known ancestor verb.
+	if got := ClassifyDwsCommand("todo", "task", "get", "abc123"); got != CmdClassRead {
+		t.Errorf("trailing id segment: got %v, want CmdClassRead", got)
+	}
+	if got := ClassifyDwsCommand("todo", "task", "create", "xyz"); got != CmdClassWrite {
+		t.Errorf("trailing id segment: got %v, want CmdClassWrite", got)
+	}
+}
+
+func TestCmdClassOverrideTable(t *testing.T) {
+	// Suppose "download" should require confirmation for some tenant: a
+	// full-path override flips a normally-read command to write without
+	// touching the heuristic tables.
+	overrides := map[string]CmdClass{
+		"drive file download": CmdClassWrite, // full-path override
+		"export":              CmdClassWrite, // single-verb override
+	}
+
+	if got := ClassifyDwsCommandWith(overrides, "drive", "file", "download"); got != CmdClassWrite {
+		t.Errorf("full-path override: got %v, want CmdClassWrite", got)
+	}
+	// A different path whose leaf is "download" is NOT affected by the
+	// full-path override and stays read.
+	if got := ClassifyDwsCommandWith(overrides, "media", "download"); got != CmdClassRead {
+		t.Errorf("unrelated download path: got %v, want CmdClassRead", got)
+	}
+	// Single-verb override flips every "export" leaf.
+	if got := ClassifyDwsCommandWith(overrides, "doc", "export"); got != CmdClassWrite {
+		t.Errorf("single-verb override: got %v, want CmdClassWrite", got)
+	}
+}
+
+func TestSetCmdClassOverrideProcessWide(t *testing.T) {
+	defer SetCmdClassOverride("status", CmdClassUnknown) // cleanup
+
+	// Baseline: status is read.
+	if got := ClassifyDwsCommand("report", "status"); got != CmdClassRead {
+		t.Fatalf("baseline status: got %v, want CmdClassRead", got)
+	}
+	// Register a process-wide override making status write.
+	SetCmdClassOverride("STATUS", CmdClassWrite) // case-insensitive key
+	if got := ClassifyDwsCommand("report", "status"); got != CmdClassWrite {
+		t.Errorf("after override: got %v, want CmdClassWrite", got)
+	}
+	// Removing the override restores the heuristic result.
+	SetCmdClassOverride("status", CmdClassUnknown)
+	if got := ClassifyDwsCommand("report", "status"); got != CmdClassRead {
+		t.Errorf("after override removal: got %v, want CmdClassRead", got)
+	}
+}
+
+func TestCmdClassString(t *testing.T) {
+	cases := map[CmdClass]string{
+		CmdClassRead:    "read",
+		CmdClassWrite:   "write",
+		CmdClassUnknown: "unknown",
+	}
+	for c, want := range cases {
+		if got := c.String(); got != want {
+			t.Errorf("String(%d): got %q, want %q", c, got, want)
+		}
+	}
+}

internal/helpers/connect_codex_appserver.go

@@ -0,0 +1,625 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+)
+
+const codexRobotDeveloperInstructions = "你是钉钉群聊里的智能助手，请用简洁、自然的中文直接回答用户问题；不要提及系统提示、内部协议或运行时细节；不要主动读写文件或执行命令。"
+
+// codexAppServerForwarder uses Codex's official app-server JSON-RPC protocol to
+// keep one Codex thread per DingTalk conversation.
+type codexAppServerForwarder struct {
+	bin      string
+	env      []string
+	timeout  time.Duration
+	workDir  string
+	model    string
+	sessions *codexThreadSessions
+}
+
+func newCodexAppServerForwarder(bin string, env []string, timeout time.Duration, opts connectAgentOptions, clientID string) forwarder {
+	var sessions *codexThreadSessions
+	if opts.Memory {
+		// Scope the on-disk thread store by clientId so multiple bots on one
+		// machine stay isolated; an empty clientId disables persistence and the
+		// map stays in memory (original behaviour).
+		sessions = newCodexThreadSessions(codexThreadStorePath(clientID))
+	}
+	return &codexAppServerForwarder{
+		bin:      bin,
+		env:      env,
+		timeout:  timeout,
+		workDir:  opts.WorkDir,
+		model:    opts.Model,
+		sessions: sessions,
+	}
+}
+
+// codexThreadStorePath returns the on-disk location for a robot's codex
+// conversation→thread map, scoped by clientId so multiple bots on one machine
+// stay isolated: <config dir>/connect/<clientId>/codex-threads.json. It mirrors
+// the Claude-family connectSessionStorePath layout but uses a distinct filename
+// so the two stores never collide. An empty clientId means "do not persist"
+// (in-memory only). The clientId is sanitized with the same rule as the connect
+// lock file so it is always filesystem-safe.
+func codexThreadStorePath(clientID string) string {
+	if clientID == "" {
+		return ""
+	}
+	return filepath.Join(config.DefaultConfigDir(), "connect", sanitizeLockID(clientID), "codex-threads.json")
+}
+
+// resetSession drops the conversation's Codex thread so the next message starts
+// a fresh one. Implements sessionResetter for the built-in /new and /clear
+// commands. A no-op when per-conversation memory is disabled.
+func (f *codexAppServerForwarder) resetSession(convID string) {
+	if f.sessions != nil {
+		f.sessions.reset(convID)
+	}
+}
+
+func (f *codexAppServerForwarder) canStream() bool { return true }
+
+func (f *codexAppServerForwarder) label() string {
+	memo := "stateless"
+	if f.sessions != nil {
+		memo = "thread-memory"
+	}
+	return fmt.Sprintf("codex-app-server:%s (%s)", f.bin, memo)
+}
+
+func (f *codexAppServerForwarder) forward(ctx context.Context, convID, text string) (string, error) {
+	return f.forwardStream(ctx, convID, text, nil)
+}
+
+func (f *codexAppServerForwarder) forwardStream(ctx context.Context, convID, text string, onDelta func(string)) (string, error) {
+	return f.forwardAppServer(ctx, convID, text, onDelta)
+}
+
+func (f *codexAppServerForwarder) forwardAppServer(ctx context.Context, convID, text string, onDelta func(string)) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, f.timeout)
+	defer cancel()
+
+	var state *codexThreadState
+	if f.sessions != nil {
+		state = f.sessions.state(convID)
+		state.mu.Lock()
+		defer state.mu.Unlock()
+	}
+
+	cli, err := newCodexAppServerClient(ctx, f.bin, f.env, f.cwd())
+	if err != nil {
+		return "", err
+	}
+	defer cli.close()
+
+	if err := cli.initialize(ctx); err != nil {
+		return "", err
+	}
+
+	_ = state // held only for its per-conversation turn lock (see above)
+	threadID := ""
+	if f.sessions != nil {
+		threadID = f.sessions.threadID(convID)
+	}
+	if threadID != "" {
+		resumed, err := cli.resumeThread(ctx, f.threadParams(threadID))
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "[connect][codex] resume thread %s 失败，重建会话: %v\n", threadID, err)
+			threadID = ""
+			f.sessions.setThreadID(convID, "")
+		} else {
+			threadID = resumed
+		}
+	}
+	if threadID == "" {
+		started, err := cli.startThread(ctx, f.threadParams(""))
+		if err != nil {
+			return "", err
+		}
+		threadID = started
+		if f.sessions != nil {
+			f.sessions.setThreadID(convID, threadID)
+		}
+	}
+
+	reply, err := cli.runTurn(ctx, threadID, text, onDelta)
+	if err != nil {
+		return "", err
+	}
+	return reply, nil
+}
+
+func (f *codexAppServerForwarder) cwd() string {
+	if f.workDir == "" {
+		return connectWorkDir()
+	}
+	if abs, err := filepath.Abs(f.workDir); err == nil {
+		return abs
+	}
+	return f.workDir
+}
+
+func (f *codexAppServerForwarder) threadParams(threadID string) map[string]any {
+	params := map[string]any{
+		"approvalPolicy":        "never",
+		"cwd":                   f.cwd(),
+		"developerInstructions": codexRobotDeveloperInstructions,
+		"sandbox":               "read-only",
+	}
+	if f.model != "" {
+		params["model"] = f.model
+	}
+	if threadID != "" {
+		params["threadId"] = threadID
+	}
+	return params
+}
+
+// codexThreadSessions maps a DingTalk conversation to its Codex thread so
+// multi-turn context survives within a conversation. The convID→threadID map
+// (threads, guarded by mu) is the authoritative store and is persisted to disk
+// so the context also survives a connector restart — the codex equivalent of
+// the Claude-family convSessions store. An empty path keeps it in memory only
+// (persistence disabled), preserving the original behaviour exactly.
+//
+// states holds a per-conversation lock that serializes turns within one
+// conversation; it carries no thread identity of its own.
+type codexThreadSessions struct {
+	mu      sync.Mutex
+	states  map[string]*codexThreadState // per-conversation turn lock
+	threads map[string]string            // convID→threadID, persisted
+	path    string                       // on-disk store; empty disables persistence
+}
+
+// codexThreadState is a per-conversation turn lock. Holding it for the duration
+// of a turn keeps two messages in the same conversation from interleaving their
+// app-server calls; thread identity lives in codexThreadSessions.threads.
+type codexThreadState struct {
+	mu sync.Mutex
+}
+
+// newCodexThreadSessions builds the session map, restoring any persisted
+// convID→threadID entries from path. A missing or corrupt file degrades to an
+// empty map (see loadConvSessionMap) — it never panics or blocks startup. An
+// empty path means in-memory only.
+func newCodexThreadSessions(path string) *codexThreadSessions {
+	return &codexThreadSessions{
+		states:  make(map[string]*codexThreadState),
+		threads: loadConvSessionMap(path),
+		path:    path,
+	}
+}
+
+// codexConvKey normalizes a conversation ID into a stable, non-empty map key.
+func codexConvKey(convID string) string {
+	key := strings.TrimSpace(convID)
+	if key == "" {
+		key = "_default"
+	}
+	return key
+}
+
+// state returns the per-conversation turn lock, minting one on first sight.
+func (s *codexThreadSessions) state(convID string) *codexThreadState {
+	key := codexConvKey(convID)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if st, ok := s.states[key]; ok {
+		return st
+	}
+	st := &codexThreadState{}
+	s.states[key] = st
+	return st
+}
+
+// threadID returns the Codex thread bound to a conversation, or "" if none.
+func (s *codexThreadSessions) threadID(convID string) string {
+	key := codexConvKey(convID)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.threads[key]
+}
+
+// setThreadID binds a conversation to a Codex thread and persists the snapshot.
+// A "" threadID forgets the binding (same as reset). Persistence is best-effort:
+// a failed save only logs a warning and never blocks message handling.
+func (s *codexThreadSessions) setThreadID(convID, threadID string) {
+	key := codexConvKey(convID)
+	s.mu.Lock()
+	if threadID == "" {
+		delete(s.threads, key)
+	} else {
+		s.threads[key] = threadID
+	}
+	snapshot := make(map[string]string, len(s.threads))
+	for k, v := range s.threads {
+		snapshot[k] = v
+	}
+	path := s.path
+	s.mu.Unlock()
+	saveConvSessionMap(path, snapshot)
+}
+
+// reset forgets a conversation's thread so the next message starts a fresh one.
+// The removal is persisted so a restart does not resurrect the dropped thread.
+func (s *codexThreadSessions) reset(convID string) {
+	s.setThreadID(convID, "")
+}
+
+type codexAppServerClient struct {
+	cmd       *exec.Cmd
+	stdin     io.WriteCloser
+	msgs      chan codexRPCMessage
+	readErr   chan error
+	done      chan struct{}
+	closeOnce sync.Once
+	stderr    *lockedBuffer
+	nextID    int
+}
+
+type lockedBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *lockedBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *lockedBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+type codexRPCMessage struct {
+	ID     *int            `json:"id,omitempty"`
+	Method string          `json:"method,omitempty"`
+	Params json.RawMessage `json:"params,omitempty"`
+	Result json.RawMessage `json:"result,omitempty"`
+	Error  *codexRPCError  `json:"error,omitempty"`
+}
+
+type codexRPCError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+func newCodexAppServerClient(ctx context.Context, bin string, env []string, cwd string) (*codexAppServerClient, error) {
+	cmd := exec.CommandContext(ctx, bin, "app-server", "--stdio")
+	cmd.Dir = cwd
+	if len(env) > 0 {
+		cmd.Env = append(os.Environ(), env...)
+	}
+	stdin, err := cmd.StdinPipe()
+	if err != nil {
+		return nil, err
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return nil, err
+	}
+	stderr := &lockedBuffer{}
+	cmd.Stderr = stderr
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	cli := &codexAppServerClient{
+		cmd:     cmd,
+		stdin:   stdin,
+		msgs:    make(chan codexRPCMessage, 64),
+		readErr: make(chan error, 1),
+		done:    make(chan struct{}),
+		stderr:  stderr,
+		nextID:  1,
+	}
+	go cli.readLoop(stdout)
+	return cli, nil
+}
+
+func (c *codexAppServerClient) readLoop(stdout io.Reader) {
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		var msg codexRPCMessage
+		if err := json.Unmarshal([]byte(line), &msg); err != nil {
+			c.reportReadErr(fmt.Errorf("parse app-server JSONL: %w", err))
+			close(c.msgs)
+			return
+		}
+		select {
+		case c.msgs <- msg:
+		case <-c.done:
+			return
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		c.reportReadErr(err)
+	} else {
+		c.reportReadErr(io.EOF)
+	}
+	close(c.msgs)
+}
+
+func (c *codexAppServerClient) close() {
+	c.closeOnce.Do(func() {
+		close(c.done)
+		_ = c.stdin.Close()
+		if c.cmd.Process != nil {
+			_ = c.cmd.Process.Kill()
+		}
+		_ = c.cmd.Wait()
+	})
+}
+
+func (c *codexAppServerClient) reportReadErr(err error) {
+	select {
+	case c.readErr <- err:
+	case <-c.done:
+	}
+}
+
+func (c *codexAppServerClient) initialize(ctx context.Context) error {
+	id := c.requestID()
+	if err := c.send(map[string]any{
+		"id":     id,
+		"method": "initialize",
+		"params": map[string]any{
+			"capabilities": map[string]any{"experimentalApi": true},
+			"clientInfo": map[string]any{
+				"name":    "dws-devapp-robot-connect",
+				"title":   "DWS DevApp Robot Connect",
+				"version": "0.1.0",
+			},
+		},
+	}); err != nil {
+		return err
+	}
+	if _, err := c.waitResponse(ctx, id); err != nil {
+		return err
+	}
+	return c.send(map[string]any{"method": "initialized", "params": map[string]any{}})
+}
+
+func (c *codexAppServerClient) startThread(ctx context.Context, params map[string]any) (string, error) {
+	id := c.requestID()
+	if err := c.send(map[string]any{"id": id, "method": "thread/start", "params": params}); err != nil {
+		return "", err
+	}
+	return codexThreadIDFromResult(c.waitResponse(ctx, id))
+}
+
+func (c *codexAppServerClient) resumeThread(ctx context.Context, params map[string]any) (string, error) {
+	id := c.requestID()
+	if err := c.send(map[string]any{"id": id, "method": "thread/resume", "params": params}); err != nil {
+		return "", err
+	}
+	return codexThreadIDFromResult(c.waitResponse(ctx, id))
+}
+
+func (c *codexAppServerClient) runTurn(ctx context.Context, threadID, text string, onDelta func(string)) (string, error) {
+	id := c.requestID()
+	if err := c.send(map[string]any{
+		"id":     id,
+		"method": "turn/start",
+		"params": map[string]any{
+			"input":    []map[string]string{{"type": "text", "text": text}},
+			"threadId": threadID,
+		},
+	}); err != nil {
+		return "", err
+	}
+
+	var acc strings.Builder
+	for {
+		msg, err := c.next(ctx)
+		if err != nil {
+			return "", c.withStderr("app-server stream ended before turn/completed", err)
+		}
+		if msg.ID != nil && msg.Method != "" {
+			c.rejectServerRequest(*msg.ID, msg.Method)
+			continue
+		}
+		if msg.ID != nil && *msg.ID == id && msg.Error != nil {
+			return "", fmt.Errorf("turn/start: %s", msg.Error.Message)
+		}
+		switch msg.Method {
+		case "item/agentMessage/delta":
+			var p struct {
+				Delta    string `json:"delta"`
+				ThreadID string `json:"threadId"`
+			}
+			if json.Unmarshal(msg.Params, &p) == nil && p.ThreadID == threadID && p.Delta != "" {
+				acc.WriteString(p.Delta)
+				if onDelta != nil {
+					onDelta(acc.String())
+				}
+			}
+		case "turn/completed":
+			final, status, errMsg, ok := codexTurnCompletedText(msg.Params, threadID)
+			if !ok {
+				continue
+			}
+			if status == "failed" {
+				if errMsg == "" {
+					errMsg = "turn failed"
+				}
+				return "", fmt.Errorf("%s", errMsg)
+			}
+			if final == "" {
+				final = strings.TrimSpace(acc.String())
+			}
+			if final == "" {
+				return "", fmt.Errorf("turn completed without agent message")
+			}
+			return final, nil
+		case "error":
+			return "", fmt.Errorf("app-server error notification: %s", truncateRunes(string(msg.Params), 300))
+		}
+	}
+}
+
+func (c *codexAppServerClient) requestID() int {
+	id := c.nextID
+	c.nextID++
+	return id
+}
+
+func (c *codexAppServerClient) send(v any) error {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	_, err = fmt.Fprintln(c.stdin, string(b))
+	return err
+}
+
+func (c *codexAppServerClient) waitResponse(ctx context.Context, id int) (json.RawMessage, error) {
+	for {
+		msg, err := c.next(ctx)
+		if err != nil {
+			return nil, c.withStderr("app-server exited before response", err)
+		}
+		if msg.ID != nil && msg.Method != "" {
+			c.rejectServerRequest(*msg.ID, msg.Method)
+			continue
+		}
+		if msg.ID == nil || *msg.ID != id {
+			continue
+		}
+		if msg.Error != nil {
+			return nil, fmt.Errorf("%s", msg.Error.Message)
+		}
+		return msg.Result, nil
+	}
+}
+
+func (c *codexAppServerClient) next(ctx context.Context) (codexRPCMessage, error) {
+	// The read loop reports EOF before closing msgs, so when the process
+	// exits right after its last frame both channels are ready and select
+	// would pick one at random — drain buffered frames (e.g. the final
+	// turn/completed) before honoring a read error.
+	select {
+	case msg, ok := <-c.msgs:
+		if !ok {
+			return codexRPCMessage{}, io.EOF
+		}
+		return msg, nil
+	default:
+	}
+	select {
+	case msg, ok := <-c.msgs:
+		if !ok {
+			return codexRPCMessage{}, io.EOF
+		}
+		return msg, nil
+	case err := <-c.readErr:
+		return codexRPCMessage{}, err
+	case <-c.done:
+		return codexRPCMessage{}, io.EOF
+	case <-ctx.Done():
+		return codexRPCMessage{}, ctx.Err()
+	}
+}
+
+func (c *codexAppServerClient) rejectServerRequest(id int, method string) {
+	_ = c.send(map[string]any{
+		"id": id,
+		"error": map[string]any{
+			"code":    -32000,
+			"message": "DWS robot connect does not support interactive Codex app-server request: " + method,
+		},
+	})
+}
+
+func (c *codexAppServerClient) withStderr(prefix string, err error) error {
+	stderr := strings.TrimSpace(c.stderr.String())
+	if stderr == "" {
+		return fmt.Errorf("%s: %w", prefix, err)
+	}
+	return fmt.Errorf("%s: %w: %s", prefix, err, truncateRunes(stderr, 300))
+}
+
+func codexThreadIDFromResult(result json.RawMessage, err error) (string, error) {
+	if err != nil {
+		return "", err
+	}
+	var r struct {
+		Thread struct {
+			ID string `json:"id"`
+		} `json:"thread"`
+	}
+	if err := json.Unmarshal(result, &r); err != nil {
+		return "", err
+	}
+	if r.Thread.ID == "" {
+		return "", fmt.Errorf("app-server response missing thread.id")
+	}
+	return r.Thread.ID, nil
+}
+
+func codexTurnCompletedText(params json.RawMessage, wantThreadID string) (final, status, errMsg string, ok bool) {
+	var p struct {
+		ThreadID string `json:"threadId"`
+		Turn     struct {
+			Status string `json:"status"`
+			Error  *struct {
+				Message           string `json:"message"`
+				AdditionalDetails string `json:"additionalDetails"`
+			} `json:"error"`
+			Items []struct {
+				Type string `json:"type"`
+				Text string `json:"text"`
+			} `json:"items"`
+		} `json:"turn"`
+	}
+	if err := json.Unmarshal(params, &p); err != nil || p.ThreadID != wantThreadID {
+		return "", "", "", false
+	}
+	for i := len(p.Turn.Items) - 1; i >= 0; i-- {
+		if p.Turn.Items[i].Type == "agentMessage" && strings.TrimSpace(p.Turn.Items[i].Text) != "" {
+			final = strings.TrimSpace(p.Turn.Items[i].Text)
+			break
+		}
+	}
+	if p.Turn.Error != nil {
+		errMsg = strings.TrimSpace(p.Turn.Error.Message)
+		if p.Turn.Error.AdditionalDetails != "" {
+			errMsg = strings.TrimSpace(errMsg + ": " + p.Turn.Error.AdditionalDetails)
+		}
+	}
+	return final, p.Turn.Status, errMsg, true
+}

internal/helpers/connect_codex_appserver_test.go

@@ -0,0 +1,271 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func writeShellExecutable(t *testing.T, dir, name, body string) string {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte("#!/bin/sh\n"+body), 0o755); err != nil {
+		t.Fatalf("write stub %s: %v", name, err)
+	}
+	return path
+}
+
+func TestForwarderForChannelCodexPrefersAppServer(t *testing.T) {
+	clearChannelEnv(t)
+	t.Setenv("DWS_CONNECT_NO_INSTALL", "1")
+	stub := t.TempDir()
+	writeShellExecutable(t, stub, "codex", "exit 0\n")
+	t.Setenv("PATH", stub)
+
+	fwd, err := forwarderForChannel("codex", "", connectAgentOptions{Memory: true})
+	if err != nil {
+		t.Fatalf("codex forwarder: %v", err)
+	}
+	cf, ok := fwd.(*codexAppServerForwarder)
+	if !ok {
+		t.Fatalf("codex should prefer app-server forwarder, got %T", fwd)
+	}
+	if cf.sessions == nil {
+		t.Fatal("codex app-server should keep per-conversation thread memory by default")
+	}
+
+	t.Setenv("DWS_CODEX_APP_SERVER", "0")
+	fwd, err = forwarderForChannel("codex", "", connectAgentOptions{Memory: true})
+	if err != nil {
+		t.Fatalf("codex forwarder with deprecated app-server env: %v", err)
+	}
+	if _, ok := fwd.(*codexAppServerForwarder); !ok {
+		t.Fatalf("DWS_CODEX_APP_SERVER=0 should be ignored and keep app-server, got %T", fwd)
+	}
+}
+
+func TestCodexConnectPlanIgnoresAppServerEnv(t *testing.T) {
+	clearChannelEnv(t)
+	plan := buildConnectPlan("codex", "cid", "")
+	if got := plan["method"]; got != "stream-bridge-codex-app-server" {
+		t.Fatalf("default codex plan method = %v", got)
+	}
+	payload := connectAgentOptionsPayload("codex", connectAgentOptions{Memory: true})
+	if got := payload["memory"]; got != "per-conversation-app-server" {
+		t.Fatalf("default codex memory = %v", got)
+	}
+
+	t.Setenv("DWS_CODEX_APP_SERVER", "0")
+	plan = buildConnectPlan("codex", "cid", "")
+	if got := plan["method"]; got != "stream-bridge-codex-app-server" {
+		t.Fatalf("deprecated app-server env should be ignored, method = %v", got)
+	}
+	payload = connectAgentOptionsPayload("codex", connectAgentOptions{Memory: true})
+	if got := payload["memory"]; got != "per-conversation-app-server" {
+		t.Fatalf("deprecated app-server env should keep codex memory, got %v", got)
+	}
+}
+
+func TestCodexConnectPlanIgnoresAgentCmdOverride(t *testing.T) {
+	clearChannelEnv(t)
+	t.Setenv("DWS_AGENT_CMD", "my-codex exec")
+	plan := buildConnectPlan("codex", "cid", "")
+	if got := plan["method"]; got != "stream-bridge-codex-app-server" {
+		t.Fatalf("codex should ignore DWS_AGENT_CMD and keep app-server plan, method = %v", got)
+	}
+	payload := connectAgentOptionsPayload("codex", connectAgentOptions{Memory: true})
+	if got := payload["memory"]; got != "per-conversation-app-server" {
+		t.Fatalf("codex should ignore DWS_AGENT_CMD and keep app-server memory, got %v", got)
+	}
+}
+
+func TestCodexAppServerForwarderStreamsAndRemembersThread(t *testing.T) {
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "requests.log")
+	codex := writeShellExecutable(t, dir, "codex", `
+while IFS= read -r line; do
+  printf '%s\n' "$line" >> "$CODEX_STUB_LOG"
+  case "$line" in
+    *\"method\":\"initialize\"*) printf '%s\n' '{"id":1,"result":{}}' ;;
+    *\"method\":\"thread/start\"*) printf '%s\n' '{"id":2,"result":{"thread":{"id":"thr_stub"}}}' ;;
+    *\"method\":\"thread/resume\"*) printf '%s\n' '{"id":2,"result":{"thread":{"id":"thr_stub"}}}' ;;
+    *\"method\":\"turn/start\"*)
+      printf '%s\n' '{"method":"item/agentMessage/delta","params":{"threadId":"thr_stub","turnId":"turn_stub","itemId":"item_1","delta":"你"}}'
+      printf '%s\n' '{"method":"item/agentMessage/delta","params":{"threadId":"thr_stub","turnId":"turn_stub","itemId":"item_1","delta":"好"}}'
+      printf '%s\n' '{"method":"turn/completed","params":{"threadId":"thr_stub","turn":{"id":"turn_stub","status":"completed","items":[{"id":"item_1","type":"agentMessage","text":"你好"}]}}}'
+      exit 0
+      ;;
+  esac
+done
+`)
+	fwd := &codexAppServerForwarder{
+		bin:      codex,
+		env:      []string{"CODEX_STUB_LOG=" + logPath},
+		timeout:  5 * time.Second,
+		workDir:  dir,
+		sessions: newCodexThreadSessions(""),
+	}
+
+	var deltas []string
+	reply, err := fwd.forwardStream(context.Background(), "conv-1", "第一问", func(s string) {
+		deltas = append(deltas, s)
+	})
+	if err != nil {
+		t.Fatalf("first forward: %v", err)
+	}
+	if reply != "你好" {
+		t.Fatalf("first reply = %q, want 你好", reply)
+	}
+	if strings.Join(deltas, "|") != "你|你好" {
+		t.Fatalf("deltas = %v, want [你 你好]", deltas)
+	}
+
+	if _, err := fwd.forwardStream(context.Background(), "conv-1", "第二问", nil); err != nil {
+		t.Fatalf("second forward: %v", err)
+	}
+	logBytes, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	log := string(logBytes)
+	if strings.Count(log, `"method":"thread/start"`) != 1 {
+		t.Fatalf("expected one thread/start, log:\n%s", log)
+	}
+	if strings.Count(log, `"method":"thread/resume"`) != 1 {
+		t.Fatalf("expected one thread/resume, log:\n%s", log)
+	}
+}
+
+func TestCodexAppServerForwarderReturnsAppServerError(t *testing.T) {
+	dir := t.TempDir()
+	codex := writeShellExecutable(t, dir, "codex", `
+while IFS= read -r line; do
+  case "$line" in
+    *\"method\":\"initialize\"*)
+      printf '%s\n' '{"id":1,"error":{"code":123,"message":"app-server-broken"}}'
+      exit 0
+      ;;
+  esac
+done
+`)
+	fwd := &codexAppServerForwarder{
+		bin:     codex,
+		timeout: 10 * time.Second,
+		workDir: dir,
+	}
+
+	reply, err := fwd.forward(context.Background(), "conv-1", "hello")
+	if err == nil {
+		t.Fatal("forward should return the app-server error instead of falling back to exec")
+	}
+	if reply != "" {
+		t.Fatalf("reply = %q, want empty reply on app-server error", reply)
+	}
+	if !strings.Contains(err.Error(), "app-server-broken") {
+		t.Fatalf("error = %v, want app-server-broken", err)
+	}
+}
+
+func TestCodexAppServerReadLoopStopsWhenClosedWithFullQueue(t *testing.T) {
+	reader, writer := io.Pipe()
+	c := &codexAppServerClient{
+		msgs:    make(chan codexRPCMessage, 1),
+		readErr: make(chan error, 1),
+		done:    make(chan struct{}),
+	}
+
+	loopDone := make(chan struct{})
+	go func() {
+		defer close(loopDone)
+		c.readLoop(reader)
+	}()
+
+	writerDone := make(chan struct{})
+	go func() {
+		defer close(writerDone)
+		for i := 0; i < 200; i++ {
+			if _, err := fmt.Fprintf(writer, `{"method":"event/%d","params":{}}`+"\n", i); err != nil {
+				return
+			}
+		}
+	}()
+
+	deadline := time.Now().Add(time.Second)
+	for len(c.msgs) == 0 && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	if len(c.msgs) == 0 {
+		t.Fatal("readLoop did not enqueue the first message")
+	}
+
+	close(c.done)
+	_ = reader.Close()
+	_ = writer.Close()
+	select {
+	case <-loopDone:
+	case <-time.After(time.Second):
+		t.Fatal("readLoop did not stop after client close")
+	}
+	select {
+	case <-writerDone:
+	case <-time.After(time.Second):
+		t.Fatal("writer stayed blocked after pipe close")
+	}
+}
+
+func TestLockedBufferConcurrentReadWrite(t *testing.T) {
+	var b lockedBuffer
+	stop := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+				_, _ = b.Write([]byte("stderr\n"))
+			}
+		}
+	}()
+
+	for i := 0; i < 1000; i++ {
+		_ = b.String()
+	}
+	close(stop)
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("writer did not stop")
+	}
+}
+
+func TestCodexTurnCompletedText(t *testing.T) {
+	final, status, errMsg, ok := codexTurnCompletedText([]byte(`{"threadId":"thr","turn":{"status":"completed","items":[{"type":"agentMessage","text":"早"},{"type":"agentMessage","text":"最终"}]}}`), "thr")
+	if !ok || status != "completed" || final != "最终" || errMsg != "" {
+		t.Fatalf("completed = (%q,%q,%q,%v)", final, status, errMsg, ok)
+	}
+
+	_, status, errMsg, ok = codexTurnCompletedText([]byte(`{"threadId":"thr","turn":{"status":"failed","error":{"message":"boom","additionalDetails":"detail"},"items":[]}}`), "thr")
+	if !ok || status != "failed" || errMsg != "boom: detail" {
+		t.Fatalf("failed = (%q,%q,%v)", status, errMsg, ok)
+	}
+}

internal/helpers/connect_codex_sessions_test.go

@@ -0,0 +1,68 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// TestCodexThreadSessionsPersist verifies that a codex conversation's thread
+// survives a connector restart: a second store opened on the same path restores
+// the convID→threadID mapping, and a reset is persisted too.
+func TestCodexThreadSessionsPersist(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "codex-threads.json")
+
+	s := newCodexThreadSessions(path)
+	if got := s.threadID("conv-1"); got != "" {
+		t.Fatalf("fresh store threadID = %q, want empty", got)
+	}
+	s.setThreadID("conv-1", "thr_a")
+	s.setThreadID("conv-2", "thr_b")
+
+	// Simulate a restart: a new store on the same path must restore both.
+	restarted := newCodexThreadSessions(path)
+	if got := restarted.threadID("conv-1"); got != "thr_a" {
+		t.Errorf("after restart conv-1 = %q, want thr_a", got)
+	}
+	if got := restarted.threadID("conv-2"); got != "thr_b" {
+		t.Errorf("after restart conv-2 = %q, want thr_b", got)
+	}
+
+	// Reset is persisted: the dropped thread must not resurrect on restart.
+	restarted.reset("conv-1")
+	again := newCodexThreadSessions(path)
+	if got := again.threadID("conv-1"); got != "" {
+		t.Errorf("after reset+restart conv-1 = %q, want empty", got)
+	}
+	if got := again.threadID("conv-2"); got != "thr_b" {
+		t.Errorf("after reset+restart conv-2 = %q, want thr_b (untouched)", got)
+	}
+}
+
+// TestCodexThreadSessionsInMemory verifies that an empty path keeps the store
+// purely in memory: it still works within the process but writes nothing to
+// disk, preserving the pre-persistence behaviour.
+func TestCodexThreadSessionsInMemory(t *testing.T) {
+	s := newCodexThreadSessions("")
+	s.setThreadID("conv-1", "thr_a")
+	if got := s.threadID("conv-1"); got != "thr_a" {
+		t.Errorf("in-memory conv-1 = %q, want thr_a", got)
+	}
+	// A separate in-memory store shares no state (nothing was persisted).
+	other := newCodexThreadSessions("")
+	if got := other.threadID("conv-1"); got != "" {
+		t.Errorf("separate in-memory store conv-1 = %q, want empty", got)
+	}
+}

internal/helpers/connect_command.go

@@ -0,0 +1,68 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import "strings"
+
+// connectControlAction is a built-in slash command a user can type in the chat
+// to control the connector's per-conversation session, instead of a message
+// that gets forwarded to the agent. Modelled on codex / OpenClaw connect's
+// preset commands: the set is fixed (never dynamically extended) so the bot's
+// behaviour stays predictable.
+type connectControlAction struct {
+	// name is the canonical action ("new" | "clear"). Both reset the current
+	// conversation's session today (the next message starts fresh with no prior
+	// context), but they stay distinct actions so the ack wording can differ and
+	// a future channel can diverge their behaviour.
+	name string
+	// ack is the user-facing confirmation sent back into the chat (Chinese, for
+	// DingTalk users). It is never forwarded to the agent.
+	ack string
+}
+
+// resetsSession reports whether this action should drop the conversation's
+// agent session. Both built-in commands do today; kept as a predicate so adding
+// a non-resetting command later does not require touching the call site.
+func (a connectControlAction) resetsSession() bool {
+	return a.name == "new" || a.name == "clear"
+}
+
+// connectControlCommands maps the recognised slash tokens to their action. The
+// map is the single source of truth for "which commands exist" — both the
+// parser and any help text should read from it. "/new", "/start" and "/reset"
+// are aliases for opening a fresh session; "/clear" wipes the current one.
+var connectControlCommands = map[string]connectControlAction{
+	"/new":   {name: "new", ack: "🆕 已为你开启新会话，之前的上下文不再带入。"},
+	"/start": {name: "new", ack: "🆕 已为你开启新会话，之前的上下文不再带入。"},
+	"/reset": {name: "new", ack: "🆕 已为你开启新会话，之前的上下文不再带入。"},
+	"/clear": {name: "clear", ack: "🧹 已清空当前对话的上下文，我们从头开始。"},
+}
+
+// parseConnectControlCommand recognises a built-in slash command. It only
+// matches when the WHOLE trimmed message is exactly one known token (case
+// insensitive), so a normal question that merely starts with a slash — e.g.
+// "/new 这个功能怎么实现?" — is forwarded to the agent untouched rather than
+// silently swallowed as a command. Returns (action, true) on a match.
+func parseConnectControlCommand(text string) (connectControlAction, bool) {
+	token := strings.ToLower(strings.TrimSpace(text))
+	if token == "" || !strings.HasPrefix(token, "/") {
+		return connectControlAction{}, false
+	}
+	// A command is a bare token: reject anything carrying arguments/whitespace.
+	if strings.ContainsAny(token, " \t\n") {
+		return connectControlAction{}, false
+	}
+	action, ok := connectControlCommands[token]
+	return action, ok
+}

internal/helpers/connect_command_test.go

@@ -0,0 +1,67 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import "testing"
+
+func TestParseConnectControlCommand(t *testing.T) {
+	cases := []struct {
+		in       string
+		wantName string // "" means no match
+	}{
+		// Recognised commands and their aliases.
+		{"/new", "new"},
+		{"/start", "new"},
+		{"/reset", "new"},
+		{"/clear", "clear"},
+		// Case-insensitive and trimmed.
+		{"/NEW", "new"},
+		{"  /Clear  ", "clear"},
+		{"/New\n", "new"},
+		// A normal question that merely starts with a slash is NOT a command —
+		// it must be forwarded to the agent, not swallowed.
+		{"/new 这个功能怎么实现?", ""},
+		{"/clear the cache please", ""},
+		{"/new x", ""},
+		// Non-commands.
+		{"", ""},
+		{"   ", ""},
+		{"你好", ""},
+		{"new", ""},      // missing slash
+		{"/unknown", ""}, // unknown token
+		{"/", ""},
+	}
+	for _, c := range cases {
+		got, ok := parseConnectControlCommand(c.in)
+		if c.wantName == "" {
+			if ok {
+				t.Errorf("parseConnectControlCommand(%q) = (%+v, true), want no match", c.in, got)
+			}
+			continue
+		}
+		if !ok {
+			t.Errorf("parseConnectControlCommand(%q) = no match, want name %q", c.in, c.wantName)
+			continue
+		}
+		if got.name != c.wantName {
+			t.Errorf("parseConnectControlCommand(%q).name = %q, want %q", c.in, got.name, c.wantName)
+		}
+		if got.ack == "" {
+			t.Errorf("parseConnectControlCommand(%q).ack is empty, want a user-facing confirmation", c.in)
+		}
+		if !got.resetsSession() {
+			t.Errorf("parseConnectControlCommand(%q).resetsSession() = false, want true", c.in)
+		}
+	}
+}

internal/helpers/connect_daemon.go

@@ -0,0 +1,536 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/spf13/cobra"
+)
+
+// connect_daemon turns the foreground `robot connect` connector into a 7x24
+// background service. Three responsibilities live here and nowhere else (the
+// forwarding/session/knowledge logic in devapp_connect.go and connect_stream.go
+// is untouched):
+//
+//  1. detach: `connect --daemon` re-execs dws in supervisor mode in a new
+//     session (POSIX setsid), prints pid + log path, and exits.
+//  2. supervise: the supervisor process runs the real connector as a worker
+//     child and restarts it with exponential backoff when it crashes.
+//  3. status/stop: read the daemon pid file, probe liveness (reusing
+//     processAlive from connect_lock.go), and signal a graceful stop.
+//
+// Two hidden internal flags select the mode of a re-exec:
+//
+//	--daemon-supervise : run the supervisor loop (set by the --daemon parent)
+//	--daemon-worker    : run a single foreground connector (set by the supervisor)
+const (
+	daemonSuperviseFlag = "daemon-supervise"
+	daemonWorkerFlag    = "daemon-worker"
+	daemonFlag          = "daemon"
+)
+
+// daemonState is the JSON persisted to the daemon pid file. It records the
+// supervisor pid plus enough context for `status` to report without re-deriving
+// it (start time for uptime, log path, the dir key it was filed under).
+type daemonState struct {
+	Pid       int    `json:"pid"`
+	StartUnix int64  `json:"startUnix"`
+	LogPath   string `json:"logPath"`
+	DirKey    string `json:"dirKey"`
+	ClientID  string `json:"clientId,omitempty"`
+}
+
+// connectDaemonDirOverride lets tests redirect the per-client daemon directory
+// away from the real ~/.dws tree. Empty means use config.DefaultConfigDir.
+var connectDaemonDirOverride string
+
+// daemonDirKey derives a filesystem-safe directory key identifying a connector.
+// Priority: clientId (the robot's AppKey, the natural identity) > unifiedAppID.
+// Reuses sanitizeLockID (connect_lock.go) so the key matches the lock naming
+// convention. Returns "" when neither is available.
+func daemonDirKey(clientID, unifiedAppID string) string {
+	if v := strings.TrimSpace(clientID); v != "" {
+		return sanitizeLockID(v)
+	}
+	if v := strings.TrimSpace(unifiedAppID); v != "" {
+		return "app-" + sanitizeLockID(v)
+	}
+	return ""
+}
+
+// connectDaemonDir returns <configDir>/connect/<dirKey>, creating it. This holds
+// daemon.pid and daemon.log for one connector.
+func connectDaemonDir(dirKey string) (string, error) {
+	base := connectDaemonDirOverride
+	if base == "" {
+		base = config.DefaultConfigDir()
+	}
+	dir := filepath.Join(base, "connect", dirKey)
+	if err := os.MkdirAll(dir, config.DirPerm); err != nil {
+		return "", err
+	}
+	return dir, nil
+}
+
+func daemonPidPath(dir string) string { return filepath.Join(dir, "daemon.pid") }
+func daemonLogPath(dir string) string { return filepath.Join(dir, "daemon.log") }
+
+// writeDaemonState atomically persists the daemon pid file (write temp + rename)
+// so a reader never sees a half-written file.
+func writeDaemonState(dir string, st daemonState) error {
+	data, err := json.MarshalIndent(st, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := daemonPidPath(dir) + ".tmp"
+	if err := os.WriteFile(tmp, data, config.FilePerm); err != nil {
+		return err
+	}
+	return os.Rename(tmp, daemonPidPath(dir))
+}
+
+// readDaemonState loads the daemon pid file. A missing file yields (nil, nil) so
+// callers can treat "not running" distinctly from a real I/O error.
+func readDaemonState(dir string) (*daemonState, error) {
+	data, err := os.ReadFile(daemonPidPath(dir))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	var st daemonState
+	if err := json.Unmarshal(data, &st); err != nil {
+		return nil, fmt.Errorf("daemon pid file %s is corrupt: %w", daemonPidPath(dir), err)
+	}
+	return &st, nil
+}
+
+// backoffDelay computes the restart delay for the Nth consecutive worker
+// failure: base * 2^(n-1) capped at cap. Pure and unit-tested. n<=0 returns 0
+// (first start is immediate). Caller resets n when a worker stays healthy.
+func backoffDelay(consecutiveFailures int, base, maxDelay time.Duration) time.Duration {
+	if consecutiveFailures <= 0 {
+		return 0
+	}
+	d := base
+	for i := 1; i < consecutiveFailures; i++ {
+		d *= 2
+		if d >= maxDelay {
+			return maxDelay
+		}
+	}
+	if d > maxDelay {
+		return maxDelay
+	}
+	return d
+}
+
+const (
+	daemonBackoffBase = time.Second
+	daemonBackoffCap  = 60 * time.Second
+	// daemonMaxFastFailures is the consecutive fast-failure ceiling: after this
+	// many crashes that each happened within daemonHealthyAfter, the supervisor
+	// gives up rather than spin forever (e.g. bad credentials).
+	daemonMaxFastFailures = 10
+	// daemonHealthyAfter is how long a worker must run before the supervisor
+	// considers it healthy and resets the failure counter.
+	daemonHealthyAfter = 60 * time.Second
+	// daemonStopTimeout bounds the graceful wait in `stop` before SIGKILL.
+	daemonStopTimeout = 10 * time.Second
+)
+
+// buildWorkerArgs rewrites the supervisor's own argv into a worker argv: it
+// strips the daemon-control flags (--daemon / --daemon-supervise) and appends
+// --daemon-worker, preserving every other flag (credentials, channel, knowledge,
+// etc.) so the worker connects exactly as the foreground command would. Pure for
+// unit testing.
+func buildWorkerArgs(args []string) []string {
+	out := make([]string, 0, len(args)+1)
+	for _, a := range args {
+		switch {
+		case a == "--"+daemonFlag, a == "--"+daemonSuperviseFlag, a == "--"+daemonWorkerFlag:
+			continue
+		case strings.HasPrefix(a, "--"+daemonFlag+"="),
+			strings.HasPrefix(a, "--"+daemonSuperviseFlag+"="),
+			strings.HasPrefix(a, "--"+daemonWorkerFlag+"="):
+			continue
+		}
+		out = append(out, a)
+	}
+	out = append(out, "--"+daemonWorkerFlag)
+	return out
+}
+
+// startDaemon implements `connect --daemon`: it re-execs dws in supervisor mode
+// detached from the terminal, writes nothing itself to the worker log (the
+// supervisor does), prints the pid + log path, and returns so the parent exits.
+func startDaemon(cmd *cobra.Command, dirKey, clientID string) error {
+	if !daemonDetachSupported {
+		return apperrors.NewValidation("--daemon is not supported on this OS; run the foreground connector under a service manager instead")
+	}
+	dir, err := connectDaemonDir(dirKey)
+	if err != nil {
+		return apperrors.NewInternal("create daemon dir: " + err.Error())
+	}
+	// Refuse to start a second supervisor for the same connector. The Stream
+	// single-instance lock would also catch this at the worker layer, but a
+	// pre-flight check gives a clearer message and avoids an orphaned supervisor.
+	if st, _ := readDaemonState(dir); st != nil && st.Pid > 0 && processAlive(st.Pid) {
+		return apperrors.NewValidation(fmt.Sprintf("a connect daemon is already running for %s (pid %d); use `robot connect status`/`stop`", dirKey, st.Pid))
+	}
+
+	exe, err := os.Executable()
+	if err != nil {
+		return apperrors.NewInternal("resolve executable: " + err.Error())
+	}
+	superviseArgs := buildSuperviseArgs(os.Args[1:])
+
+	logPath := daemonLogPath(dir)
+	logFile, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, config.FilePerm)
+	if err != nil {
+		return apperrors.NewInternal("open daemon log: " + err.Error())
+	}
+	defer logFile.Close()
+
+	child := exec.Command(exe, superviseArgs...)
+	child.Stdout = logFile
+	child.Stderr = logFile
+	child.Stdin = nil
+	// Pass the resolved dir key + clientId through the environment so the
+	// supervisor files its pid under the same key the parent computed (rather
+	// than re-deriving and risking a mismatch).
+	child.Env = append(os.Environ(),
+		"DWS_CONNECT_DAEMON_DIRKEY="+dirKey,
+		"DWS_CONNECT_DAEMON_CLIENTID="+clientID,
+	)
+	if connectDaemonDirOverride != "" {
+		child.Env = append(child.Env, "DWS_CONNECT_DAEMON_DIR="+connectDaemonDirOverride)
+	}
+	applyDetach(child)
+
+	if err := child.Start(); err != nil {
+		return apperrors.NewInternal("start daemon: " + err.Error())
+	}
+	// Release the child so the parent can exit without leaving a zombie.
+	pid := child.Process.Pid
+	_ = child.Process.Release()
+
+	writeConnectDaemonStarted(cmd.OutOrStdout(), pid, logPath, clientID, dirKey)
+	return nil
+}
+
+func writeConnectDaemonStarted(w io.Writer, pid int, logPath, clientID, dirKey string) {
+	fmt.Fprintf(w, "connect daemon started (pid %d)\n", pid)
+	fmt.Fprintf(w, "  logs:   %s\n", logPath)
+	fmt.Fprintf(w, "  status: dws devapp robot connect status%s\n", statusHintArgs(clientID, dirKey))
+	fmt.Fprintf(w, "  stop:   dws devapp robot connect stop%s\n", statusHintArgs(clientID, dirKey))
+	fmt.Fprint(w, connectLocalDebugNotice())
+}
+
+// buildSuperviseArgs rewrites argv to run the supervisor: strip --daemon, append
+// --daemon-supervise. Pure for testing.
+func buildSuperviseArgs(args []string) []string {
+	out := make([]string, 0, len(args)+1)
+	for _, a := range args {
+		if a == "--"+daemonFlag || strings.HasPrefix(a, "--"+daemonFlag+"=") {
+			continue
+		}
+		out = append(out, a)
+	}
+	out = append(out, "--"+daemonSuperviseFlag)
+	return out
+}
+
+func statusHintArgs(clientID, dirKey string) string {
+	if strings.TrimSpace(clientID) != "" {
+		return " --robot-client-id " + clientID
+	}
+	if strings.HasPrefix(dirKey, "app-") {
+		return " --unified-app-id " + strings.TrimPrefix(dirKey, "app-")
+	}
+	return ""
+}
+
+// runSupervisor is the entry point when dws is started with --daemon-supervise.
+// It writes the daemon pid file, then loops launching the worker child and
+// restarting it with backoff until told to stop (SIGTERM/SIGINT) or it exhausts
+// the fast-failure budget. On stop it forwards the signal to the worker, waits,
+// and removes its pid file.
+func runSupervisor(cmd *cobra.Command) error {
+	dirKey := strings.TrimSpace(os.Getenv("DWS_CONNECT_DAEMON_DIRKEY"))
+	if dirKey == "" {
+		return apperrors.NewInternal("supervisor started without DWS_CONNECT_DAEMON_DIRKEY")
+	}
+	if v := strings.TrimSpace(os.Getenv("DWS_CONNECT_DAEMON_DIR")); v != "" {
+		connectDaemonDirOverride = v
+	}
+	clientID := strings.TrimSpace(os.Getenv("DWS_CONNECT_DAEMON_CLIENTID"))
+	dir, err := connectDaemonDir(dirKey)
+	if err != nil {
+		return apperrors.NewInternal("create daemon dir: " + err.Error())
+	}
+	st := daemonState{
+		Pid:       os.Getpid(),
+		StartUnix: time.Now().Unix(),
+		LogPath:   daemonLogPath(dir),
+		DirKey:    dirKey,
+		ClientID:  clientID,
+	}
+	if err := writeDaemonState(dir, st); err != nil {
+		return apperrors.NewInternal("write daemon pid file: " + err.Error())
+	}
+	defer os.Remove(daemonPidPath(dir))
+
+	// Route worker stdout/stderr through the shared size-rotating writer
+	// (logging.NewRotatingFile) so a long-running connector's logs don't grow
+	// unbounded. The detached parent already redirected our own fds to the same
+	// daemon.log; from here we append through the rotator. Fall back to stderr if
+	// the rotator can't be opened.
+	var out io.Writer = cmd.ErrOrStderr()
+	if rot, rerr := logging.NewRotatingFile(daemonLogPath(dir)); rerr == nil {
+		defer rot.Close()
+		out = rot
+	}
+
+	// The supervisor reacts to SIGTERM/SIGINT itself (cmd.Context from root is
+	// already wired to these). We use an independent NotifyContext so cancelling
+	// it stops the loop and lets us forward the signal to the worker explicitly.
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	workerArgs := buildWorkerArgs(os.Args[1:])
+	exe, err := os.Executable()
+	if err != nil {
+		return apperrors.NewInternal("resolve executable: " + err.Error())
+	}
+
+	failures := 0
+	for {
+		if delay := backoffDelay(failures, daemonBackoffBase, daemonBackoffCap); delay > 0 {
+			fmt.Fprintf(out, "[daemon] restarting worker in %s (consecutive failures: %d)\n", delay, failures)
+			select {
+			case <-ctx.Done():
+				return nil
+			case <-time.After(delay):
+			}
+		}
+		if ctx.Err() != nil {
+			return nil
+		}
+
+		started := time.Now()
+		worker := exec.Command(exe, workerArgs...)
+		worker.Stdout = out
+		worker.Stderr = out
+		worker.Env = os.Environ()
+		if err := worker.Start(); err != nil {
+			fmt.Fprintf(out, "[daemon] failed to start worker: %v\n", err)
+			failures++
+			if failures >= daemonMaxFastFailures {
+				return apperrors.NewInternal("daemon worker failed to start too many times; giving up")
+			}
+			continue
+		}
+		fmt.Fprintf(out, "[daemon] worker started (pid %d)\n", worker.Process.Pid)
+
+		waitErr := superviseWait(ctx, worker)
+		ran := time.Since(started)
+
+		if ctx.Err() != nil {
+			// We were asked to stop; the worker has been (or is being) signalled.
+			fmt.Fprintln(out, "[daemon] stop requested, worker shut down; exiting supervisor")
+			return nil
+		}
+
+		if ran >= daemonHealthyAfter {
+			failures = 0
+		} else {
+			failures++
+		}
+		fmt.Fprintf(out, "[daemon] worker exited after %s (err=%v); consecutive failures: %d\n", ran.Round(time.Second), waitErr, failures)
+		if failures >= daemonMaxFastFailures {
+			return apperrors.NewInternal(fmt.Sprintf("daemon worker crashed %d times in a row; giving up (check %s)", failures, daemonLogPath(dir)))
+		}
+	}
+}
+
+// superviseWait waits for the worker to exit, but if the supervisor's ctx is
+// cancelled first it forwards SIGTERM to the worker for a graceful shutdown
+// (releasing the Stream single-instance lock) and then waits.
+func superviseWait(ctx context.Context, worker *exec.Cmd) error {
+	done := make(chan error, 1)
+	go func() { done <- worker.Wait() }()
+	select {
+	case err := <-done:
+		return err
+	case <-ctx.Done():
+		_ = worker.Process.Signal(syscall.SIGTERM)
+		select {
+		case err := <-done:
+			return err
+		case <-time.After(daemonStopTimeout):
+			_ = worker.Process.Kill()
+			return <-done
+		}
+	}
+}
+
+// daemonStatus reports the state of the connector daemon to w.
+func daemonStatus(w io.Writer, dirKey string) error {
+	dir, err := connectDaemonDir(dirKey)
+	if err != nil {
+		return apperrors.NewInternal("resolve daemon dir: " + err.Error())
+	}
+	st, err := readDaemonState(dir)
+	if err != nil {
+		return apperrors.NewInternal(err.Error())
+	}
+	if st == nil {
+		fmt.Fprintf(w, "connect daemon: not running (no pid file under %s)\n", dir)
+		return nil
+	}
+	if st.Pid <= 0 || !processAlive(st.Pid) {
+		fmt.Fprintf(w, "connect daemon: not running (stale pid file for pid %d at %s)\n", st.Pid, daemonPidPath(dir))
+		return nil
+	}
+	uptime := time.Since(time.Unix(st.StartUnix, 0)).Round(time.Second)
+	fmt.Fprintf(w, "connect daemon: running\n")
+	fmt.Fprintf(w, "  pid:     %d\n", st.Pid)
+	fmt.Fprintf(w, "  uptime:  %s\n", uptime)
+	fmt.Fprintf(w, "  logs:    %s\n", st.LogPath)
+	if st.ClientID != "" {
+		fmt.Fprintf(w, "  client:  %s\n", st.ClientID)
+	}
+	return nil
+}
+
+// daemonStop gracefully stops the connector daemon: SIGTERM the supervisor (it
+// forwards to the worker, which releases the lock and Stream connection), poll
+// until it exits, escalate to SIGKILL on timeout, and clean up the pid file.
+func daemonStop(w io.Writer, dirKey string) error {
+	dir, err := connectDaemonDir(dirKey)
+	if err != nil {
+		return apperrors.NewInternal("resolve daemon dir: " + err.Error())
+	}
+	st, err := readDaemonState(dir)
+	if err != nil {
+		return apperrors.NewInternal(err.Error())
+	}
+	if st == nil || st.Pid <= 0 {
+		fmt.Fprintf(w, "connect daemon: not running (nothing to stop)\n")
+		return nil
+	}
+	if !processAlive(st.Pid) {
+		_ = os.Remove(daemonPidPath(dir))
+		fmt.Fprintf(w, "connect daemon: was not running (cleaned up stale pid file for pid %d)\n", st.Pid)
+		return nil
+	}
+	proc, err := os.FindProcess(st.Pid)
+	if err != nil {
+		return apperrors.NewInternal(fmt.Sprintf("find daemon process %d: %v", st.Pid, err))
+	}
+	if err := proc.Signal(syscall.SIGTERM); err != nil {
+		return apperrors.NewInternal(fmt.Sprintf("signal daemon %d: %v", st.Pid, err))
+	}
+	fmt.Fprintf(w, "sent SIGTERM to connect daemon (pid %d), waiting for graceful stop...\n", st.Pid)
+
+	deadline := time.Now().Add(daemonStopTimeout)
+	for time.Now().Before(deadline) {
+		if !processAlive(st.Pid) {
+			_ = os.Remove(daemonPidPath(dir))
+			fmt.Fprintf(w, "connect daemon stopped (pid %d)\n", st.Pid)
+			return nil
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+	// Graceful window elapsed; force kill.
+	_ = proc.Signal(syscall.SIGKILL)
+	time.Sleep(200 * time.Millisecond)
+	_ = os.Remove(daemonPidPath(dir))
+	fmt.Fprintf(w, "connect daemon did not stop in %s; sent SIGKILL (pid %d)\n", daemonStopTimeout, st.Pid)
+	return nil
+}
+
+// newDevAppRobotConnectStatusCommand implements `dws devapp robot connect
+// status`: report whether a background connector daemon is running for the
+// robot identified by --robot-client-id (or --unified-app-id).
+func newDevAppRobotConnectStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "status",
+		Short:             "查看后台连接器守护进程状态（pid、运行时长、日志路径）",
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			dirKey, err := connectDaemonDirKeyFromFlags(cmd)
+			if err != nil {
+				return err
+			}
+			return daemonStatus(cmd.OutOrStdout(), dirKey)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("robot-client-id", "", "机器人 clientId（定位守护进程）")
+	cmd.Flags().String("unified-app-id", "", "统一应用 ID（当未用 clientId 起守护进程时定位）")
+	return cmd
+}
+
+// newDevAppRobotConnectStopCommand implements `dws devapp robot connect stop`:
+// gracefully stop the background connector daemon (SIGTERM, escalate to SIGKILL
+// on timeout) and clean up its pid file.
+func newDevAppRobotConnectStopCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "stop",
+		Short:             "优雅停止后台连接器守护进程（释放单实例锁与 Stream 连接）",
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			dirKey, err := connectDaemonDirKeyFromFlags(cmd)
+			if err != nil {
+				return err
+			}
+			return daemonStop(cmd.OutOrStdout(), dirKey)
+		},
+	}
+	preferLegacyLeaf(cmd)
+	cmd.Flags().String("robot-client-id", "", "机器人 clientId（定位守护进程）")
+	cmd.Flags().String("unified-app-id", "", "统一应用 ID（当未用 clientId 起守护进程时定位）")
+	return cmd
+}
+
+// connectDaemonDirKeyFromFlags resolves the daemon directory key from the
+// status/stop flags, requiring at least one identifier.
+func connectDaemonDirKeyFromFlags(cmd *cobra.Command) (string, error) {
+	clientID := devAppStringFlag(cmd, "robot-client-id")
+	unifiedAppID := devAppStringFlag(cmd, "unified-app-id")
+	dirKey := daemonDirKey(clientID, unifiedAppID)
+	if dirKey == "" {
+		return "", apperrors.NewValidation("需要 --robot-client-id 或 --unified-app-id 以定位守护进程")
+	}
+	return dirKey, nil
+}

internal/helpers/connect_daemon_test.go

@@ -0,0 +1,241 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"bytes"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestBackoffDelay(t *testing.T) {
+	base := time.Second
+	cap := 60 * time.Second
+	cases := []struct {
+		failures int
+		want     time.Duration
+	}{
+		{0, 0},
+		{-1, 0},
+		{1, time.Second},
+		{2, 2 * time.Second},
+		{3, 4 * time.Second},
+		{4, 8 * time.Second},
+		{5, 16 * time.Second},
+		{6, 32 * time.Second},
+		{7, cap}, // 64s capped to 60s
+		{8, cap},
+		{100, cap},
+	}
+	for _, c := range cases {
+		if got := backoffDelay(c.failures, base, cap); got != c.want {
+			t.Errorf("backoffDelay(%d) = %v, want %v", c.failures, got, c.want)
+		}
+	}
+}
+
+func TestDaemonDirKey(t *testing.T) {
+	cases := []struct {
+		clientID     string
+		unifiedAppID string
+		want         string
+	}{
+		{"clientABC", "", "clientABC"},
+		{"client/with:bad*chars", "", "client_with_bad_chars"},
+		{"", "app-123", "app-app-123"},
+		{"", "u/n.id", "app-u_n_id"},
+		{"  ", "  ", ""},
+		{"cid", "uid", "cid"}, // clientID wins
+	}
+	for _, c := range cases {
+		if got := daemonDirKey(c.clientID, c.unifiedAppID); got != c.want {
+			t.Errorf("daemonDirKey(%q,%q) = %q, want %q", c.clientID, c.unifiedAppID, got, c.want)
+		}
+	}
+}
+
+func TestBuildWorkerArgs(t *testing.T) {
+	in := []string{"devapp", "robot", "connect", "--daemon", "--robot-client-id", "abc", "--channel=claudecode"}
+	got := buildWorkerArgs(in)
+	joined := strings.Join(got, " ")
+	if strings.Contains(joined, "--daemon ") || strings.HasSuffix(joined, "--daemon") {
+		// only the appended --daemon-worker may contain "daemon"
+	}
+	if !strings.HasSuffix(joined, "--daemon-worker") {
+		t.Errorf("worker args must end with --daemon-worker, got %q", joined)
+	}
+	for _, a := range got[:len(got)-1] {
+		if a == "--daemon" || a == "--daemon-supervise" || a == "--daemon-worker" {
+			t.Errorf("daemon-control flag leaked into worker args: %q", a)
+		}
+	}
+	if !strings.Contains(joined, "--robot-client-id abc") || !strings.Contains(joined, "--channel=claudecode") {
+		t.Errorf("credential/channel flags must be preserved, got %q", joined)
+	}
+}
+
+func TestBuildSuperviseArgs(t *testing.T) {
+	in := []string{"devapp", "robot", "connect", "--daemon", "--robot-client-id", "abc"}
+	got := buildSuperviseArgs(in)
+	joined := strings.Join(got, " ")
+	if !strings.HasSuffix(joined, "--daemon-supervise") {
+		t.Errorf("supervise args must end with --daemon-supervise, got %q", joined)
+	}
+	if strings.Contains(joined, " --daemon ") || strings.Contains(joined, " --daemon\b") {
+		t.Errorf("--daemon should be stripped, got %q", joined)
+	}
+	for _, a := range got[:len(got)-1] {
+		if a == "--daemon" {
+			t.Errorf("--daemon leaked into supervise args: %q", a)
+		}
+	}
+}
+
+func TestWriteConnectDaemonStartedIncludesLocalDebugNotice(t *testing.T) {
+	var buf bytes.Buffer
+	writeConnectDaemonStarted(&buf, 1234, "/tmp/daemon.log", "cid", "cid")
+	out := buf.String()
+	for _, want := range []string{"connect daemon started", "/tmp/daemon.log", "本地调试", "不代表线上发布完成", "不会提交版本发布"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("daemon started output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestDaemonStateRoundTrip(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+
+	dir, err := connectDaemonDir("roundtrip")
+	if err != nil {
+		t.Fatalf("connectDaemonDir: %v", err)
+	}
+	// No file yet → nil, nil.
+	if st, err := readDaemonState(dir); err != nil || st != nil {
+		t.Fatalf("expected (nil,nil) for missing pid file, got (%v,%v)", st, err)
+	}
+	want := daemonState{Pid: 4242, StartUnix: time.Now().Unix(), LogPath: "/x/y.log", DirKey: "roundtrip", ClientID: "cid"}
+	if err := writeDaemonState(dir, want); err != nil {
+		t.Fatalf("writeDaemonState: %v", err)
+	}
+	got, err := readDaemonState(dir)
+	if err != nil || got == nil {
+		t.Fatalf("readDaemonState: (%v,%v)", got, err)
+	}
+	if got.Pid != want.Pid || got.DirKey != want.DirKey || got.ClientID != want.ClientID || got.LogPath != want.LogPath {
+		t.Errorf("round trip mismatch: got %+v want %+v", *got, want)
+	}
+}
+
+func TestReadDaemonStateCorrupt(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	dir, _ := connectDaemonDir("corrupt")
+	if err := os.WriteFile(daemonPidPath(dir), []byte("{not json"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readDaemonState(dir); err == nil {
+		t.Error("expected error for corrupt pid file")
+	}
+}
+
+func TestDaemonStatusNotRunning(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	var buf bytes.Buffer
+	if err := daemonStatus(&buf, "nope"); err != nil {
+		t.Fatalf("daemonStatus: %v", err)
+	}
+	if !strings.Contains(buf.String(), "not running") {
+		t.Errorf("expected 'not running', got %q", buf.String())
+	}
+}
+
+func TestDaemonStatusStalePid(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	dir, _ := connectDaemonDir("stale")
+	// pid that is essentially certain to be dead.
+	writeDaemonState(dir, daemonState{Pid: deadPid(t), StartUnix: time.Now().Unix(), LogPath: "/l", DirKey: "stale"})
+	var buf bytes.Buffer
+	if err := daemonStatus(&buf, "stale"); err != nil {
+		t.Fatalf("daemonStatus: %v", err)
+	}
+	if !strings.Contains(buf.String(), "stale pid file") {
+		t.Errorf("expected stale pid report, got %q", buf.String())
+	}
+}
+
+func TestDaemonStatusRunning(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	dir, _ := connectDaemonDir("live")
+	// Use our own pid: guaranteed alive.
+	writeDaemonState(dir, daemonState{Pid: os.Getpid(), StartUnix: time.Now().Add(-90 * time.Second).Unix(), LogPath: "/l.log", DirKey: "live", ClientID: "cidX"})
+	var buf bytes.Buffer
+	if err := daemonStatus(&buf, "live"); err != nil {
+		t.Fatalf("daemonStatus: %v", err)
+	}
+	out := buf.String()
+	for _, want := range []string{"running", "pid:", "uptime:", "/l.log", "cidX"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("status output missing %q; got %q", want, out)
+		}
+	}
+}
+
+func TestDaemonStopNotRunning(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	var buf bytes.Buffer
+	if err := daemonStop(&buf, "ghost"); err != nil {
+		t.Fatalf("daemonStop: %v", err)
+	}
+	if !strings.Contains(buf.String(), "not running") {
+		t.Errorf("expected 'not running', got %q", buf.String())
+	}
+}
+
+func TestDaemonStopStaleCleansPidFile(t *testing.T) {
+	connectDaemonDirOverride = t.TempDir()
+	t.Cleanup(func() { connectDaemonDirOverride = "" })
+	dir, _ := connectDaemonDir("stalestop")
+	writeDaemonState(dir, daemonState{Pid: deadPid(t), StartUnix: time.Now().Unix(), DirKey: "stalestop"})
+	var buf bytes.Buffer
+	if err := daemonStop(&buf, "stalestop"); err != nil {
+		t.Fatalf("daemonStop: %v", err)
+	}
+	if _, err := os.Stat(daemonPidPath(dir)); !os.IsNotExist(err) {
+		t.Errorf("stale pid file should be removed, stat err=%v", err)
+	}
+	if !strings.Contains(buf.String(), "stale") {
+		t.Errorf("expected stale cleanup message, got %q", buf.String())
+	}
+}
+
+// deadPid returns a pid that is not alive. It spawns `true`, waits for it to
+// exit, and returns its pid — guaranteed reaped and gone.
+func deadPid(t *testing.T) int {
+	t.Helper()
+	// A very high pid is almost never live; combine with a sanity probe.
+	for _, candidate := range []int{999999, 524287, 99999} {
+		if !processAlive(candidate) {
+			return candidate
+		}
+	}
+	t.Skip("could not find a guaranteed-dead pid on this host")
+	return 0
+}

internal/helpers/connect_daemon_unix.go

@@ -0,0 +1,38 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !windows
+
+package helpers
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+// daemonDetachSupported reports whether the current OS can detach a daemon.
+const daemonDetachSupported = true
+
+// detachSysProcAttr returns the SysProcAttr that detaches a child from the
+// controlling terminal: Setsid starts a new session so the child survives the
+// parent shell closing (no SIGHUP) and has no controlling tty. Used for the
+// `connect --daemon` re-exec. Unix-only; Windows uses the stub.
+func detachSysProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true}
+}
+
+// applyDetach configures cmd so it runs in its own session, detached from the
+// terminal.
+func applyDetach(cmd *exec.Cmd) {
+	cmd.SysProcAttr = detachSysProcAttr()
+}

internal/helpers/connect_daemon_windows.go

@@ -0,0 +1,27 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+package helpers
+
+import "os/exec"
+
+// daemonDetachSupported is false on Windows: the daemon uses POSIX setsid +
+// signal-based stop, which has no direct equivalent here. `connect --daemon`
+// errors out on Windows and users should run the foreground connector under a
+// Windows service wrapper instead.
+const daemonDetachSupported = false
+
+// applyDetach is a no-op on Windows; daemon mode is rejected earlier.
+func applyDetach(_ *exec.Cmd) {}

internal/helpers/connect_knowledge.go

@@ -0,0 +1,235 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"unicode"
+)
+
+// Lightweight local retrieval for the Q&A scenario: --knowledge-dir loads
+// .md/.txt files, chunks them, and prepends the best-matching chunks to each
+// forwarded question. The agent CLI itself keeps running from the clean
+// scratch dir — retrieval injects knowledge without the workdir-scan slowdown
+// that would miss DingTalk's AI-assistant reply window (the connector's core
+// latency constraint, see execForwarder.forward).
+const (
+	knowledgeTopK           = 3
+	knowledgeMaxChunkRunes  = 1200
+	knowledgeMaxPromptRunes = 3000
+	knowledgeMaxFileBytes   = 1 << 20
+)
+
+type knowledgeChunk struct {
+	source string
+	text   string
+	terms  map[string]int
+}
+
+type knowledgeBase struct {
+	chunks []knowledgeChunk
+}
+
+// loadKnowledgeBase walks dir for .md/.txt files (hidden dirs skipped) and
+// indexes them into scored-retrieval chunks.
+// knowledgeTextExts is the set of plain-text extensions the retriever indexes.
+var knowledgeTextExts = []string{".md", ".markdown", ".mdx", ".txt", ".text"}
+
+// isKnowledgeTextExt reports whether ext is an indexable plain-text extension.
+func isKnowledgeTextExt(ext string) bool {
+	ext = strings.ToLower(ext)
+	for _, e := range knowledgeTextExts {
+		if ext == e {
+			return true
+		}
+	}
+	return false
+}
+
+func loadKnowledgeBase(dir string) (*knowledgeBase, error) {
+	kb := &knowledgeBase{}
+	root := filepath.Clean(dir)
+	indexed, skipped := 0, 0
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if d.IsDir() {
+			if path != root && strings.HasPrefix(d.Name(), ".") {
+				return fs.SkipDir
+			}
+			return nil
+		}
+		if !isKnowledgeTextExt(filepath.Ext(path)) {
+			skipped++
+			return nil
+		}
+		if info, ierr := d.Info(); ierr == nil && info.Size() > knowledgeMaxFileBytes {
+			fmt.Fprintf(os.Stderr, "[connect][knowledge] 跳过超大文件 %s\n", path)
+			return nil
+		}
+		raw, rerr := os.ReadFile(path)
+		if rerr != nil {
+			return rerr
+		}
+		rel, _ := filepath.Rel(root, path)
+		for _, chunk := range splitKnowledgeChunks(string(raw)) {
+			kb.chunks = append(kb.chunks, knowledgeChunk{source: rel, text: chunk, terms: knowledgeTerms(chunk)})
+		}
+		indexed++
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	// Tell the operator when files were skipped — a knowledge dir full of .pdf /
+	// .docx / .json indexes nothing, which otherwise looks like "knowledge has no
+	// effect" (issue #32). Only the .md/.txt text family is indexed.
+	if skipped > 0 {
+		fmt.Fprintf(os.Stderr, "[connect][knowledge] 已索引 %d 个文本文件，跳过 %d 个非文本文件（仅索引 %s）\n",
+			indexed, skipped, strings.Join(knowledgeTextExts, "/"))
+	}
+	if len(kb.chunks) == 0 {
+		return nil, fmt.Errorf("知识目录 %s 下没有可用的文本内容（仅索引 %s；pdf/docx/json 等不会被索引）", dir, strings.Join(knowledgeTextExts, "/"))
+	}
+	return kb, nil
+}
+
+// splitKnowledgeChunks cuts a document on markdown headings, merging lines up
+// to knowledgeMaxChunkRunes so a chunk carries enough context to answer with.
+func splitKnowledgeChunks(doc string) []string {
+	var chunks []string
+	var cur []string
+	curLen := 0
+	flush := func() {
+		if s := strings.TrimSpace(strings.Join(cur, "\n")); s != "" {
+			chunks = append(chunks, s)
+		}
+		cur = cur[:0]
+		curLen = 0
+	}
+	for _, line := range strings.Split(doc, "\n") {
+		if strings.HasPrefix(strings.TrimSpace(line), "#") && curLen > 0 {
+			flush()
+		}
+		cur = append(cur, line)
+		curLen += len([]rune(line))
+		if curLen >= knowledgeMaxChunkRunes {
+			flush()
+		}
+	}
+	flush()
+	return chunks
+}
+
+// knowledgeTerms tokenizes for matching: lowercase latin/digit words (len>=2)
+// plus CJK bigrams — CJK has no word boundaries and bigrams are the standard
+// cheap approximation.
+func knowledgeTerms(s string) map[string]int {
+	terms := map[string]int{}
+	var word []rune
+	var prevCJK rune
+	flushWord := func() {
+		if len(word) >= 2 {
+			terms[strings.ToLower(string(word))]++
+		}
+		word = word[:0]
+	}
+	for _, r := range s {
+		switch {
+		case r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9':
+			word = append(word, r)
+			prevCJK = 0
+		case unicode.Is(unicode.Han, r):
+			flushWord()
+			if prevCJK != 0 {
+				terms[string([]rune{prevCJK, r})]++
+			}
+			prevCJK = r
+		default:
+			flushWord()
+			prevCJK = 0
+		}
+	}
+	flushWord()
+	return terms
+}
+
+// augment returns the prompt to forward: the original question, or the
+// question prefixed with the top-k matching knowledge chunks. No match means
+// no prefix — the agent answers from its own knowledge as before.
+func (kb *knowledgeBase) augment(question string) string {
+	if kb == nil || len(kb.chunks) == 0 {
+		return question
+	}
+	qTerms := knowledgeTerms(question)
+	if len(qTerms) == 0 {
+		return question
+	}
+	type scored struct {
+		idx  int
+		hits int // distinct query terms present
+		occ  int // total occurrences, tie-break
+	}
+	var matches []scored
+	for i, c := range kb.chunks {
+		hits, occ := 0, 0
+		for t := range qTerms {
+			if n := c.terms[t]; n > 0 {
+				hits++
+				occ += n
+			}
+		}
+		if hits > 0 {
+			matches = append(matches, scored{i, hits, occ})
+		}
+	}
+	if len(matches) == 0 {
+		// Observability for "knowledge has no effect" (issue #32): the KB loaded
+		// but nothing in it overlapped this question, so no context was injected.
+		fmt.Fprintf(os.Stderr, "[connect][knowledge] 本条未命中知识库（%d 个片段中无相关内容）\n", len(kb.chunks))
+		return question
+	}
+	sort.Slice(matches, func(a, b int) bool {
+		if matches[a].hits != matches[b].hits {
+			return matches[a].hits > matches[b].hits
+		}
+		return matches[a].occ > matches[b].occ
+	})
+	var b strings.Builder
+	b.WriteString("以下是本地知识库中可能相关的资料，请优先依据它们回答；与问题无关时忽略：\n")
+	used := 0
+	for k := 0; k < len(matches) && k < knowledgeTopK; k++ {
+		c := kb.chunks[matches[k].idx]
+		text := truncateRunes(c.text, knowledgeMaxChunkRunes)
+		used += len([]rune(text))
+		if k > 0 && used > knowledgeMaxPromptRunes {
+			break
+		}
+		fmt.Fprintf(&b, "\n【资料%d · %s】\n%s\n", k+1, c.source, text)
+	}
+	b.WriteString("\n用户问题：")
+	b.WriteString(question)
+	injected := len(matches)
+	if injected > knowledgeTopK {
+		injected = knowledgeTopK
+	}
+	fmt.Fprintf(os.Stderr, "[connect][knowledge] 本条命中并注入 %d 个知识片段\n", injected)
+	return b.String()
+}

internal/helpers/connect_knowledge_test.go

@@ -0,0 +1,154 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeKnowledgeDir(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	faq := `# 安装
+
+dws 通过 brew install dws 安装，升级用 dws upgrade。
+
+# 缓存问题
+
+出现幽灵命令或命令缺失时，运行 dws cache refresh 强制刷新发现配置缓存。
+`
+	bot := `# 机器人建联
+
+用 dws devapp robot create 建号，dws devapp robot connect 建联。
+卡片停在数据加载中说明回复超过了 AI 助理应答窗口。
+`
+	if err := os.WriteFile(filepath.Join(dir, "faq.md"), []byte(faq), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "bot.md"), []byte(bot), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Non-knowledge files are ignored.
+	if err := os.WriteFile(filepath.Join(dir, "logo.png"), []byte{0x89, 0x50}, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
+func TestKnowledgeBaseLoadAndChunk(t *testing.T) {
+	kb, err := loadKnowledgeBase(writeKnowledgeDir(t))
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	// faq.md has 2 heading-chunks, bot.md has 1.
+	if len(kb.chunks) != 3 {
+		t.Fatalf("chunks = %d, want 3", len(kb.chunks))
+	}
+}
+
+func TestKnowledgeAugmentPicksRelevantChunk(t *testing.T) {
+	kb, err := loadKnowledgeBase(writeKnowledgeDir(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := kb.augment("机器人卡在数据加载中怎么办")
+	if !strings.Contains(got, "AI 助理应答窗口") {
+		t.Fatalf("augment missed the bot chunk:\n%s", got)
+	}
+	if !strings.Contains(got, "用户问题：机器人卡在数据加载中怎么办") {
+		t.Fatalf("augment must keep the original question:\n%s", got)
+	}
+	if !strings.Contains(got, "bot.md") {
+		t.Fatalf("augment must cite the source file:\n%s", got)
+	}
+}
+
+func TestKnowledgeAugmentEnglishTerms(t *testing.T) {
+	kb, err := loadKnowledgeBase(writeKnowledgeDir(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := kb.augment("cache refresh 是干什么的")
+	if !strings.Contains(got, "强制刷新发现配置缓存") {
+		t.Fatalf("augment missed the cache chunk:\n%s", got)
+	}
+}
+
+func TestKnowledgeAugmentNoMatchPassesThrough(t *testing.T) {
+	kb, err := loadKnowledgeBase(writeKnowledgeDir(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	q := "qqqq zzzz xxxx"
+	if got := kb.augment(q); got != q {
+		t.Fatalf("no-match should pass through, got:\n%s", got)
+	}
+}
+
+func TestKnowledgeBaseEmptyDirErrors(t *testing.T) {
+	if _, err := loadKnowledgeBase(t.TempDir()); err == nil {
+		t.Fatal("empty dir should error so a typo'd --knowledge-dir is loud")
+	}
+}
+
+func TestKnowledgeNilBasePassesThrough(t *testing.T) {
+	var kb *knowledgeBase
+	if got := kb.augment("你好"); got != "你好" {
+		t.Fatalf("nil kb should pass through, got %q", got)
+	}
+}
+
+func TestIsKnowledgeTextExt(t *testing.T) {
+	for _, e := range []string{".md", ".MD", ".markdown", ".mdx", ".txt", ".text"} {
+		if !isKnowledgeTextExt(e) {
+			t.Fatalf("%q should be an indexable text ext", e)
+		}
+	}
+	for _, e := range []string{".pdf", ".docx", ".json", ".png", ""} {
+		if isKnowledgeTextExt(e) {
+			t.Fatalf("%q should NOT be indexable", e)
+		}
+	}
+}
+
+func TestKnowledgeBaseIndexesMarkdownFamily(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "a.markdown"), []byte("# 标题\n\n内容关于考勤制度的说明。"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "b.text"), []byte("纯文本资料一段。"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	kb, err := loadKnowledgeBase(dir)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if len(kb.chunks) == 0 {
+		t.Fatal(".markdown/.text should be indexed")
+	}
+}
+
+func TestKnowledgeBaseNoTextFilesError(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "doc.pdf"), []byte("%PDF-1.7"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, err := loadKnowledgeBase(dir)
+	if err == nil || !strings.Contains(err.Error(), "没有可用的文本内容") {
+		t.Fatalf("a dir with only non-text files should error clearly, got %v", err)
+	}
+}

internal/helpers/connect_knowledge_wiki.go

@@ -0,0 +1,463 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/spf13/cobra"
+)
+
+// connect_knowledge_wiki extends the local-file knowledge retriever
+// (connect_knowledge.go) to a DingTalk knowledge base (wiki) source. It does
+// NOT reimplement any DingTalk API call: it reuses the existing `doc` tools that
+// back `dws doc list` / `dws doc read` (list_nodes + get_document_content) via
+// the shared executor.Runner, dumps each document as markdown text, and feeds
+// that into the very same chunker/retriever the local-directory source uses.
+//
+// On startup the connector pulls the wiki space, caches it under
+// ~/.dws/connect/<clientId>/knowledge/wiki-<spaceId>/, and builds the knowledge
+// base from that directory. A pull failure (network / permission) degrades to a
+// stale cache if one exists, otherwise to an empty knowledge base — it never
+// blocks the connection.
+
+// knowledgeSourceKind classifies a --knowledge-source value.
+type knowledgeSourceKind int
+
+const (
+	// knowledgeSourceDir is a plain local directory (the legacy behavior, kept
+	// for any value without a recognized scheme prefix).
+	knowledgeSourceDir knowledgeSourceKind = iota
+	// knowledgeSourceWiki is a wiki:<spaceId> source — a whole knowledge space.
+	knowledgeSourceWiki
+	// knowledgeSourceDoc is a doc:<docId> source — a single document node.
+	knowledgeSourceDoc
+)
+
+type knowledgeSource struct {
+	kind knowledgeSourceKind
+	// ref is the directory path (dir), the spaceId (wiki) or the nodeId (doc).
+	ref string
+}
+
+// parseKnowledgeSource splits a --knowledge-source value into its kind and ref.
+// "wiki:<spaceId>" / "doc:<docId>" select the DingTalk knowledge base; anything
+// else (including bare paths) is treated as a local directory, so the legacy
+// --knowledge-dir semantics keep working when routed through here.
+func parseKnowledgeSource(raw string) (knowledgeSource, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return knowledgeSource{}, fmt.Errorf("empty knowledge source")
+	}
+	if rest, ok := cutKnowledgeScheme(value, "wiki"); ok {
+		if rest == "" {
+			return knowledgeSource{}, fmt.Errorf("knowledge source %q is missing a spaceId (expected wiki:<spaceId>)", raw)
+		}
+		return knowledgeSource{kind: knowledgeSourceWiki, ref: rest}, nil
+	}
+	if rest, ok := cutKnowledgeScheme(value, "doc"); ok {
+		if rest == "" {
+			return knowledgeSource{}, fmt.Errorf("knowledge source %q is missing a docId (expected doc:<docId>)", raw)
+		}
+		return knowledgeSource{kind: knowledgeSourceDoc, ref: rest}, nil
+	}
+	return knowledgeSource{kind: knowledgeSourceDir, ref: value}, nil
+}
+
+// cutKnowledgeScheme returns the part after "scheme:" and true when value starts
+// with that scheme. The scheme match is case-insensitive; the ref is trimmed.
+func cutKnowledgeScheme(value, scheme string) (string, bool) {
+	prefix := scheme + ":"
+	if len(value) < len(prefix) || !strings.EqualFold(value[:len(prefix)], prefix) {
+		return "", false
+	}
+	return strings.TrimSpace(value[len(prefix):]), true
+}
+
+// wikiNode is one document node listed under a wiki space.
+type wikiNode struct {
+	id   string
+	name string
+}
+
+// wikiFetcher abstracts the two reused doc capabilities so the pull logic can be
+// unit-tested with a fake (no real DingTalk calls). The real implementation
+// (runnerWikiFetcher) drives executor.Runner.
+type wikiFetcher interface {
+	// listNodes returns the document nodes under a wiki space.
+	listNodes(ctx context.Context, spaceID string) ([]wikiNode, error)
+	// readContent returns a node's content as plain markdown text.
+	readContent(ctx context.Context, nodeID string) (string, error)
+}
+
+// runnerWikiFetcher reuses the existing `doc` tools through the shared runner.
+// It calls the exact RPCs that back `dws doc list` (list_nodes) and
+// `dws doc read --content-format markdown` (get_document_content); no new API
+// surface is added here.
+type runnerWikiFetcher struct {
+	runner executor.Runner
+}
+
+const (
+	// wikiListPageLimit bounds pagination so a huge / misconfigured space cannot
+	// spin the pull loop forever at startup.
+	wikiListPageLimit = 50
+	// wikiListPageSize is the per-page request size for list_nodes.
+	wikiListPageSize = 50
+)
+
+func (f runnerWikiFetcher) listNodes(ctx context.Context, spaceID string) ([]wikiNode, error) {
+	var nodes []wikiNode
+	seen := map[string]struct{}{}
+	pageToken := ""
+	for page := 0; page < wikiListPageLimit; page++ {
+		params := map[string]any{
+			"workspaceId": spaceID,
+			"pageSize":    wikiListPageSize,
+		}
+		if pageToken != "" {
+			params["pageToken"] = pageToken
+		}
+		inv := executor.NewHelperInvocation("doc list", "doc", "list_nodes", params)
+		res, err := f.runner.Run(ctx, inv)
+		if err != nil {
+			return nil, err
+		}
+		for _, n := range collectWikiNodes(res.Response) {
+			if n.id == "" {
+				continue
+			}
+			if _, dup := seen[n.id]; dup {
+				continue
+			}
+			seen[n.id] = struct{}{}
+			nodes = append(nodes, n)
+		}
+		pageToken = firstStringForKeys(res.Response, "nextPageToken", "pageToken", "nextToken")
+		if pageToken == "" {
+			break
+		}
+	}
+	return nodes, nil
+}
+
+func (f runnerWikiFetcher) readContent(ctx context.Context, nodeID string) (string, error) {
+	inv := executor.NewHelperInvocation("doc read", "doc", "get_document_content", map[string]any{
+		"nodeId": nodeID,
+		"format": "markdown",
+	})
+	res, err := f.runner.Run(ctx, inv)
+	if err != nil {
+		return "", err
+	}
+	return firstStringForKeys(res.Response, "markdown", "content", "text", "data"), nil
+}
+
+// loadWikiKnowledgeBase pulls a wiki space (or a single doc node) into the local
+// cache and builds the knowledge base from it. cacheRoot is typically
+// ~/.dws/connect/<clientId>/knowledge. On a pull failure it falls back to an
+// existing (stale) cache, and finally to an empty base — it never returns an
+// error, so the connector keeps starting. Progress / warnings go to logw.
+func loadWikiKnowledgeBase(ctx context.Context, fetcher wikiFetcher, src knowledgeSource, cacheRoot string, logw io.Writer) *knowledgeBase {
+	if logw == nil {
+		logw = io.Discard
+	}
+	cacheDir := filepath.Join(cacheRoot, wikiCacheLeaf(src))
+
+	docs, err := pullWikiDocs(ctx, fetcher, src)
+	if err != nil {
+		// Pull failed: try the previous cache before giving up.
+		if kb, lerr := loadKnowledgeBase(cacheDir); lerr == nil {
+			fmt.Fprintf(logw, "[connect][knowledge] 拉取知识库失败（%v），使用旧缓存兜底：%s\n", err, cacheDir)
+			return kb
+		}
+		fmt.Fprintf(logw, "[connect][knowledge] 拉取知识库失败（%v）且无可用缓存，以空知识起，不阻断连接\n", err)
+		return &knowledgeBase{}
+	}
+
+	if writeErr := writeWikiCache(cacheDir, docs); writeErr != nil {
+		// Cache write is best-effort: build straight from what we pulled so a
+		// read-only / full disk does not break the feature.
+		fmt.Fprintf(logw, "[connect][knowledge] 缓存写入失败（%v），改用内存构建\n", writeErr)
+		return buildKnowledgeBaseFromDocs(docs)
+	}
+
+	kb, lerr := loadKnowledgeBase(cacheDir)
+	if lerr != nil {
+		// Cache wrote but produced no usable chunks (e.g. all docs empty):
+		// degrade to an empty base rather than failing the connector.
+		fmt.Fprintf(logw, "[connect][knowledge] 知识库无可用内容（%v），以空知识起\n", lerr)
+		return &knowledgeBase{}
+	}
+	fmt.Fprintf(logw, "[connect][knowledge] 知识库已拉取并缓存：%d 个文档 / %d 个片段（%s）\n", len(docs), len(kb.chunks), cacheDir)
+	return kb
+}
+
+// wikiDoc is one pulled document: a stable file stem plus its markdown text.
+type wikiDoc struct {
+	stem string
+	text string
+}
+
+// pullWikiDocs fetches the documents for a source. For a wiki space it lists the
+// nodes then reads each; for a single doc it reads that one node. Per-node read
+// failures are skipped (logged by the caller via the returned set being smaller)
+// rather than aborting the whole pull. A hard failure (list error, or zero
+// readable docs) is returned so the caller can fall back to cache.
+func pullWikiDocs(ctx context.Context, fetcher wikiFetcher, src knowledgeSource) ([]wikiDoc, error) {
+	switch src.kind {
+	case knowledgeSourceDoc:
+		text, err := fetcher.readContent(ctx, src.ref)
+		if err != nil {
+			return nil, err
+		}
+		if strings.TrimSpace(text) == "" {
+			return nil, fmt.Errorf("doc %s 内容为空", src.ref)
+		}
+		return []wikiDoc{{stem: sanitizeWikiStem(src.ref), text: text}}, nil
+	case knowledgeSourceWiki:
+		nodes, err := fetcher.listNodes(ctx, src.ref)
+		if err != nil {
+			return nil, err
+		}
+		if len(nodes) == 0 {
+			return nil, fmt.Errorf("wiki space %s 下没有文档节点", src.ref)
+		}
+		var docs []wikiDoc
+		for _, n := range nodes {
+			text, rerr := fetcher.readContent(ctx, n.id)
+			if rerr != nil || strings.TrimSpace(text) == "" {
+				continue
+			}
+			stem := n.name
+			if strings.TrimSpace(stem) == "" {
+				stem = n.id
+			}
+			docs = append(docs, wikiDoc{stem: sanitizeWikiStem(stem), text: text})
+		}
+		if len(docs) == 0 {
+			return nil, fmt.Errorf("wiki space %s 下没有可读文档", src.ref)
+		}
+		return docs, nil
+	default:
+		return nil, fmt.Errorf("source kind %d is not a wiki/doc source", src.kind)
+	}
+}
+
+// buildKnowledgeBaseFromDocs chunks pulled docs directly into a knowledge base,
+// reusing the same chunker/term-index as the local-file path. Used when the
+// cache write fails but the pull succeeded.
+func buildKnowledgeBaseFromDocs(docs []wikiDoc) *knowledgeBase {
+	kb := &knowledgeBase{}
+	for _, d := range docs {
+		source := d.stem + ".md"
+		for _, chunk := range splitKnowledgeChunks(d.text) {
+			kb.chunks = append(kb.chunks, knowledgeChunk{source: source, text: chunk, terms: knowledgeTerms(chunk)})
+		}
+	}
+	return kb
+}
+
+// writeWikiCache replaces the cache directory with the freshly pulled docs (one
+// .md per document) so loadKnowledgeBase can index it like any local directory.
+// It clears stale files first so deleted wiki docs do not linger in answers.
+func writeWikiCache(cacheDir string, docs []wikiDoc) error {
+	if err := os.RemoveAll(cacheDir); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
+		return err
+	}
+	used := map[string]int{}
+	for _, d := range docs {
+		stem := d.stem
+		if stem == "" {
+			stem = "doc"
+		}
+		// De-duplicate stems so two same-named docs do not overwrite each other.
+		if n := used[stem]; n > 0 {
+			used[stem] = n + 1
+			stem = fmt.Sprintf("%s-%d", stem, n+1)
+		} else {
+			used[stem] = 1
+		}
+		path := filepath.Join(cacheDir, stem+".md")
+		if err := os.WriteFile(path, []byte(d.text), 0o644); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// wikiCacheLeaf is the per-source cache subdirectory name, e.g. "wiki-<spaceId>"
+// or "doc-<docId>", with the id sanitized for filesystem safety.
+func wikiCacheLeaf(src knowledgeSource) string {
+	prefix := "wiki"
+	if src.kind == knowledgeSourceDoc {
+		prefix = "doc"
+	}
+	return prefix + "-" + sanitizeWikiStem(src.ref)
+}
+
+// sanitizeWikiStem maps an id/name to a safe file stem: path separators and
+// other awkward characters become '_', so a doc title or URL-ish id cannot
+// escape the cache directory.
+func sanitizeWikiStem(raw string) string {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return "doc"
+	}
+	var b strings.Builder
+	for _, r := range value {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9',
+			r == '-', r == '_', r == '.':
+			b.WriteRune(r)
+		default:
+			b.WriteByte('_')
+		}
+	}
+	stem := strings.Trim(b.String(), "._")
+	if stem == "" {
+		return "doc"
+	}
+	if len(stem) > 80 {
+		stem = stem[:80]
+	}
+	return stem
+}
+
+// collectWikiNodes walks a list_nodes response and gathers every {id, name}
+// node it can find. It is tolerant of wrapper layers (content/result/data) and
+// of the exact id/name field spelling. A map is treated as a node only when it
+// carries an id *directly* (shallow lookup, not the recursive extractor) —
+// otherwise a wrapper object would be mistaken for a single node and sibling
+// nodes in a list would be skipped.
+func collectWikiNodes(resp map[string]any) []wikiNode {
+	var nodes []wikiNode
+	var walk func(any)
+	walk = func(cur any) {
+		switch x := cur.(type) {
+		case map[string]any:
+			if id := shallowStringForKeys(x, "nodeId", "nodeID", "node_id", "id"); id != "" {
+				name := shallowStringForKeys(x, "name", "title", "nodeName")
+				nodes = append(nodes, wikiNode{id: id, name: name})
+				return
+			}
+			for _, v := range x {
+				walk(v)
+			}
+		case []any:
+			for _, item := range x {
+				walk(item)
+			}
+		}
+	}
+	walk(resp)
+	return nodes
+}
+
+// shallowStringForKeys returns the first non-empty string value for any of keys
+// at this map level only (no recursion), preserving key priority order.
+func shallowStringForKeys(m map[string]any, keys ...string) string {
+	for _, k := range keys {
+		if s, ok := m[k].(string); ok && strings.TrimSpace(s) != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+// firstStringForKeys returns the first non-empty string found for any of keys by
+// walking the value recursively (depth-first). It is the shared, source-shape
+// tolerant extractor used for both node ids and document content.
+func firstStringForKeys(v any, keys ...string) string {
+	keySet := make(map[string]struct{}, len(keys))
+	for _, k := range keys {
+		keySet[k] = struct{}{}
+	}
+	var walk func(any) string
+	walk = func(cur any) string {
+		switch x := cur.(type) {
+		case map[string]any:
+			for _, k := range keys {
+				if s, ok := x[k].(string); ok && strings.TrimSpace(s) != "" {
+					return s
+				}
+			}
+			for key, val := range x {
+				if _, direct := keySet[key]; direct {
+					continue
+				}
+				if found := walk(val); found != "" {
+					return found
+				}
+			}
+		case []any:
+			for _, item := range x {
+				if found := walk(item); found != "" {
+					return found
+				}
+			}
+		}
+		return ""
+	}
+	return walk(v)
+}
+
+// loadConnectKnowledgeSource resolves a --knowledge-source value and builds the
+// knowledge base. A bare path (or dir: semantics) reuses the strict local-file
+// loader (a typo'd directory stays loud, matching --knowledge-dir). A
+// wiki:/doc: source pulls from the DingTalk knowledge base, caches it under
+// ~/.dws/connect/<clientId>/knowledge, and never blocks the connection on a pull
+// failure. A nil knowledge base means "leave any existing base untouched".
+func loadConnectKnowledgeSource(cmd *cobra.Command, runner executor.Runner, clientID, raw string) (*knowledgeBase, error) {
+	src, err := parseKnowledgeSource(raw)
+	if err != nil {
+		return nil, err
+	}
+	logw := cmd.ErrOrStderr()
+	switch src.kind {
+	case knowledgeSourceDir:
+		kb, lerr := loadKnowledgeBase(src.ref)
+		if lerr != nil {
+			return nil, lerr
+		}
+		fmt.Fprintf(logw, "[connect] 知识库已加载：%d 个片段（%s）\n", len(kb.chunks), src.ref)
+		return kb, nil
+	case knowledgeSourceWiki, knowledgeSourceDoc:
+		fetcher := runnerWikiFetcher{runner: runner}
+		cacheRoot := connectKnowledgeCacheRoot(clientID)
+		return loadWikiKnowledgeBase(cmd.Context(), fetcher, src, cacheRoot, logw), nil
+	default:
+		return nil, fmt.Errorf("unsupported knowledge source kind %d", src.kind)
+	}
+}
+
+// connectKnowledgeCacheRoot is the per-robot knowledge cache root:
+// ~/.dws/connect/<clientId>/knowledge. clientId is sanitized so it cannot escape
+// the directory; an empty clientId degrades to a shared "default" bucket.
+func connectKnowledgeCacheRoot(clientID string) string {
+	id := sanitizeWikiStem(clientID)
+	if id == "" {
+		id = "default"
+	}
+	return filepath.Join(homeDir(), ".dws", "connect", id, "knowledge")
+}

internal/helpers/connect_knowledge_wiki_test.go

@@ -0,0 +1,218 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+// fakeWikiFetcher is an in-test wikiFetcher: no DingTalk calls, fully scripted.
+type fakeWikiFetcher struct {
+	nodes      []wikiNode
+	content    map[string]string
+	listErr    error
+	readErrFor map[string]error
+}
+
+func (f fakeWikiFetcher) listNodes(_ context.Context, _ string) ([]wikiNode, error) {
+	if f.listErr != nil {
+		return nil, f.listErr
+	}
+	return f.nodes, nil
+}
+
+func (f fakeWikiFetcher) readContent(_ context.Context, nodeID string) (string, error) {
+	if f.readErrFor != nil {
+		if err, ok := f.readErrFor[nodeID]; ok {
+			return "", err
+		}
+	}
+	return f.content[nodeID], nil
+}
+
+// ① --knowledge-source syntax parses wiki:<spaceId> / doc:<docId> correctly.
+func TestParseKnowledgeSource(t *testing.T) {
+	cases := []struct {
+		raw      string
+		wantKind knowledgeSourceKind
+		wantRef  string
+		wantErr  bool
+	}{
+		{"wiki:SPACE123", knowledgeSourceWiki, "SPACE123", false},
+		{"  wiki:SPACE123  ", knowledgeSourceWiki, "SPACE123", false},
+		{"WIKI:Sp", knowledgeSourceWiki, "Sp", false}, // scheme is case-insensitive
+		{"doc:NODE9", knowledgeSourceDoc, "NODE9", false},
+		{"/var/knowledge", knowledgeSourceDir, "/var/knowledge", false},
+		{"./local", knowledgeSourceDir, "./local", false},
+		{"wiki:", 0, "", true},
+		{"doc:", 0, "", true},
+		{"", 0, "", true},
+	}
+	for _, c := range cases {
+		got, err := parseKnowledgeSource(c.raw)
+		if c.wantErr {
+			if err == nil {
+				t.Errorf("parseKnowledgeSource(%q) expected error, got %+v", c.raw, got)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("parseKnowledgeSource(%q) unexpected error: %v", c.raw, err)
+			continue
+		}
+		if got.kind != c.wantKind || got.ref != c.wantRef {
+			t.Errorf("parseKnowledgeSource(%q) = {%d,%q}, want {%d,%q}", c.raw, got.kind, got.ref, c.wantKind, c.wantRef)
+		}
+	}
+}
+
+// ③ A pulled wiki space lands in the retriever and the right chunk is retrieved.
+func TestLoadWikiKnowledgeBaseRetrieves(t *testing.T) {
+	fetcher := fakeWikiFetcher{
+		nodes: []wikiNode{
+			{id: "n1", name: "安装指南"},
+			{id: "n2", name: "缓存问题"},
+		},
+		content: map[string]string{
+			"n1": "# 安装\n\ndws 通过 brew install dws 安装。",
+			"n2": "# 缓存问题\n\n出现幽灵命令时运行 dws cache refresh 强制刷新发现配置缓存。",
+		},
+	}
+	src := knowledgeSource{kind: knowledgeSourceWiki, ref: "SPACE123"}
+	kb := loadWikiKnowledgeBase(context.Background(), fetcher, src, t.TempDir(), io.Discard)
+	if kb == nil || len(kb.chunks) == 0 {
+		t.Fatalf("expected a non-empty knowledge base, got %+v", kb)
+	}
+	got := kb.augment("cache refresh 是干什么的")
+	if !strings.Contains(got, "强制刷新发现配置缓存") {
+		t.Fatalf("augment missed the cache chunk pulled from wiki:\n%s", got)
+	}
+}
+
+// ③ A doc:<docId> source pulls a single node into the retriever.
+func TestLoadWikiKnowledgeBaseSingleDoc(t *testing.T) {
+	fetcher := fakeWikiFetcher{
+		content: map[string]string{
+			"NODE9": "# 机器人建联\n\n卡片停在数据加载中说明回复超过了 AI 助理应答窗口。",
+		},
+	}
+	src := knowledgeSource{kind: knowledgeSourceDoc, ref: "NODE9"}
+	kb := loadWikiKnowledgeBase(context.Background(), fetcher, src, t.TempDir(), io.Discard)
+	if kb == nil || len(kb.chunks) == 0 {
+		t.Fatalf("expected a non-empty knowledge base, got %+v", kb)
+	}
+	if got := kb.augment("数据加载中怎么办"); !strings.Contains(got, "AI 助理应答窗口") {
+		t.Fatalf("augment missed the single doc chunk:\n%s", got)
+	}
+}
+
+// ② Pull failure with no prior cache degrades to an empty (non-nil) base and
+// does not panic.
+func TestLoadWikiKnowledgeBaseFailNoCacheEmpty(t *testing.T) {
+	fetcher := fakeWikiFetcher{listErr: errors.New("network down")}
+	src := knowledgeSource{kind: knowledgeSourceWiki, ref: "SPACE123"}
+	kb := loadWikiKnowledgeBase(context.Background(), fetcher, src, t.TempDir(), io.Discard)
+	if kb == nil {
+		t.Fatal("expected a non-nil empty base, got nil")
+	}
+	if len(kb.chunks) != 0 {
+		t.Fatalf("expected empty base on failure, got %d chunks", len(kb.chunks))
+	}
+	// augment on an empty base must pass the question through unchanged.
+	if got := kb.augment("任意问题"); got != "任意问题" {
+		t.Fatalf("empty base should pass through, got %q", got)
+	}
+}
+
+// ② Pull failure falls back to a previously written (stale) cache.
+func TestLoadWikiKnowledgeBaseFailUsesStaleCache(t *testing.T) {
+	cacheRoot := t.TempDir()
+	src := knowledgeSource{kind: knowledgeSourceWiki, ref: "SPACE123"}
+
+	// First pull succeeds and populates the cache.
+	good := fakeWikiFetcher{
+		nodes:   []wikiNode{{id: "n1", name: "缓存问题"}},
+		content: map[string]string{"n1": "# 缓存问题\n\n运行 dws cache refresh 强制刷新发现配置缓存。"},
+	}
+	if kb := loadWikiKnowledgeBase(context.Background(), good, src, cacheRoot, io.Discard); len(kb.chunks) == 0 {
+		t.Fatal("warm-up pull should have populated the cache")
+	}
+
+	// Second pull fails; must fall back to the stale cache, not go empty.
+	bad := fakeWikiFetcher{listErr: errors.New("permission denied")}
+	kb := loadWikiKnowledgeBase(context.Background(), bad, src, cacheRoot, io.Discard)
+	if kb == nil || len(kb.chunks) == 0 {
+		t.Fatalf("expected stale-cache fallback to keep chunks, got %+v", kb)
+	}
+	if got := kb.augment("cache refresh"); !strings.Contains(got, "强制刷新发现配置缓存") {
+		t.Fatalf("stale cache content not retrievable:\n%s", got)
+	}
+}
+
+// Per-node read failures are skipped without aborting the whole pull.
+func TestPullWikiDocsSkipsUnreadableNodes(t *testing.T) {
+	fetcher := fakeWikiFetcher{
+		nodes: []wikiNode{{id: "ok", name: "好文档"}, {id: "bad", name: "坏文档"}},
+		content: map[string]string{
+			"ok":  "# 好文档\n\n这是可读内容。",
+			"bad": "",
+		},
+		readErrFor: map[string]error{"bad": errors.New("403")},
+	}
+	docs, err := pullWikiDocs(context.Background(), fetcher, knowledgeSource{kind: knowledgeSourceWiki, ref: "S"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(docs) != 1 || !strings.Contains(docs[0].text, "可读内容") {
+		t.Fatalf("expected only the readable doc, got %+v", docs)
+	}
+}
+
+// collectWikiNodes is tolerant of wrapper layers and id/name field spellings.
+func TestCollectWikiNodesTolerant(t *testing.T) {
+	resp := map[string]any{
+		"content": map[string]any{
+			"nodes": []any{
+				map[string]any{"nodeId": "a", "name": "Alpha"},
+				map[string]any{"id": "b", "title": "Beta"},
+			},
+		},
+	}
+	nodes := collectWikiNodes(resp)
+	if len(nodes) != 2 {
+		t.Fatalf("expected 2 nodes, got %d (%+v)", len(nodes), nodes)
+	}
+	if nodes[0].id != "a" || nodes[0].name != "Alpha" || nodes[1].id != "b" || nodes[1].name != "Beta" {
+		t.Fatalf("node extraction wrong: %+v", nodes)
+	}
+}
+
+func TestSanitizeWikiStem(t *testing.T) {
+	cases := map[string]string{
+		"SPACE123":               "SPACE123",
+		"a/b/../c":               "a_b_.._c",
+		"https://x/nodes/N9?q=1": "https___x_nodes_N9_q_1",
+		"":                       "doc",
+		"...":                    "doc",
+	}
+	for in, want := range cases {
+		if got := sanitizeWikiStem(in); got != want {
+			t.Errorf("sanitizeWikiStem(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

internal/helpers/connect_lock.go

@@ -0,0 +1,82 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+)
+
+// connectLockDir is a var so tests can isolate lock files.
+var connectLockDir = os.TempDir()
+
+// acquireConnectLock guards against two local connectors holding Stream
+// connections for the same robot. DingTalk load-balances pushes across
+// connections sharing one clientId, so a duplicate connector makes the bot
+// answer intermittently — the hardest-to-diagnose failure mode this command
+// has (verified live). The lock is a pid file; a stale file whose owning
+// process is gone is taken over silently.
+func acquireConnectLock(clientID string) (release func(), err error) {
+	path := filepath.Join(connectLockDir, "dws-connect-"+sanitizeLockID(clientID)+".pid")
+	for attempt := 0; attempt < 2; attempt++ {
+		f, openErr := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+		if openErr == nil {
+			fmt.Fprintf(f, "%d", os.Getpid())
+			f.Close()
+			return func() { _ = os.Remove(path) }, nil
+		}
+		if !os.IsExist(openErr) {
+			return nil, openErr
+		}
+		raw, readErr := os.ReadFile(path)
+		if readErr == nil {
+			if pid, perr := strconv.Atoi(strings.TrimSpace(string(raw))); perr == nil && pid > 0 && processAlive(pid) {
+				return nil, fmt.Errorf("机器人 %s 已有连接器在本机运行 (pid %d)。同一机器人的多个 Stream 连接会随机分流消息，表现为机器人时灵时不灵；请先停掉旧进程，或确认后删除 %s", clientID, pid, path)
+			}
+		}
+		// Stale lock (owner gone or file unreadable): take over.
+		_ = os.Remove(path)
+	}
+	return nil, fmt.Errorf("无法获取连接器锁 %s", path)
+}
+
+// sanitizeLockID keeps the lock filename filesystem-safe.
+func sanitizeLockID(s string) string {
+	return strings.Map(func(r rune) rune {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '-', r == '_':
+			return r
+		}
+		return '_'
+	}, s)
+}
+
+// processAlive reports whether pid refers to a live process (unix signal-0
+// probe; a permission error still means "alive").
+func processAlive(pid int) bool {
+	proc, err := os.FindProcess(pid)
+	if err != nil {
+		return false
+	}
+	err = proc.Signal(syscall.Signal(0))
+	if err == nil {
+		return true
+	}
+	return errors.Is(err, syscall.EPERM)
+}

internal/helpers/connect_lock_test.go

@@ -0,0 +1,102 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func withLockDir(t *testing.T) string {
+	t.Helper()
+	old := connectLockDir
+	dir := t.TempDir()
+	connectLockDir = dir
+	t.Cleanup(func() { connectLockDir = old })
+	return dir
+}
+
+// TestConnectLockBlocksSecond: a live lock (this test process's pid) must
+// reject a second acquire for the same robot, with the dual-connection
+// explanation in the error.
+func TestConnectLockBlocksSecond(t *testing.T) {
+	withLockDir(t)
+	release, err := acquireConnectLock("ding-bot-1")
+	if err != nil {
+		t.Fatalf("first acquire: %v", err)
+	}
+	defer release()
+
+	if _, err := acquireConnectLock("ding-bot-1"); err == nil {
+		t.Fatal("second acquire succeeded, want rejection")
+	} else if !strings.Contains(err.Error(), "已有连接器在本机运行") {
+		t.Fatalf("error = %v, want dual-connection explanation", err)
+	}
+
+	// A different robot is unaffected.
+	release2, err := acquireConnectLock("ding-bot-2")
+	if err != nil {
+		t.Fatalf("other robot acquire: %v", err)
+	}
+	release2()
+}
+
+// TestConnectLockReleaseAndReacquire: release removes the pid file and the
+// same robot can be locked again.
+func TestConnectLockReleaseAndReacquire(t *testing.T) {
+	dir := withLockDir(t)
+	release, err := acquireConnectLock("ding-bot-1")
+	if err != nil {
+		t.Fatalf("acquire: %v", err)
+	}
+	release()
+	if entries, _ := os.ReadDir(dir); len(entries) != 0 {
+		t.Fatalf("lock file not removed: %v", entries)
+	}
+	release2, err := acquireConnectLock("ding-bot-1")
+	if err != nil {
+		t.Fatalf("reacquire after release: %v", err)
+	}
+	release2()
+}
+
+// TestConnectLockStaleTakeover: a lock owned by a dead pid is taken over.
+func TestConnectLockStaleTakeover(t *testing.T) {
+	dir := withLockDir(t)
+	// pid far beyond any OS pid range — guaranteed not alive.
+	stale := filepath.Join(dir, "dws-connect-ding-bot-1.pid")
+	if err := os.WriteFile(stale, []byte("999999999"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	release, err := acquireConnectLock("ding-bot-1")
+	if err != nil {
+		t.Fatalf("stale takeover failed: %v", err)
+	}
+	release()
+}
+
+// TestConnectLockGarbageFile: an unreadable/garbage lock is treated as stale.
+func TestConnectLockGarbageFile(t *testing.T) {
+	dir := withLockDir(t)
+	if err := os.WriteFile(filepath.Join(dir, "dws-connect-ding-bot-1.pid"), []byte("not-a-pid"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	release, err := acquireConnectLock("ding-bot-1")
+	if err != nil {
+		t.Fatalf("garbage lock takeover failed: %v", err)
+	}
+	release()
+}

internal/helpers/connect_media.go

@@ -0,0 +1,117 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/google/uuid"
+)
+
+// mediaMaxDownloadBytes caps a single inbound image download (screenshots are
+// well under this; the cap is a hostile-input guard).
+const mediaMaxDownloadBytes = 20 << 20
+
+// pictureDownloadCode digs the downloadCode out of a picture callback's
+// loosely-typed content payload (the stream SDK models Content as
+// interface{}).
+func pictureDownloadCode(content interface{}) string {
+	m, ok := content.(map[string]interface{})
+	if !ok {
+		return ""
+	}
+	for _, key := range []string{"downloadCode", "pictureDownloadCode"} {
+		if v, ok := m[key].(string); ok && strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+// downloadMessageFile resolves a chatbot media callback (picture etc.) to a
+// local temp file via the robot messageFiles/download API. Error-screenshot
+// questions are the top Q&A inbound; without this the connector silently
+// drops every picture message.
+func (c *aiCardClient) downloadMessageFile(ctx context.Context, robotCode, downloadCode string) (string, error) {
+	raw, err := c.callRaw(ctx, http.MethodPost, "/v1.0/robot/messageFiles/download", map[string]any{
+		"robotCode":    robotCode,
+		"downloadCode": downloadCode,
+	})
+	if err != nil {
+		return "", err
+	}
+	var parsed struct {
+		DownloadUrl string `json:"downloadUrl"`
+	}
+	if err := json.Unmarshal([]byte(raw), &parsed); err != nil || strings.TrimSpace(parsed.DownloadUrl) == "" {
+		return "", fmt.Errorf("messageFiles/download 未返回 downloadUrl: %s", truncateRunes(raw, 200))
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.DownloadUrl, nil)
+	if err != nil {
+		return "", err
+	}
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return "", fmt.Errorf("媒体下载 HTTP %d", resp.StatusCode)
+	}
+	dir := filepath.Join(os.TempDir(), "dws-connect-media")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", err
+	}
+	dest := filepath.Join(dir, uuid.NewString()+mediaExt(parsed.DownloadUrl, resp.Header.Get("Content-Type")))
+	f, err := os.Create(dest)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	if _, err := io.Copy(f, io.LimitReader(resp.Body, mediaMaxDownloadBytes)); err != nil {
+		_ = os.Remove(dest)
+		return "", err
+	}
+	return dest, nil
+}
+
+// mediaExt picks a file extension from the response content type, falling
+// back to the URL path, then ".png" (DingTalk screenshots default to png).
+func mediaExt(rawURL, contentType string) string {
+	ct := strings.ToLower(contentType)
+	switch {
+	case strings.Contains(ct, "png"):
+		return ".png"
+	case strings.Contains(ct, "jpeg"), strings.Contains(ct, "jpg"):
+		return ".jpg"
+	case strings.Contains(ct, "gif"):
+		return ".gif"
+	case strings.Contains(ct, "webp"):
+		return ".webp"
+	}
+	if u, err := url.Parse(rawURL); err == nil {
+		if ext := strings.ToLower(filepath.Ext(u.Path)); len(ext) >= 2 && len(ext) <= 5 {
+			return ext
+		}
+	}
+	return ".png"
+}

internal/helpers/connect_media_test.go

@@ -0,0 +1,119 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestPictureDownloadCode(t *testing.T) {
+	cases := []struct {
+		name    string
+		content interface{}
+		want    string
+	}{
+		{"downloadCode", map[string]interface{}{"downloadCode": "dc-1"}, "dc-1"},
+		{"pictureDownloadCode fallback", map[string]interface{}{"pictureDownloadCode": "dc-2"}, "dc-2"},
+		{"blank ignored", map[string]interface{}{"downloadCode": "  "}, ""},
+		{"wrong type", "not-a-map", ""},
+		{"nil", nil, ""},
+	}
+	for _, tc := range cases {
+		if got := pictureDownloadCode(tc.content); got != tc.want {
+			t.Fatalf("%s: got %q, want %q", tc.name, got, tc.want)
+		}
+	}
+}
+
+// TestDownloadMessageFile drives the full resolve-then-fetch flow against a
+// fake API: token → messageFiles/download (must carry robotCode+downloadCode)
+// → presigned GET → local temp file.
+func TestDownloadMessageFile(t *testing.T) {
+	var gotDownloadReq map[string]any
+	mux := http.NewServeMux()
+	var srv *httptest.Server
+	mux.HandleFunc("/v1.0/oauth2/accessToken", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"accessToken": "tok-1", "expireIn": 7200})
+	})
+	mux.HandleFunc("/v1.0/robot/messageFiles/download", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("x-acs-dingtalk-access-token") != "tok-1" {
+			t.Error("missing access token header")
+		}
+		_ = json.NewDecoder(r.Body).Decode(&gotDownloadReq)
+		_ = json.NewEncoder(w).Encode(map[string]any{"downloadUrl": srv.URL + "/file"})
+	})
+	mux.HandleFunc("/file", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = w.Write([]byte("PNGDATA"))
+	})
+	srv = httptest.NewServer(mux)
+	defer srv.Close()
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", "")
+	path, err := c.downloadMessageFile(context.Background(), "ding-client", "dc-1")
+	if err != nil {
+		t.Fatalf("downloadMessageFile: %v", err)
+	}
+	defer os.Remove(path)
+
+	if gotDownloadReq["robotCode"] != "ding-client" || gotDownloadReq["downloadCode"] != "dc-1" {
+		t.Fatalf("download request payload = %v", gotDownloadReq)
+	}
+	if !strings.HasSuffix(path, ".png") {
+		t.Fatalf("path = %q, want .png suffix from content type", path)
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil || string(raw) != "PNGDATA" {
+		t.Fatalf("saved file = %q, %v", raw, err)
+	}
+}
+
+func TestDownloadMessageFileNoURL(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1.0/oauth2/accessToken", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"accessToken": "tok-1", "expireIn": 7200})
+	})
+	mux.HandleFunc("/v1.0/robot/messageFiles/download", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{})
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+	withCardAPIBase(t, srv.URL)
+
+	c := newAICardClient("ding-client", "ding-secret", "")
+	if _, err := c.downloadMessageFile(context.Background(), "ding-client", "dc-1"); err == nil {
+		t.Fatal("missing downloadUrl should error")
+	}
+}
+
+func TestMediaExt(t *testing.T) {
+	cases := []struct{ url, ct, want string }{
+		{"https://x/y", "image/png", ".png"},
+		{"https://x/y", "image/jpeg", ".jpg"},
+		{"https://x/y.webp?sig=1", "", ".webp"},
+		{"https://x/y", "", ".png"},
+	}
+	for _, tc := range cases {
+		if got := mediaExt(tc.url, tc.ct); got != tc.want {
+			t.Fatalf("mediaExt(%q, %q) = %q, want %q", tc.url, tc.ct, got, tc.want)
+		}
+	}
+}