nocobase-portal-manage

目标

将所有常规 NocoBase UI 编写工作分派到一个已明确解析的 Portal，并管理 Portal 工作区，同时保留环境选择和源存储配置，并在变更后清晰回读。

范围

• 检查 Portal 清单和详情。
• 启动每项常规 NocoBase 页面、菜单、区块、字段、操作、布局和反应请求时，先解析目标环境和 Portal。
• 使用 nocobase-ui-builder 技能构建无代码 Portal UI。
• 定位或拉取对应的 Portal 源码目录后，使用 nocobase-ai-builder 技能进行 AI Portal 源码开发。
• 根据模板创建 Portal 工作区。
• 配置 Portal 源存储，包括 Git 仓库、分支和路径。
• 在本地工作区、NocoBase 存储和 Git 源存储之间拉取和推送 Portal 源码。
• 部署 Portal 或启动 Portal 开发模式。
• 诊断常见 Portal CLI 和 Git 源存储故障。

只有在收到明确请求并获得确认后，才销毁 Portal。

非目标

• 不要直接在此技能中编写无代码 Modern UI 页面、区块、菜单、反应或页面内容；应使用 nocobase-ui-builder 技能，同时保留 Portal 环境和工作区上下文。
• 不要直接在此技能中实现 AI Portal 源码变更；应解析或拉取源码目录，并将相同请求转交给 nocobase-ai-builder。
• 不要管理应用运行时生命周期、CLI 自更新、环境设置或已安装技能的更新；应转交给 nocobase-env-manage。
• 不要管理备份恢复或迁移发布；应转交给 nocobase-publish-manage。
• 不要根据用户措辞、模板、源布局、当前目录或本地文件推断 Portal 类型；只能使用所选记录的 portalType。
• 为常规 UI 构建选择 AI Portal 后，该构建请求即授权在其源码项目中实现并测试变更；不要另行询问源码修改授权。
• 不要通过公开的 nb portal 命令接口之外的方式修改数据库或 NocoBase 内部组件。
• 不要运行包装脚本、Docker 备用命令或直接执行 SQL 来替代 nb portal。
• 不要将缺少 nb portal 视为可以通过私有 API 模拟 Portal 生命周期、源存储、同步、部署或销毁操作的许可。

硬性规则

• 执行任何 nb portal ... 命令前，先使用 nb portal --help、nb --help 或等效的本地命令帮助检查，确认已安装的 CLI 提供 Portal 命令集。
• 如果存在该命令集，使用直接的 nb portal 命令执行 Portal 生命周期、源代码存储、同步、部署和诊断操作。
• 如果 nb portal 不可用，将生命周期、源代码、部署和销毁任务报告为受已安装的 CLI 版本限制而无法执行，并将 CLI 更新／环境相关工作交由 nocobase-env-manage；不要切换传输方式。
• 将此技能视为所有常规 NocoBase UI 编写请求的入口，即使请求中没有出现“Portal”一词。
• 执行任何常规 UI 编写操作前，先使用 nb portal list -j 检查结构化 Portal 清单；仅统计 enabled === true 的记录。
• 将 nb portal list -j 中的 isDefault／默认标记仅作为信息性回读数据。列出选项或报告回读结果时应包含该信息，但绝不能据此从多个已启用的 Portal 中进行选择。
• 用户指定 Portal 时，必须在结构化记录中与其 CLI name 精确匹配。只有恰好匹配一条记录且该记录的 enabled === true 时才能继续；若未匹配、已停用或匹配不唯一，必须停止，不得替换为其他 Portal。
• 用户未指定 Portal 时：没有已启用的 Portal，则停止 UI 构建，不得自动创建；只有一个时自动选择；有多个时，按 name 和 portalType 列出，要求用户明确选择。
• 存在多个已启用的 Portal 时，不得自动选择 isDefault === true 的记录；应在列出时标注默认项，并询问用户要使用哪个 Portal。
• 不得根据当前工作目录、活动文件、附近或最近的 portal.config.json、localPath、同步状态、标题相似度或 Portal 类型偏好，推断多个 Portal 中的目标项。
• 只能根据所选 Portal 的 portalType 确定其实现路径；不得根据请求、模板、源代码树或本地工作区推断类型。
• 只有在选中 AI Portal 后，才能使用 portal.config.json、localPath 和其他本地工作区信息，并且只能用于定位其源项目，然后调用 nocobase-ai-builder。
• 所选记录的 portalType === "ai" 时，必须加载并执行 nocobase-ai-builder。如果 nb portal list -j 或 nb portal info <portal> -j 返回的 developmentPath／localPath／本地源代码路径为空，先运行 nb portal pull <portal>，随后重新读取 Portal 信息／清单，并进入拉取后的开发目录。传入解析出的 Portal 名称、环境、本地源代码路径和用户原始请求；不得改用临时的源代码编辑工作流。
• 不得将源代码存储配置用作 AI Portal 工作目录。sourceStorage、git_repo、git_branch、git_path、--git-path、仓库子目录以及部署／存储路径都是用于拉取／推送／部署的远程存储配置，并非本地开发目录。只能在所选 Portal 现有的 developmentPath／localPath 中编辑源代码，或在 nb portal pull <portal> 后根据回读结果进入返回的本地目录进行编辑。
• 如果命令未知，或 nb portal list -j 返回明确的端点不存在特征 404／Not Found，则视为 nb portal 在运行时不可用。仅对于常规 UI 编写请求，此时进入下方的旧版能力探测流程；Portal 生命周期／源代码／部署操作仍然无法执行。
• Portal 清单在运行时不可用时，不得将 flow-surfaces list-navigation-targets 用作 Portal 清单，也不得据此推断使用无代码还是 AI。仅运行 nb api flow-surfaces list-navigation-targets -j 检查 capabilities.multiPortal：false 可进入旧版 UI Builder 路径；true 则停止。
• 较早的 Portal 前运行时可能不提供 list-navigation-targets。如果该操作明确未知或返回 404／Not Found，且用户未指定 Portal，则只有在以下两项检查均成功后，才允许进入旧版 UI Builder 路径：nb api flow-surfaces --help 中提供 apply-blueprint 和 list-templates；nb api flow-surfaces list-templates --body '{}' -j 返回结构化成功响应。这是经验证的旧版 Flow Surfaces 特征。遇到身份验证错误、5xx、格式错误的输出、缺少核心操作或读取探测失败时，必须停止；不得将这些情况重新解释为旧版证据。
• 除非用户明确指定环境，否则使用当前配置的 CLI 环境。
• 传入可能不同于当前环境的明确环境时，仅在用户要求非交互式执行或明确确认目标环境后，才附加 --yes。
• 执行 destroy 前，必须取得用户明确确认。
• 执行 pull --force、create --force 或任何会覆盖本地 Portal 源代码的操作前，必须取得用户明确确认。
• 对于每个仓库对应一个 Portal 的 Git 工作流，优先使用 --git-path .。
• 只有当用户希望在同一 Git 仓库中存放多个 Portal 或其他内容时，才使用子目录 --git-path 值。
• 绝不能将 --git-path／git_path 值作为本地 Portal 项目目录进入或编辑。它是相对于仓库的存储路径，并非拉取后的开发目录。
• 如果现有的 portal.config.json 或远程 Portal 记录已配置 Git 路径，不要假定当前 CLI 默认值会将其改写；用户要求更改时，使用 nb portal config <portal> --git-path . 明确修改。
• 执行 push 时，若用户提供了提交说明，则使用该说明；否则采用 CLI 默认值。
• 源代码或 UI 变更后，不要自动运行 push 或 deploy。只有用户强调要推送／同步／提交 Portal 源代码时，才执行 push。只有用户强调要部署／发布／上线 Portal 时，才执行 deploy。请求部署不代表此前必须先推送。
• 用户明确同时请求 push 和 deploy 时，将二者视为独立操作。必须报告 push 失败，但除非用户明确表示部署取决于推送成功，例如“推送成功后再部署”、“仅在推送成功后部署”或类似表述，否则不得自动阻止已明确请求的 deploy。
• 命令失败时，报告相关 CLI 输出和下一条具体恢复命令，不要切换传输方式。

支持的任务

• list
• info
• create
• config
• pull
• push
• deploy
• dev
• destroy
• diagnose
• build

输入约定

输入	必填	默认值	验证	澄清问题
action	是	推断	必须是 build/list/info/create/config/pull/push/deploy/dev/destroy/diagnose 之一	“应该执行哪个 Portal 操作？”
portal	除 list 外的生命周期操作必填；build 时可选	build 时唯一启用的 Portal	精确的 CLI name	“应该以哪个 Portal 为目标？”
runtime_env_name	否	当前环境	已配置的 CLI 环境名称	“应该以哪个环境为目标？”
template	仅 create	CLI 默认值	npm 包、本地路径或 file:// URL	“应该使用哪个 Portal 模板？”
title	仅 create	根据 slug 生成	非空字符串	“这个 Portal 应使用什么显示标题？”
source_storage	仅 create/config	create 时为 nocobase，config 时为现有配置	nocobase 或 git	“源存储应使用 nocobase 还是 git？”
git_repo	Git create/config	无	完整的 Git 远程 URL	“应该使用哪个 Git 远程 URL 存储 Portal 源码？”
git_branch	否	main	非空分支名称	“应该使用哪个 Git 分支？”
git_path	否	.	仓库内的相对路径，不含 ..	“应该使用仓库中的哪个路径存储 Portal 源码？”
message	仅 push	CLI 默认值	非空提交消息	“应该使用什么提交消息？”
force	破坏性操作／覆盖操作	false	需要明确确认	“请确认覆盖／销毁后，我再继续。”

规则：

• 如果缺少变更操作所需的输入，则停止并提出一个简洁的澄清问题。
• 如果用户说“你决定”，则使用文档中说明的默认值，并直接采用 nb portal 行为。
• 除非可选输入的选择会实质影响数据、源或部署结果，否则不要询问有安全 CLI 默认值的可选输入。

必须澄清的步骤

• 最多澄清轮数：2。
• 每轮最多提问：3 个。
• 变更前，确认 action、portal、用户明确指定时的环境目标，以及所有必需的 Git 字段。
• destroy 前，要求二次确认。
• pull --force 或 create --force 前，要求二次确认。
• 配置 Git 存储但未提供 git_repo 时，询问 Git 远程 URL。
• 如果 Git 源存储失败提示远程仓库为空、缺少分支或未配置 Git 路径，请先查阅 Git 源存储进行诊断，再建议手动执行 Git 命令。

工作流

常规 UI 构建工作流

所有常规 NocoBase 页面、菜单、区块、字段、操作、布局或反应请求均使用此路径，包括未提及“Portal”的请求。

1. 使用 nb env current 和 nb env info 检查当前环境。
2. 使用 nb portal --help 或等效的命令帮助输出，检测是否支持 Portal CLI。
3. 如果 nb portal 不可用：
   • 对于 create/config/pull/push/deploy/dev/destroy/list/info 请求，停止并报告缺少 CLI 功能；建议使用 nocobase-env-manage 升级 CLI/运行时或诊断环境。
   • 对于常规 UI 编写，仅调用 nb api flow-surfaces list-navigation-targets -j 作为功能检查。如果 capabilities.multiPortal 明确为 false，使用 nocobase-ui-builder 旧版流程。如果为 true，停止。如果操作明确未知，或返回 404 / Not Found，使用 Hard Rules 中定义的、经过验证的旧版 Flow Surfaces 探测；仅当完整探测成功时才继续。其他缺失、不明确或失败的结果均应停止，并提供 CLI/运行时指导。
   • 切勿将导航目标视为无代码/AI Portal 清单。
4. 当命令可用时，使用 nb portal list -j 检查结构化 Portal 清单，并仅保留 enabled === true 的记录。如果此清单调用明确返回端点不存在（404 / Not Found），则视为运行时不可用，并对常规 UI 编写应用第 3 步；对于认证错误、5xx 或格式错误的输出，不要这样处理。
5. 确定目标 Portal：
   • 如果用户提供了 Portal 名称，必须恰好匹配一条 name 完全相同且 enabled 值为 true 的记录。未找到、已禁用或匹配不唯一时，停止构建。
   • 如果用户未指定 Portal 且不存在已启用的 Portal，停止并告知用户必须先明确创建一个 Portal。不要自动创建。
   • 如果用户未指定 Portal 且恰好存在一个已启用的 Portal，则自动选择它。
   • 如果用户未指定 Portal 且存在多个 Portal，列出每个 Portal 的 name、portalType，以及存在时的默认状态，请用户明确选择，并且不要执行任何 UI 写入。即使只有一条记录的 isDefault === true，也不能据此打破平局。
   • 不要根据 cwd、活动文件、portal.config.json、localPath、同步状态、标题相似度或类型偏好推断目标。
6. 读取所选记录的 portalType。它是无代码与 AI 路由的唯一依据。
7. 如果它是无代码 Portal，则使用 nocobase-ui-builder 技能编写页面、菜单、区块、字段、操作和权限。
8. 如果它是 AI Portal，则仅使用 nb portal info <portal> -j、所选列表记录的 developmentPath、localPath、portal.config.json 或本地工作区状态，来定位已选 Portal 的本地源项目。如果本地开发路径为空或缺失，先运行 nb portal pull <portal>，然后使用 nb portal info <portal> -j 或 nb portal list -j 重新读取，并进入拉取后的开发目录。不要将 sourceStorage、git_repo、git_branch、git_path、--git-path 和部署/存储路径用作编辑位置；它们只说明 Portal 源码的存储位置，用于 pull/push/deploy。随后加载并执行 nocobase-ai-builder，并提供已解析的 Portal 名称、环境、源路径和原始请求。原始请求已授权实现和验证；无需另外询问代码编辑授权。
9. 如果 portalType 缺失或不受支持，停止，不要猜测。
10. UI 更改后，不要自动运行 nb portal push 或 nb portal deploy。仅在需要本地验证或用户提出要求时使用 nb portal dev。仅当用户明确要求推送源码时才运行 push，仅当用户明确要求部署时才运行 deploy。

明确的 action=create 请求应继续执行 Portal Command Workflow。上述无 Portal 时停止的规则仅适用于常规 UI 构建，不得阻止用户明确提出的创建 Portal 生命周期请求。

Portal 命令工作流

1. 根据用户请求推断 Portal 操作和目标环境。
2. 执行不熟悉的命令形式或构造带标志的命令时，请先阅读 运行时契约。
3. 设置 Git 源码存储或排查相关故障时，请阅读 Git 源码存储。
4. 尝试执行操作前，先检查 nb portal 是否可用。
5. 如果 nb portal 不可用，请停止操作，不要尝试其他会修改状态的方式，并报告缺少的命令接口以及后续的 nocobase-env-manage 交接步骤。
6. 仅询问缺失的必需输入或必需确认。
7. 执行对应的 nb portal 命令。
8. 除 dev 外，写入操作完成后，若可用则使用 nb portal info <portal> 回读；否则使用 nb portal list -j。
9. 对于 push，报告源码更改是否已提交，或 CLI 是否报告没有更改。
10. 对于同时请求 push 和 deploy 的情况，按顺序独立执行所请求的操作。如果 push 失败，请记录失败情况，并在完成任何必需的部署确认后继续执行所请求的 deploy，除非用户明确表示只有 push 成功后才部署。如果请求中只有 deploy，则不要插入 push 步骤。
11. 对于失败，请返回失败的命令、CLI 的关键输出、可能的原因以及一条后续命令。

操作路由

• 对于“show portals”、“有哪些 portal”或“portal 列表”，使用 list。
• 对于“portal details”、“查看 portal 配置”或“当前 git 配置”，使用 info。
• 对于“创建 portal”、“new Portal workspace”或“from template”，使用 create。
• 对于“配置 portal git”、“改 source storage”或“set git repo/branch/path”，使用 config。
• 对于“拉取 portal 源码”或“sync remote to local”，使用 pull。
• 仅在明确要求推送源码时使用 push，例如“推送 portal 源码”、“push source”、“portal push”、“commit source to Git”或“sync Portal source”。不要根据一般的构建、完成、发布、部署或发行请求推断用户要执行 push。
• 仅在明确要求部署时使用 deploy，例如“部署 portal”、“deploy”、“publish online”或“release Portal”。除非用户也明确要求推送源码，否则不要先执行 push。
• 对于“启动 portal dev”或“local portal development”，使用 dev。
• 仅在明确要求删除或销毁时使用 destroy。
• 用户提供错误日志或询问 Portal 命令失败原因时，使用 diagnose。
• 对于所有常规的 NocoBase 页面、菜单、区块、字段、操作、布局或反应请求，无论是否提及 Portal，均使用 build。
• UI 请求未指定 Portal 名称时，先检查结构化环境清单：数量为零则停止；恰好一个则自动选择；多个则要求用户明确选择，即使其中一个已标记为默认项也是如此。
• 对于无代码 Portal 构建请求，使用 nocobase-ui-builder 技能编写 UI。
• 对于 AI Portal 构建请求，先定位 Portal 本地源码目录；如果 CLI 报告尚无开发路径，则先运行 nb portal pull <portal>，然后在拉取的目录中执行 nocobase-ai-builder。不要在 git_path / --git-path 等源码存储路径中开发。

参考资料加载表

参考资料	使用时机	备注
运行时契约	构造或检查直接调用 nb portal 的命令	包含命令映射、环境标志的位置以及回读规则。
Git 源码存储	配置 Git 源码存储或诊断 Git push/pull 故障	涵盖根路径默认值、空仓库以及分支／路径恢复。
测试手册	验证技能或规划能力检查	添加测试或前向测试技能前请先阅读。

安全门

高影响操作：

• nb portal destroy
• nb portal pull --force
• nb portal create --force
• 为共享或生产 Portal 配置 Git 源存储
• 将 nb portal deploy 部署到类生产环境

二次确认模板：

• 销毁：Confirm execution: destroy Portal <portal> in env <env>. Expected impact: Portal record/workspace may be removed. Reply confirm to continue.
• 覆盖本地源：Confirm execution: overwrite local Portal source for <portal> in env <env>. Reply confirm to continue.
• 生产部署：Confirm execution: deploy Portal <portal> to env <env>. Reply confirm to continue.

回滚指南：

• config 失败：使用 nb portal info <portal> 检查；如果知道之前的值，则使用这些值重新运行 nb portal config。
• pull --force 失败：被覆盖的本地文件可能需要从 Git 或备份恢复；不要臆造回滚方案。
• push 失败：检查 Git 错误；只有在分支、身份验证、仓库或路径问题得到纠正后才重试。
• deploy 失败：报告 CLI 输出，并运行 nb portal info <portal>；如果有特定于部署的回读命令，也可运行该命令。

验证清单

• 当命令接口支持所请求的操作时，已确定操作和 Portal 目标。
• nb portal 可用时，使用直接的 nb portal 命令。
• 执行 Portal 命令前，先检查 nb portal 是否可用。
• 保留显式 env 处理方式。
• 执行破坏性操作或覆盖操作前，已收集必要的确认。
• Git 源存储命令在需要时包含完整的远程 URL。
• 对于一个仓库对应一个 Portal 的工作流，默认 Git 路径使用 .。
• 写入操作会使用 nb portal info 或 nb portal list -j 进行回读。
• 对于普通 UI 构建请求，使用 nb portal list -j，筛选 enabled === true，仅将 isDefault 用于显示或回读，并在选择实现路径前确定唯一一个 Portal。
• 显式 Portal 名称必须与 name 完全匹配；存在多个 Portal 时，绝不使用本地上下文进行选择。
• 存在多个 Portal 时，绝不使用默认状态进行选择；仅将默认状态作为标记显示给用户。
• Portal 类型仅从 portalType 获取。
• 无代码 Portal UI 编写使用 nocobase-ui-builder 技能。
• AI Portal UI 编写在相应的 Portal 本地源目录中使用 nocobase-ai-builder；当 developmentPath / localPath 为空时，先运行 nb portal pull <portal> 拉取；绝不将 git_path / --git-path 等源存储路径视为编辑目录。
• UI/源代码编辑后绝不自动添加 push 和 deploy。源代码推送请求仅执行 push；部署请求仅执行 deploy；明确要求组合操作时，分别独立执行两者。
• 组合的 push + deploy 请求应分别保留这两项操作；push 失败时需报告，但除非明确要求 deploy 以 push 成功为前提，否则不得阻止 deploy。
• 失败输出包含失败的命令和相关 CLI 行。
• 最终答复报告命令、结果、回读状态、假设和剩余风险。

最小测试场景

1. list 使用 nb portal list -j，且不询问 Portal 名称。
2. 使用 Git 存储的 config 必须提供 git_repo，且 git_path 默认为 .。
3. 对空 Git 仓库执行 push 时，报告支持创建分支或提供可执行的恢复方案。
4. 普通部署请求只执行 deploy，不会插入 push 步骤。
5. 普通源代码推送请求只执行 push，不会部署。
6. 组合执行 push + deploy 时，如果用户将两项操作分别独立提出，即使 push 失败，也会继续部署；只有当用户要求部署以 push 成功为前提时，才会在部署前停止。
7. pull --force 会阻止操作，直到获得明确确认。
8. destroy 会阻止操作，直到获得明确确认。
9. 启用的 Portal 数量为零时，普通 UI 编写操作会停止，不会隐式创建 Portal。
10. 只有一个无代码 Portal 时，使用 nocobase-ui-builder 技能。
11. 只有一个 AI Portal 时，解析其本地源代码目录；如果没有开发路径，则先运行 nb portal pull <portal>，然后将原始请求传给 nocobase-ai-builder。
12. 存在多个 Portal 时，列出 name、portalType，以及（如有）默认状态；必须明确选择，不得根据 cwd、默认标记或本地文件推断。
13. 指定的 Portal 名称不存在、已禁用或不唯一时，停止操作，不进行替换。
14. 应用启动／更新请求交由 nocobase-env-manage 处理。
15. 缺少 nb portal 时，阻止生命周期／源代码／部署操作，清楚报告 CLI 功能情况，且不使用私有 API 作为后备方案。
16. 当 list-navigation-targets 明确返回 capabilities.multiPortal: false，或该操作明确不存在且已验证的旧版 Flow Surfaces 特征探测成功时，缺少 Portal 运行时支持仍可使用旧版 UI Builder 流程。返回 true、认证错误、5xx、格式错误的输出或核心探测失败时，停止操作。

输出约定

对于直接的 Portal 命令任务，始终返回：

• request
• capability
• commands
• env
• portal
• default
• result
• readback
• assumptions
• next_steps

对于自然语言 UI 构建任务，返回：

• request
• env
• portal
• default
• capability
• portal_type
• implementation_path
• build_summary
• verification
• next_steps

参考资料

• 运行时约定
• Git 源代码存储
• 测试操作指南
• NocoBase Portal CLI 文档：官方命令参考。[verified: 2026-07-28]