@lark-apaas/action-plugin-cli

官方 CLI 工具，用于创建、构建和发布 Action 插件

特性

• 快速初始化 - 使用模板快速创建插件项目
• 智能构建 - 自动检测包管理器，统一构建入口
• 完整验证 - 验证插件结构和构建产物
• 版本管理 - 自动升级版本号，遵循语义化版本规范
• 一键发布 - 发布插件到 Registry
• 插件管理 - 取消发布已发布的插件

安装

npm install -g @lark-apaas/action-plugin-cli

安装后可使用 apaas-plugin 或简写 ap 命令。

快速开始

1. 配置 Registry

首次使用需要配置 Registry 地址和认证信息：

# 交互式配置（推荐）
apaas-plugin config init

# 或手动设置
apaas-plugin config set registry https://your-backend.com/api/plugins
apaas-plugin config set cookie "session=xxx; token=yyy"
apaas-plugin config set canary_env "ppe_xxx"  # 可选，灰度环境

2. 创建插件

# 交互式创建
apaas-plugin init

# 或使用命令行参数
apaas-plugin init @my-scope/my-plugin --template single-static

3. 开发插件

cd @my-scope/my-plugin

# 安装依赖
pnpm install

# 开发模式（实时构建）
apaas-plugin build --watch

# 验证插件
apaas-plugin validate

4. 发布插件

# 升级版本
apaas-plugin bump patch  # 1.0.0 → 1.0.1

# 构建并发布
pnpm build
apaas-plugin publish

命令列表

配置管理

# 交互式初始化配置
apaas-plugin config init

# 查看所有配置
apaas-plugin config list

# 设置配置项
apaas-plugin config set <key> <value>

# 获取配置项
apaas-plugin config get <key>

# 删除配置项
apaas-plugin config delete <key>

# 重置所有配置
apaas-plugin config reset

插件开发

# 初始化插件
apaas-plugin init [name] [options]

# 构建插件
apaas-plugin build [--watch]

# 验证插件
apaas-plugin validate

# 打包插件
apaas-plugin pack [--output <dir>]

版本管理

# 升级版本号
apaas-plugin bump [major|minor|patch]

# 示例
apaas-plugin bump patch   # 1.0.0 → 1.0.1
apaas-plugin bump minor   # 1.0.0 → 1.1.0
apaas-plugin bump major   # 1.0.0 → 2.0.0

发布和管理

# 发布插件
apaas-plugin publish [--dry-run]

# 取消发布
apaas-plugin unpublish <plugin-name>@<version>

插件模板

依赖要求

重要: 请使用 zod v3.25.76 或更高版本。

pnpm add zod@^3.25.76

基础插件 - Unary 模式

适用于单次请求响应的简单插件。

import { definePlugin, type ActionContext } from '@lark-apaas/action-plugin-core';
import { z } from 'zod';

const InputSchema = z.object({
  message: z.string().describe('消息内容'),
});

const OutputSchema = z.object({
  success: z.boolean(),
  data: z.string(),
});

export default definePlugin([
  {
    name: 'myAction',
    input: InputSchema,
    output: OutputSchema,
    handler: async (context: ActionContext, input) => {
      context.logger?.log('Plugin action started', { input });

      return {
        success: true,
        data: `Processed: ${input.message}`,
      };
    },
  },
]);

流式插件 - Stream 模式

适用于 LLM 对话、大数据查询等流式响应场景。

import {
  definePlugin,
  StreamTextOutput,
  Aggregators,
  type ActionContext,
} from '@lark-apaas/action-plugin-core';
import { z } from 'zod';

export default definePlugin([
  {
    name: 'chat',
    outputMode: 'stream',
    input: z.object({
      message: z.string().describe('用户消息'),
    }),
    output: StreamTextOutput,
    aggregate: Aggregators.text, // 聚合器：拼接所有文本
    async *handler(context: ActionContext, input) {
      context.logger?.log('Chat started', { message: input.message });

      // 模拟 LLM 流式响应
      const tokens = ['Hello', ', ', 'World', '!'];
      for (const token of tokens) {
        yield { data: { content: token } };
      }
    },
  },
]);

带配置插件

适用于需要 API Key、Endpoint 等配置的插件。

import { definePlugin, type ActionContext } from '@lark-apaas/action-plugin-core';
import { z } from 'zod';

const ConfigSchema = z.object({
  apiKey: z.string().describe('API密钥'),
  apiEndpoint: z.string().url().describe('API端点'),
});

type Config = z.infer<typeof ConfigSchema>;

export default definePlugin(
  [
    {
      name: 'fetchData',
      input: z.object({
        id: z.string().describe('记录ID'),
      }),
      handler: async (context: ActionContext, input, config: Config) => {
        const response = await fetch(`${config.apiEndpoint}/data/${input.id}`, {
          headers: { Authorization: `Bearer ${config.apiKey}` },
        });
        return { data: await response.json() };
      },
    },
  ],
  {
    config: ConfigSchema,
    configUISchema: {
      apiKey: {
        'ui:widget': 'password',
        'ui:description': '请输入 API 密钥',
      },
    },
  },
);

动态输出 Schema

输出结构依赖输入参数的复杂场景。

import { definePlugin, type ActionContext } from '@lark-apaas/action-plugin-core';
import { z } from 'zod';

const InputSchema = z.object({
  operation: z.enum(['create', 'delete']).describe('操作类型'),
});

export default definePlugin([
  {
    name: 'operate',
    input: InputSchema,
    output: (_config, input) => {
      if (input.operation === 'create') {
        return z.object({ id: z.string(), created: z.boolean() });
      }
      return z.object({ deleted: z.boolean() });
    },
    handler: async (context: ActionContext, input) => {
      if (input.operation === 'create') {
        return { id: 'record_123', created: true };
      }
      return { deleted: true };
    },
  },
]);

完整工作流

# 1. 配置（首次使用）
apaas-plugin config set registry https://your-registry.com/api/plugins
apaas-plugin config set cookie "session=xxx"

# 2. 创建插件
apaas-plugin init @my-scope/awesome-plugin
cd @my-scope/awesome-plugin
pnpm install

# 3. 开发
# 编辑 src/index.ts
apaas-plugin build --watch  # 开发模式

# 4. 验证
apaas-plugin validate

# 5. 版本管理
apaas-plugin bump patch
git add . && git commit -m "feat: initial version"
git tag v1.0.0

# 6. 发布
apaas-plugin publish

配置文件

全局配置存储在 ~/.apaas-plugin/config.json：

{
  "registry": "https://your-backend.com/api/plugins",
  "cookie": "session=xxx; token=yyy",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  }
}

常见问题

Q: 如何获取 Cookie？

从浏览器开发者工具中复制完整的 Cookie 字符串：

1. 打开浏览器开发者工具（F12）
2. 进入 Network 标签
3. 访问需要认证的页面
4. 找到请求，查看 Request Headers
5. 复制完整的 Cookie 值

Q: 如何在 CI/CD 中使用？

# 在 CI/CD 脚本中设置配置
apaas-plugin config set registry $REGISTRY_URL
apaas-plugin config set cookie $COOKIE

# 或使用命令行参数
apaas-plugin publish --registry $REGISTRY_URL --cookie $COOKIE

Q: 如何调试 CLI？

开发模式下直接运行：

node packages/plugin-cli/lib/cli.js <command> [options]

Q: 支持哪些包管理器？

CLI 自动检测以下包管理器：

• pnpm（优先）
• yarn
• npm

相关包

• @lark-apaas/action-plugin-core - 插件核心库
• @lark-apaas/action-plugin-testing - 测试工具
• @lark-apaas/action-plugin-common - 公共工具库

License

MIT