nocobase-plugin-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Provide a deterministic V1 workflow for plugin operations that works for both local and remote NocoBase applications, using runtime APIs and existing CLI commands instead of documentation-only sources.

为本地和远程NocoBase应用提供确定性的V1插件操作工作流，使用运行时API和现有CLI命令，而非仅依赖文档数据源。

Scope

适用范围

Inspect plugin catalog and plugin state (
```
enabled
```
,
```
installed
```
, version, package metadata) from runtime-backed sources.

For local inspect/readback, prefer CLI

yarn nocobase pm list

output and parse JSON between

--- BEGIN_PLUGIN_LIST_JSON ---

and

--- END_PLUGIN_LIST_JSON ---

Enable plugins using the existing
```
pm enable
```
capability.
Disable plugins using the existing
```
pm disable
```
capability.
Expose a stable invocation contract that other skills can call.
Return machine-parseable execution and verification results.

从运行时数据源检查插件目录与插件状态（
```
enabled
```
、
```
installed
```
、版本、包元数据）。
对于本地检查/回读操作，优先使用CLI
```
yarn nocobase pm list
```
的输出，并解析
```
--- BEGIN_PLUGIN_LIST_JSON ---
```
与
```
--- END_PLUGIN_LIST_JSON ---
```
之间的JSON内容。
使用现有
```
pm enable
```
功能启用插件。
使用现有
```
pm disable
```
功能禁用插件。
暴露稳定的调用契约，供其他技能调用。
返回可机器解析的执行与验证结果。

Non-Goals

非目标

Do not modify NocoBase source code.
Do not introduce new
```
nocobase pm
```
subcommands.
Do not perform destructive removal (
```
pm remove
```
) by default.
Do not scaffold or develop plugin code.
Do not persist secrets in any skill file.
Do not use
```
nocobase-ctl
```
as execution path for plugin
```
inspect/enable/disable
```
actions.

不修改NocoBase源代码。
不新增
```
nocobase pm
```
子命令。
默认不执行破坏性的移除操作（
```
pm remove
```
）。
不搭建或开发插件代码。
不在任何技能文件中存储密钥。
不使用
```
nocobase-ctl
```
作为插件
```
inspect/enable/disable
```
操作的执行路径。

Input Contract

输入契约

Input	Required	Default	Validation	Clarification Question
`action`	yes	none	one of `inspect/enable/disable`	"Which action should I run: inspect, enable, or disable?"
`target.mode`	no	`auto`	one of `auto/local/remote`	"Should I force local or remote target?"
`target.app_path`	no	auto-detected from workspace	existing directory with NocoBase app	"Which local NocoBase app path should I use?"
`target.base_url`	no	remote default `http://127.0.0.1:13000` when remote is selected	valid HTTP(S) URL	"What base URL should I query for plugin state?"
`target.compose_service`	no	`app`	non-empty docker compose service name	"Which compose service should be used for local Docker CLI?"
`auth.token_env`	no	`NOCOBASE_API_TOKEN`	env var exists and non-empty when required	"Which env var contains the access token?"
`plugins`	enable/disable: yes	none	non-empty array of plugin names/package names	"Which plugin(s) should be changed?"
`execution_backend`	no	`auto`	one of `auto/docker_cli/host_cli/remote_api`	"Should I force docker_cli, host_cli, or remote_api?"
`execution_mode`	no	`safe`	one of `safe/fast`	"Use safe mode (recommended) or fast mode?"
`verify.timeout_seconds`	no	`90`	integer in `10..600`	"What verification timeout should I use?"

Rules:

Support two invocation styles:

compact:

Use $nocobase-plugin-manage <action> [plugin...]

structured: JSON payload (for cross-skill orchestration)
Normalize
```
target.base_url
```
by removing trailing
```
/
```
.
Accept both short plugin names and full package names where NocoBase parser supports them.
In
```
safe
```
mode, require pre-check and post-check status readback.
Resolve
```
target.mode=auto
```
with this priority:
if explicit
```
target.app_path
```
exists, choose
```
local
```
(even when
```
target.base_url
```
is also present)
if explicit
```
target.base_url
```
exists and
```
target.app_path
```
is absent, choose
```
remote
```
if current workspace contains a NocoBase app (for example
```
.env
```
and app package metadata), choose
```
local
```
if
```
NOCOBASE_BASE_URL
```
or
```
APP_BASE_URL
```
env is set, choose
```
remote
```
fallback to
```
local
```
with current working directory
Resolve
```
execution_backend=auto
```
with this priority:
if channel is
```
remote
```
, use
```
remote_api
```
if channel is
```
local
```
and action is
```
enable/disable
```
, run fast docker eligibility check first:

compare

target.base_url

port with

docker compose port <service> 80

mapping in

target.app_path

if port mismatches (for example target
```
19000
```
while compose maps
```
13000
```
), skip docker write path directly
if channel is
```
local
```
and action is
```
inspect
```
, prefer local CLI (
```
docker_cli
```
, then
```
host_cli
```
); API inspect is fallback only when local marker extraction fails
if channel is
```
local
```
and action is
```
enable/disable
```
, use fallback chain:
```
docker_cli
```
first
then
```
remote_api
```
when docker path is unavailable/failed and
```
target.base_url
```
+ token are ready
then manual fallback guidance when both paths are unavailable/failed
If user says "you decide", use defaults in this table.

Invocation payload template:

json

{
  "action": "inspect",
  "target": {
    "mode": "auto",
    "app_path": null,
    "base_url": null,
    "compose_service": "app"
  },
  "auth": {
    "token_env": "NOCOBASE_API_TOKEN"
  },
  "execution_backend": "auto",
  "plugins": [],
  "execution_mode": "safe",
  "verify": {
    "timeout_seconds": 90
  }
}

输入	是否必填	默认值	验证规则	澄清问题
`action`	是	无	必须为 `inspect/enable/disable` 之一	"我应该执行哪个操作：inspect、enable还是disable？"
`target.mode`	否	`auto`	必须为 `auto/local/remote` 之一	"是否强制使用本地或远程目标？"
`target.app_path`	否	从工作区自动检测	存在NocoBase应用的现有目录	"应使用哪个本地NocoBase应用路径？"
`target.base_url`	否	选择远程时默认值为 `http://127.0.0.1:13000`	有效的HTTP(S) URL	"查询插件状态应使用哪个基础URL？"
`target.compose_service`	否	`app`	非空的Docker Compose服务名称	"本地Docker CLI应使用哪个Compose服务？"
`auth.token_env`	否	`NOCOBASE_API_TOKEN`	需要时环境变量存在且非空	"哪个环境变量包含访问令牌？"
`plugins`	enable/disable操作：是	无	非空的插件名称/包名称数组	"应修改哪些插件？"
`execution_backend`	否	`auto`	必须为 `auto/docker_cli/host_cli/remote_api` 之一	"是否强制使用docker_cli、host_cli或remote_api？"
`execution_mode`	否	`safe`	必须为 `safe/fast` 之一	"使用安全模式（推荐）还是快速模式？"
`verify.timeout_seconds`	否	`90`	10到600之间的整数	"应使用多少秒的验证超时时间？"

规则：

支持两种调用方式：

简洁式：

Use $nocobase-plugin-manage <action> [plugin...]

结构化：JSON负载（用于跨技能编排）
标准化
```
target.base_url
```
，移除末尾的
```
/
```
。
接受NocoBase解析器支持的短插件名称和完整包名称。
在
```
safe
```
模式下，要求进行操作前检查和操作后状态回读。
按照以下优先级解析
```
target.mode=auto
```
：
如果指定的
```
target.app_path
```
存在，选择
```
local
```
（即使同时存在
```
target.base_url
```
）
如果指定的
```
target.base_url
```
存在且
```
target.app_path
```
不存在，选择
```
remote
```
如果当前工作区包含NocoBase应用（例如存在
```
.env
```
和应用包元数据），选择
```
local
```
如果设置了
```
NOCOBASE_BASE_URL
```
或
```
APP_BASE_URL
```
环境变量，选择
```
remote
```
回退到
```
local
```
，使用当前工作目录
按照以下优先级解析
```
execution_backend=auto
```
：
如果通道为
```
remote
```
，使用
```
remote_api
```
如果通道为
```
local
```
且操作为
```
enable/disable
```
，先执行快速Docker适配性检查：

比较

target.base_url

的端口与

target.app_path

中

docker compose port <service> 80

的映射

如果端口不匹配（例如目标端口为
```
19000
```
而Compose映射为
```
13000
```
），直接跳过Docker写入路径
如果通道为
```
local
```
且操作为
```
inspect
```
，优先使用本地CLI（
```
docker_cli
```
，然后是
```
host_cli
```
）；仅当本地标记提取失败时，才回退到API检查
如果通道为
```
local
```
且操作为
```
enable/disable
```
，使用回退链：
优先使用
```
docker_cli
```
当Docker路径不可用/失败且
```
target.base_url
```
+ 令牌已就绪时，回退到
```
remote_api
```
当两种路径都不可用/失败时，提供手动回退指导
如果用户说“你决定”，使用本表中的默认值。

调用负载模板：

json

{
  "action": "inspect",
  "target": {
    "mode": "auto",
    "app_path": null,
    "base_url": null,
    "compose_service": "app"
  },
  "auth": {
    "token_env": "NOCOBASE_API_TOKEN"
  },
  "execution_backend": "auto",
  "plugins": [],
  "execution_mode": "safe",
  "verify": {
    "timeout_seconds": 90
  }
}

Mandatory Clarification Gate

强制澄清环节

Max clarification rounds:
```
2
```
Max questions per round:
```
3
```
Pre-mutation requirements:
```
action
```
is resolved.
target channel is resolved (auto-resolution or explicit).
For local mode:
```
target.app_path
```
exists.
For remote mode:
```
target.base_url
```
is reachable.
For enable/disable:
```
plugins
```
is non-empty.
For remote writes in safe mode: auth token is available.
For local
```
docker_cli
```
: docker compose command is available and target service exists.
For local write fallback to
```
remote_api
```
:
```
target.base_url
```
and token are available.
If both local and remote candidates exist and confidence is low, ask one concise disambiguation question.
If these are not met, stop mutation and report missing prerequisites.

最大澄清轮次：
```
2
```
每轮最多问题数：
```
3
```
变更前要求：
```
action
```
已确定。
目标通道已确定（自动解析或显式指定）。
本地模式：
```
target.app_path
```
存在。
远程模式：
```
target.base_url
```
可访问。
enable/disable操作：
```
plugins
```
非空。
安全模式下的远程写入：身份验证令牌可用。
本地
```
docker_cli
```
：Docker Compose命令可用且目标服务存在。
本地写入回退到
```
remote_api
```
：
```
target.base_url
```
和令牌可用。
如果同时存在本地和远程候选对象且置信度低，提出一个简洁的消歧问题。
如果未满足上述要求，停止变更并报告缺失的先决条件。

Workflow

工作流

Parse input, support compact action form, and resolve execution channel/backend.

If input is compact (

Use $nocobase-plugin-manage enable @nocobase/plugin-api-doc

), normalize into structured payload.

Apply
```
target.mode=auto
```
resolution rules.
Apply
```
execution_backend=auto
```
resolution rules.
```
remote_api
```
: inspect and mutate through runtime API actions.

docker_cli

: inspect and mutate through

docker compose exec -T <service> yarn nocobase pm ...

(including

pm list

```
host_cli
```
: inspect/readback fallback through host
```
yarn nocobase pm list
```
when docker inspect path is unavailable.
In local channel,
```
pm list
```
is the preferred inspect/readback source; API readback is fallback when CLI JSON extraction is unavailable.
In local channel for write actions, mutation path is deterministic fallback:
```
docker_cli -> remote_api -> manual
```
.
Fast discriminator should avoid slow docker retry when target URL is clearly not served by current compose mapping.

Resolve runtime evidence source (never docs as source of truth).

For local catalog/status, use
```
yarn nocobase pm list
```
(or docker compose equivalent) and parse JSON marker block.
For remote catalog/status, use
```
pm:list
```
and
```
pm:get
```
.
For remote enabled plugin lanes, use
```
pm:listEnabled
```
and
```
pm:listEnabledV2
```
.
If local CLI output marker block is unavailable, fallback to API (
```
pm:list
```
/
```
pm:get
```
) and record fallback reason in output.
Record pre-state snapshot before mutation when in
```
safe
```
mode.

Execute action.

```
inspect
```
:

local

docker_cli

: run

docker compose exec -T <service> yarn nocobase pm list

target.app_path

, parse JSON marker block.

local

host_cli

: run

yarn nocobase pm list

target.app_path

, parse JSON marker block.

remote: query
```
pm:list
```
and optionally
```
pm:listEnabled
```
lanes.
```
enable
```
:

local

docker_cli

: run

docker compose exec -T <service> yarn nocobase pm enable <plugin>

target.app_path

if local docker write is unavailable/failed, fallback to remote
```
pm:enable
```
when remote prerequisites are ready.
remote: call
```
pm:enable
```
with
```
filterByTk
```
(single plugin or plugin array).
```
disable
```
:

local

docker_cli

: run

docker compose exec -T <service> yarn nocobase pm disable <plugin>

target.app_path

if local docker write is unavailable/failed, fallback to remote
```
pm:disable
```
when remote prerequisites are ready.
remote: call
```
pm:disable
```
with
```
filterByTk
```
.

Verify by readback polling.

Poll every 2 seconds until timeout.
For
```
enable
```
, verify
```
enabled=true
```
in local
```
pm list
```
snapshot (or remote
```
pm:get
```
).
For
```
disable
```
, verify
```
enabled=false
```
in local
```
pm list
```
snapshot (or remote
```
pm:get
```
).
If timeout hits, return
```
pending_verification
```
with last observed state.

Return a structured result.

Include

channel

commands_or_actions

pre_state

post_state

verification

, and

next_steps

Include
```
execution_backend
```
and
```
target_resolution
```
evidence (why local/remote and backend were chosen).
If no backend is available, include
```
fallback_hints
```
with UI and command guidance.

Execution channel matrix:

Mode	Inspect	Enable	Disable
`local`	local CLI ( `pm list` , parse marker JSON; fallback API if marker parse fails)	`docker_cli -> remote_api -> manual`	`docker_cli -> remote_api -> manual`
`remote`	remote API ( `pm:list` / `pm:get` )	remote API ( `pm:enable` )	remote API ( `pm:disable` )

Execution backend matrix (local):

Backend Inspect Enable Disable When to prefer

Backend	Inspect	Enable	Disable	When to prefer
`docker_cli`	`docker compose exec -T <service> yarn nocobase pm list`	`docker compose exec -T <service> yarn nocobase pm enable ...`	`docker compose exec -T <service> yarn nocobase pm disable ...`	local Docker app detected
`host_cli`	`yarn nocobase pm list`	inspect/readback only	inspect/readback only	local non-docker inspect fallback

docker_cli

docker compose exec -T <service> yarn nocobase pm list

docker compose exec -T <service> yarn nocobase pm enable ...

docker compose exec -T <service> yarn nocobase pm disable ...

local Docker app detected

host_cli

yarn nocobase pm list

inspect/readback only

local non-docker inspect fallback

Operational notes:

```
pm list
```
CLI output is wrapped by marker lines (
```
--- BEGIN_PLUGIN_LIST_JSON ---
```
/
```
--- END_PLUGIN_LIST_JSON ---
```
); only the JSON block between markers is considered canonical plugin payload.
```
pm:enable
```
and
```
pm:disable
```
in resource actions are asynchronous (
```
runAsCLI
```
), so readback polling is mandatory.
Remote actions should prefer API-client style URLs (
```
pm:list
```
,
```
pm:get
```
,
```
pm:enable
```
,
```
pm:disable
```
) when available.
For local Docker environments, prefer
```
docker_cli
```
as primary write backend.
For local write actions, when docker path fails, attempt one remote API fallback (
```
pm:enable/pm:disable
```
) before manual fallback guidance.
Local inspect/readback still prefers CLI marker parsing; API inspect/readback remains fallback when marker parsing fails.
If deterministic local command path is required, set
```
target.mode=local
```
and
```
execution_backend=docker_cli
```
.

解析输入，支持简洁式操作格式，并解析执行通道/后端。

如果输入为简洁式（
```
Use $nocobase-plugin-manage enable @nocobase/plugin-api-doc
```
），将其标准化为结构化负载。
应用
```
target.mode=auto
```
解析规则。
应用
```
execution_backend=auto
```
解析规则。
```
remote_api
```
：通过运行时API操作进行检查和变更。

docker_cli

：通过

docker compose exec -T <service> yarn nocobase pm ...

（包括

pm list

）进行检查和变更。

```
host_cli
```
：当Docker检查路径不可用时，通过主机
```
yarn nocobase pm list
```
进行检查/回读回退。
在本地通道中，
```
pm list
```
是首选的检查/回读数据源；当CLI JSON提取不可用时，才回退到API回读。
在本地通道的写入操作中，变更路径为确定性回退：
```
docker_cli -> remote_api -> manual
```
。
快速判别器应在目标URL明显不由当前Compose映射提供服务时，避免缓慢的Docker重试。

解析运行时证据源（绝不以文档为事实来源）。

对于本地目录/状态，使用
```
yarn nocobase pm list
```
（或Docker Compose等效命令）并解析标记块中的JSON。
对于远程目录/状态，使用
```
pm:list
```
和
```
pm:get
```
。
对于远程已启用插件通道，使用
```
pm:listEnabled
```
和
```
pm:listEnabledV2
```
。
如果本地CLI输出标记块不可用，回退到API（
```
pm:list
```
/
```
pm:get
```
）并在输出中记录回退原因。
在
```
safe
```
模式下，变更前记录状态快照。

执行操作。

```
inspect
```
:

本地

docker_cli

: 在

target.app_path

中运行

docker compose exec -T <service> yarn nocobase pm list

，解析标记块中的JSON。

本地
```
host_cli
```
: 在
```
target.app_path
```
中运行
```
yarn nocobase pm list
```
，解析标记块中的JSON。
远程: 查询
```
pm:list
```
并可选查询
```
pm:listEnabled
```
通道。
```
enable
```
:

本地

docker_cli

: 在

target.app_path

中运行

docker compose exec -T <service> yarn nocobase pm enable <plugin>

。

如果本地Docker写入不可用/失败，当远程先决条件就绪时，回退到远程
```
pm:enable
```
。
远程: 使用
```
filterByTk
```
调用
```
pm:enable
```
（单个插件或插件数组）。
```
disable
```
:

本地

docker_cli

: 在

target.app_path

中运行

docker compose exec -T <service> yarn nocobase pm disable <plugin>

。

如果本地Docker写入不可用/失败，当远程先决条件就绪时，回退到远程
```
pm:disable
```
。
远程: 使用
```
filterByTk
```
调用
```
pm:disable
```
。

通过回读轮询进行验证。

每2秒轮询一次，直到超时。
对于
```
enable
```
操作，验证本地
```
pm list
```
快照（或远程
```
pm:get
```
）中
```
enabled=true
```
。
对于
```
disable
```
操作，验证本地
```
pm list
```
快照（或远程
```
pm:get
```
）中
```
enabled=false
```
。
如果超时，返回
```
pending_verification
```
并附上最后观测到的状态。

返回结构化结果。

包含

channel

、

commands_or_actions

、

pre_state

、

post_state

、

verification

和

next_steps

。

包含
```
execution_backend
```
和
```
target_resolution
```
证据（说明选择本地/远程和后端的原因）。
如果没有可用后端，包含带有UI和命令指导的
```
fallback_hints
```
。

执行通道矩阵：

模式	检查	启用	禁用
`local`	本地CLI（ `pm list` ，解析标记JSON；标记解析失败时回退到API）	`docker_cli -> remote_api -> manual`	`docker_cli -> remote_api -> manual`
`remote`	远程API（ `pm:list` / `pm:get` ）	远程API（ `pm:enable` ）	远程API（ `pm:disable` ）

执行后端矩阵（本地）：

后端检查启用禁用优先使用场景

后端	检查	启用	禁用	优先使用场景
`docker_cli`	`docker compose exec -T <service> yarn nocobase pm list`	`docker compose exec -T <service> yarn nocobase pm enable ...`	`docker compose exec -T <service> yarn nocobase pm disable ...`	检测到本地Docker应用
`host_cli`	`yarn nocobase pm list`	仅用于检查/回读	仅用于检查/回读	本地非Docker检查回退

docker_cli

docker compose exec -T <service> yarn nocobase pm list

docker compose exec -T <service> yarn nocobase pm enable ...

docker compose exec -T <service> yarn nocobase pm disable ...

检测到本地Docker应用

host_cli

yarn nocobase pm list

仅用于检查/回读

本地非Docker检查回退

操作说明：

```
pm list
```
CLI输出被标记行（
```
--- BEGIN_PLUGIN_LIST_JSON ---
```
/
```
--- END_PLUGIN_LIST_JSON ---
```
）包裹；仅标记之间的JSON块被视为规范插件负载。
资源操作中的
```
pm:enable
```
和
```
pm:disable
```
是异步的（
```
runAsCLI
```
），因此回读轮询是必需的。
远程操作应优先使用API客户端风格的URL（
```
pm:list
```
、
```
pm:get
```
、
```
pm:enable
```
、
```
pm:disable
```
）（如果可用）。
对于本地Docker环境，优先使用
```
docker_cli
```
作为主要写入后端。
对于本地写入操作，当Docker路径失败时，在提供手动回退指导前，尝试一次远程API回退（
```
pm:enable/pm:disable
```
）。
本地检查/回读仍优先使用CLI标记解析；当标记解析失败时，API检查/回读仍作为回退方案。
如果需要确定性本地命令路径，设置
```
target.mode=local
```
和
```
execution_backend=docker_cli
```
。

Reference Loading Map

参考加载映射

Reference	Use When	Notes
references/v1-runtime-contract.md	any action	endpoint and command templates for local/remote flows
references/test-playbook.md	running acceptance tests	prompt-driven test cases with expected outcomes
pm.ts	implementing local CLI inspect/enable/disable	confirms `pm list/enable/disable` command signatures used by this skill
resource.ts	implementing inspect or remote mutation	confirms `pm:list/get/listEnabled/enable/disable` actions used by this skill
preset index.ts	proving plugin info source is runtime-backed	shows `getAllPlugins` and DB merge behavior
client PluginManager.tsx	confirming front-end action routes	uses `pm:list` and `pm:enable`
app PluginManager.ts	confirming enabled-plugin lane route	uses `pm:listEnabled`

参考	使用场景	说明
references/v1-runtime-contract.md	任何操作	本地/远程流程的端点和命令模板
references/test-playbook.md	运行验收测试	带有预期结果的提示驱动测试用例
pm.ts	实现本地CLI检查/启用/禁用	确认本技能使用的 `pm list/enable/disable` 命令签名
resource.ts	实现检查或远程变更	确认本技能使用的 `pm:list/get/listEnabled/enable/disable` 操作
preset index.ts	证明插件信息源来自运行时	展示 `getAllPlugins` 和数据库合并行为
client PluginManager.tsx	确认前端操作路由	使用 `pm:list` 和 `pm:enable`
app PluginManager.ts	确认已启用插件通道路由	使用 `pm:listEnabled`

Safety Gate

安全环节

High-impact actions:
disabling authentication, ACL, or system-critical plugins
remote mutations in production-like environments
multi-plugin batch operations
Secondary confirmation template:

"Confirm execution:

{{action}}

for

{{plugins}}

{{target.base_url or target.app_path}}

. Type

confirm

to continue."

In
```
safe
```
mode:
block mutation if pre-state cannot be read
block mutation if plugin identity is ambiguous
block mutation if remote token is missing for protected endpoints
block mutation when all execution backends are unavailable
Rollback guidance:
failed disable: run
```
pm enable <plugin>
```
(local CLI or remote
```
pm:enable
```
)
failed enable: run
```
pm disable <plugin>
```
if rollback is required and explicitly requested
Backend unavailable rich guidance template:
```
Local Docker path
```
: verify
```
docker compose ps
```
, verify service name (default
```
app
```
), then retry.
```
Remote API fallback
```
: if local docker write failed, retry via
```
pm:enable/pm:disable
```
using
```
target.base_url
```
and token env.

UI fallback

: open

{{base_url}}/admin/settings/plugin-manager

, enable target plugin manually.

CLI runtime dependency special case

: enable

@nocobase/plugin-api-doc

and

@nocobase/plugin-api-keys

, restart app, then hand off runtime refresh to

nocobase-env-bootstrap

nocobase-acl-manage

```
Auth fallback
```
: if endpoint returns
```
401/403
```
, open
```
{{base_url}}/admin/settings/api-keys
```
, create/regenerate token, set env var, retry.
If
```
base_url
```
is unknown, use default
```
http://127.0.0.1:13000
```
when generating fallback URLs.

高影响操作：
禁用身份验证、ACL或系统关键插件
类生产环境中的远程变更
多插件批量操作
二次确认模板：

"确认执行：在

{{target.base_url or target.app_path}}

上对

{{plugins}}

执行

{{action}}

。输入

confirm

以继续。"

在
```
safe
```
模式下：
如果无法读取操作前状态，阻止变更
如果插件身份不明确，阻止变更
如果受保护端点缺少远程令牌，阻止变更
如果所有执行后端都不可用，阻止变更
回退指导：
禁用失败：运行
```
pm enable <plugin>
```
（本地CLI或远程
```
pm:enable
```
）
启用失败：如果需要回退且明确请求，运行
```
pm disable <plugin>
```
后端不可用的详细指导模板：
```
本地Docker路径
```
: 验证
```
docker compose ps
```
，验证服务名称（默认
```
app
```
），然后重试。
```
远程API回退
```
: 如果本地Docker写入失败，使用
```
target.base_url
```
和令牌环境变量通过
```
pm:enable/pm:disable
```
重试。

UI回退

: 打开

{{base_url}}/admin/settings/plugin-manager

，手动启用目标插件。

CLI运行时依赖特殊情况

: 启用

@nocobase/plugin-api-doc

和

@nocobase/plugin-api-keys

，重启应用，然后将运行时刷新交给

nocobase-env-bootstrap

nocobase-acl-manage

。

```
身份验证回退
```
: 如果端点返回
```
401/403
```
，打开
```
{{base_url}}/admin/settings/api-keys
```
，创建/重新生成令牌，设置环境变量，重试。
如果
```
base_url
```
未知，生成回退URL时使用默认值
```
http://127.0.0.1:13000
```
。

Verification Checklist

验证清单

Input contract fields are resolved and validated.
Execution channel (
```
local
```
or
```
remote
```
) is explicit in output.
```
execution_backend
```
is explicit in output.
Auto-resolution decisions are recorded in output assumptions and target resolution evidence.
When both
```
target.app_path
```
and
```
target.base_url
```
are present under
```
target.mode=auto
```
, resolution must remain
```
local
```
.
Pre-state is captured in
```
safe
```
mode.
Mutation call(s) succeeded without shell/API errors.
Post-state was fetched by readback polling.
Expected condition is met (
```
enabled=true
```
for enable,
```
enabled=false
```
for disable).
Local inspect/readback parsing extracts JSON from marker block (
```
BEGIN_PLUGIN_LIST_JSON
```
...
```
END_PLUGIN_LIST_JSON
```
) or explicitly records API fallback reason.
Timeouts are reported as
```
pending_verification
```
, not hidden as success.
CLI/API commands used are included in output for reproducibility.
Token values are redacted; only env var names are shown.
For local write failures, output explicitly records fallback attempts in order:
```
docker_cli
```
then
```
remote_api
```
.
Backend unavailable cases return
```
verification=failed
```
and include rich
```
fallback_hints
```
.
Any unresolved risk is listed in
```
next_steps
```
.

输入契约字段已解析并验证。
执行通道（
```
local
```
或
```
remote
```
）在输出中明确说明。
```
execution_backend
```
在输出中明确说明。
自动解析决策记录在输出的假设和目标解析证据中。

当

target.mode=auto

下同时存在

target.app_path

和

target.base_url

时，解析结果必须为

local

。

在
```
safe
```
模式下已捕获操作前状态。
变更调用成功，无Shell/API错误。
通过回读轮询获取操作后状态。
满足预期条件（启用操作对应
```
enabled=true
```
，禁用操作对应
```
enabled=false
```
）。
本地检查/回读解析从标记块（
```
BEGIN_PLUGIN_LIST_JSON
```
...
```
END_PLUGIN_LIST_JSON
```
）提取JSON，或明确记录API回退原因。
超时报告为
```
pending_verification
```
，而非隐藏为成功。
输出中包含使用的CLI/API命令，以便重现。
令牌值已脱敏；仅显示环境变量名称。
对于本地写入失败，输出按顺序明确记录回退尝试：
```
docker_cli
```
然后是
```
remote_api
```
。
后端不可用的情况返回
```
verification=failed
```
并包含详细的
```
fallback_hints
```
。
任何未解决的风险都列在
```
next_steps
```
中。

Minimal Test Scenarios

最小测试场景

Local inspect:
```
yarn nocobase pm list
```
(or docker compose equivalent) succeeds and marker JSON is parsed into plugin states.
Remote inspect: authenticated call returns plugin states and enabled lanes.
Compact invocation happy path:
```
Use $nocobase-plugin-manage enable <plugin>
```
auto-resolves target and succeeds.
Local Docker enable happy path: backend resolves to
```
docker_cli
```
and command uses
```
docker compose exec -T app ...
```
.
Enable happy path:
```
pm enable
```
completes and plugin becomes
```
enabled=true
```
.
Disable guarded case: attempt to disable critical plugin requires confirmation.
Remote mutation failure: missing token blocks mutation with actionable error.
Local write fallback path: docker failure triggers remote API fallback; if both fail, return rich manual guidance.
Auto target with both
```
app_path
```
and
```
base_url
```
resolves to local; write fallback may still use
```
remote_api
```
after docker failure.

本地检查：
```
yarn nocobase pm list
```
（或Docker Compose等效命令）成功，标记JSON被解析为插件状态。
远程检查：已认证调用返回插件状态和已启用通道。
简洁式调用成功路径：
```
Use $nocobase-plugin-manage enable <plugin>
```
自动解析目标并成功执行。
本地Docker启用成功路径：后端解析为
```
docker_cli
```
，命令使用
```
docker compose exec -T app ...
```
。
启用成功路径：
```
pm enable
```
完成，插件变为
```
enabled=true
```
。
禁用防护场景：尝试禁用关键插件需要确认。
远程变更失败：缺少令牌阻止变更并返回可操作错误。
本地写入回退路径：Docker失败触发远程API回退；如果两者都失败，返回详细的手动指导。
同时存在
```
app_path
```
和
```
base_url
```
的自动目标解析为本地；Docker失败后写入回退仍可使用
```
remote_api
```
。

Output Contract

输出契约

Always return:

```
request
```
: normalized action and target
```
channel
```
: chosen execution channel

execution_backend

: chosen backend (

docker_cli | host_cli | remote_api

)

```
commands_or_actions
```
: exact commands or action routes invoked
```
pre_state
```
: plugin snapshot before mutation (if available)
```
post_state
```
: plugin snapshot after mutation (or last observed snapshot on timeout)

verification

passed | failed | pending_verification

```
assumptions
```
: defaults applied
```
target_resolution
```
: explicit reason and signals used to choose local/remote
```
fallback_hints
```
: rich fallback guidance when backend resolution/execution fails
```
next_steps
```
: concrete follow-up actions

始终返回：

```
request
```
: 标准化的操作和目标
```
channel
```
: 选择的执行通道

execution_backend

: 选择的后端（

docker_cli | host_cli | remote_api

）

```
commands_or_actions
```
: 调用的确切命令或操作路由
```
pre_state
```
: 变更前的插件快照（如果可用）
```
post_state
```
: 变更后的插件快照（或超时后最后观测到的快照）

verification

passed | failed | pending_verification

```
assumptions
```
: 应用的默认值
```
target_resolution
```
: 选择本地/远程的明确原因和信号
```
fallback_hints
```
: 后端解析/执行失败时的详细回退指导
```
next_steps
```
: 具体的后续操作

References

参考资料

V1 Runtime Contract: runtime endpoint and CLI mapping for this skill.
Test Playbook: copy-ready prompts and expected assertions for local/remote flows.
NocoBase PM CLI Commands: confirms supported
```
pm
```
operations.
NocoBase PM Resource Actions: confirms inspect and remote mutation actions.
Preset Plugin Aggregation: confirms plugin inventory + DB status merge.
Client Plugin Manager Actions: confirms action route usage from client.

V1 Runtime Contract: 本技能的运行时端点和CLI映射。
Test Playbook: 本地/远程流程的可直接使用的提示和预期断言。
NocoBase PM CLI Commands: 确认支持的
```
pm
```
操作。
NocoBase PM Resource Actions: 确认检查和远程变更操作。
Preset Plugin Aggregation: 确认插件清单 + 数据库状态合并。
Client Plugin Manager Actions: 确认客户端使用的操作路由。