fix: align cli commands

Andrew1989Y · Andrew1989Y · commit faa24202447e · 2026-04-29T18:30:35.000+08:00
diff --git a/skills/nocobase-env-manage/SKILL.md b/skills/nocobase-env-manage/SKILL.md
@@ -1,23 +1,25 @@
 ---
 name: nocobase-env-manage
-description: "Use when users need NocoBase bootstrap and runtime lifecycle with nb CLI only."
-argument-hint: "[task: install|app-manage|upgrade|start|stop]"
+description: "Use when users need NocoBase bootstrap, runtime lifecycle, CLI maintenance, and skills maintenance with nb CLI only."
+argument-hint: "[task: install|app-manage|upgrade|start|stop|restart|logs|down|self-check|self-update|skills-check|skills-update]"
 allowed-tools: Bash, Read, Write, Grep, Glob
 owner: platform-tools
-version: 2.5.1
-last-reviewed: 2026-04-23
+version: 2.6.0
+last-reviewed: 2026-04-29
 risk-level: medium
 ---
 
 # Goal
 
-Use `nb` CLI only to complete NocoBase bootstrap and lifecycle actions.
+Use `nb` CLI only to complete NocoBase bootstrap, lifecycle, and maintenance actions.
 
 # Scope
 
 - Bootstrap or connect NocoBase environments through `nb init`.
 - Manage saved CLI environments through `nb env`.
 - Manage app runtime lifecycle through `nb app`.
+- Check and update the `nb` CLI through `nb self`.
+- Check and update installed NocoBase skills through `nb skills`.
 - Inspect built-in database runtime only when it helps verify or diagnose the selected environment.
 
 # Non-Goals
@@ -39,6 +41,9 @@ Use `nb` CLI only to complete NocoBase bootstrap and lifecycle actions.
 - Never proactively fill install/setup forms on the user's behalf; only surface the URL, explain the next step, and let the user complete the form.
 - If the CLI prints a continuation or recovery command, especially `nb init ... --resume ...`, execute that exact direct `nb` command unless it is destructive or conflicts with the user's latest instruction.
 - Use `nb app <command>` for runtime lifecycle operations.
+- Use `nb self <command>` only for CLI self-check/update.
+- Use `nb skills <command>` only for installed skills check/update.
+- Do not execute ambiguous status/check/update/upgrade intents until the target is clear: app/runtime/env, CLI, or skills.
 - Do not add extra precheck gates before executing user-requested `nb` commands.
 - Prefer executing user-requested runtime commands first; use `nb --help` when user asks for diagnostics/help output or command discovery is needed.
 - Surface CLI outputs and hints directly to users.
@@ -53,12 +58,16 @@ Use `nb` CLI only to complete NocoBase bootstrap and lifecycle actions.
 - `restart`
 - `logs`
 - `down`
+- `self-check`
+- `self-update`
+- `skills-check`
+- `skills-update`
 
 # Input Contract
 
 | Input | Required | Default | Notes |
 |---|---|---|---|
-| `task` | yes | inferred | one of `install/app-manage/upgrade/start/stop/restart/logs/down` |
+| `task` | yes | inferred | one of `install/app-manage/upgrade/start/stop/restart/logs/down/self-check/self-update/skills-check/skills-update` |
 | `app_env_action` | for `task=app-manage` | `list` | one of `add/use/current/list/remove`; `current` is derived from list output |
 | `app_env_name` | conditional | none | required for `add/use/remove` |
 | `app_base_url` | conditional | none | required for `add`; accepts URL with or without `/api` (auto-normalized) |
@@ -69,6 +78,7 @@ Use `nb` CLI only to complete NocoBase bootstrap and lifecycle actions.
 # Execution Policy
 
 - Execute the target `nb` command directly.
+- Intent clarification is not a precheck gate. If the user's wording is ambiguous, ask one concise clarification question before running any command.
 - Install routing:
   - when the user provides an official NocoBase install or quick-start URL, read it first and follow that official flow, ignoring local install command tables on conflict
   - otherwise use `nb init --ui` as the guided install entrypoint
@@ -91,6 +101,45 @@ Use `nb` CLI only to complete NocoBase bootstrap and lifecycle actions.
 - For `env add`, normalize API base URL before execution:
   - if URL already ends with `/api`, keep as-is
   - otherwise append `/api`
+- For CLI maintenance, execute the exact command requested by task:
+  - `self-check` -> `nb self check --json`
+  - `self-update` -> `nb self update --yes`
+- For skills maintenance, execute the exact command requested by task:
+  - `skills-check` -> `nb skills check --json`
+  - `skills-update` -> `nb skills update --yes`
+- Preserve JSON check output from `nb self check --json` and `nb skills check --json` when reporting results.
+- After `self-update` or `skills-update`, run the matching check command as readback unless the CLI says the shell/session must be restarted first.
+
+# Intent Disambiguation
+
+When the user says generic status/check/update/upgrade wording without an explicit target, do not infer a command.
+
+Ambiguous examples include:
+
+- `检查状态`
+- `检查一下`
+- `健康检查`
+- `诊断一下`
+- `检查更新`
+- `升级`
+- `更新`
+- `修复`
+
+Ask which target they mean before executing:
+
+- app/runtime/env: `nb env list`, `nb env info`, or `nb app ...`
+- CLI: `nb self check --json` or `nb self update --yes`
+- skills: `nb skills check --json` or `nb skills update --yes`
+
+Clarification template:
+
+- `你想检查/更新哪一类：NocoBase app/runtime/env、nb CLI，还是已安装 skills？`
+
+Treat these as clear targets:
+
+- explicit command text, such as `nb self check --json`
+- exact task names, such as `self-check` or `skills-update`
+- wording that names the target, such as `检查 nb CLI`, `更新已安装 skills`, `升级 NocoBase app`, `检查当前环境`
 
 # Env Resolution Rule
 
@@ -103,11 +152,13 @@ For `upgrade/start/stop/restart/logs/down`:
 # Workflow
 
 1. Infer the requested task and any explicit env name, API base URL, auth mode, or official install URL.
-2. For install requests with an official URL, read the URL first and follow the official guide flow.
-3. Execute only direct `nb` commands from the current command map or from CLI-provided continuation hints.
-4. Keep interactive install commands alive until completion, actionable failure, or user interruption.
-5. Verify with `nb env list`, `nb env info`, and app/database status when relevant.
-6. Report executed commands, important CLI output, and the next concrete action.
+2. If status/check/update/upgrade intent could target app/runtime/env, CLI, or skills, ask for clarification before executing.
+3. For install requests with an official URL, read the URL first and follow the official guide flow.
+4. Execute only direct `nb` commands from the current command map or from CLI-provided continuation hints.
+5. Keep interactive install commands alive until completion, actionable failure, or user interruption.
+6. Verify with `nb env list`, `nb env info`, and app/database status when relevant.
+7. For CLI/skills maintenance, use the `nb self` / `nb skills` commands exactly as mapped.
+8. Report executed commands, important CLI output, and the next concrete action.
 
 # Command Map
 
@@ -232,12 +283,48 @@ nb app logs [--env <env>] [--tail <lines>] [--no-follow]
 nb app down [--env <env>]
 ```
 
+## self-check
+
+```bash
+nb self check --json
+```
+
+Use this for `nb` CLI health/version/update checks. No env is required.
+
+## self-update
+
+```bash
+nb self update --yes
+nb self check --json
+```
+
+Run the update command first. Run the check command afterward as readback unless the CLI says a new shell/session is required.
+
+## skills-check
+
+```bash
+nb skills check --json
+```
+
+Use this for installed NocoBase skills health/version/update checks. No env is required.
+
+## skills-update
+
+```bash
+nb skills update --yes
+nb skills check --json
+```
+
+Run the update command first. Run the check command afterward as readback unless the CLI says a new shell/session is required.
+
 # Safety
 
 - Never run `upgrade` on ambiguous env.
 - Ask explicit confirmation before `upgrade` when user intent is not explicit.
 - Treat `nb app down` as destructive because it removes runtime containers and saved local app files. Always ask explicit confirmation before running it.
 - Never pass `--all` or `--yes` to `nb app down` unless the user explicitly requests those flags.
+- Treat `nb self update --yes` and `nb skills update --yes` as allowed update shortcuts only when the user clearly requests CLI or skills update.
+- Do not substitute package-manager update commands (`npm`, `pnpm`, `yarn`) for `nb self update --yes` or `nb skills update --yes`.
 
 Confirmation template:
 
@@ -247,18 +334,19 @@ Confirmation template:
 
 Require explicit user confirmation before:
 
+- ambiguous status/check/update/upgrade intents where the target could be app/runtime/env, CLI, or skills.
 - `nb app upgrade` when the target env is ambiguous or the user did not clearly request an upgrade.
 - `nb app down` in all cases.
 - `nb env remove <name> -f`.
-- Any command that includes `--all`, `--yes`, or force-style deletion flags.
+- Any command that includes `--all`, `--yes`, or force-style deletion flags, except exact `nb self update --yes` / `nb skills update --yes` commands when the user clearly requested that update.
 
 # Output Contract
 
 Final response must include:
 
 - selected task
 - executed commands
-- relevant CLI outputs (including error/hint lines when failed)
+- relevant CLI outputs, including JSON check output and error/hint lines when failed
 - normalized API base URL (for `env add`)
 - next action
 
@@ -279,6 +367,10 @@ Final response must include:
 - Any CLI-provided `nb init ... --resume ...` continuation was followed or surfaced with a blocker.
 - Runtime lifecycle commands used `nb app ...`.
 - Env operations used the final `nb env` syntax.
+- Ambiguous status/check/update/upgrade wording was clarified before command execution.
+- CLI maintenance used `nb self check --json` or `nb self update --yes`.
+- Skills maintenance used `nb skills check --json` or `nb skills update --yes`.
+- Maintenance update commands were followed by matching check commands when the CLI allowed it.
 - Final readback used `nb env list` and, when relevant, `nb env info`.
 
 # References
diff --git a/skills/nocobase-env-manage/agents/openai.yaml b/skills/nocobase-env-manage/agents/openai.yaml
@@ -1,6 +1,6 @@
 interface:
   display_name: "NocoBase Env Manage"
-  short_description: "Bootstrap and manage NocoBase with nb CLI only"
+  short_description: "Bootstrap, lifecycle, CLI, and skills maintenance with nb CLI only"
   default_prompt: >
     Use $nocobase-env-manage with nb CLI only.
 
@@ -17,12 +17,17 @@ interface:
     - If install prints a URL that cannot be opened in a sandbox, ask to elevate/open outside the sandbox first; if the user refuses, provide the URL directly.
     - Never proactively fill or submit install/setup forms for the user.
     - Runtime lifecycle commands are under `nb app`.
+    - CLI self maintenance commands are under `nb self`.
+    - Skills maintenance commands are under `nb skills`.
+    - Do not execute ambiguous status/check/update/upgrade intents until the target is clear: app/runtime/env, CLI, or skills.
     - Do not add extra precheck gates before executing requested `nb` commands.
     - Prefer executing requested runtime commands first; use `nb --help` when user asks diagnostics/help output or command discovery is needed.
     - Relay CLI outputs and hints directly.
 
     Execution policy:
     - execute target command directly
+    - intent clarification is not a precheck gate: if the user says generic `检查状态`, `健康检查`, `诊断`, `检查更新`, `升级`, or `更新` without naming app/runtime/env, CLI, or skills, ask which target they mean before running any command
+    - clarification wording: `你想检查/更新哪一类：NocoBase app/runtime/env、nb CLI，还是已安装 skills？`
     - for `nb init --ui`, treat it as a long-running interactive command; wait for completion instead of interrupting it mid-run or stopping at the setup URL
     - when an install command fails with a CLI hint, follow the printed direct `nb` next-step command, especially `nb init ... --resume ...`
     - if command fails, report key CLI error/hint lines as-is and provide next action
@@ -35,6 +40,14 @@ interface:
     - for `env add`, normalize `--api-base-url` before execution:
       - if URL already ends with `/api`, keep as-is
       - otherwise append `/api`
+    - for CLI maintenance, execute exact commands:
+      - self-check: `nb self check --json`
+      - self-update: `nb self update --yes`, then `nb self check --json` unless CLI asks for a new shell/session first
+    - for skills maintenance, execute exact commands:
+      - skills-check: `nb skills check --json`
+      - skills-update: `nb skills update --yes`, then `nb skills check --json` unless CLI asks for a new shell/session first
+    - preserve JSON check output from `nb self check --json` and `nb skills check --json`
+    - do not substitute package-manager update commands for `nb self update --yes` or `nb skills update --yes`
 
     Tasks:
     - install: official URL flow when provided; otherwise `nb init --ui`; follow `--resume` hints; verify with `nb env list` and `nb env info`
@@ -51,6 +64,16 @@ interface:
     - restart: `nb app restart --env <env>`
     - logs: `nb app logs --env <env> --tail 100 --no-follow`
     - down: `nb app down --env <env>`; require explicit confirmation
+    - self-check: `nb self check --json`
+    - self-update: `nb self update --yes`
+    - skills-check: `nb skills check --json`
+    - skills-update: `nb skills update --yes`
+
+    Clear target examples:
+    - `检查 nb CLI` or `self-check` means `nb self check --json`
+    - `更新已安装 skills` or `skills-update` means `nb skills update --yes`
+    - `升级 NocoBase app` means `nb app upgrade --env <env>` after env resolution
+    - `检查当前环境` means `nb env list` / `nb env info`
 
     Env resolution for upgrade/start/stop/restart/logs/down/current:
     1) if explicit env is provided, use it
@@ -60,12 +83,16 @@ interface:
     After write actions (`env add/use/remove`), always run readback:
     - `nb env list`
 
+    After maintenance update actions, run matching readback unless CLI asks for a new shell/session first:
+    - after `nb self update --yes`: `nb self check --json`
+    - after `nb skills update --yes`: `nb skills check --json`
+
     If `nb env list` reports:
     - `No envs configured.`
     - `Run 'nb env add <name> --api-base-url <url>' to add one.`
     relay this to user directly and ask whether to create a new app (`nb init --ui`) or add env.
 
-    Output should include executed command, relevant CLI outputs, and normalized API base URL when `env add` is used.
+    Output should include executed command, relevant CLI outputs, JSON check output when present, and normalized API base URL when `env add` is used.
 
 policy:
   allow_implicit_invocation: true
diff --git a/skills/nocobase-env-manage/references/preflight-checklist.md b/skills/nocobase-env-manage/references/preflight-checklist.md
@@ -17,6 +17,8 @@ nb app --help
 nb app upgrade --help
 nb app stop --help
 nb app start --help
+nb self check --json
+nb skills check --json
 ```
 
 ## Rule
diff --git a/skills/nocobase-env-manage/references/troubleshooting.md b/skills/nocobase-env-manage/references/troubleshooting.md
@@ -10,6 +10,9 @@
 - [6) `nb init --ui` fails and prints `--resume`](#6-nb-init---ui-fails-and-prints--resume)
 - [7) Token mode env add fails](#7-token-mode-env-add-fails)
 - [8) Wrong env targeted for runtime command](#8-wrong-env-targeted-for-runtime-command)
+- [9) CLI self check or update fails](#9-cli-self-check-or-update-fails)
+- [10) Skills check or update fails](#10-skills-check-or-update-fails)
+- [11) Generic check or update intent is ambiguous](#11-generic-check-or-update-intent-is-ambiguous)
 
 ## 1) `nb` command not found
 
@@ -121,3 +124,64 @@ nb app upgrade --env <correct_env>
 nb app stop --env <correct_env>
 nb app start --env <correct_env>
 ```
+
+## 9) CLI self check or update fails
+
+Symptom:
+
+- `nb self check --json` reports an unhealthy CLI, version mismatch, or update availability
+- `nb self update --yes` fails or asks for a shell/session restart
+
+Fix:
+
+```bash
+nb self check --json
+nb self update --yes
+nb self check --json
+```
+
+If the update command says a new shell/session is required, stop after surfacing that message and ask the user to restart the shell or agent session before rechecking. Do not replace the command with `npm`, `pnpm`, or `yarn` update flows.
+
+## 10) Skills check or update fails
+
+Symptom:
+
+- `nb skills check --json` reports missing, stale, or invalid installed skills
+- `nb skills update --yes` fails or asks for a shell/session restart
+
+Fix:
+
+```bash
+nb skills check --json
+nb skills update --yes
+nb skills check --json
+```
+
+If the update command prints repair instructions, surface them directly. Do not edit installed skill files manually unless the user explicitly asks for local skill development.
+
+## 11) Generic check or update intent is ambiguous
+
+Symptom:
+
+- user says `检查状态`, `健康检查`, `诊断`, `检查更新`, `升级`, or `更新`
+- user does not name app/runtime/env, CLI, or skills
+
+Fix:
+
+Ask before executing:
+
+```text
+你想检查/更新哪一类：NocoBase app/runtime/env、nb CLI，还是已安装 skills？
+```
+
+Then run only the clarified command family:
+
+```bash
+nb env list
+nb env info
+nb app upgrade [--env <env>]
+nb self check --json
+nb self update --yes
+nb skills check --json
+nb skills update --yes
+```
diff --git a/skills/nocobase-env-manage/references/usage-guide.md b/skills/nocobase-env-manage/references/usage-guide.md
