Plugins
Plugin Actions
说明 plugin action 的 command、api、execute 结构，以及 allowWhenDisabled 的语义
Plugin Actions
plugin action 是 plugin 最直接的显式能力入口。
一个 action 主要由这些部分组成：
allowWhenDisabledcommandapiexecute
最核心的是 execute
最小例子：
actions: {
status: {
execute: async ({ context }) => {
return {
success: true,
data: {
rootPath: context.rootPath,
},
};
},
},
}execute 负责：
- 接收结构化 payload
- 执行业务逻辑
- 返回
success / data / error / message
command
command 用于 CLI 输入映射。
它适合定义：
- 描述文本
- commander 参数和选项
- 从 CLI 输入到 payload 的映射
api
api 用于 HTTP action 输入映射。
它适合定义：
- method
- path
- 从 HTTP 请求到 payload 的映射
allowWhenDisabled
这是 plugin action 和普通运行态 action 一个很容易忽略的差异点。
它表示：
- 即使 plugin 当前处于 disabled，某个 action 仍然允许执行
典型场景：
statusinstallconfiguremodels
也就是那些“你正是因为 plugin 还没可用，所以更需要先执行”的 action。
如果没有显式打开 allowWhenDisabled，disabled plugin 的普通 action 会被拦住。
action 的执行上下文是什么
plugin action 的 execute 接收到的是 PluginCommandContext 语义。
对使用者来说，可以理解为：
- 一组最小但稳定的命令执行上下文
它通常包括：
cwdrootPathloggerconfigenvglobalEnvpathspluginConfig
一个完整一些的例子
actions: {
use: {
allowWhenDisabled: true,
command: {
description: "切换默认 provider",
mapInput({ args }) {
return {
provider: String(args[0] || ""),
};
},
},
execute: async ({ payload }) => {
const provider = String((payload as { provider?: unknown }).provider || "").trim();
if (!provider) {
return {
success: false,
error: "provider is required",
message: "provider is required",
};
}
return {
success: true,
data: { provider },
};
},
},
}