npm package: @lark-apaas/action-plugin-cli
Description: CLI tool for creating, building and publishing action plugins
Latest version: 0.1.0

# @lark-apaas/action-plugin-cli

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

## 特性

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

## 安装

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

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

## 快速开始

### 1. 配置 Registry

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

```bash
# 交互式配置（推荐）
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. 创建插件

```bash
# 交互式创建
apaas-plugin init

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

### 3. 开发插件

```bash
cd @my-scope/my-plugin

# 安装依赖
pnpm install

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

# 验证插件
apaas-plugin validate
```

### 4. 发布插件

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

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

## 命令列表

### 配置管理

```bash
# 交互式初始化配置
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
```

### 插件开发

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

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

# 验证插件
apaas-plugin validate

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

### 版本管理

```bash
# 升级版本号
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
```

### 发布和管理

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

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

## 插件模板

### 依赖要求

> **重要**: 请使用 **zod v3.25.76** 或更高版本。
>
> ```bash
> pnpm add zod@^3.25.76
> ```

### 基础插件 - Unary 模式

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

```typescript
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 对话、大数据查询等流式响应场景。

```typescript
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 等配置的插件。

```typescript
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

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

```typescript
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 };
    },
  },
]);
```

## 完整工作流

```bash
# 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`：

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

## 常见问题

### Q: 如何获取 Cookie？

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

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

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

```bash
# 在 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？

开发模式下直接运行：

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

### Q: 支持哪些包管理器？

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

- pnpm（优先）
- yarn
- npm

## 相关包

- [@lark-apaas/action-plugin-core](https://www.npmjs.com/package/@lark-apaas/action-plugin-core) - 插件核心库
- [@lark-apaas/action-plugin-testing](https://www.npmjs.com/package/@lark-apaas/action-plugin-testing) - 测试工具
- [@lark-apaas/action-plugin-common](https://www.npmjs.com/package/@lark-apaas/action-plugin-common) - 公共工具库

## License

MIT