inkreach-teable-cli/skills/inkreach-teable-plugin/SKILL.md

---
name: inkreach-teable-plugin
description: >-
  Develop dynamic React component plugins for inkreach-teable — IIFE bundles
  loaded at runtime via window.__TEABLE_HOST__, no iframe sandbox, full host
  API access. Scaffold with plugin-cli, build with webpack, deploy via
  upload-bundle API, register via definePlugin + PluginContext. Positions:
  contextMenu, panel, view, dashboard, route. Use this whenever the user
  mentions plugins, 插件, batch-edit, context-menu actions, panel widgets,
  dashboard charts, custom views, plugin.json, definePlugin, bundle plugin,
  plugin-cli, plugin-sdk, plugin-host, or window.__TEABLE_HOST__. Even if
  the user just says "add a right-click action" or "make a side panel" or
  "I need a dashboard widget" — or wants the native form embedded or
  extended inside a plugin (原生表单, 表单注入, 表单虚拟字段, custom form
  layout, NativeForm, NativeFormScope, form panel) — load this skill.
  Reference example at `plugins/batch-edit-pro/` (on the deployment host: `/root/deployments/inkreach-teable/plugins/batch-edit-pro/`).
---

# inkreach-teable dynamic plugin development

This skill develops React component plugins that load at runtime without
rebuilding the host Next.js app. Plugins are IIFE bundles — they ship as plain
JS that executes in the host page and accesses host APIs through
`window.__TEABLE_HOST__`.

> **Contract**: A plugin = a webpack IIFE bundle (`dist/main.js` + optional
> `dist/styles.css`) + `plugin.json` manifest, uploaded to the host via
> `POST /api/plugin/:id/upload-bundle`. It runs in the same React tree as the host
> and has full access to the host's SDK, UI library, and OpenAPI helpers.
>
> **Critical constraint**: no RUNTIME imports from `@teable/sdk`, `@teable/ui-lib`,
> `@teable/openapi` — webpack maps them to `window.__TEABLE_HOST__.*` externals, so a
> value import compiles to `undefined` at runtime. `import type { X } from '@teable/...'`
> IS fine (erased at compile time). `react`/`react-dom` may be imported ONLY when your
> webpack `externals` maps them to `window.__TEABLE_HOST__.React/ReactDOM` (see the
> batch-edit-pro webpack config). For everything else, read from the host global:
> `const { useFields } = window.__TEABLE_HOST__.SDK`. See
> `dynamic-plugins/troubleshooting.md` Pitfall 1 for details and symptoms.

## 0. Two efficiency rules (read first)

- **Trust these docs.** The `dynamic-plugins/` documents are the verified contract
  for this deployment. Answer plugin capability/behavior questions directly from
  them — do NOT re-derive behavior by spelunking `nestjs-backend/src` or the host
  source tree; that burns minutes and adds nothing. Source diving is only for
  debugging a concrete discrepancy the docs can't explain.
- **Don't upload demo plugins to verify knowledge.** For how-to/consultation
  questions, a written answer (with code) is the deliverable. Only upload a bundle
  when the user actually asked to deploy — test uploads belong in a throwaway
  sandbox base, never the production plugin registry.

## 1. When to use this skill

- User says "写个插件 / 做个插件 / make a plugin" — yes.
- User wants a context-menu action (batch edit / process selected records) — yes.
- User wants a panel gadget (real-time stats / summary) — yes.
- User wants a custom view (kanban, gallery, timeline) — yes.
- User wants a dashboard chart — yes.
- User wants to embed / extend the NATIVE FORM in a plugin (原生表单, form
  injection, virtual form fields, custom multi-step form with native field
  editors, `host.NativeForm`, `NativeFormScope`) — yes, see `sdk-api.md`.
- User mentions `definePlugin`, `plugin-cli`, `plugin-sdk`, `window.__TEABLE_HOST__`, bundle plugin — yes.
- User wants to manage tables/automations (not plugins) — use `inkreach-teable` skill instead.

## 2. Module map (read in order when developing)

| Stage | File | Read it when... |
|---|---|---|
| 1. Understand architecture | `dynamic-plugins/overview.md` | always first — how `window.__TEABLE_HOST__`, PluginLoader, PluginSlot work |
| 2. Dev workflow | `dynamic-plugins/dev-workflow.md` | when building a plugin — the step-by-step recipe from scaffold to deploy |
| 3. SDK API | `dynamic-plugins/sdk-api.md` | when writing plugin logic — definePlugin, PluginContext, events, storage, useSelection, native form embedding (`NativeForm` Tier-1 injection / `NativeFormScope`+`useNativeForm` Tier-2 kit), NativeGrid |
| 3b. Native form quick answer | `dynamic-plugins/native-form.md` | **when the user ASKS whether/how to embed native field editors, custom form layout, or multi-step forms — read this FIRST and answer directly (consultative questions need no scaffold/build)** |
| 4. Deployment | `dynamic-plugins/deployment.md` | when uploading + enabling + authority matrix permissions |
| 5. Troubleshooting | `dynamic-plugins/troubleshooting.md` | before writing logic — common pitfalls (host globals, developer whitelist, AM, empty states) |
| Ref: batch-edit-pro | `plugins/batch-edit-pro/` | the canonical example — contextMenu plugin, full React + SDK |

## 3. Quick decision: which position?

| User wants | Position | `definePlugin` registration |
|---|---|---|
| Right-click action on records | **ContextMenu** | `ctx.addContextMenuAction(id, component)` |
| Side gadget while viewing a table | **Panel** | `ctx.addPanel(id, component)` |
| A new view type | **View** | `ctx.addView(id, component)` |
| Card on the space dashboard | **Dashboard** | `ctx.addDashboardWidget(id, component)` |
| A new page/route | **Route** | `ctx.addRoute(path, component)` |

## 4. Auth & test credentials

- Endpoint: `http://localhost:3003` (backend; `:3000` is taken by an unrelated
  docker container on this host — see AGENTS.md), frontend `http://localhost:3002`.
- Plugin upload requires a `plugin_developer` row for the uploading user
  (`INSERT INTO plugin_developer (id, user_id, email, created_time, created_by)
  VALUES ('plgd<name>', '<userId>', '<email>', now(), '<userId>')`).
- **Sandbox base for any hands-on test**: create a throwaway base
  (`POST /api/base` with `{"spaceId":"<spaceId>","name":"Sandbox(可删)"}`),
  do all table/install testing inside it, and delete it (`DELETE /api/base/:id`)
  when done. Never hardcode base/table IDs here — they rot; resolve them at
  runtime (`inkreach-teable base list`) instead.
- Auth: PAT (`Authorization: Bearer <PAT>`; upload-bundle supports it) or
  session cookie `auth_session`. Note: some admin-gated routes (e.g.
  `DELETE /api/plugin/:id`) pass with an admin session but 403 with a plain PAT
  even for the same user — fall back to the session for those.

## 5. Start here

For any plugin request, read `dynamic-plugins/overview.md` then
`dynamic-plugins/dev-workflow.md`. Reference `plugins/batch-edit-pro/` for a
complete working example.

## 6. Plugin backend services — MUST use the same-origin proxy (2026-08-21)

The instance is publicly served at `https://table.inkreach.cc` (frp + cloud Caddy);
browsers on the public internet CANNOT reach LAN addresses like
`http://192.168.124.92:8001`. Plugin bundles that need their own backend service
MUST call it through the session-gated dynamic proxy instead:

- **URL contract**: `fetch('/api/plugin-proxy/<service>/<path...>')` — same-origin,
  works from LAN and public internet alike. NEVER hardcode LAN IPs / `localhost`
  in a bundle.
- **Registry**: one line in `PLUGIN_API_SERVICES` (JSON, in
  `apps/nextjs-app/.env` AND `.env.development`), then restart
  `teable-backend.service`. No rebuild, no code change.
  Example: `PLUGIN_API_SERVICES={"track":"http://127.0.0.1:8001"}`
- **Implementation**: NestJS controller
  `apps/nestjs-backend/src/features/plugin/plugin-proxy.controller.ts`
  (global AuthGuard gates login; upstream whitelist = registry; session cookies
  are never forwarded upstream). Do NOT move this to a Next.js pages-router API
  route — the `/api/:path*` rewrite in `next.config.js` outranks catch-all file
  routes, and files outside `pages/api/` get compiled as SSR pages (observed on
  Next 16.1.6/turbopack).
- **CSP**: same-origin fetches need nothing; truly external origins must be
  declared in the plugin manifest `apiOrigins` (appended to connect-src by
  `plugin-runtime.controller.ts`).
- Re-uploading a plugin zip OVERWRITES the bundle — re-check for hardcoded LAN
  URLs afterwards (`grep -o 'http://192.168[^\"']*' <bundle>/main.js`).
  Live example: `apps/nestjs-backend/.assets/plugins/bundle/track-panel/`
  (patched from LAN URL to `/api/plugin-proxy/track`; backups kept as
  `main.js.bak-*`).
- **Root fix (2026-08-22 recurrence)**: a developer re-uploaded track-panel at
  02:23 with the LAN URL back in the source-built bundle, breaking public
  search with a CORS error within hours of the last patch. Patching
  `main.js` on disk only fixes the CURRENT artifact — the plugin SOURCE must
  use `/api/plugin-proxy/track` before building/uploading, otherwise every
  re-upload reintroduces the bug. The backend serves bundle files from disk
  per-request, so a disk patch takes effect without a backend restart.