Plugin Example: Lark Docs

​

Background

• System Integration: Connect Lark app credentials such as AppID and AppSecret for authentication.
• Document Loading: Retrieve document content from Lark folders or document APIs.
• Knowledge Management: Convert documents into structured content usable by Xpert AI’s knowledge base and agents.
• Extension Strategies: Implement extension points for integration, document sources, and document transformation via strategy interfaces.

​

1. Clone the Plugin Template

git clone [email protected]:xpert-ai/xpert-plugins-starter.git lark
cd lark

npm install

npx nx g @nx/js:lib packages/lark \
  --publishable \
  --importPath=@xpert-ai/plugin-lark \
  --bundler=tsc \
  --unitTestRunner=jest \
  --linter=eslint

npx nx show project @xpert-ai/plugin-lark

✅ This generates a plugin named @xpert-ai/plugin-lark that will handle all Lark Docs integration features.

​

2. Plugin Entry Code

import { z } from 'zod';
import { type XpertPlugin } from '@xpert-ai/plugin-sdk';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { initI18n } from './lib/i18n.js';
import { LarkModule } from './lib/lark.module.js';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const ConfigSchema = z.object({});

const plugin: XpertPlugin<z.infer<typeof ConfigSchema>> = {
  meta: {
    name: '@xpert-ai/plugin-lark',
    version: '1.0.0',
    category: 'doc-source',
    displayName: 'Lark Plugin',
    description: 'Integrate Lark functionality',
    keywords: ['lark', 'feishu', 'document source'],
    author: 'Xpert AI team',
  },
  config: {
    schema: ConfigSchema,
  },
  register(ctx) {
    ctx.logger.log('register lark plugin');
    initI18n(join(__dirname, '../src'));
    return { module: LarkModule, global: true };
  },
  async onStart(ctx) {
    ctx.logger.log('lark plugin started');
  },
  async onStop(ctx) {
    ctx.logger.log('lark plugin stopped');
  },
};

export default plugin;

​

Key Points

1. meta: Defines basic plugin info (name, version, category, keywords, etc.).
2. config: Describes the plugin config schema, allowing users to input config in the UI (reserved for future use).
3. register: Registers LarkModule, mounting the plugin to the NestJS module system.
4. onStart/onStop: Plugin lifecycle callbacks.

​

3. NestJS Module Structure

import chalk from 'chalk';
import { XpertServerPlugin, IOnPluginBootstrap, IOnPluginDestroy } from '@xpert-ai/plugin-sdk';
import { LarkIntegrationStrategy } from './integration.strategy.js';
import { LarkController } from './lark.controller.js';
import { LarkSourceStrategy } from './source.strategy.js';
import { LarkDocTransformerStrategy } from './transformer.strategy.js';

@XpertServerPlugin({
  controllers: [LarkController],
  providers: [
    LarkIntegrationStrategy,
    LarkSourceStrategy,
    LarkDocTransformerStrategy
  ]
})
export class LarkModule implements IOnPluginBootstrap, IOnPluginDestroy {
  onPluginBootstrap(): void {
    console.log(chalk.green(`${LarkModule.name} is being bootstrapped...`));
  }
  onPluginDestroy(): void {
    console.log(chalk.green(`${LarkModule.name} is being destroyed...`));
  }
}

✅ The Strategy classes are extension points, for example:

• LarkIntegrationStrategy: Handles integration with the Lark system.
• LarkSourceStrategy: Defines how to load documents from Lark.
• LarkDocTransformerStrategy: Defines how to transform documents into a format usable by the knowledge base.

​

4. API Interfaces

@Post('test')
async connect(@Body() integration: IIntegration) {
  try {
    const botInfo = await this.integrationStrategy.validateConfig(integration.options)
    return integration
  } catch (err) {
    throw new ForbiddenException('Credentials failed')
  }
}

​

5. Plugin Extension Points

​

5.1 System Integration Extension

async validateConfig(config: TLarkIntegrationConfig) {
  if (!config.appId || !config.appSecret) {
    throw new Error('App ID and Secret required')
  }
  const larkClient = new LarkClient({ options: config } as IIntegration)
  const botInfo = await larkClient.getBotInfo()
  if (!botInfo) throw new ForbiddenException('Bot permission denied')
  return botInfo
}

✅ Here, LarkClient wraps Lark OpenAPI requests.

​

5.2 Document Source Extension

• Config params: folder token, document type (docx/sheet/file, etc.).
• Loading logic: Calls client.listDriveFiles(folderToken), returns Document[].

​

5.3 Document Transformation Extension

• Calls Lark API to get document body.
• Splits body into Document objects (for vectorization).
• Outputs in IKnowledgeDocument format.

​

5.4 Client Wrapper

• getBotInfo() Get bot info
• listDriveFiles(folderToken) List folder contents
• getDocumentContent(docToken) Get document body
• getAllDocsInFolder(folderToken) Recursively get all documents

​

6. Development Workflow Summary

1. Prepare template: Clone the plugin template and generate the project.
2. Write entry code: Define plugin meta, config, and lifecycle.
3. Build module: Register controllers and strategy classes in LarkModule.
4. Implement strategies:
   • Integration strategy: Handle AppID/Secret validation.
   • Source strategy: Fetch documents from Lark.
   • Transformation strategy: Convert documents to knowledge base content.
5. Wrap client: Manage Lark API calls in a unified way.
6. Test API: Use /lark/test to verify integration.

​

7. Build, Release, and npm Publish Workflow

​

7.1 Build the Plugin

npx nx build @xpert-ai/plugin-lark

• This uses Nx’s builder (TypeScript compiler tsc by default) to compile source code to JavaScript.
• Build output goes to:
  Copy

  packages/lark/dist
  
• The output directory contains the publishable artifacts (index.js, type declarations .d.ts, etc.).

​

7.2 Version Management

​

Auto bump version

npx nx release patch @xpert-ai/plugin-lark

• patch: Patch version (e.g. 1.0.0 → 1.0.1)
• minor: Minor version (e.g. 1.0.0 → 1.1.0)
• major: Major version (e.g. 1.0.0 → 2.0.0)

1. Update the version in package.json.
2. Update CHANGELOG.md.
3. Generate the corresponding Git tag.

If not using nx release, you can manually edit the version field in package.json.

​

7.3 Publish to npm

npx nx run @xpert-ai/plugin-lark:nx-release-publish --access public --otp=<one-time-password-if-needed>

• --access public Specifies the package as public (suitable for packages under the @xpert-ai npm scope).
• --otp=<code> If your npm account has 2FA enabled, enter a one-time password (OTP).

⚠️ Before publishing, make sure the following fields in package.json are correct:

• main: Points to the build output entry, e.g. "dist/index.js"
• types: Points to type declarations, e.g. "dist/index.d.ts"
• files: Only includes files to be published (e.g. "dist/**/*")
• publishConfig: Can define default publish access (e.g. "access": "public")

​

7.4 Final Workflow Example

# 1. Build the plugin
npx nx build @xpert-ai/plugin-lark

# 2. Auto bump version (patch)
npx nx release patch @xpert-ai/plugin-lark

# 3. Publish to npm
npx nx run @xpert-ai/plugin-lark:nx-release-publish --access public --otp=<one-time-password-if-needed>

​

8. Final Usage

• Configure Lark AppID/AppSecret
• Select document folders and types
• Automatically load Lark Docs content
• Convert documents into knowledge base entries, supporting AI conversations and agent analysis