@lark-project/meegle 1.0.10 → 1.0.12

package/CHANGELOG.md

@@ -8,6 +8,22 @@ versioned section on each npm release.
 
 ## [Unreleased]
 
+## [v1.0.12] - 2026-06-29
+
+### Fixed
+
+- The install wizard now always installs the AI Agent Skill instead of trying to detect a prior install. The previous name-substring check matched sibling skills such as `meegle-plugin` and silently skipped installing the core `meegle` skill. `skills add` is idempotent, so re-running it on an already-installed skill simply upgrades or no-ops.
+
+## [v1.0.11] - 2026-06-26
+
+### Added
+
+- `meegle install` now runs a one-stop setup wizard for npm users: install or upgrade the CLI globally, install the AI Agent Skill, configure the host, and start browser or Device Code login. This enables `npx @lark-project/meegle@latest install` as the primary quick-start command.
+
+### Fixed
+
+- The install wizard now invokes the `skills` CLI through `npm exec --package=skills` so `skills add` and `skills ls` are parsed reliably across npm/npx versions. A real isolated install smoke test previously exposed that `npx -y skills add ...` could be misparsed as `add@latest`.
+
 ## [v1.0.10] - 2026-06-25
 
 ### Fixed

package/README.md

@@ -12,7 +12,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, `--dry-run` previews, and `--device-code` flows for non-TTY environments
+- **Agent-Native** — The setup wizard installs the bundled AI Agent Skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents. Every CLI command is designed for both humans and agents, with structured JSON output, `--dry-run` previews, and `--device-code` flows for non-TTY environments
 - **Broad Coverage** — 16 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project, attachments, deliverables, resource library, WBS plan tables) and 50+ commands mapping to Meegle's core capabilities
 - **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
@@ -47,22 +47,21 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 
 - Node.js >= 16 (ships with `npm` / `npx`)
 
-### Install
+Run the setup wizard:
 
 ```bash
-npm install -g @lark-project/meegle
+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.
+
 ## 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 steps you need.
+> **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.
 
 ```bash
-# (Optional) Persist the host so future logins skip the arrow-key picker
-meegle config set host <host>
-
-# 1. Log in (arrow-key host picker + browser OAuth)
-meegle auth login
+# 1. Install CLI + Skill, configure host, and log in
+npx @lark-project/meegle@latest install
 
 # 2. View this week's to-dos
 meegle mywork todo --action this_week --page-num 1
@@ -77,45 +76,15 @@ meegle inspect workitem.create
 
 ## Quick Start (AI Agent / CI / Headless)
 
-The default `meegle auth login` uses an arrow-key host picker plus a browser OAuth callback — both require a real TTY, so they will hang or fail in CI runners, pipes, and agent shells like Claude Code. Use the Device Code flow instead: it prints an authorization URL that the user opens in any browser.
-
-**Step 1 — Install the CLI**
-
-```bash
-npm install -g @lark-project/meegle
-```
-
-**Step 2 — Install the Agent Skill**
-
-> Recommended for AI-agent workflows, optional for direct CLI use. The skill teaches agents how to choose and run `meegle` commands correctly.
-
-```bash
-npx skills add larksuite/meegle-cli -y -g
-```
-
-**Step 3 — Persist the host**
+The default browser OAuth flow requires a real TTY. In CI runners, pipes, and agent shells like Claude Code, run the same setup wizard with an explicit host and Device Code login:
 
 ```bash
-meegle config set host <host>
+npx -y @lark-project/meegle@latest install --host <host> --device-code --lang en
 ```
 
-Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your self-hosted tenant domain such as `your-tenant.example.com`.
-
-**Step 4 — Log in with Device Code**
+Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your self-hosted tenant domain such as `your-tenant.example.com`. The Device Code flow prints an authorization URL; send it to the user and keep the command running until authorization completes.
 
-> Run this command in the background. It prints an authorization URL — extract it and send it to the user. The command exits automatically once the user completes authorization in the browser.
-
-```bash
-meegle auth login --device-code
-```
-
-Alternatively, pass the host inline each time without persisting it:
-
-```bash
-meegle auth login --device-code --host <host>
-```
-
-**Step 5 — Verify**
+Verify:
 
 ```bash
 meegle auth status
@@ -125,19 +94,7 @@ For fully unattended CI (no human-in-the-loop), inject a token via environment v
 
 ## AI Agent Skill
 
-`skills/meegle/` is a drop-in **skill** that teaches AI Agents — Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI — how to operate Meegle through this CLI. It bundles the command catalog, MQL syntax, field-value conventions, rich-text Markdown rules, and standard operating procedures for common write flows.
-
-### Install
-
-```bash
-# Install the CLI first (the skill calls `meegle` under the hood)
-npm install -g @lark-project/meegle
-
-# Then add the skill — auto-detects installed agents and registers in each
-npx skills add larksuite/meegle-cli -y -g
-```
-
-`npx skills add` reads `skills/meegle/SKILL.md` from the repo and drops it into the skill directory of every agent CLI it finds on the machine. Re-run any time to pick up updates.
+The setup wizard installs `skills/meegle/`, a drop-in skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI, and other agents. It teaches agents how to operate Meegle through this CLI instead of guessing command shapes from prose.
 
 ### What it covers
 
@@ -148,11 +105,9 @@ npx skills add larksuite/meegle-cli -y -g
 - **SOPs** — step-by-step playbooks for creating work items, transitioning nodes, transitioning states, and updating fields
 - **Auth guard** — the skill refuses to run business commands until `meegle auth status` succeeds
 
-See [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) and [skills/meegle/references/](./skills/meegle/references/) for the full contents.
-
 ### Usage
 
-Once installed, just ask the agent in natural language. For example, in Trae:
+Once the setup wizard has run, ask the agent in natural language. For example:
 
 ```
 Show me this week's P0 stories in the PROJ space.
@@ -160,8 +115,6 @@ Show me this week's P0 stories in the PROJ space.
 
 The agent consults the skill, picks the right `meegle` commands, and runs them for you. Pair with `--dry-run` (see [Security](#security--risk-warnings)) to preview side-effectful operations before the agent commits them.
 
-> Heads up: the skill name `meegle` is the same string as the CLI binary. When documentation refers to "the **`meegle` skill**" it means the files in `skills/meegle/`; when it refers to "the **`meegle` CLI**" it means the `meegle` command on your PATH.
-
 ## Commands
 
 ### workitem — Work Items

package/README.zh-CN.md

@@ -12,7 +12,7 @@
 
 ## 为什么选择 Meegle CLI？
 
-- **Agent 友好** — 附带一份 [AI Agent Skill](#ai-agent-skill)，一条命令即可把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、`--dry-run` 预览、`--device-code` 无 TTY 流程
+- **Agent 友好** — 安装向导会安装内置 AI Agent Skill，把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、`--dry-run` 预览、`--device-code` 无 TTY 流程
 - **覆盖完整** — 16 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间、附件、交付物、资源库、WBS 计划表），50+ 命令映射到 Meegle 核心能力
 - **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
 - **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
@@ -47,22 +47,21 @@
 
 - Node.js >= 16（自带 `npm` / `npx`）
 
-### 安装命令
+运行安装向导：
 
 ```bash
-npm install -g @lark-project/meegle
+npx @lark-project/meegle@latest install
 ```
 
+向导会全局安装或升级 CLI、安装 AI Agent Skill、配置 Meegle host，并启动登录。
+
 ## 快速开始（人类用户）
 
-> **给 AI Agent 的提示：** 如果你是在替用户完成这套安装的 AI Agent，请直接跳到 [快速开始（AI Agent）](#快速开始ai-agent--ci--无头环境) —— 那里有你需要的非交互步骤。
+> **给 AI Agent 的提示：** 如果你是在替用户完成这套安装的 AI Agent，请直接跳到 [快速开始（AI Agent）](#快速开始ai-agent--ci--无头环境) —— 那里有你需要的非交互命令。
 
 ```bash
-# （可选）持久化 host，后续登录就不用再选菜单
-meegle config set host <host>
-
-# 1. 登录（上下选择 host + 浏览器 OAuth）
-meegle auth login
+# 1. 安装 CLI + Skill，配置 host，并登录
+npx @lark-project/meegle@latest install
 
 # 2. 查看本周待办
 meegle mywork todo --action this_week --page-num 1
@@ -77,45 +76,17 @@ meegle inspect workitem.create
 
 ## 快速开始（AI Agent / CI / 无头环境）
 
-`meegle auth login` 默认走上下选择菜单 + 浏览器 OAuth 回调，依赖真实 TTY，在 CI Runner、管道、Claude Code 这类没有 TTY 的环境里会挂起或报错。这些场景请改用 Device Code 流程 —— 命令会输出授权 URL，让用户在浏览器里完成授权。
-
-**Step 1 — 安装 CLI**
+默认浏览器 OAuth 流程依赖真实 TTY。在 CI Runner、管道、Claude Code 这类环境里，使用同一个安装向导，但显式传入 host 并启用 Device Code 登录：
 
 ```bash
-npm install -g @lark-project/meegle
-```
-
-**Step 2 — 安装 Agent Skill**
-
-> 推荐用于 AI Agent 场景；如果只是手动使用 CLI，则是可选步骤。Skill 会教 Agent 正确选择和执行 `meegle` 命令。
-
-```bash
-npx skills add larksuite/meegle-cli -y -g
-```
-
-**Step 3 — 持久化 host**
-
-```bash
-meegle config set host <host>
+npx -y @lark-project/meegle@latest install --host <host> --device-code --lang zh
 ```
 
 `<host>` 示例：`project.feishu.cn`、`meegle.com`，或自建租户域名（如 `your-tenant.example.com`）。
 
-**Step 4 — Device Code 登录**
-
-> 建议后台执行。命令会输出授权 URL —— 提取后发给用户，用户在浏览器完成授权后命令自动退出。
-
-```bash
-meegle auth login --device-code
-```
-
-如不想持久化 host，也可以每次显式传入：
+Device Code 流程会输出授权 URL；把链接发给用户，并保持命令运行直到用户在浏览器完成授权。
 
-```bash
-meegle auth login --device-code --host <host>
-```
-
-**Step 5 — 验证**
+验证：
 
 ```bash
 meegle auth status
@@ -125,19 +96,7 @@ meegle auth status
 
 ## AI Agent Skill
 
-`skills/meegle/` 是一份可直接加载的 **skill**，用来教 AI Agent —— Trae、Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot CLI —— 通过本 CLI 操作 Meegle。它把命令目录、MQL 语法、字段值写法、富文本 Markdown 规则，以及常见写入流程的 SOP 全部打包好。
-
-### 安装
-
-```bash
-# 先装 CLI（skill 底层会调用 meegle 命令）
-npm install -g @lark-project/meegle
-
-# 再加载 skill —— 会自动探测已装的 Agent，并在各自的 skill 目录里登记
-npx skills add larksuite/meegle-cli -y -g
-```
-
-`npx skills add` 会从仓库读取 `skills/meegle/SKILL.md`，写入本机所有 Agent CLI 的 skill 目录。每次升级重跑一遍即可拉取最新内容。
+安装向导会安装 `skills/meegle/`，这是一份可直接加载到 Trae、Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot CLI 等 Agent 的 skill。它会教 Agent 通过本 CLI 操作 Meegle，而不是从自然语言说明里猜命令形状。
 
 ### 覆盖内容
 
@@ -148,11 +107,9 @@ npx skills add larksuite/meegle-cli -y -g
 - **SOP** — 创建工作项、节点流转、状态流转、更新字段等场景的分步剧本
 - **授权守护** — 所有业务命令前强制先过 `meegle auth status`
 
-完整内容见 [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) 和 [skills/meegle/references/](./skills/meegle/references/)。
-
 ### 使用方式
 
-安装后直接用自然语言和 Agent 对话。例如 Trae：
+安装向导执行完成后，直接用自然语言和 Agent 对话。例如：
 
 ```
 帮我看一下 PROJ 空间本周待办里的 P0 需求
@@ -160,8 +117,6 @@ npx skills add larksuite/meegle-cli -y -g
 
 Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--dry-run`（见 [安全](#安全与风险提示)）可以在 Agent 真正执行副作用前先预览请求。
 
-> 小提示：skill 的名字 `meegle` 和 CLI 二进制同名。文档里提到 **`meegle` skill** 时指 `skills/meegle/` 里的文件；提到 **`meegle` CLI** 时指你 PATH 上的 `meegle` 命令。
-
 ## 命令一览
 
 ### workitem — 工作项域

package/bin/install-wizard.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+const { execFileSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+
+const PKG = "@lark-project/meegle";
+const SKILLS_REPO = "larksuite/meegle-cli";
+const DEFAULT_HOST = "meegle.com";
+const PRESET_HOSTS = [
+  { label: "Feishu Project (project.feishu.cn)", value: "project.feishu.cn" },
+  { label: "Meegle (meegle.com)", value: "meegle.com" },
+];
+const isWindows = process.platform === "win32";
+
+const messages = {
+  en: {
+    setup: "Setting up Meegle CLI...",
+    language: "Select language",
+    installing: "Installing %s globally...",
+    upgrading: "Upgrading %s (v%s -> v%s)...",
+    installedSkip: "Already installed globally (v%s). Skipped",
+    installed: "CLI installed globally",
+    skills: "Installing AI Agent Skill...",
+    skillsDone: "AI Agent Skill installed",
+    hostExisting: "Found existing host: %s. Use it?",
+    hostSelect: "Select Meegle site",
+    hostCustom: "Custom domain",
+    hostInput: "Enter custom domain, for example project.feishu.cn: ",
+    hostConfigured: "Host configured: %s",
+    authSkip: "Skipped authorization. Run later: meegle auth login",
+    authAlready: "Already authenticated. Skipped authorization",
+    authConfirm: "Log in now?",
+    authBrowser: "Starting browser OAuth login...",
+    authDevice: "Starting Device Code login...",
+    done: "Setup complete. Try: meegle mywork todo --action this_week --page-num 1",
+    nonTtyHost: "No TTY detected and no --host was provided. Using default host: %s",
+  },
+  zh: {
+    setup: "正在设置 Meegle CLI...",
+    language: "请选择语言",
+    installing: "正在全局安装 %s...",
+    upgrading: "正在升级 %s (v%s -> v%s)...",
+    installedSkip: "已全局安装 (v%s)，跳过",
+    installed: "CLI 已全局安装",
+    skills: "正在安装 AI Agent Skill...",
+    skillsDone: "AI Agent Skill 已安装",
+    hostExisting: "发现已有 host: %s，继续使用？",
+    hostSelect: "请选择 Meegle 站点",
+    hostCustom: "自定义域名",
+    hostInput: "请输入自定义域名，例如 project.feishu.cn: ",
+    hostConfigured: "Host 已配置: %s",
+    authSkip: "已跳过授权。后续可运行: meegle auth login",
+    authAlready: "已登录，跳过授权",
+    authConfirm: "现在登录？",
+    authBrowser: "正在启动浏览器 OAuth 登录...",
+    authDevice: "正在启动 Device Code 登录...",
+    done: "安装完成。可以试试: meegle mywork todo --action this_week --page-num 1",
+    nonTtyHost: "当前不是交互终端且未传 --host，将使用默认 host: %s",
+  },
+};
+
+function fmt(template, ...values) {
+  let i = 0;
+  return template.replace(/%s/g, () => String(values[i++] ?? ""));
+}
+
+function parseArgs(argv) {
+  const opts = {
+    auth: true,
+    skills: true,
+    deviceCode: false,
+    yes: false,
+    host: "",
+    lang: "",
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--host" && argv[i + 1]) {
+      opts.host = argv[++i];
+    } else if (arg.startsWith("--host=")) {
+      opts.host = arg.slice("--host=".length);
+    } else if (arg === "--lang" && argv[i + 1]) {
+      opts.lang = argv[++i];
+    } else if (arg.startsWith("--lang=")) {
+      opts.lang = arg.slice("--lang=".length);
+    } else if (arg === "--device-code") {
+      opts.deviceCode = true;
+    } else if (arg === "--no-auth") {
+      opts.auth = false;
+    } else if (arg === "--no-skills") {
+      opts.skills = false;
+    } else if (arg === "-y" || arg === "--yes") {
+      opts.yes = true;
+    } else if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  if (opts.lang !== "zh" && opts.lang !== "en") {
+    opts.lang = "";
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`Usage: meegle install [options]
+
+Set up Meegle CLI, AI Agent Skill, host configuration, and login.
+
+Options:
+  --host <host>       Configure a site host, e.g. project.feishu.cn
+  --device-code       Use Device Code login instead of browser OAuth
+  --no-auth           Skip login
+  --no-skills         Skip AI Agent Skill installation
+  --lang <en|zh>      Select wizard language
+  -y, --yes           Use defaults for non-essential prompts
+  -h, --help          Show help`);
+}
+
+function cmdParts(cmd, args) {
+  if (!isWindows) return { cmd, args };
+  return { cmd: "cmd.exe", args: ["/c", cmd, ...args] };
+}
+
+function run(cmd, args, opts = {}) {
+  const actual = cmdParts(cmd, args);
+  const result = spawnSync(actual.cmd, actual.args, {
+    stdio: "inherit",
+    env: process.env,
+    ...opts,
+  });
+  if (result.signal) process.kill(process.pid, result.signal);
+  if (result.status !== 0) {
+    throw new Error(`${cmd} ${args.join(" ")} failed with exit code ${result.status}`);
+  }
+}
+
+function runSilent(cmd, args, opts = {}) {
+  const actual = cmdParts(cmd, args);
+  return execFileSync(actual.cmd, actual.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: process.env,
+    ...opts,
+  });
+}
+
+function runCapture(cmd, args, opts = {}) {
+  const actual = cmdParts(cmd, args);
+  return spawnSync(actual.cmd, actual.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: process.env,
+    ...opts,
+  });
+}
+
+function question(prompt) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function select(message, options) {
+  console.log(message);
+  options.forEach((opt, idx) => {
+    console.log(`  ${idx + 1}. ${opt.label}`);
+  });
+  for (;;) {
+    const answer = await question("> ");
+    const idx = Number(answer);
+    if (Number.isInteger(idx) && idx >= 1 && idx <= options.length) {
+      return options[idx - 1].value;
+    }
+  }
+}
+
+async function confirm(message, defaultValue) {
+  const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
+  const answer = (await question(message + suffix)).toLowerCase();
+  if (!answer) return defaultValue;
+  return answer === "y" || answer === "yes";
+}
+
+function semverLessThan(a, b) {
+  const pa = String(a).replace(/-.*/, "").split(".").map(Number);
+  const pb = String(b).replace(/-.*/, "").split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return true;
+    if ((pa[i] || 0) > (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+function getGloballyInstalledVersion() {
+  try {
+    const out = runSilent("npm", ["list", "-g", PKG, "--depth=0"], { timeout: 15000 });
+    const match = out.match(/@lark-project\/meegle@([^\s]+)/);
+    return match ? match[1] : "unknown";
+  } catch (_) {
+    return null;
+  }
+}
+
+function getLatestVersion() {
+  try {
+    const out = runSilent("npm", ["view", PKG, "version"], { timeout: 15000 }).trim();
+    return /^\d+\.\d+\.\d+/.test(out) ? out : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function whichMeegle() {
+  try {
+    const prefix = runSilent("npm", ["prefix", "-g"], { timeout: 15000 }).trim();
+    const bin = isWindows ? path.join(prefix, "meegle.cmd") : path.join(prefix, "bin", "meegle");
+    if (fs.existsSync(bin)) return bin;
+  } catch (_) {
+    // fall through
+  }
+  try {
+    const cmd = isWindows ? "where" : "which";
+    const out = runSilent(cmd, ["meegle"], { timeout: 15000 });
+    return out.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function normalizeHost(raw) {
+  const trimmed = String(raw || "").trim();
+  if (!trimmed) return "";
+  try {
+    const withScheme = trimmed.includes("://") ? trimmed : `https://${trimmed}`;
+    return new URL(withScheme).host;
+  } catch (_) {
+    return trimmed.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+  }
+}
+
+async function selectLanguage(opts) {
+  if (opts.lang) return opts.lang;
+  const locale = (process.env.LANG || process.env.LANGUAGE || "").toLowerCase();
+  if (!process.stdin.isTTY || opts.yes) return locale.includes("zh") ? "zh" : "en";
+  return select("Select language / 请选择语言", [
+    { label: "English", value: "en" },
+    { label: "中文", value: "zh" },
+  ]);
+}
+
+async function stepInstallGlobally(msg) {
+  const installed = getGloballyInstalledVersion();
+  const latest = getLatestVersion();
+  const needsUpgrade = installed && latest && semverLessThan(installed, latest);
+  if (installed && !needsUpgrade) {
+    console.log(fmt(msg.installedSkip, installed));
+    return;
+  }
+  console.log(needsUpgrade ? fmt(msg.upgrading, PKG, installed, latest) : fmt(msg.installing, PKG));
+  run("npm", ["install", "-g", PKG], { timeout: 120000 });
+  console.log(msg.installed);
+}
+
+async function stepInstallSkills(msg) {
+  console.log(msg.skills);
+  // `skills add` is idempotent (with `-y`): re-running on an already-installed
+  // 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 });
+  console.log(msg.skillsDone);
+}
+
+function getConfiguredHost(meegleBin) {
+  try {
+    const out = runSilent(meegleBin, ["config", "get", "host"], { timeout: 15000 }).trim();
+    if (!out || out === "(not set)") return "";
+    return normalizeHost(out);
+  } catch (_) {
+    return "";
+  }
+}
+
+async function resolveHost(opts, msg, meegleBin) {
+  if (opts.host) return normalizeHost(opts.host);
+  const existing = getConfiguredHost(meegleBin);
+  if (existing) {
+    if (!process.stdin.isTTY || opts.yes) return existing;
+    if (await confirm(fmt(msg.hostExisting, existing), true)) return existing;
+  }
+  if (!process.stdin.isTTY || opts.yes) {
+    console.log(fmt(msg.nonTtyHost, DEFAULT_HOST));
+    return DEFAULT_HOST;
+  }
+  const selected = await select(msg.hostSelect, [
+    ...PRESET_HOSTS,
+    { label: msg.hostCustom, value: "__custom__" },
+  ]);
+  if (selected !== "__custom__") return selected;
+  return normalizeHost(await question(msg.hostInput));
+}
+
+function configureHost(meegleBin, host, msg) {
+  run(meegleBin, ["config", "set", "host", host], { timeout: 30000 });
+  console.log(fmt(msg.hostConfigured, host));
+}
+
+function isAuthenticated(meegleBin) {
+  const result = runCapture(meegleBin, ["auth", "status", "--format", "json"], { timeout: 15000 });
+  const text = result.stdout || "";
+  try {
+    const parsed = JSON.parse(text);
+    return !!parsed.authenticated;
+  } catch (_) {
+    return result.status === 0;
+  }
+}
+
+async function stepAuth(meegleBin, host, opts, msg) {
+  if (!opts.auth) {
+    console.log(msg.authSkip);
+    return;
+  }
+  if (isAuthenticated(meegleBin)) {
+    console.log(msg.authAlready);
+    return;
+  }
+  const useDeviceCode = opts.deviceCode || !process.stdin.isTTY;
+  if (!useDeviceCode && !opts.yes) {
+    const shouldLogin = await confirm(msg.authConfirm, true);
+    if (!shouldLogin) {
+      console.log(msg.authSkip);
+      return;
+    }
+  }
+  console.log(useDeviceCode ? msg.authDevice : msg.authBrowser);
+  const args = ["auth", "login", "--host", host];
+  if (useDeviceCode) args.push("--device-code");
+  run(meegleBin, args, { timeout: 900000 });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  const lang = await selectLanguage(opts);
+  const msg = messages[lang];
+  console.log(msg.setup);
+
+  await stepInstallGlobally(msg);
+  if (opts.skills) {
+    await stepInstallSkills(msg);
+  }
+
+  const meegleBin = whichMeegle();
+  if (!meegleBin) {
+    throw new Error("meegle was installed but no global executable was found in PATH");
+  }
+  const host = await resolveHost(opts, msg, meegleBin);
+  configureHost(meegleBin, host, msg);
+  await stepAuth(meegleBin, host, opts, msg);
+
+  console.log(msg.done);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err && err.message ? err.message : err);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/bin/meegle.js

@@ -15,30 +15,38 @@ 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);
 
-try {
-  fs.accessSync(binPath, fs.constants.X_OK);
-} catch {
-  const detected = `${platform}-${arch}`;
-  const isSupported = SUPPORTED.includes(detected);
-  console.error(
-    isSupported
-      ? `meegle binary is missing or not executable.\n` +
-        `Detected platform: ${detected}\n` +
-        `Expected binary at: ${binPath}\n` +
-        `Try reinstalling: npm i -g @lark-project/meegle\n` +
-        `If the problem persists, please file an issue with the output of: node -v && npm -v`
-      : `Unsupported platform: ${detected}\n` +
-        `Supported platforms: ${SUPPORTED.join(", ")}`
-  );
-  process.exit(1);
-}
+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 {
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+  } catch {
+    const detected = `${platform}-${arch}`;
+    const isSupported = SUPPORTED.includes(detected);
+    console.error(
+      isSupported
+        ? `meegle binary is missing or not executable.\n` +
+          `Detected platform: ${detected}\n` +
+          `Expected binary at: ${binPath}\n` +
+          `Try reinstalling: npm i -g @lark-project/meegle\n` +
+          `If the problem persists, please file an issue with the output of: node -v && npm -v`
+        : `Unsupported platform: ${detected}\n` +
+          `Supported platforms: ${SUPPORTED.join(", ")}`
+    );
+    process.exit(1);
+  }
 
-const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+  const result = spawnSync(binPath, 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);
+  // 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);
 }
-process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-project/meegle",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "homepage": "https://github.com/larksuite/meegle-cli#readme",
@@ -28,6 +28,7 @@
   ],
   "files": [
     "bin/meegle.js",
+    "bin/install-wizard.js",
     "bin/meegle-*",
     "README.md",
     "README.zh-CN.md",