nocobase-env-manage

目标

仅使用 nb CLI 完成 NocoBase 的引导、生命周期和维护操作。

范围

• 通过 nb init 引导或连接 NocoBase 环境。
• 通过 nb env 管理已保存的 CLI 环境。
• 通过 nb app 管理应用运行时生命周期。
• 通过 nb self 检查和更新 nb CLI。
• 通过 nb skills 检查和更新已安装的 NocoBase 技能。
• 仅在有助于验证或诊断所选环境时检查内置数据库运行时。

非目标

• 不实现 NocoBase 业务模型、UI 页面、工作流或插件。
• 不运行仓库本地辅助脚本来执行安装或生命周期操作。
• 用户提供官方安装 URL 时，不绕过官方安装指南。

硬性规则

• 只运行直接的 nb 命令。
• 绝不运行本地脚本（*.mjs、*.ps1、*.sh）。
• 绝不使用模板驱动的安装流程。
• 对于 task=install，如果用户提供了官方 NocoBase 安装或快速入门 URL，先阅读该 URL 并遵循官方指南流程。若本地安装命令表与官方指南冲突，则忽略本地安装命令表。
• 对于 task=install，除非当前官方指南另有说明，否则使用 nb init --ui 作为引导式安装入口。
• nb init --ui 不代表安装已完成。继续遵循 CLI 输出，直到设置完成或 CLI 以可执行的故障提示退出。
• 执行 nb init --ui 时，将 CLI 超时时间设为 30 分钟，并且在命令退出前不要中断。
• 如果安装流程显示的 URL 因 Agent 在沙盒环境中运行而无法打开，请明确请求提升权限或在沙盒外打开；如果用户拒绝，则直接向用户提供该 URL。
• 绝不主动代替用户填写安装/设置表单；只提供 URL、说明下一步，并让用户自行完成表单。
• 如果 CLI 输出了继续执行或恢复命令，尤其是 nb init ... --resume ...，则执行该条直接的 nb 命令，除非该命令具有破坏性或与用户最新指令冲突。
• 使用 nb app <command> 执行运行时生命周期操作。
• 仅使用 nb self <command> 检查/更新 CLI 本身。
• 仅使用 nb skills <command> 检查/更新已安装的技能。
• 对于含义不明确的状态/检查/更新/升级意图，在目标明确之前不要执行：应用/运行时/环境、CLI 或技能。
• 执行用户请求的 nb 命令前，不要额外增加预检查关卡。
• 优先先执行用户请求的运行时命令；仅当用户请求诊断/帮助输出或需要探索命令时，才使用 nb --help。
• 直接向用户展示 CLI 输出和提示。

支持的任务

• install
• app-manage
• upgrade
• stop
• start
• restart
• logs
• down
• self-check
• self-update
• skills-check
• skills-update

输入约定

输入	必填	默认值	备注
task	是	推断	以下之一：install/app-manage/upgrade/start/stop/restart/logs/down/self-check/self-update/skills-check/skills-update
app_env_action	task=app-manage 时必填	list	以下之一：add/use/current/list/remove；current 根据列表输出确定
app_env_name	条件必填	无	add/use/remove 时必填
app_base_url	条件必填	无	add 时必填；接受带或不带 /api 的 URL（会自动规范化）
cli_auth_mode	添加环境时必填	oauth	以下之一：oauth/token
app_token	条件必填	无	cli_auth_mode=token 时必填
runtime_env_name	upgrade/start/stop/restart/logs/down 时可选	当前环境	明确指定的运行时环境名称

执行策略

• 直接执行目标 nb 命令。
• 意图澄清不是执行命令前的必经步骤。如果用户的措辞含糊，请先提出一个简短的澄清问题，再运行任何命令。
• 安装路由：
  • 当用户提供 NocoBase 官方安装或快速入门 URL 时，先阅读该页面并遵循官方流程；如与本地安装命令表冲突，以官方流程为准。
  • 否则，使用 nb init --ui 作为引导式安装入口。
• 对于 task=install，将 nb init --ui 视为长时间运行的交互式命令：
  • 将命令超时设置为 30 分钟。
  • 不要中断命令、缩短等待时间或以会导致 CLI 在完成前退出的方式轮询。
  • 不要仅因打印了本地设置 URL 就停止。
  • 持续执行，直到 CLI 报告已就绪、工作区已完成，或明确失败。
• 如果 nb init --ui 打印了本地 URL，且在沙盒中无法打开浏览器，应先请求提升权限／在沙盒外打开；如果用户拒绝，则提供该 URL，供用户手动打开。
• 在安装／设置流程中，绝不代替用户提交或填写网页表单；只能提供操作说明。
• 如果安装失败，且 CLI 打印了恢复命令，下一步应运行打印出的 nb init ... --resume ... 命令。除非 CLI 要求或用户明确提出，否则不要重新开始安装。
• 除非用户明确要求诊断，否则不要运行单独的预检。
• 如果命令失败，返回 CLI 输出中的关键行和 CLI 提供的建议后续命令。
• 对于环境查询意图（list/current），使用快速路径：
  • 第一个命令：nb env list
  • 带前置 * 标记的行即为当前环境。
• 对于环境查询意图，尽量精简命令：
  • 需要发现命令时，可使用 nb env --help / nb env list --help。
• 对于环境详情和安装后的验证，优先使用 nb env info [name]，并检查应用／数据库／API 状态。
• 对于 env add，执行前规范化 API 基础 URL：
  • 如果 URL 已以 /api 结尾，则保持不变。
  • 否则追加 /api。
• 对于 CLI 维护，执行与任务完全对应的命令：
  • self-check -> nb self check --json
  • self-update -> nb self update --yes
• 对于 skills 维护，执行与任务完全对应的命令：
  • skills-check -> nb skills check --json
  • skills-update -> nb skills update --yes
• 报告结果时，保留 nb self check --json 和 nb skills check --json 的 JSON 检查输出。
• 执行 self-update 或 skills-update 后，运行对应的检查命令以读取更新结果，除非 CLI 提示必须先重启 shell／会话。

意图消歧

当用户使用泛指状态／检查／更新／升级等措辞，且没有明确目标时，不要自行推断命令。

含糊示例包括：

• 检查状态
• 检查一下
• 健康检查
• 诊断一下
• 检查更新
• 升级
• 更新
• 修复

执行前询问用户指的是哪一类：

• 你想检查/更新哪一类：NocoBase app/runtime/env、nb CLI，还是已安装 skills？

以下情况视为目标明确：

• 明确写出命令，例如 nb self check --json
• 明确写出准确的任务名称，例如 self-check 或 skills-update
• 明确指出目标，例如 检查 nb CLI、更新已安装 skills、升级 NocoBase app、检查当前环境

环境解析规则

对于 upgrade/start/stop/restart/logs/down：

1. 如果提供了 runtime_env_name，则传入 --env <env>。
2. 如果未提供环境，则不带 --env 运行命令，并遵循 CLI 的响应。
3. 如果 CLI 报告未配置环境，则告知用户该消息，并询问用户是要创建新应用还是添加环境。

工作流

1. 推断用户请求的任务，以及任何明确指定的环境名称、API 基础 URL、身份验证模式或官方安装 URL。
2. 如果状态／检查／更新／升级意图可能针对应用／运行时／环境、CLI 或技能，请先询问以澄清，再执行。
3. 对于带有官方 URL 的安装请求，先读取该 URL，并遵循官方指南的流程。
4. 仅执行当前命令映射或 CLI 提供的后续提示中的直接 nb 命令。
5. 让交互式安装命令持续运行，直到完成、出现可采取行动的失败，或用户中断。
6. 在相关时，通过 nb env list、nb env info 和应用／数据库状态进行验证。
7. 对于 CLI／技能维护，请严格使用映射中列出的 nb self／nb skills 命令。
8. 报告已执行的命令、重要的 CLI 输出以及下一步具体操作。

命令映射

install

nb init --ui
nb env list
nb env info

只有当 CLI 报告已就绪／完成（例如 NocoBase is ready ... 和 Workspace init finished），或当前官方指南显示等效的成功输出时，才算安装完成。

app-manage

list/current

nb env list
nb env info [name]

对于 current，根据 nb env list 输出中带有前导 * 的行确定。不要调用 nb env current。

当 CLI 返回：

• No envs configured.
• Run 'nb env add <name> --api-base-url <url>' to add one.

请直接显示此消息，并询问是否要创建新应用（nb init --ui）或添加环境。

add（oauth）

nb env add <name> --api-base-url <url> --auth-type oauth

<url> 使用规范化后的值（缺少 /api 时自动追加）。

add（token）

nb env add <name> --api-base-url <url> --auth-type token --access-token <token>

<url> 使用规范化后的值（缺少 /api 时自动追加）。

use

nb env use <name>

remove

nb env remove <name>

写入操作（add/use/remove）之后必须始终执行：

nb env list

只有在用户明确确认后，才使用 nb env remove <name> -f。

auth

nb env auth [name]

upgrade

nb app upgrade [--env <env>]

可选：

nb app upgrade [--env <env>] --skip-code-update

stop

nb app stop [--env <env>]

start

nb app start [--env <env>]

可选：

nb app start --env <env> --quickstart
nb app start --env <env> --port <port>
nb app start --env <env> --daemon
nb app start --env <env> --no-daemon

restart

nb app restart [--env <env>]

logs

nb app logs [--env <env>] [--tail <lines>] [--no-follow]

down

nb app down [--env <env>]

self-check

nb self check --json

用于检查 nb CLI 的运行状况／版本／更新。无需指定环境。

self-update

nb self update --yes
nb self check --json

先运行更新命令。除非 CLI 表示需要新的 shell／会话，否则随后运行检查命令以回读结果。

skills-check

nb skills check --json

用于检查已安装的 NocoBase 技能的运行状况／版本／更新。无需指定环境。

skills-update

nb skills update --yes
nb skills check --json

先运行更新命令。除非 CLI 表示需要新的 shell／会话，否则随后运行检查命令以回读结果。

安全

• 绝不要对不明确的环境运行 upgrade。
• 用户意图不明确时，运行 upgrade 前必须征得明确确认。
• 将 nb app down 视为破坏性操作，因为它会移除运行时容器和本地保存的应用文件。运行前必须始终征得明确确认。
• 除非用户明确要求这些标志，否则绝不要向 nb app down 传递 --all 或 --yes。
• 仅当用户明确要求更新 CLI 或技能时，才将 nb self update --yes 和 nb skills update --yes 视为允许使用的更新快捷命令。
• 不要使用包管理器更新命令（npm、pnpm、yarn）替代 nb self update --yes 或 nb skills update --yes。

确认模板：

• 确认执行：nb app upgrade --env <env>。回复 confirm 以继续。

安全门槛

以下操作需要用户明确确认：

• 目标可能是应用／运行时／环境、CLI 或技能，但状态／检查／更新／升级意图不明确。
• 目标环境不明确，或用户未明确要求升级时，执行 nb app upgrade。
• 任何情况下执行 nb app down。
• 执行 nb env remove <name> -f。
• 执行任何包含 --all、--yes 或强制删除标志的命令；但用户明确要求更新时，精确匹配的 nb self update --yes／nb skills update --yes 命令除外。

输出约定

最终回复必须包含：

• 选定的任务
• 已执行的命令
• 相关 CLI 输出，包括 JSON 检查输出，以及失败时的错误／提示行
• 规范化后的 API 基础 URL（用于 env add）
• 下一步操作

参考资料加载索引

参考资料	使用时机
使用指南	将用户意图映射到当前的 nb 命令。
安装操作手册	执行安装／引导流程，尤其是官方 URL 和恢复处理。
升级操作手册	使用 nb app upgrade 升级应用运行时。
预检清单	用户明确要求时进行可选诊断。
故障排除	解决 CLI 错误和版本不匹配问题。

验证清单

• 对于包含官方 URL 的安装请求，先读取并访问该 URL。
• 如果 nb init --ui 仅显示设置 URL，不应将其视为已完成。
• 如果 CLI 提供了 nb init ... --resume ... 续接命令，应执行该命令；如果存在阻碍，则应说明。
• 运行时生命周期命令使用 nb app ...。
• Env 操作使用最终版 nb env 语法。
• 执行命令前，应先澄清含糊的状态／检查／更新／升级表述。
• CLI 维护使用 nb self check --json 或 nb self update --yes。
• Skills 维护使用 nb skills check --json 或 nb skills update --yes。
• 如果 CLI 允许，维护更新命令之后应执行对应的检查命令。
• 最终回读使用 nb env list，并在相关情况下使用 nb env info。

参考资料

• 使用指南
• 安装操作手册
• 升级操作手册
• 预检清单
• 故障排除