@xpert-ai/plugin-sdk 3.21.0 → 3.21.1

package/{README.md → docs/README.md}

@@ -2,7 +2,9 @@
 
 ## Runtime capabilities
 
-See [platform capabilities and scoped factories](./runtime-capabilities.md) for domain registration, execution-scoped APIs and usage outside Agent middleware.
+See [platform capabilities and scoped factories](./en/runtime-capabilities.md) for domain registration, execution-scoped APIs and usage outside Agent middleware.
+
+See [knowledgebase APIs](./en/KNOWLEDGEBASE_API.md) for resource discovery, readiness, permissions and migration from legacy listing.
 
 ## Building
 
@@ -14,11 +16,11 @@ Run `nx test plugin-sdk` to execute the unit tests via [Jest](https://jestjs.io)
 
 ## Schema config
 
-[Schema UI 扩展规范](./SCHEMA_SPECIFICATION.md)
+[Schema UI Extension Specification](./en/SCHEMA_SPECIFICATION.md)
 
 ## Permissions
 
-[插件权限设计指南](./PERMISSIONS.md)
+[Plugin Permission Design Guide](./en/PERMISSIONS.md)
 
 ## Decorator-driven business Tools
 
@@ -115,13 +117,13 @@ For completed operations, `prepareToolResult(() => project(result), () => minima
 
 For a host-native MCP App, declare each static HTML bundle once in the Provider's `apps` array, then bind a Tool with `mcp.app.resourceKey` and include `app` visibility. The App key must exist in the same Provider and its entry must be a relative `.html` path inside the packaged plugin. The host publishes the bundle as a `ui://` resource; plugins must not create a stdio server or put CSP/credentials in Tool results.
 
-Agent middleware can also expose these Apps without a published Toolset. See [middleware Apps and post-tool continuation](./MIDDLEWARE_APPS.md) for `app` bindings and `interruptAfter` checkpoints.
+Agent middleware can also expose these Apps without a published Toolset. See [middleware Apps and post-tool continuation](./en/MIDDLEWARE_APPS.md) for `app` bindings and `interruptAfter` checkpoints.
 
 The host owns the public MCP endpoint identity. It combines the plugin's stable `artifactNamespace`, the Provider key, and an opaque scope hash; client names and product-specific identifiers do not belong in the slug. A tenant- or system-level plugin has one tenant-scoped Publication and capability snapshot, while each organization receives an independent access grant and organization-bound credential. An organization-level plugin receives a dedicated organization-scoped Publication.
 
 ## View extensions
 
-[View Extension Protocol](./docs/view-extension-protocol.md)
+[View Extension Protocol](./en/view-extension-protocol.md)
 
 ## Browser collaboration client
 
@@ -159,7 +161,7 @@ containing these interfaces. They are not part of the published SDK 3.18.3 basel
 
 ## Conversation resource receipts
 
-See [RESOURCE-CARDS.md](./RESOURCE-CARDS.md) for the public protocol, tool/middleware emitter, transactional Project provider example, and coordinated release order.
+See [RESOURCE-CARDS.md](./en/RESOURCE-CARDS.md) for the public protocol, tool/middleware emitter, transactional Project provider example, and coordinated release order.
 
 ## Project task business types
 
@@ -175,7 +177,7 @@ export class ExampleTasks implements IProjectTaskProvider {
     {
       key: 'example.tasks.illustration',
       presentation: {
-        label: { en_US: 'Construction images', zh_Hans: '施工配图' },
+        label: { en_US: 'Construction images' },
         icon: 'Images'
       }
     }
@@ -210,4 +212,4 @@ Deploy matching contracts, SDK and host support before a plugin starts emitting
 
 ## Tool image references
 
-See [TOOL-IMAGES.md](./TOOL-IMAGES.md) for `ToolImagesRuntimeCapability`, reference-only tool results, temporary visual model inputs, execution scope, and recovery rules. Never persist the messages returned by `prepareModelInput`.
+See [TOOL-IMAGES.md](./en/TOOL-IMAGES.md) for `ToolImagesRuntimeCapability`, reference-only tool results, temporary visual model inputs, execution scope, and recovery rules. Never persist the messages returned by `prepareModelInput`.

package/docs/en/KNOWLEDGEBASE_API.md

@@ -0,0 +1,42 @@
+# Knowledgebase resource discovery
+
+`platform.knowledgebase` separates catalog discovery, metadata, permission inspection and content retrieval. All new catalog methods use the authenticated runtime's tenant, organization and actor. Inputs cannot select another identity or organization.
+
+| Method      | Responsibility                                                                                                               |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `query`     | Discover resources with explicit scope, metadata filters, required actions and cursor pagination.                            |
+| `get`       | Read one resource's safe metadata, supported ingestion capability, configuration and processing readiness.                   |
+| `getAccess` | Inspect named actions for up to 100 resource IDs. Missing and inaccessible IDs both return `unavailable`.                    |
+| `search`    | Retrieve indexed content; its existing contract is unchanged.                                                                |
+| `list`      | Deprecated for new integrations; preserves the old scope, shared-library behavior and array result. Use `query` in new code. |
+
+The draft-only `listWritable` method has been removed. Destination discovery uses `query` with required actions.
+
+Document lifecycle methods remain on `platform.knowledgebase.documents`; administrative provisioning remains on `platform.knowledgebase.provisioning`. Resource discovery does not create or connect libraries.
+
+## Discover a destination
+
+Feature-detect `query`, `get` and `getAccess` before using them on an older host. A workflow requiring write authorization must fail explicitly when these methods are absent; the old `list` is not an authorization substitute.
+
+```ts
+const actions: KnowledgebaseAction[] = ['documents.create', 'documents.process']
+const page = await api.query({
+  scope: { kind: 'workspace', workspaceId, relation: 'owned' },
+  filter: {
+    visibility: 'organization',
+    applicationTags: { allOf: [imageLibraryTag] }
+  },
+  access: { requireAll: actions },
+  page: { limit: 100, cursor }
+})
+```
+
+- `owned` restricts results to the selected workspace. `available` also considers organization/public resources in the current organization, subject to point-read authorization. It does not grant access to another workspace or include tenant libraries implicitly.
+- `organization` searches the current organization. `tenant` searches tenant-owned public libraries. No scope bypasses resource permissions.
+- Text filtering is a literal substring of name/description; `applicationTags.allOf` requires every tag. Publication and visibility are separate filters.
+- Page limits are 1–100 (default 20), with stable ascending ID keysets. Follow `nextCursor` even after a short or empty page; each request scans at most 1,000 rows. Only `null` confirms exhaustion.
+- Cursors are bound to tenant, organization, actor, scope, filters and required actions. Changing these requires restarting the query. Permissions are evaluated again on every page. Pagination is not a database snapshot; insertions before the current ID may appear only in a fresh query.
+
+Before starting paid work, inspect `getAccess` for every required action and `get` for readiness. `configuration.embeddingConfigured` means an embedding model binding exists, not that an external provider is currently healthy. Recheck access before saving, and retain normal authorization on actual document writes; an earlier check never authorizes a later write.
+
+Catalog responses expose neither provider credentials nor model bindings. Current document/chunk mutations use the platform's existing knowledgebase write policy; exposing distinct action names allows future permission refinement without adding action-specific list methods.

package/docs/en/PERMISSIONS.md

@@ -0,0 +1,173 @@
+# Plugin Permission Design Guide
+
+Declare model requirements in a strategy's `meta.permissions` and expose provider/model selection in `configSchema`. The host resolves the user's configuration and credentials, creates the appropriate model client, and injects it into `config.client` before calling `understandImages`.
+
+The following design illustrates how `OpenAIGPT4VStrategy` can request a host-provided client instead of constructing its own OpenAI, Anthropic or other vision-model client.
+
+## Strategy definition
+
+```ts
+import { Injectable } from '@nestjs/common'
+import { Document } from 'langchain/document'
+import {
+  ImageUnderstandingStrategy,
+  IImageUnderstandingStrategy,
+  TImageUnderstandingFile,
+  TImageUnderstandingResult
+} from './strategy.interface'
+
+@Injectable()
+@ImageUnderstandingStrategy('openai-gpt4v')
+export class OpenAIGPT4VStrategy implements IImageUnderstandingStrategy<any> {
+  readonly meta = {
+    name: 'openai-gpt4v',
+    label: { en: 'OpenAI GPT-4 Vision' },
+
+    /**
+     * Declare the plugin's requirement for "llm" access,
+     * with OpenAI as the provider and vision as the capability.
+     * The host uses config.provider and config.model to create the client
+     * and inject it into config.client.
+     */
+    permissions: [
+      {
+        type: 'llm',
+        provider: 'openai',
+        capability: 'vision'
+      }
+    ],
+
+    /**
+     * The configuration schema requires provider and model.
+     * The host uses these settings and the user's API key
+     * to create and inject the client.
+     */
+    configSchema: {
+      type: 'object',
+      properties: {
+        provider: {
+          type: 'string',
+          enum: ['openai'],
+          description: 'Model provider'
+        },
+        model: {
+          type: 'string',
+          default: 'gpt-4-vision-preview',
+          description: 'Model name'
+        },
+        prompt: {
+          type: 'string',
+          default: 'Describe this image in detail.',
+          description: 'Prompt for the image understanding task'
+        }
+      },
+      required: ['provider', 'model']
+    },
+
+    icon: {
+      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><circle cx="10" cy="10" r="8" stroke="black" fill="none"/><text x="6" y="14">VLM</text></svg>',
+      color: '#10a37f'
+    }
+  }
+
+  async validateConfig(config: any): Promise<void> {
+    if (!config.client) {
+      throw new Error('Missing injected LLM client in config. Core system must inject client.')
+    }
+  }
+
+  async understandImages(files: TImageUnderstandingFile[], config: any): Promise<TImageUnderstandingResult[]> {
+    const client = config.client // Injected by the host.
+    const results: TImageUnderstandingResult[] = []
+
+    for (const file of files) {
+      const description = await this.runGPT4V(client, file.path, config)
+
+      const doc = new Document({
+        pageContent: description,
+        metadata: {
+          chunkId: `img-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          parentChunkId: file.parentChunkId,
+          imagePath: file.path,
+          source: file.filename,
+          type: 'vlm',
+          engine: config.model
+        }
+      })
+
+      results.push({
+        docs: [doc],
+        metadata: { engine: config.model, file: file.filename }
+      })
+    }
+
+    return results
+  }
+
+  private async runGPT4V(client: any, imagePath: string, config: any): Promise<string> {
+    // The host has already created this OpenAI client.
+    const response = await client.chat.completions.create({
+      model: config.model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: config.prompt || 'Describe this image in detail.' },
+            { type: 'image_url', image_url: { url: imagePath } }
+          ]
+        }
+      ],
+      max_tokens: 500
+    })
+
+    return response.choices[0]?.message?.content || ''
+  }
+}
+```
+
+---
+
+## Host processing
+
+- Read the plugin's `meta.permissions` to identify the requirement:
+
+  ```json
+  { "type": "llm", "provider": "openai", "capability": "vision" }
+  ```
+
+- Use the user's `config.provider = "openai"` and `config.model = "gpt-4-vision-preview"`
+  to instantiate `OpenAI({ apiKey: userApiKey })`.
+- Inject the client into `config.client`.
+- Call `strategy.understandImages(files, config)`.
+
+---
+
+## Usage example
+
+```ts
+const strategy = this.imageUnderstandingRegistry.get('openai-gpt4v')
+const result = await strategy.understandImages(
+  [
+    {
+      path: 'https://example.com/chart.png',
+      filename: 'chart.png',
+      extname: 'png',
+      parentChunkId: 'uuid-123'
+    }
+  ],
+  {
+    provider: 'openai',
+    model: 'gpt-4-vision-preview',
+    prompt: 'Describe this image in detail in English.',
+    client: openaiClient // Injected by the host.
+  }
+)
+
+console.log(result[0].docs[0].pageContent)
+```
+
+---
+
+The plugin declares its permission requirements and provider/model configuration; the host supplies the appropriate client without requiring plugin-specific OpenAI initialization logic.
+
+A shared permission-request interface, such as `ILLMPermissionRequest`, can give OCR, vision-model and embedding plugins a common way to declare dependencies.

package/{RESOURCE-CARDS.md → docs/en/RESOURCE-CARDS.md}

@@ -205,15 +205,15 @@ For example, add this `content` property to the card passed to `emitResourceCard
 
 ```ts
 content: [
-  { kind: 'fields', fields: [{ label: '状态', value: '已完成' }] },
+  { kind: 'fields', fields: [{ label: 'Status', value: 'Completed' }] },
   {
     kind: 'image-gallery',
-    title: '施工配图',
+    title: 'Construction images',
     images: [
       {
         id: 'site-layout',
-        title: '施工现场平面布置图',
-        alt: '施工分区、出入口和运输路线',
+        title: 'Construction site layout',
+        alt: 'Work zones, entrances, exits and transport routes',
         file: {
           viewKey: 'bid.view-provider__bid.studio',
           fileKey: 'bid-project-image',
@@ -358,4 +358,4 @@ The built-in `platform.agent-invocation/execution` provider owns direct Coding i
 
 The card opens `platform.coding-execution__execution` with the exact invocation ID. Public CLI activity is written through the optional Runtime `context.activity` recorder and queried by the View provider. Resource-card refresh contains only presentation/state/target updates; it does not transport command output or invoke a CLI. Final summary cards are suppressed only when a Coding execution card already covers the run; independently delivered files retain their own cards.
 
-See [Coding Execution View](../server-ai/src/agent-invocation/execution-view/README.md) for the capability, authorization, storage, retention and navigation contract.
+See [Coding Execution View](../../../server-ai/src/agent-invocation/execution-view/README.md) for the capability, authorization, storage, retention and navigation contract.

package/docs/en/SCHEMA_SPECIFICATION.md

@@ -0,0 +1,325 @@
+# Schema UI Extension Specification
+
+Use a common UI extension across plugin configuration schemas so frontend renderers can apply consistent presentation and interaction rules.
+
+Extend JSON Schema with the reserved `x-ui` field:
+
+```json
+"x-ui": { ... }
+```
+
+The frontend renderer uses `x-ui` to select components, present fields and apply dynamic dependencies.
+
+---
+
+## 1. Basic fields
+
+| Field          | Type   | Description                                                                                                          |
+| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
+| `component`    | string | UI component type, such as `textInput`, `textarea`, `select`, `switch`, `slider`, `prompt-editor`, `ai-model-select` |
+| `inputs`       | object | Additional input properties for a custom component                                                                   |
+| `label`        | string | Displayed field label                                                                                                |
+| `description`  | string | Help text; takes precedence over `schema.description`                                                                |
+| `help`         | string | Additional help, displayed as a help icon or tooltip when appropriate                                                |
+| `placeholder`  | string | Input placeholder                                                                                                    |
+| `defaultValue` | any    | Default value; takes precedence over `schema.default`                                                                |
+| `order`        | number | Display order in the UI                                                                                              |
+
+---
+
+## 2. Data sources
+
+| Field        | Type   | Description                                                                                                                |
+| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `options`    | array  | Static options for selects or multi-selects, such as `[{ label: 'OpenAI', value: 'openai' }]`                              |
+| `enumLabels` | object | Map enum values to labels, for example `{ openai: 'OpenAI', azure: 'Azure OpenAI' }`, overriding the displayed enum labels |
+| `dataSource` | string | Dynamic option source identifier, such as `"system.providers"`, `"system.models"`                                          |
+| `dependency` | string | Another field whose value filters the options, such as `"provider"`                                                        |
+| `mapping`    | object | Field mapping, for example `{ label: 'name', value: 'id' }`                                                                |
+
+---
+
+## 3. Validation and interaction
+
+| Field         | Type    | Description                                                                        |
+| ------------- | ------- | ---------------------------------------------------------------------------------- |
+| `required`    | boolean | Whether the field is required; takes precedence over `schema.required`             |
+| `visibleWhen` | object  | Display the field only when conditions match, for example `{ provider: 'openai' }` |
+| `enabledWhen` | object  | Enable the field when conditions match, for example `{ useCustomPrompt: true }`    |
+| `maxLength`   | number  | Maximum input length                                                               |
+| `minLength`   | number  | Minimum input length                                                               |
+| `regex`       | string  | Custom regular-expression validation rule                                          |
+
+---
+
+## 4. Specialized components
+
+### `modelProviderSelect`
+
+- Select a model provider, such as OpenAI, Anthropic, Azure or Ollama.
+- `dataSource = "system.providers"`
+
+### `modelSelect`
+
+- Select a specific model.
+- Depends on `provider`.
+- `dataSource = "system.models"`
+- `dependency = "provider"`
+
+### `promptEditor`
+
+- Edit prompts with multiline input, syntax highlighting and variable interpolation.
+
+### `jsonEditor`
+
+- Edit JSON objects with format validation.
+
+### `codeEditor`
+
+- Edit code with syntax highlighting, such as JavaScript, TypeScript or Python.
+
+---
+
+## 5. Example schema
+
+```ts
+configSchema: {
+  type: 'object',
+  properties: {
+    provider: {
+      type: 'string',
+      description: 'Model provider',
+      enum: ['openai', 'anthropic', 'azure', 'ollama'],
+      'x-ui': {
+        component: 'modelProviderSelect',
+        label: 'Provider',
+        order: 1,
+        dataSource: 'system.providers'
+      }
+    },
+    model: {
+      type: 'string',
+      description: 'Model name',
+      default: 'gpt-4-vision-preview',
+      'x-ui': {
+        component: 'modelSelect',
+        label: 'Model',
+        order: 2,
+        dependency: 'provider',
+        dataSource: 'system.models'
+      }
+    },
+    prompt: {
+      type: 'string',
+      default: 'Describe this image in detail.',
+      description: 'Prompt',
+      'x-ui': {
+        component: 'promptEditor',
+        label: 'Prompt',
+        order: 3,
+        placeholder: 'Enter a prompt; {{variables}} placeholders are supported'
+      }
+    },
+    temperature: {
+      type: 'number',
+      default: 0.7,
+      'x-ui': {
+        component: 'slider',
+        label: 'Temperature',
+        order: 4,
+        min: 0,
+        max: 1,
+        step: 0.1
+      }
+    },
+    advanced: {
+      type: 'object',
+      'x-ui': {
+        component: 'jsonEditor',
+        label: 'Advanced Config',
+        order: 5,
+        visibleWhen: { provider: 'openai' }
+      }
+    }
+  },
+  required: ['provider', 'model']
+}
+```
+
+---
+
+With these conventions:
+
+- Renderers select the component from `x-ui.component`; the remaining `x-ui` properties drive its behavior.
+- Plugin developers declare a schema to obtain a consistent configuration experience.
+- The same conventions can support embedding, OCR, vision-model and vector-store plugins.
+
+## Representing secret input fields
+
+Secret fields, such as API keys, tokens and passwords, need explicit UI handling:
+
+1. Render a password input (`type="password"`) or masked value.
+2. Represent a stored secret with `"******"` or an empty placeholder instead of returning its plaintext value.
+3. Mark secret fields in the schema so renderers can recognize them.
+
+---
+
+## Secret-field extension
+
+Set `component: "secretInput"` in `x-ui` and support these properties:
+
+| Field         | Type    | Description                                                                       |
+| ------------- | ------- | --------------------------------------------------------------------------------- |
+| `component`   | string  | Set to `"secretInput"` to render a password input                                 |
+| `label`       | string  | Field label                                                                       |
+| `description` | string  | Field description                                                                 |
+| `placeholder` | string  | Placeholder, such as `Enter API key`                                              |
+| `revealable`  | boolean | Whether a button may temporarily reveal the value                                 |
+| `maskSymbol`  | string  | Mask character (default: `*`)                                                     |
+| `persist`     | boolean | Whether to persist the value; false means runtime-only use without saving to disk |
+
+---
+
+## Example schema
+
+```ts
+configSchema: {
+  type: 'object',
+  properties: {
+    apiKey: {
+      type: 'string',
+      description: 'OpenAI API Key',
+      'x-ui': {
+        component: 'secretInput',
+        label: 'API Key',
+        placeholder: 'Enter your OpenAI API key',
+        revealable: true,
+        maskSymbol: '*',
+        persist: true
+      }
+    },
+    provider: {
+      type: 'string',
+      enum: ['openai', 'anthropic', 'azure'],
+      'x-ui': {
+        component: 'modelProviderSelect',
+        label: 'Provider'
+      }
+    }
+  },
+  required: ['apiKey', 'provider']
+}
+```
+
+---
+
+## Frontend presentation
+
+- Render `apiKey` as a password input, masked by default.
+- When `revealable: true`, provide a reveal/hide toggle.
+- During editing, `"******"` indicates an existing value. Leaving it unchanged preserves that value.
+
+---
+
+## Secret handling
+
+- When the form submits `apiKey === "******"`, preserve the stored value.
+- Replace the stored value when a new value is submitted.
+- Omit secret fields from logs and configuration exports.
+
+---
+
+A shared interface such as `ISchemaSecretField` makes secret-specific behavior explicit.
+
+## Shared interface
+
+Secret fields share the base UI contract while declaring the additional handling required for sensitive values.
+
+---
+
+### Interface design
+
+```ts
+/**
+ * Base UI schema field definition
+ */
+export interface ISchemaUIBase {
+  component: string // UI component type
+  label?: string // Field label
+  description?: string // Field description
+  placeholder?: string // Input placeholder
+  order?: number // UI display order
+  required?: boolean // Whether the field is required
+  visibleWhen?: Record<string, any> // Conditional visibility
+  enabledWhen?: Record<string, any> // Conditional enablement
+}
+
+/**
+ * Secret field extension
+ */
+export interface ISchemaSecretField extends ISchemaUIBase {
+  component: 'secretInput' // Fixed component type
+  revealable?: boolean // Whether the reveal button is available
+  maskSymbol?: string // Mask character (default: *)
+  persist?: boolean // Whether to persist; false means runtime-only use
+}
+```
+
+Secret fields inherit the same base contract as ordinary fields, with additional properties for handling sensitive data.
+
+---
+
+### Usage example
+
+```ts
+configSchema: {
+  type: 'object',
+  properties: {
+    apiKey: {
+      type: 'string',
+      description: 'OpenAI API Key',
+      'x-ui': <ISchemaSecretField>{
+        component: 'secretInput',
+        label: 'API Key',
+        placeholder: 'Enter your OpenAI API key',
+        revealable: true,
+        maskSymbol: '*',
+        persist: true
+      }
+    },
+    provider: {
+      type: 'string',
+      enum: ['openai', 'anthropic', 'azure'],
+      'x-ui': {
+        component: 'modelProviderSelect',
+        label: 'Provider'
+      }
+    }
+  },
+  required: ['apiKey', 'provider']
+}
+```
+
+---
+
+### Frontend behavior
+
+1. **Rendering:**
+   - Render `secretInput` as a password field (`type=password`).
+   - Add a reveal toggle when `revealable: true`.
+
+2. **Loading configuration:**
+   - Treat `******` as an existing stored value without displaying the original content.
+
+3. **Saving configuration:**
+   - Preserve the stored value when the submitted value remains `******`.
+   - Replace the stored value when a new value is submitted.
+
+4. **Exporting configuration or logs:**
+   - Omit secret fields or output `******` to avoid disclosure.
+
+---
+
+This makes `secretInput` a first-class, schema-driven UI component alongside `textInput` and `select`.
+
+An `ISchemaUIComponent` union can describe the complete set of supported components, including selects, sliders, secret inputs and prompt editors.

package/{TOOL-IMAGES.md → docs/en/TOOL-IMAGES.md}

@@ -1,7 +1,7 @@
 # Tool images with immutable references
 
 For the API responsibilities, image lifecycle, validation limits and server-only
-text-result policy, see the [tool images feature guide](../../docs/tool-images.md).
+text-result policy, see the [tool images feature guide](../../../../docs/tool-images.md).
 
 Use `ToolImagesRuntimeCapability` inside an Agent middleware when a tool returns
 an image for visual inspection. The host stores validated image bytes in