@tingwillforever/meegle-cli 1.0.0-dev.20260519131637322 → 1.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@tingwillforever/meegle-cli.svg)](https://www.npmjs.com/package/@tingwillforever/meegle-cli)
+
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
 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.
@@ -11,7 +13,7 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 ## Why Meegle CLI?
 
 - **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output and `--dry-run` previews
-- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project) and 40+ commands mapping to Meegle's core capabilities
+- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, views, charts, team, user, spaces, attachments, releases / deploy tasks, URL parsing) and 40+ commands mapping to the private-deployment surface
 - **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
@@ -20,18 +22,20 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 
 | Category                                           | Capabilities                                                                                   |
 | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, query (MQL), list operation records, inspect metadata        |
+| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, search by params/filter, list operation records, inspect metadata |
 | 🔀 [Workflow](#workflow--workflow)                 | Transition nodes & states, update node fields, list available transitions and required fields |
-| ✅ [Subtasks](#subtask--subtasks)                  | Create, update, complete, rollback subtasks                                                    |
-| 💬 [Comments](#comment--comments)                  | Add and list comments on work items                                                            |
-| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records, view team-member schedules                                             |
-| 🔗 [Relations](#relation--relations)               | List related work items, inspect relation-type definitions                                     |
-| 📌 [My Work](#mywork--my-work)                     | View this week / overdue / completed to-dos                                                    |
-| 👁️ [Views](#view--views)                           | Create and update fixed views, search views by name                                            |
+| ✅ [Subtasks](#subtask--subtasks)                  | Create, list, update, complete, rollback subtasks                                              |
+| 💬 [Comments](#comment--comments)                  | Add, list, update comments on work items                                                       |
+| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records                                                                          |
+| 👁️ [Views](#view--views)                           | Search, get, create, update views; fixed-view item access                                       |
 | 📊 [Charts](#chart--charts)                        | List charts under a view, fetch chart details                                                  |
-| 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
-| 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
-| 🔐 [Auth & Config](#authentication)                | Remote MCP SSO config, profile config, env-var injection                                       |
+| 👥 [Team & User](#team--user--people)              | List team members, search users, view current login                                            |
+| 🗂️ [Spaces](#space--spaces)                        | List spaces, get space detail, list business lines                                              |
+| 📎 [Attachments](#attachment--attachments)         | Upload file to a work item field, download by UUID, delete                                      |
+| 🚀 [Releases](#release--release-deploy-tasks)      | Release-first deploy task surface — list / inspect / prepare / create / execute / verify / apply-whitelist |
+| 🔗 [URL Parsing](#url--url-parsing)                | Offline decode of Meegle / Feishu Project URLs into `url_kind` + structured fields              |
+| 🔐 [Auth & Config](#authentication)                | Remote MCP SSO login, status, multi-profile config, env-var injection                          |
+| 🩺 [Doctor](#authentication)                       | Read-only diagnostics for the active profile (runtime, network, session)                        |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
 
 ## Installation
@@ -42,47 +46,36 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 
 ### Install
 
-Install the published package with a GitHub token that can read packages:
-
 ```bash
-npm config set @tingwillforever:registry https://npm.pkg.github.com
-npm config set //npm.pkg.github.com/:_authToken <github_pat_with_read_packages>
-npm install -g @tingwillforever/meegle-cli@latest
+npm install -g @tingwillforever/meegle-cli
 ```
 
 ## Quick Start
 
 For ordinary users, the CLI is a thin client for the deployed Meegle MCP Server.
 You do not need to configure plugin credentials, project credentials, or a local
-MCP runtime.
+MCP runtime — `auth login` opens the browser, completes enterprise SSO, and
+exchanges the SSO ticket for a refreshable session managed by the MCP Server.
 
 ```bash
-# 1. Start ordinary-user remote MCP SSO login
-meegle auth login
+# 1. Install the CLI
+npm install -g @tingwillforever/meegle-cli
 
-# 2. Inspect the current authorization summary returned by the server
-meegle auth whoami --format table
+# 2. Log in via remote MCP SSO (opens browser)
+meegle auth login
 
-# 3. Verify the installed CLI and runtime
-meegle version
+# 3. Verify session and runtime
+meegle auth status
 meegle doctor --format json
 ```
 
-`auth login` opens the browser, completes enterprise SSO, exchanges the SSO
-ticket for an MCP-managed session, and stores the refreshable session locally.
-The production package should embed the production MCP endpoint. Use
-`mcp_server_url` or `--mcp-server-url ...` only for local debugging, staging, or
-temporary bootstrap.
-
-`auth whoami` shows the authenticated domain account plus the Meegle user key,
-project scope, and business-line scope returned by the server.
-
-If login reports that access must be requested or approved, SSO has identified
-you successfully but the MCP Server has not found an active access grant for
-your account yet. Ask an administrator to approve or maintain your grant through
+If `auth login` reports that access must be requested or approved, SSO has
+identified you successfully but the MCP Server has no active access grant for
+your account. Ask an administrator to approve or maintain your grant through
 the MCP Server access-request / access-grant APIs.
 
-If `doctor` fails, stop and fix runtime/config first. Do not start with business commands.
+If `doctor` fails, fix runtime/config first — do not start with business
+commands.
 
 ## AI Agent Skill
 
@@ -90,16 +83,16 @@ If `doctor` fails, stop and fix runtime/config first. Do not start with business
 
 ### Install
 
-Complete [Installation](#installation) first, then install the skill:
+Complete [Installation](#installation) first, then add the skill:
 
 ```bash
-npx -y skills add tingwillforever/meegle-cli --skill meegle -y -g
+# Installs the skill into every supported agent CLI on this machine
+npx -y skills add https://github.com/tingwillforever/meegle-cli --skill meegle -y -g
 ```
 
-Private-repository install prerequisites:
-
-- the machine must already be able to access `tingwillforever/meegle-cli`
-- `skills add` will clone the private GitHub repository, so the user should authenticate with GitHub first, for example with `gh auth login`, or have working git/SSH credentials for that repository
+`npx skills add` reads `skills/meegle/SKILL.md` from this repo and registers it
+into the skill directory of every agent CLI it finds (Trae, Claude Code,
+Cursor, Windsurf, Gemini CLI, Copilot CLI). Re-run any time to pick up updates.
 
 ### What it covers
 
@@ -132,15 +125,16 @@ The agent consults the skill, runs `meegle doctor` first when needed, picks the
 
 | Command | Description |
 |---------|-------------|
-| `workitem create` | Create a work item |
-| `workitem get` | View work item details |
+| `workitem create` | Create a new work item |
+| `workitem get` | Query work items by IDs — returns full details, fields, workflow state, metadata |
 | `workitem +batch-get` | Batch-read work items by IDs (client-side fan-out over `workitem get`; `+` marks scenario/sugar commands) |
-| `workitem update` | Update work item fields |
-| `workitem search-by-params` | Search work items with structured field filters |
-| `workitem search-filter` | Search work items by title/name filter |
-| `workitem list-op-records` | View operation records |
-| `workitem meta-types` | List work item types |
-| `workitem meta-create-fields` | List fields available at creation |
+| `workitem update` | Update fields on an existing work item |
+| `workitem search-by-params` | Advanced search by field-level filters within a space |
+| `workitem search-filter` | Search work items by name/title filter within a space |
+| `workitem search-filter-across` | Search by name filter across multiple spaces |
+| `workitem list-op-records` | Get operation history / audit log |
+| `workitem meta-types` | List work item types available in a space |
+| `workitem meta-create-fields` | List field metadata available at creation time |
 | `workitem meta-fields` | List field configurations |
 | `workitem meta-roles` | List role configurations |
 
@@ -148,75 +142,101 @@ The agent consults the skill, runs `meegle doctor` first when needed, picks the
 
 | Command | Description |
 |---------|-------------|
-| `workflow transition` | Transition or rollback a node |
-| `workflow transition-state` | Transition a state-flow state |
-| `workflow update-node` | Update a node |
-| `workflow list-state-transitions` | List available state transitions |
-| `workflow list-state-required` | List required fields for transitions |
+| `workflow transition` | Transition or rollback a workflow node (node-flow) |
+| `workflow transition-state` | Transition a state-flow work item to a new state |
+| `workflow update-node` | Update node metadata — schedule, owners, fields |
+| `workflow list-state-transitions` | List the work item's nodes, states, owners, and available transitions |
+| `workflow list-state-required` | List required fields for a workflow transition |
 
 ### subtask — Subtasks
 
 | Command | Description |
 |---------|-------------|
-| `subtask update` | Create / update / complete / rollback subtasks |
+| `subtask create` | Create a sub-task under a workflow node |
+| `subtask list` | List sub-tasks under a node |
+| `subtask update` | Update sub-task name, owners, schedule, note |
+| `subtask operate` | Confirm (complete) or rollback a sub-task |
 
 ### comment — Comments
 
 | Command | Description |
 |---------|-------------|
-| `comment add` | Add a comment |
-| `comment list` | List comments |
+| `comment add` | Add a comment (plain text or rich text) |
+| `comment list` | List comments on a work item |
+| `comment update` | Update an existing comment |
 
 ### workhour — Work Hours
 
 | Command | Description |
 |---------|-------------|
 | `workhour list-records` | List work hour records |
-| `workhour list-schedule` | View team member schedules |
-
-### relation — Relations
-
-| Command | Description |
-|---------|-------------|
 
 ### view — Views
 
 | Command | Description |
 |---------|-------------|
+| `view search` | Search view configurations in a space; returns `view_type` (0=system list, 1=condition/panoramic, 2=fixed) |
+| `view get` | Get items in a system / fixed list view (typically `view_type=0` or `2`) |
 | `view create-fixed` | Create a fixed view |
-| `view get` | View details of a view |
 | `view update-fixed` | Update a fixed view |
-| `view search` | Search views by name |
 
 ### chart — Charts
 
 | Command | Description |
 |---------|-------------|
-| `chart get` | View chart details |
 | `chart list` | List charts under a view |
+| `chart get` | Fetch chart details |
 
 ### team / user — People
 
 | Command | Description |
 |---------|-------------|
-| `team list-members` | List team members |
-| `user me` | View current logged-in user information |
-| `user query` | Query user information |
+| `team list-members` | List team members in a space |
+| `user me` | Show current logged-in user information |
+| `user query` | Query user details by `user_key`, `out_id`, or `email` |
+
+### space — Spaces
+
+| Command | Description |
+|---------|-------------|
+| `space list` | List all spaces accessible to the current user |
+| `space detail` | Get detailed information about specific spaces by key |
+| `space business-lines` | Get all business lines in a space |
 
-### space — Projects
+### attachment — Attachments
 
 | Command | Description |
 |---------|-------------|
-| `space list` | List projects |
+| `attachment upload` | Upload and attach a file to a work item field |
+| `attachment upload-file` | Upload a generic file (rich-text image, attachment field) |
+| `attachment download` | Download an attachment by UUID |
+| `attachment delete` | Delete an attachment (destructive) |
+
+### release — Release Deploy Tasks
+
+| Command | Description |
+|---------|-------------|
+| `release deploy-task-list` | List deploy tasks for a release work item |
+| `release deploy-task-inspect` | Inspect a deploy task with pod status and mismatch warnings |
+| `release deploy-task-prepare` | Prepare a Kubelink deploy-task creation payload from `appName` / `iBuildId` |
+| `release deploy-task-create` | Create release-oriented deploy tasks |
+| `release deploy-task-execute` | Execute deployment for deploy tasks |
+| `release deploy-task-verify` | Run verification for deploy tasks |
+| `release deploy-task-apply-white-list` | Apply whitelist after explicit user confirmation |
+
+### url — URL Parsing
+
+| Command | Description |
+|---------|-------------|
+| `url decode` | Offline decode a Meegle / Feishu Project URL into structured fields (returns `url_kind`) |
 
 ### auth — Authentication
 
 | Command | Description |
 |---------|-------------|
-| `auth login` | Start remote MCP SSO login |
+| `auth login` | Start remote MCP SSO login (browser-based) |
+| `auth status` | View authentication status |
 | `auth logout` | Log out and revoke the remote session when possible |
-| `auth status` | View login status |
-| `auth whoami` | Show the current authenticated identity and authorization summary |
 
 ### config — Configuration
 
@@ -232,7 +252,9 @@ The agent consults the skill, runs `meegle doctor` first when needed, picks the
 
 | Command | Description |
 |---------|-------------|
-| `inspect [command]` | Inspect command parameters |
+| `doctor` | Run read-only diagnostics for the active profile |
+| `inspect [command]` | Show parameter details for a command (e.g. `inspect workitem.create`) |
+| `version` | Print the CLI version |
 | `completion bash\|zsh\|fish` | Generate shell completion script |
 | `completion install` | Auto-install shell completion |
 
@@ -262,7 +284,6 @@ Verification-state guidance:
 - `release deploy-task-prepare`
 - `release deploy-task-list`
 - `release deploy-task-inspect`
-- `integration kubelink-app-catalog-resolve`
 
 These are `verified` and are the default-safe first picks.
 
@@ -270,18 +291,13 @@ These are `verified` and are the default-safe first picks.
 - `release deploy-task-execute`
 - `release deploy-task-apply-white-list`
 - `release deploy-task-verify`
-- `integration kubelink-deploy-task-create`
-- `integration kubelink-deploy-task-upgrade`
-- `integration kubelink-deploy-task-verify`
-- `integration kubelink-deploy-task-apply-white-list`
-- `integration kubelink-deploy-task-inspect`
 
 These are `conditional`. Use `meegle inspect <resource>.<method>` first if the parameter shape is unclear, and do not run them blindly in agentic workflows.
 
 Advanced fallback:
 
-- stay on `release` commands for ordinary release-oriented deploy-task requests
-- use `integration` only when you already have exact Kubelink payloads or record IDs, or when the release-layer command cannot express the action
+- stay on `release` commands — they cover the full release-oriented deploy-task surface
+- if a backend-only Kubelink action is needed that the release layer cannot express, raise the case rather than reaching for an unsupported integration command
 
 ## Common Examples
 
@@ -294,7 +310,7 @@ meegle workitem get \
   --work-item-type-key WORK_ITEM_TYPE_KEY \
   --work-item-ids 12345
 
-# View workflow state, nodes, and transitions
+# View workflow state, nodes, owners, and possible transitions
 meegle workflow list-state-transitions \
   --project-key PROJ \
   --work-item-type-key WORK_ITEM_TYPE_KEY \
@@ -339,31 +355,45 @@ per-item `error` field. A 401 from the server aborts the whole run.
 ### Creating Work Items
 
 ```bash
-# Pass fields[] via --params (JSON)
-meegle workitem create --project-key PROJ --work-item-type story \
+# Required flags + extra fields[] via --params (JSON)
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "Optimize login flow" \
   --params '{"fields":[
-    {"field_key":"name","field_value":"Optimize login flow"},
     {"field_key":"priority","field_value":"P1"}
   ]}'
 
 # Complex field values (arrays, nested JSON) also go through --params
-meegle workitem create --project-key PROJ --work-item-type story \
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "Scheduled task" \
   --params '{"fields":[
-    {"field_key":"name","field_value":"Scheduled task"},
     {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
   ]}'
 ```
 
 ### Updating Fields
 
+`workitem update` requires `--work-item-id`, `--project-key`, and
+`--work-item-type-key`. Field values come through `--update-fields` (one
+`key=value` per entry) or via `--params` for complex payloads.
+
 ```bash
-# Update work item name
-meegle workitem update --work-item-id 12345 \
-  --params '{"fields":[{"field_key":"name","field_value":"New title"}]}'
+# Update a single field via --update-fields
+meegle workitem update \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-id 12345 \
+  --update-fields 'name=New title'
 
-# Update multiple fields at once
-meegle workitem update --work-item-id 12345 \
-  --params '{"fields":[
+# Update multiple fields with a JSON payload
+meegle workitem update \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-id 12345 \
+  --params '{"update_fields":[
     {"field_key":"name","field_value":"New title"},
     {"field_key":"priority","field_value":"P0"}
   ]}'
@@ -372,61 +402,61 @@ meegle workitem update --work-item-id 12345 \
 ### Work Item Search
 
 ```bash
-# Query P0 stories in a project by title/name filter
-meegle workitem search-filter --project-key PROJ \
-  --work-item-type-key STORY_TYPE_KEY \
-  --name P0
-```
-
-### Viewing Schedules
+# Filter by name across one or more work item types in a space
+meegle workitem search-filter \
+  --project-key PROJ \
+  --work-item-type-keys STORY_TYPE_KEY \
+  --work-item-name "login"
 
-```bash
-# View team member schedules
-meegle workhour list-schedule --project-key PROJ \
-  --start-time 2026-03-01 --end-time 2026-03-31 \
-  --user-keys "Alice,Bob,Charlie"
+# Structured field-level search (advanced)
+meegle workitem search-by-params \
+  --project-key PROJ \
+  --work-item-type-key STORY_TYPE_KEY \
+  --params '{"search_params":{"conditions":[
+    {"field_key":"priority","operator":"=","value":"P0"}
+  ]}}'
 ```
 
 ### Searching Users
 
 ```bash
-meegle user query --user-keys "Alice,Bob"
+# Resolve current login
+meegle user query --user-keys "current_login_user()"
+
+# Look up by email
+meegle user query --emails "alice@example.com,bob@example.com"
 ```
 
 ### Deploy Tasks
 
 ```bash
-# Prepare a release-oriented deploy-task payload
-meegle release deploy-task-prepare \
-  --project-key PROJ \
-  --release-id RELEASE_ID \
-  --appName APP_NAME \
-  --format json
+# 1. Verify runtime first
+meegle doctor --format json
 
-# List deploy tasks bound to a release
+# 2. List deploy tasks bound to a release
 meegle release deploy-task-list \
   --project-key PROJ \
   --release-id RELEASE_ID \
   --format json
 
-# Inspect one deploy task with release context
+# 3. Inspect one deploy task with pod-status detail
 meegle release deploy-task-inspect \
+  --recordID RECORD_ID \
+  --format json
+
+# 4. Prepare a deploy-task creation payload
+meegle release deploy-task-prepare \
   --project-key PROJ \
   --release-id RELEASE_ID \
-  --recordID RECORD_ID \
+  --appName APP_NAME \
   --format json
 
-# Apply whitelist from the release layer after explicit user confirmation
+# 5. Apply whitelist after explicit user confirmation
 meegle release deploy-task-apply-white-list \
   --project-key PROJ \
   --release-id RELEASE_ID \
   --recordIDs RECORD_ID \
   --format json
-
-# Resolve app/chart candidates from the advanced Kubelink layer
-meegle integration kubelink-app-catalog-resolve \
-  --appName APP_NAME \
-  --format json
 ```
 
 ## Parameter Passing
@@ -470,8 +500,11 @@ meegle workitem search-filter --set project_key=PROJ --set work_item_type_keys=W
 All commands support `--params` to pass a full JSON parameter body:
 
 ```bash
-meegle workitem create --project-key PROJ --work-item-type story \
-  --params '{"fields":[{"field_key":"name","field_value":"Title"}]}'
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "Title" \
+  --params '{"fields":[{"field_key":"priority","field_value":"P1"}]}'
 ```
 
 ### Priority
@@ -564,8 +597,12 @@ loss-less.
 For commands with side effects, preview the rendered request with `--dry-run` before executing:
 
 ```bash
-meegle workitem create --project-key PROJ --work-item-type story \
-  --params '{"fields":[{"field_key":"name","field_value":"Test"}]}' --dry-run
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "Test" \
+  --params '{"fields":[{"field_key":"priority","field_value":"P2"}]}' \
+  --dry-run
 ```
 
 ### Command Introspection
@@ -588,7 +625,7 @@ means the remote MCP SSO path shown in [Quick Start](#quick-start):
 - run `meegle auth login`
 - the production package uses its built-in production MCP endpoint by default
 - use `meegle config set mcp_server_url ...` only for local debugging or staging overrides
-- inspect the granted identity and scope with `meegle auth whoami`
+- check the active session with `meegle auth status`
 
 Run `meegle doctor --format json` after login. If `doctor` fails, stop and fix
 config before running business commands.
@@ -597,7 +634,7 @@ Example ordinary-user remote MCP SSO login commands:
 
 ```bash
 meegle auth login
-meegle auth whoami --format table
+meegle auth status
 ```
 
 Bootstrap / one-off override example:
@@ -608,7 +645,7 @@ meegle auth login
 
 # or a one-off endpoint override
 meegle auth login --mcp-server-url https://mcp.example.com/mcp
-meegle auth whoami --format table
+meegle auth status
 ```
 
 ### Generic OAuth / Device Code flows
@@ -657,7 +694,7 @@ Before publishing the ordinary-user package:
 - update `DefaultRemoteMCPServerURL` in `internal/products/meegle/config.go` to the production `/mcp` endpoint
 - build the CLI package with `make meegle-cli`
 - install the staged or published package in a clean shell and run `meegle auth login`
-- confirm `meegle auth whoami --format table` shows the expected account, Meegle user key, projects, and business lines
+- confirm `meegle auth status` shows an active session and the expected account / scope
 - leave `mcp_server_url` unset for ordinary users; use it only for local or staging overrides
 
 ### Sandbox / CI: Direct Environment-Variable Injection

package/README.zh-CN.md

@@ -2,6 +2,8 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@tingwillforever/meegle-cli.svg)](https://www.npmjs.com/package/@tingwillforever/meegle-cli)
+
 [English](./README.md) | [简体中文](./README.zh-CN.md)
 
 飞书项目（[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)）命令行工具。在终端中管理工作项、查看排期、搜索数据，无需打开浏览器。
@@ -11,7 +13,7 @@
 ## 为什么选择 Meegle CLI？
 
 - **Agent 友好** — 附带一份 [AI Agent Skill](#ai-agent-skill)，一条命令即可把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、`--dry-run` 预览
-- **覆盖完整** — 12 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间），40+ 命令映射到 Meegle 核心能力
+- **覆盖完整** — 12 个业务域（工作项、工作流、子任务、评论、工时、视图、度量、团队、用户、空间、附件、发布 / 部署任务、URL 解析），40+ 命令映射到私有化部署面
 - **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
 - **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
 - **默认安全** — 凭证存进系统 keychain、`${VAR}` 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod
@@ -20,18 +22,20 @@
 
 | 域                                                 | 能力                                                                                     |
 | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| 📋 [工作项](#workitem--工作项域)                   | 创建、查看、更新、批量读、MQL 查询、查看操作记录、读元数据                               |
+| 📋 [工作项](#workitem--工作项域)                   | 创建、查看、更新、批量读、按字段/标题搜索、查看操作记录、读字段元数据                    |
 | 🔀 [工作流](#workflow--工作流域)                   | 节点和状态流转、更新节点字段、列出可用流转和必填字段                                     |
-| ✅ [子任务](#subtask--子任务)                      | 创建、更新、完成、回滚子任务                                                             |
-| 💬 [评论](#comment--评论域)                        | 在工作项上添加和列出评论                                                                 |
-| ⏱️ [工时](#workhour--工时域)                       | 列出工时记录、查看团队成员排期                                                           |
-| 🔗 [关联](#relation--关系域)                       | 列出关联工作项、查看关联类型定义                                                         |
-| 📌 [我的工作](#mywork--工作台域)                   | 查看本周 / 已完成 / 逾期待办                                                             |
-| 👁️ [视图](#view--视图域)                           | 创建和更新固定视图、按名称搜索视图                                                       |
-| 📊 [图表](#chart--度量域)                          | 列出视图下的图表、查看图表详情                                                           |
-| 👥 [团队与用户](#team--user--人员域)               | 列出团队、团队成员、搜索用户、查看当前登录身份                                           |
-| 🗂️ [空间](#project--空间域)                        | 按关键词搜索空间                                                                         |
-| 🔐 [认证与配置](#认证)                             | 远端 MCP SSO 配置、多 profile 配置、环境变量注入                                       |
+| ✅ [子任务](#subtask--子任务)                      | 在工作流节点下创建、列出、更新、完成、回滚子任务                                          |
+| 💬 [评论](#comment--评论域)                        | 添加、列出、更新工作项评论                                                                |
+| ⏱️ [工时](#workhour--工时域)                       | 列出工时登记记录                                                                          |
+| 👁️ [视图](#view--视图域)                           | 搜索、查看、创建、更新视图，固定视图条目读取                                              |
+| 📊 [度量](#chart--度量域)                          | 列出视图下的图表、查看图表详情                                                            |
+| 👥 [团队与用户](#team--user--人员域)               | 查看团队成员、搜索用户、查看当前登录身份                                                  |
+| 🗂️ [空间](#space--空间域)                          | 列出空间、查看空间详情、查看业务线                                                        |
+| 📎 [附件](#attachment--附件域)                     | 上传文件到工作项字段、按 UUID 下载、删除                                                  |
+| 🚀 [发布](#release--发布部署任务)                  | release-first 部署任务面 —— list / inspect / prepare / create / execute / verify / apply-whitelist |
+| 🔗 [URL 解析](#url--url-解析)                      | 离线解析飞书项目 / Meegle URL，输出 `url_kind` + 结构化字段                              |
+| 🔐 [认证与配置](#认证)                             | 远端 MCP SSO 登录、状态、多 profile 配置、环境变量注入                                   |
+| 🩺 [Doctor](#认证)                                  | 当前 profile 只读诊断（运行时、网络、会话）                                                |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用             |
 
 ## 安装
@@ -42,43 +46,34 @@
 
 ### 安装命令
 
-使用具备 package 读取权限的 GitHub token 安装已发布的包：
-
 ```bash
-npm config set @tingwillforever:registry https://npm.pkg.github.com
-npm config set //npm.pkg.github.com/:_authToken <github_pat_with_read_packages>
-npm install -g @tingwillforever/meegle-cli@latest
+npm install -g @tingwillforever/meegle-cli
 ```
 
 ## 快速开始
 
 对于普通用户，CLI 只是已部署 Meegle MCP Server 的轻量客户端。你不需要配置
-plugin 凭据、project 凭据，也不需要在本机启动 MCP runtime。
+plugin 凭据、project 凭据，也不需要在本机启动 MCP runtime —— `auth login`
+会拉起浏览器完成企业 SSO，再把 SSO ticket 交换成由 MCP Server 管理的可刷新
+本地会话。
 
 ```bash
-# 1. 发起普通用户远端 MCP SSO 登录
-meegle auth login
+# 1. 安装 CLI
+npm install -g @tingwillforever/meegle-cli
 
-# 2. 查看服务端返回的当前授权摘要
-meegle auth whoami --format table
+# 2. 远端 MCP SSO 登录（自动拉起浏览器）
+meegle auth login
 
-# 3. 验证安装结果和运行时状态
-meegle version
+# 3. 验证会话与运行时
+meegle auth status
 meegle doctor --format json
 ```
 
-`auth login` 会拉起浏览器完成企业 SSO，再把 SSO ticket 交换成由 MCP
-Server 管理的本地可刷新会话。正式安装包应内置生产 MCP 地址。只有本地调试、
-预发验证或临时引导时，才需要设置 `mcp_server_url` 或显式传
-`--mcp-server-url ...`。
+如果 `auth login` 提示需要申请或审批访问权限，说明 SSO 已确认你的身份，但
+MCP Server 还没有找到你的 active access grant。请联系管理员通过 MCP Server
+的 access-request / access-grant API 审批或维护权限。
 
-`auth whoami` 会展示当前登录域账号、Meegle user key，以及服务端下发的项目和业务线授权范围。
-
-如果登录提示需要申请或审批访问权限，说明 SSO 已确认你的身份，但 MCP Server
-还没有找到你的 active access grant。请联系管理员通过 MCP Server 的
-access-request / access-grant API 审批或维护权限。
-
-如果 `doctor` 没过，不要直接跑业务命令，先把运行时/配置补齐。
+如果 `doctor` 没过，先把运行时/配置补齐，不要直接跑业务命令。
 
 ## AI Agent Skill
 
@@ -86,16 +81,16 @@ access-request / access-grant API 审批或维护权限。
 
 ### 安装
 
-先完成[安装](#安装)，然后安装 skill：
+先完成[安装](#安装)，然后注册 skill：
 
 ```bash
-npx -y skills add tingwillforever/meegle-cli --skill meegle -y -g
+# 自动检测本机已安装的 Agent CLI 并逐个注册
+npx -y skills add https://github.com/tingwillforever/meegle-cli --skill meegle -y -g
 ```
 
-私有仓库安装前提：
-
-- 机器本身必须已经有 `tingwillforever/meegle-cli` 的访问权限
-- `skills add` 会 clone 私有 GitHub 仓库，因此用户应先完成 GitHub 认证，例如 `gh auth login`，或确保本机 git/SSH 已能访问该仓库
+`npx skills add` 会读取本仓库的 `skills/meegle/SKILL.md`，把它注册到本机
+所有受支持的 Agent CLI（Trae、Claude Code、Cursor、Windsurf、Gemini CLI、
+Copilot CLI）。后续 skill 有更新只需重跑同一条命令。
 
 ### 覆盖内容
 
@@ -128,91 +123,118 @@ Agent 会参考 skill，必要时先跑 `meegle doctor`，再自动选择合适
 
 | 命令 | 说明 |
 |------|------|
-| `workitem create` | 创建工作项 |
-| `workitem get` | 查看工作项概况 |
-| `workitem +batch-get` | 按 ID 批量读取工作项（客户端侧在 `workitem get` 之上做扇出；`+` 前缀代表场景/语法糖命令） |
+| `workitem create` | 创建新工作项 |
+| `workitem get` | 按 ID 查询工作项 —— 返回字段、工作流状态、元数据 |
+| `workitem +batch-get` | 按 ID 批量读取（客户端侧在 `workitem get` 之上做扇出；`+` 前缀代表场景/语法糖命令） |
 | `workitem update` | 修改工作项字段 |
-| `workitem search-by-params` | 使用结构化字段条件搜索工作项 |
-| `workitem search-filter` | 按标题 / 名称过滤搜索工作项 |
-| `workitem list-op-records` | 查看操作记录 |
-| `workitem meta-types` | 查看工作项类型列表 |
-| `workitem meta-create-fields` | 查看创建时可用字段 |
-| `workitem meta-fields` | 查看字段配置 |
-| `workitem meta-roles` | 查看角色配置 |
+| `workitem search-by-params` | 在空间内按字段级条件做高级搜索 |
+| `workitem search-filter` | 在空间内按名称/标题过滤搜索 |
+| `workitem search-filter-across` | 跨多个空间按名称过滤搜索 |
+| `workitem list-op-records` | 查看操作历史 / 审计记录 |
+| `workitem meta-types` | 列出空间下的工作项类型 |
+| `workitem meta-create-fields` | 列出创建时可用的字段元数据 |
+| `workitem meta-fields` | 列出字段配置 |
+| `workitem meta-roles` | 列出角色配置 |
 
 ### workflow — 工作流域
 
 | 命令 | 说明 |
 |------|------|
-| `workflow transition` | 流转或回滚节点 |
-| `workflow transition-state` | 流转状态流状态 |
-| `workflow update-node` | 修改节点 |
-| `workflow list-state-transitions` | 查看可流转状态 |
-| `workflow list-state-required` | 查看流转必填信息 |
+| `workflow transition` | 节点流转或回滚（节点流） |
+| `workflow transition-state` | 状态流模式下流转工作项到新状态 |
+| `workflow update-node` | 更新节点元数据 —— 排期、负责人、字段 |
+| `workflow list-state-transitions` | 查询工作项的节点、状态、负责人和可执行流转 |
+| `workflow list-state-required` | 查看流转所需的必填字段 |
 
 ### subtask — 子任务
 
 | 命令 | 说明 |
 |------|------|
-| `subtask update` | 创建/修改/完成/回滚子任务 |
+| `subtask create` | 在工作流节点下创建子任务 |
+| `subtask list` | 列出节点下的子任务 |
+| `subtask update` | 修改子任务名称、负责人、排期、备注 |
+| `subtask operate` | 确认（完成）或回滚一个子任务 |
 
 ### comment — 评论域
 
 | 命令 | 说明 |
 |------|------|
-| `comment add` | 添加评论 |
-| `comment list` | 查看评论列表 |
+| `comment add` | 添加评论（纯文本或富文本） |
+| `comment list` | 查看工作项评论列表 |
+| `comment update` | 修改已存在的评论 |
 
 ### workhour — 工时域
 
 | 命令 | 说明 |
 |------|------|
 | `workhour list-records` | 查看工时登记记录 |
-| `workhour list-schedule` | 查看人员排期 |
-
-### relation — 关系域
-
-| 命令 | 说明 |
-|------|------|
 
 ### view — 视图域
 
 | 命令 | 说明 |
 |------|------|
+| `view search` | 搜索空间下的视图配置；返回 `view_type`（0=系统列表，1=条件/全景，2=固定） |
+| `view get` | 读取系统/固定列表视图条目（通常 `view_type=0` 或 `2`） |
 | `view create-fixed` | 创建固定视图 |
-| `view get` | 查看视图详情 |
 | `view update-fixed` | 更新固定视图 |
-| `view search` | 按名称搜索视图 |
 
 ### chart — 度量域
 
 | 命令 | 说明 |
 |------|------|
+| `chart list` | 列出视图下的图表 |
 | `chart get` | 查看图表详情 |
-| `chart list` | 查看视图下的图表列表 |
 
 ### team / user — 人员域
 
 | 命令 | 说明 |
 |------|------|
-| `team list-members` | 查看团队成员 |
+| `team list-members` | 查看空间团队成员 |
 | `user me` | 查看当前登录用户信息 |
-| `user query` | 查询用户信息 |
+| `user query` | 按 `user_key` / `out_id` / `email` 查询用户详情 |
 
 ### space — 空间域
 
 | 命令 | 说明 |
 |------|------|
-| `space list` | 列出空间信息 |
+| `space list` | 列出当前用户可访问的所有空间 |
+| `space detail` | 按 key 查询指定空间的详细信息 |
+| `space business-lines` | 查看空间下的业务线 |
+
+### attachment — 附件域
+
+| 命令 | 说明 |
+|------|------|
+| `attachment upload` | 上传文件并附加到工作项字段 |
+| `attachment upload-file` | 上传通用文件（富文本图片、附件字段） |
+| `attachment download` | 按 UUID 下载附件 |
+| `attachment delete` | 删除附件（destructive） |
+
+### release — 发布部署任务
+
+| 命令 | 说明 |
+|------|------|
+| `release deploy-task-list` | 列出发布单下的部署任务 |
+| `release deploy-task-inspect` | 查看部署任务详情，包含 pod 状态和不一致告警 |
+| `release deploy-task-prepare` | 基于 `appName` / `iBuildId` 准备 Kubelink 部署任务创建载荷 |
+| `release deploy-task-create` | 创建 release-oriented 部署任务 |
+| `release deploy-task-execute` | 执行部署 |
+| `release deploy-task-verify` | 执行部署校验 |
+| `release deploy-task-apply-white-list` | 在用户显式确认后应用白名单 |
+
+### url — URL 解析
+
+| 命令 | 说明 |
+|------|------|
+| `url decode` | 离线解析飞书项目 / Meegle URL，返回 `url_kind` + 结构化字段 |
 
 ### auth — 认证域
 
 | 命令 | 说明 |
 |------|------|
-| `auth login` | 发起远端 MCP SSO 登录 |
-| `auth logout` | 登出，并在可达时撤销远端会话 |
+| `auth login` | 发起远端 MCP SSO 登录（基于浏览器） |
 | `auth status` | 查看登录状态 |
-| `auth whoami` | 查看当前登录身份和授权摘要 |
+| `auth logout` | 登出，并在可达时撤销远端会话 |
 
 ### config — 配置域
 
@@ -228,7 +250,9 @@ Agent 会参考 skill，必要时先跑 `meegle doctor`，再自动选择合适
 
 | 命令 | 说明 |
 |------|------|
-| `inspect [command]` | 查看命令参数详情 |
+| `doctor` | 当前 profile 只读诊断 |
+| `inspect [command]` | 查看命令参数详情（如 `inspect workitem.create`） |
+| `version` | 打印 CLI 版本号 |
 | `completion bash\|zsh\|fish` | 生成 Shell 补全脚本 |
 | `completion install` | 自动安装 Shell 补全 |
 
@@ -250,7 +274,6 @@ Agent 会参考 skill，必要时先跑 `meegle doctor`，再自动选择合适
 - `release deploy-task-prepare`
 - `release deploy-task-list`
 - `release deploy-task-inspect`
-- `integration kubelink-app-catalog-resolve`
 
 这些是 `verified`，可以作为默认安全的首选入口。
 
@@ -258,18 +281,13 @@ Agent 会参考 skill，必要时先跑 `meegle doctor`，再自动选择合适
 - `release deploy-task-execute`
 - `release deploy-task-apply-white-list`
 - `release deploy-task-verify`
-- `integration kubelink-deploy-task-create`
-- `integration kubelink-deploy-task-upgrade`
-- `integration kubelink-deploy-task-verify`
-- `integration kubelink-deploy-task-apply-white-list`
-- `integration kubelink-deploy-task-inspect`
 
 这些是 `conditional`。如果参数形状不明确，先执行 `meegle inspect <resource>.<method>`，不要在 Agent 场景里盲跑。
 
 高级降级入口：
 
-- 常规发布任务优先使用 `release` 资源组
-- 只有在你已经持有精确 Kubelink payload / record ID，或 release 层命令无法表达目标动作时，才退回 `integration`
+- 发布相关动作统一走 `release` 资源组 —— 它已经覆盖完整的发布部署任务面
+- 如果出现 release 层无法表达的后端 Kubelink 动作，应反馈给维护者而不是寻找未上线的 integration 命令
 
 ## 常用示例
 
@@ -282,7 +300,7 @@ meegle workitem get \
   --work-item-type-key WORK_ITEM_TYPE_KEY \
   --work-item-ids 12345
 
-# 查看工作项当前工作流状态、节点和可执行流转
+# 查看工作流当前状态、节点、负责人和可执行流转
 meegle workflow list-state-transitions \
   --project-key PROJ \
   --work-item-type-key WORK_ITEM_TYPE_KEY \
@@ -326,31 +344,44 @@ meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o n
 ### 创建工作项
 
 ```bash
-# 通过 --params 传 fields[]
-meegle workitem create --project-key PROJ --work-item-type story \
+# 必填 flag + 通过 --params 追加 fields[]
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "优化登录流程" \
   --params '{"fields":[
-    {"field_key":"name","field_value":"优化登录流程"},
     {"field_key":"priority","field_value":"P1"}
   ]}'
 
 # 复杂字段值（数组、嵌套 JSON）也走 --params
-meegle workitem create --project-key PROJ --work-item-type story \
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "排期任务" \
   --params '{"fields":[
-    {"field_key":"name","field_value":"排期任务"},
     {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
   ]}'
 ```
 
 ### 修改字段
 
+`workitem update` 必填 `--work-item-id`、`--project-key`、`--work-item-type-key`。
+字段值通过 `--update-fields`（每条 `key=value`）或 `--params` 传复杂载荷。
+
 ```bash
-# 修改工作项名称
-meegle workitem update --work-item-id 12345 \
-  --params '{"fields":[{"field_key":"name","field_value":"新标题"}]}'
+# 通过 --update-fields 修改单个字段
+meegle workitem update \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-id 12345 \
+  --update-fields 'name=新标题'
 
-# 同时修改多个字段
-meegle workitem update --work-item-id 12345 \
-  --params '{"fields":[
+# 通过 JSON 同时修改多个字段
+meegle workitem update \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --work-item-id 12345 \
+  --params '{"update_fields":[
     {"field_key":"name","field_value":"新标题"},
     {"field_key":"priority","field_value":"P0"}
   ]}'
@@ -359,61 +390,61 @@ meegle workitem update --work-item-id 12345 \
 ### 工作项搜索
 
 ```bash
-# 按标题 / 名称过滤查询空间下的 P0 需求
-meegle workitem search-filter --project-key PROJ \
-  --work-item-type-key STORY_TYPE_KEY \
-  --name P0
-```
-
-### 查看排期
+# 在空间内按名称过滤一个或多个工作项类型
+meegle workitem search-filter \
+  --project-key PROJ \
+  --work-item-type-keys STORY_TYPE_KEY \
+  --work-item-name "登录"
 
-```bash
-# 查看团队成员排期
-meegle workhour list-schedule --project-key PROJ \
-  --start-time 2026-03-01 --end-time 2026-03-31 \
-  --user-keys "张三,李四,王五"
+# 按字段级条件做高级搜索
+meegle workitem search-by-params \
+  --project-key PROJ \
+  --work-item-type-key STORY_TYPE_KEY \
+  --params '{"search_params":{"conditions":[
+    {"field_key":"priority","operator":"=","value":"P0"}
+  ]}}'
 ```
 
 ### 查看用户信息
 
 ```bash
-meegle user query --user-keys "张三,李四"
+# 查看当前登录用户
+meegle user query --user-keys "current_login_user()"
+
+# 按邮箱查询
+meegle user query --emails "alice@example.com,bob@example.com"
 ```
 
 ### 部署任务
 
 ```bash
-# 从发布单上下文准备 deploy-task payload
-meegle release deploy-task-prepare \
-  --project-key PROJ \
-  --release-id RELEASE_ID \
-  --appName APP_NAME \
-  --format json
+# 1. 先验证运行时
+meegle doctor --format json
 
-# 查看一个发布单下的 deploy tasks
+# 2. 列出发布单下的 deploy tasks
 meegle release deploy-task-list \
   --project-key PROJ \
   --release-id RELEASE_ID \
   --format json
 
-# 结合发布单上下文检查单个 deploy task
+# 3. 查看单个 deploy task 详情（含 pod 状态）
 meegle release deploy-task-inspect \
+  --recordID RECORD_ID \
+  --format json
+
+# 4. 准备 deploy-task 创建载荷
+meegle release deploy-task-prepare \
   --project-key PROJ \
   --release-id RELEASE_ID \
-  --recordID RECORD_ID \
+  --appName APP_NAME \
   --format json
 
-# 用户确认后，从 release 层申请加白
+# 5. 用户确认后申请加白
 meegle release deploy-task-apply-white-list \
   --project-key PROJ \
   --release-id RELEASE_ID \
   --recordIDs RECORD_ID \
   --format json
-
-# 在高级 Kubelink 层解析可部署应用和 chart
-meegle integration kubelink-app-catalog-resolve \
-  --appName APP_NAME \
-  --format json
 ```
 
 ## 参数传递
@@ -457,8 +488,11 @@ meegle workitem search-filter --set project_key=PROJ --set work_item_type_keys=W
 所有命令都支持 `--params` 传入完整 JSON 参数：
 
 ```bash
-meegle workitem create --project-key PROJ --work-item-type story \
-  --params '{"fields":[{"field_key":"name","field_value":"标题"}]}'
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "标题" \
+  --params '{"fields":[{"field_key":"priority","field_value":"P1"}]}'
 ```
 
 ### 优先级
@@ -542,8 +576,12 @@ meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" \
 有副作用的命令先用 `--dry-run` 预览请求再执行：
 
 ```bash
-meegle workitem create --project-key PROJ --work-item-type story \
-  --params '{"fields":[{"field_key":"name","field_value":"测试"}]}' --dry-run
+meegle workitem create \
+  --project-key PROJ \
+  --work-item-type-key WORK_ITEM_TYPE_KEY \
+  --name "测试" \
+  --params '{"fields":[{"field_key":"priority","field_value":"P2"}]}' \
+  --dry-run
 ```
 
 ### 命令内省
@@ -566,7 +604,7 @@ MCP SSO 路径：
 - 执行 `meegle auth login`
 - 正式安装包默认使用内置的生产 MCP 地址
 - 仅本地调试或预发覆盖时使用 `meegle config set mcp_server_url ...`
-- 然后用 `meegle auth whoami` 查看当前身份和授权范围
+- 用 `meegle auth status` 查看当前会话状态
 
 完成登录后，先执行 `meegle doctor --format json`。如果 `doctor`
 没过，先修配置，再跑业务命令。
@@ -575,7 +613,7 @@ MCP SSO 路径：
 
 ```bash
 meegle auth login
-meegle auth whoami --format table
+meegle auth status
 ```
 
 首次引导 / 单次覆盖示例：
@@ -586,7 +624,7 @@ meegle auth login
 
 # 或者仅单次覆盖 endpoint
 meegle auth login --mcp-server-url https://mcp.example.com/mcp
-meegle auth whoami --format table
+meegle auth status
 ```
 
 ### 通用 OAuth / Device Code 流程
@@ -633,7 +671,7 @@ meegle config get host
 - 将 `internal/products/meegle/config.go` 里的 `DefaultRemoteMCPServerURL` 改为生产 `/mcp` 地址
 - 使用 `make meegle-cli` 构建 CLI 包
 - 在干净 shell 中安装 staged 或已发布包，执行 `meegle auth login`
-- 确认 `meegle auth whoami --format table` 展示正确账号、Meegle user key、项目和业务线
+- 确认 `meegle auth status` 显示活跃会话和正确账号 / 范围
 - 普通用户侧保持 `mcp_server_url` 未配置；该配置只用于本地或预发覆盖
 
 ### 沙盒 / CI：直接注入环境变量

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tingwillforever/meegle-cli",
-  "version": "1.0.0-dev.20260519131637322",
+  "version": "1.0.0",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "bin": {