@lark-project/meegle 1.0.20 → 1.0.22

package/CHANGELOG.md

@@ -8,6 +8,69 @@ versioned section on each npm release.
 
 ## [Unreleased]
 
+## [v1.0.22] - 2026-08-27
+
+### Fixed
+
+- Restored the Facade command-string Go SDK to its MCP-only contract: local CLI API commands such as `ai-handoff` and `preference handoff` remain available in the npm-distributed `meegle` CLI but are no longer registered or routed by the remote RPC SDK.
+
+## [v1.0.21] - 2026-08-26
+
+### Added
+
+- Added an interactive startup update notifier for npm-distributed CLI installs. At most once every 24 hours it checks the latest npm version, summarizes released `Added` and `Changed` entries from the GitHub CHANGELOG, and offers an arrow-key choice between immediate upgrade (recommended and selected by default) or a 24-hour deferral. Immediate upgrade installs the latest CLI first, then best-effort upgrades the Meegle Agent Skill through the existing install-wizard path; an unavailable Skill installer or failed Skill upgrade cannot fail the completed CLI upgrade. Non-interactive/CI, piped-output, install, and shell-completion invocations are skipped, and `MEEGLE_NO_UPDATE_CHECK=1` disables the check explicitly.
+- Added non-MCP `ai-handoff availability` and `ai-handoff create-link` commands to both the CLI binary and programmatic command-string SDK. Availability reads the Handoff section of generic CLI config discovery; expected business rejections use `reject_code`/`reject_msg`, while dependency and transport failures use the standard error model. Successful config snapshots are cached per profile for up to 1 hour. Link creation accepts typed Project/WorkItemType/WorkItem/View/MeasureChart entities, always re-validates server-side, and returns an AI assistant URL.
+- Handoff Config, Preference, and Create Link failures now surface the gateway `x-tt-logid` response header as `meta.logid` in the structured error envelope, so production-package failures can be traced without enabling or exporting debug logs.
+- Successful Handoff Config, Preference, and Create Link calls now retain the same response-header LogID in result metadata, exposing it as `meta.logid` only when `--envelope` is requested while keeping default output unchanged.
+- Create-link responses always include `available`: success returns HTTP 200 with `available=true` and the generated `url`; expected business rejection returns HTTP 200 with `available=false`, `reject_code`, and `reject_msg` and invalidates the local config cache. Unexpected failures continue to use the standard API error model.
+- Added `preference handoff auto|ask|off`, backed by the server-side unified user preference service. The generic batch write API uses `type=handoff_suggestions` with a type-owned `{"mode":"off|ask|auto"}` JSON-string payload and reports only write success; current values are read through CLI config discovery. A successful write invalidates the local CLI config cache.
+- Added the local `MEEGLE_AI_HANDOFF=disabled` hard-disable. It makes `availability` and valid `create-link` invocations return `available=false` with `reject_code=LOCAL_DISABLED` without requiring authentication, reading cached availability, or calling the Handoff API.
+- Added compile-time enterprise CLI extensions without requiring a repository fork: public `cmd.Execute` / `cmd.ExecuteWithVersion` entry points, Credential providers, a single Transport interceptor, and Platform plugins for command observation, wrapping, lifecycle hooks, and restrictions.
+- Added `meegle extension doctor|credentials|transport|plugins|policy|discovery` diagnostics that expose non-secret registration, compatibility, selector, rule, transport-baseline, and isolated dynamic-tool metadata.
+- Added standalone no-extension and enterprise binaries under `examples/`, including public-module build and end-to-end MCP/OAuth/governance coverage.
+- Added wire-level `tools/list` metadata parsing so previously unknown MCP tools with `metadata.resource` and `metadata.method` become executable dynamic commands in both CLI and SDK registries.
+- Dynamic discovery now isolates malformed, oversized, duplicate, flag-conflicting, and static-command-shadowing tools per entry; known fallback paths remain immutable, help text is sanitized, Registry rebuild state is published coherently, and SDK callers can inspect skipped entries through `Client.DiscoveryIssues()`.
+- Unknown tools without metadata now report a stable `missing_mapping` discovery issue in both CLI and SDK diagnostics instead of being silently omitted.
+- Nullable JSON Schema parameter types such as `["string", "null"]` now remain available in CLI and SDK discovery; unions with multiple non-null types report `unsupported_schema_union` without affecting valid sibling tools.
+
+### Changed
+
+- Renamed the Handoff commands to `ai-handoff availability` and `ai-handoff create-link`; the earlier plus-prefixed forms are no longer registered.
+- `ai-handoff create-link` keeps the CLI/facade `user_query/related_context` contract and the CLI flags `--query`/`--related-context`; facade converts it to the AI `query/entities` contract internally. Public context payloads use business identifiers (`project_key`, `work_item_type_key`, `work_item_id`, `view_id`, `chart_id`) instead of exposing AI's generic `key`; View keeps `work_item_type_key` optional.
+- Successful `ai-handoff create-link` responses now replace the returned URL host with the active CLI login host while preserving the scheme, path, query, and fragment.
+- Expanded local-command help with full `meegle` usage paths, required-flag markers, behavior/parameter details, and examples; `meegle inspect` now includes local and nested commands such as `ai-handoff create-link` and `preference handoff auto`.
+
+### Security
+
+- Transport extensions apply a 30-second timeout to provider and hook callbacks without shortening the caller-owned MCP, OAuth, or attachment request lifetime. They retain a 10-redirect limit and HTTPS downgrade protection, including when inherited redirect callbacks mutate both the destination and redirect history. Requests rejected before reaching the base transport now close their bodies, and extension callback panics are converted to controlled failures.
+- MCP requests using a custom token header remove stale static credential headers and reject cross-origin redirects against an immutable source snapshot, so credentials cannot be duplicated or copied to another HTTPS origin.
+- Hand-written Platform plugins that declare command restrictions with a fail-open policy now fail CLI startup before `Install` runs instead of silently disabling all of that plugin's policy rules.
+- Platform metadata/Install and Startup callbacks now have a two-second safety boundary. Fail-open timeouts do not block later plugins, fail-closed timeouts stop execution, and timed-out Install callbacks cannot commit late registrations.
+- Transport pre-hooks that replace a request Body now release both the original and replacement streams; post-hook TLS snapshots deep-clone certificate objects so extensions cannot mutate live response metadata.
+- Extension startup and runtime failures retain safe `errors.Is` / `errors.As` matching without reflecting callback causes or panic values into public output; callback errors whose custom `Is`, `As`, `Unwrap`, `Error`, or payload methods panic are contained at Credential, Transport, Platform, formatter, and process-entry boundaries, while runtime and explicit abort failures expose stable structured error codes.
+
+### Compatibility
+
+- Broken profile variables now produce `CONFIG_ENV_UNRESOLVED` for dynamic business commands with or without a discovery cache, `inspect --profile` consistently uses the selected profile, and extension diagnostics report frozen resolution states instead of re-running providers.
+
+- The no-extension wrapper is regression-tested against the official binary, and the official binary is checked against a pinned `main@6326b7d` contract for legacy help, version, completion, authentication status, output, and exit-code behavior. CLI extensions remain isolated from SDK clients.
+- Restrict policy denials honor explicit structured output modes and expose the stable `CLIENT_COMMAND_DENIED` error envelope.
+- The legacy `--version` flag is routed through the governed `version` command, and destructive WBS publish/reset operations are classified as `high-risk-write` for enterprise policy enforcement.
+- Generated open-source trees are required to pass both `go build ./...` and `go test ./...`; source-only sync tooling and its tests are excluded from the published repository together.
+
+### Fixed
+
+- Tool discovery and server-side CLI configuration caches now share one profile-aware JSON file cache with atomic replacement, preventing concurrent CLI processes from exposing partially written cache files.
+- Remote catalog resources can no longer shadow locally owned root commands such as `ai-handoff` and `preference` and abort the complete CLI startup; conflicting tools are isolated as `reserved_path` discovery issues while unrelated dynamic commands remain available.
+- Map Facade invalid-parameter envelopes, including handoff query/context limit violations, to non-retryable `HANDOFF_API_INVALID_PARAM` errors and replace internal biz error IDs/causes/chains with a concise user-safe message and availability hint.
+- Credential and Platform failures raised before CLI App construction now honor explicit JSON/NDJSON output and retain their stable error codes; the published readonly enterprise policy keeps `extension/**` diagnostics available for troubleshooting.
+- Broken `${VAR}` profile placeholders no longer lock users out of help, version, login help, or configuration repair commands; credential-dependent business commands still fail with `CONFIG_ENV_UNRESOLVED`. Known local/recovery commands also defer Credential Provider resolution, so slow or unavailable OIDC providers no longer block them, while dynamic business commands remain fail-closed on ordinary errors, timeouts, and `BlockError`. A literal `--version` consumed as another flag's value is no longer rewritten as the version command. `dev` builds still reject non-empty `RequireCLI` constraints but now point enterprise developers to `ExecuteWithVersion` in the compatibility error chain.
+- Transport extensions no longer cancel successful HTTP requests when `RoundTrip` returns: delayed `tools/list` and `tools/call` bodies remain readable until closed, invalid URLs produced by pre-hooks fail closed instead of panicking, and post-hooks receive body-free metadata snapshots so timeouts release the live response immediately without a response-body race or connection leak.
+- Credential-bearing MCP requests now freeze the exact original origin for both default Bearer and custom token headers, preventing HTTPS downgrade, port-change, cross-domain forwarding, and multi-hop redirect-history mutation from leaking credentials.
+- Credential redirect guards now retain the standard 10-hop limit even when they install a custom redirect callback; all JSON-RPC responses are bounded before decoding (`tools/list` at 8 MiB, other calls at 32 MiB); Transport post-hooks receive a cloned TLS connection state instead of a pointer into the live response.
+- Multiple Restrict rules now compose as cumulative constraints; wrappers cannot return success after skipping, delaying, or duplicating `next`; a token-only Credential provider cannot hide a broken built-in configuration; first-run setup uses the Profile selected by the Credential provider; first-run completion is treated as success by Shutdown hooks and process entries without hiding fail-closed Shutdown failures; and spaced `RequireCLI` comparators such as `>= 1.2.0` are accepted.
+- Wrappers can no longer turn a non-nil downstream command error into exit 0 by ignoring the result of synchronous or awaited asynchronous `next` calls.
+
 ## [v1.0.20] - 2026-08-20
 
 ### Changed

package/README.md

@@ -8,7 +8,7 @@
 
 Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) ([Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)). Manage work items, schedules, and data from your terminal — no browser needed.
 
-[Install](#installation) · [Quick Start](#quick-start-human-users) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
+[Install](#installation) · [Quick Start](#quick-start-human-users) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Enterprise Extensions](#enterprise-cli-extensions) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
 
 ## Why Meegle CLI?
 
@@ -17,6 +17,7 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 - **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` for complex payloads like `fields[]` — pick the right granularity per call
 - **Flexible Output** — `json` / `table` / `ndjson` / `raw`, with `--select` dot-path projection for piping to other tools
 - **Secure by Default** — OS keychain credential storage, `${VAR}` env-var templating so secrets never land in config files, multi-profile switching for staging / prod
+- **Enterprise-Extensible** — Build a company distribution without forking this repository by importing the public `cmd`, Credential, Transport, and Platform packages at compile time
 
 ## Features
 
@@ -55,6 +56,26 @@ npx @lark-project/meegle@latest install
 
 The wizard installs or upgrades the CLI globally, installs the AI Agent Skill, configures the Meegle host, and starts login.
 
+### Automatic update prompt
+
+The npm-distributed CLI checks npm for a newer version at most once every 24 hours when it starts in an interactive terminal. When an update is available, it reads the released `Added` and `Changed` entries between the installed and latest versions from the [CHANGELOG](https://github.com/larksuite/meegle-cli/blob/main/CHANGELOG.md#changed), then shows an interactive prompt:
+
+```text
+✨ Meegle CLI update available: v<current> → v<latest>
+
+What's new:
+  v<version>
+    • Added: <feature summary>
+
+❯ Update now (recommended)
+  Remind me later
+  Use ↑/↓ to select, then press Enter
+```
+
+Pressing Enter first upgrades the CLI with `npm install -g @lark-project/meegle@latest`, then makes a best-effort attempt to upgrade the Meegle Agent Skill through the same installer used by `meegle install`, and finally continues the original command. A missing or incompatible Skill installer, or a Skill download failure, never changes a successful CLI upgrade into a failure. Choosing **Remind me later** defers the next check for 24 hours. This lightweight update does not reconfigure the host or trigger login; use `meegle install` when you want the full setup wizard.
+
+The check is skipped for non-interactive/CI execution, piped stdout, `install`, and shell-completion commands, so structured command output remains unchanged. Set `MEEGLE_NO_UPDATE_CHECK=1` to disable it explicitly.
+
 ## Quick Start (Human Users)
 
 > **Note for AI assistants:** if you are an AI Agent helping the user set this up, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent--ci--headless) — it contains the non-interactive command you need.
@@ -244,6 +265,69 @@ The agent consults the skill, picks the right `meegle` commands, and runs them f
 | `wbs get-draft-progress` | Get the execution progress of a WBS draft operation (create / edit / publish) |
 | `wbs list-element-templates` | List element templates (resource nodes and tasks) from the flow resource library |
 
+### ai-handoff — AI Assistant Handoff
+
+These commands are registered locally in the CLI and are not MCP tools. `availability` is an optional preflight before preparing `query` or related context; an expected business rejection is a successful probe and includes stable `reject_code` and display-only `reject_msg` fields. Dependency and transport failures use the standard CLI error model.
+
+`availability` reads the Handoff section of the generic `GET /goapi/v5/meeglecli/config` discovery response, including its `mode` (`off`, `ask`, or `auto`). The complete successful config snapshot is cached locally per profile for up to 1 hour; dependency or transport errors are never cached. The config cache is invalidated immediately on a successful `preference handoff auto|ask|off`, on `auth login`, and whenever `create-link` is rejected server-side. `create-link` never reads the cache: it always re-validates server-side and creates the link directly.
+
+The create-link HTTP response always includes `available`: success returns HTTP 200 with `available=true` and `url`; the CLI then replaces only that URL's host (including the configured port) with the active login host, preserving its scheme, path, query, and fragment. This keeps links in the currently selected Meegle or Lark Project environment. An expected business rejection returns HTTP 200 with `available=false`, `reject_code`, and `reject_msg`, and clears the local config cache. Unexpected failures use the standard API error response.
+
+Set `MEEGLE_AI_HANDOFF=disabled` to hard-disable Handoff in the local installation. Both `availability` and a valid `create-link` invocation then return `available=false` with `reject_code=LOCAL_DISABLED` and a display-only `reject_msg`; they do not require authentication, read the CLI configuration cache, or call the Handoff API. Unset values and values other than `disabled` preserve the normal server-controlled behavior. This local gate can only disable the feature—it cannot override the server business switch, entitlement, or personal preference to enable it.
+
+| Command | Description |
+|---------|-------------|
+| `ai-handoff availability` | Check the business switch, rollout, AI entitlement, personal preference, and link-service readiness |
+| `ai-handoff create-link` | Create an AI assistant link from required `--query` and optional, repeatable typed `--related-context` JSON objects |
+
+```bash
+meegle ai-handoff availability --format json
+
+MEEGLE_AI_HANDOFF=disabled meegle ai-handoff availability --format json
+
+meegle ai-handoff create-link --params '{
+  "query": "Summarize the risks and propose next actions",
+  "related_context": [{
+    "type": 3,
+    "work_item": {
+      "project_key": "PROJ",
+      "work_item_type_key": "story",
+      "work_item_id": "123"
+    }
+  }]
+}' --format json
+
+meegle ai-handoff create-link --help
+meegle inspect ai-handoff create-link
+```
+
+Each `related_context` item must set `type` and exactly one matching payload. The facade contract uses business identifiers and never exposes the AI service's generic `key`; facade fills that field only while converting to the internal `query + entities` contract:
+
+| Type | Payload | Required fields | Optional fields |
+|------|---------|-----------------|-----------------|
+| `1` Project | `project` | `project_key` | — |
+| `3` WorkItem | `work_item` | `project_key`, `work_item_type_key`, `work_item_id` | — |
+| `4` View | `view` | `project_key`, `view_id` | `work_item_type_key` |
+| `5` MeasureChart | `measure_chart` | `project_key`, `chart_id` | — |
+
+Context type `2` is reserved by the IDL for the currently unsupported WorkItemType context and must not be used.
+
+Each attempt is bounded by a per-attempt timeout, and transient transport failures (timeout, HTTP 5xx/429, network errors) are retried up to 3 times with exponential backoff and jitter. `create-link` sends a stable idempotency key that is reused across those retries, so a retried request never creates a second link. Policy, validation, and 4xx errors fail fast without retrying. Facade invalid-parameter envelopes are reported as `HANDOFF_API_INVALID_PARAM` with `retryable=false`, including payloads that exceed the negotiated query or context limits. Internal Facade biz error IDs, causes, and chains are not exposed; the CLI returns a concise message plus a suggestion to inspect the current limits with `ai-handoff availability`.
+
+### preference — Personal Preferences
+
+Handoff suggestion mode is stored in the server-side unified user preference service. It has no project or tenant argument and defaults to `auto` when no override exists. The generic write request carries a `preferences` list with `type=handoff_suggestions`; its payload is `{"mode":"off|ask|auto"}`. A successful mode update invalidates the local `ai-handoff availability` cache.
+
+| Command | Description |
+|---------|-------------|
+| `preference handoff auto` | Automatically show AI handoff recommendations |
+| `preference handoff ask` | Ask before showing an AI handoff recommendation |
+| `preference handoff off` | Disable AI handoff recommendations |
+
+Use `meegle preference handoff --help` for mode behavior and `meegle inspect preference handoff auto` (or `ask` / `off`) for the command-level parameter view.
+
+`reset` is intentionally not exposed until the preference service provides an atomic unset operation.
+
 ### auth — Authentication
 
 | Command | Description |
@@ -658,6 +742,8 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--auto-paginate` | | Automatically fetch and merge all pages when the response contains pagination signals (`next_page_token` or `pagination.has_more`); merged list arrays are concatenated, and a 200-page safety cap plus a 3-empty-page streak guard prevent runaway loops |
 | `--version` | | Print the CLI version and exit (alias of `meegle version`) |
 
+`--version` is treated as the version alias only when it is a standalone flag. If a preceding string flag is waiting for a value, the literal `--version` remains that flag's value.
+
 ## Advanced Usage
 
 ### Output Formats
@@ -726,6 +812,11 @@ carries the backend trace id (when the server returns one). Hand that id
 to oncall to look up the request in argos. Without `--envelope` the id is
 suppressed so the default output stays clean for piping.
 
+AI handoff Config, Preference, and Create Link responses also copy the gateway
+`x-tt-logid` response header to `meta.logid`. Successful calls expose it only
+with `--envelope`; failures include it in their structured error envelope
+automatically. No debug logging is required.
+
 ### Dry Run
 
 For commands with side effects, preview the rendered request with `--dry-run` before executing:
@@ -758,6 +849,10 @@ escape sequences retain their backslash.
 This decoding only applies to programmatic command-string entry points such as
 `CommandClient.Execute` and `ExecuteCommandString`. The `meegle` binary receives
 an argument array from the shell, so normal shell quoting rules apply there.
+The command-string Go SDK used by Facade for remote RPC execution registers only
+MCP-discovered commands. Local CLI API commands such as `ai-handoff` and
+`preference handoff` are available only in the npm-distributed `meegle` CLI;
+direct `CallTool` also continues to address MCP tools only.
 
 ## Authentication
 
@@ -840,16 +935,17 @@ Main config options:
 
 ### Sandbox / CI: Direct Environment-Variable Injection
 
-Two well-known environment variables are read directly at CLI startup and override the matching profile fields without requiring any `config set`:
+The following well-known environment variables are read directly by the CLI without requiring any `config set`:
 
 ```bash
 export MEEGLE_HOST=project.feishu.cn
 export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
 export MEEGLE_USER_AGENT=ci-runner  # optional; appended to User-Agent, highest priority over config.user_agent
+export MEEGLE_AI_HANDOFF=disabled   # optional; locally hard-disable AI Handoff
 meegle workitem get --work-item-id 123
 ```
 
-Either variable may be set independently. When `MEEGLE_USER_ACCESS_TOKEN` is set, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value. Setting only `MEEGLE_HOST` (without a token) still uses the keychain-stored credentials.
+These variables may be set independently. When `MEEGLE_USER_ACCESS_TOKEN` is set, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value. Setting only `MEEGLE_HOST` (without a token) still uses the keychain-stored credentials. `MEEGLE_AI_HANDOFF=disabled` is a disable-only local gate and does not alter profile configuration.
 
 ### Custom Auth Header
 
@@ -883,7 +979,7 @@ If your runtime exposes a variable with a name other than `MEEGLE_*`, bind it th
 
 Rules:
 - Only whole-string placeholders are recognized. `"${X}"` is expanded; `"Bearer ${X}"` is treated as a literal.
-- When a referenced variable is unset or empty, the CLI fails fast and reports the field path and variable name.
+- When a referenced variable is unset or empty, commands that require credentials fail fast and report the field path and variable name. Recovery entry points such as `--help`, `version`, `auth login --help`, and `config set` remain available so the profile can be repaired.
 - When `user_access_token` is configured, it takes precedence over any token stored locally by `meegle auth login`. Because this mode has no refresh path, rotate the environment value yourself when the server returns 401.
 
 ### Multi-Environment Profiles
@@ -910,6 +1006,22 @@ meegle mywork todo --action this_week --page-num 1 --profile staging
 meegle config profile delete staging
 ```
 
+## Enterprise CLI Extensions
+
+Companies can depend on this Go module, register trusted in-process adapters, and build their own `meegle` binary without modifying the official repository. V1 supports three extension seams:
+
+- `extension/credential` selects an account and supplies an existing Meegle user token. Known local/recovery commands bootstrap without invoking Credential providers, so a slow OIDC provider cannot block help, version, configuration repair, completion, URL parsing, or extension diagnostics; commands that need identity still resolve the provider and fail closed on any provider error.
+- `extension/transport` observes or blocks CLI HTTP requests while retaining redirect and TLS-downgrade protections. Provider and hook callbacks have a 30-second safety timeout, but the real MCP, OAuth, and attachment request keeps the caller's Context and original HTTP client timeout, so enabling an extension does not shorten large uploads, downloads, or slow server operations. Its trusted in-process pre-hook sees the credential-injected live request and can technically change authentication headers; the CLI does not provide in-process isolation or freeze header values. Its post-hook receives an isolated metadata snapshot with `http.NoBody` and a cloned TLS state, so a stalled hook cannot consume, retain, or mutate the live response stream. Credential-bearing MCP requests—default Bearer or custom token header—retain a 10-redirect limit and are never redirected away from their exact original origin.
+- `extension/platform` observes, wraps, or restricts both static commands and MCP-discovered dynamic commands. Plugin metadata/Install and each Startup hook have a two-second safety boundary; a timed-out fail-open plugin is skipped, while fail-closed stops the CLI, and late registration is ignored. Restrict plugins must be fail-closed; a hand-written plugin that declares `Restricts=true` with `FailurePolicy=FailOpen` fails startup instead of being silently skipped.
+
+Use `cmd.ExecuteWithVersion(version)` for an enterprise binary whose plugins declare `RequireCLI`; `cmd.Execute()` remains the compatible default entry point. A `dev` build deliberately cannot satisfy a version constraint and its compatibility error points to `ExecuteWithVersion`; this fail-closed check is not bypassed. Extensions are linked at build time—there is no runtime plugin download—and the SDK does not load CLI extension registries. See [all extension examples](./examples/README.md) and the [architecture contract](./docs/design/CLI-EXTENSION-ARCHITECTURE.md).
+
+An extension-enabled binary exposes non-secret diagnostics under `meegle extension doctor|credentials|transport|plugins|policy|discovery`. Credential and transport diagnostics distinguish `not-evaluated`, `active`, and `failed` instead of re-running providers during an offline diagnostic command. Restrict rules also govern these commands, so a readonly allow-list should include `extension/**` when operators need troubleshooting access.
+Policy denials honor explicit structured output modes and use the stable `CLIENT_COMMAND_DENIED` error code. Credential and Platform failures that happen before CLI App construction also honor explicit JSON/NDJSON output and expose `CLIENT_CREDENTIAL_RESOLUTION_FAILED` or `CLIENT_EXTENSION_INSTALL_FAILED` instead of plain text.
+Errors and panic values returned by extension callbacks stay behind a guarded Go error-chain boundary: custom `Is`, `As`, `Unwrap`, `Error`, or payload methods cannot crash the CLI, and panic details cannot enter public output. Extension code should still return ordinary, context-aware errors because it runs as trusted code in the CLI process.
+Every JSON-RPC response is bounded before decoding: `tools/list` uses an 8 MiB discovery limit and all other calls use a 32 MiB per-response limit.
+Dynamic discovery accepts nullable JSON Schema types such as `"type": ["string", "null"]` and exposes them as the underlying CLI/SDK parameter type. Unions containing multiple non-null types are isolated with the stable `unsupported_schema_union` diagnostic instead of silently removing unrelated tools.
+
 ## FAQ
 
 ### Empty Command List

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 飞书项目（[Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) / [Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)）命令行工具。在终端中管理工作项、查看排期、搜索数据，无需打开浏览器。
 
-[安装](#安装) · [快速开始](#快速开始人类用户) · [Agent Skill](#ai-agent-skill) · [命令](#命令一览) · [认证](#认证) · [配置](#配置) · [安全](#安全与风险提示) · [贡献](#贡献)
+[安装](#安装) · [快速开始](#快速开始人类用户) · [Agent Skill](#ai-agent-skill) · [命令](#命令一览) · [企业扩展](#企业-cli-扩展) · [认证](#认证) · [配置](#配置) · [安全](#安全与风险提示) · [贡献](#贡献)
 
 ## 为什么选择 Meegle CLI？
 
@@ -17,6 +17,7 @@
 - **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
 - **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
 - **默认安全** — 凭证存进系统 keychain、`${VAR}` 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod
+- **支持企业扩展** — 企业通过编译期引用公开的 `cmd`、Credential、Transport、Platform 包构建自己的发行版，无需 Fork 本仓库
 
 ## 功能概览
 
@@ -55,6 +56,26 @@ npx @lark-project/meegle@latest install
 
 向导会全局安装或升级 CLI、安装 AI Agent Skill、配置 Meegle host，并启动登录。
 
+### 自动更新提示
+
+通过 npm 分发的 CLI 在交互式终端启动时，最多每 24 小时检查一次 npm 最新版本。发现新版本后，会从 [CHANGELOG](https://github.com/larksuite/meegle-cli/blob/main/CHANGELOG.md#changed) 提取当前版本到最新版本之间已经发布的 `Added` 和 `Changed` 条目，并展示交互式功能上新提示：
+
+```text
+✨ Meegle CLI 有新版本: v<当前版本> → v<最新版本>
+
+功能上新:
+  v<版本号>
+    • 新增: <功能摘要>
+
+❯ 立即更新（推荐）
+  稍后提醒
+  使用 ↑/↓ 选择，按 Enter 确认
+```
+
+直接按 Enter 会先执行 `npm install -g @lark-project/meegle@latest` 更新 CLI，再通过 `meegle install` 使用的同一套安装方式 best-effort 更新 Meegle Agent Skill，最后继续原命令。当前环境缺少合适的 Skill 安装器、安装器不兼容或 Skill 下载失败时，只会提示已跳过，不会把成功的 CLI 更新改判为失败。选择**稍后提醒**后，24 小时内不再检查。这个轻量更新流程不会重新配置 host 或触发登录；需要完整的一站式设置时仍可运行 `meegle install`。
+
+非交互/CI 环境、stdout 被管道接走、执行 `install` 或 Shell 补全命令时会跳过检查，保证结构化命令输出不变。也可以设置 `MEEGLE_NO_UPDATE_CHECK=1` 显式关闭。
+
 ## 快速开始（人类用户）
 
 > **给 AI Agent 的提示：** 如果你是在替用户完成这套安装的 AI Agent，请直接跳到 [快速开始（AI Agent）](#快速开始ai-agent--ci--无头环境) —— 那里有你需要的非交互命令。
@@ -246,6 +267,69 @@ Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--
 | `wbs get-draft-progress` | 查询计划表草稿操作（创建 / 编辑 / 发布）的执行进度 |
 | `wbs list-element-templates` | 列出流程资源库中的资源节点与资源任务模板 |
 
+### ai-handoff — AI 助手接力
+
+这组命令由 CLI 本地注册，不属于 MCP tool。`availability` 是准备 `query` 或关联上下文前的可选预检；预期内的业务拒绝属于成功探测，返回稳定的 `reject_code` 和仅用于展示的 `reject_msg`。依赖或传输异常走 CLI 通用错误模型。
+
+`availability` 读取通用 `GET /goapi/v5/meeglecli/config` 探测结果中的 Handoff 配置及其 `mode`（`off`、`ask`、`auto`）。CLI 按 profile 缓存成功返回的完整配置快照至多 1 小时，依赖或传输异常不缓存。`preference handoff auto|ask|off` 成功、`auth login`、以及 `create-link` 被服务端拒绝时会立即失效配置缓存。`create-link` 不读缓存：它始终在服务端二次校验并直接创建链接。
+
+create-link HTTP 响应始终包含 `available`：正常情况返回 HTTP 200 和 `available=true + url`；CLI 随后只把该 URL 的 host（含配置的端口）替换为当前登录域名，保留 scheme、path、query 和 fragment，使链接始终落在当前选择的 Meegle 或飞书项目环境。业务预期内的不可用返回 HTTP 200 和 `available=false + reject_code + reject_msg`，同时清理本地配置缓存；非预期异常走接口通用错误响应。
+
+设置 `MEEGLE_AI_HANDOFF=disabled` 可在当前安装环境中硬禁用 Handoff。此时 `availability` 和参数合法的 `create-link` 都会返回 `available=false`、`reject_code=LOCAL_DISABLED` 及仅用于展示的 `reject_msg`，不要求登录、不读取 availability 缓存，也不调用 Handoff API。未设置或值不是 `disabled` 时保持原有的服务端控制行为。本地门禁只能关闭功能，不能绕过服务端业务开关、权益或个人偏好将功能强制打开。
+
+| 命令 | 说明 |
+|------|------|
+| `ai-handoff availability` | 检查业务开关、灰度、AI 助手权益、个人偏好和链接服务可用性 |
+| `ai-handoff create-link` | 根据必填的 `--query` 和可选、可重复的类型化 `--related-context` JSON 对象生成 AI 助手链接 |
+
+```bash
+meegle ai-handoff availability --format json
+
+MEEGLE_AI_HANDOFF=disabled meegle ai-handoff availability --format json
+
+meegle ai-handoff create-link --params '{
+  "query": "总结风险并给出下一步行动建议",
+  "related_context": [{
+    "type": 3,
+    "work_item": {
+      "project_key": "PROJ",
+      "work_item_type_key": "story",
+      "work_item_id": "123"
+    }
+  }]
+}' --format json
+
+meegle ai-handoff create-link --help
+meegle inspect ai-handoff create-link
+```
+
+每个 `related_context` 元素必须设置 `type`，并且只设置一个与类型匹配的 payload。Facade 契约只使用业务标识，不对外暴露 AI 服务的通用 `key`；只有转换为内部 `query + entities` 契约时才补齐该字段：
+
+| Type | Payload | 必填字段 | 可选字段 |
+|------|---------|----------|----------|
+| `1` Project | `project` | `project_key` | — |
+| `3` WorkItem | `work_item` | `project_key`、`work_item_type_key`、`work_item_id` | — |
+| `4` View | `view` | `project_key`、`view_id` | `work_item_type_key` |
+| `5` MeasureChart | `measure_chart` | `project_key`、`chart_id` | — |
+
+上下文类型 `2` 是 IDL 为当前暂不支持的 WorkItemType 上下文保留的枚举值，请勿使用或复用。
+
+每次尝试都有独立的超时保护，可重试的传输失败（超时、HTTP 5xx/429、网络错误）会以指数退避加抖动的方式最多重试 3 次。`create-link` 会携带一个稳定的幂等键，并在这些重试中保持不变，因此重试不会创建第二条链接。策略、参数校验和 4xx 错误会快速失败，不做重试。Facade 返回的参数错误信封会映射为 `HANDOFF_API_INVALID_PARAM` 且 `retryable=false`，包括 query 或 context 数量超过协商上限的情况。CLI 不暴露 Facade 内部的 biz error id、cause 或 chain，只返回简洁消息，并建议通过 `ai-handoff availability` 查看当前限制。
+
+### preference — 个人偏好
+
+Handoff Suggestions 偏好存储在服务端统一用户偏好服务中，不接收项目或租户参数；不存在用户覆盖值时默认 `auto`。通用偏好写接口使用 `preferences` 列表，当前 item 的 `type=handoff_suggestions`，payload 为 `{"mode":"off|ask|auto"}`；成功仅表示写入完成。读取当前配置统一走 CLI config 探测接口。模式写入成功后会失效本地配置缓存，使变更在下次探测时生效。
+
+| 命令 | 说明 |
+|------|------|
+| `preference handoff auto` | 自动展示 AI Handoff 推荐 |
+| `preference handoff ask` | 展示 AI Handoff 推荐前先询问 |
+| `preference handoff off` | 关闭 AI Handoff 推荐 |
+
+使用 `meegle preference handoff --help` 查看模式行为，使用 `meegle inspect preference handoff auto`（或 `ask` / `off`）查看命令级参数说明。
+
+在偏好服务提供原子 unset 能力前，MVP 不开放 `reset`。
+
 ### auth — 认证域
 
 | 命令 | 说明 |
@@ -640,6 +724,8 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--auto-paginate` | | 当响应包含分页信号（`next_page_token` 或 `pagination.has_more`）时自动拉取并合并所有页；列表数组会拼接，200 页安全上限与连续 3 空页保护防止失控循环 |
 | `--version` | | 输出 CLI 版本号并退出（`meegle version` 的别名） |
 
+只有作为独立 Flag 时，`--version` 才表示版本别名；如果前面的字符串 Flag 正在等待参数值，字面量 `--version` 会保留为该 Flag 的值。
+
 ## 进阶用法
 
 ### 输出格式
@@ -698,6 +784,10 @@ meegle workflow update-node --work-item-id 12345 \
 `meta.logid` 里——把这个 id 交给 oncall 就能在 argos 定位到这次请求。
 不加 `--envelope` 时 logid 会被抑制，保持默认输出干净便于管道处理。
 
+AI Handoff 的 Config、Preference、Create Link 响应也会把网关响应头 `x-tt-logid`
+写入 `meta.logid`：成功时仅在指定 `--envelope` 后展示，失败时自动进入结构化错误
+envelope，无需开启 debug 日志。
+
 ### Dry Run
 
 有副作用的命令先用 `--dry-run` 预览请求再执行：
@@ -728,6 +818,9 @@ meegle inspect workitem.create
 该解码只作用于 `CommandClient.Execute`、`ExecuteCommandString` 等程序化
 命令字符串入口。`meegle` 二进制直接接收 shell 解析后的参数数组，因此仍遵循
 对应 shell 的引号和转义规则。
+供 Facade 远程 RPC 调用的命令字符串 Go SDK 只注册 MCP 动态发现命令。
+`ai-handoff`、`preference handoff` 等本地 CLI API 命令只在 npm 分发的
+`meegle` CLI 中提供；直接调用 `CallTool` 时也仍然只访问 MCP tool。
 
 ## 认证
 
@@ -809,16 +902,17 @@ meegle config get host
 
 ### 沙盒 / CI：直接注入环境变量
 
-`MEEGLE_HOST` 和 `MEEGLE_USER_ACCESS_TOKEN` 两个约定名环境变量会在 CLI 启动时被直接读取，覆盖 profile 中的同名字段，无需任何 `config set`：
+CLI 会直接读取以下约定名环境变量，无需执行任何 `config set`：
 
 ```bash
 export MEEGLE_HOST=project.feishu.cn
 export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
 export MEEGLE_USER_AGENT=ci-runner  # 可选；追加到 User-Agent，优先级高于 config.user_agent
+export MEEGLE_AI_HANDOFF=disabled   # 可选；在本地硬禁用 AI Handoff
 meegle workitem get --work-item-id 123
 ```
 
-任一变量可以单独设置。当 `MEEGLE_USER_ACCESS_TOKEN` 设置时，CLI 不访问 keychain，401 错误不会自动 refresh，由调用方自行轮转。仅设置 `MEEGLE_HOST`（不带 token）时仍走 keychain 中存储的凭证。
+各变量可以单独设置。当 `MEEGLE_USER_ACCESS_TOKEN` 设置时，CLI 不访问 keychain，401 错误不会自动 refresh，由调用方自行轮转。仅设置 `MEEGLE_HOST`（不带 token）时仍走 keychain 中存储的凭证。`MEEGLE_AI_HANDOFF=disabled` 只是本地禁用门禁，不修改 profile 配置。
 
 ### 自定义 Auth Header
 
@@ -852,7 +946,7 @@ export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth
 
 规则：
 - 仅识别**整串形态**的占位符。`"${X}"` 会被展开；`"Bearer ${X}"` 按字面量处理，不展开。
-- 引用的环境变量未设置或为空时 CLI **fail fast**，错误信息会带上字段路径和变量名。
+- 引用的环境变量未设置或为空时，需要凭证的业务命令会 **fail fast**，错误信息会带上字段路径和变量名；`--help`、`version`、`auth login --help`、`config set` 等自救入口仍可运行，方便修复 profile。
 - 当配置了 `user_access_token` 时，它会覆盖 `meegle auth login` 在本地 keychain 里写入的令牌。由于这种模式下没有本地 refresh 能力，服务端返回 401 时需要自行轮转环境变量值。
 
 ### 多环境 Profile
@@ -879,6 +973,22 @@ meegle mywork todo --action this_week --page-num 1 --profile staging
 meegle config profile delete staging
 ```
 
+## 企业 CLI 扩展
+
+企业可以直接依赖本 Go Module，注册可信的进程内适配器并构建自己的 `meegle` 二进制，无需修改官方仓库。V1 提供三个扩展点：
+
+- `extension/credential` 选择账号，并提供现有的 Meegle 用户 Token。已知的本地/自救命令在启动时不会调用 Credential Provider，因此慢 OIDC Provider 不会阻塞帮助、版本、配置修复、补全、URL 解析或扩展诊断；需要身份的命令仍会解析 Provider，任何 Provider 错误都会 fail-closed。
+- `extension/transport` 观察或阻断 CLI HTTP 请求，同时保留重定向和 TLS 防降级约束。Provider 和 Hook 回调有 30 秒安全超时，但真实 MCP、OAuth 和附件请求继续使用调用方 Context 与原 HTTP Client timeout，因此启用扩展不会截断大文件上传下载或慢服务端操作；可信的进程内前置 Hook 会看到注入凭证后的真实请求，技术上可以修改认证 Header，CLI 不提供进程内隔离也不会冻结 Header 值；后置 Hook 只接收 `Body=http.NoBody`、TLS 状态也已复制的隔离元数据快照，阻塞的 Hook 不会消费、占住或修改真实响应流；携带默认 Bearer 或自定义 Token Header 的 MCP 请求都保留 10 跳上限，且不会被重定向到原始精确 origin 之外。
+- `extension/platform` 观察、包装或限制静态命令和 MCP 动态发现命令。插件元数据/Install 和每个 Startup Hook 都有两秒安全边界；fail-open 插件超时后跳过，fail-closed 会终止 CLI，迟到注册会被忽略。Restrict 插件必须 fail-closed；手写插件如果同时声明 `Restricts=true` 和 `FailurePolicy=FailOpen`，CLI 会启动失败，不会静默跳过策略。
+
+企业插件声明 `RequireCLI` 时，入口应调用 `cmd.ExecuteWithVersion(version)`；`cmd.Execute()` 仍是兼容的默认入口。`dev` 构建会按设计拒绝版本约束，兼容性错误会提示改用 `ExecuteWithVersion`，不会绕过 fail-closed 校验。扩展在编译时链接，不支持运行时下载插件；SDK 也不会加载 CLI 的全局扩展注册表。完整用法见[扩展示例](./examples/README.md)和[架构契约](./docs/design/CLI-EXTENSION-ARCHITECTURE.md)。
+
+扩展版二进制可通过 `meegle extension doctor|credentials|transport|plugins|policy|discovery` 查看脱敏后的诊断信息。Credential 与 Transport 诊断会区分 `not-evaluated`、`active`、`failed`，离线诊断不会为了显示状态而重新调用 Provider。Restrict 同样治理这些命令；需要保留排障入口时，readonly Allow 列表应包含 `extension/**`。
+Policy 拒绝遵循显式结构化输出格式，并使用稳定错误码 `CLIENT_COMMAND_DENIED`。CLI App 构造前发生的 Credential 与 Platform 失败也遵循显式 JSON/NDJSON 输出，分别暴露 `CLIENT_CREDENTIAL_RESOLUTION_FAILED` 或 `CLIENT_EXTENSION_INSTALL_FAILED`，不会退化成纯文本。
+扩展回调返回的 error 和 panic 值会留在受保护的 Go 错误链边界内；自定义 `Is`、`As`、`Unwrap`、`Error` 或错误载荷方法不能让 CLI 崩溃，panic 细节也不会进入公开输出。扩展仍属于进程内可信代码，实现方应返回普通且遵守 Context 的错误。
+所有 JSON-RPC 响应都会在解码前限制大小：`tools/list` 使用 8 MiB 的发现上限，其他调用使用每次响应 32 MiB 的通用上限。
+动态发现支持 `"type": ["string", "null"]` 这类 nullable JSON Schema，并在 CLI/SDK 中按其非 null 类型注册参数。包含多个非 null 类型的 union 会被单项隔离，并输出稳定的 `unsupported_schema_union` 诊断，不影响其他工具。
+
 ## 常见问题
 
 ### 命令列表为空

package/bin/install-wizard.js

@@ -157,6 +157,20 @@ function runCapture(cmd, args, opts = {}) {
   });
 }
 
+// installAgentSkill is shared by the full install wizard and the lightweight
+// startup updater. The wizard keeps strict failure semantics, while the
+// updater passes bestEffort=true so an unavailable Skill installer never
+// changes a successful CLI upgrade into a failure.
+function installAgentSkill({ bestEffort = false, runFn = run } = {}) {
+  try {
+    runFn("npm", ["exec", "--yes", "--package=skills", "--", "skills", "add", SKILLS_REPO, "-y", "-g"], { timeout: 120000 });
+    return true;
+  } catch (err) {
+    if (!bestEffort) throw err;
+    return false;
+  }
+}
+
 function question(prompt) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -274,7 +288,7 @@ async function stepInstallSkills(msg) {
   // skill just upgrades / no-ops. We always run it instead of trying to detect
   // prior installs — name-substring detection mis-fired on sibling skills like
   // `meegle-plugin` and silently skipped the core skill.
-  run("npm", ["exec", "--yes", "--package=skills", "--", "skills", "add", SKILLS_REPO, "-y", "-g"], { timeout: 120000 });
+  installAgentSkill();
   console.log(msg.skillsDone);
 }
 
@@ -375,4 +389,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main };
+module.exports = { installAgentSkill, main };

package/bin/meegle.js

@@ -3,6 +3,8 @@ const { spawnSync } = require("child_process");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const { maybeCheckForUpdates } = require("./update-notifier.js");
+const packageJSON = require("../package.json");
 
 const SUPPORTED = [
   "darwin-arm64", "darwin-x64",
@@ -15,14 +17,13 @@ const arch = os.arch();
 const ext = platform === "win32" ? ".exe" : "";
 const binName = `meegle-${platform}-${arch}${ext}`;
 const binPath = path.join(__dirname, binName);
-const args = process.argv.slice(2);
 
-if (args[0] === "install") {
-  Promise.resolve(require("./install-wizard.js").main(args.slice(1))).catch((err) => {
-    console.error("Unexpected install error:", err && err.message ? err.message : err);
-    process.exit(1);
-  });
-} else {
+async function main(args = process.argv.slice(2)) {
+  if (args[0] === "install") {
+    await require("./install-wizard.js").main(args.slice(1));
+    return 0;
+  }
+
   try {
     fs.accessSync(binPath, fs.constants.X_OK);
   } catch {
@@ -38,15 +39,43 @@ if (args[0] === "install") {
         : `Unsupported platform: ${detected}\n` +
           `Supported platforms: ${SUPPORTED.join(", ")}`
     );
-    process.exit(1);
+    return 1;
   }
 
-  const result = spawnSync(binPath, args, { stdio: "inherit" });
+  let commandBinPath = binPath;
+  try {
+    const update = await maybeCheckForUpdates({
+      args,
+      currentVersion: packageJSON.version,
+      binName,
+    });
+    if (update.updated && update.binaryPath) commandBinPath = update.binaryPath;
+  } catch (err) {
+    if (err && err.code === "UPDATE_PROMPT_INTERRUPTED") {
+      process.kill(process.pid, "SIGINT");
+      return 130;
+    }
+    // The update notifier is best-effort. A registry, GitHub, cache, or prompt
+    // failure must never prevent the user's actual CLI command from running.
+  }
+
+  const result = spawnSync(commandBinPath, args, { stdio: "inherit" });
 
   // Re-raise the signal so parent shells see the real cause (e.g. 130 for SIGINT)
   // instead of a generic exit 1.
   if (result.signal) {
     process.kill(process.pid, result.signal);
   }
-  process.exit(result.status ?? 1);
+  return result.status ?? 1;
+}
+
+if (require.main === module) {
+  main().then((status) => {
+    process.exit(status);
+  }).catch((err) => {
+    console.error("Unexpected meegle error:", err && err.message ? err.message : err);
+    process.exit(1);
+  });
 }
+
+module.exports = { main };

package/bin/update-notifier.js

@@ -0,0 +1,544 @@
+#!/usr/bin/env node
+const { execFileSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+
+const PKG = "@lark-project/meegle";
+const CHANGELOG_URL = "https://github.com/larksuite/meegle-cli/blob/main/CHANGELOG.md#changed";
+const CHANGELOG_RAW_URL = "https://raw.githubusercontent.com/larksuite/meegle-cli/main/CHANGELOG.md";
+const CACHE_SCHEMA_VERSION = 1;
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_RETRY_MS = 60 * 60 * 1000;
+const NETWORK_TIMEOUT_MS = 5000;
+const MAX_CHANGELOG_BYTES = 1024 * 1024;
+const MAX_FEATURE_ITEMS = 8;
+
+const messages = {
+  en: {
+    title: "Meegle CLI update available",
+    whatsNew: "What's new",
+    added: "Added",
+    changed: "Changed",
+    maintenance: "This update mainly contains fixes and maintenance changes.",
+    omitted: "... and %s more feature changes",
+    changelog: "Full changelog",
+    updateNow: "Update now (recommended)",
+    later: "Remind me later",
+    hint: "Use ↑/↓ to select, then press Enter",
+    updating: "Updating @lark-project/meegle to v%s...\n",
+    updated: "✓ Meegle CLI updated to v%s.\n",
+    skillUpdating: "Updating the Meegle Agent Skill (best effort)...\n",
+    skillUpdated: "✓ Meegle Agent Skill updated.\n",
+    skillSkipped: "! Meegle Agent Skill update was unavailable; the CLI update is still complete.\n",
+    continuing: "Continuing with your command...\n\n",
+    updateFailed: "Could not update automatically. Continue with the current version and retry later:\n  npm install -g @lark-project/meegle@latest\n\n",
+  },
+  zh: {
+    title: "Meegle CLI 有新版本",
+    whatsNew: "功能上新",
+    added: "新增",
+    changed: "变化",
+    maintenance: "本次更新以问题修复和维护性改进为主。",
+    omitted: "……另有 %s 项功能变化",
+    changelog: "完整更新日志",
+    updateNow: "立即更新（推荐）",
+    later: "稍后提醒",
+    hint: "使用 ↑/↓ 选择，按 Enter 确认",
+    updating: "正在将 @lark-project/meegle 更新到 v%s...\n",
+    updated: "✓ Meegle CLI 已更新到 v%s。\n",
+    skillUpdating: "正在尝试更新 Meegle Agent Skill（失败不影响 CLI 更新）...\n",
+    skillUpdated: "✓ Meegle Agent Skill 已更新。\n",
+    skillSkipped: "! 当前环境无法更新 Meegle Agent Skill；CLI 已成功更新。\n",
+    continuing: "将继续执行当前命令。\n\n",
+    updateFailed: "自动更新失败，将继续使用当前版本。你可以稍后手动执行：\n  npm install -g @lark-project/meegle@latest\n\n",
+  },
+};
+
+function fmt(template, ...values) {
+  let index = 0;
+  return template.replace(/%s/g, () => String(values[index++] ?? ""));
+}
+
+function localeFromEnv(env = process.env) {
+  const locale = [env.LC_ALL, env.LC_MESSAGES, env.LANG, env.LANGUAGE]
+    .find((value) => typeof value === "string" && value.trim() !== "") || "";
+  return locale.toLowerCase().startsWith("zh") ? "zh" : "en";
+}
+
+function parseSemver(raw) {
+  const match = String(raw || "").trim().match(
+    /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+  const count = Math.max(left.length, right.length);
+  for (let index = 0; index < count; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    if (left[index] === right[index]) continue;
+    const leftNumber = /^\d+$/.test(left[index]) ? Number(left[index]) : null;
+    const rightNumber = /^\d+$/.test(right[index]) ? Number(right[index]) : null;
+    if (leftNumber !== null && rightNumber !== null) return leftNumber < rightNumber ? -1 : 1;
+    if (leftNumber !== null) return -1;
+    if (rightNumber !== null) return 1;
+    return left[index].localeCompare(right[index]) < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+function compareVersions(leftRaw, rightRaw) {
+  const left = parseSemver(leftRaw);
+  const right = parseSemver(rightRaw);
+  if (!left || !right) return null;
+  for (const field of ["major", "minor", "patch"]) {
+    if (left[field] !== right[field]) return left[field] < right[field] ? -1 : 1;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+function isNewerVersion(candidate, current) {
+  return compareVersions(candidate, current) === 1;
+}
+
+function parseFeatureItems(section) {
+  const items = [];
+  let category = "";
+  let activeItem = null;
+  for (const line of section.split(/\r?\n/)) {
+    const heading = line.match(/^###\s+(Added|Changed)\s*$/i);
+    if (heading) {
+      category = heading[1].toLowerCase();
+      activeItem = null;
+      continue;
+    }
+    if (/^###\s+/.test(line)) {
+      category = "";
+      activeItem = null;
+      continue;
+    }
+    if (!category) continue;
+    const bullet = line.match(/^-\s+(.+)/);
+    if (bullet) {
+      activeItem = { category, text: bullet[1].trim() };
+      items.push(activeItem);
+      continue;
+    }
+    if (activeItem && /^\s{2,}\S/.test(line)) {
+      activeItem.text += ` ${line.trim()}`;
+    }
+  }
+  return items;
+}
+
+function parseReleaseNotes(markdown, currentVersion, latestVersion) {
+  const source = String(markdown || "");
+  const headingPattern = /^## \[v?([^\]]+)\](?:\s+-\s+.*)?\s*$/gm;
+  const headings = Array.from(source.matchAll(headingPattern));
+  const releases = [];
+  for (let index = 0; index < headings.length; index += 1) {
+    const version = headings[index][1].trim();
+    const newerThanCurrent = compareVersions(version, currentVersion);
+    const noNewerThanLatest = compareVersions(version, latestVersion);
+    if (newerThanCurrent !== 1 || noNewerThanLatest === null || noNewerThanLatest > 0) continue;
+    const start = headings[index].index + headings[index][0].length;
+    const end = index + 1 < headings.length ? headings[index + 1].index : source.length;
+    releases.push({ version, items: parseFeatureItems(source.slice(start, end)) });
+  }
+  releases.sort((left, right) => compareVersions(right.version, left.version) || 0);
+  return releases;
+}
+
+function sanitizeMarkdown(text) {
+  return String(text || "")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/[`*_~]/g, "")
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function truncate(text, maxLength) {
+  const chars = Array.from(text);
+  if (chars.length <= maxLength) return text;
+  return `${chars.slice(0, Math.max(1, maxLength - 1)).join("")}…`;
+}
+
+function renderUpdateNotice({ currentVersion, latestVersion, releases, locale = "en", columns = 100 }) {
+  const msg = messages[locale] || messages.en;
+  const lines = [
+    "",
+    `✨ ${msg.title}: v${currentVersion} → v${latestVersion}`,
+    "",
+    `${msg.whatsNew}:`,
+  ];
+  const allItems = releases.flatMap((release) =>
+    release.items.map((item) => ({ ...item, version: release.version })),
+  );
+  const maxTextLength = Math.max(60, Math.min(180, Number(columns || 100) - 18));
+  let displayed = 0;
+  let previousVersion = "";
+  for (const item of allItems.slice(0, MAX_FEATURE_ITEMS)) {
+    if (item.version !== previousVersion) {
+      lines.push(`  v${item.version}`);
+      previousVersion = item.version;
+    }
+    const category = item.category === "added" ? msg.added : msg.changed;
+    lines.push(`    • ${category}: ${truncate(sanitizeMarkdown(item.text), maxTextLength)}`);
+    displayed += 1;
+  }
+  if (displayed === 0) lines.push(`  • ${msg.maintenance}`);
+  if (allItems.length > displayed) lines.push(`  ${fmt(msg.omitted, allItems.length - displayed)}`);
+  lines.push("", `${msg.changelog}: ${CHANGELOG_URL}`, "");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderChoices(output, msg, selected, rerender) {
+  if (rerender) {
+    readline.cursorTo(output, 0);
+    readline.moveCursor(output, 0, -2);
+    readline.clearScreenDown(output);
+  }
+  const marker = (index) => (selected === index ? "❯" : " ");
+  output.write([
+    `${marker(0)} ${msg.updateNow}`,
+    `${marker(1)} ${msg.later}`,
+    `  ${msg.hint}`,
+  ].join("\n"));
+}
+
+function selectUpdateAction({ input = process.stdin, output = process.stderr, locale = "en" } = {}) {
+  const msg = messages[locale] || messages.en;
+  if (!input.isTTY || !output.isTTY) return Promise.resolve("later");
+  readline.emitKeypressEvents(input);
+  const wasRaw = Boolean(input.isRaw);
+  const wasPaused = typeof input.isPaused === "function" ? input.isPaused() : true;
+  if (typeof input.setRawMode === "function") input.setRawMode(true);
+  input.resume();
+  let selected = 0;
+  let rendered = false;
+
+  return new Promise((resolve, reject) => {
+    function cleanup() {
+      input.removeListener("keypress", onKeypress);
+      if (typeof input.setRawMode === "function" && !wasRaw) input.setRawMode(false);
+      if (wasPaused && typeof input.pause === "function") input.pause();
+      output.write("\n");
+    }
+
+    function onKeypress(_value, key = {}) {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        const err = new Error("update prompt interrupted");
+        err.code = "UPDATE_PROMPT_INTERRUPTED";
+        reject(err);
+        return;
+      }
+      if (key.name === "up" || key.name === "down") {
+        selected = selected === 0 ? 1 : 0;
+        renderChoices(output, msg, selected, rendered);
+        rendered = true;
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        resolve(selected === 0 ? "update" : "later");
+      }
+    }
+
+    input.on("keypress", onKeypress);
+    renderChoices(output, msg, selected, rendered);
+    rendered = true;
+  });
+}
+
+function npmInvocation(args, env = process.env) {
+  if (process.platform !== "win32") return { command: "npm", args };
+  return {
+    command: env.ComSpec || env.COMSPEC || "cmd.exe",
+    args: ["/d", "/s", "/c", "npm", ...args],
+  };
+}
+
+function getLatestVersion({ env = process.env } = {}) {
+  const invocation = npmInvocation(["view", PKG, "version"], env);
+  const value = execFileSync(invocation.command, invocation.args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: NETWORK_TIMEOUT_MS,
+  }).trim();
+  return parseSemver(value) ? value.replace(/^v/, "") : null;
+}
+
+function fetchText(url, redirectsLeft = 3) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, {
+      headers: {
+        Accept: "text/plain",
+        "User-Agent": "meegle-cli-update-notifier",
+      },
+    }, (response) => {
+      const status = response.statusCode || 0;
+      if (status >= 300 && status < 400 && response.headers.location && redirectsLeft > 0) {
+        response.resume();
+        const redirectURL = new URL(response.headers.location, url);
+        if (redirectURL.protocol !== "https:") {
+          reject(new Error("refusing non-HTTPS changelog redirect"));
+          return;
+        }
+        fetchText(redirectURL.toString(), redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) {
+        response.resume();
+        reject(new Error(`changelog request failed with HTTP ${status}`));
+        return;
+      }
+      const chunks = [];
+      let size = 0;
+      response.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > MAX_CHANGELOG_BYTES) {
+          request.destroy(new Error("changelog response is too large"));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      response.on("error", reject);
+    });
+    request.setTimeout(NETWORK_TIMEOUT_MS, () => request.destroy(new Error("changelog request timed out")));
+    request.on("error", reject);
+  });
+}
+
+function fetchChangelog() {
+  return fetchText(CHANGELOG_RAW_URL);
+}
+
+function defaultCacheFile(env = process.env) {
+  if (env.MEEGLE_UPDATE_CACHE_FILE) return env.MEEGLE_UPDATE_CACHE_FILE;
+  return path.join(os.homedir(), ".meegle", "cache", "update-notifier.json");
+}
+
+function readCache(cacheFile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+    return parsed && parsed.schema_version === CACHE_SCHEMA_VERSION ? parsed : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeCache(cacheFile, value) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(cacheFile, `${JSON.stringify({ schema_version: CACHE_SCHEMA_VERSION, ...value }, null, 2)}\n`, {
+      mode: 0o600,
+    });
+  } catch (_) {
+    // Update checks are best-effort and must never block a CLI command.
+  }
+}
+
+function truthyEnv(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function shouldRunUpdateCheck({
+  args = [],
+  input = process.stdin,
+  output = process.stderr,
+  stdout = process.stdout,
+  env = process.env,
+} = {}) {
+  if (!input.isTTY || !output.isTTY || !stdout.isTTY) return false;
+  if (truthyEnv(env.CI) || truthyEnv(env.MEEGLE_NO_UPDATE_CHECK)) return false;
+  const command = args[0] || "";
+  return command !== "install" && command !== "completion" && !command.startsWith("__complete");
+}
+
+function getGlobalBinaryPath(binName, env = process.env) {
+  try {
+    const invocation = npmInvocation(["root", "-g"], env);
+    const root = execFileSync(invocation.command, invocation.args, {
+      encoding: "utf8",
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: NETWORK_TIMEOUT_MS,
+    }).trim();
+    const candidate = path.join(root, ...PKG.split("/"), "bin", binName);
+    fs.accessSync(candidate, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
+    return candidate;
+  } catch (_) {
+    return "";
+  }
+}
+
+function updateAgentSkillBestEffort({ output = process.stderr, locale = "en", installerFn } = {}) {
+  const msg = messages[locale] || messages.en;
+  output.write(msg.skillUpdating);
+  let updated = false;
+  try {
+    const install = installerFn || require("./install-wizard.js").installAgentSkill;
+    updated = install({ bestEffort: true }) !== false;
+  } catch (_) {
+    updated = false;
+  }
+  output.write(updated ? msg.skillUpdated : msg.skillSkipped);
+  return updated;
+}
+
+function installLatest({
+  latestVersion,
+  binName,
+  env = process.env,
+  output = process.stderr,
+  locale = "en",
+  skillInstallerFn,
+  spawnFn = spawnSync,
+  globalBinaryPathFn = getGlobalBinaryPath,
+}) {
+  const msg = messages[locale] || messages.en;
+  output.write(fmt(msg.updating, latestVersion));
+  const invocation = npmInvocation(["install", "-g", `${PKG}@latest`], env);
+  const result = spawnFn(invocation.command, invocation.args, {
+    env,
+    stdio: "inherit",
+    timeout: 120000,
+  });
+  if (result.signal) process.kill(process.pid, result.signal);
+  if (result.error || result.status !== 0) {
+    output.write(msg.updateFailed);
+    return { ok: false, binaryPath: "" };
+  }
+  output.write(fmt(msg.updated, latestVersion));
+  const skillUpdated = updateAgentSkillBestEffort({ output, locale, installerFn: skillInstallerFn });
+  output.write(msg.continuing);
+  return { ok: true, binaryPath: globalBinaryPathFn(binName, env), skillUpdated };
+}
+
+async function maybeCheckForUpdates(options = {}) {
+  const args = options.args || [];
+  const input = options.input || process.stdin;
+  const output = options.output || process.stderr;
+  const stdout = options.stdout || process.stdout;
+  const env = options.env || process.env;
+  const currentVersion = options.currentVersion;
+  const binName = options.binName || "";
+  const now = options.now === undefined ? Date.now() : options.now;
+  const locale = options.locale || localeFromEnv(env);
+  const cacheFile = options.cacheFile || defaultCacheFile(env);
+  if (!shouldRunUpdateCheck({ args, input, output, stdout, env }) || !parseSemver(currentVersion)) {
+    return { status: "skipped", updated: false, binaryPath: "" };
+  }
+
+  const cache = readCache(cacheFile);
+  if (cache.current_version === currentVersion && Number(cache.next_check_at || 0) > now) {
+    return { status: "cached", updated: false, binaryPath: "" };
+  }
+
+  const latestVersionFn = options.getLatestVersionFn || getLatestVersion;
+  let latestVersion;
+  try {
+    latestVersion = await latestVersionFn({ env });
+  } catch (_) {
+    latestVersion = null;
+  }
+  if (!latestVersion || !parseSemver(latestVersion)) {
+    writeCache(cacheFile, {
+      current_version: currentVersion,
+      checked_at: now,
+      next_check_at: now + FAILURE_RETRY_MS,
+    });
+    return { status: "unavailable", updated: false, binaryPath: "" };
+  }
+  if (!isNewerVersion(latestVersion, currentVersion)) {
+    writeCache(cacheFile, {
+      current_version: currentVersion,
+      latest_version: latestVersion,
+      checked_at: now,
+      next_check_at: now + CHECK_INTERVAL_MS,
+    });
+    return { status: "current", updated: false, binaryPath: "" };
+  }
+
+  const fetchChangelogFn = options.fetchChangelogFn || fetchChangelog;
+  let changelog = "";
+  try {
+    changelog = await fetchChangelogFn();
+  } catch (_) {
+    // Version discovery still succeeded, so show the update with a link even
+    // when GitHub is temporarily unreachable.
+  }
+  const releases = parseReleaseNotes(changelog, currentVersion, latestVersion);
+  output.write(renderUpdateNotice({
+    currentVersion,
+    latestVersion,
+    releases,
+    locale,
+    columns: output.columns,
+  }));
+
+  const selectActionFn = options.selectActionFn || selectUpdateAction;
+  const action = await selectActionFn({ input, output, locale });
+  if (action !== "update") {
+    writeCache(cacheFile, {
+      current_version: currentVersion,
+      latest_version: latestVersion,
+      checked_at: now,
+      next_check_at: now + CHECK_INTERVAL_MS,
+      deferred_at: now,
+    });
+    return { status: "deferred", updated: false, binaryPath: "" };
+  }
+
+  const installFn = options.installFn || installLatest;
+  const installResult = await installFn({ latestVersion, binName, env, output, locale });
+  const ok = installResult === true || Boolean(installResult && installResult.ok);
+  writeCache(cacheFile, {
+    current_version: ok ? latestVersion : currentVersion,
+    latest_version: latestVersion,
+    checked_at: now,
+    next_check_at: now + (ok ? CHECK_INTERVAL_MS : FAILURE_RETRY_MS),
+  });
+  return {
+    status: ok ? "updated" : "update-failed",
+    updated: ok,
+    binaryPath: ok && installResult.binaryPath ? installResult.binaryPath : "",
+  };
+}
+
+module.exports = {
+  CHANGELOG_URL,
+  CHECK_INTERVAL_MS,
+  compareVersions,
+  defaultCacheFile,
+  getLatestVersion,
+  installLatest,
+  isNewerVersion,
+  localeFromEnv,
+  maybeCheckForUpdates,
+  parseReleaseNotes,
+  renderUpdateNotice,
+  selectUpdateAction,
+  shouldRunUpdateCheck,
+  updateAgentSkillBestEffort,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-project/meegle",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "homepage": "https://github.com/larksuite/meegle-cli#readme",
@@ -29,6 +29,7 @@
   "files": [
     "bin/meegle.js",
     "bin/install-wizard.js",
+    "bin/update-notifier.js",
     "bin/meegle-*",
     "README.md",
     "README.zh-CN.md",
@@ -38,7 +39,8 @@
     "third_party_licenses/**"
   ],
   "scripts": {
-    "prepublishOnly": "cp ../../README.zh-CN.md ./README.zh-CN.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../THIRD_PARTY_NOTICES.md ./THIRD_PARTY_NOTICES.md && rm -rf ./third_party_licenses && cp -R ../../third_party_licenses ./third_party_licenses && cp ../../README.md ./README.md"
+    "prepublishOnly": "cp ../../README.zh-CN.md ./README.zh-CN.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../THIRD_PARTY_NOTICES.md ./THIRD_PARTY_NOTICES.md && rm -rf ./third_party_licenses && cp -R ../../third_party_licenses ./third_party_licenses && cp ../../README.md ./README.md",
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "meegle",