@lark-apaas/fullstack-cli

@lark-apaas/fullstack-cli

Fullstack 开发工具集 - 文件派生、数据库 Schema 生成、OpenAPI 生成、能力管理、构建工具

功能

• 自动派生 - 自动管理项目脚本和配置文件
• 数据库 Schema 生成 - 从现有数据库生成 Drizzle ORM schema
• OpenAPI 生成 - 自动生成 API 文档和客户端 SDK
• Action 插件管理 - 安装、更新、删除 action 插件
• 能力配置管理 - 查看、充血、迁移能力配置
• 构建工具 - 获取 STI 制品上传凭证等构建相关操作

安装

npm install --save-dev @lark-apaas/fullstack-cli

使用

1. 自动派生

每次运行 npm install 时，会自动派生文件到项目：

派生内容：

• scripts/ - Shell 脚本目录（总是覆盖）
• .gitignore - 追加 fullstack-cli 相关忽略规则

⚠️ scripts/ 目录由 CLI 自动管理，请勿手动修改！

2. 生成数据库 Schema

从现有数据库生成 Drizzle ORM schema：

npm run gen:db-schema

环境变量配置：

# 必需
SUDA_DATABASE_URL=postgresql://user:pass@host:port/dbname?schema=public

# 可选
DB_SCHEMA_OUTPUT=server/database/schema.ts  # 输出路径
DRIZZLE_SCHEMA_FILTER=public,custom         # Schema 过滤器
DRIZZLE_TABLES_FILTER=users,orders          # 表过滤器

工作流程：

• 从 SUDA_DATABASE_URL 读取数据库连接
• 使用 CLI 内置的 drizzle.config.ts（用户无需维护）
• 执行 drizzle-kit introspect
• 后处理 schema（通过 devtool-kits）
• 输出到 server/database/schema.ts

3. 生成 OpenAPI 文档

自动生成 OpenAPI 文档和客户端 SDK：

npm run gen:openapi

环境变量配置：

# 可选
APP_MODULE_PATH=server/app.module    # AppModule 路径（不含扩展名）
CLIENT_BASE_PATH=/                   # 客户端基础路径

工作流程：

• 动态导入用户项目的 AppModule
• 挂载 DevToolsModule
• 生成 OpenAPI 文档和客户端 SDK

4. Action 插件管理

管理 Action 插件的安装、更新、删除和查看：

# 安装插件（默认最新版）
fullstack-cli action-plugin install @office/feishu-create-group

# 安装指定版本
fullstack-cli action-plugin install @office/feishu-create-group@1.0.0

# 更新插件到最新版
fullstack-cli action-plugin update @office/feishu-create-group

# 删除插件
fullstack-cli action-plugin remove @office/feishu-create-group

# 查看已安装的插件列表
fullstack-cli action-plugin list

命令别名：

完整命令	别名
action-plugin install	action-plugin i
action-plugin update	action-plugin up
action-plugin remove	action-plugin rm
action-plugin list	action-plugin ls

插件存储：

• 插件文件：node_modules/<plugin-name>/（标准 npm 包位置）
• 配置文件：.capabilityrc.json（记录已安装的 action 插件元信息）

5. 能力配置管理

查看和管理项目中的能力配置：

# 列出所有能力（充血后，带 actions 信息）
fullstack-cli capability list

# 列出所有能力（原始配置，不充血）
fullstack-cli capability list --summary

# 获取指定能力配置
fullstack-cli capability list --id create_feishu_group_for_task

# 获取指定能力原始配置
fullstack-cli capability list --id create_feishu_group_for_task --summary

能力充血：

• 默认返回充血后的能力配置，包含从插件 manifest 读取的 actions 信息
• 支持动态 Schema：manifest 中标记 { dynamic: true } 的 schema 会运行时生成
• Schema 优先级：capability.paramsSchema > 动态 schema > 静态 schema
• 充血失败时返回原始配置 + _hydrateError 字段（不抛异常）
• --summary 返回原始配置（存储在 server/capabilities/*.json 中的内容）

6. 能力迁移

将老版本 capability 配置（capabilities.json）迁移到新版本（独立 JSON 文件）：

# 执行迁移
fullstack-cli capability migration

# 预览模式（不修改文件）
fullstack-cli capability migration --dry-run

# 跳过插件安装
fullstack-cli capability migration --skip-install

# 跳过代码迁移
fullstack-cli capability migration --skip-code

迁移步骤：

• JSON 文件迁移

  • 读取 server/capabilities.json（老格式：数组）
  • 转换为独立文件 server/capabilities/<id>.json（新格式）
  • 自动备份原文件为 capabilities.json.backup

• 插件安装

  • 根据 sourceActionID → pluginID 映射表查找对应插件
  • 自动调用 fullstack-cli action-plugin install 安装缺失的插件

• 代码迁移

  • 扫描 server/ 目录下的 TypeScript 文件
  • 移除 capability 直接导入 import xxx from '@/capabilities/xxx'
  • 添加 CapabilityService 依赖注入
  • 替换调用点为 capabilityService.load('xxx').call('run', params)

老格式 vs 新格式：

// 老格式 (capabilities.json)
{
  "id": "create_group",
  "sourceActionID": "feishu_group_create",  // 老字段
  "name": "创建群组",
  "desc": "创建飞书群组",                    // 老字段
  "actionInput": { ... },                    // 老字段
  "inputSchema": { ... }
}

// 新格式 (server/capabilities/create_group.json)
{
  "id": "create_group",
  "pluginID": "@official/feishu-group",      // 新字段
  "pluginVersion": "1.0.0",                  // 新字段
  "name": "创建群组",
  "description": "创建飞书群组",             // 重命名
  "formValue": { ... },                      // 重命名
  "paramsSchema": { ... }
}

映射文件格式：

{
  "feishu_group_create": "@official/feishu-group",
  "feishu_send_message": "@official/feishu-message"
}

7. 构建工具

获取构建流程所需的 STI 制品上传凭证：

# Pipeline 发布场景 - 需要 commit-id
fullstack-cli build get-token --app-id app_xxx --scene pipeline --commit-id abc123

# 静态资源部署场景
fullstack-cli build get-token --app-id app_xxx --scene static

参数说明：

参数	必填	说明
--app-id <id>	是	应用 ID
--scene <scene>	是	构建场景（pipeline、static）
--commit-id <id>	scene=pipeline 时必填	Git Commit ID

输出： stdout 输出 API 返回的完整 JSON，日志/错误输出到 stderr，便于脚本解析：

token_response=$(fullstack-cli build get-token --app-id "$APP_ID" --scene pipeline --commit-id "$COMMIT_ID")
credential=$(echo "$token_response" | jq -r '.data.accessKeyID')

环境变量：

• FORCE_AUTHN_INNERAPI_DOMAIN — API 域名
• FORCE_AUTHN_ACCESS_KEY — Access Key
• FORCE_AUTHN_ACCESS_SECRET — Secret Key
• FORCE_FRAMEWORK_CLI_CANARY_ENV — Canary 环境（可选）

8. CLI 命令

# 查看帮助
fullstack-cli --help

# 生成数据库 schema
fullstack-cli gen-db-schema

# 生成 OpenAPI
fullstack-cli gen-openapi

# Action 插件管理
fullstack-cli action-plugin --help
fullstack-cli action-plugin install <plugin>
fullstack-cli action-plugin list

# 能力配置管理
fullstack-cli capability --help
fullstack-cli capability list
fullstack-cli capability migration --dry-run

# 构建工具
fullstack-cli build --help
fullstack-cli build get-token --app-id <id> --scene <scene> [--commit-id <id>]

# 查看版本
fullstack-cli --version

9. 全局选项

Canary 环境

支持通过 --canary 选项指定 canary 环境，会在 HTTP 请求中添加 x-tt-env header：

# 通过命令行参数指定
fullstack-cli --canary boe_canary action-plugin install @office/feishu-create-group

# 也可以放在命令后面
fullstack-cli action-plugin install @office/feishu-create-group --canary boe_canary

也支持通过环境变量设置：

FORCE_FRAMEWORK_CLI_CANARY_ENV=boe_canary fullstack-cli action-plugin install @office/feishu-create-group

package.json 配置

在用户项目的 package.json 中添加：

{
  "scripts": {
    "gen:db-schema": "fullstack-cli gen-db-schema",
    "gen:openapi": "NODE_ENV=development DEPRECATED_SKIP_INIT_DB_CONNECTION=true fullstack-cli gen-openapi"
  },
  "devDependencies": {
    "@lark-apaas/fullstack-cli": "^0.1.0",
    "drizzle-kit": "^0.20.0"  // 如果使用数据库功能
  }
}

技术细节

派生配置

派生规则在 src/postinstall.config.ts 中定义：

export default {
  sync: [
    {
      from: 'templates/scripts',
      to: 'scripts',
      type: 'directory',
      overwrite: true,
    },
    {
      from: 'templates/.gitignore.append',
      to: '.gitignore',
      type: 'append',
    },
  ],
  permissions: {
    '**/*.sh': 0o755,
  },
};

Drizzle 配置

CLI 内置 templates/drizzle.config.ts，通过环境变量动态配置：

• 用户无需维护 drizzle.config.ts
• 所有配置通过环境变量传递
• 使用绝对路径指向用户项目

OpenAPI 生成

• 动态导入用户的 AppModule
• 使用 @lark-apaas/fullstack-nestjs-core 的 DevToolsModule
• 自动生成客户端 SDK

依赖关系

fullstack-cli
  ↓ 依赖
@lark-apaas/devtool-kits (核心逻辑)

用户项目 peerDependencies:
  - @nestjs/core (用于 gen-openapi)
  - @lark-apaas/fullstack-nestjs-core (用于 gen-openapi)
  - drizzle-kit (用于 gen-db-schema，可选)

升级说明

从旧版本迁移

可以删除的文件：

• ❌ scripts/gen-db-schema.ts - 已内置到 CLI
• ❌ scripts/gen-openapi.ts - 已内置到 CLI
• ❌ drizzle.config.ts - 已由 CLI 管理

更新 package.json：

{
  "scripts": {
-   "gen:db-schema": "ts-node scripts/gen-db-schema.ts",
+   "gen:db-schema": "fullstack-cli gen-db-schema",
-   "gen:openapi": "nest start --entryFile ../scripts/gen-openapi",
+   "gen:openapi": "fullstack-cli gen-openapi"
  }
}

Capability 迁移

如果项目使用老版本的 capability 系统（capabilities.json 文件），可以使用迁移命令自动升级：

# 1. 先预览迁移效果
fullstack-cli capability migration --dry-run

# 2. 确认无误后执行迁移
fullstack-cli capability migration

迁移会自动完成：

• JSON 配置文件格式转换
• 插件安装
• 代码调用方式更新（从直接导入改为 CapabilityService 注入）

License

MIT